NAME¶

vdo - manage kernel VDO devices and related configuration information

SYNOPSIS¶

vdo { activate | changeWritePolicy | convert | create | deactivate | disableCompression | disableDeduplication | enableCompression | enableDeduplication | growLogical | growPhysical | import | list | modify | printConfigFile | remove | start | status | stop | version } [ options... ]

DESCRIPTION¶

The commands available are:

activate

Activates one or more VDO volumes. Activated volumes can be started using the start command. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--confFile=file
--logfile=file
--verbose

changeWritePolicy

Modifies the write policy of one or all running VDO volumes. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--writePolicy=policy (required)
--confFile=file
--logfile=file
--verbose

convert

Converts a VDO volume so it can be managed by LVM. Converted volumes cannot be reverted back. This command is intended to be used by LVM. Do not call this directly unless you are sure what you are doing. This command must be run with root privileges. Applicable options include:

--name=volume (required)
--force (required)
--confFile=file
--logfile=file
--verbose

create

Creates a VDO volume and its associated index and makes it available. If --activate=disabled is specified the VDO volume is created but not made available.

If the specified device is already in use by a VDO volume (as determined from the configuration file) the create will always be rejected, even if --force is specified. If the device is not so in use but is formatted as a VDO volume or contains an existing file system the create will be rejected unless --force is given.

This command must be run with root privileges.

Applicable options include:

--name=volume (required)
--device=device (required)
--activate={  enabled  |  disabled  } 
--blockMapCacheSize=size
--blockMapPeriod=period
--compression={  enabled  |  disabled  } 
--deduplication={  enabled  |  disabled  } 
--emulate512={  enabled  |  disabled  } 
--indexMem=size
--maxDiscardSize=size
--sparseIndex={  enabled  |  disabled  } 
--uuid=uuid
--vdoAckThreads=thread count
--vdoBioRotationInterval=I/O count
--vdoBioThreads=thread count
--vdoCpuThreads=thread count
--vdoHashZoneThreads=thread count
--vdoLogicalThreads=thread count
--vdoLogLevel=level
--vdoLogicalSize=size
--vdoPhysicalThreads=thread count
--vdoSlabSize=size
--writePolicy=policy
--confFile=file
--logfile=file
--verbose

deactivate

Deactivates one or more VDO volumes. Deactivated volumes cannot be started by the start command. Deactivating a currently running volume does not stop it. Once stopped a deactivated VDO volume must be activated before it can be started again. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--confFile=file
--logfile=file
--verbose

disableCompression

Disables compression on one or more VDO volumes. If the VDO volume is running, takes effect immediately. If the VDO volume is not running compression will be disabled the next time the VDO volume is started. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--confFile=file
--logfile=file
--verbose

disableDeduplication

Disables deduplication on one or more VDO volumes. If the VDO volume is running, takes effect immediately. If the VDO volume is not running deduplication will be disabled the next time the VDO volume is started. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--confFile=file
--logfile=file
--verbose

enableCompression

Enables compression on one or more VDO volumes. If the VDO volume is running, takes effect immediately. If the VDO volume is not running compression will be enabled the next time the VDO volume is started. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--confFile=file
--logfile=file
--verbose

enableDeduplication

Enables deduplication on one or more VDO volumes. If the VDO volume is running, takes effect immediately. If the VDO volume is not running deduplication will be enabled the next time the VDO volume is started. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--confFile=file
--logfile=file
--verbose

growLogical

Grows the logical size of a VDO volume. The volume must exist and must be running. This command must be run with root privileges. Applicable options include:

--name=volume (required)
--vdoLogicalSize=size (required)
--confFile=file
--logfile=file
--verbose

growPhysical

Grows the physical size of a VDO volume. The volume must exist and must be running. This command must be run with root privileges. Applicable options include:

--name=volume (required)
--confFile=file
--verbose
--logfile=file

import

Creates a VDO volume from an existing VDO formatted storage device by importing it into VDO manager for use.

NOTE: The following values are not stored on the device and must be reset via command line parameters if you changed them from the default value during create: block map cache size, block map period, compression state, deduplication state, 512 emulation, maximum discard size, and thread configurations. If --activate=disabled is specified the VDO volume is imported but not made available. This command must be run with root privileges. Applicable options include:

