1VDO(8) System Manager's Manual VDO(8)
2
6 vdo - manage kernel VDO devices and related configuration information
7
9 vdo { activate | changeWritePolicy | create | deactivate |
10 disableCompression | disableDeduplication | enableCompression |
11 enableDeduplication | growLogical | growPhysical | list | modify
12 | printConfigFile | remove | start | status | stop } [ options...
13 ]
14
16 The commands available are:
17 activate
19 Activates one or more VDO volumes. Activated volumes can be
20 started using the start command. This command must be run with
21 root privileges. Applicable options include:
22 { --all | --name=volume } (required)
23 --confFile=file
24 --logfile=file
25 --verbose
26 changeWritePolicy
28 Modifies the write policy of one or all running VDO volumes.
29 This command must be run with root privileges. Applicable
30 options include:
31 { --all | --name=volume } (required)
32 --writePolicy={ sync | async | auto } (required)
33 --confFile=file
34 --logfile=file
35 --verbose
36 create Creates a VDO volume and its associated index and makes it
38 available. If --activate=disabled is specified the VDO volume is
39 created but not made available.
40 If the specified device is already in use by a VDO volume (as
42 determined from the configuration file) the create will always
43 be rejected, even if --force is specified. If the device is not
44 so in use but is formatted as a VDO volume or contains an exist‐
45 ing file system the create will be rejected unless --force is
46 given.
47 This command must be run with root privileges.
49 Applicable options include:
51 --name=volume (required)
52 --device=device (required)
53 --activate={ enabled | disabled }
54 --blockMapCacheSize=size
55 --blockMapPeriod=period
56 --compression={ enabled | disabled }
57 --deduplication={ enabled | disabled }
58 --emulate512={ enabled | disabled }
59 --indexMem=size
60 --maxDiscardSize=size
61 --sparseIndex={ enabled | disabled }
62 --vdoAckThreads=thread count
63 --vdoBioRotationInterval=I/O count
64 --vdoBioThreads=thread count
65 --vdoCpuThreads=thread count
66 --vdoHashZoneThreads=thread count
67 --vdoLogicalThreads=thread count
68 --vdoLogLevel=level
69 --vdoLogicalSize=size
70 --vdoPhysicalThreads=thread count
71 --vdoSlabSize=size
72 --writePolicy={ sync | async | auto }
73 --confFile=file
74 --logfile=file
75 --verbose
76 deactivate
78 Deactivates one or more VDO volumes. Deactivated volumes cannot
79 be started by the start command. Deactivating a currently run‐
80 ning volume does not stop it. Once stopped a deactivated VDO
81 volume must be activated before it can be started again. This
82 command must be run with root privileges. Applicable options
83 include:
84 { --all | --name=volume } (required)
85 --confFile=file
86 --logfile=file
87 --verbose
88 disableCompression
90 Disables compression on one or more VDO volumes. If the VDO vol‐
91 ume is running, takes effect immediately. If the VDO volume is
92 not running compression will be disabled the next time the VDO
93 volume is started. This command must be run with root privi‐
94 leges. Applicable options include:
95 { --all | --name=volume } (required)
96 --confFile=file
97 --logfile=file
98 --verbose
99 disableDeduplication
101 Disables deduplication on one or more VDO volumes. If the VDO
102 volume is running, takes effect immediately. If the VDO volume
103 is not running deduplication will be disabled the next time the
104 VDO volume is started. This command must be run with root privi‐
105 leges. Applicable options include:
106 { --all | --name=volume } (required)
107 --confFile=file
108 --logfile=file
109 --verbose
110 enableCompression
112 Enables compression on one or more VDO volumes. If the VDO vol‐
113 ume is running, takes effect immediately. If the VDO volume is
114 not running compression will be enabled the next time the VDO
115 volume is started. This command must be run with root privi‐
116 leges. Applicable options include:
117 { --all | --name=volume } (required)
118 --confFile=file
119 --logfile=file
120 --verbose
121 enableDeduplication
123 Enables deduplication on one or more VDO volumes. If the VDO
124 volume is running, takes effect immediately. If the VDO volume
125 is not running deduplication will be enabled the next time the
126 VDO volume is started. This command must be run with root privi‐
127 leges. Applicable options include:
128 { --all | --name=volume } (required)
129 --confFile=file
130 --logfile=file
131 --verbose
132 growLogical
134 Grows the logical size of a VDO volume. The volume must exist
135 and must be running. This command must be run with root privi‐
136 leges. Applicable options include:
137 --name=volume (required)
138 --vdoLogicalSize=size (required)
139 --confFile=file
140 --logfile=file
141 --verbose
142 growPhysical
144 Grows the physical size of a VDO volume. The volume must exist
145 and must be running. This command must be run with root privi‐
146 leges. Applicable options include:
147 --name=volume (required)
148 --confFile=file
149 --verbose
150 --logfile=file
151 list Displays a list of started VDO volumes. If --all is specified it
153 displays both started and non-started volumes. This command must
154 be run with root privileges. Applicable options include:
155 --all
156 --confFile=file
157 --logfile=file
158 --verbose
159 modify Modifies configuration parameters of one or all VDO volumes.
161 Changes take effect the next time the VDO device is started;
162 already-running devices are not affected. Applicable options
163 include:
164 { --all | --name=volume } (required)
165 --blockMapCacheSize=size
166 --blockMapPeriod=period
167 --maxDiscardSize=size
168 --vdoAckThreads=thread count
169 --vdoBioThreads=thread count
170 --vdoCpuThreads=thread count
171 --vdoHashZoneThreads=thread count
172 --vdoLogicalThreads=thread count
173 --vdoPhysicalThreads=thread count
174 --confFile=file
175 --logfile=file
176 --verbose
177 printConfigFile
179 Prints the configuration file to stdout. This command does not
180 require root privileges. Applicable options include:
181 --confFile=file
182 --logfile=file
183 --verbose
184 remove Removes one or more stopped VDO volumes and associated indexes.
186 This command must be run with root privileges. Applicable
187 options include:
188 { --all | --name=volume } (required)
189 --force
190 --confFile=file
191 --logfile=file
192 --verbose
193 start Starts one or more stopped, activated VDO volumes and associated
195 services. This command must be run with root privileges. Appli‐
196 cable options include:
197 { --all | --name=volume } (required)
198 --forceRebuild
199 --confFile=file
200 --logfile=file
201 --verbose
202 status Reports VDO system and volume status in YAML format. This com‐
204 mand does not require root privileges though information will be
205 incomplete if run without. Applicable options include:
206 { --all | --name=volume }
207 --confFile=file
208 --logfile=file
209 --verbose
210 See below for the output provided.
211 stop Stops one or more running VDO volumes and associated services.
213 This command must be run with root privileges. Applicable
214 options include:
215 { --all | --name=volume } (required)
216 --force
217 --confFile=file
218 --logfile=file
219 --verbose
220 The status command returns the following information in YAML format,
222 divided into keys as follows:
223 VDO Status
225 Information in this key covers the name of the host and date and
226 time at which the status inquiry is being made. Parameters
227 reported in this area include:
228 Node The host name of the system on which VDO is running.
230 Date The date and time at which the vdo status command is run.
232 Kernel Module
234 Information in this key covers the configured kernel.
235 Loaded Whether or not the kernel module is loaded (True or
237 False).
238 Version Information
240 Information on the version of kvdo that is configured.
241 Configuration
243 Information in this key covers the location and status of the
244 VDO configuration file.
245 File Location of the VDO configuration file.
247 Last modified
249 The last-modified date of the VDO configuration file.
250 VDOs Provides configuration information for all VDO volumes. Parame‐
252 ters reported for each VDO volume include:
253 Block size
255 The block size of the VDO volume, in bytes.
256 Emulate 512 byte
258 Indicates whether the volume is running in 512-byte emu‐
259 lation mode.
260 Deduplication
262 Whether deduplication is enabled for the volume.
263 Logical size
265 The logical size of the VDO volume.
266 Physical size
268 The size of a VDO volume's underlying physical storage.
269 Configured write policy
271 The configured value of the write policy (sync, async or
272 auto).
273 VDO Statistics
275 Output of the vdostats utility.
276
278 The options supported by some or all of the commands listed above
279 include:
280 --activate={ enabled | disabled }
282 Indicates if the VDO volume should, in addition to being cre‐
283 ated, be activated and started. The default is enabled.
284 --all
286 -a
287 Indicates that the command should be applied to all configured
288 VDO volumes. May not be used with --name.
289 --blockMapCacheSize=megabytes
291 Specifies the amount of memory allocated for caching block map
292 pages; the value must be a multiple of 4096. Using a value with
293 a B (bytes), K (kilobytes), M (megabytes), G (gigabytes), T
294 (terabytes), P (petabytes) or E (exabytes) suffix is optional.
295 If no suffix is supplied, the value will be interpreted as
296 megabytes. The value must be at least 128M and less than 16T.
297 The cache must be at least 16MB per logical thread. Note that
298 there is a memory overhead of 15%. The default is 128M.
299 --blockMapPeriod=period
301 Tunes the quantity of block map updates that can accumulate
302 before cache pages are flushed to disk. The value must at least
303 1 and less than or equal to 16380. A lower value means shorter
304 recovery time but lower performance. The default value is 16380.
305 --compression={ enabled | disabled }
307 Enables or disables compression when creating a VDO volume. The
308 default is enabled. Compression may be disabled if necessary to
309 maximize performance or to speed processing of data that is
310 unlikely to compress.
311 --confFile=file
313 -ffile
314 Specifies an alternate configuration file; the default is
315 /etc/vdoconf.yml.
316 --deduplication={ enabled | disabled }
318 Enables or disables deduplication when creating a VDO volume.
319 The default is enabled. Deduplication may be disabled in
320 instances where data is not expected to have good deduplication
321 rates but compression is still desired.
322 --device=absolute_path
324 Specifies an absolute path of the device to use for VDO storage.
325 This might not be the path that gets used to access the storage
326 device by future command invocations; see the DEVICE NAMES sec‐
327 tion below.
328 --emulate512={ enabled | disabled }
330 Specifies that the VDO volume is to emulate a 512 byte block
331 device. The default is disabled.
332 --force
334 When creating a volume, ignores any existing file system or VDO
335 signature already present in the storage device. When stopping
336 or removing a VDO volume, first unmounts the file system stored
337 on the device if mounted.
338 --forceRebuild
340 Forces an offline rebuild of a read-only VDO's metadata before
341 starting so that it may be brought back online and made avail‐
342 able. This option may result in data loss or corruption.
343 --indexMem=gigabytes
345 Specifies the amount of index memory in gigabytes; the default
346 is currently 0.25 GB. The special decimal values 0.25, 0.5, 0.75
347 can be used, as can any integer value at least 1 and less than
348 or equal to 1024. (The special decimal values are matched as
349 exact strings; "0.5" works but "0.50" is not accepted.)
350 Larger values will require more disk space. For a dense index,
352 each gigabyte of index memory will use approximately 11 GB of
353 storage. For a sparse index, each gigabyte of index memory will
354 use approximately 100 GB of storage.
355 --help
357 -h
358 If specified with vdo only, displays documentation for the vdo
359 utility. If specified with a command, displays documentation
360 for that command.
361 --logfile=pathname
363 Specify the path of the file to which log messages are directed.
364 If unspecified, log messages will go to syslog. Warning and
365 error messages are always logged to syslog.
366 --name=volume
368 -nvolume
369 Operates on the specified VDO volume. May not be used with
370 --all.
371 --maxDiscardSize=megabytes
373 Specifies the maximum discard size VDO can receive. This is used
374 for performance tuning and support of devices above us. The
375 value must be a multiple of 4K. Using a value with a S (sec‐
376 tors), B (bytes), K (kilobytes), M (megabytes), G (gigabytes), T
377 (terabytes), P (petabytes) or E (exabytes) suffix is optional.
378 If no suffix is supplied, the value will be interpreted as
379 megabytes. The value must be at least 4K and less than 4G. The
380 default is 4K.
381 --sparseIndex={ enabled | disabled }
383 Enables sparse indexing. The default is disabled.
384 --vdoAckThreads=thread count
386 Specifies the number of threads to use for acknowledging comple‐
387 tion of requested VDO I/O operations. The value must be at least
388 0 and less than or equal to 100. The default is 1.
389 --vdoBioRotationInterval=I/O count
391 Specifies the number of I/O operations to enqueue for each bio-
392 submission thread before directing work to the next. The value
393 must be at least 1 and less than or equal to 1024. The default
394 is 64.
395 --vdoBioThreads=thread count
397 Specifies the number of threads to use for submitting I/O opera‐
398 tions to the storage device. The value must be at least 1 and
399 less than or equal to 100. Each additional thread after the
400 first will use an additional 18 MB of RAM, The default is 4.
401 --vdoCpuThreads=thread count
403 Specifies the number of threads to use for CPU-intensive work
404 such as hashing or compression. The value must be at least 1 and
405 less than or equal to 100. The default is 2.
406 --vdoHashZoneThreads=thread count
408 Specifies the number of threads across which to subdivide parts
409 of the VDO processing based on the hash value computed from the
410 block data. The value must be at least 0 and less than or equal
411 to 100. vdoHashZonesThreads, vdoLogicalThreads and vdoPhysi‐
412 calThreads must be either all zero or all non-zero. The default
413 is 1.
414 --vdoLogicalThreads=thread count
416 Specifies the number of threads across which to subdivide parts
417 of the VDO processing based on the hash value computed from the
418 block data. The value must be at least 0 and less than or equal
419 to 60. A logical thread count of 9 or more will require explic‐
420 itly specifying a sufficiently large block map cache size, as
421 well. vdoHashZonesThreads, vdoLogicalThreads and vdoPhysi‐
422 calThreads must be either all zero or all non-zero. The default
423 is 1.
424 --vdoLogicalSize=megabytes
426 Specifies the logical VDO volume size in megabytes. Using a
427 value with a S (sectors), B (bytes), K (kilobytes), M
428 (megabytes), G (gigabytes), T (terabytes), P (petabytes) or E
429 (exabytes) suffix is optional. Used for over-provisioning vol‐
430 umes. The maximum size supported is 4P. The default is the size
431 of the storage device.
432 --vdoLogLevel=level
434 Specifies the VDO driver log level: critical, error, warning,
435 notice, info, or debug. Levels are case sensitive; the default
436 is info.
437 --vdoPhysicalThreads=thread count
439 Specifies the number of threads across which to subdivide parts
440 of the VDO processing based on physical block addresses. The
441 value must be at least 0 and less than or equal to 16. Each
442 additional thread after the first will use an additional 10 MB
443 of RAM. vdoPhysicalThreads, vdoHashZonesThreads and vdoLogi‐
444 calThreads must be either all zero or all non-zero. The default
445 is 1.
446 --vdoSlabSize=megabytes
448 Specifies the size of the increment by which a VDO is grown.
449 Using a smaller size constrains the total maximum physical size
450 that can be accommodated. Must be a power of two between 128M
451 and 32G. Using a value with a S (sectors), B (bytes), K (kilo‐
452 bytes), M (megabytes), G (gigabytes), T (terabytes), P
453 (petabytes) or E (exabytes) suffix is optional. If no suffix is
454 used, the value will be interpreted as megabytes. The default is
455 2G.
456 --verbose
458 Prints commands before executing them.
459 --writePolicy={ sync | async | auto }
461 Specifies the write policy:
462 sync Writes are acknowledged only after data is stably writ‐
464 ten. This policy is not supported if the underlying stor‐
465 age is not also synchronous.
466 async Writes are acknowledged after data has been cached for
468 writing to stable storage. Data which has not been
469 flushed is not guaranteed to persist in this mode.
470 auto VDO will check the storage device and determine whether
472 it supports flushes. If it does, VDO will run in async
473 mode, otherwise it will run in sync mode. This is the
474 default.
475
477 Device recognition order can change at boot time, and devices can be
478 added to or removed from a system, both possibly affecting device nam‐
479 ing at boot time, so a device recognized as /dev/sda at one time may be
480 /dev/sdb after a reboot.
481 In the directory /dev/disk/by-id, udev normally creates symbolic links
483 after booting when devices are identified, and are named based on
484 device serial numbers, UUIDs, WWNs, etc., so they should be more stable
485 names across reboots for referring to the device in question.
486 When a VDO device is created, vdo will look for links in /dev/disk/by-
488 id that refer to the same block device as the one supplied on the com‐
489 mand line, and if some are found, use one of those instead. This name
490 will be written into the config file for future use. If no such links
491 are found, the device name as supplied is used.
492 This may cause problems if a VDO storage volume needs to be copied from
494 a failing device to a replacement, or from a small device to a larger
495 one to allow for expansion. In cases like these, the config file may
496 need to be edited to refer to the new device; there is currently no
497 automated way to make this change with the administrative tools. (If a
498 logical volume is used as the VDO storage volume, VDO will find the
499 storage via the volume's UUID; the standard LVM tools can be used to
500 manage the migration or growth of the volume.)
501 If a multipath device is used, udev should be configured to either not
503 create any /dev/disk/by-id symbolic links for any of the devices used,
504 or to only create a link for the multipath device itself.
505
507 /etc/vdoconf.yml
508 The default configuration file; used if the --confFile option is
509 not provided.
510
512 Creation of a VDO device named vdo0, with a 10 terabyte thinly-provi‐
513 sioned logical address size:
514 # vdo create --name=vdo0 --device=/dev/sdb1 --vdoLogicalSize=10T
516 Creating VDO vdo0
517 Starting VDO vdo0
518 Starting compression on VDO vdo0
519 VDO instance 1 volume is ready at /dev/mapper/vdo0
520 #
521 Of course, as with any thinly-provisioned device, it may not hold 10
523 terabytes of user data even after deduplication and compression unless
524 the underlying storage has sufficient space available for the resulting
525 compressed, unique data blocks plus metadata overhead.
526
528 The following are exit statuses that may be encountered during normal
529 operation. Any other exit status is an abnormal occurrence.
530 0 Success.
532 1 Non-specific failure.
534 2 Pre-processing argument parsing failure.
536 3 Non-specific processing failure.
538 5 Incorrect state for requested action; e.g., attempting to per‐
540 form a growPhysical on a stopped vdo.
541 6 A requested operation from the system failed; e.g., error from
543 dmsetup(8).
544 7 User error; e.g., attempting to create a vdo with the same name
546 as one already existing.
547
549 udev(7), vdostats(8).
550Red Hat 2018-07-19 VDO(8)