vdo.8

.TH VDO 8 "2018-07-19" "Red Hat" \" -*- nroff -*-
.\"
.\" Copyright (c) 2020 Red Hat, Inc.
.\"
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License
.\" as published by the Free Software Foundation; either version 2
.\" of the License, or (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
.\" 02110-1301, USA. 
.\"
.\" $Id: //eng/vdo-releases/aluminum/src/python/vdo/man/vdo.8#20 $
.
.\" Constants (as strings, for ease of use and consistency)
.ds ackThreadsDefault 1
.ds ackThreadsMin 0
.ds ackThreadsMax 100
.ds bioRotationDefault 64
.ds bioRotationMin 1
.ds bioRotationMax 1024
.ds bioThreadOverheadMB 18
.ds bioThreadsDefault 4
.ds bioThreadsMin 1
.ds bioThreadsMax 100
.ds blockMapCacheSizeDefault 128M
.ds blockMapCacheSizeMin 128M
.ds blockMapCacheSizeMaxPlusOne 16T
.ds blockMapPeriodDefault 16380
.ds blockMapPeriodMin 1
.ds blockMapPeriodMax 16380
.ds compressionDefault enabled
.ds confFileDefault /etc/vdoconf.yml
.ds cpuThreadsDefault 2
.ds cpuThreadsMin 1
.ds cpuThreadsMax 100
.ds deduplicationDefault enabled
.ds emulate512Default disabled
.ds hashZoneThreadsDefault 1
.ds hashZoneThreadsMin 0
.ds hashZoneThreadsMax 100
.ds indexMemDefault 0.25
.ds indexMemIntMin 1
.ds indexMemIntMax 1024
.ds logicalSizeMax 4P
.ds logicalThreadsBlockMapCacheSizeThreshold 9
.ds logicalThreadsDefault 1
.ds logicalThreadsMin 0
.ds logicalThreadsMax 60
.ds logLevelChoices \fBcritical\fP, \fBerror\fP, \
\fBwarning\fP, \fBnotice\fP, \fBinfo\fP, or \fBdebug\fP
.ds logLevelDefault \fBinfo\fP
.ds lvmOptionalSiSuffix Using a value with a \fBB\fP (bytes), \
\fBK\fP (kilobytes), \fBM\fP (megabytes), \fBG\fP (gigabytes), \fBT\fP \
(terabytes), \fBP\fP (petabytes) or \fBE\fP (exabytes) suffix is optional
.ds lvmOptionalSuffix Using a value with a \fBS\fP (sectors), \
\fBB\fP (bytes), \fBK\fP (kilobytes), \fBM\fP (megabytes), \
\fBG\fP (gigabytes), \fBT\fP (terabytes), \fBP\fP (petabytes) or \
\fBE\fP (exabytes) suffix is optional
.ds lvmUnitsDefault megabytes
.ds maxDiscardSize 4K
.ds maxDiscardSizeMin 4K
.ds maxDiscardSizeMaxPlusOne 4G
.ds pageSizeDefault 4096
.ds physicalThreadOverheadMB 10
.ds physicalThreadsDefault 1
.ds physicalThreadsMin 0
.ds physicalThreadsMax 16
.ds slabSizeDefault 2G
.ds slabSizeMin 128M
.ds slabSizeMax 32G
.ds sparseIndexDefault disabled
.ds uuidDefault ""

.
.\" Formatting for per-command option lists: indented, no filling
.nr optionListIndent 15
.de startOptionList
.  RS \n[optionListIndent]
.  nf
.  ft B
..
.de endOptionList
.  fi
.  RE
.  ft R
..
.\" Value string for options. Show the possible values, properly
.\" italicized, but restore the original font when we're done.
.ds bool \fR{ \fP\fI enabled \fP\fR | \fP\fI disabled \fP\fR } \fP
.ds targetSpec \fR{ \fP\-\-all\fP | \fP\-\-name=\fIvolume\fP\fR }\fP
.ds targetSpecRequired \*[targetSpec]\fR (required)\fP
.
.\" Save the default hyphenation mode, so we can suspend (.nh) and
 \" resume.