--name=volume (required)
--device=device (required)
--activate={  enabled  |  disabled  } 
--blockMapCacheSize=size
--blockMapPeriod=period
--compression={  enabled  |  disabled  } 
--deduplication={  enabled  |  disabled  } 
--emulate512={  enabled  |  disabled  } 
--maxDiscardSize=size
--uuid=uuid
--vdoAckThreads=thread count
--vdoBioRotationInterval=I/O count
--vdoBioThreads=thread count
--vdoCpuThreads=thread count
--vdoHashZoneThreads=thread count
--vdoLogicalThreads=thread count
--vdoLogLevel=level
--vdoPhysicalThreads=thread count
--writePolicy=policy
--confFile=file
--logfile=file
--verbose

list

Displays a list of started VDO volumes. If --all is specified it displays both started and non-started volumes. This command must be run with root privileges. Applicable options include:

--all
--confFile=file
--logfile=file
--verbose

modify

Modifies configuration parameters of one or all VDO volumes. Changes take effect the next time the VDO device is started; already-running devices are not affected. Applicable options include:

{ --all | --name=volume } (required)
--blockMapCacheSize=size
--blockMapPeriod=period
--maxDiscardSize=size
--uuid=uuid
--vdoAckThreads=thread count
--vdoBioThreads=thread count
--vdoCpuThreads=thread count
--vdoHashZoneThreads=thread count
--vdoLogicalThreads=thread count
--vdoPhysicalThreads=thread count
--confFile=file
--logfile=file
--verbose

printConfigFile

Prints the configuration file to stdout. This command does not require root privileges. Applicable options include:

--confFile=file
--logfile=file
--verbose

remove

Removes one or more stopped VDO volumes and associated indexes. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--force
--confFile=file
--logfile=file
--verbose

start

Starts one or more stopped, activated VDO volumes and associated services. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--forceRebuild
--confFile=file
--logfile=file
--verbose

status

Reports VDO system and volume status in YAML format. This command does not require root privileges though information will be incomplete if run without. Applicable options include:

{ --all | --name=volume }
--pending
--confFile=file
--logfile=file
--verbose

stop

Stops one or more running VDO volumes and associated services. This command must be run with root privileges. Applicable options include:

{ --all | --name=volume } (required)
--force
--confFile=file
--logfile=file
--verbose

version

Displays the version of the VDO manager. This command does not require root privileges. Applicable options include:

--confFile=file
--logfile=file
--verbose

The status command returns the following information in YAML format, divided into keys as follows:

VDO Status

Information in this key covers the name of the host and date and time at which the status inquiry is being made. Parameters reported in this area include:

Kernel Module

Information in this key covers the configured kernel.

Configuration

Information in this key covers the location and status of the VDO configuration file.

VDOs

Provides configuration information for all VDO volumes. Parameters reported for each VDO volume include:

OPTIONS¶

The options supported by some or all of the commands listed above include:

--activate={ enabled | disabled }

Indicates if the VDO volume should, in addition to being created, be activated and started. The default is enabled.

--all
-a

--blockMapCacheSize=megabytes

Specifies the amount of memory allocated for caching block map pages; the value must be a multiple of 4096. Using a value with a B (bytes), K (kilobytes), M (megabytes), G (gigabytes), T (terabytes), P (petabytes) or E (exabytes) suffix is optional. If no suffix is supplied, the value will be interpreted as megabytes. The value must be at least 128M and less than 16T. The cache must be at least 16MB per logical thread. Note that there is a memory overhead of 15%. The default is 128M.

--blockMapPeriod=period

Tunes the quantity of block map updates that can accumulate before cache pages are flushed to disk. The value must at least 1 and less than or equal to 16380. A lower value means shorter recovery time but lower performance. The default value is 16380.

--compression={ enabled | disabled }

Enables or disables compression when creating a VDO volume. The default is enabled. Compression may be disabled if necessary to maximize performance or to speed processing of data that is unlikely to compress.

--confFile=file
-ffile

--deduplication={ enabled | disabled }

Enables or disables deduplication when creating a VDO volume. The default is enabled. Deduplication may be disabled in instances where data is not expected to have good deduplication rates but compression is still desired.

--device=absolute_path

Specifies an absolute path of the device to use for VDO storage. This might not be the path that gets used to access the storage device by future command invocations; see the DEVICE NAMES section below.

--emulate512={ enabled | disabled }

Specifies that the VDO volume is to emulate a 512 byte block device. The default is disabled.

--force

