Ubuntu Manpage: lvconvert — convert a logical volume from linear to mirror or snapshot

name
synopsis
description
options
examples
see also

Provided by: lvm2_2.02.133-1ubuntu10_amd64

NAME

       lvconvert — convert a logical volume from linear to mirror or snapshot

SYNOPSIS

       lvconvert  -m|--mirrors  Mirrors  [--type  SegmentType]  [--mirrorlog  {disk|core|mirrored}]  [--corelog]
       [-R|--regionsize  MirrorLogRegionSize]  [--stripes  Stripes  [-I|--stripesize  StripeSize]]   [-A|--alloc
       AllocationPolicy]  [-b|--background]  [-f|--force] [-i|--interval Seconds] [--commandprofile ProfileName]
       [-h|-?|--help]    [--noudevsync]    [-v|--verbose]     [-y|--yes]     [--version]     LogicalVolume[Path]
       [PhysicalVolume[Path][:PE[-PE]]...]

       lvconvert   --split   [--commandprofile   ProfileName]   [-h|-?|--help]   [--noudevsync]   [-v|--verbose]
       SplitableLogicalVolume{Name|Path}

       lvconvert   --splitcache|--uncache   [--commandprofile   ProfileName]    [-h|-?|--help]    [--noudevsync]
       [-v|--verbose] [--version] CacheLogicalVolume{Name|Path}

       lvconvert      --splitmirrors      Images      [--name      SplitLogicalVolumeName]      [--trackchanges]
       MirrorLogicalVolume[Path] [--commandprofile ProfileName] [SplittablePhysicalVolume[Path][:PE[-PE]]...]

       lvconvert --splitsnapshot [--commandprofile  ProfileName]  [-h|-?|--help]  [--noudevsync]  [-v|--verbose]
       [--version] SnapshotLogicalVolume[Path]

       lvconvert   -s|--snapshot   [-c|--chunksize   ChunkSize[bBsSkK]]   [-Z|--zero   {y|n}]  [--commandprofile
       ProfileName]  [-h|-?|--help]  [--noudevsync]   [-v|--verbose]   [--version]   OriginalLogicalVolume[Path]
       SnapshotLogicalVolume[Path]

       lvconvert --merge [-b|--background] [-i|--interval Seconds] [--commandprofile ProfileName] [-h|-?|--help]
       [-v|--verbose] [--version] LogicalVolume[Path]...

       lvconvert  --repair  [--stripes  Stripes  [-I|--stripesize  StripeSize]]  [--commandprofile  ProfileName]
       [-h|-?|--help] [-v|--verbose] [--version] LogicalVolume[Path] [PhysicalVolume[Path]...]

       lvconvert   --replace   PhysicalVolume   [--commandprofile   ProfileName]  [-h|-?|--help]  [-v|--verbose]
       [--version] LogicalVolume[Path] [PhysicalVolume[Path]...]

       lvconvert   --type   thin[-pool]|-T|--thin   [--originname    NewExternalOriginVolumeName]    [--thinpool
       ThinPoolLogicalVolume{Name|Path}         [-c|--chunksize        ChunkSize[bBsSkKmMgG]]        [--discards
       {ignore|nopassdown|passdown}]      [--poolmetadata       ThinPoolMetadataLogicalVolume{Name|Path}       |
       --poolmetadatasize    ThinPoolMetadataSize[bBsSkKmMgG]]   [-r|--readahead   {ReadAheadSectors|auto|none}]
       [--stripes Stripes   [-I|--stripesize StripeSize]]]   [--poolmetadataspare   {y|n}]    [-Z|--zero {y|n}]]
       [--commandprofile          ProfileName]         [-h|-?|--help]         [-v|--verbose]         [--version]
       [[ExternalOrigin|ThinPool]LogicalVolume{Name|Path}] [PhysicalVolume[Path][:PE [-PE]] ...

       lvconvert --type cache[-pool]|-H|--cache [--cachepool CachePoolLogicalVolume{Name|Path}]  [-c|--chunksize
       ChunkSize[bBsSkKmMgG]]  [--cachemode  {writeback|writethrough}]  [--cachepolicy  policy] [--cachesettings
       key=value]     [--poolmetadata     CachePoolMetadataLogicalVolume{Name|Path}     |     --poolmetadatasize
       CachePoolMetadataSize[bBsSkKmMgG]]    [--poolmetadataspare    {y|n}]    [--commandprofile    ProfileName]
       [-h|-?|--help] [-v|--verbose] [--version] LogicalVolume{Name|Path} [PhysicalVolume[Path][:PE[-PE]]...]

DESCRIPTION

       lvconvert is used to change the segment type (i.e. linear, mirror, etc) or characteristics of  a  logical
       volume.   For example, it can add or remove the redundant images of a logical volume, change the log type
       of a mirror, or designate a logical volume as a snapshot repository.
       If the conversion requires allocation of physical extents (for example, when converting  from  linear  to
       mirror)  and  you  specify  one  or  more  PhysicalVolumes  (optionally with ranges of physical extents),
       allocation of physical extents will be restricted to these physical extents.   If  the  conversion  frees
       physical  extents  (for  example, when converting from a mirror to a linear, or reducing mirror legs) and
       you specify one or more PhysicalVolumes, the freed extents come first from the specified PhysicalVolumes.

OPTIONS

See lvm(8) for common options.
Exactly one of --cache, --corelog, --merge, --mirrorlog, --mirrors, --repair, --replace, --snapshot,
--split, --splitcache, --splitsnapshot, --splitmirrors, --thin, --type or --uncache arguments is
required.

-b, --background
Run the daemon in the background.

-H, --cache, --type cache
Converts logical volume to a cached LV with the use of cache pool specified with --cachepool. For
more information on cache pool LVs and cache LVs, see lvmcache(7).

--cachepolicy policy
Only applicable to cached LVs; see also lvmcache(7). Sets the cache policy. mq is the basic policy
name. smq is more advanced version available in newer kernels.

--cachepool CachePoolLV
This argument is necessary when converting a logical volume to a cache LV. For more information
on cache pool LVs and cache LVs, see lvmcache(7).

--cachesettings key=value
Only applicable to cached LVs; see also lvmcache(7). Sets the cache tunable settings. In most use-
cases, default values should be adequate. Special string value default switches setting back to
its default kernel value and removes it from the list of settings stored in lvm2 metadata.

-m, --mirrors Mirrors
Specifies the degree of the mirror you wish to create. For example, "-m 1" would convert the
original logical volume to a mirror volume with 2-sides; that is, a linear volume plus one copy.
There are two implementations of mirroring which correspond to the "raid1" and "mirror" segment
types. The default mirroring segment type is "raid1". If the legacy "mirror" segment type is
desired, the --type argument must be used to explicitly select the desired type. The --mirrorlog
and --corelog options below are only relevant to the legacy "mirror" segment type.

--mirrorlog {disk|core|mirrored}
Specifies the type of log to use. The default is disk, which is persistent and requires a small
amount of storage space, usually on a separate device from the data being mirrored. Core may be
useful for short-lived mirrors: It means the mirror is regenerated by copying the data from the
first device again every time the device is activated - perhaps, for example, after every reboot.
Using mirrored will create a persistent log that is itself mirrored.

--corelog
The optional argument --corelog is the same as specifying --mirrorlog core.

-R, --regionsize MirrorLogRegionSize
A mirror is divided into regions of this size (in MB), and the mirror log uses this granularity to
track which regions are in sync.

--type SegmentType
Used to convert a logical volume to another segment type, like cache, cache-pool, raid1, snapshot,
thin, or thin-pool. When converting a logical volume to a cache LV, the --cachepool argument is
required. When converting a logical volume to a thin LV, the --thinpool argument is required.
See lvmcache(7) for more info about caching support and lvmthin(7) for thin provisioning support.

-i, --interval Seconds
Report progress as a percentage at regular intervals.

--noudevsync
Disables udev synchronisation. The process will not wait for notification from udev. It will
continue irrespective of any possible udev processing in the background. You should only use this
if udev is not running or has rules that ignore the devices LVM2 creates.

--splitmirrors Images
The number of redundant Images of a mirror to be split off and used to form a new logical volume.
A name must be supplied for the newly-split-off logical volume using the --name argument, unless
the --trackchanges argument is given.

-n, --name Name
The name to apply to a logical volume which has been split off from a mirror logical volume.

--trackchanges
Used with --splitmirrors on a raid1 device, this tracks changes so that the read-only detached
image can be merged efficiently back into the mirror later. Only the regions of the detached
device where the data changed get resynchronized.

Please note that this feature is only supported with the new md-based mirror implementation and
not with the original device-mapper mirror implementation.

--split
Separates SplitableLogicalVolume. Option is agregating various split commands and tries to detect
necessary split operation from its arguments.

--splitcache
Separates CacheLogicalVolume from cache pool. Before the logical volume becomes uncached, cache
is flushed. The cache pool volume is then left unused and could be used e.g. for caching another
volume. See also the option --uncache for uncaching and removing cache pool with one command.

--splitsnapshot
Separates SnapshotLogicalVolume from its origin. The volume that is split off contains the chunks
that differ from the origin along with the metadata describing them. This volume can be wiped and
then destroyed with lvremove. The inverse of --snapshot.

-s, --snapshot, --type snapshot
Recreates a snapshot from constituent logical volumes (or copies of them) after having been
separated using --splitsnapshot. For this to work correctly, no changes may be made to the
contents of either volume after the split.

-c, --chunksize ChunkSize[bBsSkKmMgG]
Gives the size of chunk for snapshot, cache pool and thin pool logical volumes. Default unit is
in kilobytes.

For snapshots the value must be power of 2 between 4KiB and 512KiB and the default value is 4.

For cache pools the value must be between 32KiB and 1GiB and the default value is 64.

For thin pools the value must be between 64KiB and 1GiB and the default value starts with 64 and
scales up to fit the pool metadata size within 128MiB, if the pool metadata size is not specified.
The value must be a multiple of 64KiB. (Early kernel support until thin target version 1.4
required the value to be a power of 2. Discards weren't supported for non-power of 2 values until
thin target version 1.5.)

--discards {ignore|nopassdown|passdown}
Specifies whether or not discards will be processed by the thin layer in the kernel and passed
down to the Physical Volume. Options is currently supported only with thin pools. Default is
passdown.

-Z, --zero {y|n}
Controls zeroing of the first 4KiB of data in the snapshot. If the volume is read-only the
snapshot will not be zeroed. For thin pool volumes it controls zeroing of provisioned blocks.
Note: Provisioning of large zeroed chunks negatively impacts performance.

--merge
Merges a snapshot into its origin volume or merges a raid1 image that has been split from its
mirror with --trackchanges back into its mirror.

To check if your kernel supports the snapshot merge feature, look for 'snapshot-merge' in the
output of dmsetup targets. If both the origin and snapshot volume are not open the merge will
start immediately. Otherwise, the merge will start the first time either the origin or snapshot
are activated and both are closed. Merging a snapshot into an origin that cannot be closed, for
example a root filesystem, is deferred until the next time the origin volume is activated. When
merging starts, the resulting logical volume will have the origin's name, minor number and UUID.
While the merge is in progress, reads or writes to the origin appear as they were directed to the
snapshot being merged. When the merge finishes, the merged snapshot is removed. Multiple
snapshots may be specified on the commandline or a @tag may be used to specify multiple snapshots
be merged to their respective origin.

--originname NewExternalOriginVolumeName
The new name for original logical volume, which becomes external origin volume for a thin logical
volume that will use given --thinpool.
Without this option a default name of "lvol<n>" will be generated where <n> is the LVM internal
number of the logical volume. This volume will be read-only and cannot be further modified as
long, as it is being used as the external origin.

--poolmetadata PoolMetadataLogicalVolume{Name|Path}
Specifies cache or thin pool metadata logical volume. The size should be in between 2MiB and
16GiB. Cache pool is specified with the option --cachepool. Thin pool is specified with the
option --thinpool. When the specified pool already exists, the pool's metadata volume will be
swapped with the given LV. Pool properties (like chunk size, discards or zero) are preserved by
default in this case. It can be useful for pool metadata repair or its offline resize, since the
metadata volume is available as regular volume for a user with thin provisioning tools
cache_dump(8), cache_repair(8), cache_restore(8), thin_dump(8), thin_repair(8) and
thin_restore(8).

--poolmetadatasize PoolMetadataSize[bBsSkKmMgG]
Sets the size of cache or thin pool's metadata logical volume, if the pool metadata volume is
undefined. Pool is specified with the option --cachepool or --thinpool. For thin pool supported
value is in the range between 2MiB and 16GiB. The default value is estimated with this formula
(Pool_LV_size / Pool_LV_chunk_size * 64b). Default unit is megabytes.

--poolmetadataspare {y|n}
Controls creation and maintanence of pool metadata spare logical volume that will be used for
automated pool recovery. Only one such volume is maintained within a volume group with the size
of the biggest pool metadata volume. Default is yes.

-r, --readahead {ReadAheadSectors|auto|none}
Sets read ahead sector count of thin pool metadata logical volume. The default value is "auto"
which allows the kernel to choose a suitable value automatically. "None" is equivalent to
specifying zero.

--repair
Repair a mirror after suffering a disk failure or try to fix thin pool metadata.

The mirror will be brought back into a consistent state. By default, the original number of
mirrors will be restored if possible. Specify -y on the command line to skip the prompts. Use -f
if you do not want any replacement. Additionally, you may use --use-policies to use the device
replacement policy specified in lvm.conf(5), viz. activation/mirror_log_fault_policy or
activation/mirror_device_fault_policy.

Thin pool repair automates the use of thin_repair(8) tool. Only inactive thin pool volumes can be
repaired. There is no validation of metadata between kernel and lvm2. This requires further
manual work. After successfull repair the old unmodified metadata are still available in
"<pool>_meta<n>" LV.

--replace PhysicalVolume
Remove the specified device (PhysicalVolume) and replace it with one that is available in the
volume group or from the specific list provided. This option is only available to RAID segment
types (e.g. raid1, raid5, etc).

--stripes Stripes
Gives the number of stripes. This is equal to the number of physical volumes to scatter the
logical volume. This does not apply to existing allocated space, only newly allocated space can be
striped.

-I, --stripesize StripeSize
Gives the number of kilobytes for the granularity of the stripes.
StripeSize must be 2^n (n = 2 to 9) for metadata in LVM1 format. For metadata in LVM2 format, the
stripe size may be a larger power of 2 but must not exceed the physical extent size.

-T, --thin, --type thin
Converts the logical volume into a thin logical volume of the thin pool specified with --thinpool.
The original logical volume ExternalOriginLogicalVolume is renamed into a new read-only logical
volume. For the non-default name for this volume use --originname. The volume cannot be further
modified as long as it is used as an external origin volume for unprovisioned areas of any thin
logical volume.

--thinpool ThinPoolLogicalVolume{Name|Path}
Specifies or converts logical volume into a thin pool's data volume. Content of converted volume
is lost. Thin pool's metadata logical volume can be specified with the option --poolmetadata or
allocated with --poolmetadatasize. See lvmthin(7) for more info about thin provisioning support.

--uncache
Uncaches CacheLogicalVolume. Before the volume becomes uncached, cache is flushed. Unlike with
--splitcache the cache pool volume is removed. This option could be seen as an inverse of
--cache.

Examples

       Converts the linear logical volume "vg00/lvol1" to a two-way mirror logical volume:

       lvconvert -m1 vg00/lvol1

       Converts the linear logical volume "vg00/lvol1" to a two-way RAID1 logical volume:

       lvconvert --type raid1 -m1 vg00/lvol1

       Converts a mirror with a disk log to a mirror with an in-memory log:

       lvconvert --mirrorlog core vg00/lvol1

       Converts a mirror with an in-memory log to a mirror with a disk log:

       lvconvert --mirrorlog disk vg00/lvol1

       Converts a mirror logical volume to a linear logical volume:

       lvconvert -m0 vg00/lvol1

       Converts a mirror logical volume to a RAID1 logical volume with the same number of images:

       lvconvert --type raid1 vg00/mirror_lv

       Converts logical volume "vg00/lvol2" to snapshot of original volume "vg00/lvol1":

       lvconvert -s vg00/lvol1 vg00/lvol2

       Converts linear logical volume "vg00/lvol1" to a two-way mirror, using physical extents /dev/sda:0-15 and
       /dev/sdb:0-15 for allocation of new extents:

       lvconvert -m1 vg00/lvol1 /dev/sda:0-15 /dev/sdb:0-15

       Converts mirror logical volume "vg00/lvmirror1" to linear, freeing physical extents from /dev/sda:

       lvconvert -m0 vg00/lvmirror1 /dev/sda

       Merges "vg00/lvol1_snap" into its origin:

       lvconvert --merge vg00/lvol1_snap

       If  "vg00/lvol1",  "vg00/lvol2"  and  "vg00/lvol3"  are  all tagged with "some_tag" each snapshot logical
       volume  will  be  merged  serially,  e.g.:  "vg00/lvol1",  then  "vg00/lvol2",  then  "vg00/lvol3".    If
       --background were used it would start all snapshot logical volume merges in parallel.

       lvconvert --merge @some_tag

       Extracts  one  image  from  the  mirror, making it a new logical volume named "lv_split".  The mirror the
       image is extracted from is reduced accordingly.  If it was a 2-way mirror (created with '-m 1'), then the
       resulting original volume will be linear.

       lvconvert --splitmirrors 1 --name lv_split vg00/lvmirror1

       A  mirrored  logical  volume created with --type raid1 can use the --trackchanges argument when splitting
       off an image.  Detach one image from the mirrored logical volume lv_raid1 as a separate read-only  device
       and  track  the  changes made to the mirror while it is detached.  The split-off device has a name of the
       form lv_raid1_rimage_N, where N is a number, and it cannot be renamed.

       lvconvert --splitmirrors 1 --trackchanges vg00/lv_raid1

       Merge an image that was detached temporarily from its mirror with the --trackchanges argument  back  into
       its original mirror and bring its contents back up-to-date.

       lvconvert --merge vg00/lv_raid1_rimage_1

       Replaces  the  physical  volume  "/dev/sdb1"  in  the  RAID1 logical volume "my_raid1" with the specified
       physical volume "/dev/sdf1".  Had the argument "/dev/sdf1" been left out, lvconvert would attempt to find
       a suitable device from those available in the volume group.

       lvconvert --replace /dev/sdb1 vg00/my_raid1 /dev/sdf1

       Convert  the  logical volume "vg00/lvpool" into a thin pool with chunk size 128KiB and convert "vg00/lv1"
       into a thin volume using this pool. Original "vg00/lv1" is used as an external  read-only  origin,  where
       all writes to such volume are stored in the "vg00/lvpool".

       lvconvert --type thin --thinpool vg00/lvpool -c 128 lv1

       Convert  the  logical volume "vg00/origin" into a thin volume from the thin pool "vg00/lvpool". This thin
       volume will use "vg00/origin" as an external origin volume for unprovisioned areas in this  volume.   For
       the read-only external origin use the new name "vg00/external".

       lvconvert -T --thinpool vg00/lvpool --originname external vg00/origin

       Convert an existing logical volume to a cache pool LV using the given cache metadata LV.

       lvconvert --type cache-pool --poolmetadata vg00/lvx_meta vg00/lvx_data
       lvrename vg00/lvx_data vg00/lvx_cachepool

       Convert an existing logical volume to a cache LV using the given cache pool LV and chunk size 128KiB.

       lvconvert --cache --cachepool vg00/lvx_cachepool -c 128 vg00/lvx

       Detach cache pool from an existing cached logical volume "vg00/lvol1" and leave cache pool unused.

       lvconvert --splitcache vg00/lvol1

       Drop cache pool from an existing cached logical volume "vg00/lvol1".

       lvconvert --uncache vg00/lvol1

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

Examples

SEE ALSO