1LVCONVERT(8)                System Manager's Manual               LVCONVERT(8)
2
3
4

NAME

6       lvconvert - Change logical volume layout
7

SYNOPSIS

9       lvconvert option_args position_args
10           [ option_args ]
11           [ position_args ]
12
13           --alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit
14        -b|--background
15        -H|--cache
16           --cachemetadataformat auto|1|2
17           --cachemode writethrough|writeback|passthrough
18           --cachepolicy String
19           --cachepool LV
20           --cachesettings String
21           --cachevol LV
22        -c|--chunksize Size[k|UNIT]
23           --commandprofile String
24           --compression y|n
25           --config String
26        -d|--debug
27           --deduplication y|n
28           --discards passdown|nopassdown|ignore
29           --driverloaded y|n
30        -f|--force
31        -h|--help
32        -i|--interval Number
33           --lockopt String
34           --longhelp
35           --merge
36           --mergemirrors
37           --mergesnapshot
38           --mergethin
39           --metadataprofile String
40           --mirrorlog core|disk
41        -m|--mirrors [+|-]Number
42        -n|--name String
43           --nolocking
44           --noudevsync
45           --originname LV
46           --poolmetadata LV
47           --poolmetadatasize Size[m|UNIT]
48           --poolmetadataspare y|n
49           --profile String
50        -q|--quiet
51        -r|--readahead auto|none|Number
52        -R|--regionsize Size[m|UNIT]
53           --repair
54           --replace PV
55        -s|--snapshot
56           --splitcache
57           --splitmirrors Number
58           --splitsnapshot
59           --startpoll
60           --stripes Number
61        -I|--stripesize Size[k|UNIT]
62           --swapmetadata
63        -t|--test
64        -T|--thin
65           --thinpool LV
66           --trackchanges
67           --type linear|striped|snapshot|mir‐
68       ror|raid|thin|cache|vdo|thin-pool|cache-pool|vdo-pool
69           --uncache
70           --usepolicies
71           --vdopool LV
72        -v|--verbose
73           --version
74        -V|--virtualsize Size[m|UNIT]
75        -y|--yes
76        -Z|--zero y|n
77

DESCRIPTION

79       lvconvert changes the LV type and includes utilities for LV data  main‐
80       tenance.  The LV type controls data layout and redundancy.  The LV type
81       is also called the segment type or segtype.
82
83       To display the current LV type, run the command:
84
85       lvs -o name,segtype LV
86
87       In some cases, an LV is a single device mapper (dm) layer above  physi‐
88       cal  devices.   In  other  cases,  hidden  LVs (dm devices) are layered
89       between the visible LV and physical devices.  LVs in the middle  layers
90       are  called  sub LVs.  A command run on a visible LV sometimes operates
91       on a sub LV rather than the specified LV.  In other  cases,  a  sub  LV
92       must be specified directly on the command line.
93
94       Sub LVs can be displayed with the command:
95
96       lvs -a
97
98       The  linear  type  is  equivalent  to  the striped type when one stripe
99       exists.  In that case, the types can sometimes be used interchangably.
100
101       In most cases, the mirror type is deprecated and the raid1 type  should
102       be used.  They are both implementations of mirroring.
103
104       Striped raid types are raid0/raid0_meta, raid5 (an alias for raid5_ls),
105       raid6 (an alias for raid6_zr) and raid10 (an alias for raid10_near).
106
107       As opposed to mirroring, raid5 and raid6 stripe data and calculate par‐
108       ity  blocks.  The  parity blocks can be used for data block recovery in
109       case devices fail. A maximum number of one device in  a  raid5  LV  may
110       fail, and two in case of raid6. Striped raid types typically rotate the
111       parity and data blocks for  performance  reasons,  thus  avoiding  con‐
112       tention  on  a  single device. Specific arrangements of parity and data
113       blocks (layouts) can be used to optimize I/O performance, or to convert
114       between raid levels.  See lvmraid(7) for more information.
115
116       Layouts  of  raid5  rotating  parity  blocks  can  be:  left-asymmetric
117       (raid5_la), left-symmetric (raid5_ls with alias raid5),  right-asymmet‐
118       ric  (raid5_ra),  right-symmetric (raid5_rs) and raid5_n, which doesn't
119       rotate parity blocks. Layouts of raid6 are: zero-restart (raid6_zr with
120       alias raid6), next-restart (raid6_nr), and next-continue (raid6_nc).
121
122       Layouts  including _n allow for conversion between raid levels (raid5_n
123       to raid6 or raid5_n to striped/raid0/raid0_meta). Additionally, special
124       raid6  layouts  for raid level conversions between raid5 and raid6 are:
125       raid6_ls_6, raid6_rs_6, raid6_la_6 and raid6_ra_6. Those correspond  to
126       their  raid5  counterparts  (e.g. raid5_rs can be directly converted to
127       raid6_rs_6 and vice-versa).
128
129       raid10 (an alias for raid10_near) is currently limited to one data copy
130       and  even number of sub LVs. This is a mirror group layout, thus a sin‐
131       gle sub LV may fail per mirror group without data loss.
132
133       Striped raid types support converting the layout, their stripesize  and
134       their number of stripes.
135
136       The  striped  raid  types combined with raid1 allow for conversion from
137       linear-> striped/raid0/raid0_meta and vice-versa  by  e.g.  linear  <->
138       raid1 <-> raid5_n (then adding stripes) <-> striped/raid0/raid0_meta.
139