When creating a volume, ignores any existing file system or VDO signature already present in the storage device. When stopping or removing a VDO volume, first unmounts the file system stored on the device if mounted. When converting a volume to be used by LVM, this parameter is required.

--forceRebuild

Forces an offline rebuild of a read-only VDO's metadata before starting so that it may be brought back online and made available. This option may result in data loss or corruption.

--indexMem=gigabytes

Specifies the amount of index memory in gigabytes; the default is currently 0.25 GB. The special decimal values 0.25, 0.5, 0.75 can be used, as can any integer value at least 1 and less than or equal to 1024. (The special decimal values are matched as exact strings; "0.5" works but "0.50" is not accepted.)

Larger values will require more disk space. For a dense index, each gigabyte of index memory will use approximately 11 GB of storage. For a sparse index, each gigabyte of index memory will use approximately 100 GB of storage.

--help
-h

--logfile=pathname

Specify the path of the file to which log messages are directed. If unspecified, log messages will go to syslog. Warning and error messages are always logged to syslog.

--name=volume
-nvolume

--maxDiscardSize=megabytes

Specifies the maximum discard size VDO can receive. This is used for performance tuning and support of devices above us. The value must be a multiple of 4K. Using a value with a S (sectors), B (bytes), K (kilobytes), M (megabytes), G (gigabytes), T (terabytes), P (petabytes) or E (exabytes) suffix is optional. If no suffix is supplied, the value will be interpreted as megabytes. The value must be at least 4K and less than 4G. The default is 4K.

--pending

Shows pending modifications that will take effect upon restart in the status report of a running VDO volume. Pending modifications are denoted with square brackets.

--sparseIndex={ enabled | disabled }

Enables sparse indexing. The default is disabled.

--uuid=uuid

Sets the UUID of the VDO volume. The value needs to be either a valid uuid or an empty string. If an empty string is specified, a new random uuid is generated for the VDO volume. For newly created volumes, the default is an empty string (generate a new uuid). For importing existing volumes, the default is the existing VDO volume's uuid.

--vdoAckThreads=thread count

Specifies the number of threads to use for acknowledging completion of requested VDO I/O operations. The value must be at least 0 and less than or equal to 100. The default is 1.

--vdoBioRotationInterval=I/O count

Specifies the number of I/O operations to enqueue for each bio-submission thread before directing work to the next. The value must be at least 1 and less than or equal to 1024. The default is 64.

--vdoBioThreads=thread count

Specifies the number of threads to use for submitting I/O operations to the storage device. The value must be at least 1 and less than or equal to 100. Each additional thread after the first will use an additional 18 MB of RAM, The default is 4.

--vdoCpuThreads=thread count

Specifies the number of threads to use for CPU-intensive work such as hashing or compression. The value must be at least 1 and less than or equal to 100. The default is 2.

--vdoHashZoneThreads=thread count

Specifies the number of threads across which to subdivide parts of the VDO processing based on the hash value computed from the block data. The value must be at least 0 and less than or equal to 100. vdoHashZonesThreads, vdoLogicalThreads and vdoPhysicalThreads must be either all zero or all non-zero. The default is 1.

--vdoLogicalThreads=thread count

Specifies the number of threads across which to subdivide parts of the VDO processing based on the logical address. The value must be at least 0 and less than or equal to 60. A logical thread count of 9 or more will require explicitly specifying a sufficiently large block map cache size. vdoHashZonesThreads, vdoLogicalThreads and vdoPhysicalThreads must be either all zero or all non-zero. The default is 1.

--vdoLogicalSize=megabytes

Specifies the logical VDO volume size in megabytes. Using a value with a S (sectors), B (bytes), K (kilobytes), M (megabytes), G (gigabytes), T (terabytes), P (petabytes) or E (exabytes) suffix is optional. Used for over-provisioning volumes. The maximum size supported is 4P. The default is the size of the storage device.

--vdoLogLevel=level

Specifies the VDO driver log level: critical, error, warning, notice, info, or debug. Levels are case sensitive; the default is info.

--vdoPhysicalThreads=thread count

Specifies the number of threads across which to subdivide parts of the VDO processing based on physical block addresses. The value must be at least 0 and less than or equal to 16. The value must also be less than or equal to the slab count (which can be found via the status command after device creation). Each additional thread after the first will use an additional 10 MB of RAM. vdoPhysicalThreads, vdoHashZonesThreads and vdoLogicalThreads must be either all zero or all non-zero. The default is 1.

--vdoSlabSize=megabytes

