[lvm-devel] master - man: Enhancements to various man pages for cache[-pool] segtypes
Jonathan Brassow
jbrassow at fedoraproject.org
Tue Feb 25 19:29:36 UTC 2014
Gitweb: http://git.fedorahosted.org/git/?p=lvm2.git;a=commitdiff;h=3bb9eda97c6ef2fb6848322e36b2b44a688ed37c
Commit: 3bb9eda97c6ef2fb6848322e36b2b44a688ed37c
Parent: f8bf4d7dfbd0ab44ec035bc61a286388a263fc48
Author: Jonathan Brassow <jbrassow at redhat.com>
AuthorDate: Tue Feb 25 12:17:03 2014 -0600
Committer: Jonathan Brassow <jbrassow at redhat.com>
CommitterDate: Tue Feb 25 12:17:03 2014 -0600
man: Enhancements to various man pages for cache[-pool] segtypes
Better formatting. More consistent naming. Better clarity.
---
man/lvconvert.8.in | 30 +++----
man/lvcreate.8.in | 33 ++++----
man/lvm.8.in | 256 ++++++++++++++++++++++++++++++----------------------
man/lvs.8.in | 2 +-
4 files changed, 179 insertions(+), 142 deletions(-)
diff --git a/man/lvconvert.8.in b/man/lvconvert.8.in
index c496d74..190e221 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 c449eb1..325baad 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 363f6af..39e47d3 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.
+require more than one command to create. The cache and thin provisioning
+types are examples of this.
+
.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.
-
-.SS Creating Cache Logical Volumes
-The steps to create a logical volume of cache 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.
-.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.
-.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 <name>_cdata and <name>_cmeta.
-.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
-<origial name>_corig. Users can perform this step while the device which
-is to be cached is in use.
+.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 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 5c76cf1..95eb25a 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,
More information about the lvm-devel
mailing list