Provided by: lvm2_2.02.133-1ubuntu10_amd64 bug

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

SEE ALSO

       lvm(8),    lvm.conf(5),    lvmcache(7),    lvmthin(7),    lvdisplay(8),
       lvextend(8),    lvreduce(8),   lvremove(8),   lvrename(8),   lvscan(8),
       vgcreate(8),    cache_dump(8),    cache_repair(8),    cache_restore(8),
       thin_dump(8), thin_repair(8), thin_restore(8)