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