.nr defaultHyphenationMode \n[.hy]
.de hyResume
.  hy \n[defaultHyphenationMode]
..
.
.SH NAME
vdo \- manage kernel VDO devices and related configuration information
.
.SH SYNOPSIS
.nh
.in +6
.ti -6
.B vdo
.RI
{
.B activate
|
.B changeWritePolicy
|
.B create
|
.B deactivate
|
.B disableCompression
|
.B disableDeduplication
|
.B enableCompression
|
.B enableDeduplication
|
.B growLogical
|
.B growPhysical
|
.B import
|
.B list
|
.B modify
|
.B printConfigFile
|
.B remove
|
.B start
|
.B status
|
.B stop
|
.B version
}
[ options... ]
.in -6
.RE
.SH DESCRIPTION
.hyResume
The commands available are:
.TP
.B activate
Activates one or more VDO volumes. Activated volumes can be started
using the \fBstart\fR command. This command must be run with root
privileges. Applicable options include:
.startOptionList
\*[targetSpecRequired]
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B changeWritePolicy
Modifies the write policy of one or all running VDO
volumes. This command must be run with root privileges.
Applicable options include:
.startOptionList
\*[targetSpecRequired]
\-\-writePolicy=\fIpolicy\fP\fR (required)\fP
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B create
Creates a VDO volume and its associated index and makes it available. If
\fB\-\-activate=disabled\fP 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
\fB\-\-force\fP 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 \fB\-\-force\fP is given.

This command must be run with root privileges.

Applicable options include:
.startOptionList
\-\-name=\fIvolume\fP\fR (required)\fP
\-\-device=\fIdevice\fP\fR (required)\fP
\-\-activate=\*[bool]
\-\-blockMapCacheSize=\fIsize\fP
\-\-blockMapPeriod=\fIperiod\fP
\-\-compression=\*[bool]
\-\-deduplication=\*[bool]
\-\-emulate512=\*[bool]
\-\-indexMem=\fIsize\fP
\-\-maxDiscardSize=\fIsize\fP
\-\-sparseIndex=\*[bool]
\-\-uuid=\fIuuid\fP
\-\-vdoAckThreads=\fIthread count\fP
\-\-vdoBioRotationInterval=\fII/O count\fP
\-\-vdoBioThreads=\fIthread count\fP
\-\-vdoCpuThreads=\fIthread count\fP
\-\-vdoHashZoneThreads=\fIthread count\fP
\-\-vdoLogicalThreads=\fIthread count\fP
\-\-vdoLogLevel=\fIlevel\fP
\-\-vdoLogicalSize=\fIsize\fP
\-\-vdoPhysicalThreads=\fIthread count\fP
\-\-vdoSlabSize=\fIsize\fP
\-\-writePolicy=\fIpolicy\fP
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.
.TP
.B deactivate
Deactivates one or more VDO volumes. Deactivated volumes cannot be started by
the \fBstart\fR 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:
.startOptionList
\*[targetSpecRequired]
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B 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:
.startOptionList
\*[targetSpecRequired]
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B 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:
.startOptionList
\*[targetSpecRequired]
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B 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:
.startOptionList
\*[targetSpecRequired]
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B 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:
.startOptionList
\*[targetSpecRequired]
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B 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:
.startOptionList
\-\-name=\fIvolume\fP\fR (required)\fP
\-\-vdoLogicalSize=\fIsize\fP\fR (required)\fP
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B 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:
.startOptionList
\-\-name=\fIvolume\fP\fR (required)\fP
\-\-confFile=\fIfile\fP
\-\-verbose
\-\-logfile=\fIfile\fP
.endOptionList
.TP
.B import
Creates a VDO volume from an existing VDO formatted storage
device by importing it into VDO manager for use.

