github.com/pritambaral/docker@v1.4.2-0.20150120174542-b2fe1b3dd952/daemon/graphdriver/devmapper/README.md (about) 1 ## devicemapper - a storage backend based on Device Mapper 2 3 ### Theory of operation 4 5 The device mapper graphdriver uses the device mapper thin provisioning 6 module (dm-thinp) to implement CoW snapshots. For each devicemapper 7 graph location (typically `/var/lib/docker/devicemapper`, $graph below) 8 a thin pool is created based on two block devices, one for data and 9 one for metadata. By default these block devices are created 10 automatically by using loopback mounts of automatically created sparse 11 files. 12 13 The default loopback files used are `$graph/devicemapper/data` and 14 `$graph/devicemapper/metadata`. Additional metadata required to map 15 from docker entities to the corresponding devicemapper volumes is 16 stored in the `$graph/devicemapper/json` file (encoded as Json). 17 18 In order to support multiple devicemapper graphs on a system, the thin 19 pool will be named something like: `docker-0:33-19478248-pool`, where 20 the `0:33` part is the minor/major device nr and `19478248` is the 21 inode number of the $graph directory. 22 23 On the thin pool, docker automatically creates a base thin device, 24 called something like `docker-0:33-19478248-base` of a fixed 25 size. This is automatically formatted with an empty filesystem on 26 creation. This device is the base of all docker images and 27 containers. All base images are snapshots of this device and those 28 images are then in turn used as snapshots for other images and 29 eventually containers. 30 31 ### Information on `docker info` 32 33 As of docker-1.4.1, `docker info` when using the `devicemapper` storage driver 34 will display something like: 35 36 $ sudo docker info 37 [...] 38 Storage Driver: devicemapper 39 Pool Name: docker-253:1-17538953-pool 40 Pool Blocksize: 65.54 kB 41 Data file: /dev/loop4 42 Metadata file: /dev/loop4 43 Data Space Used: 2.536 GB 44 Data Space Total: 107.4 GB 45 Metadata Space Used: 7.93 MB 46 Metadata Space Total: 2.147 GB 47 Udev Sync Supported: true 48 Data loop file: /home/docker/devicemapper/devicemapper/data 49 Metadata loop file: /home/docker/devicemapper/devicemapper/metadata 50 Library Version: 1.02.82-git (2013-10-04) 51 [...] 52 53 #### status items 54 55 Each item in the indented section under `Storage Driver: devicemapper` are 56 status information about the driver. 57 * `Pool Name` name of the devicemapper pool for this driver. 58 * `Pool Blocksize` tells the blocksize the thin pool was initialized with. This only changes on creation. 59 * `Data file` blockdevice file used for the devicemapper data 60 * `Metadata file` blockdevice file used for the devicemapper metadata 61 * `Data Space Used` tells how much of `Data file` is currently used 62 * `Data Space Total` tells max size the `Data file` 63 * `Metadata Space Used` tells how much of `Metadata file` is currently used 64 * `Metadata Space Total` tells max size the `Metadata file` 65 * `Udev Sync Supported` tells whether devicemapper is able to sync with Udev. Should be `true`. 66 * `Data loop file` file attached to `Data file`, if loopback device is used 67 * `Metadata loop file` file attached to `Metadata file`, if loopback device is used 68 * `Library Version` from the libdevmapper used 69 70 ### options 71 72 The devicemapper backend supports some options that you can specify 73 when starting the docker daemon using the `--storage-opt` flags. 74 This uses the `dm` prefix and would be used something like `docker -d --storage-opt dm.foo=bar`. 75 76 Here is the list of supported options: 77 78 * `dm.basesize` 79 80 Specifies the size to use when creating the base device, which 81 limits the size of images and containers. The default value is 82 10G. Note, thin devices are inherently "sparse", so a 10G device 83 which is mostly empty doesn't use 10 GB of space on the 84 pool. However, the filesystem will use more space for the empty 85 case the larger the device is. **Warning**: This value affects the 86 system-wide "base" empty filesystem that may already be 87 initialized and inherited by pulled images. Typically, a change 88 to this value will require additional steps to take effect: 1) 89 stop `docker -d`, 2) `rm -rf /var/lib/docker`, 3) start `docker -d`. 90 91 Example use: 92 93 ``docker -d --storage-opt dm.basesize=20G`` 94 95 * `dm.loopdatasize` 96 97 Specifies the size to use when creating the loopback file for the 98 "data" device which is used for the thin pool. The default size is 99 100G. Note that the file is sparse, so it will not initially take 100 up this much space. 101 102 Example use: 103 104 ``docker -d --storage-opt dm.loopdatasize=200G`` 105 106 * `dm.loopmetadatasize` 107 108 Specifies the size to use when creating the loopback file for the 109 "metadadata" device which is used for the thin pool. The default size is 110 2G. Note that the file is sparse, so it will not initially take 111 up this much space. 112 113 Example use: 114 115 ``docker -d --storage-opt dm.loopmetadatasize=4G`` 116 117 * `dm.fs` 118 119 Specifies the filesystem type to use for the base device. The supported 120 options are "ext4" and "xfs". The default is "ext4" 121 122 Example use: 123 124 ``docker -d --storage-opt dm.fs=xfs`` 125 126 * `dm.mkfsarg` 127 128 Specifies extra mkfs arguments to be used when creating the base device. 129 130 Example use: 131 132 ``docker -d --storage-opt "dm.mkfsarg=-O ^has_journal"`` 133 134 * `dm.mountopt` 135 136 Specifies extra mount options used when mounting the thin devices. 137 138 Example use: 139 140 ``docker -d --storage-opt dm.mountopt=nodiscard`` 141 142 * `dm.thinpooldev` 143 144 Specifies a custom blockdevice to use for the thin pool. 145 146 If using a block device for device mapper storage, ideally lvm2 147 would be used to create/manage the thin-pool volume that is then 148 handed to docker to exclusively create/manage the thin and thin 149 snapshot volumes needed for it's containers. Managing the thin-pool 150 outside of docker makes for the most feature-rich method of having 151 docker utilize device mapper thin provisioning as the backing 152 storage for docker's containers. lvm2-based thin-pool management 153 feature highlights include: automatic or interactive thin-pool 154 resize support, dynamically change thin-pool features, automatic 155 thinp metadata checking when lvm2 activates the thin-pool, etc. 156 157 Example use: 158 159 ``docker -d --storage-opt dm.thinpooldev=/dev/mapper/thin-pool`` 160 161 * `dm.datadev` 162 163 Specifies a custom blockdevice to use for data for the thin pool. 164 165 If using a block device for device mapper storage, ideally both 166 datadev and metadatadev should be specified to completely avoid 167 using the loopback device. 168 169 Example use: 170 171 ``docker -d --storage-opt dm.datadev=/dev/sdb1 --storage-opt dm.metadatadev=/dev/sdc1`` 172 173 * `dm.metadatadev` 174 175 Specifies a custom blockdevice to use for metadata for the thin 176 pool. 177 178 For best performance the metadata should be on a different spindle 179 than the data, or even better on an SSD. 180 181 If setting up a new metadata pool it is required to be valid. This 182 can be achieved by zeroing the first 4k to indicate empty 183 metadata, like this: 184 185 ``dd if=/dev/zero of=$metadata_dev bs=4096 count=1``` 186 187 Example use: 188 189 ``docker -d --storage-opt dm.datadev=/dev/sdb1 --storage-opt dm.metadatadev=/dev/sdc1`` 190 191 * `dm.blocksize` 192 193 Specifies a custom blocksize to use for the thin pool. The default 194 blocksize is 64K. 195 196 Example use: 197 198 ``docker -d --storage-opt dm.blocksize=512K`` 199 200 * `dm.blkdiscard` 201 202 Enables or disables the use of blkdiscard when removing 203 devicemapper devices. This is enabled by default (only) if using 204 loopback devices and is required to res-parsify the loopback file 205 on image/container removal. 206 207 Disabling this on loopback can lead to *much* faster container 208 removal times, but will make the space used in /var/lib/docker 209 directory not be returned to the system for other use when 210 containers are removed. 211 212 Example use: 213 214 ``docker -d --storage-opt dm.blkdiscard=false``