diff --git a/man/lvconvert.8.in b/man/lvconvert.8.in index c496d7478..190e221be 100644 --- a/man/lvconvert.8.in +++ b/man/lvconvert.8.in @@ -131,7 +131,7 @@ lvconvert \- convert a logical volume from linear to mirror or snapshot .sp .B lvconvert \-\-type cache .RB \-\-cachepool -.IR CachePoolLogicalVolume { Name | Path } +.IR CachePoolLV { Name | Path } .IR LogicalVolume [ Path ] .RB [ \-h | \-? | \-\-help ] .RB [ \-v | \-\-verbose ] @@ -170,12 +170,9 @@ arguments is required. .BR \-b ", " \-\-background Run the daemon in the background. .TP -.BR \-\-cachepool " " \fCachePoolLogicalVolume -This argument is used when converting a logical volume to a cached -logical volume. The CachePoolLogicalVolume is the small and fast -logical volume that will provide the cache for the large slow logical -volume that is being converted. Not that a cache pool LV can only be -used by one logical volume. +.BR \-\-cachepool " " \fCachePoolLV +This argument is necessary when converting a logical volume to a cache LV. +For more information on cache pool LVs and cache LVs, see \fBlvm\fP(8). .TP .BR \-m ", " \-\-mirrors " " \fIMirrors Specifies the degree of the mirror you wish to create. @@ -208,8 +205,8 @@ uses this granularity to track which regions are in sync. .TP .B \-\-type \fISegmentType Used to convert a logical volume to another segment type, like cache-pool, -cache, raid1, mirror. When converting a logical volume to a cached logical -volume, the \-\-cachepool argument is required. +cache, raid1, or thin-pool. When converting a logical volume to a cache LV, +the \-\-cachepool argument is required. .TP .BR \-i ", " \-\-interval " " \fISeconds Report progress as a percentage at regular intervals. @@ -478,16 +475,17 @@ For the read-only external origin use the new name "vg00/external". .sp .B lvconvert \-\-thinpool vg00/lvpool \-\-originname external -T vg00/origin -Convert an existing logical volume to a cache pool logical volume using the -given pool metadata LV. +Convert an existing logical volume to a cache pool LV using the +given cache metadata LV. .sp -.B lvconvert --type cache-pool vg00/my_lv_data \-\-poolmetadata vg00/my_lv_meta -.B lvrename vg00/my_lv_data vg00/my_lv_cachepool +.B lvconvert --type cache-pool --poolmetadata vg00/lvx_meta vg00/lvx_data +.br +.B lvrename vg00/lvx_data vg00/lvx_cachepool -Convert an existing logical volume to a cached logical volume using the given -cachepool. +Convert an existing logical volume to a cache LV using the given +cache pool LV. .sp -.B lvconvert \-\-type cache vg00/my_lv \-\-cachepool vg00/my_lv_cachepool +.B lvconvert \-\-type cache \-\-cachepool vg00/lvx_cachepool vg00/lvx .SH SEE ALSO .BR lvm (8), diff --git a/man/lvcreate.8.in b/man/lvcreate.8.in index c449eb125..325baadca 100644 --- a/man/lvcreate.8.in +++ b/man/lvcreate.8.in @@ -160,13 +160,14 @@ Ignore the flag to skip Logical Volumes during activation. .TP .BR \-\-cachemode " " { writeback | writethrough } -Specifying a cache mode determines when the writes to a cached logical volume -are considered complete. When "writeback" is specified, a write is considered -complete as soon as it is stored in the cache pool (i.e. the smaller faster -device). If "writethough" is specified, a write is considered complete only -when it has been stored in the cache pool and on the origin (i.e. the larger -slower device). While "writethrough" may be slower for writes, it is more -resilient if something should happen to the cache pool device. +Specifying a cache mode determines when the writes to a cache LV +are considered complete. When \fIwriteback\fP is specified, a write is +considered complete as soon as it is stored in the cache pool LV. +If \fIwritethough\fP is specified, a write is considered complete only +when it has been stored in the cache pool LV and on the origin LV. +While \fIwritethrough\fP may be slower for writes, it is more +resilient if something should happen to a device associated with the +cache pool LV. .TP .BR \-c ", " \-\-chunksize " " \fIChunkSize [ \fIbBsSkKmMgG ] @@ -176,7 +177,7 @@ Default unit is in kilobytes. For snapshots the value must be power of 2 between 4KiB and 512KiB and the default value is 4. .br -For cache pools the value must be between 32KiB and 1GiB. The default +For cache pool LVs the value must be between 32KiB and 1GiB. The default is 64KiB. Values must be a multiple of 32KiB. .br For thin pools the value must be between 64KiB and @@ -415,7 +416,7 @@ as is the case with or .IR zero . Note that the cache segment type requires a dm-cache kernel module version -1.3.0 or greater or a kernel version 3.14 or newer. +1.3.0 or greater. .TP .BR \-V ", " \-\-virtualsize " " \fIVirtualSize [ \fIbBsSkKmMgGtTpPeE ] @@ -532,20 +533,20 @@ in vg00 that will use an existing thin pool "vg00/pool": .sp .B lvcreate -s --thinpool vg00/pool origin -Create a cache pool logical volume that can later be used to cache one +Create a cache pool LV that can later be used to cache one logical volume. .sp .B lvcreate --type cache-pool -L 1G -n my_lv_cachepool vg /dev/fast1 -If there is an existing cache pool logical volume, create the large slow -device (i.e. the origin) and link it to the supplied cache pool LV, -creating a cache logical volume. +If there is an existing cache pool LV, create the large slow +device (i.e. the origin LV) and link it to the supplied cache pool LV, +creating a cache LV. .sp .B lvcreate --type cache -L 100G -n my_lv vg/my_lv_cachepool /dev/slow1 -If there is an existing logical volume, create the fast and small -cache pool logical volume and link it to the supplied existing logical -volume (i.e. the origin), creating a cache logical volume. +If there is an existing logical volume, create the small and fast +cache pool LV and link it to the supplied existing logical +volume (i.e. the origin LV), creating a cache LV. .sp .B lvcreate --type cache -L 1G -n my_lv_cachepool vg/my_lv /dev/fast1 diff --git a/man/lvm.8.in b/man/lvm.8.in index 363f6af35..39e47d386 100644 --- a/man/lvm.8.in +++ b/man/lvm.8.in @@ -390,156 +390,194 @@ To view the way the allocation process currently works in any specific case, read the debug logging output, for example by adding \fB\-vvvv\fP to a command. -.SH ADVANCED LOGICAL VOLUME TYPES +.SH LOGICAL VOLUME TYPES Some logical volume types are simple to create and can be done with a single \fBlvcreate\fP(8) command. The linear and striped logical volume types are an example of this. Other logical volume types may -require more than one command to create. The cache and thinly provisioned -types are examples of this. This section is devoted to explaining the -creation and monitoring of the more advanced types of logical volumes in -LVM. While the specifics of each command can be found in their respective -man page, here you will find examples and best practices that may invoke -multiple commands. -.br -.SS Cache Logical Volumes -A cache logical volume is one that allows a small and fast block device to -be used to improve the performance of larger and slower block devices. It -does this by storing the more frequently used blocks on the faster device. -LVM refers to the small fast device as a "cache pool". The large slow device -is called the "origin". Due to requirements from dm-cache (the kernel -driver), LVM further splits the "cache pool" into two devices - the "cache pool -metadata" and "cache pool data" devices. The "cache pool data" device is where -copies of data blocks are kept from the origin to increase speed. The "cache -pool metadata" device holds the accounting information that specifies where -data blocks are stored (e.g. on the "origin" or in the "cache pool data" device). -Users should be familiar with these three devices should they wish to create -the best and most robust cached logical volumes. +require more than one command to create. The cache and thin provisioning +types are examples of this. -.SS Creating Cache Logical Volumes -The steps to create a logical volume of cache type are as follows: +.br +.SS Cache +The \fIcache\fP logical volume type uses a small and fast LV to improve +the performance of a large and slow LV. It does this by storing the +frequently used blocks on the faster LV. +LVM refers to the small fast LV as a \fBcache pool LV\fP. The large +slow LV is called the \fBorigin LV\fP. Due to requirements from dm-cache +(the kernel driver), LVM further splits the cache pool LV into two +devices - the \fBcache data LV\fP and \fBcache metadata LV\fP. The cache +data LV is where copies of data blocks are kept from the +origin LV to increase speed. The cache metadata LV holds the +accounting information that specifies where data blocks are stored (e.g. +on the origin LV or on the cache data LV). Users should be familiar with +these LVs if they wish to create the best and most robust cached +logical volumes. + +.SS Cache Terms +.nf +origin LV OriginLV large slow LV +cache data LV CacheDataLV small fast LV for cache pool data +cache metadata LV CacheMetaLV small fast LV for cache pool metadata +cache pool LV CachePoolLV CacheDataLV + CacheMetaLV +cache LV CacheLV OriginLV + CachePoolLV +.fi + +.SS Cache Steps +The steps to create a logical volume of \fIcache\fP type are as follows: .TP -1) -Create the cache pool's data device. The size of this device directly -correlates to the size of the cache and will ultimately be reported as -the size of the cache pool. +0. +Create an LV or identify an existing LV to be the origin LV. .TP -2) -Create the cache pool's metadata device. The size of this device is -loosely related to the size of the data device. Generally, a user can -size this 1000 times smaller than the cache pool data device with a -minimum size of 8MiB. +1. +Create the cache data LV. The size of this LV is the size of the cache +and will be reported as the size of the cache pool LV. .TP -3) -Create the cache pool by combining the cache pool data and metadata -logical volumes created in steps 1 & 2. When performing this step, -the user can specify behavioral characteristics of the cache pool if -they wish. If no new name is specified when combining, the name of the -cache pool data device will become the name of the cachepool. The sub-LVs -are then renamed to _cdata and _cmeta. +2. +Create the cache metadata LV. +The size of this LV should be 1000 times smaller than the cache data LV +with a minimum size of 8MiB. .TP -4) -Create a cached logical volume by linking the cache pool to an existing -logical volume. The user accessible cached LV keeps the name of the origin, -while the actual origin device becomes a hidden LV with the name -_corig. Users can perform this step while the device which -is to be cached is in use. +3. +Create the cache pool LV by combining the cache data LV (from step 1) +and cache metadata LV (from step 2). When performing this step, +behavioral characteristics of the cache pool LV can be set. +The name of the cache pool LV takes the name of the cache data LV and +the cache data LV and cache metadata LV are renamed +to CachePoolLV_cdata and CachePoolLV_cmeta. +.TP +4. +Create a cache LV by linking the cache pool LV to the origin LV. +The user accessible cache LV takes the name of the origin LV, +while the origin LV becomes a hidden LV with the name +OriginLV_corig. Users can perform this step while the origin LV +is in use. .P -The above steps represent the best way to create a cached logical volume. -They provide access to the most options and have the ability to create the -most robust logical volumes. The examples below will illustrate how these +The steps above represent the best way to create a cache LV. +They provide the most options and have the ability to create the +most robust logical volumes. The examples below illustrate how these steps might be used in practice. +.SS Cache Commands +.nf +0. create OriginLV +lvcreate -L LargeSize -n OriginLV VG SlowPVs + +1. create CacheDataLV +lvcreate -L CacheSize -n CacheDataLV VG FastPVs + +2. create CacheMetaLV +lvcreate -L MetaSize -n CacheMetaLV VG FastPVs + +3. create CachePoolLV +lvconvert --type cache-pool --poolmetadata VG/CacheMetaLV VG/CacheDataLV +CachePoolLV takes the name of CacheDataLV. +CacheDataLV is renamed CachePoolLV_cdata and becomes hidden. +CacheMetaLV is renamed CachePoolLV_cmeta and becomes hidden. + +4. create CacheLV +lvconvert --type cache --cachepool VG/CachePoolLV VG/OriginLV +CacheLV takes the name of OriginLV. +OriginLV is renamed OriginLV_corig and becomes hidden. +.fi + +.SS Cache Examples + .B Example 1: -Creating a simple cache device named, "my_lv". +Creating a simple cache LV. .br .nf -# Create a device we wish to cache (yours may already exist) -Step-0> lvcreate -L 10G -n my_lv my_vg /dev/slow_dev +0. Create the origin LV +# lvcreate -L 10G -n lvx vg /dev/slow_dev -# Create a cache pool data LV -Step-1> lvcreate -L 1G -n cachepool my_vg /dev/fast_dev +1. Create a cache data LV +# lvcreate -L 1G -n lvx_cache vg /dev/fast_dev -# Create a cache pool metadata LV (~1/1000th size of pool data) -Step-2> lvcreate -L 8M -n meta my_vg /dev/fast_dev +2. Create a cache metadata LV (~1/1000th size of CacheDataLV or 8MiB) +# lvcreate -L 8M -n lvx_cache_meta vg /dev/fast_dev -# Combine cache pool sub-LVs into a cache pool. -Step-3> lvconvert --type cache-pool vg/cachepool --poolmetadata vg/meta +3. Create a cache pool LV, combining cache data LV and cache metadata LV +# lvconvert --type cache-pool --poolmetadata vg/lvx_cache_meta \\ + vg/lvx_cache -# Combine the cache pool and origin to create a cached LV -Step-4> lvconvert --type cache my_vg/my_lv --cachepool vg/cachepool +4. Create a cached LV by combining the cache pool LV and origin LV +# lvconvert --type cache --cachepool vg/lvx_cache vg/lvx .fi +.B Example 2: +Creating a cache LV with a fault tolerant cache pool LV. + Users who are concerned about the possibility of failures in their fast devices that could lead to data loss might consider making their cache pool sub-LVs -redundant. Example 2 illustrates how to do just that. Note that only steps -1 & 2 change slightly. - -.B Example 2: -Creating a cache LV with a fault tolerant cache pool. +redundant. Example 2 illustrates how to do that. Note that only steps +1 & 2 change. .nf -# Create a device we wish to cache (yours may already exist) -Step-0> lvcreate -L 10G -n my_lv my_vg /dev/slow_dev +0. Create an origin LV we wish to cache +# lvcreate -L 10G -n lvx vg /dev/slow_devs -# Create a 2-way RAID1 cache pool data LV -Step-01> lvcreate --type raid1 -L 1G -n cachepool my_vg /dev/fast[12] +1. Create a 2-way RAID1 cache data LV +# lvcreate --type raid1 -m 1 -L 1G -n lvx_cache vg \\ + /dev/fast1 /dev/fast2 -# Create a 2-way RAID1 cache pool metadata LV -Step-2> lvcreate --type raid1 -L 8M -n meta my_vg /dev/fast1 /dev/fast2 +2. Create a 2-way RAID1 cache metadata LV +# lvcreate --type raid1 -m 1 -L 8M -n lvx_cache_meta vg \\ + /dev/fast1 /dev/fast2 -# Combine cache pool sub-LVs into a cache pool. -Step-3> lvconvert --type cache-pool vg/cachepool --poolmetadata vg/meta +3. Create a cache pool LV combining cache data LV and cache metadata LV +# lvconvert --type cache-pool --poolmetadata vg/lvx_cache_meta \\ + vg/lvx_cache -# Combine the cache pool and origin to create a cached LV -Step-4> lvconvert --type cache my_vg/my_lv --cachepool vg/cachepool +4. Create a cached LV by combining the cache pool LV and origin LV +# lvconvert --type cache --cachepool vg/lvx_cache vg/lvx .fi -Some users wish to ensure that any data written will be stored both in the -cache pool and on the origin. The loss of the cache device in this case -would not mean the loss of any data. When combining the cache pool's sub-LVs -to form the cachepool, behavioral characteristics of the cache can be -specified - in this case, writethrough vs. writeback. Note that only step -3 is affected in this case. - .B Example 3: -Creating a simple cache device with "writethough" caching. +Creating a simple cache LV with \fIwritethough\fP caching. + +Some users wish to ensure that any data written will be stored both in the +cache pool LV and on the origin LV. The loss of a device associated with +the cache pool LV in this case would not mean the loss of any data. When +combining the cache data LV and the cache metadata LV to form the cache pool +LV, properties of the cache can be specified - in this case, +\fIwritethrough\fP vs. \fIwriteback\fP. Note that only step 3 is affected +in this case. .nf -# Create a device we wish to cache (yours may already exist) -Step-0> lvcreate -L 10G -n my_lv my_vg /dev/slow_dev +0. Create an origin LV we wish to cache (yours may already exist) +# lvcreate -L 10G -n lvx vg /dev/slow -# Create a cache pool data LV -Step-1> lvcreate -L 1G -n cachepool my_vg /dev/fast_dev +1. Create a cache data LV +# lvcreate -L 1G -n lvx_cache vg /dev/fast -# Create a cache pool metadata LV -Step-2> lvcreate -L 8M -n meta my_vg /dev/fast_dev +2. Create a cache metadata LV +# lvcreate -L 8M -n lvx_cache_meta vg /dev/fast -# Combine cache pool sub-LVs into a cache pool and specify "writethough". -Step-3> lvconvert --type cache-pool vg/cachepool \\ - --poolmetadata vg/meta --cachemode writethrough -n cachepool +3. Create a cache pool LV specifying cache mode "writethrough" +# lvconvert --type cache-pool --poolmetadata vg/lvx_cache_meta \\ + --cachemode writethrough vg/lvx_cache -# Combine the cache pool and origin to create a cached LV -Step-4> lvconvert --type cache my_vg/my_lv --cachepool vg/cachepool +4. Create a cache LV by combining the cache pool LV and origin LV +# lvconvert --type cache --cachepool vg/lvx_cache vg/lvx .fi .SS Removing Cache Logical Volumes -If users wish to remove all logical volumes associated with a cached -logical volume, they must remove both top-level, user visible devices. -The cache pool metadata and data logical volumes cannot be removed -directly. If only the cache pool is specfied for removal, any cached -blocks not yet on the origin will be flush, the cache pool will be -removed, and the now un-cached origin will remain. If the user -specifies a cached LV for removal, then the origin device is -removed and only the cache pool will remain. The cache pool can then be -used to create another cache LV with a different origin if desired. +If you wish to remove all logical volumes associated with a cache +LV, you must remove both top-level, user-visible devices. +The cache metadata LV and cache data LV cannot be removed +directly. If only the cache pool LV is specfied for removal, any cached +blocks not yet on the origin LV will be flush, the cache pool LV will be +removed, and the now un-cached origin LV will remain. If the user +specifies a cache LV for removal, then the origin LV is +removed and only the cache pool LV will remain. The cache pool LV can then +be used to create another cache LV with a different origin LV if desired. When users intend to remove all logical volumes associated with a -cached LV, it is generally better to start with the origin and then -remove the cache pool. If the operations are performed in the +cache LV, it is generally better to start with the origin LV and then +remove the cache pool LV. If the operations are performed in the reverse order, the user will have to wait for the contents of the -cache pool to be flushed before they remove the origin. This +cache pool LV to be flushed before the origin LV is removed. This could take some time. .SH DIAGNOSTICS diff --git a/man/lvs.8.in b/man/lvs.8.in index 5c76cf111..95eb25ade 100644 --- a/man/lvs.8.in +++ b/man/lvs.8.in @@ -135,7 +135,7 @@ can also be chosen. The lv_attr bits are: .RS .IP 1 3 -Volume type: (C)ached, (m)irrored, (M)irrored without initial sync, (o)rigin, +Volume type: (C)ache, (m)irrored, (M)irrored without initial sync, (o)rigin, (O)rigin with merging snapshot, (r)aid, (R)aid without initial sync, (s)napshot, merging (S)napshot, (p)vmove, (v)irtual, mirror or raid (i)mage, mirror or raid (I)mage out-of-sync, mirror (l)og device,