github.com/daaku/docker@v1.5.0/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 resparsify 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``