If \fB\-\-activate=disabled\fP is specified the VDO volume is
imported but not made available. This command must be run with
root privileges. Applicaable options include:
.startOptionList
\-\-name=\fIvolume\fP\fR (required)\fP
\-\-device=\fIdevice\fP\fR (required)\fP
\-\-activate=\*[bool]
\-\-blockMapCacheSize=\fIsize\fP
\-\-blockMapPeriod=\fIperiod\fP
\-\-compression=\*[bool]
\-\-deduplication=\*[bool]
\-\-emulate512=\*[bool]
\-\-maxDiscardSize=\fIsize\fP
\-\-uuid=\fIuuid\fP
\-\-vdoAckThreads=\fIthread count\fP
\-\-vdoBioRotationInterval=\fII/O count\fP
\-\-vdoBioThreads=\fIthread count\fP
\-\-vdoCpuThreads=\fIthread count\fP
\-\-vdoHashZoneThreads=\fIthread count\fP
\-\-vdoLogicalThreads=\fIthread count\fP
\-\-vdoLogLevel=\fIlevel\fP
\-\-vdoPhysicalThreads=\fIthread count\fP
\-\-writePolicy=\fIpolicy\fP
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B list
Displays a list of started VDO volumes. If \fB\-\-all\fP is specified it
displays both started and non-started volumes. This command must be run with
root privileges. Applicable options include:
.startOptionList
\-\-all
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B 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:
.startOptionList
\*[targetSpecRequired]
\-\-blockMapCacheSize=\fIsize\fP
\-\-blockMapPeriod=\fIperiod\fP
\-\-maxDiscardSize=\fIsize\fP
\-\-uuid=\fIuuid\fP
\-\-vdoAckThreads=\fIthread count\fP
\-\-vdoBioThreads=\fIthread count\fP
\-\-vdoCpuThreads=\fIthread count\fP
\-\-vdoHashZoneThreads=\fIthread count\fP
\-\-vdoLogicalThreads=\fIthread count\fP
\-\-vdoPhysicalThreads=\fIthread count\fP
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B printConfigFile
Prints the configuration file to stdout. This command does not require root
privileges. Applicable options include:
.startOptionList
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B remove
Removes one or more stopped VDO volumes and associated
indexes. This command must be run with root privileges.
Applicable options include:
.startOptionList
\*[targetSpecRequired]
\-\-force
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B start
Starts one or more stopped, activated VDO volumes and associated services. This
command must be run with root privileges. Applicable options include:
.startOptionList
\*[targetSpecRequired]
\-\-forceRebuild
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B 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:
.startOptionList
\*[targetSpec]
\-\-pending
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.RS
See below for the output provided.
.RE
.TP
.B stop
Stops one or more running VDO volumes and associated services. This command
must be run with root privileges. Applicable options include:
.startOptionList
\*[targetSpecRequired]
\-\-force
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.TP
.B version
Displays the version of the VDO manager. This command does not require root
privileges. Applicable options include:
.startOptionList
\-\-confFile=\fIfile\fP
\-\-logfile=\fIfile\fP
\-\-verbose
.endOptionList
.
.PP
The \fBstatus\fP command returns the following information in YAML
format, divided into keys as follows:
.
.
.TP
.B 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:
.RS
.TP
.B Node
The host name of the system on which VDO is running.
.TP
.B Date
The date and time at which the vdo status command is run.
.RE
.TP
.B Kernel Module
Information in this key covers the configured kernel.
.RS
.TP
.B Loaded
Whether or not the kernel module is loaded (True or False).
.TP
.B Version Information
Information on the version of kvdo that is configured.
.RE
.TP
.B Configuration
Information in this key covers the location and status of the VDO
configuration file.
.RS
.TP
.B File
Location of the VDO configuration file.
.TP
.B Last modified
The last-modified date of the VDO configuration file.
.RE
.TP
.B VDOs
Provides configuration information for all VDO volumes.
Parameters reported for each VDO volume include:
.RS
.TP
.B Block size
The block size of the VDO volume, in bytes.
.TP
.B Emulate 512 byte
Indicates whether the volume is running in 512-byte emulation
mode.
.TP
.B Deduplication
Whether deduplication is enabled for the volume.
.TP
.B Logical size
The logical size of the VDO volume.
.TP
.B Physical size
The size of a VDO volume's underlying physical storage.
.TP
.B Configured write policy
The configured value of the write policy (sync, async, async-unsafe or auto).
.TP
.B VDO Statistics
Output of the \fBvdostats\fP utility.
.RE
.
.
.SH OPTIONS
The options supported by some or all of the commands listed above
include:
.TP
.B \-\-activate=\*[bool]
Indicates if the VDO volume should, in addition to being created, be
activated and started. The default is \fBenabled\fP.
.PP
.B \-\-all
.br
.B \-a
.br
.RS
Indicates that the command should be applied to all configured
VDO volumes. May not be used with \fB\-\-name\fP.
.RE
.TP
.B \-\-blockMapCacheSize=\fImegabytes\fR
Specifies the amount of memory allocated for caching block map pages; the
value must be a multiple of \*[pageSizeDefault].  \*[lvmOptionalSiSuffix]. If
no suffix is supplied, the value will be interpreted as
\fB\*[lvmUnitsDefault]\fP. The value must be at least
\*[blockMapCacheSizeMin] and less than \*[blockMapCacheSizeMaxPlusOne]. The
cache must be at least 16MB per logical thread. Note that there is a memory
overhead of 15%. The default is \*[blockMapCacheSizeDefault].
.TP
.B \-\-blockMapPeriod=\fIperiod\fR
Tunes the quantity of block map updates that can accumulate before cache
pages are flushed to disk. The value must at least \*[blockMapPeriodMin] and
less than or equal to \*[blockMapPeriodMax]. A lower value means shorter
recovery time but lower performance. The default value is
\*[blockMapPeriodDefault].
.TP
.B \-\-compression=\*[bool]
Enables or disables compression when creating a VDO volume. The default is
\*[compressionDefault]. Compression may be disabled if necessary to maximize
performance or to speed processing of data that is unlikely to compress.
.PP
.B \-\-confFile=\fIfile\fR
.br
.B \-f\fIfile\fR
.br
.RS
Specifies an alternate configuration file; the default is
\f[CR]\*[confFileDefault]\fP.
.RE
.TP
.B \-\-deduplication=\*[bool]
Enables or disables deduplication when creating a VDO volume. The default is
\*[deduplicationDefault]. Deduplication may be disabled in instances where
data is not expected to have good deduplication rates but compression is
still desired.
.TP
.B \-\-device=\fIabsolute_path\fR
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 \fBDEVICE NAMES\fP section
below.
.TP
.B \-\-emulate512=\*[bool]
Specifies that the VDO volume is to emulate a 512 byte block device. The
default is \*[emulate512Default].
.TP
.B \-\-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.
.TP
.B \-\-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. \fBThis option may
result in data loss or corruption.\fP
.TP
.B \-\-indexMem=\fIgigabytes\fR
Specifies the amount of index memory in gigabytes; the default is
currently \*[indexMemDefault] GB. The special decimal values 0.25, 0.5,
0.75 can be used, as can any integer value at least \*[indexMemIntMin] and less
than or equal to \*[indexMemIntMax]. (The special decimal values are matched as
exact strings; "0.5" works but "0.50" is not accepted.)
.IP
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.
.PP
.B \-\-help
.br
.B \-h
.br
.RS
If specified with \fBvdo\fP only, displays documentation for the \fBvdo\fP utility.
If specified with a command, displays documentation for that command.
.RE
.TP
.B \-\-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.
.PP
.B \-\-name=\fIvolume\fR
.br
.B \-n\fIvolume\fR
.br
.RS
Operates on the specified VDO volume. May not be used with
\fB\-\-all\fP.
.RE
.TP
.B \-\-maxDiscardSize=\fImegabytes\fR
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 \*[maxDiscardSize]. \*[lvmOptionalSuffix]. If no suffix
is supplied, the value will be interpreted as \*[lvmUnitsDefault].
The value must be at least \*[maxDiscardSizeMin] and less than
\*[maxDiscardSizeMaxPlusOne]. The default is \*[maxDiscardSize].
.TP
.B \-\-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.
.TP
.B \-\-sparseIndex=\*[bool]
Enables sparse indexing. The default is \*[sparseIndexDefault].
.TP
.B \-\-uuid=\fIuuid\fR
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.
The default is \*[uuidDefault]..
.TP
.B \-\-vdoAckThreads=\fIthread count\fR
Specifies the number of threads to use for acknowledging completion of
requested VDO I/O operations. The value must be at least \*[ackThreadsMin]
and less than or equal to \*[ackThreadsMax]. The default is
\*[ackThreadsDefault].
.TP
.B \-\-vdoBioRotationInterval=\fII/O count\fR
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
\*[bioRotationMin] and less than or equal to \*[bioRotationMax]. The default
is \*[bioRotationDefault].
.TP
.B \-\-vdoBioThreads=\fIthread count\fR
Specifies the number of threads to use for submitting I/O operations to the
storage device. The value must be at least \*[bioThreadsMin] and less than or
equal to \*[bioThreadsMax]. Each additional thread after the first will use
an additional \*[bioThreadOverheadMB] MB of RAM, The default is
\*[bioThreadsDefault].
.TP
.B \-\-vdoCpuThreads=\fIthread count\fR
Specifies the number of threads to use for CPU-intensive work such as hashing
or compression. The value must be at least \*[cpuThreadsMin] and less than or
equal to \*[cpuThreadsMax]. The default is \*[cpuThreadsDefault].
.TP
.B \-\-vdoHashZoneThreads=\fIthread count\fR
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 \*[hashZoneThreadsMin] and less than or equal to
\*[hashZoneThreadsMax]. vdoHashZonesThreads, vdoLogicalThreads and
vdoPhysicalThreads must be either all zero or all non-zero. The default is
\*[hashZoneThreadsDefault].
.TP
.B \-\-vdoLogicalThreads=\fIthread count\fR
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
\*[logicalThreadsMin] and less than or equal to \*[logicalThreadsMax].
A logical thread count of \*[logicalThreadsBlockMapCacheSizeThreshold] 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 \*[logicalThreadsDefault].
.TP
.B \-\-vdoLogicalSize=\fImegabytes\fR
Specifies the logical VDO volume size in \*[lvmUnitsDefault].
\*[lvmOptionalSuffix]. Used for over-provisioning volumes. The maximum size
supported is \*[logicalSizeMax]. The default is the size of the storage
device.
.TP
.B \-\-vdoLogLevel=\fIlevel\fR
Specifies the VDO driver log level: \*[logLevelChoices]. Levels are
case sensitive; the default is \*[logLevelDefault].
.TP
.B \-\-vdoPhysicalThreads=\fIthread count\fR
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 \*[physicalThreadsMin] and less than or equal to
\*[physicalThreadsMax]. The value must also be less than or equal to
the slab count (which can be found via the \fBstatus\fR command after
device creation). Each additional thread after the first will use an
additional \*[physicalThreadOverheadMB] MB of RAM. vdoPhysicalThreads,
vdoHashZonesThreads and vdoLogicalThreads must be either all zero or
all non-zero. The default is \*[physicalThreadsDefault].
.TP
.B \-\-vdoSlabSize=\fImegabytes\fR
Set the free space allocator's slab size. Must be a power of two between
\*[slabSizeMin] and \*[slabSizeMax] (inclusive). \*[lvmOptionalSuffix].
If no suffix is used, the value will be interpreted as \*[lvmUnitsDefault].
The default is \*[slabSizeDefault]. 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.

