diff --git a/container-storage-setup.1 b/container-storage-setup.1 index fd1125d..1cb3b4e 100644 --- a/container-storage-setup.1 +++ b/container-storage-setup.1 @@ -9,52 +9,61 @@ container\-storage\-setup - Tool for setting up storage for container runtimes. \f[B]container-storage-setup\f[] [OPTIONS] COMMAND [args] .SH DESCRIPTION - container-storage-setup configures storage for use by container - runtimes. - - container-storage-setup without specifying a command defaults to - using docker config files /etc/sysconfig/docker-storage-setup for - input and /etc/sysconfig/docker-storage for output. - - container-storage-setup with a commnad creates and manages storage - configurations. - - container-storage-setup can configure multiple backends: - devicemapper, overlay, and overlay2. +.PP +container-storage-setup configures storage for use by container +runtimes. +.PP +container-storage-setup without specifying a command defaults to +using docker config files /etc/sysconfig/docker-storage-setup for +input and /etc/sysconfig/docker-storage for output. +.PP +container-storage-setup with a commnad creates and manages storage +configurations. +.PP +container-storage-setup can configure multiple backends: +devicemapper, overlay, and overlay2. .SH OPTIONS -.PP -\f[B]--help\f[] - Print usage statement +.TP +.B --help +Print usage statement -\f[B]--reset\f[] - Reset your container storage to init state. Reset does not remove - volume groups or remove any of the disks added previously. +.TP +.B --reset +Reset your container storage to init state. Reset does not remove +volume groups or remove any of the disks added previously. - Note: The \f[B]--reset\f[] +Note: The \f[B]--reset\f[] command is not always sufficient to cleanup your - container runtime environment. Other tools (\f[B]atomic storage reset\f[]) - use this command to cleanup all storage. - -\f[B]--version\f[] - Print version information +container runtime environment. Other tools (\f[B]atomic storage reset\f[]) +use this command to cleanup all storage. +.TP +.B --version +Print version information .SH COMMANDS Following commands are supported. - -\f[B]create\f[] Create storage configuration - -\f[B]remove\f[] Remove storage configuration - -\f[B]list\f[] List currently created storage configurations - -\f[B]activate\f[] Activate storage configuration - -\f[B]deactivate\f[] Deactivate storage configuration - -\f[B]add-dev\f[] Add block device to storage configuration - -\f[B]export\f[] Export file which can be used to set environment variables for use by container runtimes +.TP +.B create +Create storage configuration +.TP +.B remove +Remove storage configuration +.TP +.B list +List currently created storage configurations +.TP +.B activate +Activate storage configuration +.TP +.B deactivate +Deactivate storage configuration +.TP +.B add-dev +Add block device to storage configuration +.TP +.B export +Export file which can be used to set environment variables for use by container runtimes .SH EXAMPLES Run \f[B]container-storage-setup\f[] after setting up your configuration in @@ -66,7 +75,9 @@ settings specified in /usr/share/container-storage-setup/container-storage-setup Create storage configuration example-config. +.RS .B container-storage-setup create -o OUTPUTFILE example-config INPUTFILE +.RE Above will create a storage configuration named example-config as specified in INPUTFILE and will put the output in OUTPUTFILE. OUTPUTFILE is @@ -78,176 +89,207 @@ be parsed by container runtime process. To cleanup storage configuration, execute remove command. +.RS .B container-storage-setup remove example-config +.RE lvm2 version should be same or higher than lvm2-2.02.112 for lvm thin pool functionality to work properly. \f[B]Supported options for the configuration file\f[]: -STORAGE_DRIVER: - Specify a storage driver to be used with container runtime. - Default: "devicemapper". - Valid values are overlay, overlay2 and "". - "" tells container-storage-setup to not perform any storage setup. - -CONTAINER_THINPOOL: - Specify the thinpool name for the lvm thinpool. This is required - when using the devicemapper STORAGE_DRIVER. CONTAINER_THINPOOL - is logical volume name passed to \f[B]lvcreate\f[] when creating - the thin pool volume. - -EXTRA_STORAGE_OPTIONS: - A set of extra options that should be passed to the container - runtime daemon. - Note: EXTRA_STORAGE_OPTIONS replaces EXTRA_DOCKER_STORAGE_OPTIONS - which has been deprecated - -DEVS: A quoted, space-separated list of devices to be used. - If a drive is partitioned and contains a ${dev}1 partition, - that partition will be configured for use. Unpartitioned - drives will be partitioned and configured for use. If "VG" - is not specified, then use of the root disk's extra space - is implied. - -VG: The volume group to use for container storage. Defaults to the - volume group where the root filesystem resides. If VG is - specified and the volume group does not exist, it will be - created (which requires that "DEVS" be nonempty, since we don't - currently support putting a second partition on the root disk). - +.RS +.TP +STORAGE_DRIVER +Specify a storage driver to be used with container runtime. +Default: "devicemapper". +Valid values are overlay, overlay2 and "". +"" tells container-storage-setup to not perform any storage setup. + +.TP +CONTAINER_THINPOOL +Specify the thinpool name for the lvm thinpool. This is required +when using the devicemapper STORAGE_DRIVER. CONTAINER_THINPOOL +is logical volume name passed to \f[B]lvcreate\f[] when creating +the thin pool volume. + +.TP +EXTRA_STORAGE_OPTIONS +A set of extra options that should be passed to the container +runtime daemon. +Note: EXTRA_STORAGE_OPTIONS replaces EXTRA_DOCKER_STORAGE_OPTIONS +which has been deprecated + +.TP +DEVS +A quoted, space-separated list of devices to be used. +If a drive is partitioned and contains a ${dev}1 partition, +that partition will be configured for use. Unpartitioned +drives will be partitioned and configured for use. If "VG" +is not specified, then use of the root disk's extra space +is implied. + +.TP +VG +The volume group to use for container storage. Defaults to the +volume group where the root filesystem resides. If VG is +specified and the volume group does not exist, it will be +created (which requires that "DEVS" be nonempty, since we don't +currently support putting a second partition on the root disk). + +.TP Note: lvm2 needs to be lvm2-2.02.112 or later for lvm thin pool functionality to work properly. -GROWPART: - One can use this option to enable/disable growing of partition - table backing root volume group. This is intended for - virtualization and cloud installations. By default it is - disabled. Use GROWPART=true to enable automatic partition - table resizing. - -AUTO_EXTEND_POOL: - Enable automatic extension of pool by lvm. lvm can monitor - the pool and automatically extend it when pool is getting full. - -POOL_AUTOEXTEND_THRESHOLD: - Determines the pool extension threshold in terms of percentage - of pool size. For example, if threshold is 60, that means when - pool is 60% full, threshold has been hit. - -POOL_AUTOEXTEND_PERCENT: - Determines the amount by which pool needs to be grown. This is - specified in terms of % of pool size. So a value of 20 means - that when threshold is hit, pool will be grown by 20% of existing - pool size. - -CHUNK_SIZE: - Controls the chunk size/block size of thin pool. CHUNK_SIZE value - must be suitable for passing to \f[B]lvconvert --chunk-size\f[]. - -DEVICE_WAIT_TIMEOUT: - Specifies a device wait timeout value in seconds. In certain - cases required devices might not be immediately available and - container-storage-setup might decide to wait for it. This timeout - specifies how long one should wait for the device. - Default is 60 seconds. 0 disables wait. - -WIPE_SIGNATURES: - Wipe any signatures found on disk. Valid values are - true/false and default value is false. By default if any - signatures are found on disk operation is aborted. If this value - is set to true, then signatures will either be wiped or - overwritten as suitable. This also means that if there is any - data on disk, it will be lost. - -CONTAINER_ROOT_LV_NAME: - Name of the logical volume that will be mounted on - CONTAINER_ROOT_LV_MOUNT_PATH. If a user is setting - CONTAINER_ROOT_LV_MOUNT_PATH, he/she must set - CONTAINER_ROOT_LV_NAME. - -CONTAINER_ROOT_LV_MOUNT_PATH: - Creates a logical volume named CONTAINER_ROOT_LV_NAME and mounts - it at the specified path. By default no new logical volume will - be created. For example: - \f[B]CONTAINER_ROOT_LV_MOUNT_PATH=/var/lib/containers/container-runtime\f[] - would carve out a logical volume, format it with an XFS filesystem - and mount it on /var/lib/containers/container-runtime. - - Note: DOCKER_ROOT_VOLUME is deprecated. Specifying - DOCKER_ROOT_VOLUME and CONTAINER_ROOT_LV_MOUNT_PATH at the same - time is not allowed. - -CONTAINER_ROOT_LV_SIZE: - Specify the desired size for CONTAINER_ROOT_LV_MOUNT_PATH - root volume. It defaults to 40% of all free space. - - CONTAINER_ROOT_LV_SIZE can take values acceptable to - \f[B]lvcreate -L\f[] as well as some values acceptable to - \f[B]lvcreate -l\f[]. If user intends to pass values acceptable - to \f[B]lvcreate -l\f[], then only those values which contains "%" - in syntax are acceptable. If value does not contain "%" it - is assumed value is suitable for \f[B]lvcreate -L\f[]. - - Note: If both STORAGE_DRIVER=devicemapper and - CONTAINER_ROOT_LV_MOUNT_PATH is set, container-storage-setup - would set up the thin pool for devicemapper first, - followed by extra volume. e.g if free space in the - volume group is 10G, devicemapper thin pool size - would be 4G (40% of 10G) and extra volume would be - 2.4G (40% of 6G). - - Note: DOCKER_ROOT_VOLUME_SIZE is deprecated. Specifying - DOCKER_ROOT_VOLUME_SIZE and CONTAINER_ROOT_LV_SIZE at the same - time is not allowed. - - +.TP +GROWPART +One can use this option to enable/disable growing of partition +table backing root volume group. This is intended for +virtualization and cloud installations. By default it is +disabled. Use GROWPART=true to enable automatic partition +table resizing. + +.TP +AUTO_EXTEND_POOL +Enable automatic extension of pool by lvm. lvm can monitor +the pool and automatically extend it when pool is getting full. + +.TP +POOL_AUTOEXTEND_THRESHOLD +Determines the pool extension threshold in terms of percentage +of pool size. For example, if threshold is 60, that means when +pool is 60% full, threshold has been hit. + +.TP +POOL_AUTOEXTEND_PERCENT +Determines the amount by which pool needs to be grown. This is +specified in terms of % of pool size. So a value of 20 means +that when threshold is hit, pool will be grown by 20% of existing +pool size. + +.TP +CHUNK_SIZE +Controls the chunk size/block size of thin pool. CHUNK_SIZE value +must be suitable for passing to \f[B]lvconvert --chunk-size\f[]. + +.TP +DEVICE_WAIT_TIMEOUT +Specifies a device wait timeout value in seconds. In certain +cases required devices might not be immediately available and +container-storage-setup might decide to wait for it. This timeout +specifies how long one should wait for the device. +Default is 60 seconds. 0 disables wait. + +.TP +WIPE_SIGNATURES +Wipe any signatures found on disk. Valid values are +true/false and default value is false. By default if any +signatures are found on disk operation is aborted. If this value +is set to true, then signatures will either be wiped or +overwritten as suitable. This also means that if there is any +data on disk, it will be lost. + +.TP +CONTAINER_ROOT_LV_NAME +Name of the logical volume that will be mounted on +CONTAINER_ROOT_LV_MOUNT_PATH. If a user is setting +CONTAINER_ROOT_LV_MOUNT_PATH, he/she must set +CONTAINER_ROOT_LV_NAME. + +.TP +CONTAINER_ROOT_LV_MOUNT_PATH +Creates a logical volume named CONTAINER_ROOT_LV_NAME and mounts +it at the specified path. By default no new logical volume will +be created. For example: +\f[B]CONTAINER_ROOT_LV_MOUNT_PATH=/var/lib/containers/container-runtime\f[] +would carve out a logical volume, format it with an XFS filesystem +and mount it on /var/lib/containers/container-runtime. + +Note: DOCKER_ROOT_VOLUME is deprecated. Specifying +DOCKER_ROOT_VOLUME and CONTAINER_ROOT_LV_MOUNT_PATH at the same +time is not allowed. + +.TP +CONTAINER_ROOT_LV_SIZE +Specify the desired size for CONTAINER_ROOT_LV_MOUNT_PATH +root volume. It defaults to 40% of all free space. + +CONTAINER_ROOT_LV_SIZE can take values acceptable to +\f[B]lvcreate -L\f[] as well as some values acceptable to +\f[B]lvcreate -l\f[]. If user intends to pass values acceptable +to \f[B]lvcreate -l\f[], then only those values which contains "%" +in syntax are acceptable. If value does not contain "%" it +is assumed value is suitable for \f[B]lvcreate -L\f[]. + +Note: If both STORAGE_DRIVER=devicemapper and +CONTAINER_ROOT_LV_MOUNT_PATH is set, container-storage-setup +would set up the thin pool for devicemapper first, +followed by extra volume. e.g if free space in the +volume group is 10G, devicemapper thin pool size +would be 4G (40% of 10G) and extra volume would be +2.4G (40% of 6G). + +Note: DOCKER_ROOT_VOLUME_SIZE is deprecated. Specifying +DOCKER_ROOT_VOLUME_SIZE and CONTAINER_ROOT_LV_SIZE at the same +time is not allowed. + +.TP Options below should be specified as values acceptable to \f[B]lvextend -L\f[]. -ROOT_SIZE: The size to which the root filesystem should be grown. - - ROOT_SIZE can take values acceptable to \f[B]lvcreate -L\f[] as well as - some values acceptable to \f[B]lvcreate -l\f[]. If user intends to pass - values acceptable to \f[B]lvcreate -l\f[], then only those values which - contains "%" in syntax are acceptable. If value does not contain - "%" it is assumed value is suitable for \f[B]lvcreate -L\f[]. - -DATA_SIZE: The desired size for container runtime thin pool data LV. - Defaults: 40% free space in the VG after the root LV and container - runtime metadata LV have been allocated/grown. - - DATA_SIZE can take values acceptable to \f[B]lvcreate -L\f[] as well as - some values acceptable to \f[B]lvcreate -l\f[]. If user intends to pass - values acceptable to \f[B]lvcreate -l\f[], then only those values which - contains "%" in syntax are acceptable. If value does not contain - "%" it is assumed value is suitable for \f[B]lvcreate -L\f[]. - -MIN_DATA_SIZE: Specifies the minimum size of the thin pool data LV. If - sufficient free space is not available, the pool creation will - fail. - - Value should be a number followed by a optional suffix. - "bBsSkKmMgGtTpPeE" are valid suffixes. If no suffix is specified - then value will be considered as megabyte unit. - - Both upper and lower case suffix represent same unit of size. - Use suffix B for Bytes, S for sectors as 512 bytes, K for - kibibytes (1024 bytes), M for mebibytes (1024 kibibytes), G for - gibibytes, T for tebibytes, P for pebibytes and E for exbibytes. - -POOL_META_SIZE: Specifies the size of thin pool metadata LV. If - sufficient free space is not available, the pool creation will - fail. - - Value should be a number followed by a optional suffix. - "bBsSkKmMgGtTpPeE" are valid suffixes. If no suffix is specified - then value will be considered as megabyte unit. - - Both upper and lower case suffix represent same unit of size. - Use suffix B for Bytes, S for sectors as 512 bytes, K for - kibibytes (1024 bytes), M for mebibytes (1024 kibibytes), G for - gibibytes, T for tebibytes, P for pebibytes and E for exbibytes. - -\f[B]Sample\f[] +.TP +ROOT_SIZE +The size to which the root filesystem should be grown. + +ROOT_SIZE can take values acceptable to \f[B]lvcreate -L\f[] as well as +some values acceptable to \f[B]lvcreate -l\f[]. If user intends to pass +values acceptable to \f[B]lvcreate -l\f[], then only those values which +contains "%" in syntax are acceptable. If value does not contain +"%" it is assumed value is suitable for \f[B]lvcreate -L\f[]. + +.TP +DATA_SIZE +The desired size for container runtime thin pool data LV. +Defaults: 40% free space in the VG after the root LV and container +runtime metadata LV have been allocated/grown. + +DATA_SIZE can take values acceptable to \f[B]lvcreate -L\f[] as well as +some values acceptable to \f[B]lvcreate -l\f[]. If user intends to pass +values acceptable to \f[B]lvcreate -l\f[], then only those values which +contains "%" in syntax are acceptable. If value does not contain +"%" it is assumed value is suitable for \f[B]lvcreate -L\f[]. + +.TP +MIN_DATA_SIZE +Specifies the minimum size of the thin pool data LV. If +sufficient free space is not available, the pool creation will +fail. + +Value should be a number followed by a optional suffix. +"bBsSkKmMgGtTpPeE" are valid suffixes. If no suffix is specified +then value will be considered as megabyte unit. + +Both upper and lower case suffix represent same unit of size. +Use suffix B for Bytes, S for sectors as 512 bytes, K for +kibibytes (1024 bytes), M for mebibytes (1024 kibibytes), G for +gibibytes, T for tebibytes, P for pebibytes and E for exbibytes. + +.TP +POOL_META_SIZE +Specifies the size of thin pool metadata LV. If +sufficient free space is not available, the pool creation will +fail. + +Value should be a number followed by a optional suffix. +"bBsSkKmMgGtTpPeE" are valid suffixes. If no suffix is specified +then value will be considered as megabyte unit. + +Both upper and lower case suffix represent same unit of size. +Use suffix B for Bytes, S for sectors as 512 bytes, K for +kibibytes (1024 bytes), M for mebibytes (1024 kibibytes), G for +gibibytes, T for tebibytes, P for pebibytes and E for exbibytes. +.RE + +.TP +.B Sample A simple, sample INPUTFILE: @@ -268,5 +310,7 @@ based on comments in Andy Grimm's script. February 2017, Modified by Dan Walsh . .SH AUTHORS Joe Brockmeier +.br Andy Grimm +.br Dan Walsh