USAGE

141       Convert LV to linear.
142
143       lvconvert --type linear LV
144           [ COMMON_OPTIONS ]
145           [ PV ... ]
146       -
147
148       Convert LV to striped.
149
150       lvconvert --type striped LV
151           [ -I|--stripesize Size[k|UNIT] ]
152           [ -R|--regionsize Size[m|UNIT] ]
153           [ -i|--interval Number ]
154           [    --stripes Number ]
155           [ COMMON_OPTIONS ]
156           [ PV ... ]
157       -
158
159       Convert LV to type mirror (also see type raid1),
160
161       lvconvert --type mirror LV
162           [ -m|--mirrors [+|-]Number ]
163           [ -I|--stripesize Size[k|UNIT] ]
164           [ -R|--regionsize Size[m|UNIT] ]
165           [ -i|--interval Number ]
166           [    --stripes Number ]
167           [    --mirrorlog core|disk ]
168           [ COMMON_OPTIONS ]
169           [ PV ... ]
170       -
171
172       Convert LV to raid or change raid layout
173       (a specific raid level must be used, e.g. raid1).
174
175       lvconvert --type raid 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           [ COMMON_OPTIONS ]
182           [ PV ... ]
183       -
184
185       Convert LV to raid1 or mirror, or change number of mirror images.
186
187       lvconvert -m|--mirrors [+|-]Number LV
188           [ -R|--regionsize Size[m|UNIT] ]
189           [ -i|--interval Number ]
190           [    --mirrorlog core|disk ]
191           [ COMMON_OPTIONS ]
192           [ PV ... ]
193       -
194
195       Convert raid LV to change number of stripe images.
196
197       lvconvert --stripes Number LV_raid
198           [ -i|--interval Number ]
199           [ -R|--regionsize Size[m|UNIT] ]
200           [ -I|--stripesize Size[k|UNIT] ]
201           [ COMMON_OPTIONS ]
202           [ PV ... ]
203       -
204
205       Convert raid LV to change the stripe size.
206
207       lvconvert -I|--stripesize Size[k|UNIT] LV_raid
208           [ -i|--interval Number ]
209           [ -R|--regionsize Size[m|UNIT] ]
210           [ COMMON_OPTIONS ]
211       -
212
213       Split images from a raid1 or mirror LV and use them to create a new LV.
214
215       lvconvert --splitmirrors Number -n|--name LV_new LV_cache_mirror_raid1
216           [ COMMON_OPTIONS ]
217           [ PV ... ]
218       -
219
220       Split  images  from  a  raid1  LV and track changes to origin for later
221       merge.
222
223       lvconvert --splitmirrors Number --trackchanges LV_cache_raid1
224           [ COMMON_OPTIONS ]
225           [ PV ... ]
226       -
227
228       Merge LV images that were split from a raid1 LV.
229
230       lvconvert --mergemirrors VG|LV_linear_raid|Tag ...
231           [ COMMON_OPTIONS ]
232       -
233
234       Convert LV to a thin LV, using the original LV as an external origin.
235
236       lvconvert --type thin --thinpool LV LV_linear_striped_thin_cache_raid
237           [ -T|--thin ]
238           [ -r|--readahead auto|none|Number ]
239           [ -c|--chunksize Size[k|UNIT] ]
240           [ -Z|--zero y|n ]
241           [    --originname LV_new ]
242           [    --poolmetadata LV ]
243           [    --poolmetadatasize Size[m|UNIT] ]
244           [    --poolmetadataspare y|n ]
245           [    --metadataprofile String ]
246           [ COMMON_OPTIONS ]
247       -
248
249       Attach a cache pool to an LV, converts the LV to type cache.
250
251       lvconvert   --type   cache   --cachepool   LV   LV_linear_striped_thin‐
252       pool_vdo_vdopool_vdopooldata_raid
253           [ -H|--cache ]
254           [ -Z|--zero y|n ]
255           [ -r|--readahead auto|none|Number ]
256           [ -c|--chunksize Size[k|UNIT] ]
257           [    --cachemetadataformat auto|1|2 ]
258           [    --cachemode writethrough|writeback|passthrough ]
259           [    --cachepolicy String ]
260           [    --cachesettings String ]
261           [    --poolmetadata LV ]
262           [    --poolmetadatasize Size[m|UNIT] ]
263           [    --poolmetadataspare y|n ]
264           [    --metadataprofile String ]
265           [ COMMON_OPTIONS ]
266       -
267
268       Attach a writecache to an LV, converts the LV to type writecache.
269
270       lvconvert --type writecache --cachevol LV LV_linear_striped_raid
271           [    --cachesettings String ]
272           [ COMMON_OPTIONS ]
273       -
274
275       Attach a cache to an LV, converts the LV to type cache.
276
277       lvconvert --type cache --cachevol LV LV_linear_striped_thinpool_raid
278           [ -H|--cache ]
279           [ -Z|--zero y|n ]
280           [ -c|--chunksize Size[k|UNIT] ]
281           [    --cachemetadataformat auto|1|2 ]
282           [    --cachemode writethrough|writeback|passthrough ]
283           [    --cachepolicy String ]
284           [    --cachesettings String ]
285           [    --poolmetadatasize Size[m|UNIT] ]
286           [ COMMON_OPTIONS ]
287       -
288
289       Convert LV to type thin-pool.
290
291       lvconvert --type thin-pool LV_linear_striped_cache_raid
292           [ -I|--stripesize Size[k|UNIT] ]
293           [ -r|--readahead auto|none|Number ]
294           [ -c|--chunksize Size[k|UNIT] ]
295           [ -Z|--zero y|n ]
296           [    --stripes Number ]
297           [    --discards passdown|nopassdown|ignore ]
298           [    --poolmetadata LV ]
299           [    --poolmetadatasize Size[m|UNIT] ]
300           [    --poolmetadataspare y|n ]
301           [    --metadataprofile String ]
302           [ COMMON_OPTIONS ]
303           [ PV ... ]
304       -
305
306       Convert LV to type cache-pool.
307
308       lvconvert --type cache-pool LV_linear_striped_raid
309           [ -Z|--zero y|n ]
310           [ -r|--readahead auto|none|Number ]
311           [ -c|--chunksize Size[k|UNIT] ]
312           [    --cachemetadataformat auto|1|2 ]
313           [    --cachemode writethrough|writeback|passthrough ]
314           [    --cachepolicy String ]
315           [    --cachesettings String ]
316           [    --poolmetadata LV ]
317           [    --poolmetadatasize Size[m|UNIT] ]
318           [    --poolmetadataspare y|n ]
319           [    --metadataprofile String ]
320           [ COMMON_OPTIONS ]
321           [ PV ... ]
322       -
323
324       Convert LV to type vdopool.
325
326       lvconvert --type vdo-pool LV_linear_striped_cache_raid
327           [ -n|--name LV_new ]
328           [ -V|--virtualsize Size[m|UNIT] ]
329           [    --compression y|n ]
330           [    --deduplication y|n ]
331           [ COMMON_OPTIONS ]
332       -
333
334       Detach a cache from an LV.
335
336       lvconvert --splitcache LV_thinpool_cache_cachepool_vdopool_writecache
337           [ COMMON_OPTIONS ]
338       -
339
340       Merge thin LV into its origin LV.
341
342       lvconvert --mergethin LV_thin ...
343           [ COMMON_OPTIONS ]
344       -
345
346       Merge COW snapshot LV into its origin.
347
348       lvconvert --mergesnapshot LV_snapshot ...
349           [ -i|--interval Number ]
350           [ COMMON_OPTIONS ]
351       -
352
353       Combine a former COW snapshot (second arg) with a former
354       origin LV (first arg) to reverse a splitsnapshot command.
355
356       lvconvert --type snapshot LV LV_linear_striped
357           [ -s|--snapshot ]
358           [ -c|--chunksize Size[k|UNIT] ]
359           [ -Z|--zero y|n ]
360           [ COMMON_OPTIONS ]
361       -
362
363       Replace failed PVs in a raid or mirror LV.
364       Repair a thin pool.
365       Repair a cache pool.
366
367       lvconvert --repair LV_thinpool_cache_cachepool_mirror_raid
368           [ -i|--interval Number ]
369           [    --usepolicies ]
370           [    --poolmetadataspare y|n ]
371           [ COMMON_OPTIONS ]
372           [ PV ... ]
373       -
374
375       Replace specific PV(s) in a raid LV with another PV.
376
377       lvconvert --replace PV LV_raid
378           [ COMMON_OPTIONS ]
379           [ PV ... ]
380       -
381
382       Poll LV to continue conversion.
383
384       lvconvert --startpoll LV_mirror_raid
385           [ COMMON_OPTIONS ]
386       -
387
388       Common options for command:
389           [ -b|--background ]
390           [ -f|--force ]
391           [    --alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit
392           ]
393           [    --noudevsync ]
394
395       Common options for lvm:
396           [ -d|--debug ]
397           [ -h|--help ]
398           [ -q|--quiet ]
399           [ -t|--test ]
400           [ -v|--verbose ]
401           [ -y|--yes ]
402           [    --commandprofile String ]
403           [    --config String ]
404           [    --driverloaded y|n ]
405           [    --lockopt String ]
406           [    --longhelp ]
407           [    --nolocking ]
408           [    --profile String ]
409           [    --version ]
410

