1LVCONVERT(8) System Manager's Manual LVCONVERT(8)
2
6 lvconvert — Change logical volume layout
7
9 lvconvert option_args position_args
10 [ option_args ]
11 [ position_args ]
12 --alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit
14 -b|--background
15 -H|--cache
16 --cachedevice PV
17 --cachemetadataformat auto|1|2
18 --cachemode writethrough|writeback|passthrough
19 --cachepolicy String
20 --cachepool LV
21 --cachesettings String
22 --cachesize Size[m|UNIT]
23 --cachevol LV
24 -c|--chunksize Size[k|UNIT]
25 --commandprofile String
26 --compression y|n
27 --config String
28 -d|--debug
29 --deduplication y|n
30 --devices PV
31 --devicesfile String
32 --discards passdown|nopassdown|ignore
33 --driverloaded y|n
34 --errorwhenfull y|n
35 -f|--force
36 -h|--help
37 -i|--interval Number
38 --journal String
39 --lockopt String
40 --longhelp
41 --merge
42 --mergemirrors
43 --mergesnapshot
44 --mergethin
45 --metadataprofile String
46 --mirrorlog core|disk
47 -m|--mirrors [+|-]Number
48 -n|--name String
49 --nohints
50 --nolocking
51 --noudevsync
52 --originname LV
53 --poolmetadata LV
54 --poolmetadatasize Size[m|UNIT]
55 --poolmetadataspare y|n
56 --profile String
57 -q|--quiet
58 --raidintegrity y|n
59 --raidintegrityblocksize Number
60 --raidintegritymode String
61 -r|--readahead auto|none|Number
62 -R|--regionsize Size[m|UNIT]
63 --repair
64 --replace PV
65 -k|--setactivationskip y|n
66 -s|--snapshot
67 --splitcache
68 --splitmirrors Number
69 --splitsnapshot
70 --startpoll
71 --stripes Number
72 -I|--stripesize Size[k|UNIT]
73 --swapmetadata
74 -t|--test
75 -T|--thin
76 --thinpool LV
77 --trackchanges
78 --type linear|striped|snapshot|raid|mirror|thin|thin-pool|vdo|
79 vdo-pool|cache|cache-pool|writecache
80 --uncache
81 --usepolicies
82 --vdopool LV
83 --vdosettings String
84 -v|--verbose
85 --version
86 -V|--virtualsize Size[m|UNIT]
87 -y|--yes
88 -Z|--zero y|n
89
91 lvconvert changes the LV type and includes utilities for LV data main‐
92 tenance. The LV type controls data layout and redundancy. The LV type
93 is also called the segment type or segtype.
94 To display the current LV type, run the command:
96 lvs -o name,segtype LV
98 In some cases, an LV is a single device mapper (dm) layer above physi‐
100 cal devices. In other cases, hidden LVs (dm devices) are layered be‐
101 tween the visible LV and physical devices. LVs in the middle layers
102 are called sub LVs. A command run on a visible LV sometimes operates
103 on a sub LV rather than the specified LV. In other cases, a sub LV
104 must be specified directly on the command line.
105 Sub LVs can be displayed with the command:
107 lvs -a
109 The linear type is equivalent to the striped type when one stripe ex‐
111 ists. In that case, the types can sometimes be used interchangeably.
112 In most cases, the mirror type is deprecated and the raid1 type should
114 be used. They are both implementations of mirroring.
115 Striped raid types are raid0/raid0_meta, raid5 (an alias for raid5_ls),
117 raid6 (an alias for raid6_zr) and raid10 (an alias for raid10_near).
118 As opposed to mirroring, raid5 and raid6 stripe data and calculate par‐
120 ity blocks. The parity blocks can be used for data block recovery in
121 case devices fail. A maximum number of one device in a raid5 LV may
122 fail, and two in case of raid6. Striped raid types typically rotate the
123 parity and data blocks for performance reasons, thus avoiding con‐
124 tention on a single device. Specific arrangements of parity and data
125 blocks (layouts) can be used to optimize I/O performance, or to convert
126 between raid levels. See lvmraid(7) for more information.
127 Layouts of raid5 rotating parity blocks can be: left-asymmetric
129 (raid5_la), left-symmetric (raid5_ls with alias raid5), right-asymmet‐
130 ric (raid5_ra), right-symmetric (raid5_rs) and raid5_n, which doesn't
131 rotate parity blocks. Layouts of raid6 are: zero-restart (raid6_zr with
132 alias raid6), next-restart (raid6_nr), and next-continue (raid6_nc).
133 Layouts including _n allow for conversion between raid levels (raid5_n
135 to raid6 or raid5_n to striped/raid0/raid0_meta). Additionally, special
136 raid6 layouts for raid level conversions between raid5 and raid6 are:
137 raid6_ls_6, raid6_rs_6, raid6_la_6 and raid6_ra_6. Those correspond to
138 their raid5 counterparts (e.g. raid5_rs can be directly converted to
139 raid6_rs_6 and vice-versa).
140 raid10 (an alias for raid10_near) is currently limited to one data copy
142 and even number of sub LVs. This is a mirror group layout, thus a sin‐
143 gle sub LV may fail per mirror group without data loss.
144 Striped raid types support converting the layout, their stripesize and
146 their number of stripes.
147 The striped raid types combined with raid1 allow for conversion from
149 linear → striped/raid0/raid0_meta and vice-versa by e.g. linear ↔ raid1
150 ↔ raid5_n (then adding stripes) ↔ striped/raid0/raid0_meta.
151
153 Convert LV to linear.
154 lvconvert --type linear LV
156 [ COMMON_OPTIONS ]
157 [ PV ... ]
158 —
160 Convert LV to striped.
162 lvconvert --type striped LV
164 [ -I|--stripesize Size[k|UNIT] ]
165 [ -R|--regionsize Size[m|UNIT] ]
166 [ -i|--interval Number ]
167 [ --stripes Number ]
168 [ COMMON_OPTIONS ]
169 [ PV ... ]
170 —
172 Convert LV to type mirror (also see type raid1),
174 lvconvert --type mirror LV
176 [ -m|--mirrors [+|-]Number ]
177 [ -I|--stripesize Size[k|UNIT] ]
178 [ -R|--regionsize Size[m|UNIT] ]
179 [ -i|--interval Number ]
180 [ --stripes Number ]
181 [ --mirrorlog core|disk ]
182 [ COMMON_OPTIONS ]
183 [ PV ... ]
184 —
186 Convert LV to raid or change raid layout
188 (a specific raid level must be used, e.g. raid1).
189 lvconvert --type raid LV
191 [ -m|--mirrors [+|-]Number ]
192 [ -I|--stripesize Size[k|UNIT] ]
193 [ -R|--regionsize Size[m|UNIT] ]
194 [ -i|--interval Number ]
195 [ --stripes Number ]
196 [ COMMON_OPTIONS ]
197 [ PV ... ]
198 —
200 Convert LV to raid1 or mirror, or change number of mirror images.
202 lvconvert -m|--mirrors [+|-]Number LV
204 [ -R|--regionsize Size[m|UNIT] ]
205 [ -i|--interval Number ]
206 [ --mirrorlog core|disk ]
207 [ COMMON_OPTIONS ]
208 [ PV ... ]
209 —
211 Convert raid LV to change number of stripe images.
213 lvconvert --stripes Number LV1
215 [ -i|--interval Number ]
216 [ -R|--regionsize Size[m|UNIT] ]
217 [ -I|--stripesize Size[k|UNIT] ]
218 [ COMMON_OPTIONS ]
219 [ PV ... ]
220 LV1 types: raid
222 —
224 Convert raid LV to change the stripe size.
226 lvconvert -I|--stripesize Size[k|UNIT] LV1
228 [ -i|--interval Number ]
229 [ -R|--regionsize Size[m|UNIT] ]
230 [ COMMON_OPTIONS ]
231 LV1 types: raid
233 —
235 Split images from a raid1 or mirror LV and use them to create a new LV.
237 lvconvert --splitmirrors Number -n|--name LV_new LV1
239 [ COMMON_OPTIONS ]
240 [ PV ... ]
241 LV1 types: cache mirror raid1
243 —
245 Split images from a raid1 LV and track changes to origin for later
247 merge.
248 lvconvert --splitmirrors Number --trackchanges LV1
250 [ COMMON_OPTIONS ]
251 [ PV ... ]
252 LV1 types: cache raid1
254 —
256 Merge LV images that were split from a raid1 LV.
258 lvconvert --mergemirrors VG|LV1|Tag ...
260 [ COMMON_OPTIONS ]
261 LV1 types: linear raid
263 —
265 Convert LV to a thin LV, using the original LV as an external origin.
267 lvconvert --type thin --thinpool LV LV1
269 [ -T|--thin ]
270 [ -r|--readahead auto|none|Number ]
271 [ -c|--chunksize Size[k|UNIT] ]
272 [ -Z|--zero y|n ]
273 [ --originname LV_new ]
274 [ --poolmetadata LV ]
275 [ --poolmetadatasize Size[m|UNIT] ]
276 [ --poolmetadataspare y|n ]
277 [ --metadataprofile String ]
278 [ COMMON_OPTIONS ]
279 LV1 types: linear striped thin cache raid error zero
281 —
283 Convert LV to a thin LV, using LV as thin-pool data volume.
285 lvconvert --type thin LV1
287 [ -T|--thin ]
288 [ -r|--readahead auto|none|Number ]
289 [ -c|--chunksize Size[k|UNIT] ]
290 [ -Z|--zero y|n ]
291 [ --poolmetadata LV ]
292 [ --poolmetadatasize Size[m|UNIT] ]
293 [ --poolmetadataspare y|n ]
294 [ --metadataprofile String ]
295 [ COMMON_OPTIONS ]
296 LV1 types: linear striped cache vdo raid error zero writecache
298 —
300 Attach a cache pool to an LV, converts the LV to type cache.
302 lvconvert --type cache --cachepool LV LV1
304 [ -H|--cache ]
305 [ -Z|--zero y|n ]
306 [ -r|--readahead auto|none|Number ]
307 [ -c|--chunksize Size[k|UNIT] ]
308 [ --cachemetadataformat auto|1|2 ]
309 [ --cachemode writethrough|writeback|passthrough ]
310 [ --cachepolicy String ]
311 [ --cachesettings String ]
312 [ --poolmetadata LV ]
313 [ --poolmetadatasize Size[m|UNIT] ]
314 [ --poolmetadataspare y|n ]
315 [ --metadataprofile String ]
316 [ COMMON_OPTIONS ]
317 LV1 types: linear striped thin thinpool vdo vdopool vdopooldata
319 raid error zero
320 —
322 Attach a writecache to an LV, converts the LV to type writecache.
324 lvconvert --type writecache --cachevol LV LV1
326 [ --cachesettings String ]
327 [ COMMON_OPTIONS ]
328 LV1 types: linear striped thinpool raid
330 —
332 Attach a cache to an LV, converts the LV to type cache.
334 lvconvert --type cache --cachevol LV LV1
336 [ -H|--cache ]
337 [ -Z|--zero y|n ]
338 [ -c|--chunksize Size[k|UNIT] ]
339 [ --cachemetadataformat auto|1|2 ]
340 [ --cachemode writethrough|writeback|passthrough ]
341 [ --cachepolicy String ]
342 [ --cachesettings String ]
343 [ --poolmetadatasize Size[m|UNIT] ]
344 [ COMMON_OPTIONS ]
345 LV1 types: linear striped thinpool raid
347 —
349 Add a writecache to an LV, using a specified cache device.
351 lvconvert --type writecache --cachedevice PV LV1
353 [ --cachesize Size[m|UNIT] ]
354 [ --cachesettings String ]
355 [ COMMON_OPTIONS ]
356 LV1 types: linear striped thinpool raid
358 —
360 Add a cache to an LV, using a specified cache device.
362 lvconvert --type cache --cachedevice PV LV1
364 [ -c|--chunksize Size[k|UNIT] ]
365 [ --cachesize Size[m|UNIT] ]
366 [ --cachesettings String ]
367 [ COMMON_OPTIONS ]
368 LV1 types: linear striped thinpool raid
370 —
372 Convert LV to type thin-pool.
374 lvconvert --type thin-pool LV1
376 [ -I|--stripesize Size[k|UNIT] ]
377 [ -r|--readahead auto|none|Number ]
378 [ -c|--chunksize Size[k|UNIT] ]
379 [ -Z|--zero y|n ]
380 [ --stripes Number ]
381 [ --discards passdown|nopassdown|ignore ]
382 [ --errorwhenfull y|n ]
383 [ --poolmetadata LV ]
384 [ --poolmetadatasize Size[m|UNIT] ]
385 [ --poolmetadataspare y|n ]
386 [ --metadataprofile String ]
387 [ COMMON_OPTIONS ]
388 [ PV ... ]
389 LV1 types: linear striped cache raid error zero writecache
391 —
393 Convert LV to type cache-pool.
395 lvconvert --type cache-pool LV1
397 [ -Z|--zero y|n ]
398 [ -r|--readahead auto|none|Number ]
399 [ -c|--chunksize Size[k|UNIT] ]
400 [ --cachemetadataformat auto|1|2 ]
401 [ --cachemode writethrough|writeback|passthrough ]
402 [ --cachepolicy String ]
403 [ --cachesettings String ]
404 [ --poolmetadata LV ]
405 [ --poolmetadatasize Size[m|UNIT] ]
406 [ --poolmetadataspare y|n ]
407 [ --metadataprofile String ]
408 [ COMMON_OPTIONS ]
409 [ PV ... ]
410 LV1 types: linear striped raid error zero
412 —
414 Convert LV to type vdopool.
416 lvconvert --type vdo-pool LV1
418 [ -n|--name LV_new ]
419 [ -V|--virtualsize Size[m|UNIT] ]
420 [ -r|--readahead auto|none|Number ]
421 [ -Z|--zero y|n ]
422 [ --metadataprofile String ]
423 [ --compression y|n ]
424 [ --deduplication y|n ]
425 [ --vdosettings String ]
426 [ COMMON_OPTIONS ]
427 LV1 types: linear striped cache raid
429 —
431 Detach a cache from an LV.
433 lvconvert --splitcache LV1
435 [ --cachesettings String ]
436 [ COMMON_OPTIONS ]
437 LV1 types: thinpool cache cachepool vdopool writecache
439 —
441 Merge thin LV into its origin LV.
443 lvconvert --mergethin LV1 ...
445 [ COMMON_OPTIONS ]
446 LV1 types: thin
448 —
450 Merge COW snapshot LV into its origin.
452 lvconvert --mergesnapshot LV1 ...
454 [ -i|--interval Number ]
455 [ COMMON_OPTIONS ]
456 LV1 types: snapshot
458 —
460 Combine a former COW snapshot (second arg) with a former
462 origin LV (first arg) to reverse a splitsnapshot command.
463 lvconvert --type snapshot LV LV1
465 [ -s|--snapshot ]
466 [ -c|--chunksize Size[k|UNIT] ]
467 [ -Z|--zero y|n ]
468 [ COMMON_OPTIONS ]
469 LV1 types: linear striped
471 —
473 Replace failed PVs in a raid or mirror LV.
475 Repair a thin pool.
476 Repair a cache pool.
477 lvconvert --repair LV1
479 [ -i|--interval Number ]
480 [ -k|--setactivationskip y|n ]
481 [ --usepolicies ]
482 [ --poolmetadataspare y|n ]
483 [ COMMON_OPTIONS ]
484 [ PV ... ]
485 LV1 types: thinpool cache cachepool mirror raid
487 —
489 Replace specific PV(s) in a raid LV with another PV.
491 lvconvert --replace PV LV1
493 [ COMMON_OPTIONS ]
494 [ PV ... ]
495 LV1 types: raid
497 —
499 Poll LV to continue conversion.
501 lvconvert --startpoll LV1
503 [ COMMON_OPTIONS ]
504 LV1 types: mirror raid
506 —
508 Add or remove data integrity checksums to raid images.
510 lvconvert --raidintegrity y|n LV1
512 [ --raidintegritymode String ]
513 [ --raidintegrityblocksize Number ]
514 [ COMMON_OPTIONS ]
515 [ PV ... ]
516 LV1 types: raid
518 —
520 Common options for command:
522 [ -b|--background ]
523 [ -f|--force ]
524 [ --alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit
525 ]
526 [ --noudevsync ]
527 Common options for lvm:
529 [ -d|--debug ]
530 [ -h|--help ]
531 [ -q|--quiet ]
532 [ -t|--test ]
533 [ -v|--verbose ]
534 [ -y|--yes ]
535 [ --commandprofile String ]
536 [ --config String ]
537 [ --devices PV ]
538 [ --devicesfile String ]
539 [ --driverloaded y|n ]
540 [ --journal String ]
541 [ --lockopt String ]
542 [ --longhelp ]
543 [ --nohints ]
544 [ --nolocking ]
545 [ --profile String ]
546 [ --version ]
547
549 --alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit
550 Determines the allocation policy when a command needs to allo‐
551 cate Physical Extents (PEs) from the VG. Each VG and LV has an
552 allocation policy which can be changed with vgchange/lvchange,
553 or overridden on the command line. normal applies common sense
554 rules such as not placing parallel stripes on the same PV. in‐
555 herit applies the VG policy to an LV. contiguous requires new
556 PEs be placed adjacent to existing PEs. cling places new PEs on
557 the same PV as existing PEs in the same stripe of the LV. If
558 there are sufficient PEs for an allocation, but normal does not
559 use them, anywhere will use them even if it reduces performance,
560 e.g. by placing two stripes on the same PV. Optional positional
561 PV args on the command line can also be used to limit which PVs
562 the command will use for allocation. See lvm(8) for more infor‐
563 mation about allocation.
564 -b|--background
566 If the operation requires polling, this option causes the com‐
567 mand to return before the operation is complete, and polling is
568 done in the background.
569 -H|--cache
571 Specifies the command is handling a cache LV or cache pool. See
572 --type cache and --type cache-pool. See lvmcache(7) for more
573 information about LVM caching.
574 --cachedevice PV
576 The name of a device to use for a cache.
577 --cachemetadataformat auto|1|2
579 Specifies the cache metadata format used by cache target.
580 --cachemode writethrough|writeback|passthrough
582 Specifies when writes to a cache LV should be considered com‐
583 plete. writeback considers a write complete as soon as it is
584 stored in the cache pool. writethough considers a write com‐
585 plete only when it has been stored in both the cache pool and on
586 the origin LV. While writethrough may be slower for writes, it
587 is more resilient if something should happen to a device associ‐
588 ated with the cache pool LV. With passthrough, all reads are
589 served from the origin LV (all reads miss the cache) and all
590 writes are forwarded to the origin LV; additionally, write hits
591 cause cache block invalidates. See lvmcache(7) for more informa‐
592 tion.
593 --cachepolicy String
595 Specifies the cache policy for a cache LV. See lvmcache(7) for
596 more information.
597 --cachepool LV
599 The name of a cache pool.
600 --cachesettings String
602 Specifies tunable kernel options for dm-cache or dm-writecache
603 LVs. Use the form 'option=value' or 'option1=value option2=val‐
604 ue', or repeat --cachesettings for each option being set. These
605 settings override the default kernel behaviors which are usually
606 adequate. To remove cachesettings and revert to the default ker‐
607 nel behaviors, use --cachesettings 'default' for dm-cache or an
608 empty string --cachesettings '' for dm-writecache. See lvm‐
609 cache(7) for more information.
610 --cachesize Size[m|UNIT]
612 The size of cache to use.
613 --cachevol LV
615 The name of a cache volume.
616 -c|--chunksize Size[k|UNIT]
618 The size of chunks in a snapshot, cache pool or thin pool. For
619 snapshots, the value must be a power of 2 between 4 KiB and
620 512 KiB and the default value is 4. For a cache pool the value
621 must be between 32 KiB and 1 GiB and the default value is 64.
622 For a thin pool the value must be between 64 KiB and 1 GiB and
623 the default value starts with 64 and scales up to fit the pool
624 metadata size within 128 MiB, if the pool metadata size is not
625 specified. The value must be a multiple of 64 KiB. See
626 lvmthin(7) and lvmcache(7) for more information.
627 --commandprofile String
629 The command profile to use for command configuration. See
630 lvm.conf(5) for more information about profiles.
631 --compression y|n
633 Controls whether compression is enabled or disable for VDO vol‐
634 ume. See lvmvdo(7) for more information about VDO usage.
635 --config String
637 Config settings for the command. These override lvm.conf(5) set‐
638 tings. The String arg uses the same format as lvm.conf(5), or
639 may use section/field syntax. See lvm.conf(5) for more informa‐
640 tion about config.
641 -d|--debug ...
643 Set debug level. Repeat from 1 to 6 times to increase the detail
644 of messages sent to the log file and/or syslog (if configured).
645 --deduplication y|n
647 Controls whether deduplication is enabled or disable for VDO
648 volume. See lvmvdo(7) for more information about VDO usage.
649 --devices PV
651 Restricts the devices that are visible and accessible to the
652 command. Devices not listed will appear to be missing. This op‐
653 tion can be repeated, or accepts a comma separated list of de‐
654 vices. This overrides the devices file.
655 --devicesfile String
657 A file listing devices that LVM should use. The file must exist
658 in /etc/lvm/devices/ and is managed with the lvmdevices(8) com‐
659 mand. This overrides the lvm.conf(5) devices/devicesfile and
660 devices/use_devicesfile settings.
661 --discards passdown|nopassdown|ignore
663 Specifies how the device-mapper thin pool layer in the kernel
664 should handle discards. ignore causes the thin pool to ignore
665 discards. nopassdown causes the thin pool to process discards
666 itself to allow reuse of unneeded extents in the thin pool.
667 passdown causes the thin pool to process discards itself (like
668 nopassdown) and pass the discards to the underlying device. See
669 lvmthin(7) for more information.
670 --driverloaded y|n
672 If set to no, the command will not attempt to use device-mapper.
673 For testing and debugging.
674 --errorwhenfull y|n
676 Specifies thin pool behavior when data space is exhausted. When
677 yes, device-mapper will immediately return an error when a thin
678 pool is full and an I/O request requires space. When no, de‐
679 vice-mapper will queue these I/O requests for a period of time
680 to allow the thin pool to be extended. Errors are returned if
681 no space is available after the timeout. (Also see dm-thin-pool
682 kernel module option no_space_timeout.) See lvmthin(7) for more
683 information.
684 -f|--force ...
686 Override various checks, confirmations and protections. Use
687 with extreme caution.
688 -h|--help
690 Display help text.
691 -i|--interval Number
693 Report progress at regular intervals.
694 --journal String
696 Record information in the systemd journal. This information is
697 in addition to information enabled by the lvm.conf log/journal
698 setting. command: record information about the command. out‐
699 put: record the default command output. debug: record full com‐
700 mand debugging.
701 --lockopt String
703 Used to pass options for special cases to lvmlockd. See lvm‐
704 lockd(8) for more information.
705 --longhelp
707 Display long help text.
708 --merge
710 An alias for --mergethin, --mergemirrors, or --mergesnapshot,
711 depending on the type of LV.
712 --mergemirrors
714 Merge LV images that were split from a raid1 LV. See --split‐
715 mirrors with --trackchanges.
716 --mergesnapshot
718 Merge COW snapshot LV into its origin. When merging a snapshot,
719 if both the origin and snapshot LVs are not open, the merge will
720 start immediately. Otherwise, the merge will start the first
721 time either the origin or snapshot LV are activated and both are
722 closed. Merging a snapshot into an origin that cannot be closed,
723 for example a root filesystem, is deferred until the next time
724 the origin volume is activated. When merging starts, the result‐
725 ing LV will have the origin's name, minor number and UUID. While
726 the merge is in progress, reads or writes to the origin appear
727 as being directed to the snapshot being merged. When the merge
728 finishes, the merged snapshot is removed. Multiple snapshots
729 may be specified on the command line or a @tag may be used to
730 specify multiple snapshots be merged to their respective origin.
731 --mergethin
733 Merge thin LV into its origin LV. The origin thin LV takes the
734 content of the thin snapshot, and the thin snapshot LV is re‐
735 moved. See lvmthin(7) for more information.
736 --metadataprofile String
738 The metadata profile to use for command configuration. See
739 lvm.conf(5) for more information about profiles.
740 --mirrorlog core|disk
742 Specifies the type of mirror log for LVs with the "mirror" type
743 (does not apply to the "raid1" type.) disk is a persistent log
744 and requires a small amount of storage space, usually on a sepa‐
745 rate device from the data being mirrored. core is not persis‐
746 tent; the log is kept only in memory. In this case, the mirror
747 must be synchronized (by copying LV data from the first device
748 to others) each time the LV is activated, e.g. after reboot.
749 mirrored is a persistent log that is itself mirrored, but should
750 be avoided. Instead, use the raid1 type for log redundancy.
751 -m|--mirrors [+|-]Number
753 Specifies the number of mirror images in addition to the origi‐
754 nal LV image, e.g. --mirrors 1 means there are two images of the
755 data, the original and one mirror image. Optional positional PV
756 args on the command line can specify the devices the images
757 should be placed on. There are two mirroring implementations:
758 "raid1" and "mirror". These are the names of the corresponding
759 LV types, or "segment types". Use the --type option to specify
760 which to use (raid1 is default, and mirror is legacy) Use
761 lvm.conf(5) global/mirror_segtype_default and global/raid10_seg‐
762 type_default to configure the default types. The plus prefix +
763 can be used, in which case the number is added to the current
764 number of images, or the minus prefix - can be used, in which
765 case the number is subtracted from the current number of images.
766 See lvmraid(7) for more information.
767 -n|--name String
769 Specifies the name of a new LV. When unspecified, a default
770 name of "lvol#" is generated, where # is a number generated by
771 LVM.
772 --nohints
774 Do not use the hints file to locate devices for PVs. A command
775 may read more devices to find PVs when hints are not used. The
776 command will still perform standard hint file invalidation where
777 appropriate.
778 --nolocking
780 Disable locking. Use with caution, concurrent commands may pro‐
781 duce incorrect results.
782 --noudevsync
784 Disables udev synchronization. The process will not wait for no‐
785 tification from udev. It will continue irrespective of any pos‐
786 sible udev processing in the background. Only use this if udev
787 is not running or has rules that ignore the devices LVM creates.
788 --originname LV
790 Specifies the name to use for the external origin LV when con‐
791 verting an LV to a thin LV. The LV being converted becomes a
792 read-only external origin with this name.
793 --poolmetadata LV
795 The name of a an LV to use for storing pool metadata.
796 --poolmetadatasize Size[m|UNIT]
798 Specifies the size of the new pool metadata LV.
799 --poolmetadataspare y|n
801 Enable or disable the automatic creation and management of a
802 spare pool metadata LV in the VG. A spare metadata LV is re‐
803 served space that can be used when repairing a pool.
804 --profile String
806 An alias for --commandprofile or --metadataprofile, depending on
807 the command.
808 -q|--quiet ...
810 Suppress output and log messages. Overrides --debug and --ver‐
811 bose. Repeat once to also suppress any prompts with answer
812 'no'.
813 --raidintegrity y|n
815 Enable or disable data integrity checksums for raid images.
816 --raidintegrityblocksize Number
818 The block size to use for dm-integrity on raid images. The in‐
819 tegrity block size should usually match the device logical block
820 size, or the file system block size. It may be less than the
821 file system block size, but not less than the device logical
822 block size. Possible values: 512, 1024, 2048, 4096.
823 --raidintegritymode String
825 Use a journal (default) or bitmap for keeping integrity check‐
826 sums consistent in case of a crash. The bitmap areas are recal‐
827 culated after a crash, so corruption in those areas would not be
828 detected. A journal does not have this problem. The journal
829 mode doubles writes to storage, but can improve performance for
830 scattered writes packed into a single journal write. bitmap
831 mode can in theory achieve full write throughput of the device,
832 but would not benefit from the potential scattered write opti‐
833 mization.
834 -r|--readahead auto|none|Number
836 Sets read ahead sector count of an LV. auto is the default
837 which allows the kernel to choose a suitable value automatical‐
838 ly. none is equivalent to zero.
839 -R|--regionsize Size[m|UNIT]
841 Size of each raid or mirror synchronization region. lvm.conf(5)
842 activation/raid_region_size can be used to configure a default.
843 --repair
845 Replace failed PVs in a raid or mirror LV, or run a repair util‐
846 ity on a thin pool. See lvmraid(7) and lvmthin(7) for more in‐
847 formation.
848 --replace PV
850 Replace a specific PV in a raid LV with another PV. The new PV
851 to use can be optionally specified after the LV. Multiple PVs
852 can be replaced by repeating this option. See lvmraid(7) for
853 more information.
854 -k|--setactivationskip y|n
856 Persistently sets (yes) or clears (no) the "activation skip"
857 flag on an LV. An LV with this flag set is not activated unless
858 the --ignoreactivationskip option is used by the activation com‐
859 mand. This flag is set by default on new thin snapshot LVs.
860 The flag is not applied to deactivation. The current value of
861 the flag is indicated in the lvs lv_attr bits.
862 -s|--snapshot
864 Combine a former COW snapshot LV with a former origin LV to re‐
865 verse a previous --splitsnapshot command.
866 --splitcache
868 Separates a cache pool from a cache LV, and keeps the unused
869 cache pool LV. Before the separation, the cache is flushed. Al‐
870 so see --uncache.
871 --splitmirrors Number
873 Splits the specified number of images from a raid1 or mirror LV
874 and uses them to create a new LV. If --trackchanges is also
875 specified, changes to the raid1 LV are tracked while the split
876 LV remains detached. If --name is specified, then the images
877 are permanently split from the original LV and changes are not
878 tracked.
879 --splitsnapshot
881 Separates a COW snapshot from its origin LV. The LV that is
882 split off contains the chunks that differ from the origin LV
883 along with metadata describing them. This LV can be wiped and
884 then destroyed with lvremove.
885 --startpoll
887 Start polling an LV to continue processing a conversion.
888 --stripes Number
890 Specifies the number of stripes in a striped LV. This is the
891 number of PVs (devices) that a striped LV is spread across. Data
892 that appears sequential in the LV is spread across multiple de‐
893 vices in units of the stripe size (see --stripesize). This does
894 not apply to existing allocated space, only newly allocated
895 space can be striped.
896 -I|--stripesize Size[k|UNIT]
898 The amount of data that is written to one device before moving
899 to the next in a striped LV.
900 --swapmetadata
902 Extracts the metadata LV from a pool and replaces it with anoth‐
903 er specified LV. The extracted LV is preserved and given the
904 name of the LV that replaced it. Use for repair only. When the
905 metadata LV is swapped out of the pool, it can be activated di‐
906 rectly and used with thin provisioning tools: cache_dump(8),
907 cache_repair(8), cache_restore(8), thin_dump(8), thin_repair(8),
908 thin_restore(8).
909 -t|--test
911 Run in test mode. Commands will not update metadata. This is
912 implemented by disabling all metadata writing but nevertheless
913 returning success to the calling function. This may lead to un‐
914 usual error messages in multi-stage operations if a tool relies
915 on reading back metadata it believes has changed but hasn't.
916 -T|--thin
918 Specifies the command is handling a thin LV or thin pool. See
919 --type thin, --type thin-pool, and --virtualsize. See
920 lvmthin(7) for more information about LVM thin provisioning.
921 --thinpool LV
923 The name of a thin pool LV.
924 --trackchanges
926 Can be used with --splitmirrors on a raid1 LV. This causes
927 changes to the original raid1 LV to be tracked while the split
928 images remain detached. This is a temporary state that allows
929 the read-only detached image to be merged efficiently back into
930 the raid1 LV later. Only the regions with changed data are
931 resynchronized during merge. While a raid1 LV is tracking
932 changes, operations on it are limited to merging the split image
933 (see --mergemirrors) or permanently splitting the image (see
934 --splitmirrors with --name.
935 --type linear|striped|snapshot|raid|mirror|thin|thin-pool|vdo|vdo-pool|
937 cache|cache-pool|writecache
938 The LV type, also known as "segment type" or "segtype". See us‐
939 age descriptions for the specific ways to use these types. For
940 more information about redundancy and performance (raid<N>, mir‐
941 ror, striped, linear) see lvmraid(7). For thin provisioning
942 (thin, thin-pool) see lvmthin(7). For performance caching
943 (cache, cache-pool) see lvmcache(7). For copy-on-write snap‐
944 shots (snapshot) see usage definitions. For VDO (vdo) see lvmv‐
945 do(7). Several commands omit an explicit type option because
946 the type is inferred from other options or shortcuts (e.g.
947 --stripes, --mirrors, --snapshot, --virtualsize, --thin,
948 --cache, --vdo). Use inferred types with care because it can
949 lead to unexpected results.
950 --uncache
952 Separates a cache pool from a cache LV, and deletes the unused
953 cache pool LV. Before the separation, the cache is flushed. Al‐
954 so see --splitcache.
955 --usepolicies
957 Perform an operation according to the policy configured in
958 lvm.conf(5) or a profile.
959 --vdopool LV
961 The name of a VDO pool LV. See lvmvdo(7) for more information
962 about VDO usage.
963 --vdosettings String
965 Specifies tunable VDO options for VDO LVs. Use the form 'op‐
966 tion=value' or 'option1=value option2=value', or repeat
967 --vdosettings for each option being set. These settings over‐
968 ride the default VDO behaviors. To remove vdosettings and re‐
969 vert to the default VDO behaviors, use --vdosettings 'default'.
970 See lvmvdo(7) for more information.
971 -v|--verbose ...
973 Set verbose level. Repeat from 1 to 4 times to increase the de‐
974 tail of messages sent to stdout and stderr.
975 --version
977 Display version information.
978 -V|--virtualsize Size[m|UNIT]
980 The virtual size of a new thin LV. See lvmthin(7) for more in‐
981 formation about LVM thin provisioning. Using virtual size (-V)
982 and actual size (-L) together creates a sparse LV. lvm.conf(5)
983 global/sparse_segtype_default determines the default segment
984 type used to create a sparse LV. Anything written to a sparse
985 LV will be returned when reading from it. Reading from other
986 areas of the LV will return blocks of zeros. When using a snap‐
987 shot to create a sparse LV, a hidden virtual device is created
988 using the zero target, and the LV has the suffix _vorigin.
989 Snapshots are less efficient than thin provisioning when creat‐
990 ing large sparse LVs (GiB).
991 -y|--yes
993 Do not prompt for confirmation interactively but always assume
994 the answer yes. Use with extreme caution. (For automatic no,
995 see -qq.)
996 -Z|--zero y|n
998 For snapshots, this controls zeroing of the first 4 KiB of data
999 in the snapshot. If the LV is read-only, the snapshot will not
1000 be zeroed. For thin pools, this controls zeroing of provisioned
1001 blocks. Provisioning of large zeroed chunks negatively impacts
1002 performance.
1003
1005 VG Volume Group name. See lvm(8) for valid names.
1006 LV Logical Volume name. See lvm(8) for valid names. An LV posi‐
1008 tional arg generally includes the VG name and LV name, e.g.
1009 VG/LV. LV1 indicates the LV must have a specific type, where
1010 the accepted LV types are listed. (raid represents raid<N>
1011 type).
1012 PV Physical Volume name, a device path under /dev. For commands
1014 managing physical extents, a PV positional arg generally accepts
1015 a suffix indicating a range (or multiple ranges) of physical ex‐
1016 tents (PEs). When the first PE is omitted, it defaults to the
1017 start of the device, and when the last PE is omitted it defaults
1018 to end. Start and end range (inclusive): PV[:PE-PE]... Start
1019 and length range (counting from 0): PV[:PE+PE]...
1020 Tag Tag name. See lvm(8) for information about tag names and using
1022 tags in place of a VG, LV or PV.
1023 String See the option description for information about the string con‐
1025 tent.
1026 Size[UNIT]
1028 Size is an input number that accepts an optional unit. Input
1029 units are always treated as base two values, regardless of capi‐
1030 talization, e.g. 'k' and 'K' both refer to 1024. The default
1031 input unit is specified by letter, followed by |UNIT. UNIT rep‐
1032 resents other possible input units: b|B is bytes, s|S is sectors
1033 of 512 bytes, k|K is KiB, m|M is MiB, g|G is GiB, t|T is TiB,
1034 p|P is PiB, e|E is EiB. (This should not be confused with the
1035 output control --units, where capital letters mean multiple of
1036 1000.)
1037
1039 See lvm(8) for information about environment variables used by lvm.
1040 For example, LVM_VG_NAME can generally be substituted for a required VG
1041 parameter.
1042
1044 Alternate command forms, advanced command usage, and listing of all
1045 valid syntax for completeness.
1046 Change the region size of an LV.
1048 lvconvert -R|--regionsize Size[m|UNIT] LV1
1050 [ COMMON_OPTIONS ]
1051 LV1 types: raid
1053 —
1055 Change the type of mirror log used by a mirror LV.
1057 lvconvert --mirrorlog core|disk LV1
1059 [ COMMON_OPTIONS ]
1060 [ PV ... ]
1061 LV1 types: mirror
1063 —
1065 Convert LV to a thin LV, using the original LV as an external origin.
1067 lvconvert -T|--thin --thinpool LV LV1
1069 [ --type thin ] (implied)
1070 [ -r|--readahead auto|none|Number ]
1071 [ -c|--chunksize Size[k|UNIT] ]
1072 [ -Z|--zero y|n ]
1073 [ --originname LV_new ]
1074 [ --poolmetadata LV ]
1075 [ --poolmetadatasize Size[m|UNIT] ]
1076 [ --poolmetadataspare y|n ]
1077 [ --metadataprofile String ]
1078 [ COMMON_OPTIONS ]
1079 LV1 types: linear striped thin cache raid error zero
1081 —
1083 Convert LV to a thin LV, using LV as thin-pool data volume.
1085 lvconvert -T|--thin LV1
1087 [ --type thin ] (implied)
1088 [ -r|--readahead auto|none|Number ]
1089 [ -c|--chunksize Size[k|UNIT] ]
1090 [ -Z|--zero y|n ]
1091 [ --poolmetadata LV ]
1092 [ --poolmetadatasize Size[m|UNIT] ]
1093 [ --poolmetadataspare y|n ]
1094 [ --metadataprofile String ]
1095 [ COMMON_OPTIONS ]
1096 LV1 types: linear striped cache vdo raid error zero writecache
1098 —
1100 Attach a cache pool to an LV.
1102 lvconvert -H|--cache --cachepool LV LV1
1104 [ --type cache ] (implied)
1105 [ -Z|--zero y|n ]
1106 [ -r|--readahead auto|none|Number ]
1107 [ -c|--chunksize Size[k|UNIT] ]
1108 [ --cachemetadataformat auto|1|2 ]
1109 [ --cachemode writethrough|writeback|passthrough ]
1110 [ --cachepolicy String ]
1111 [ --cachesettings String ]
1112 [ --poolmetadata LV ]
1113 [ --poolmetadatasize Size[m|UNIT] ]
1114 [ --poolmetadataspare y|n ]
1115 [ --metadataprofile String ]
1116 [ COMMON_OPTIONS ]
1117 LV1 types: linear striped thin thinpool vdo vdopool vdopooldata
1119 raid error zero
1120 —
1122 Attach a cache to an LV, converts the LV to type cache.
1124 lvconvert -H|--cache --cachevol LV LV1
1126 [ -Z|--zero y|n ]
1127 [ -c|--chunksize Size[k|UNIT] ]
1128 [ --cachemetadataformat auto|1|2 ]
1129 [ --cachemode writethrough|writeback|passthrough ]
1130 [ --cachepolicy String ]
1131 [ --cachesettings String ]
1132 [ --poolmetadatasize Size[m|UNIT] ]
1133 [ COMMON_OPTIONS ]
1134 LV1 types: linear striped thinpool raid
1136 —
1138 Convert LV to type vdopool.
1140 lvconvert --vdopool LV
1142 [ --type vdo-pool ] (implied)
1143 [ -r|--readahead auto|none|Number ]
1144 [ -Z|--zero y|n ]
1145 [ -n|--name LV_new ]
1146 [ -V|--virtualsize Size[m|UNIT] ]
1147 [ --metadataprofile String ]
1148 [ --compression y|n ]
1149 [ --deduplication y|n ]
1150 [ --vdosettings String ]
1151 [ COMMON_OPTIONS ]
1152 —
1154 Detach and delete a cache from an LV.
1156 lvconvert --uncache LV1
1158 [ --cachesettings String ]
1159 [ COMMON_OPTIONS ]
1160 LV1 types: thinpool cache vdopool writecache
1162 —
1164 Swap metadata LV in a thin pool or cache pool (for repair only).
1166 lvconvert --swapmetadata --poolmetadata LV LV1
1168 [ -c|--chunksize Size[k|UNIT] ]
1169 [ COMMON_OPTIONS ]
1170 LV1 types: thinpool cachepool
1172 —
1174 Merge LV that was split from a mirror (variant, use --mergemirrors).
1176 Merge thin LV into its origin LV (variant, use --mergethin).
1177 Merge COW snapshot LV into its origin (variant, use --mergesnapshot).
1178 lvconvert --merge VG|LV1|Tag ...
1180 [ -i|--interval Number ]
1181 [ COMMON_OPTIONS ]
1182 LV1 types: linear striped snapshot thin raid
1184 —
1186 Separate a COW snapshot from its origin LV.
1188 lvconvert --splitsnapshot LV1
1190 [ COMMON_OPTIONS ]
1191 LV1 types: snapshot
1193 —
1195 Combine a former COW snapshot (second arg) with a former
1197 origin LV (first arg) to reverse a splitsnapshot command.
1198 lvconvert -s|--snapshot LV LV1
1200 [ --type snapshot ] (implied)
1201 [ -c|--chunksize Size[k|UNIT] ]
1202 [ -Z|--zero y|n ]
1203 [ COMMON_OPTIONS ]
1204 LV1 types: linear striped
1206 —
1208 Poll LV to continue conversion (also see --startpoll)
1210 or waits till conversion/mirror syncing is finished
1211 lvconvert LV1
1213 [ COMMON_OPTIONS ]
1214 LV1 types: mirror raid
1216 —
1218
1220 This previous command syntax would perform two different operations:
1221 lvconvert --thinpool LV1 --poolmetadata LV2
1222 If LV1 was not a thin pool, the command would convert LV1 to a thin
1223 pool, optionally using a specified LV for metadata. But, if LV1 was
1224 already a thin pool, the command would swap the current metadata LV
1225 with LV2 (for repair purposes.)
1226 In the same way, this previous command syntax would perform two differ‐
1228 ent operations:
1229 lvconvert --cachepool LV1 --poolmetadata LV2
1230 If LV1 was not a cache pool, the command would convert LV1 to a cache
1231 pool, optionally using a specified LV for metadata. But, if LV1 was
1232 already a cache pool, the command would swap the current metadata LV
1233 with LV2 (for repair purposes.)
1234
1236 Convert a linear LV to a two-way mirror LV.
1237 lvconvert --type mirror --mirrors 1 vg/lvol1
1238 Convert a linear LV to a two-way RAID1 LV.
1240 lvconvert --type raid1 --mirrors 1 vg/lvol1
1241 Convert a mirror LV to use an in-memory log.
1243 lvconvert --mirrorlog core vg/lvol1
1244 Convert a mirror LV to use a disk log.
1246 lvconvert --mirrorlog disk vg/lvol1
1247 Convert a mirror or raid1 LV to a linear LV.
1249 lvconvert --type linear vg/lvol1
1250 Convert a mirror LV to a raid1 LV with the same number of images.
1252 lvconvert --type raid1 vg/lvol1
1253 Convert a linear LV to a two-way mirror LV, allocating new extents from
1255 specific PV ranges.
1256 lvconvert --mirrors 1 vg/lvol1 /dev/sda:0-15 /dev/sdb:0-15
1257 Convert a mirror LV to a linear LV, freeing physical extents from a
1259 specific PV.
1260 lvconvert --type linear vg/lvol1 /dev/sda
1261 Split one image from a mirror or raid1 LV, making it a new LV.
1263 lvconvert --splitmirrors 1 --name lv_split vg/lvol1
1264 Split one image from a raid1 LV, and track changes made to the raid1 LV
1266 while the split image remains detached.
1267 lvconvert --splitmirrors 1 --trackchanges vg/lvol1
1268 Merge an image (that was previously created with --splitmirrors and
1270 --trackchanges) back into the original raid1 LV.
1271 lvconvert --mergemirrors vg/lvol1_rimage_1
1272 Replace PV /dev/sdb1 with PV /dev/sdf1 in a raid1/4/5/6/10 LV.
1274 lvconvert --replace /dev/sdb1 vg/lvol1 /dev/sdf1
1275 Replace 3 PVs /dev/sd[b-d]1 with PVs /dev/sd[f-h]1 in a raid1 LV.
1277 lvconvert --replace /dev/sdb1 --replace /dev/sdc1 --replace /dev/sdd1
1278 vg/lvol1 /dev/sd[fgh]1
1279 Replace the maximum of 2 PVs /dev/sd[bc]1 with PVs /dev/sd[gh]1 in a
1281 raid6 LV.
1282 lvconvert --replace /dev/sdb1 --replace /dev/sdc1 vg/lvol1 /dev/sd[gh]1
1283 Convert a thick LV into a thin-pool data volume and continue using this
1285 LV through thinLV and for the conversion set the pool metadata size to
1286 1GiB.
1287 lvconvert --type thin --poolmetadatasize 1G vg/lvol1
1288 Convert an LV into a thin LV in the specified thin pool. The existing
1290 LV is used as an external read-only origin for the new thin LV.
1291 lvconvert --type thin --thinpool vg/tpool1 vg/lvol1
1292 Convert an LV into a thin LV in the specified thin pool. The existing
1294 LV is used as an external read-only origin for the new thin LV, and is
1295 renamed "external".
1296 lvconvert --type thin --thinpool vg/tpool1
1297 --originname external vg/lvol1
1298 Convert an LV to a cache pool LV using another specified LV for cache
1300 pool metadata.
1301 lvconvert --type cache-pool --poolmetadata vg/poolmeta1 vg/lvol1
1302 Convert an LV to a cache LV using the specified cache pool and chunk
1304 size.
1305 lvconvert --type cache --cachepool vg/cpool1 -c 128 vg/lvol1
1306 Detach and keep the cache pool from a cache LV.
1308 lvconvert --splitcache vg/lvol1
1309 Detach and remove the cache pool from a cache LV.
1311 lvconvert --uncache vg/lvol1
1312
1314 lvm(8), lvm.conf(5), lvmconfig(8), lvmdevices(8),
1315 pvchange(8), pvck(8), pvcreate(8), pvdisplay(8), pvmove(8),
1317 pvremove(8), pvresize(8), pvs(8), pvscan(8),
1318 vgcfgbackup(8), vgcfgrestore(8), vgchange(8), vgck(8), vgcreate(8),
1320 vgconvert(8), vgdisplay(8), vgexport(8), vgextend(8), vgimport(8),
1321 vgimportclone(8), vgimportdevices(8), vgmerge(8), vgmknodes(8),
1322 vgreduce(8), vgremove(8), vgrename(8), vgs(8), vgscan(8), vgsplit(8),
1323 lvcreate(8), lvchange(8), lvconvert(8), lvdisplay(8), lvextend(8),
1325 lvreduce(8), lvremove(8), lvrename(8), lvresize(8), lvs(8), lvscan(8),
1326 lvm-fullreport(8), lvm-lvpoll(8), blkdeactivate(8), lvmdump(8),
1328 dmeventd(8), lvmpolld(8), lvmlockd(8), lvmlockctl(8), cmirrord(8),
1330 lvmdbusd(8), fsadm(8),
1331 lvmsystemid(7), lvmreport(7), lvmcache(7), lvmraid(7), lvmthin(7),
1333 lvmvdo(7), lvmautoactivation(7)
1334Red Hat, Inc. LVM TOOLS 2.03.22(2) (2023-08-02) LVCONVERT(8)