{"action":"created","comment":{"url":"https://api.github.com/repos/docker/docker/pulls/comments/31149249","id":31149249,"diff_hunk":"@@ -292,79 +292,192 @@ inside it)\n \n # STORAGE DRIVER OPTIONS\n \n-Options to storage backend can be specified with **--storage-opt** flags. The\n-only backend which currently takes options is *devicemapper*. Therefore use these\n+Docker uses storage backends (or \"graphdriver\" in Docker internals) to create\n+writable containers from images.  Many of these backends use operating system\n+level technologies and can be configured.\n+\n+Specify options to the storage backend with **--storage-opt** flags. The only\n+backend that currently takes options is *devicemapper*. Therefore use these\n flags with **-s=**devicemapper.\n \n+Specifically for devicemapper, the default is a \"loopback\" model which\n+requires no pre-configuration, but is extremely inefficient.  Do not\n+use it in production.\n+\n+To make the best use of Docker with the devicemapper backend,\n+you must have a recent version of `lvm2`.  Use `lvm` to create a thin\n+pool.  Then, use `--storage-opt dm.thinpooldev` to tell the Docker\n+engine to use that pool for allocating images and container snapshots.\n+\n Here is the list of *devicemapper* options:\n \n+#### dm.thinpooldev\n+\n+Specifies a custom block storage device to use for the thin pool.\n+\n+If using a block device for device mapper storage, it is best to use\n+`lvm2` to create and manage the thin-pool volume. This volume is then\n+handed to Docker to create snapshot volumes needed for images and\n+containers.\n+\n+Managing the thin-pool outside of Docker makes for the most feature-rich method\n+of having Docker utilize device mapper thin provisioning as the backing storage\n+for Docker's containers. The highlights of the lvm2-based thin-pool management\n+feature include: automatic or interactive thin-pool resize support, dynamically\n+changing thin-pool features, automatic thinp metadata checking when lvm2 activates\n+the thin-pool, etc.\n+\n+Example use: ``docker -d --storage-opt dm.thinpooldev=/dev/mapper/thin-pool``\n+\n #### dm.basesize\n-Specifies the size to use when creating the base device, which limits the size\n-of images and containers. The default value is 10G. Note, thin devices are\n-inherently \"sparse\", so a 10G device which is mostly empty doesn't use 10 GB\n-of space on the pool. However, the filesystem will use more space for the empty\n-case the larger the device is. **Warning**: This value affects the system-wide\n-\"base\" empty filesystem that may already be initialized and inherited by pulled\n-images.\n \n-#### dm.loopdatasize\n-Specifies the size to use when creating the loopback file for the \"data\"\n-device which is used for the thin pool. The default size is 100G. Note that the\n-file is sparse, so it will not initially take up this much space.\n+Specifies the size to use when creating the base device, which limits\n+the size of images and containers. The default value is 10G. Note,\n+thin devices are inherently \"sparse\", so a 10G device which is mostly\n+empty doesn't use 10 GB of space on the pool. However, the filesystem\n+will use more space for the empty case the larger the device\n+is. **Warning**: This value affects the system-wide \"base\" empty\n+filesystem that may already be initialized and inherited by pulled\n+images.  Typically, a change to this value will require additional\n+steps to take effect: 1) stop `docker -d`, 2) `rm -rf\n+/var/lib/docker`, 3) start `docker -d`.\n \n-#### dm.loopmetadatasize\n-Specifies the size to use when creating the loopback file for the \"metadadata\"\n-device which is used for the thin pool. The default size is 2G. Note that the\n-file is sparse, so it will not initially take up this much space.\n+Example use: ``docker -d --storage-opt dm.basesize=20G``\n \n #### dm.fs\n-Specifies the filesystem type to use for the base device. The supported\n-options are \"ext4\" and \"xfs\". The default is \"ext4\"\n+\n+Specifies the filesystem type to use for the base device. The\n+supported options are `ext4` and `xfs`. The default is `ext4`.\n+\n+Example use: ``docker -d --storage-opt dm.fs=xfs``\n \n #### dm.mkfsarg\n+\n Specifies extra mkfs arguments to be used when creating the base device.\n \n+Example use: ``docker -d --storage-opt \"dm.mkfsarg=-O ^has_journal\"``\n+\n #### dm.mountopt\n+\n Specifies extra mount options used when mounting the thin devices.\n \n+Example use: ``docker -d --storage-opt dm.mountopt=nodiscard``\n+\n+#### dm.use_deferred_removal\n+\n+Enables use of deferred device removal if `libdm` and kernel driver\n+support the mechanism.\n+\n+Deferred device removal means that if device is busy when devices are\n+being removed/deactivated, then a deferred removal is scheduled on\n+device. And devices automatically goes away when last user of device\n+exits.\n+\n+For example, when a container exits, its associated thin device is removed. If\n+that devices has leaked into some other mount namespace and can't be removed,\n+the container exit still succeeds and this option causes the system to schedule\n+device for deferred removal. It does not wait in a loop trying to remove a busy\n+device.\n+\n+Example use: ``docker -d --storage-opt dm.use_deferred_removal=true``\n+\n+#### dm.loopdatasize\n+\n+**Note**: This option configures devicemapper loopback, which is not for\n+production use.\n+\n+Specifies the size to use when creating the loopback file for the\n+\"data\" device which is used for the thin pool. The default size is\n+100G. Note that the file is sparse, so it will not initially take up\n+this much space.\n+\n+Example use: ``docker -d --storage-opt dm.loopdatasize=200G``\n+\n+#### dm.loopmetadatasize\n+\n+**Note**: This option configures devicemapper loopback, which is not for","path":"docs/man/docker.1.md","position":126,"original_position":126,"commit_id":"d41d890d9d3617b53eda628bb550b38c2e72dc1b","original_commit_id":"d41d890d9d3617b53eda628bb550b38c2e72dc1b","user":{"login":"jamtur01","id":4365,"avatar_url":"https://avatars.githubusercontent.com/u/4365?v=3","gravatar_id":"","url":"https://api.github.com/users/jamtur01","html_url":"https://github.com/jamtur01","followers_url":"https://api.github.com/users/jamtur01/followers","following_url":"https://api.github.com/users/jamtur01/following{/other_user}","gists_url":"https://api.github.com/users/jamtur01/gists{/gist_id}","starred_url":"https://api.github.com/users/jamtur01/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jamtur01/subscriptions","organizations_url":"https://api.github.com/users/jamtur01/orgs","repos_url":"https://api.github.com/users/jamtur01/repos","events_url":"https://api.github.com/users/jamtur01/events{/privacy}","received_events_url":"https://api.github.com/users/jamtur01/received_events","type":"User","site_admin":false},"body":"As above.","created_at":"2015-05-27T15:58:07Z","updated_at":"2015-05-27T15:58:07Z","html_url":"https://github.com/docker/docker/pull/13323#discussion_r31149249","pull_request_url":"https://api.github.com/repos/docker/docker/pulls/13323","_links":{"self":{"href":"https://api.github.com/repos/docker/docker/pulls/comments/31149249"},"html":{"href":"https://github.com/docker/docker/pull/13323#discussion_r31149249"},"pull_request":{"href":"https://api.github.com/repos/docker/docker/pulls/13323"}}},"pull_request":{"url":"https://api.github.com/repos/docker/docker/pulls/13323","id":35749040,"html_url":"https://github.com/docker/docker/pull/13323","diff_url":"https://github.com/docker/docker/pull/13323.diff","patch_url":"https://github.com/docker/docker/pull/13323.patch","issue_url":"https://api.github.com/repos/docker/docker/issues/13323","number":13323,"state":"open","locked":false,"title":"docs: Unify devmapper option docs in docs/man/docker.1.md","user":{"login":"cgwalters","id":244096,"avatar_url":"https://avatars.githubusercontent.com/u/244096?v=3","gravatar_id":"","url":"https://api.github.com/users/cgwalters","html_url":"https://github.com/cgwalters","followers_url":"https://api.github.com/users/cgwalters/followers","following_url":"https://api.github.com/users/cgwalters/following{/other_user}","gists_url":"https://api.github.com/users/cgwalters/gists{/gist_id}","starred_url":"https://api.github.com/users/cgwalters/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cgwalters/subscriptions","organizations_url":"https://api.github.com/users/cgwalters/orgs","repos_url":"https://api.github.com/users/cgwalters/repos","events_url":"https://api.github.com/users/cgwalters/events{/privacy}","received_events_url":"https://api.github.com/users/cgwalters/received_events","type":"User","site_admin":false},"body":"I'll say up front, `man docker` is probably not the best place to\r\ninclude all of the details of the devmapper storage options.  However,\r\ntoday we have them there, and *also* in the `README.md` in the source\r\ncode.\r\n\r\nThere was quite a lot of duplication.  I went over the two docs and\r\ntook the best from each.\r\n\r\nThe man page makes sense because it's shipped with the package/system,\r\nand it's important for system administrators to be able to see options\r\ndocumented for the version of the system that they have, rather than\r\njust looking on github or whatever.\r\n\r\nAs a future step I'd like to move the devmapper options out to\r\ne.g. `man docker-devmapper` or so, but let's first deduplicate.\r\n\r\nDocker-DCO-1.1-Signed-off-by: Colin Walters <walters@verbum.org> (github: cgwalters)","created_at":"2015-05-19T16:28:30Z","updated_at":"2015-05-27T15:58:07Z","closed_at":null,"merged_at":null,"merge_commit_sha":"3df0311cd508224a12df047067547e4b4dcfa01b","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/docker/docker/pulls/13323/commits","review_comments_url":"https://api.github.com/repos/docker/docker/pulls/13323/comments","review_comment_url":"https://api.github.com/repos/docker/docker/pulls/comments{/number}","comments_url":"https://api.github.com/repos/docker/docker/issues/13323/comments","statuses_url":"https://api.github.com/repos/docker/docker/statuses/d41d890d9d3617b53eda628bb550b38c2e72dc1b","head":{"label":"cgwalters:devmapper-docs-merge-to-manpage","ref":"devmapper-docs-merge-to-manpage","sha":"d41d890d9d3617b53eda628bb550b38c2e72dc1b","user":{"login":"cgwalters","id":244096,"avatar_url":"https://avatars.githubusercontent.com/u/244096?v=3","gravatar_id":"","url":"https://api.github.com/users/cgwalters","html_url":"https://github.com/cgwalters","followers_url":"https://api.github.com/users/cgwalters/followers","following_url":"https://api.github.com/users/cgwalters/following{/other_user}","gists_url":"https://api.github.com/users/cgwalters/gists{/gist_id}","starred_url":"https://api.github.com/users/cgwalters/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cgwalters/subscriptions","organizations_url":"https://api.github.com/users/cgwalters/orgs","repos_url":"https://api.github.com/users/cgwalters/repos","events_url":"https://api.github.com/users/cgwalters/events{/privacy}","received_events_url":"https://api.github.com/users/cgwalters/received_events","type":"User","site_admin":false},"repo":{"id":20006906,"name":"docker","full_name":"cgwalters/docker","owner":{"login":"cgwalters","id":244096,"avatar_url":"https://avatars.githubusercontent.com/u/244096?v=3","gravatar_id":"","url":"https://api.github.com/users/cgwalters","html_url":"https://github.com/cgwalters","followers_url":"https://api.github.com/users/cgwalters/followers","following_url":"https://api.github.com/users/cgwalters/following{/other_user}","gists_url":"https://api.github.com/users/cgwalters/gists{/gist_id}","starred_url":"https://api.github.com/users/cgwalters/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cgwalters/subscriptions","organizations_url":"https://api.github.com/users/cgwalters/orgs","repos_url":"https://api.github.com/users/cgwalters/repos","events_url":"https://api.github.com/users/cgwalters/events{/privacy}","received_events_url":"https://api.github.com/users/cgwalters/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/cgwalters/docker","description":"Docker - the open-source application container engine","fork":true,"url":"https://api.github.com/repos/cgwalters/docker","forks_url":"https://api.github.com/repos/cgwalters/docker/forks","keys_url":"https://api.github.com/repos/cgwalters/docker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/cgwalters/docker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/cgwalters/docker/teams","hooks_url":"https://api.github.com/repos/cgwalters/docker/hooks","issue_events_url":"https://api.github.com/repos/cgwalters/docker/issues/events{/number}","events_url":"https://api.github.com/repos/cgwalters/docker/events","assignees_url":"https://api.github.com/repos/cgwalters/docker/assignees{/user}","branches_url":"https://api.github.com/repos/cgwalters/docker/branches{/branch}","tags_url":"https://api.github.com/repos/cgwalters/docker/tags","blobs_url":"https://api.github.com/repos/cgwalters/docker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/cgwalters/docker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/cgwalters/docker/git/refs{/sha}","trees_url":"https://api.github.com/repos/cgwalters/docker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/cgwalters/docker/statuses/{sha}","languages_url":"https://api.github.com/repos/cgwalters/docker/languages","stargazers_url":"https://api.github.com/repos/cgwalters/docker/stargazers","contributors_url":"https://api.github.com/repos/cgwalters/docker/contributors","subscribers_url":"https://api.github.com/repos/cgwalters/docker/subscribers","subscription_url":"https://api.github.com/repos/cgwalters/docker/subscription","commits_url":"https://api.github.com/repos/cgwalters/docker/commits{/sha}","git_commits_url":"https://api.github.com/repos/cgwalters/docker/git/commits{/sha}","comments_url":"https://api.github.com/repos/cgwalters/docker/comments{/number}","issue_comment_url":"https://api.github.com/repos/cgwalters/docker/issues/comments{/number}","contents_url":"https://api.github.com/repos/cgwalters/docker/contents/{+path}","compare_url":"https://api.github.com/repos/cgwalters/docker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/cgwalters/docker/merges","archive_url":"https://api.github.com/repos/cgwalters/docker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/cgwalters/docker/downloads","issues_url":"https://api.github.com/repos/cgwalters/docker/issues{/number}","pulls_url":"https://api.github.com/repos/cgwalters/docker/pulls{/number}","milestones_url":"https://api.github.com/repos/cgwalters/docker/milestones{/number}","notifications_url":"https://api.github.com/repos/cgwalters/docker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/cgwalters/docker/labels{/name}","releases_url":"https://api.github.com/repos/cgwalters/docker/releases{/id}","created_at":"2014-05-21T03:40:31Z","updated_at":"2014-07-24T21:22:47Z","pushed_at":"2015-05-27T01:37:46Z","git_url":"git://github.com/cgwalters/docker.git","ssh_url":"git@github.com:cgwalters/docker.git","clone_url":"https://github.com/cgwalters/docker.git","svn_url":"https://github.com/cgwalters/docker","homepage":"http://www.docker.io","size":54684,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"docker:master","ref":"master","sha":"e580734149c646adf1c939cc292bebc4950afde4","user":{"login":"docker","id":5429470,"avatar_url":"https://avatars.githubusercontent.com/u/5429470?v=3","gravatar_id":"","url":"https://api.github.com/users/docker","html_url":"https://github.com/docker","followers_url":"https://api.github.com/users/docker/followers","following_url":"https://api.github.com/users/docker/following{/other_user}","gists_url":"https://api.github.com/users/docker/gists{/gist_id}","starred_url":"https://api.github.com/users/docker/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/docker/subscriptions","organizations_url":"https://api.github.com/users/docker/orgs","repos_url":"https://api.github.com/users/docker/repos","events_url":"https://api.github.com/users/docker/events{/privacy}","received_events_url":"https://api.github.com/users/docker/received_events","type":"Organization","site_admin":false},"repo":{"id":7691631,"name":"docker","full_name":"docker/docker","owner":{"login":"docker","id":5429470,"avatar_url":"https://avatars.githubusercontent.com/u/5429470?v=3","gravatar_id":"","url":"https://api.github.com/users/docker","html_url":"https://github.com/docker","followers_url":"https://api.github.com/users/docker/followers","following_url":"https://api.github.com/users/docker/following{/other_user}","gists_url":"https://api.github.com/users/docker/gists{/gist_id}","starred_url":"https://api.github.com/users/docker/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/docker/subscriptions","organizations_url":"https://api.github.com/users/docker/orgs","repos_url":"https://api.github.com/users/docker/repos","events_url":"https://api.github.com/users/docker/events{/privacy}","received_events_url":"https://api.github.com/users/docker/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/docker/docker","description":"Docker - the open-source application container engine","fork":false,"url":"https://api.github.com/repos/docker/docker","forks_url":"https://api.github.com/repos/docker/docker/forks","keys_url":"https://api.github.com/repos/docker/docker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/docker/docker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/docker/docker/teams","hooks_url":"https://api.github.com/repos/docker/docker/hooks","issue_events_url":"https://api.github.com/repos/docker/docker/issues/events{/number}","events_url":"https://api.github.com/repos/docker/docker/events","assignees_url":"https://api.github.com/repos/docker/docker/assignees{/user}","branches_url":"https://api.github.com/repos/docker/docker/branches{/branch}","tags_url":"https://api.github.com/repos/docker/docker/tags","blobs_url":"https://api.github.com/repos/docker/docker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/docker/docker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/docker/docker/git/refs{/sha}","trees_url":"https://api.github.com/repos/docker/docker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/docker/docker/statuses/{sha}","languages_url":"https://api.github.com/repos/docker/docker/languages","stargazers_url":"https://api.github.com/repos/docker/docker/stargazers","contributors_url":"https://api.github.com/repos/docker/docker/contributors","subscribers_url":"https://api.github.com/repos/docker/docker/subscribers","subscription_url":"https://api.github.com/repos/docker/docker/subscription","commits_url":"https://api.github.com/repos/docker/docker/commits{/sha}","git_commits_url":"https://api.github.com/repos/docker/docker/git/commits{/sha}","comments_url":"https://api.github.com/repos/docker/docker/comments{/number}","issue_comment_url":"https://api.github.com/repos/docker/docker/issues/comments{/number}","contents_url":"https://api.github.com/repos/docker/docker/contents/{+path}","compare_url":"https://api.github.com/repos/docker/docker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/docker/docker/merges","archive_url":"https://api.github.com/repos/docker/docker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/docker/docker/downloads","issues_url":"https://api.github.com/repos/docker/docker/issues{/number}","pulls_url":"https://api.github.com/repos/docker/docker/pulls{/number}","milestones_url":"https://api.github.com/repos/docker/docker/milestones{/number}","notifications_url":"https://api.github.com/repos/docker/docker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/docker/docker/labels{/name}","releases_url":"https://api.github.com/repos/docker/docker/releases{/id}","created_at":"2013-01-18T18:10:57Z","updated_at":"2015-05-27T15:25:20Z","pushed_at":"2015-05-27T15:50:18Z","git_url":"git://github.com/docker/docker.git","ssh_url":"git@github.com:docker/docker.git","clone_url":"https://github.com/docker/docker.git","svn_url":"https://github.com/docker/docker","homepage":"http://www.docker.com","size":217634,"stargazers_count":21945,"watchers_count":21945,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":5199,"mirror_url":null,"open_issues_count":1027,"forks":5199,"open_issues":1027,"watchers":21945,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/docker/docker/pulls/13323"},"html":{"href":"https://github.com/docker/docker/pull/13323"},"issue":{"href":"https://api.github.com/repos/docker/docker/issues/13323"},"comments":{"href":"https://api.github.com/repos/docker/docker/issues/13323/comments"},"review_comments":{"href":"https://api.github.com/repos/docker/docker/pulls/13323/comments"},"review_comment":{"href":"https://api.github.com/repos/docker/docker/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/docker/docker/pulls/13323/commits"},"statuses":{"href":"https://api.github.com/repos/docker/docker/statuses/d41d890d9d3617b53eda628bb550b38c2e72dc1b"}}}}