OPTIONS

412       --alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit
413              Determines the allocation policy when a command needs to allo‐
414              cate Physical Extents (PEs) from the VG. Each VG and LV has an
415              allocation policy which can be changed with vgchange/lvchange,
416              or overriden on the command line.  normal applies common sense
417              rules such as not placing parallel stripes on the same PV.
418              inherit applies the VG policy to an LV.  contiguous requires new
419              PEs be placed adjacent to existing PEs.  cling places new PEs on
420              the same PV as existing PEs in the same stripe of the LV.  If
421              there are sufficient PEs for an allocation, but normal does not
422              use them, anywhere will use them even if it reduces performance,
423              e.g. by placing two stripes on the same PV.  Optional positional
424              PV args on the command line can also be used to limit which PVs
425              the command will use for allocation.  See lvm(8) for more infor‐
426              mation about allocation.
427
428       -b|--background
429              If the operation requires polling, this option causes the com‐
430              mand to return before the operation is complete, and polling is
431              done in the background.
432
433       -H|--cache
434              Specifies the command is handling a cache LV or cache pool.  See
435              --type cache and --type cache-pool.  See lvmcache(7) for more
436              information about LVM caching.
437
438       --cachemetadataformat auto|1|2
439              Specifies the cache metadata format used by cache target.
440
441       --cachemode writethrough|writeback|passthrough
442              Specifies when writes to a cache LV should be considered com‐
443              plete.  writeback considers a write complete as soon as it is
444              stored in the cache pool.  writethough considers a write com‐
445              plete only when it has been stored in both the cache pool and on
446              the origin LV.  While writethrough may be slower for writes, it
447              is more resilient if something should happen to a device associ‐
448              ated with the cache pool LV. With passthrough, all reads are
449              served from the origin LV (all reads miss the cache) and all
450              writes are forwarded to the origin LV; additionally, write hits
451              cause cache block invalidates. See lvmcache(7) for more informa‐
452              tion.
453
454       --cachepolicy String
455              Specifies the cache policy for a cache LV.  See lvmcache(7) for
456              more information.
457
458       --cachepool LV
459              The name of a cache pool.
460
461       --cachesettings String
462              Specifies tunable values for a cache LV in "Key = Value" form.
463              Repeat this option to specify multiple values.  (The default
464              values should usually be adequate.)  The special string value
465              default switches settings back to their default kernel values
466              and removes them from the list of settings stored in LVM meta‐
467              data.  See lvmcache(7) for more information.
468
469       --cachevol LV
470              The name of a cache volume.
471
472       -c|--chunksize Size[k|UNIT]
473              The size of chunks in a snapshot, cache pool or thin pool.  For
474              snapshots, the value must be a power of 2 between 4KiB and
475              512KiB and the default value is 4.  For a cache pool the value
476              must be between 32KiB and 1GiB and the default value is 64.  For
477              a thin pool the value must be between 64KiB and 1GiB and the
478              default value starts with 64 and scales up to fit the pool meta‐
479              data size within 128MiB, if the pool metadata size is not speci‐
480              fied.  The value must be a multiple of 64KiB.  See lvmthin(7)
481              and lvmcache(7) for more information.
482
483       --commandprofile String
484              The command profile to use for command configuration.  See
485              lvm.conf(5) for more information about profiles.
486
487       --compression y|n
488              Controls whether compression is enabled or disable for VDO vol‐
489              ume.  See lvmvdo(7) for more information about VDO usage.
490
491       --config String
492              Config settings for the command. These override lvm.conf set‐
493              tings.  The String arg uses the same format as lvm.conf, or may
494              use section/field syntax.  See lvm.conf(5) for more information
495              about config.
496
497       -d|--debug ...
498              Set debug level. Repeat from 1 to 6 times to increase the detail
499              of messages sent to the log file and/or syslog (if configured).
500
501       --deduplication y|n
502              Controls whether deduplication is enabled or disable for VDO
503              volume.  See lvmvdo(7) for more information about VDO usage.
504
505       --discards passdown|nopassdown|ignore
506              Specifies how the device-mapper thin pool layer in the kernel
507              should handle discards.  ignore causes the thin pool to ignore
508              discards.  nopassdown causes the thin pool to process discards
509              itself to allow reuse of unneeded extents in the thin pool.
510              passdown causes the thin pool to process discards itself (like
511              nopassdown) and pass the discards to the underlying device.  See
512              lvmthin(7) for more information.
513
514       --driverloaded y|n
515              If set to no, the command will not attempt to use device-mapper.
516              For testing and debugging.
517
518       -f|--force ...
519              Override various checks, confirmations and protections.  Use
520              with extreme caution.
521
522       -h|--help
523              Display help text.
524
525       -i|--interval Number
526              Report progress at regular intervals.
527
528       --lockopt String
529              Used to pass options for special cases to lvmlockd.  See lvm‐
530              lockd(8) for more information.
531
532       --longhelp
533              Display long help text.
534
535       --merge
536              An alias for --mergethin, --mergemirrors, or --mergesnapshot,
537              depending on the type of LV.
538
539       --mergemirrors
540              Merge LV images that were split from a raid1 LV.  See --split‐
541              mirrors with --trackchanges.
542
543       --mergesnapshot
544              Merge COW snapshot LV into its origin.  When merging a snapshot,
545              if both the origin and snapshot LVs are not open, the merge will
546              start immediately. Otherwise, the merge will start the first
547              time either the origin or snapshot LV are activated and both are
548              closed. Merging a snapshot into an origin that cannot be closed,
549              for example a root filesystem, is deferred until the next time
550              the origin volume is activated. When merging starts, the result‐
551              ing LV will have the origin's name, minor number and UUID. While
552              the merge is in progress, reads or writes to the origin appear
553              as being directed to the snapshot being merged. When the merge
554              finishes, the merged snapshot is removed.  Multiple snapshots
555              may be specified on the command line or a @tag may be used to
556              specify multiple snapshots be merged to their respective origin.
557
558       --mergethin
559              Merge thin LV into its origin LV.  The origin thin LV takes the
560              content of the thin snapshot, and the thin snapshot LV is
561              removed.  See lvmthin(7) for more information.
562
563       --metadataprofile String
564              The metadata profile to use for command configuration.  See
565              lvm.conf(5) for more information about profiles.
566
567       --mirrorlog core|disk
568              Specifies the type of mirror log for LVs with the "mirror" type
569              (does not apply to the "raid1" type.)  disk is a persistent log
570              and requires a small amount of storage space, usually on a sepa‐
571              rate device from the data being mirrored.  core is not persis‐
572              tent; the log is kept only in memory.  In this case, the mirror
573              must be synchronized (by copying LV data from the first device
574              to others) each time the LV is activated, e.g. after reboot.
575              mirrored is a persistent log that is itself mirrored, but should
576              be avoided. Instead, use the raid1 type for log redundancy.
577
578       -m|--mirrors [+|-]Number
579              Specifies the number of mirror images in addition to the origi‐
580              nal LV image, e.g. --mirrors 1 means there are two images of the
581              data, the original and one mirror image.  Optional positional PV
582              args on the command line can specify the devices the images
583              should be placed on.  There are two mirroring implementations:
584              "raid1" and "mirror".  These are the names of the corresponding
585              LV types, or "segment types".  Use the --type option to specify
586              which to use (raid1 is default, and mirror is legacy) Use
587              lvm.conf global/mirror_segtype_default and global/raid10_seg‐
588              type_default to configure the default types.  The plus prefix +
589              can be used, in which case the number is added to the current
590              number of images, or the minus prefix - can be used, in which
591              case the number is subtracted from the current number of images.
592              See lvmraid(7) for more information.
593
594       -n|--name String
595              Specifies the name of a new LV.  When unspecified, a default
596              name of "lvol#" is generated, where # is a number generated by
597              LVM.
598
599       --nolocking
600              Disable locking.
601
602       --noudevsync
603              Disables udev synchronisation. The process will not wait for
604              notification from udev. It will continue irrespective of any
605              possible udev processing in the background. Only use this if
606              udev is not running or has rules that ignore the devices LVM
607              creates.
608
609       --originname LV
610              Specifies the name to use for the external origin LV when con‐
611              verting an LV to a thin LV. The LV being converted becomes a
612              read-only external origin with this name.
613
614       --poolmetadata LV
615              The name of a an LV to use for storing pool metadata.
616
617       --poolmetadatasize Size[m|UNIT]
618              Specifies the size of the new pool metadata LV.
619
620       --poolmetadataspare y|n
621              Enable or disable the automatic creation and management of a
622              spare pool metadata LV in the VG. A spare metadata LV is
623              reserved space that can be used when repairing a pool.
624
625       --profile String
626              An alias for --commandprofile or --metadataprofile, depending on
627              the command.
628
629       -q|--quiet ...
630              Suppress output and log messages. Overrides --debug and --ver‐
631              bose.  Repeat once to also suppress any prompts with answer
632              'no'.
633
634       -r|--readahead auto|none|Number
635              Sets read ahead sector count of an LV.  auto is the default
636              which allows the kernel to choose a suitable value automati‐
637              cally.  none is equivalent to zero.
638
639       -R|--regionsize Size[m|UNIT]
640              Size of each raid or mirror synchronization region.  lvm.conf
641              activation/raid_region_size can be used to configure a default.
642
643       --repair
644              Replace failed PVs in a raid or mirror LV, or run a repair util‐
645              ity on a thin pool. See lvmraid(7) and lvmthin(7) for more
646              information.
647
648       --replace PV
649              Replace a specific PV in a raid LV with another PV.  The new PV
650              to use can be optionally specified after the LV.  Multiple PVs
651              can be replaced by repeating this option.  See lvmraid(7) for
652              more information.
653
654       -s|--snapshot
655              Combine a former COW snapshot LV with a former origin LV to
656              reverse a previous --splitsnapshot command.
657
658       --splitcache
659              Separates a cache pool from a cache LV, and keeps the unused
660              cache pool LV.  Before the separation, the cache is flushed.
661              Also see --uncache.
662
663       --splitmirrors Number
664              Splits the specified number of images from a raid1 or mirror LV
665              and uses them to create a new LV. If --trackchanges is also
666              specified, changes to the raid1 LV are tracked while the split
667              LV remains detached.  If --name is specified, then the images
668              are permanently split from the original LV and changes are not
669              tracked.
670
671       --splitsnapshot
672              Separates a COW snapshot from its origin LV. The LV that is
673              split off contains the chunks that differ from the origin LV
674              along with metadata describing them. This LV can be wiped and
675              then destroyed with lvremove.
676
677       --startpoll
678              Start polling an LV to continue processing a conversion.
679
680       --stripes Number
681              Specifies the number of stripes in a striped LV. This is the
682              number of PVs (devices) that a striped LV is spread across. Data
683              that appears sequential in the LV is spread across multiple
684              devices in units of the stripe size (see --stripesize). This
685              does not apply to existing allocated space, only newly allocated
686              space can be striped.
687
688       -I|--stripesize Size[k|UNIT]
689              The amount of data that is written to one device before moving
690              to the next in a striped LV.
691
692       --swapmetadata
693              Extracts the metadata LV from a pool and replaces it with
694              another specified LV.  The extracted LV is preserved and given
695              the name of the LV that replaced it.  Use for repair only. When
696              the metadata LV is swapped out of the pool, it can be activated
697              directly and used with thin provisioning tools: cache_dump(8),
698              cache_repair(8), cache_restore(8), thin_dump(8), thin_repair(8),
699              thin_restore(8).
700
701       -t|--test
702              Run in test mode. Commands will not update metadata.  This is
703              implemented by disabling all metadata writing but nevertheless
704              returning success to the calling function. This may lead to
705              unusual error messages in multi-stage operations if a tool
706              relies on reading back metadata it believes has changed but
707              hasn't.
708
709       -T|--thin
710              Specifies the command is handling a thin LV or thin pool.  See
711              --type thin, --type thin-pool, and --virtualsize.  See
712              lvmthin(7) for more information about LVM thin provisioning.
713
714       --thinpool LV
715              The name of a thin pool LV.
716
717       --trackchanges
718              Can be used with --splitmirrors on a raid1 LV. This causes
719              changes to the original raid1 LV to be tracked while the split
720              images remain detached. This is a temporary state that allows
721              the read-only detached image to be merged efficiently back into
722              the raid1 LV later.  Only the regions with changed data are
723              resynchronized during merge.  While a raid1 LV is tracking
724              changes, operations on it are limited to merging the split image
725              (see --mergemirrors) or permanently splitting the image (see
726              --splitmirrors with --name.
727
728       --type linear|striped|snapshot|mir‐
729              ror|raid|thin|cache|vdo|thin-pool|cache-pool|vdo-pool
730              The LV type, also known as "segment type" or "segtype".  See
731              usage descriptions for the specific ways to use these types.
732              For more information about redundancy and performance (raid<N>,
733              mirror, striped, linear) see lvmraid(7).  For thin provisioning
734              (thin, thin-pool) see lvmthin(7).  For performance caching
735              (cache, cache-pool) see lvmcache(7).  For copy-on-write snap‐
736              shots (snapshot) see usage definitions.  For VDO (vdo) see
737              lvmvdo(7).  Several commands omit an explicit type option
738              because the type is inferred from other options or shortcuts
739              (e.g. --stripes, --mirrors, --snapshot, --virtualsize, --thin,
740              --cache, --vdo).  Use inferred types with care because it can
741              lead to unexpected results.
742
743       --uncache
744              Separates a cache pool from a cache LV, and deletes the unused
745              cache pool LV.  Before the separation, the cache is flushed.
746              Also see --splitcache.
747
748       --usepolicies
749              Perform an operation according to the policy configured in
750              lvm.conf or a profile.
751
752       --vdopool LV
753              The name of a VDO pool LV.  See lvmvdo(7) for more information
754              about VDO usage.
755
756       -v|--verbose ...
757              Set verbose level. Repeat from 1 to 4 times to increase the
758              detail of messages sent to stdout and stderr.
759
760       --version
761              Display version information.
762
763       -V|--virtualsize Size[m|UNIT]
764              The virtual size of a new thin LV.  See lvmthin(7) for more
765              information about LVM thin provisioning.  Using virtual size
766              (-V) and actual size (-L) together creates a sparse LV.
767              lvm.conf global/sparse_segtype_default determines the default
768              segment type used to create a sparse LV.  Anything written to a
769              sparse LV will be returned when reading from it.  Reading from
770              other areas of the LV will return blocks of zeros.  When using a
771              snapshot to create a sparse LV, a hidden virtual device is cre‐
772              ated using the zero target, and the LV has the suffix _vorigin.
773              Snapshots are less efficient than thin provisioning when creat‐
774              ing large sparse LVs (GiB).
775
776       -y|--yes
777              Do not prompt for confirmation interactively but always assume
778              the answer yes. Use with extreme caution.  (For automatic no,
779              see -qq.)
780
781       -Z|--zero y|n
782              For snapshots, this controls zeroing of the first 4KiB of data
783              in the snapshot. If the LV is read-only, the snapshot will not
784              be zeroed.  For thin pools, this controls zeroing of provisioned
785              blocks.  Provisioning of large zeroed chunks negatively impacts
786              performance.
787

VARIABLES

789       VG
790              Volume Group name.  See lvm(8) for valid names.
791
792       LV
793              Logical  Volume  name.  See lvm(8) for valid names.  An LV posi‐
794              tional arg generally includes the VG  name  and  LV  name,  e.g.
795              VG/LV.  LV followed by _<type> indicates that an LV of the given
796              type is required. (raid represents raid<N> type)
797
798       PV
799              Physical Volume name, a device path under  /dev.   For  commands
800              managing physical extents, a PV positional arg generally accepts
801              a suffix indicating a range (or  multiple  ranges)  of  physical
802              extents  (PEs). When the first PE is omitted, it defaults to the
803              start of the device, and when the last PE is omitted it defaults
804              to  end.   Start and end range (inclusive): PV[:PE-PE]...  Start
805              and length range (counting from 0): PV[:PE+PE]...
806
807       Tag
808              Tag name.  See lvm(8) for information about tag names and  using
809              tags in place of a VG, LV or PV.
810
811       String
812              See the option description for information about the string con‐
813              tent.
814
815       Size[UNIT]
816              Size is an input number that accepts an  optional  unit.   Input
817              units are always treated as base two values, regardless of capi‐
818              talization, e.g. 'k' and 'K' both refer to  1024.   The  default
819              input unit is specified by letter, followed by |UNIT.  UNIT rep‐
820              resents other possible input units:  bBsSkKmMgGtTpPeE.   b|B  is
821              bytes,  s|S  is  sectors  of 512 bytes, k|K is kilobytes, m|M is
822              megabytes, g|G is gigabytes, t|T is terabytes, p|P is petabytes,
823              e|E  is  exabytes.  (This should not be confused with the output
824              control --units, where capital letters mean multiple of 1000.)
825

ENVIRONMENT VARIABLES

827       See lvm(8) for information about environment  variables  used  by  lvm.
828       For example, LVM_VG_NAME can generally be substituted for a required VG
829       parameter.
830

ADVANCED USAGE

832       Alternate command forms, advanced command usage,  and  listing  of  all
833       valid syntax for completeness.
834
835       Change the region size of an LV.
836
837       lvconvert -R|--regionsize Size[m|UNIT] LV_raid
838           [ COMMON_OPTIONS ]
839       -
840
841       Change the type of mirror log used by a mirror LV.
842
843       lvconvert --mirrorlog core|disk LV_mirror
844           [ COMMON_OPTIONS ]
845           [ PV ... ]
846       -
847
848       Convert LV to a thin LV, using the original LV as an external origin
849       (infers --type thin).
850
851       lvconvert -T|--thin --thinpool LV LV_linear_striped_thin_cache_raid
852           [ -r|--readahead auto|none|Number ]
853           [ -c|--chunksize Size[k|UNIT] ]
854           [ -Z|--zero y|n ]
855           [    --type thin ]
856           [    --originname LV_new ]
857           [    --poolmetadata LV ]
858           [    --poolmetadatasize Size[m|UNIT] ]
859           [    --poolmetadataspare y|n ]
860           [    --metadataprofile String ]
861           [ COMMON_OPTIONS ]
862       -
863
864       Attach a cache pool to an LV (infers --type cache).
865
866       lvconvert    -H|--cache    --cachepool    LV    LV_linear_striped_thin‐
867       pool_vdo_vdopool_vdopooldata_raid
868           [ -Z|--zero y|n ]
869           [ -r|--readahead auto|none|Number ]
870           [ -c|--chunksize Size[k|UNIT] ]
871           [    --type cache ]
872           [    --cachemetadataformat auto|1|2 ]
873           [    --cachemode writethrough|writeback|passthrough ]
874           [    --cachepolicy String ]
875           [    --cachesettings String ]
876           [    --poolmetadata LV ]
877           [    --poolmetadatasize Size[m|UNIT] ]
878           [    --poolmetadataspare y|n ]
879           [    --metadataprofile String ]
880           [ COMMON_OPTIONS ]
881       -
882
883       Attach a cache to an LV, converts the LV to type cache.
884
885       lvconvert -H|--cache --cachevol LV LV_linear_striped_thinpool_raid
886           [ -Z|--zero y|n ]
887           [ -c|--chunksize Size[k|UNIT] ]
888           [    --cachemetadataformat auto|1|2 ]
889           [    --cachemode writethrough|writeback|passthrough ]
890           [    --cachepolicy String ]
891           [    --cachesettings String ]
892           [    --poolmetadatasize Size[m|UNIT] ]
893           [ COMMON_OPTIONS ]
894       -
895
896       Convert LV to type vdopool.
897
898       lvconvert --vdopool LV_linear_striped_cache_raid
899           [ -n|--name LV_new ]
900           [ -V|--virtualsize Size[m|UNIT] ]
901           [    --type vdo-pool ]
902           [    --compression y|n ]
903           [    --deduplication y|n ]
904           [ COMMON_OPTIONS ]
905       -
906
907       Detach and delete a cache from an LV.
908
909       lvconvert --uncache LV_thinpool_cache_vdopool_writecache
910           [ COMMON_OPTIONS ]
911       -
912
913       Swap metadata LV in a thin pool or cache pool (for repair only).
914
915       lvconvert --swapmetadata --poolmetadata LV LV_thinpool_cachepool
916           [ -c|--chunksize Size[k|UNIT] ]
917           [ COMMON_OPTIONS ]
918       -
919
920       Merge LV that was split from a mirror (variant, use --mergemirrors).
921       Merge thin LV into its origin LV (variant, use --mergethin).
922       Merge COW snapshot LV into its origin (variant, use --mergesnapshot).
923
924       lvconvert --merge VG|LV_linear_striped_snapshot_thin_raid|Tag ...
925           [ -i|--interval Number ]
926           [ COMMON_OPTIONS ]
927       -
928
929       Separate a COW snapshot from its origin LV.
930
931       lvconvert --splitsnapshot LV_snapshot
932           [ COMMON_OPTIONS ]
933       -
934
935       Combine a former COW snapshot (second arg) with a former
936       origin LV (first arg) to reverse a splitsnapshot command.
937
938       lvconvert -s|--snapshot LV LV_linear_striped
939           [ -c|--chunksize Size[k|UNIT] ]
940           [ -Z|--zero y|n ]
941           [    --type snapshot ]
942           [ COMMON_OPTIONS ]
943       -
944
945       Poll LV to continue conversion (also see --startpoll)
946       or waits till conversion/mirror syncing is finished
947
948       lvconvert LV_mirror_raid
949           [ COMMON_OPTIONS ]
950       -
951
952

NOTES

954       This previous command syntax would perform two different operations:
955       lvconvert --thinpool LV1 --poolmetadata LV2
956       If LV1 was not a thin pool, the command would convert  LV1  to  a  thin
957       pool,  optionally  using  a specified LV for metadata.  But, if LV1 was
958       already a thin pool, the command would swap  the  current  metadata  LV
959       with LV2 (for repair purposes.)
960
961       In the same way, this previous command syntax would perform two differ‐
962       ent operations:
963       lvconvert --cachepool LV1 --poolmetadata LV2
964       If LV1 was not a cache pool, the command would convert LV1 to  a  cache
965       pool,  optionally  using  a specified LV for metadata.  But, if LV1 was
966       already a cache pool, the command would swap the  current  metadata  LV
967       with LV2 (for repair purposes.)
968

EXAMPLES

970       Convert a linear LV to a two-way mirror LV.
971       lvconvert --type mirror --mirrors 1 vg/lvol1
972
973       Convert a linear LV to a two-way RAID1 LV.
974       lvconvert --type raid1 --mirrors 1 vg/lvol1
975
976       Convert a mirror LV to use an in-memory log.
977       lvconvert --mirrorlog core vg/lvol1
978
979       Convert a mirror LV to use a disk log.
980       lvconvert --mirrorlog disk vg/lvol1
981
982       Convert a mirror or raid1 LV to a linear LV.
983       lvconvert --type linear vg/lvol1
984
985       Convert a mirror LV to a raid1 LV with the same number of images.
986       lvconvert --type raid1 vg/lvol1
987
988       Convert a linear LV to a two-way mirror LV, allocating new extents from
989       specific PV ranges.
990       lvconvert --mirrors 1 vg/lvol1 /dev/sda:0-15 /dev/sdb:0-15
991
992       Convert a mirror LV to a linear LV, freeing  physical  extents  from  a
993       specific PV.
994       lvconvert --type linear vg/lvol1 /dev/sda
995
996       Split one image from a mirror or raid1 LV, making it a new LV.
997       lvconvert --splitmirrors 1 --name lv_split vg/lvol1
998
999       Split one image from a raid1 LV, and track changes made to the raid1 LV
1000       while the split image remains detached.
1001       lvconvert --splitmirrors 1 --trackchanges vg/lvol1
1002
1003       Merge an image (that was previously  created  with  --splitmirrors  and
1004       --trackchanges) back into the original raid1 LV.
1005       lvconvert --mergemirrors vg/lvol1_rimage_1
1006
1007       Replace PV /dev/sdb1 with PV /dev/sdf1 in a raid1/4/5/6/10 LV.
1008       lvconvert --replace /dev/sdb1 vg/lvol1 /dev/sdf1
1009
1010       Replace 3 PVs /dev/sd[b-d]1 with PVs /dev/sd[f-h]1 in a raid1 LV.
1011       lvconvert --replace /dev/sdb1 --replace /dev/sdc1 --replace /dev/sdd1
1012              vg/lvol1 /dev/sd[fgh]1
1013
1014       Replace  the  maximum  of 2 PVs /dev/sd[bc]1 with PVs /dev/sd[gh]1 in a
1015       raid6 LV.
1016       lvconvert --replace /dev/sdb1 --replace /dev/sdc1 vg/lvol1 /dev/sd[gh]1
1017
1018       Convert an LV into a thin LV in the specified thin pool.  The  existing
1019       LV is used as an external read-only origin for the new thin LV.
1020       lvconvert --type thin --thinpool vg/tpool1 vg/lvol1
1021
1022       Convert  an LV into a thin LV in the specified thin pool.  The existing
1023       LV is used as an external read-only origin for the new thin LV, and  is
1024       renamed "external".
1025       lvconvert --type thin --thinpool vg/tpool1
1026              --originname external vg/lvol1
1027
1028       Convert  an  LV to a cache pool LV using another specified LV for cache
1029       pool metadata.
1030       lvconvert --type cache-pool --poolmetadata vg/poolmeta1 vg/lvol1
1031
1032       Convert an LV to a cache LV using the specified cache  pool  and  chunk
1033       size.
1034       lvconvert --type cache --cachepool vg/cpool1 -c 128 vg/lvol1
1035
1036       Detach and keep the cache pool from a cache LV.
1037       lvconvert --splitcache vg/lvol1
1038
1039       Detach and remove the cache pool from a cache LV.
1040       lvconvert --uncache vg/lvol1
1041

SEE ALSO

1043       lvm(8) lvm.conf(5) lvmconfig(8)
1044
1045       pvchange(8)  pvck(8)  pvcreate(8)  pvdisplay(8)  pvmove(8)  pvremove(8)
1046       pvresize(8) pvs(8) pvscan(8)
1047
1048       vgcfgbackup(8) vgcfgrestore(8) vgchange(8) vgck(8)  vgcreate(8)  vgcon‐
1049       vert(8)  vgdisplay(8)  vgexport(8)  vgextend(8)  vgimport(8)  vgimport‐
1050       clone(8) vgmerge(8) vgmknodes(8)  vgreduce(8)  vgremove(8)  vgrename(8)
1051       vgs(8) vgscan(8) vgsplit(8)
1052
1053       lvcreate(8)  lvchange(8)  lvconvert(8)  lvdisplay(8)  lvextend(8) lvre‐
1054       duce(8) lvremove(8) lvrename(8) lvresize(8) lvs(8) lvscan(8)
1055
1056       lvm-fullreport(8) lvm-lvpoll(8) lvm2-activation-generator(8) blkdeacti‐
1057       vate(8) lvmdump(8)
1058
1059       dmeventd(8)  lvmpolld(8)  lvmlockd(8)  lvmlockctl(8)  cmirrord(8) lvmd‐
1060       busd(8)
1061
1062       lvmsystemid(7) lvmreport(7) lvmraid(7) lvmthin(7) lvmcache(7)
1063
1064
1065
1066Red Hat, Inc.          LVM TOOLS 2.03.06(2) (2019-10-23)          LVCONVERT(8)
Impressum