.TP
.B \-\-verbose
Prints commands before executing them.
.TP
.B \-\-writePolicy=\fIpolicy\fR
Specifies the write policy:
.RS
.TP
.B sync
Writes are acknowledged only after the data is guaranteed to persist.
.TP
.B async
Writes are acknowledged when the data has been cached for writing to the
underlying storage. Data which has not been flushed is not guaranteed
to persist in this mode, however this mode is ACID compliant (after
recovery from a crash any unflushed write is guaranteed either to have
persisted all its data, or to have done nothing). Most databases and
filesystems should use this mode.
.TP
.B async-unsafe
Writes are handled like 'async' but there is no guarantee of the atomicity
async provides. This mode should only be used for better performance when
atomicity is not required.
.TP
.B auto
VDO will check the storage device and determine whether it supports
flushes. If it does, VDO will run in async mode, otherwise it will run
in sync mode. This is the default.
.RE
.
.
.SH 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.
.PP
In the directory /dev/disk/by-id, \fBudev\fP 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.
.PP
When a VDO device is created, \fBvdo\fP 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.
.PP
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.)
.PP
If a multipath device is used, \fBudev\fP 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.
.
.
.SH 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.
.PP
There are two ways to mount filesystems automatically during system
startup: adding a line to \fB/etc/fstab\fP, or adding a mount unit
to systemd (on systemd-based systems).

