Gitweb: http://git.fedorahosted.org/git/?p=lvm2.git;a=commitdiff;h=864ff3cb181183cc…
Commit: 864ff3cb181183ccfabc8a2e3c53ddcd1e36390f
Parent: 50961f43d03aec309dd06e121d03a6fd7b301850
Author: David Teigland <teigland(a)redhat.com>
AuthorDate: Tue Jul 22 15:10:35 2014 -0500
Committer: David Teigland <teigland(a)redhat.com>
CommitterDate: Tue Jul 22 15:12:02 2014 -0500
man: rework lvmcache to match lvmthin
Reorganize and rewrite parts to match lvmthin(7).
---
man/lvmcache.7.in | 251 ++++++++++++++++++++++++++++++++--------------------
1 files changed, 154 insertions(+), 97 deletions(-)
diff --git a/man/lvmcache.7.in b/man/lvmcache.7.in
index 4b21a8a..cc92673 100644
--- a/man/lvmcache.7.in
+++ b/man/lvmcache.7.in
@@ -4,7 +4,7 @@ lvmcache \(em LVM caching
.SH DESCRIPTION
-The \fIcache\fP logical volume type uses a small and fast LV to improve
+The \fBcache\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
@@ -27,59 +27,60 @@ cache pool LV CachePoolLV CacheDataLV + CacheMetaLV
cache LV CacheLV OriginLV + CachePoolLV
.fi
-.SH 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.
+.SH Cache Usage
-.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.
+The primary method for using a cache type logical volume:
-.SH Cache Commands
-0. create OriginLV
-.br
-.B lvcreate \-L LargeSize \-n OriginLV VG SlowPVs
+.SS 0. create OriginLV
-1. create CacheDataLV
+Create an LV or identify an existing LV to be the origin LV.
+
+.B lvcreate \-n OriginLV \-L LargeSize VG SlowPVs
+
+.I Example
.br
-.B lvcreate \-L CacheSize \-n CacheDataLV VG FastPVs
+# lvcreate \-n lvol0 \-L 100G vg
+
-2. create CacheMetaLV
+.SS 1. create CacheDataLV
+
+Create the cache data LV. This LV will hold data blocks from the
+OriginLV. The size of this LV is the size of the cache and will be
+reported as the size of the cache pool LV.
+
+.B lvcreate \-n CacheDataLV \-L CacheSize VG FastPVs
+
+.I Example
.br
-.B lvcreate \-L MetaSize \-n CacheMetaLV VG FastPVs
+# lvcreate \-n cache0 \-L 10G vg /dev/fast
+
-3. create CachePoolLV
+.SS 2. create CacheMetaLV
+
+Create the cache metadata LV. This LV will hold cache pool metadata. The
+size of this LV should be 1000 times smaller than the cache data LV, with
+a minimum size of 8MiB.
+
+.B lvcreate \-n CacheMetaLV \-L MetaSize VG FastPVs
+
+.I Example
.br
-.B lvconvert \-\-cachepool VG/CacheDataLV \-\-poolmetadata VG/CacheMetaLV
+# lvcreate \-n cache0meta \-L 12M vg /dev/fast
+
+.nf
+# lvs -a vg
+ LV VG Attr LSize Pool Origin
+ cache0 vg -wi-a----- 10.00g
+ cache0meta vg -wi-a----- 12.00m
+ lvol0 vg -wi-a----- 100.00g
+.fi
+
+
+.SS 3. create CachePoolLV
+
+Combine the data and metadata LVs into a cache pool LV.
+The behavior of the cache pool LV can be set in this step.
.br
CachePoolLV takes the name of CacheDataLV.
.br
@@ -87,44 +88,108 @@ CacheDataLV is renamed CachePoolLV_cdata and becomes hidden.
.br
CacheMetaLV is renamed CachePoolLV_cmeta and becomes hidden.
-4. create CacheLV
+.B lvconvert \-\-cachepool VG/CacheDataLV \-\-poolmetadata VG/CacheMetaLV
+
+.I Example
.br
-.B lvconvert \-\-type cache \-\-cachepool VG/CachePoolLV VG/OriginLV
+# lvconvert \-\-cachepool vg/cache0 \-\-poolmetadata vg/cache0meta
+
+.nf
+# lvs -a vg
+ LV VG Attr LSize Pool Origin
+ cache0 vg Cwi---C--- 10.00g
+ [cache0_cdata] vg Cwi------- 10.00g
+ [cache0_cmeta] vg ewi------- 12.00m
+ lvol0 vg -wi-a----- 100.00g
+.fi
+
+
+.SS 4. create CacheLV
+
+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. This can be done while the origin LV is in use.
.br
CacheLV takes the name of OriginLV.
.br
OriginLV is renamed OriginLV_corig and becomes hidden.
+.B lvconvert \-\-type cache \-\-cachepool VG/CachePoolLV VG/OriginLV
-.SH Cache Examples
+.I Example
+.br
+# lvconvert \-\-type cache \-\-cachepool vg/cache0 vg/lvol0
+
+.nf
+# lvs -a vg
+ LV VG Attr LSize Pool Origin
+ cache0 vg Cwi---C--- 10.00g
+ [cache0_cdata] vg Cwi-ao---- 10.00g
+ [cache0_cmeta] vg ewi-ao---- 12.00m
+ lvol0 vg Cwi-a-C--- 100.00g cache0 [lvol0_corig]
+ [lvol0_corig] vg -wi-ao---- 100.00g
+.fi
+
+
+.SH Cache Removal
-.SS Example 1
-Create a simple cache LV.
+.SS Removing a cache pool LV without removing its linked origin LV
+\&
+
+This writes back data from the cache pool to the origin LV when necessary,
+then removes the cache pool LV, leaving the un-cached origin LV.
+
+.B lvremove VG/CachePoolLV
+
+.I Example
.nf
-0. Create the origin LV
-# lvcreate \-L 10G \-n lvx vg /dev/slow_dev
+# lvs vg
+ LV VG Attr LSize Pool Origin
+ cache0 vg Cwi---C--- 10.00g
+ lvol0 vg Cwi-a-C--- 100.00g cache0 [lvol0_corig]
-1. Create a cache data LV
-# lvcreate \-L 1G \-n lvx_cache vg /dev/fast_dev
+# lvremove vg/cache0
-2. Create a cache metadata LV (~1/1000th size of CacheDataLV or 8MiB)
-# lvcreate \-L 8M \-n lvx_cache_meta vg /dev/fast_dev
+# lvs vg
+ LV VG Attr LSize Pool Origin
+ lvol0 vg -wi-a----- 100.00g
+.fi
-3. Create a cache pool LV, combining cache data LV and cache metadata LV
-# lvconvert \-\-cachepool vg/lvx_cache \-\-poolmetadata vg/lvx_cache_meta
+.SS Removing an origin LV without removing its linked cache pool LV
-4. Create a cached LV by combining the cache pool LV and origin LV
-# lvconvert \-\-type cache \-\-cachepool vg/lvx_cache vg/lvx
+\&
+
+This removes the origin LV, leaving the cache pool LV which can be linked
+to another origin LV.
+
+.B lvremove VG/CacheLV
+
+.I Example
+.nf
+# lvs vg
+ LV VG Attr LSize Pool Origin
+ cache0 vg Cwi---C--- 10.00g
+ lvol0 vg Cwi-a-C--- 100.00g cache0 [lvol0_corig]
+
+# lvremove vg/lvol0
+
+# lvs vg
+ LV VG Attr LSize Pool Origin
+ cache0 vg Cwi---C--- 10.00g
.fi
-.SS Example 2
-Create 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.
+.SH Cache Topics
+
+.SS Tolerate device failures in a 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.
.nf
0. Create an origin LV we wish to cache
@@ -145,16 +210,16 @@ redundant. Example 2 illustrates how to do that. Note that only steps
# lvconvert \-\-type cache \-\-cachepool vg/lvx_cache vg/lvx
.fi
-.SS Example 3
-Create a simple cache LV with \fIwritethough\fP caching.
+.SS Writethough 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.
+\&
+
+Writethrough caching ensures 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.
.nf
0. Create an origin LV we wish to cache (yours may already exist)
@@ -174,35 +239,27 @@ in this case.
# lvconvert \-\-type cache \-\-cachepool vg/lvx_cache vg/lvx
.fi
-.SH Cache Removal
-
-.SS Removing a cache pool LV without removing an associated origin LV
+.SS Spare metadata LV
-This writes back data from the cache pool to the origin LV, then removes
-the cache pool LV, leaving the un-cached origin LV. (If the origin LV
-will also be removed, the data flushing can be avoided; see "Removing
-both" below.)
+\&
-.B lvremove VG/CachePoolLV
+See
+.BR lvmthin (7)
+for a description of the "pool metadata spare" LV.
+The same concept is used for cache pools.
-.SS Removing both an origin LV and its associated cache pool LV
+.SS Automatic pool metadata LV
-This removes the cache LV, which includes removing both the origin LV and
-its associated cache pool LV. Data blocks from the cache pool are not
-written back to the origin LV.
+\&
-.B lvremove VG/CacheLV
+A cache data LV can be converted to cache pool LV without specifying a
+cache pool metadata LV. LVM will automatically create a metadata LV from
+the same VG.
-./" .SS Separating a cache pool LV from an origin LV
-./" This writes back data from the cache pool to the origin LV, then removes
-./" the association between the cache pool LV and the origin LV.
-./" .br
-./" Not yet implemented.
+.B lvcreate -n CacheDataLV -L CacheSize VG
+.br
+.B lvconvert --cachepool VG/CacheDataLV
-./" .SS Removing an origin LV without removing an associated cache pool LV
-./" Separate the cache pool LV from the origin LV, then remove the origin LV.
-./" .br
-./" Not yet implemented.
.SH SEE ALSO
.BR lvm.conf (5),
Gitweb: http://git.fedorahosted.org/git/?p=lvm2.git;a=commitdiff;h=fe5b282a4a51bcc2…
Commit: fe5b282a4a51bcc2780da9ef7ab298d97c45f3db
Parent: 1fe487043dadf189b08b9862f45d21438f197cf2
Author: David Teigland <teigland(a)redhat.com>
AuthorDate: Mon Jul 21 15:41:42 2014 -0500
Committer: David Teigland <teigland(a)redhat.com>
CommitterDate: Mon Jul 21 15:41:42 2014 -0500
man: lvmcache updates
- use the lvconvert --cachepool syntax to match the lvmthin style
- rewrite removal information
- very minor formatting adjustments
---
man/lvmcache.7.in | 101 +++++++++++++++++++++++++++++++---------------------
1 files changed, 60 insertions(+), 41 deletions(-)
diff --git a/man/lvmcache.7.in b/man/lvmcache.7.in
index 87fb9f4..4b21a8a 100644
--- a/man/lvmcache.7.in
+++ b/man/lvmcache.7.in
@@ -18,7 +18,7 @@ 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
+.SH Cache Terms
.nf
origin LV OriginLV large slow LV
cache data LV CacheDataLV small fast LV for cache pool data
@@ -27,7 +27,7 @@ cache pool LV CachePoolLV CacheDataLV + CacheMetaLV
cache LV CacheLV OriginLV + CachePoolLV
.fi
-.SS Cache Steps
+.SH Cache Steps
The steps to create a logical volume of \fIcache\fP type are as follows:
.TP
0.
@@ -63,34 +63,43 @@ 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
+.SH Cache Commands
+
0. create OriginLV
-lvcreate \-L LargeSize \-n OriginLV VG SlowPVs
+.br
+.B lvcreate \-L LargeSize \-n OriginLV VG SlowPVs
1. create CacheDataLV
-lvcreate \-L CacheSize \-n CacheDataLV VG FastPVs
+.br
+.B lvcreate \-L CacheSize \-n CacheDataLV VG FastPVs
2. create CacheMetaLV
-lvcreate \-L MetaSize \-n CacheMetaLV VG FastPVs
+.br
+.B lvcreate \-L MetaSize \-n CacheMetaLV VG FastPVs
3. create CachePoolLV
-lvconvert \-\-type cache-pool \-\-poolmetadata VG/CacheMetaLV VG/CacheDataLV
+.br
+.B lvconvert \-\-cachepool VG/CacheDataLV \-\-poolmetadata VG/CacheMetaLV
+.br
CachePoolLV takes the name of CacheDataLV.
+.br
CacheDataLV is renamed CachePoolLV_cdata and becomes hidden.
+.br
CacheMetaLV is renamed CachePoolLV_cmeta and becomes hidden.
4. create CacheLV
-lvconvert \-\-type cache \-\-cachepool VG/CachePoolLV VG/OriginLV
+.br
+.B lvconvert \-\-type cache \-\-cachepool VG/CachePoolLV VG/OriginLV
+.br
CacheLV takes the name of OriginLV.
+.br
OriginLV is renamed OriginLV_corig and becomes hidden.
-.fi
-.SS Cache Examples
-.B Example 1:
-Creating a simple cache LV.
-.br
+.SH Cache Examples
+
+.SS Example 1
+Create a simple cache LV.
.nf
0. Create the origin LV
@@ -103,15 +112,14 @@ Creating a simple cache LV.
# 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
+# lvconvert \-\-cachepool vg/lvx_cache \-\-poolmetadata vg/lvx_cache_meta
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.
+.SS Example 2
+Create 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
@@ -131,15 +139,14 @@ redundant. Example 2 illustrates how to do that. Note that only steps
/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
+# lvconvert \-\-cachepool vg/lvx_cache \-\-poolmetadata vg/lvx_cache_meta
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.
+.SS Example 3
+Create 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
@@ -160,30 +167,42 @@ in this case.
# 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
+# lvconvert \-\-cachepool vg/lvx_cache \-\-poolmetadata vg/lvx_cache_meta \\
+ \-\-cachemode writethrough
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 Cache Removal
+
+.SS Removing a cache pool LV without removing an associated origin LV
+
+This writes back data from the cache pool to the origin LV, then removes
+the cache pool LV, leaving the un-cached origin LV. (If the origin LV
+will also be removed, the data flushing can be avoided; see "Removing
+both" below.)
+
+.B lvremove VG/CachePoolLV
+
+.SS Removing both an origin LV and its associated cache pool LV
+
+This removes the cache LV, which includes removing both the origin LV and
+its associated cache pool LV. Data blocks from the cache pool are not
+written back to the origin LV.
+
+.B lvremove VG/CacheLV
+
+./" .SS Separating a cache pool LV from an origin LV
+./" This writes back data from the cache pool to the origin LV, then removes
+./" the association between the cache pool LV and the origin LV.
+./" .br
+./" Not yet implemented.
+
+./" .SS Removing an origin LV without removing an associated cache pool LV
+./" Separate the cache pool LV from the origin LV, then remove the origin LV.
+./" .br
+./" Not yet implemented.
.SH SEE ALSO
.BR lvm.conf (5),
Gitweb: http://git.fedorahosted.org/git/?p=lvm2.git;a=commitdiff;h=513fd029a6354705…
Commit: 513fd029a635470522e1c8a9cdddb70eec39474a
Parent: 8c231a5f4d8e3e309dd018c92644580d06b11dd1
Author: Alasdair G Kergon <agk(a)redhat.com>
AuthorDate: Mon Jul 21 15:50:47 2014 +0100
Committer: Alasdair G Kergon <agk(a)redhat.com>
CommitterDate: Mon Jul 21 15:50:47 2014 +0100
config: Adjust description of activation_mode.
---
WHATS_NEW | 3 ++-
conf/example.conf.in | 32 +++++++++++++++-----------------
lib/activate/activate.c | 1 +
3 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/WHATS_NEW b/WHATS_NEW
index 956b07b..c800dd0 100644
--- a/WHATS_NEW
+++ b/WHATS_NEW
@@ -10,7 +10,8 @@ Version 2.02.108 -
Prompt for confirmation before change LV into a snapshot exception store.
Return proper error codes for some failing lvconvert funtions.
Add initial code to use cache tools (cache_check|dump|repair|restore).
- Add "degraded" activation mode and make it the default.
+ Support lvdisplay --maps for raid.
+ Add --activationmode degraded to activate degraded raid volumes by default.
Add separate lv_active_{locally,remotely,exclusively} LV reporting fields.
Recognize "auto"/"unmanaged" values in selection for appropriate fields only.
Add report/binary_values_as_numeric lvm.conf option for binary values as 0/1.
diff --git a/conf/example.conf.in b/conf/example.conf.in
index 2930054..21c553a 100644
--- a/conf/example.conf.in
+++ b/conf/example.conf.in
@@ -1042,26 +1042,24 @@ activation {
# operation is complete.
polling_interval = 15
- # 'activation_mode' determines how logical volumes are activated if
- # devices are missing. Possible settings are:
- #
- # "complete" - Only allow activation of an LV if all of the PVs
- # that it uses are available (i.e. the volume group
- # is complete). There may be a failed PV in the
- # volume group; but if a particular LV is not on that
- # PV, it is still allowed to activate in this mode.
- #
- # "degraded" - Like "complete", except that RAID logical volumes of
- # segment type "raid{1,4,5,6,10}" are activated if
- # they have sufficient redundancy to present the entire
- # addressable range of the logical volume.
- #
- # "partial" - Allow activation for any logical volume - even if
- # a missing or failed PV would cause a portion of the
- # logical volume to be inaccessible. (E.g. a stripe
- # volume that has lost one of its members would be
- # unable to access a portion of the logical volume.)
- # This setting is not recommended for normal use.
+ # 'activation_mode' determines how Logical Volumes are activated if
+ # any devices are missing. Possible settings are:
+ #
+ # "complete" - Only allow activation of an LV if all of the Physical
+ # Volumes it uses are present. Other PVs in the Volume
+ # Group may be missing.
+ #
+ # "degraded" - Like "complete", but additionally RAID Logical Volumes of
+ # segment type raid1, raid4, raid5, radid6 and raid10 will
+ # be activated if there is no data loss, i.e. they have
+ # sufficient redundancy to present the entire addressable
+ # range of the Logical Volume.
+ #
+ # "partial" - Allows the activation of any Logical Volume even if
+ # a missing or failed PV could cause data loss with a
+ # portion of the Logical Volume inaccessible.
+ # This setting should not normally be used, but may
+ # sometimes assist with data recovery.
#
# This setting was introduced in LVM version 2.02.108. It corresponds
# with the '--activationmode' option for lvchange and vgchange.
diff --git a/lib/activate/activate.c b/lib/activate/activate.c
index 70777fd..deb09e2 100644
--- a/lib/activate/activate.c
+++ b/lib/activate/activate.c
@@ -2203,6 +2203,7 @@ out:
return r;
}
+/* FIXME Move this non-activation code elsewhere */
static int _lv_raid_is_redundant(struct logical_volume *lv)
{
struct lv_segment *raid_seg = first_seg(lv);