Set the free space allocator's slab size. Must be a power of two between 128M and 32G (inclusive). Using a value with a S (sectors), B (bytes), K (kilobytes), M (megabytes), G (gigabytes), T (terabytes), P (petabytes) or E (exabytes) suffix is optional. If no suffix is used, the value will be interpreted as megabytes. The default is 2G. This allocator manages the space VDO uses to store user data.

The maximum number of slabs in the system is 8192, so this value determines the maximum physical size of a VDO volume. One slab is the minimum amount by which a VDO volume can be grown. Smaller slabs also increase the potential for parallelism if the device has multiple physical threads. Therefore, this value should be set as small as possible, given the eventual maximal size of the volume.

--verbose

Prints commands before executing them.

--writePolicy=policy

Specifies the write policy:

DEVICE NAMES¶

Device recognition order can change at boot time, and devices can be added to or removed from a system, both possibly affecting device naming at boot time, so a device recognized as /dev/sda at one time may be /dev/sdb after a reboot.

In the directory /dev/disk/by-id, udev normally creates symbolic links after booting when devices are identified, and are named based on device serial numbers, UUIDs, WWNs, etc., so they should be more stable names across reboots for referring to the device in question.

When a VDO device is created, vdo will look for links in /dev/disk/by-id that refer to the same block device as the one supplied on the command line, and if some are found, use one of those instead. This name will be written into the config file for future use. If no such links are found, the device name as supplied is used.

This may cause problems if a VDO storage device needs to be copied from a failing device to a replacement, or from a small device to a larger one to allow for expansion. In cases like these, you can use the import command to create a new VDO volume from the copied storage device. (If a logical volume is used as the VDO storage volume, VDO will find the storage via the volume's UUID; the standard LVM tools can be used to manage the migration or growth of the volume.)

If a multipath device is used, udev should be configured to either not create any /dev/disk/by-id symbolic links for any of the devices used, or to only create a link for the multipath device itself.

AUTOMATIC MOUNTING¶

Mounting a filesystem atop a VDO at boot time is usually easy, but does require some care to ensure VDO is started before the mount is attempted.

There are two ways to mount filesystems automatically during system startup: adding a line to /etc/fstab, or adding a mount unit to systemd (on systemd-based systems).

For /etc/fstab mounting, in order to make sure the mount waits for the VDO to start, use the mount option x-systemd.requires=vdo.service For example, an /etc/fstab line involving VDO could be the following:

/dev/mapper/vdo0 /vdo xfs defaults,x-systemd.requires=vdo.service 0 0

To add a mount unit, modify the example from /usr/share/doc/vdo/examples to match your mount point and configuration, and add it to /etc/systemd/system.

Complications may arise if you have VDO layered atop other software defined devices, e.g. VDO atop LVM, VDO atop ISCSI, or VDO both above and below a single type of software defined device.

You may need to add dependencies to the VDO service, by adding a symlink to the required service into the appropriate vdo.service.requires directory. For instance, you may need to create an /etc/systemd/system/vdo.service.requires/ directory and symlink iscsi.service into it, in order to make the VDO service wait for the iscsi service to have started. More information can be found in systemd.unit(5) about setting up dependencies in this way.

FILES¶

/etc/vdoconf.yml

The default configuration file; used if the --confFile option is not provided.

EXAMPLES¶

Creation of a VDO device named vdo0, with a 10 terabyte thinly-provisioned logical address size:

# vdo create --name=vdo0 --device=/dev/sdb1 --vdoLogicalSize=10T
Creating VDO vdo0
Starting VDO vdo0
Starting compression on VDO vdo0
VDO instance 1 volume is ready at /dev/mapper/vdo0
#

Of course, as with any thinly-provisioned device, it may not hold 10 terabytes of user data even after deduplication and compression unless the underlying storage has sufficient space available for the resulting compressed, unique data blocks plus metadata overhead.

EXIT STATUS¶

The following are exit statuses that may be encountered during normal operation. Any other exit status is an abnormal occurrence.

0

Success.

1

Non-specific failure.

2

Pre-processing argument parsing failure.

3

Non-specific processing failure.

5

Incorrect state for requested action; e.g., attempting to perform a growPhysical on a stopped vdo.

6

A requested operation from the system failed; e.g., error from dmsetup(8).

7

User error; e.g., attempting to create a vdo with the same name as one already existing.

SEE ALSO¶

udev(7), vdostats(8).