Improve flag help consistency, and update docs

This adds the `--live-restore` option to the documentation.

Also synched usage description in the documentation
with the actual description, and re-phrased some
flag descriptions to be a bit more consistent.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

cmd/dockerd/docker.go

@@ -31,7 +31,7 @@ func main() {
 	flag.Merge(flag.CommandLine, daemonCli.commonFlags.FlagSet)
 
 	flag.Usage = func() {
-		fmt.Fprint(stdout, "Usage: dockerd [ --help | -v | --version ]\n\n")
+		fmt.Fprint(stdout, "Usage: dockerd [OPTIONS]\n\n")
 		fmt.Fprint(stdout, "A self-sufficient runtime for containers.\n\nOptions:\n")
 
 		flag.CommandLine.SetOutput(stdout)

contrib/completion/zsh/_docker

@@ -1551,13 +1551,13 @@ __docker_subcommand() {
                 "($help)--default-gateway[Container default gateway IPv4 address]:IPv4 address: " \
                 "($help)--default-gateway-v6[Container default gateway IPv6 address]:IPv6 address: " \
                 "($help)--cluster-store=[URL of the distributed storage backend]:Cluster Store:->cluster-store" \
-                "($help)--cluster-advertise=[Address of the daemon instance to advertise]:Instance to advertise (host\:port): " \
-                "($help)*--cluster-store-opt=[Cluster options]:Cluster options:->cluster-store-options" \
+                "($help)--cluster-advertise=[Address or interface name to advertise]:Instance to advertise (host\:port): " \
+                "($help)*--cluster-store-opt=[Cluster store options]:Cluster options:->cluster-store-options" \
                 "($help)*--dns=[DNS server to use]:DNS: " \
                 "($help)*--dns-search=[DNS search domains to use]:DNS search: " \
                 "($help)*--dns-opt=[DNS options to use]:DNS option: " \
-                "($help)*--default-ulimit=[Default ulimit settings for containers]:ulimit: " \
-                "($help)--disable-legacy-registry[Do not contact legacy registries]" \
+                "($help)*--default-ulimit=[Default ulimits for containers]:ulimit: " \
+                "($help)--disable-legacy-registry[Disable contacting legacy registries]" \
                 "($help)*--exec-opt=[Runtime execution options]:runtime execution options: " \
                 "($help)--exec-root=[Root directory for execution state files]:path:_directories" \
                 "($help)--fixed-cidr=[IPv4 subnet for fixed IPs]:IPv4 subnet: " \
@@ -1576,7 +1576,7 @@ __docker_subcommand() {
                 "($help)*--label=[Key=value labels]:label: " \
                 "($help)--live-restore[Enable live restore of docker when containers are still running]" \
                 "($help)--log-driver=[Default driver for container logs]:Logging driver:(awslogs etwlogs fluentd gcplogs gelf journald json-file none splunk syslog)" \
-                "($help)*--log-opt=[Log driver specific options]:log driver options:__docker_log_options" \
+                "($help)*--log-opt=[Default log driver options for containers]:log driver options:__docker_log_options" \
                 "($help)--max-concurrent-downloads[Set the max concurrent downloads for each pull]" \
                 "($help)--max-concurrent-uploads[Set the max concurrent uploads for each push]" \
                 "($help)--mtu=[Network MTU]:mtu:(0 576 1420 1500 9000)" \
@@ -1896,7 +1896,7 @@ __docker_subcommand() {
                 "($help)--runtime=[Name of the runtime to be used for that container]:runtime:__docker_complete_runtimes" \
                 "($help)--sig-proxy[Proxy all received signals to the process (non-TTY mode only)]" \
                 "($help)--stop-signal=[Signal to kill a container]:signal:_signals" \
-                "($help)--storage-opt=[Set storage driver options per container]:storage options:->storage-opt" \
+                "($help)--storage-opt=[Storage driver options for the container]:storage options:->storage-opt" \
                 "($help -): :__docker_images" \
                 "($help -):command: _command_names -e" \
                 "($help -)*::arguments: _normal" && ret=0

daemon/config.go

@@ -144,9 +144,9 @@ func (config *Config) InstallCommonFlags(cmd *flag.FlagSet, usageFn func(string)
 
 	config.ServiceOptions.InstallCliFlags(cmd, usageFn)
 
-	cmd.Var(opts.NewNamedListOptsRef("storage-opts", &config.GraphOptions, nil), []string{"-storage-opt"}, usageFn("Set storage driver options"))
-	cmd.Var(opts.NewNamedListOptsRef("authorization-plugins", &config.AuthorizationPlugins, nil), []string{"-authorization-plugin"}, usageFn("List authorization plugins in order from first evaluator to last"))
-	cmd.Var(opts.NewNamedListOptsRef("exec-opts", &config.ExecOptions, nil), []string{"-exec-opt"}, usageFn("Set runtime execution options"))
+	cmd.Var(opts.NewNamedListOptsRef("storage-opts", &config.GraphOptions, nil), []string{"-storage-opt"}, usageFn("Storage driver options"))
+	cmd.Var(opts.NewNamedListOptsRef("authorization-plugins", &config.AuthorizationPlugins, nil), []string{"-authorization-plugin"}, usageFn("Authorization plugins to load"))
+	cmd.Var(opts.NewNamedListOptsRef("exec-opts", &config.ExecOptions, nil), []string{"-exec-opt"}, usageFn("Runtime execution options"))
 	cmd.StringVar(&config.Pidfile, []string{"p", "-pidfile"}, defaultPidFile, usageFn("Path to use for daemon PID file"))
 	cmd.StringVar(&config.Root, []string{"g", "-graph"}, defaultGraph, usageFn("Root of the Docker runtime"))
 	cmd.BoolVar(&config.AutoRestart, []string{"#r", "#-restart"}, true, usageFn("--restart on the daemon has been deprecated in favor of --restart policies on docker run"))
@@ -159,9 +159,9 @@ func (config *Config) InstallCommonFlags(cmd *flag.FlagSet, usageFn func(string)
 	cmd.Var(opts.NewListOptsRef(&config.DNSSearch, opts.ValidateDNSSearch), []string{"-dns-search"}, usageFn("DNS search domains to use"))
 	cmd.Var(opts.NewNamedListOptsRef("labels", &config.Labels, opts.ValidateLabel), []string{"-label"}, usageFn("Set key=value labels to the daemon"))
 	cmd.StringVar(&config.LogConfig.Type, []string{"-log-driver"}, "json-file", usageFn("Default driver for container logs"))
-	cmd.Var(opts.NewNamedMapOpts("log-opts", config.LogConfig.Config, nil), []string{"-log-opt"}, usageFn("Set log driver options"))
+	cmd.Var(opts.NewNamedMapOpts("log-opts", config.LogConfig.Config, nil), []string{"-log-opt"}, usageFn("Default log driver options for containers"))
 	cmd.StringVar(&config.ClusterAdvertise, []string{"-cluster-advertise"}, "", usageFn("Address or interface name to advertise"))
-	cmd.StringVar(&config.ClusterStore, []string{"-cluster-store"}, "", usageFn("Set the cluster store"))
+	cmd.StringVar(&config.ClusterStore, []string{"-cluster-store"}, "", usageFn("URL of the distributed storage backend"))
 	cmd.Var(opts.NewNamedMapOpts("cluster-store-opts", config.ClusterOpts, nil), []string{"-cluster-store-opt"}, usageFn("Set cluster store options"))
 	cmd.StringVar(&config.CorsHeaders, []string{"-api-cors-header"}, "", usageFn("Set CORS headers in the remote API"))
 	cmd.IntVar(&maxConcurrentDownloads, []string{"-max-concurrent-downloads"}, defaultMaxConcurrentDownloads, usageFn("Set the max concurrent downloads for each pull"))

daemon/config_unix.go

@@ -68,7 +68,7 @@ func (config *Config) InstallFlags(cmd *flag.FlagSet, usageFn func(string) strin
 	cmd.BoolVar(&config.EnableSelinuxSupport, []string{"-selinux-enabled"}, false, usageFn("Enable selinux support"))
 	cmd.StringVar(&config.SocketGroup, []string{"G", "-group"}, "docker", usageFn("Group for the unix socket"))
 	config.Ulimits = make(map[string]*units.Ulimit)
-	cmd.Var(runconfigopts.NewUlimitOpt(&config.Ulimits), []string{"-default-ulimit"}, usageFn("Set default ulimits for containers"))
+	cmd.Var(runconfigopts.NewUlimitOpt(&config.Ulimits), []string{"-default-ulimit"}, usageFn("Default ulimits for containers"))
 	cmd.BoolVar(&config.bridgeConfig.EnableIPTables, []string{"#iptables", "-iptables"}, true, usageFn("Enable addition of iptables rules"))
 	cmd.BoolVar(&config.bridgeConfig.EnableIPForward, []string{"#ip-forward", "-ip-forward"}, true, usageFn("Enable net.ipv4.ip_forward"))
 	cmd.BoolVar(&config.bridgeConfig.EnableIPMasq, []string{"-ip-masq"}, true, usageFn("Enable IP masquerading"))
@@ -90,7 +90,7 @@ func (config *Config) InstallFlags(cmd *flag.FlagSet, usageFn func(string) strin
 	cmd.BoolVar(&config.LiveRestore, []string{"-live-restore"}, false, usageFn("Enable live restore of docker when containers are still running"))
 	config.Runtimes = make(map[string]types.Runtime)
 	cmd.Var(runconfigopts.NewNamedRuntimeOpt("runtimes", &config.Runtimes, stockRuntimeName), []string{"-add-runtime"}, usageFn("Register an additional OCI compatible runtime"))
-	cmd.StringVar(&config.DefaultRuntime, []string{"-default-runtime"}, stockRuntimeName, usageFn("Default OCI runtime to be used"))
+	cmd.StringVar(&config.DefaultRuntime, []string{"-default-runtime"}, stockRuntimeName, usageFn("Default OCI runtime for containers"))
 	cmd.IntVar(&config.OOMScoreAdjust, []string{"-oom-score-adjust"}, -500, usageFn("Set the oom_score_adj for the daemon"))
 
 	config.attachExperimentalFlags(cmd, usageFn)

docs/reference/commandline/create.md

@@ -64,7 +64,7 @@ Options:
       --label-file value            Read in a line delimited file of labels (default [])
       --link value                  Add link to another container (default [])
       --link-local-ip value         Container IPv4/IPv6 link-local addresses (default [])
-      --log-driver string           Logging driver for container
+      --log-driver string           Logging driver for the container
       --log-opt value               Log driver options (default [])
       --mac-address string          Container MAC address (e.g. 92:d0:c6:0a:29:33)
   -m, --memory string               Memory limit
@@ -97,7 +97,7 @@ Options:
                                     Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
                                     or `g` (gigabytes). If you omit the unit, the system uses bytes.
       --stop-signal string          Signal to stop a container, SIGTERM by default (default "SIGTERM")
-      --storage-opt value           Set storage driver options per container (default [])
+      --storage-opt value           Storage driver options for the container (default [])
       --sysctl value                Sysctl options (default map[])
       --tmpfs value                 Mount a tmpfs directory (default [])
   -t, --tty                         Allocate a pseudo-TTY

docs/reference/commandline/dockerd.md

@@ -12,35 +12,45 @@ weight = -1
 
 # daemon
 
+```markdown
     Usage: dockerd [OPTIONS]
 
-    A self-sufficient runtime for linux containers.
+    A self-sufficient runtime for containers.
 
     Options:
+
+Usage: dockerd [OPTIONS]
+
+A self-sufficient runtime for containers.
+
+Options:
+
       --add-runtime=[]                       Register an additional OCI compatible runtime
-      --api-cors-header=""                   Set CORS headers in the remote API
-      --authorization-plugin=[]              Set authorization plugins to load
-      -b, --bridge=""                        Attach containers to a network bridge
-      --bip=""                               Specify network bridge IP
-      --cgroup-parent=                       Set parent cgroup for all containers
-      --cluster-store=""                     URL of the distributed storage backend
-      --cluster-advertise=""                 Address of the daemon instance on the cluster
-      --cluster-store-opt=map[]              Set cluster options
+      --api-cors-header                      Set CORS headers in the remote API
+      --authorization-plugin=[]              Authorization plugins to load
+      -b, --bridge                           Attach containers to a network bridge
+      --bip                                  Specify network bridge IP
+      --cgroup-parent                        Set parent cgroup for all containers
+      --cluster-advertise                    Address or interface name to advertise
+      --cluster-store                        URL of the distributed storage backend
+      --cluster-store-opt=map[]              Set cluster store options
       --config-file=/etc/docker/daemon.json  Daemon configuration file
       --containerd                           Path to containerd socket
       -D, --debug                            Enable debug mode
-      --default-gateway=""                   Container default gateway IPv4 address
-      --default-gateway-v6=""                Container default gateway IPv6 address
+      --default-gateway                      Container default gateway IPv4 address
+      --default-gateway-v6                   Container default gateway IPv6 address
+      --default-runtime=runc                 Default OCI runtime for containers
+      --default-ulimit=[]                    Default ulimits for containers
+      --disable-legacy-registry              Disable contacting legacy registries
       --dns=[]                               DNS server to use
       --dns-opt=[]                           DNS options to use
       --dns-search=[]                        DNS search domains to use
-      --default-ulimit=[]                    Set default ulimit settings for containers
-      --exec-opt=[]                          Set runtime execution options
-      --exec-root="/var/run/docker"          Root directory for execution state files
-      --fixed-cidr=""                        IPv4 subnet for fixed IPs
-      --fixed-cidr-v6=""                     IPv6 subnet for fixed IPs
-      -G, --group="docker"                   Group for the unix socket
-      -g, --graph="/var/lib/docker"          Root of the Docker runtime
+      --exec-opt=[]                          Runtime execution options
+      --exec-root=/var/run/docker            Root directory for execution state files
+      --fixed-cidr                           IPv4 subnet for fixed IPs
+      --fixed-cidr-v6                        IPv6 subnet for fixed IPs
+      -G, --group=docker                     Group for the unix socket
+      -g, --graph=/var/lib/docker            Root of the Docker runtime
       -H, --host=[]                          Daemon socket(s) to connect to
       --help                                 Print usage
       --icc=true                             Enable inter-container communication
@@ -50,28 +60,30 @@ weight = -1
       --ip-masq=true                         Enable IP masquerading
       --iptables=true                        Enable addition of iptables rules
       --ipv6                                 Enable IPv6 networking
-      -l, --log-level="info"                 Set the logging level
+      -l, --log-level=info                   Set the logging level
       --label=[]                             Set key=value labels to the daemon
-      --log-driver="json-file"               Default driver for container logs
-      --log-opt=[]                           Log driver specific options
+      --live-restore                         Enable live restore of docker when containers are still running
+      --log-driver=json-file                 Default driver for container logs
+      --log-opt=map[]                        Default log driver options for containers
       --max-concurrent-downloads=3           Set the max concurrent downloads for each pull
       --max-concurrent-uploads=5             Set the max concurrent uploads for each push
-      --mtu=0                                Set the containers network MTU
+      --mtu                                  Set the containers network MTU
       --oom-score-adjust=-500                Set the oom_score_adj for the daemon
-      --disable-legacy-registry              Do not contact legacy registries
-      -p, --pidfile="/var/run/docker.pid"    Path to use for daemon PID file
+      -p, --pidfile=/var/run/docker.pid      Path to use for daemon PID file
       --raw-logs                             Full timestamps without ANSI coloring
       --registry-mirror=[]                   Preferred Docker registry mirror
-      -s, --storage-driver=""                Storage driver to use
+      -s, --storage-driver                   Storage driver to use
       --selinux-enabled                      Enable selinux support
-      --storage-opt=[]                       Set storage driver options
+      --storage-opt=[]                       Storage driver options
       --tls                                  Use TLS; implied by --tlsverify
-      --tlscacert="~/.docker/ca.pem"         Trust certs signed only by this CA
-      --tlscert="~/.docker/cert.pem"         Path to TLS certificate file
-      --tlskey="~/.docker/key.pem"           Path to TLS key file
+      --tlscacert=~/.docker/ca.pem           Trust certs signed only by this CA
+      --tlscert=~/.docker/cert.pem           Path to TLS certificate file
+      --tlskey=~/.docker/key.pem             Path to TLS key file
       --tlsverify                            Use TLS and verify the remote
-      --userns-remap="default"               Enable user namespace remapping
       --userland-proxy=true                  Use userland proxy for loopback traffic
+      --userns-remap                         User/Group setting for user namespaces
+      -v, --version                          Print version information and quit
+```
 
 Options with [] may be specified multiple times.
 

docs/reference/commandline/run.md

@@ -70,7 +70,7 @@ Options:
       --label-file value            Read in a line delimited file of labels (default [])
       --link value                  Add link to another container (default [])
       --link-local-ip value         Container IPv4/IPv6 link-local addresses (default [])
-      --log-driver string           Logging driver for container
+      --log-driver string           Logging driver for the container
       --log-opt value               Log driver options (default [])
       --mac-address string          Container MAC address (e.g. 92:d0:c6:0a:29:33)
   -m, --memory string               Memory limit
@@ -105,7 +105,7 @@ Options:
                                     or `g` (gigabytes). If you omit the unit, the system uses bytes.
       --sig-proxy                   Proxy received signals to the process (default true)
       --stop-signal string          Signal to stop a container, SIGTERM by default (default "SIGTERM")
-      --storage-opt value           Set storage driver options per container (default [])
+      --storage-opt value           Storage driver options for the container (default [])
       --sysctl value                Sysctl options (default map[])
       --tmpfs value                 Mount a tmpfs directory (default [])
   -t, --tty                         Allocate a pseudo-TTY

man/docker-create.1.md

@@ -225,7 +225,7 @@ millions of trillions.
    Add one or more link-local IPv4/IPv6 addresses to the container's interface
 
 **--log-driver**="*json-file*|*syslog*|*journald*|*gelf*|*fluentd*|*awslogs*|*splunk*|*etwlogs*|*gcplogs*|*none*"
-  Logging driver for container. Default is defined by daemon `--log-driver` flag.
+  Logging driver for the container. Default is defined by daemon `--log-driver` flag.
   **Warning**: the `docker logs` command works only for the `json-file` and
   `journald` logging drivers.
 

man/docker-run.1.md

@@ -331,7 +331,7 @@ which interface and port to use.
    Add one or more link-local IPv4/IPv6 addresses to the container's interface
 
 **--log-driver**="*json-file*|*syslog*|*journald*|*gelf*|*fluentd*|*awslogs*|*splunk*|*etwlogs*|*gcplogs*|*none*"
-  Logging driver for container. Default is defined by daemon `--log-driver` flag.
+  Logging driver for the container. Default is defined by daemon `--log-driver` flag.
   **Warning**: the `docker logs` command works only for the `json-file` and
   `journald` logging drivers.
 

man/dockerd.8.md

@@ -121,10 +121,10 @@ format.
   IPv6 address of the container default gateway
 
 **--default-ulimit**=[]
-  Set default ulimits for containers.
+  Default ulimits for containers.
 
 **--disable-legacy-registry**=*true*|*false*
-  Do not contact legacy registries
+  Disable contacting legacy registries
 
 **--dns**=""
   Force Docker to use specific DNS servers

registry/config.go

@@ -77,7 +77,7 @@ func (options *ServiceOptions) InstallCliFlags(cmd *flag.FlagSet, usageFn func(s
 	insecureRegistries := opts.NewNamedListOptsRef("insecure-registries", &options.InsecureRegistries, ValidateIndexName)
 	cmd.Var(insecureRegistries, []string{"-insecure-registry"}, usageFn("Enable insecure registry communication"))
 
-	cmd.BoolVar(&options.V2Only, []string{"-disable-legacy-registry"}, false, usageFn("Do not contact legacy registries"))
+	cmd.BoolVar(&options.V2Only, []string{"-disable-legacy-registry"}, false, usageFn("Disable contacting legacy registries"))
 }
 
 // newServiceConfig returns a new instance of ServiceConfig

runconfig/opts/parse.go

@@ -194,10 +194,10 @@ func AddFlags(flags *pflag.FlagSet) *ContainerOptions {
 	flags.MarkHidden("net-alias")
 
 	// Logging and storage
-	flags.StringVar(&copts.flLoggingDriver, "log-driver", "", "Logging driver for container")
+	flags.StringVar(&copts.flLoggingDriver, "log-driver", "", "Logging driver for the container")
 	flags.StringVar(&copts.flVolumeDriver, "volume-driver", "", "Optional volume driver for the container")
 	flags.Var(&copts.flLoggingOpts, "log-opt", "Log driver options")
-	flags.Var(&copts.flStorageOpt, "storage-opt", "Set storage driver options per container")
+	flags.Var(&copts.flStorageOpt, "storage-opt", "Storage driver options for the container")
 	flags.Var(&copts.flTmpfs, "tmpfs", "Mount a tmpfs directory")
 	flags.Var(&copts.flVolumesFrom, "volumes-from", "Mount volumes from the specified container(s)")
 	flags.VarP(&copts.flVolumes, "volume", "v", "Bind mount a volume")