diff --git a/contrib/completion/fish/docker.fish b/contrib/completion/fish/docker.fish index 73c2966393..a082adc02c 100644 --- a/contrib/completion/fish/docker.fish +++ b/contrib/completion/fish/docker.fish @@ -53,7 +53,7 @@ complete -c docker -f -n '__fish_docker_no_subcommand' -s d -l daemon -d 'Enable complete -c docker -f -n '__fish_docker_no_subcommand' -l dns -d 'Force docker to use specific DNS servers' complete -c docker -f -n '__fish_docker_no_subcommand' -s e -l exec-driver -d 'Force the docker runtime to use a specific exec driver' complete -c docker -f -n '__fish_docker_no_subcommand' -s g -l graph -d 'Path to use as the root of the docker runtime' -complete -c docker -f -n '__fish_docker_no_subcommand' -l icc -d 'Enable inter-container communication' +complete -c docker -f -n '__fish_docker_no_subcommand' -l icc -d 'Allow unrestricted inter-container and Docker daemon host communication' complete -c docker -f -n '__fish_docker_no_subcommand' -l ip -d 'Default IP address to use when binding container ports' complete -c docker -f -n '__fish_docker_no_subcommand' -l ip-forward -d 'Disable enabling of net.ipv4.ip_forward' complete -c docker -f -n '__fish_docker_no_subcommand' -l iptables -d "Disable docker's addition of iptables rules" diff --git a/daemon/config.go b/daemon/config.go index 785fd4d290..4d9041e895 100644 --- a/daemon/config.go +++ b/daemon/config.go @@ -59,7 +59,7 @@ func (config *Config) InstallFlags() { flag.StringVar(&config.BridgeIface, []string{"b", "-bridge"}, "", "Attach containers to a pre-existing network bridge\nuse 'none' to disable container networking") flag.StringVar(&config.FixedCIDR, []string{"-fixed-cidr"}, "", "IPv4 subnet for fixed IPs (ex: 10.20.0.0/16)\nthis subnet must be nested in the bridge subnet (which is defined by -b or --bip)") opts.ListVar(&config.InsecureRegistries, []string{"-insecure-registry"}, "Enable insecure communication with specified registries (no certificate verification for HTTPS and enable HTTP fallback) (e.g., localhost:5000 or 10.20.0.0/16)") - flag.BoolVar(&config.InterContainerCommunication, []string{"#icc", "-icc"}, true, "Enable inter-container communication") + flag.BoolVar(&config.InterContainerCommunication, []string{"#icc", "-icc"}, true, "Allow unrestricted inter-container and Docker daemon host communication") flag.StringVar(&config.GraphDriver, []string{"s", "-storage-driver"}, "", "Force the Docker runtime to use a specific storage driver") flag.StringVar(&config.ExecDriver, []string{"e", "-exec-driver"}, "native", "Force the Docker runtime to use a specific exec driver") flag.BoolVar(&config.EnableSelinuxSupport, []string{"-selinux-enabled"}, false, "Enable selinux support. SELinux does not presently support the BTRFS storage driver") diff --git a/docs/man/docker.1.md b/docs/man/docker.1.md index c8d28b2c23..e07687c18d 100644 --- a/docs/man/docker.1.md +++ b/docs/man/docker.1.md @@ -54,7 +54,7 @@ unix://[/path/to/socket] to use. IPv4 subnet for fixed IPs (ex: 10.20.0.0/16); this subnet must be nested in the bridge subnet (which is defined by \-b or \-\-bip) **--icc**=*true*|*false* - Enable inter\-container communication. Default is true. + Allow unrestricted inter\-container and Docker daemon host communication. If disabled, containers can still be linked together using **--link** option (see **docker-run(1)**). Default is true. **--ip**="" Default IP address to use when binding container ports. Default is `0.0.0.0`. @@ -77,12 +77,15 @@ unix://[/path/to/socket] to use. **-p**="" Path to use for daemon PID file. Default is `/var/run/docker.pid` -**--registry-mirror=:// +**--registry-mirror**=:// Prepend a registry mirror to be used for image pulls. May be specified multiple times. **-s**="" Force the Docker runtime to use a specific storage driver. +**--storage-opt**=[] + Set storage driver options. See STORAGE DRIVER OPTIONS. + **-v**=*true*|*false* Print version information and quit. Default is false. @@ -202,13 +205,87 @@ inside it) **docker-wait(1)** Block until a container stops, then print its exit code -# EXAMPLES +# STORAGE DRIVER OPTIONS -For specific examples please see the man page for the specific Docker command. -For example: +Options to storage backend can be specified with **--storage-opt** flags. The +only backend which currently takes options is *devicemapper*. Therefore use these +flags with **-s=**devicemapper. + +Here is the list of *devicemapper* options: + +#### dm.basesize +Specifies the size to use when creating the base device, which limits the size +of images and containers. The default value is 10G. Note, thin devices are +inherently "sparse", so a 10G device which is mostly empty doesn't use 10 GB +of space on the pool. However, the filesystem will use more space for the empty +case the larger the device is. **Warning**: This value affects the system-wide +"base" empty filesystem that may already be initialized and inherited by pulled +images. + +#### dm.loopdatasize +Specifies the size to use when creating the loopback file for the "data" +device which is used for the thin pool. The default size is 100G. Note that the +file is sparse, so it will not initially take up this much space. + +#### dm.loopmetadatasize +Specifies the size to use when creating the loopback file for the "metadadata" +device which is used for the thin pool. The default size is 2G. Note that the +file is sparse, so it will not initially take up this much space. + +#### dm.fs +Specifies the filesystem type to use for the base device. The supported +options are "ext4" and "xfs". The default is "ext4" + +#### dm.mkfsarg +Specifies extra mkfs arguments to be used when creating the base device. + +#### dm.mountopt +Specifies extra mount options used when mounting the thin devices. + +#### dm.datadev +Specifies a custom blockdevice to use for data for the thin pool. + +If using a block device for device mapper storage, ideally both datadev and +metadatadev should be specified to completely avoid using the loopback device. + +#### dm.metadatadev +Specifies a custom blockdevice to use for metadata for the thin pool. + +For best performance the metadata should be on a different spindle than the +data, or even better on an SSD. + +If setting up a new metadata pool it is required to be valid. This can be +achieved by zeroing the first 4k to indicate empty metadata, like this: + + dd if=/dev/zero of=/dev/metadata_dev bs=4096 count=1 + +#### dm.blocksize +Specifies a custom blocksize to use for the thin pool. The default blocksize +is 64K. + +#### dm.blkdiscard +Enables or disables the use of blkdiscard when removing devicemapper devices. +This is enabled by default (only) if using loopback devices and is required to +res-parsify the loopback file on image/container removal. + +Disabling this on loopback can lead to *much* faster container removal times, +but will prevent the space used in `/var/lib/docker` directory from being returned to +the system for other use when containers are removed. + +# EXAMPLES +Launching docker daemon with *devicemapper* backend with particular block devices +for data and metadata: + + docker -d -s=devicemapper \ + --storage-opt dm.datadev=/dev/vdb \ + --storage-opt dm.metadatadev=/dev/vdc \ + --storage-opt dm.basesize=20G + +#### Client +For specific client examples please see the man page for the specific Docker +command. For example: man docker run # HISTORY -April 2014, Originally compiled by William Henry (whenry at redhat dot com) based - on docker.com source material and internal work. +April 2014, Originally compiled by William Henry (whenry at redhat dot com) based on docker.com source material and internal work. diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 090d8180dd..6224c5223f 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -69,7 +69,7 @@ expect an integer, and they can only be specified once. use '' (the empty string) to disable setting of a group -g, --graph="/var/lib/docker" Path to use as the root of the Docker runtime -H, --host=[] The socket(s) to bind to in daemon mode or connect to in client mode, specified using one or more tcp://host:port, unix:///path/to/socket, fd://* or fd://socketfd. - --icc=true Enable inter-container communication + --icc=true Allow unrestricted inter-container and Docker daemon host communication --insecure-registry=[] Enable insecure communication with specified registries (disables certificate verification for HTTPS and enables HTTP fallback) (e.g., localhost:5000 or 10.20.0.0/16) --ip=0.0.0.0 Default IP address to use when binding container ports --ip-forward=true Enable net.ipv4.ip_forward @@ -164,13 +164,16 @@ serious kernel crashes. However, `aufs` is also the only storage driver that all containers to share executable and shared library memory, so is a useful choice when running thousands of containers with the same program or libraries. -The `devicemapper` driver uses thin provisioning and Copy on Write (CoW) snapshots. -This driver will create a 100GB sparse file containing all your images and -containers. Each container will be limited to a 10 GB thin volume, and either of -these will require tuning - see [~jpetazzo/Resizing Docker containers with the -Device Mapper plugin]( http://jpetazzo.github.io/2014/01/29/docker-device-mapper-resize/) -To tell the Docker daemon to use `devicemapper`, use -`docker -d -s devicemapper`. +The `devicemapper` driver uses thin provisioning and Copy on Write (CoW) +snapshots. For each devicemapper graph location – typically +`/var/lib/docker/devicemapper` – a thin pool is created based on two block +devices, one for data and one for metadata. By default, these block devices +are created automatically by using loopback mounts of automatically created +sparse files. Refer to [Storage driver options](#storage-driver-options) below +for a way how to customize this setup. +[~jpetazzo/Resizing Docker containers with the Device Mapper plugin]( +http://jpetazzo.github.io/2014/01/29/docker-device-mapper-resize/) article +explains how to tune your existing setup without the use of options. The `btrfs` driver is very fast for `docker build` - but like `devicemapper` does not share executable memory between devices. Use `docker -d -s btrfs -g /mnt/btrfs_partition`. @@ -179,6 +182,135 @@ The `overlay` is a very fast union filesystem. It is now merged in the main Linux kernel as of [3.18.0](https://lkml.org/lkml/2014/10/26/137). Call `docker -d -s overlay` to use it. +#### Storage driver options + +Particular storage-driver can be configured with options specified with +`--storage-opt` flags. The only driver accepting options is `devicemapper` as +of now. All its options are prefixed with `dm`. + +Currently supported options are: + + * `dm.basesize` + + Specifies the size to use when creating the base device, which limits the + size of images and containers. The default value is 10G. Note, thin devices + are inherently "sparse", so a 10G device which is mostly empty doesn't use + 10 GB of space on the pool. However, the filesystem will use more space for + the empty case the larger the device is. + + **Warning**: This value affects the system-wide "base" empty filesystem + that may already be initialized and inherited by pulled images. Typically, + a change to this value will require additional steps to take effect: + + $ sudo service docker stop + $ sudo rm -rf /var/lib/docker + $ sudo service docker start + + Example use: + + $ sudo docker -d --storage-opt dm.basesize=20G + + * `dm.loopdatasize` + + Specifies the size to use when creating the loopback file for the "data" + device which is used for the thin pool. The default size is 100G. Note that + the file is sparse, so it will not initially take up this much space. + + Example use: + + $ sudo docker -d --storage-opt dm.loopdatasize=200G + + * `dm.loopmetadatasize` + + Specifies the size to use when creating the loopback file for the + "metadata" device which is used for the thin pool. The default size is 2G. + Note that the file is sparse, so it will not initially take up this much + space. + + Example use: + + $ sudo docker -d --storage-opt dm.loopmetadatasize=4G + + * `dm.fs` + + Specifies the filesystem type to use for the base device. The supported + options are "ext4" and "xfs". The default is "ext4" + + Example use: + + $ sudo docker -d --storage-opt dm.fs=xfs + + * `dm.mkfsarg` + + Specifies extra mkfs arguments to be used when creating the base device. + + Example use: + + $ sudo docker -d --storage-opt "dm.mkfsarg=-O ^has_journal" + + * `dm.mountopt` + + Specifies extra mount options used when mounting the thin devices. + + Example use: + + $ sudo docker -d --storage-opt dm.mountopt=nodiscard + + * `dm.datadev` + + Specifies a custom blockdevice to use for data for the thin pool. + + If using a block device for device mapper storage, ideally both datadev and + metadatadev should be specified to completely avoid using the loopback + device. + + Example use: + + $ sudo docker -d \ + --storage-opt dm.datadev=/dev/sdb1 \ + --storage-opt dm.metadatadev=/dev/sdc1 + + * `dm.metadatadev` + + Specifies a custom blockdevice to use for metadata for the thin pool. + + For best performance the metadata should be on a different spindle than the + data, or even better on an SSD. + + If setting up a new metadata pool it is required to be valid. This can be + achieved by zeroing the first 4k to indicate empty metadata, like this: + + $ dd if=/dev/zero of=$metadata_dev bs=4096 count=1 + + Example use: + + $ sudo docker -d \ + --storage-opt dm.datadev=/dev/sdb1 \ + --storage-opt dm.metadatadev=/dev/sdc1 + + * `dm.blocksize` + + Specifies a custom blocksize to use for the thin pool. The default + blocksize is 64K. + + Example use: + + $ sudo docker -d --storage-opt dm.blocksize=512K + + * `dm.blkdiscard` + + Enables or disables the use of blkdiscard when removing devicemapper + devices. This is enabled by default (only) if using loopback devices and is + required to res-parsify the loopback file on image/container removal. + + Disabling this on loopback can lead to *much* faster container removal + times, but will make the space used in `/var/lib/docker` directory not be + returned to the system for other use when containers are removed. + + Example use: + + $ sudo docker -d --storage-opt dm.blkdiscard=false + ### Docker exec-driver option The Docker daemon uses a specifically built `libcontainer` execution driver as its