Gitweb: http://git.fedorahosted.org/git/?p=lvm2.git;a=commitdiff;h=477351fc4d2f2d0a5... Commit: 477351fc4d2f2d0a55089fb6b6bc1f26e2605f7b Parent: 91284bd9b913f74a0071082d542c3c09d11524f2 Author: Zdenek Kabelac zkabelac@redhat.com AuthorDate: Sun May 18 20:09:47 2014 +0200 Committer: Zdenek Kabelac zkabelac@redhat.com CommitterDate: Sun May 18 20:09:47 2014 +0200

man: lvmcache

separate man page for lvm cache --- man/lvmcache.7.in | 201 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 201 insertions(+), 0 deletions(-)

diff --git a/man/lvmcache.7.in b/man/lvmcache.7.in new file mode 100644 index 0000000..5a09257 --- /dev/null +++ b/man/lvmcache.7.in @@ -0,0 +1,201 @@ +.TH "LVMCACHE" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" """ +.SH NAME +lvmcache - LVM caching + +.SH DESCRIPTION + +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 +0. +Create an LV or identify an existing LV to be the origin LV. +.TP +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 +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 +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 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 LV. +.br + +.nf +0. Create the origin LV +# lvcreate -L 10G -n lvx vg /dev/slow_dev + +1. Create a cache data LV +# lvcreate -L 1G -n lvx_cache 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 + +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 + +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 that. Note that only steps +1 & 2 change. + +.nf +0. Create an origin LV we wish to cache +# lvcreate -L 10G -n lvx vg /dev/slow_devs + +1. Create a 2-way RAID1 cache data LV +# lvcreate --type raid1 -m 1 -L 1G -n lvx_cache 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 + +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 + +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 3: +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 +0. Create an origin LV we wish to cache (yours may already exist) +# lvcreate -L 10G -n lvx vg /dev/slow + +1. Create a cache data LV +# lvcreate -L 1G -n lvx_cache vg /dev/fast + +2. Create a cache metadata LV +# lvcreate -L 8M -n lvx_cache_meta vg /dev/fast + +3. Create a cache pool LV specifying cache mode "writethrough" +# lvconvert --type cache-pool --poolmetadata vg/lvx_cache_meta \ + --cachemode writethrough vg/lvx_cache + +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 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 +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 LV to be flushed before the origin LV is removed. This +could take some time. + +.SH SEE ALSO +.BR lvm.conf (5), +.BR lvchange (8), +.BR lvcreate (8), +.BR lvdisplay (8), +.BR lvextend (8), +.BR lvremove (8), +.BR lvrename (8), +.BR lvresize (8), +.BR lvs (8), +.BR vgchange (8), +.BR vgmerge (8), +.BR vgreduce (8), +.BR vgsplit (8)