Gitweb: http://git.fedorahosted.org/git/?p=lvm2.git;a=commitdiff;h=b73a78675576c562b... Commit: b73a78675576c562b8bf510d16dab8a35bf4cb02 Parent: 11bedf1baf6dbc48c7abf9a14f8584d996d00a59 Author: Zdenek Kabelac zkabelac@redhat.com AuthorDate: Thu May 15 12:06:18 2014 +0200 Committer: Zdenek Kabelac zkabelac@redhat.com CommitterDate: Thu May 15 12:13:24 2014 +0200

man: lvmcache

Migrate cache description into man(7) entry (like lvmthin). --- WHATS_NEW | 1 + man/Makefile.in | 11 ++- man/lvm.8.in | 189 +--------------------------------------------------- spec/packages.inc | 1 + 4 files changed, 13 insertions(+), 189 deletions(-)

diff --git a/WHATS_NEW b/WHATS_NEW index 5900bc6..72834a8 100644 --- a/WHATS_NEW +++ b/WHATS_NEW @@ -1,5 +1,6 @@ Version 2.02.107 - ================================== + Move cache description from lvm(8) to lvmcache(7) man page. Display skipped prompt in silent mode. Make reporting commands show help about possible sort keys on '-O help'. Add metadata_percent to lvs_cols. diff --git a/man/Makefile.in b/man/Makefile.in index c6a27d0..dd59555 100644 --- a/man/Makefile.in +++ b/man/Makefile.in @@ -41,6 +41,7 @@ LVMETAD = endif

MAN5=lvm.conf.5 +MAN7= MAN8=lvm-dumpconfig.8 \ lvchange.8 lvconvert.8 lvcreate.8 lvdisplay.8 lvextend.8 lvm.8 \ lvmchange.8 lvmconf.8 lvmdiskscan.8 lvmdump.8 lvmsadc.8 lvmsar.8 \ @@ -61,10 +62,12 @@ ifeq ("@BUILD_CMIRRORD@", "yes") MAN8CLUSTER+=cmirrord.8 endif

+ifneq ("@CACHE@", "none") + MAN7+=lvmcache.7 +endif + ifneq ("@THIN@", "none") - MAN7=lvmthin.7 -else - MAN7= + MAN7+=lvmthin.7 endif

MAN8DM=dmsetup.8 $(DMEVENTDMAN) @@ -75,7 +78,7 @@ MAN8DIR=$(mandir)/man8 MAN8SYSTEMD_GENERATORS=lvm2-activation-generator.8

CLEAN_TARGETS=$(MAN5) $(MAN7) $(MAN8) $(MAN8CLUSTER) $(FSADMMAN) $(BLKDEACTIVATEMAN) $(DMEVENTDMAN) $(MAN8DM) -DISTCLEAN_TARGETS=fsadm.8 clvmd.8 cmirrord.8 dmeventd.8 lvmthin.7 blkdeactivate.8 +DISTCLEAN_TARGETS=fsadm.8 clvmd.8 cmirrord.8 dmeventd.8 lvmcache.7 lvmthin.7 blkdeactivate.8

include $(top_builddir)/make.tmpl

diff --git a/man/lvm.8.in b/man/lvm.8.in index e1063c6..41223b0 100644 --- a/man/lvm.8.in +++ b/man/lvm.8.in @@ -406,191 +406,8 @@ a command. 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 thin provisioning -types are examples of this. - -.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 -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. +require more than one command to create. The cache (\fBlvmcache\fP(7)) +and thin provisioning (\fBlvmthin\fP(7)) types are examples of this.

.SH DIAGNOSTICS All tools return a status code of zero on success or non-zero on failure. @@ -600,6 +417,8 @@ All tools return a status code of zero on success or non-zero on failure. .I $HOME/.lvm_history .SH SEE ALSO .BR lvm.conf (5), +.BR lvmcache (7), +.BR lvmthin (7), .BR lvm\ dumpconfig (8), .BR clvmd (8), .BR lvchange (8), diff --git a/spec/packages.inc b/spec/packages.inc index 16b90e0..5999ab7 100644 --- a/spec/packages.inc +++ b/spec/packages.inc @@ -83,6 +83,7 @@ fi %{_sbindir}/lvmetad %endif %{_mandir}/man5/lvm.conf.5.gz +%{_mandir}/man7/lvmcache.7.gz %{_mandir}/man7/lvmthin.7.gz %{_mandir}/man8/fsadm.8.gz %{_mandir}/man8/lvchange.8.gz