1
0
mirror of git://sourceware.org/git/lvm2.git synced 2025-01-27 18:04:20 +03:00
lvm2/man/lvconvert.8.in

236 lines
7.6 KiB
Groff
Raw Normal View History

.TH LVCONVERT 8 "LVM TOOLS #VERSION#" "Red Hat, Inc" \" -*- nroff -*-
2006-08-18 21:49:19 +00:00
.SH NAME
lvconvert \- convert a logical volume from linear to mirror or snapshot
2006-08-18 21:49:19 +00:00
.SH SYNOPSIS
.B lvconvert
\-m|\-\-mirrors Mirrors [\-\-mirrorlog {disk|core|mirrored}] [\-\-corelog] [\-R|\-\-regionsize MirrorLogRegionSize]
[\-A|\-\-alloc AllocationPolicy]
2009-06-30 18:39:31 +00:00
[\-b|\-\-background] [\-f|\-\-force] [\-i|\-\-interval Seconds]
[\-h|\-?|\-\-help]
2010-04-13 01:54:32 +00:00
[\-\-stripes Stripes [\-I|\-\-stripesize StripeSize]]
[\-\-noudevsync]
2009-06-30 18:39:31 +00:00
[\-v|\-\-verbose] [\-y|\-\-yes]
2006-08-18 21:49:19 +00:00
[\-\-version]
.br
LogicalVolume[Path] [PhysicalVolume[Path][:PE[-PE]]...]
.br
2010-01-08 22:00:31 +00:00
.br
.B lvconvert
Add the ability to split an image from the mirror and track changes. ~> lvconvert --splitmirrors 1 --trackchanges vg/lv The '--trackchanges' option allows a user the ability to use an image of a RAID1 array for the purposes of temporary read-only access. The image can be merged back into the array at a later time and only the blocks that have changed in the array since the split will be resync'ed. This operation can be thought of as a partial split. The image is never completely extracted from the array, in that the array reserves the position the device occupied and tracks the differences between the array and the split image via a bitmap. The image itself is rendered read-only and the name (<LV>_rimage_*) cannot be changed. The user can complete the split (permanently splitting the image from the array) by re-issuing the 'lvconvert' command without the '--trackchanges' argument and specifying the '--name' argument. ~> lvconvert --splitmirrors 1 --name my_split vg/lv Merging the tracked image back into the array is done with the '--merge' option (included in a follow-on patch). ~> lvconvert --merge vg/lv_rimage_<n> The internal mechanics of this are relatively simple. The 'raid' device- mapper target allows for the specification of an empty slot in an array via '- -'. This is what will be used if a partial activation of an array is ever required. (It would also be possible to use 'error' targets in place of the '- -'.) If a RAID image is found to be both read-only and visible, then it is considered separate from the array and '- -' is used to hold it's position in the array. So, all that needs to be done to temporarily split an image from the array /and/ cause the kernel target's bitmap to track (aka "mark") changes made is to make the specified image visible and read-only. To merge the device back into the array, the image needs to be returned to the read/write state of the top-level LV and made invisible.
2011-08-18 19:38:26 +00:00
\-\-splitmirrors Images [\-\-name SplitLogicalVolumeName] [\-\-trackchanges]
2010-01-08 22:00:31 +00:00
.br
MirrorLogicalVolume[Path] [SplittablePhysicalVolume[Path][:PE[-PE]]...]
.br
.br
.B lvconvert
\-s|\-\-snapshot [\-c|\-\-chunksize ChunkSize]
[\-h|\-?|\-\-help]
[\-\-noudevsync]
[\-v|\-\-verbose]
[\-Z|\-\-zero y|n]
[\-\-version]
.br
OriginalLogicalVolume[Path] SnapshotLogicalVolume[Path]
.br
.br
.B lvconvert
\-\-merge [\-b|\-\-background] [\-i|\-\-interval Seconds]
[\-h|\-?|\-\-help]
[\-v|\-\-verbose]
[\-\-version]
SnapshotLogicalVolume[Path]...
.br
.br
.B lvconvert
\-\-repair
[\-h|\-?|\-\-help]
[\-v|\-\-verbose]
[\-\-version]
LogicalVolume[Path] [PhysicalVolume[Path]...]
2006-08-18 21:49:19 +00:00
.SH 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.
.br
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.
2006-08-18 21:49:19 +00:00
.SH OPTIONS
See \fBlvm\fP for common options.
.br
Exactly one of \-\-splitmirrors, \-\-mirrors, \-\-repair, \-\-snapshot
or \-\-merge arguments is required.
.br
2006-08-18 21:49:19 +00:00
.TP
.I \-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.
.TP
.I \-\-mirrorlog {disk|core|mirrored}
2007-08-24 21:01:52 +00:00
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.
.TP
.I \-\-corelog
The optional argument "--corelog" is the same as specifying "--mirrorlog core".
2006-10-07 10:47:05 +00:00
.TP
.I \-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.
2007-12-22 12:13:29 +00:00
.TP
.I \-b, \-\-background
Run the daemon in the background.
.TP
.I \-i, \-\-interval Seconds
Report progress as a percentage at regular intervals.
.br
.TP
.I \-\-noudevsync
Disable 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.
2010-01-08 22:00:31 +00:00
.br
.TP
2010-01-08 22:00:31 +00:00
.I \-\-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
Add the ability to split an image from the mirror and track changes. ~> lvconvert --splitmirrors 1 --trackchanges vg/lv The '--trackchanges' option allows a user the ability to use an image of a RAID1 array for the purposes of temporary read-only access. The image can be merged back into the array at a later time and only the blocks that have changed in the array since the split will be resync'ed. This operation can be thought of as a partial split. The image is never completely extracted from the array, in that the array reserves the position the device occupied and tracks the differences between the array and the split image via a bitmap. The image itself is rendered read-only and the name (<LV>_rimage_*) cannot be changed. The user can complete the split (permanently splitting the image from the array) by re-issuing the 'lvconvert' command without the '--trackchanges' argument and specifying the '--name' argument. ~> lvconvert --splitmirrors 1 --name my_split vg/lv Merging the tracked image back into the array is done with the '--merge' option (included in a follow-on patch). ~> lvconvert --merge vg/lv_rimage_<n> The internal mechanics of this are relatively simple. The 'raid' device- mapper target allows for the specification of an empty slot in an array via '- -'. This is what will be used if a partial activation of an array is ever required. (It would also be possible to use 'error' targets in place of the '- -'.) If a RAID image is found to be both read-only and visible, then it is considered separate from the array and '- -' is used to hold it's position in the array. So, all that needs to be done to temporarily split an image from the array /and/ cause the kernel target's bitmap to track (aka "mark") changes made is to make the specified image visible and read-only. To merge the device back into the array, the image needs to be returned to the read/write state of the top-level LV and made invisible.
2011-08-18 19:38:26 +00:00
newly-split-off logical volume using the \-\-name argument, unless
the \-\-trackchanges argument is given.
2010-01-08 22:00:31 +00:00
.TP
.I \-n Name
The name to apply to a logical volume which has been split off from
a mirror logical volume.
.br
2010-01-08 22:00:31 +00:00
Add the ability to split an image from the mirror and track changes. ~> lvconvert --splitmirrors 1 --trackchanges vg/lv The '--trackchanges' option allows a user the ability to use an image of a RAID1 array for the purposes of temporary read-only access. The image can be merged back into the array at a later time and only the blocks that have changed in the array since the split will be resync'ed. This operation can be thought of as a partial split. The image is never completely extracted from the array, in that the array reserves the position the device occupied and tracks the differences between the array and the split image via a bitmap. The image itself is rendered read-only and the name (<LV>_rimage_*) cannot be changed. The user can complete the split (permanently splitting the image from the array) by re-issuing the 'lvconvert' command without the '--trackchanges' argument and specifying the '--name' argument. ~> lvconvert --splitmirrors 1 --name my_split vg/lv Merging the tracked image back into the array is done with the '--merge' option (included in a follow-on patch). ~> lvconvert --merge vg/lv_rimage_<n> The internal mechanics of this are relatively simple. The 'raid' device- mapper target allows for the specification of an empty slot in an array via '- -'. This is what will be used if a partial activation of an array is ever required. (It would also be possible to use 'error' targets in place of the '- -'.) If a RAID image is found to be both read-only and visible, then it is considered separate from the array and '- -' is used to hold it's position in the array. So, all that needs to be done to temporarily split an image from the array /and/ cause the kernel target's bitmap to track (aka "mark") changes made is to make the specified image visible and read-only. To merge the device back into the array, the image needs to be returned to the read/write state of the top-level LV and made invisible.
2011-08-18 19:38:26 +00:00
.TP
.I \-\-trackchanges
This argument is used along with \-\-splitmirrors when the intention
is to use the split-off image temporarily in a read-only fashion. Splitting
off an image in this way allows it to be merged back into the mirror later
- only resynchronizing those portions of the image that have changed since
the split occurred. This option is only available to the "raid1" segment
type.
.br
2010-01-08 22:00:31 +00:00
.TP
.I \-s, \-\-snapshot
Create a snapshot from existing logical volume using another
existing logical volume as its origin.
.TP
.I \-c, \-\-chunksize ChunkSize
Power of 2 chunk size for the snapshot logical volume between 4k and 512k.
.TP
.I \-Z, \-\-zero y|n
Controls zeroing of the first KB of data in the snapshot.
If the volume is read-only the snapshot will not be zeroed.
.TP
.I \-\-merge
Merges a snapshot into its origin volume. To check if your kernel
supports this 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.
.br
2010-01-08 22:00:31 +00:00
.TP
.I \-\-repair
Repair a mirror after suffering a disk failure. 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,
viz. activation/mirror_log_fault_policy or
activation/mirror_device_fault_policy.
.br
2006-08-18 21:49:19 +00:00
.SH Examples
"lvconvert -m1 vg00/lvol1"
.br
converts the linear logical volume "vg00/lvol1" to
a two-way mirror logical volume.
2006-08-18 21:49:19 +00:00
"lvconvert --mirrorlog core vg00/lvol1"
2006-08-18 21:49:19 +00:00
.br
converts a mirror with a disk log to a
mirror with an in-memory log.
"lvconvert --mirrorlog disk vg00/lvol1"
.br
converts a mirror with an in-memory log
to a mirror with a disk log.
2006-08-18 21:49:19 +00:00
"lvconvert -m0 vg00/lvol1"
.br
converts a mirror logical volume to a linear logical
volume.
.br
.br
"lvconvert -s vg00/lvol1 vg00/lvol2"
.br
converts logical volume "vg00/lvol2" to snapshot of original volume "vg00/lvol1"
2006-08-18 21:49:19 +00:00
.br
"lvconvert -m1 vg00/lvol1 /dev/sda:0-15 /dev/sdb:0-15"
.br
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.
.br
"lvconvert -m0 vg00/lvmirror1 /dev/sda
.br
converts mirror logical volume "vg00/lvmirror1" to linear, freeing physical
extents from /dev/sda.
.br
"lvconvert --merge vg00/lvol1_snap"
.br
merges "vg00/lvol1_snap" into its origin.
.br
"lvconvert --merge @some_tag"
.br
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.
2006-08-18 21:49:19 +00:00
.SH SEE ALSO
.BR lvm (8),
.BR vgcreate (8),
.BR lvremove (8),
.BR lvrename (8),
.BR lvextend (8),
.BR lvreduce (8),
.BR lvdisplay (8),
.BR lvscan (8)