CONTAINER-STORAGE-SETUP(1)

📦 version 0.11.0, in fedora 43, fedora 44

🌸 NAME 🌸

okay so bestie, meet container-storage-setup — the tool for setting up storage for container runtimes. that's the whole job description, no cap. 💅

✨ SYNOPSIS ✨

container-storage-setup [OPTIONS]

container-storage-setup [OPTIONS] COMMAND [args]

🦋 DESCRIPTION 🦋

container-storage-setup configures storage for use by container runtimes. iconic behavior honestly.

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. it just knows what you meant. main character energy. ✨

container-storage-setup with a commnad creates and manages storage configurations. (yes, "commnad" — we're quoting the original typo, it's canon now, don't come for me 🙈)

container-storage-setup can configure multiple backends: devicemapper, overlay, and overlay2. three flavors, all valid, we love options. 🍓

💅 OPTIONS 💅

  • --help — prints the usage statement. the classic "wait what does this do again" button. 🫶
  • --reset — resets your container storage back to init state. lowkey important: Reset does not remove volume groups or remove any of the disks added previously.
⚠️ Note: The --reset command is not always sufficient to cleanup your container runtime environment. Other tools (atomic storage reset) use this command to cleanup all storage. so like, don't assume this one flag does the entire cleanup, bestie. 😭
  • --version — prints version information. the "who even are you" of flags. 👑

🎀 COMMANDS 🎀

following commands are supported, periodt:

  • create — Create storage configuration ✨
  • remove — Remove storage configuration
  • list — List currently created storage configurations 👀
  • activate — Activate storage configuration 🔥
  • deactivate — Deactivate storage configuration 💤
  • add-dev — Add block device to storage configuration
  • export — Export file which can be used to set environment variables for use by container runtimes 🌈

🌟 EXAMPLES 🌟

run container-storage-setup after setting up your configuration in the INPUTFILE or /etc/sysconfig/docker-storage-setup. you can look at /usr/share/container-storage-setup/container-storage-setup for various options and their default settings. anything that the user wants to change, should be changed in the INPUTFILE. this is the file which will override any settings specified in /usr/share/container-storage-setup/container-storage-setup. it's giving "defaults first, your opinions second." 💅

create storage configuration example-config:

container-storage-setup create -o OUTPUTFILE example-config INPUTFILE

above will create a storage configuration named example-config as specified in INPUTFILE and will put the output in OUTPUTFILE. OUTPUTFILE is a file which can be parsed by container runtime for various config options. in a typical form, output file can be passed in the EnvironmentFile directive of container runtime systemd unit file. that will set the STORAGE_OPTIONS environment variable which in turn can be parsed by container runtime process. slay. 🧚

to cleanup storage configuration, execute the remove command:

container-storage-setup remove example-config

lvm2 version should be same or higher than lvm2-2.02.112 for lvm thin pool functionality to work properly. no old lvm2 energy allowed. 🙅

🍓 Supported options for the configuration file 🍓

  • STORAGE_DRIVER — Specify a storage driver to be used with container runtime. Default: "devicemapper". Valid values are overlay, overlay2 and "". an empty "" tells container-storage-setup to not perform any storage setup. (it's the "we're good, don't touch anything" option 😌)
  • CONTAINER_THINPOOL — Specify the thinpool name for the lvm thinpool. this is required when using the devicemapper STORAGE_DRIVER. CONTAINER_THINPOOL is the logical volume name passed to lvcreate 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). it's a whole chain of "if this then that," iykyk. 🫠
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. it's giving "self-care for your thin pool." 🧖
  • 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 lvconvert --chunk-size.
  • 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. (patience: configurable 🕰️)
  • 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. like, gone gone. be so serious before you set this one, bestie.
  • 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. they're a package deal. 💞
  • 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: CONTAINER_ROOT_LV_MOUNT_PATH=/var/lib/containers/container-runtime 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. pick a lane. 🚧
  • 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 lvcreate -L as well as some values acceptable to lvcreate -l. if user intends to pass values acceptable to lvcreate -l, then only those values which contains % in syntax are acceptable. if value does not contain % it is assumed value is suitable for lvcreate -L.

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). math is mathing. 🧮
Note: DOCKER_ROOT_VOLUME_SIZE is deprecated. Specifying DOCKER_ROOT_VOLUME_SIZE and CONTAINER_ROOT_LV_SIZE at the same time is not allowed.

Options below should be specified as values acceptable to lvextend -L.

  • ROOT_SIZE — The size to which the root filesystem should be grown.

ROOT_SIZE can take values acceptable to lvcreate -L as well as some values acceptable to lvcreate -l. if user intends to pass values acceptable to lvcreate -l, then only those values which contains % in syntax are acceptable. if value does not contain % it is assumed value is suitable for lvcreate -L.

  • 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 lvcreate -L as well as some values acceptable to lvcreate -l. if user intends to pass values acceptable to lvcreate -l, then only those values which contains % in syntax are acceptable. if value does not contain % it is assumed value is suitable for lvcreate -L.

  • 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.

🌈 Sample 🌈

a simple, sample INPUTFILE:

DEVS=/dev/vdb

DATA_SIZE=8GB

👑 SEE ALSO 👑

  • atomic(1)

📜 HISTORY 📜

November 2014, originally compiled by Joe Brockmeier <jzb@redhat.com> based on comments in Andy Grimm's <agrimm@redhat.com> script. February 2017, Modified by Dan Walsh <dwalsh@redhat.com>. a whole lineage, we respect the elders. 🫡

🫶 AUTHORS 🫶

Joe Brockmeier Andy Grimm Dan Walsh

and that's the whole page, bestie!! 💖 this was Helper Script for Container S..., FEBRUARY 2017, from the CONTAINER-STORAGE-SETUP(1) manual — go forth and configure your storage, you absolute icon. ✨💅🎀

📦 where this page comes from