From 64a8317a5a306dffd0ec080d9ec5b4ceb2479a01 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 16 Jul 2016 01:52:59 +0200 Subject: [PATCH] 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 --- cmd/dockerd/docker.go | 2 +- contrib/completion/zsh/_docker | 12 ++--- daemon/config.go | 10 ++-- daemon/config_unix.go | 4 +- docs/reference/commandline/create.md | 4 +- docs/reference/commandline/dockerd.md | 72 ++++++++++++++++----------- docs/reference/commandline/run.md | 4 +- man/docker-create.1.md | 2 +- man/docker-run.1.md | 2 +- man/dockerd.8.md | 4 +- registry/config.go | 2 +- runconfig/opts/parse.go | 4 +- 12 files changed, 67 insertions(+), 55 deletions(-) diff --git a/cmd/dockerd/docker.go b/cmd/dockerd/docker.go index 5eec9e0476..b1c9b803a1 100644 --- a/cmd/dockerd/docker.go +++ b/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) diff --git a/contrib/completion/zsh/_docker b/contrib/completion/zsh/_docker index 170a47f5c4..87ecea81c0 100644 --- a/contrib/completion/zsh/_docker +++ b/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 diff --git a/daemon/config.go b/daemon/config.go index 262918b328..9dfb4f7fb1 100644 --- a/daemon/config.go +++ b/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")) diff --git a/daemon/config_unix.go b/daemon/config_unix.go index 26beaf4f32..d80a2c07c0 100644 --- a/daemon/config_unix.go +++ b/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) diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index 1d41c68665..3b550c0464 100644 --- a/docs/reference/commandline/create.md +++ b/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 diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index 939f3c189c..04e16534c2 100644 --- a/docs/reference/commandline/dockerd.md +++ b/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. diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index a5057a6250..fb8d75de25 100644 --- a/docs/reference/commandline/run.md +++ b/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 diff --git a/man/docker-create.1.md b/man/docker-create.1.md index e9b1ebe31a..980e09c101 100644 --- a/man/docker-create.1.md +++ b/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. diff --git a/man/docker-run.1.md b/man/docker-run.1.md index d4a2953161..65cdc7ae9f 100644 --- a/man/docker-run.1.md +++ b/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. diff --git a/man/dockerd.8.md b/man/dockerd.8.md index fc9226d387..333cf5a5aa 100644 --- a/man/dockerd.8.md +++ b/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 diff --git a/registry/config.go b/registry/config.go index 51302d110e..e349660e32 100644 --- a/registry/config.go +++ b/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 diff --git a/runconfig/opts/parse.go b/runconfig/opts/parse.go index e6409cc4d5..9d2ba67ae6 100644 --- a/runconfig/opts/parse.go +++ b/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")