man/lvconvert.8.in

   1 .TH LVCONVERT 8 "LVM TOOLS #VERSION#" "Red Hat, Inc" \" -*- nroff -*-
   2 .SH NAME
   3 lvconvert \- convert a logical volume from linear to mirror or snapshot
   4 .SH SYNOPSIS
   5 .B lvconvert
   6 \-m|\-\-mirrors Mirrors [\-\-mirrorlog {disk|core|mirrored}] [\-\-corelog] [\-R|\-\-regionsize MirrorLogRegionSize]
   7 [\-\-type SegmentType]
   8 [\-A|\-\-alloc AllocationPolicy]
   9 [\-b|\-\-background] [\-f|\-\-force] [\-i|\-\-interval Seconds]
  10 [\-h|\-?|\-\-help]
  11 [\-\-stripes Stripes [\-I|\-\-stripesize StripeSize]]
  12 [\-\-noudevsync]
  13 [\-v|\-\-verbose] [\-y|\-\-yes]
  14 [\-\-version]
  15 .br
  16 LogicalVolume[Path] [PhysicalVolume[Path][:PE[-PE]]...]
  17 .br
  18
  19 .br
  20 .B lvconvert
  21 \-\-splitmirrors Images [\-\-name SplitLogicalVolumeName] [\-\-trackchanges]
  22 .br
  23 MirrorLogicalVolume[Path] [SplittablePhysicalVolume[Path][:PE[-PE]]...]
  24 .br
  25
  26 .br
  27 .B lvconvert
  28 \-s|\-\-snapshot [\-c|\-\-chunksize ChunkSize]
  29 [\-h|\-?|\-\-help]
  30 [\-\-noudevsync]
  31 [\-v|\-\-verbose]
  32 [\-Z|\-\-zero y|n]
  33 [\-\-version]
  34 .br
  35 OriginalLogicalVolume[Path] SnapshotLogicalVolume[Path]
  36 .br
  37
  38 .br
  39 .B lvconvert
  40 \-\-merge [\-b|\-\-background] [\-i|\-\-interval Seconds]
  41 [\-h|\-?|\-\-help]
  42 [\-v|\-\-verbose]
  43 [\-\-version]
  44 LogicalVolume[Path]...
  45 .br
  46
  47 .br
  48 .B lvconvert
  49 \-\-repair
  50 [\-h|\-?|\-\-help]
  51 [\-v|\-\-verbose]
  52 [\-\-version]
  53 LogicalVolume[Path] [PhysicalVolume[Path]...]
  54
  55 .br
  56 .B lvconvert
  57 \-\-replace PhysicalVolume
  58 [\-h|\-?|\-\-help]
  59 [\-v|\-\-verbose]
  60 [\-\-version]
  61 LogicalVolume[Path] [PhysicalVolume[Path]...]
  62
  63 .SH DESCRIPTION
  64 lvconvert is used to change the segment type (i.e. linear, mirror, etc) or
  65 characteristics of a logical volume.  For example, it can add or remove the
  66 redundant images of a logical volume, change the log type of a mirror, or
  67 designate a logical volume as a snapshot repository.
  68 .br
  69 If the conversion requires allocation of physical extents (for
  70 example, when converting from linear to mirror) and you specify
  71 one or more PhysicalVolumes (optionally with ranges of physical
  72 extents), allocation of physical extents will be restricted to
  73 these physical extents.  If the conversion frees physical extents
  74 (for example, when converting from a mirror to a linear, or reducing
  75 mirror legs) and you specify one or more PhysicalVolumes,
  76 the freed extents come first from the specified PhysicalVolumes.
  77 .SH OPTIONS
  78 See \fBlvm\fP for common options.
  79 .br
  80 Exactly one of \-\-splitmirrors, \-\-mirrors, \-\-repair, \-\-snapshot
  81 or \-\-merge arguments is required.
  82 .br
  83 .TP
  84 .I \-m, \-\-mirrors Mirrors
  85 Specifies the degree of the mirror you wish to create.
  86 For example, "-m 1" would convert the original logical
  87 volume to a mirror volume with 2-sides; that is, a
  88 linear volume plus one copy.
  89 .TP
  90 .I \-\-mirrorlog {disk|core|mirrored}
  91 Specifies the type of log to use.
  92 The default is disk, which is persistent and requires
  93 a small amount of storage space, usually on a separate device
  94 from the data being mirrored.
  95 Core may be useful for short-lived mirrors: It means the mirror is
  96 regenerated by copying the data from the first device again every
  97 time the device is activated - perhaps, for example, after every reboot.
  98 Using "mirrored" will create a persistent log that is itself mirrored.
  99 .TP
 100 .I \-\-corelog
 101 The optional argument "--corelog" is the same as specifying "--mirrorlog core".
 102 .TP
 103 .I \-R, \-\-regionsize MirrorLogRegionSize
 104 A mirror is divided into regions of this size (in MB), and the mirror log
 105 uses this granularity to track which regions are in sync.
 106 .TP
 107 .I \-\-type SegmentType
 108 Used to convert a logical volume to another segment type or to explicitly state
 109 the desired RAID1 segment type ("mirror" or "raid1") when converting a linear
 110 logical volume to a mirror with the '-m' argument.
 111 .TP
 112 .I \-b, \-\-background
 113 Run the daemon in the background.
 114 .TP
 115 .I \-i, \-\-interval Seconds
 116 Report progress as a percentage at regular intervals.
 117 .br
 118 .TP
 119 .I \-\-noudevsync
 120 Disable udev synchronisation. The
 121 process will not wait for notification from udev.
 122 It will continue irrespective of any possible udev processing
 123 in the background.  You should only use this if udev is not running
 124 or has rules that ignore the devices LVM2 creates.
 125 .br
 126
 127
 128 .TP
 129 .I \-\-splitmirrors Images
 130 The number of redundant Images of a mirror to be split off and used
 131 to form a new logical volume.  A name must be supplied for the
 132 newly-split-off logical volume using the \-\-name argument, unless
 133 the \-\-trackchanges argument is given.
 134
 135 .TP
 136 .I \-n Name
 137 The name to apply to a logical volume which has been split off from
 138 a mirror logical volume.
 139 .br
 140
 141 .TP
 142 .I \-\-trackchanges
 143 Used with \-\-splitmirrors on a raid1 device, this tracks changes so that the
 144 read-only detached image can be merged efficiently back into the mirror later.
 145 Only the regions of the detatched device where the data changed get resynchronized.
 146
 147 Please note that this feature is only supported with the new md-based mirror
 148 implementation and not with the original device-mapper mirror implementation.
 149 .br
 150
 151 .TP
 152 .I \-s, \-\-snapshot
 153 Create a snapshot from existing logical volume using another
 154 existing logical volume as its origin.
 155 .TP
 156 .I \-c, \-\-chunksize ChunkSize
 157 Power of 2 chunk size for the snapshot logical volume between 4k and 512k.
 158 .TP
 159 .I \-Z, \-\-zero y|n
 160 Controls zeroing of the first KB of data in the snapshot.
 161 If the volume is read-only the snapshot will not be zeroed.
 162 .TP
 163 .I \-\-merge
 164 Merges a snapshot into its origin volume or merges a raid1 image that has
 165 been split from its mirror with \-\-trackchanges back into its mirror.
 166
 167 To check if your kernel supports the snapshot merge feature, look
 168 for 'snapshot-merge' in the output
 169 of 'dmsetup targets'.  If both the origin and snapshot volume are not
 170 open the merge will start immediately.  Otherwise, the merge will start
 171 the first time either the origin or snapshot are activated and both are closed.
 172 Merging a snapshot into an origin that cannot be closed, for example a root
 173 filesystem, is deferred until the next time the origin volume is activated.
 174 When merging starts, the resulting logical volume will have the origin's name,
 175 minor number and UUID.  While the merge is in progress, reads or writes to the
 176 origin appear as they were directed to the snapshot being merged.  When the
 177 merge finishes, the merged snapshot is removed.  Multiple snapshots may
 178 be specified on the commandline or a @tag may be used to specify
 179 multiple snapshots be merged to their respective origin.
 180 .br
 181
 182 .TP
 183 .I \-\-repair
 184 Repair a mirror after suffering a disk failure. The mirror will be brought back
 185 into a consistent state.  By default, the original number of mirrors will be
 186 restored if possible.  Specify \-y on the command line to skip the prompts.
 187 Use \-f if you do not want any replacement.  Additionally, you may use
 188 \-\-use-policies to use the device replacement policy specified in lvm.conf,
 189 viz. activation/mirror_log_fault_policy or
 190 activation/mirror_device_fault_policy.
 191 .br
 192
 193 .TP
 194 .I \-\-replace PhysicalVolume
 195 Remove the specified device (PhysicalVolume) and replace it with one that is
 196 available in the volume group or from the specific list provided.  This option
 197 is only available to RAID segment types (e.g. "raid1", "raid5", etc).
 198 .br
 199
 200 .SH Examples
 201 "lvconvert -m1 vg00/lvol1"
 202 .br
 203 converts the linear logical volume "vg00/lvol1" to
 204 a two-way mirror logical volume.
 205 .br
 206 .SH Examples
 207 "lvconvert --type raid1 -m1 vg00/lvol1"
 208 .br
 209 converts the linear logical volume "vg00/lvol1" to a two-way RAID1
 210 logical volume.
 211
 212 "lvconvert --mirrorlog core vg00/lvol1"
 213 .br
 214 converts a mirror with a disk log to a
 215 mirror with an in-memory log.
 216
 217 "lvconvert --mirrorlog disk vg00/lvol1"
 218 .br
 219 converts a mirror with an in-memory log
 220 to a mirror with a disk log.
 221
 222 "lvconvert -m0 vg00/lvol1"
 223 .br
 224 converts a mirror logical volume to a linear logical
 225 volume.
 226 .br
 227 "lvconvert --type raid1 vg00/mirror_lv"
 228 .br
 229 converts a mirror logical volume to a RAID1 logical volume with the same
 230 number of images.
 231 .br
 232
 233 .br
 234 "lvconvert -s vg00/lvol1 vg00/lvol2"
 235 .br
 236 converts logical volume "vg00/lvol2" to snapshot of original volume "vg00/lvol1"
 237
 238 .br
 239 "lvconvert -m1 vg00/lvol1 /dev/sda:0-15 /dev/sdb:0-15"
 240 .br
 241 converts linear logical volume "vg00/lvol1" to a two-way mirror, using physical
 242 extents /dev/sda:0-15 and /dev/sdb:0-15 for allocation of new extents.
 243
 244 .br
 245 "lvconvert -m0 vg00/lvmirror1 /dev/sda"
 246 .br
 247 converts mirror logical volume "vg00/lvmirror1" to linear, freeing physical
 248 extents from /dev/sda.
 249
 250 .br
 251 "lvconvert --merge vg00/lvol1_snap"
 252 .br
 253 merges "vg00/lvol1_snap" into its origin.
 254
 255 .br
 256 "lvconvert --merge @some_tag"
 257 .br
 258 If vg00/lvol1, vg00/lvol2, and vg00/lvol3 are all tagged with "some_tag"
 259 each snapshot logical volume will be merged serially, e.g.: vg00/lvol1,
 260 then vg00/lvol2, then vg00/lvol3.  If --background were used it would start
 261 all snapshot logical volume merges in parallel.
 262
 263 .br
 264 "lvconvert --splitmirrors 1 --name lv_split vg00/lvmirror1"
 265 .br
 266 Extract one image from the mirror, making it a new logical volume named
 267 "lv_split".  The mirror the image is extracted from is reduced accordingly.
 268 If it was a 2-way mirror (created with '-m 1'), then the resulting original
 269 volume will be linear.
 270
 271 .br
 272 "lvconvert --splitmirrors 1 --trackchanges vg00/lv_raid1"
 273 .br
 274 A mirrored logical volume created with --type raid1 can use the '\-\-trackchanges' argument when splitting
 275 off an image.
 276
 277 Detach one image from the mirrored logical volume lv_raid1 as a separate
 278 read-only device and track the changes made to the mirror while it is detached.
 279 The split-off device has a name of the form lv_raid1_rimage_N, where N is
 280 a number, and it cannot be renamed.
 281
 282 .br
 283 "lvconvert --merge vg00/lv_raid1_rimage_1"
 284 .br
 285 Merge an image that was detached temporarily from its mirror with
 286 the '\-\-trackchanges' argument back into its original mirror and
 287 bring its contents back up-to-date.
 288
 289 .br
 290 "lvconvert --replace /dev/sdb1 vg00/my_raid1 /dev/sdf1"
 291 .br
 292 Replace the physical volume "/dev/sdb1" in the RAID1 logical volume "my_raid1"
 293 with the specified physical volume "/dev/sdf1".  Had the argument "/dev/sdf1"
 294 been left out, lvconvert would attempt to find a suitable device from those
 295 available in the volume group.
 296
 297 .SH SEE ALSO
 298 .BR lvm (8),
 299 .BR vgcreate (8),
 300 .BR lvremove (8),
 301 .BR lvrename (8),
 302 .BR lvextend (8),
 303 .BR lvreduce (8),
 304 .BR lvdisplay (8),
 305 .BR lvscan (8)