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