For \fB/etc/fstab\fP mounting, in order to make sure the mount waits
for the VDO to start, use the mount option
\fBx-systemd.requires=vdo.service\fP
For example, an \fB/etc/fstab\fP line involving VDO could be the following:
.PP
.nf
.nh
/dev/mapper/vdo0 /vdo xfs defaults,x-systemd.requires=vdo.service 0 0
.fi
.hyResume
.PP
To add a mount unit, modify the example from \fB/usr/share/doc/vdo/examples\fP
to match your mount point and configuration, and add it to
/etc/systemd/system.
.PP
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.
.PP
You may need to add dependencies to the VDO service, by adding a symlink to
the required service into the appropriate \fBvdo.service.requires\fP
directory. For instance, you may need to create an 
\fB/etc/systemd/system/vdo.service.requires/\fP directory and symlink
\fBiscsi.service\fP into it, in order to make the VDO service wait for the
iscsi service to have started. More information can be found in 
\fBsystemd.unit(5)\fP about setting up dependencies in this way.
.
.
.
.SH FILES
.TP
.ft CR
\*[confFileDefault]
The default configuration file; used if the \fB\-\-confFile\fP option
is not provided.
.SH EXAMPLES
Creation of a VDO device named \fBvdo0\fP, with a 10 terabyte
thinly-provisioned logical address size:
.PP
.nf
.nh
# \fBvdo create --name=vdo0 --device=/dev/sdb1 --vdoLogicalSize=10T\fP
Creating VDO vdo0
Starting VDO vdo0
Starting compression on VDO vdo0
VDO instance 1 volume is ready at /dev/mapper/vdo0
#
.fi
.hyResume
.PP
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.
.
.SH EXIT STATUS
The following are exit statuses that may be encountered during normal
operation.  Any other exit status is an abnormal occurrence.
.IP 0
Success.
.IP 1
Non-specific failure.
.IP 2
Pre-processing argument parsing failure.
.IP 3
Non-specific processing failure.
.IP 5
Incorrect state for requested action; e.g., attempting to perform a
growPhysical on a stopped vdo.
.IP 6
A requested operation from the system failed; e.g., error from dmsetup(8).
.IP 7
User error; e.g., attempting to create a vdo with the same name as one already
existing.
.
.\" .SH NOTES
.
.SH SEE ALSO
.BR udev (7),
.BR vdostats (8).