mirror of
git://sourceware.org/git/lvm2.git
synced 2024-12-21 13:34:40 +03:00
d71b738c17
Also make the slow device name consistent everywhere. Signed-off-by: Eric Ren <zren@suse.com>
439 lines
12 KiB
Plaintext
439 lines
12 KiB
Plaintext
.TH "LVMCACHE" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\""
|
|
.SH NAME
|
|
lvmcache \(em LVM caching
|
|
|
|
.SH DESCRIPTION
|
|
|
|
An \fBlvm\fP(8) \fBcache\fP Logical Volume (LV) 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
|
|
LVs. All of these associated LVs must be in the same Volume
|
|
Group (VG).
|
|
|
|
.SH 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
|
|
|
|
.SH Cache Usage
|
|
|
|
The primary method for using a cache type LV:
|
|
|
|
|
|
.SS 0. create OriginLV
|
|
|
|
Create an LV or identify an existing LV to be the origin LV.
|
|
|
|
.B lvcreate -n OriginLV -L LargeSize VG SlowPVs
|
|
|
|
.I Example
|
|
.br
|
|
# lvcreate -n lvol0 -L 100G vg /dev/slow
|
|
|
|
|
|
.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
|
|
# lvcreate -n cache0 -L 10G vg /dev/fast
|
|
|
|
|
|
.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
|
|
# 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
|
|
CacheDataLV is renamed CachePoolLV_cdata and becomes hidden.
|
|
.br
|
|
CacheMetaLV is renamed CachePoolLV_cmeta and becomes hidden.
|
|
|
|
.B lvconvert --type cache-pool --poolmetadata VG/CacheMetaLV
|
|
.RS
|
|
.B VG/CacheDataLV
|
|
.RE
|
|
|
|
.I Example
|
|
.br
|
|
# lvconvert --type cache-pool --poolmetadata vg/cache0meta vg/cache0
|
|
|
|
.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
|
|
|
|
.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 Split a cache pool LV off of a cache LV
|
|
|
|
\&
|
|
|
|
A cache pool LV can be disconnected from a cache LV, leaving an
|
|
unused cache pool LV, and an uncached origin LV. This command
|
|
writes back data from the cache pool to the origin LV when necessary.
|
|
|
|
.B lvconvert --splitcache VG/CacheLV
|
|
|
|
.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 uncached origin LV.
|
|
|
|
.B lvremove VG/CachePoolLV
|
|
|
|
An alternative command that also disconnects the cache pool from the cache
|
|
LV, and deletes the cache pool:
|
|
|
|
.B lvconvert --uncache 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/cache0
|
|
|
|
# lvs vg
|
|
LV VG Attr LSize Pool Origin
|
|
lvol0 vg -wi-a----- 100.00g
|
|
.fi
|
|
|
|
.SS Removing a cache LV: both origin LV and the cache pool LV
|
|
|
|
\&
|
|
|
|
Removing a cache LV removes both the origin LV and the linked cache pool
|
|
LV.
|
|
|
|
.B lvremove VG/CacheLV
|
|
|
|
|
|
.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.
|
|
|
|
.I Example
|
|
.nf
|
|
0. Create an origin LV we wish to cache
|
|
# lvcreate -L 10G -n lv1 vg /dev/slow
|
|
|
|
1. Create a 2-way RAID1 cache data LV
|
|
# lvcreate --type raid1 -m 1 -L 1G -n cache1 vg \\
|
|
/dev/fast1 /dev/fast2
|
|
|
|
2. Create a 2-way RAID1 cache metadata LV
|
|
# lvcreate --type raid1 -m 1 -L 8M -n cache1meta 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/cache1meta vg/cache1
|
|
|
|
4. Create a cached LV by combining the cache pool LV and origin LV
|
|
# lvconvert --type cache --cachepool vg/cache1 vg/lv1
|
|
.fi
|
|
|
|
.SS Cache mode
|
|
|
|
\&
|
|
|
|
The default cache mode is "writethrough". Writethrough 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.
|
|
|
|
A second cache mode is "writeback". Writeback delays writing data blocks
|
|
from the cache pool back to the origin LV. This mode will increase
|
|
performance, but the loss of a device associated with the cache pool LV
|
|
can result in lost data.
|
|
|
|
With the --cachemode option, the cache mode can be set when creating a
|
|
cache LV, or changed on an existing cache LV. The current cache mode of a
|
|
cache LV can be displayed with the cache_mode reporting option:
|
|
|
|
.B lvs -o+cache_mode VG/CacheLV
|
|
|
|
.BR lvm.conf (5)
|
|
.B allocation/cache_mode
|
|
.br
|
|
defines the default cache mode.
|
|
|
|
.I Example
|
|
.nf
|
|
0. Create an origin LV we wish to cache (yours may already exist)
|
|
# lvcreate -L 10G -n lv1 vg /dev/slow
|
|
|
|
1. Create a cache data LV
|
|
# lvcreate -L 1G -n cache1 vg /dev/fast
|
|
|
|
2. Create a cache metadata LV
|
|
# lvcreate -L 8M -n cache1meta vg /dev/fast
|
|
|
|
3. Create a cache pool LV
|
|
# lvconvert --type cache-pool --poolmetadata vg/cache1meta vg/cache1
|
|
|
|
4. Create a cache LV by combining the cache pool LV and origin LV,
|
|
and use the writethrough cache mode.
|
|
# lvconvert --type cache --cachepool vg/cache1 \\
|
|
--cachemode writethrough vg/lv1
|
|
.fi
|
|
|
|
|
|
.SS Cache policy
|
|
|
|
\&
|
|
|
|
The cache subsystem has additional per-LV parameters: the cache policy to
|
|
use, and possibly tunable parameters for the cache policy. Three policies
|
|
are currently available: "smq" is the default policy, "mq" is an older
|
|
implementation, and "cleaner" is used to force the cache to write back
|
|
(flush) all cached writes to the origin LV.
|
|
|
|
The "mq" policy has a number of tunable parameters. The defaults are
|
|
chosen to be suitable for the majority of systems, but in special
|
|
circumstances, changing the settings can improve performance.
|
|
|
|
With the --cachepolicy and --cachesettings options, the cache policy
|
|
and settings can be set when creating a cache LV, or changed on an
|
|
existing cache LV (both options can be used together). The current cache
|
|
policy and settings of a cache LV can be displayed with the cache_policy
|
|
and cache_settings reporting options:
|
|
|
|
.B lvs -o+cache_policy,cache_settings VG/CacheLV
|
|
|
|
.I Example
|
|
.nf
|
|
Change the cache policy and settings of an existing cache LV.
|
|
# lvchange --cachepolicy mq --cachesettings \\
|
|
\(aqmigration_threshold=2048 random_threshold=4\(aq vg/lv1
|
|
.fi
|
|
|
|
.BR lvm.conf (5)
|
|
.B allocation/cache_policy
|
|
.br
|
|
defines the default cache policy.
|
|
|
|
.BR lvm.conf (5)
|
|
.B allocation/cache_settings
|
|
.br
|
|
defines the default cache settings.
|
|
|
|
|
|
.SS Chunk size
|
|
|
|
\&
|
|
|
|
The size of data blocks managed by a cache pool can be specified with the
|
|
--chunksize option when the cache LV is created. The default unit
|
|
is KiB. The value must be a multiple of 32KiB between 32KiB and 1GiB.
|
|
|
|
Using a chunk size that is too large can result in wasteful use of the
|
|
cache, where small reads and writes can cause large sections of an LV to
|
|
be mapped into the cache. However, choosing a chunk size that is too
|
|
small can result in more overhead trying to manage the numerous chunks
|
|
that become mapped into the cache. Overhead can include both excessive
|
|
CPU time searching for chunks, and excessive memory tracking chunks.
|
|
|
|
Command to display the cache pool LV chunk size:
|
|
.br
|
|
.B lvs -o+chunksize VG/CacheLV
|
|
|
|
.BR lvm.conf (5)
|
|
.B cache_pool_chunk_size
|
|
.br
|
|
controls the default chunk size used when creating a cache LV.
|
|
|
|
The default value is shown by:
|
|
.br
|
|
.B lvmconfig --type default allocation/cache_pool_chunk_size
|
|
|
|
|
|
.SS Spare metadata LV
|
|
|
|
\&
|
|
|
|
See
|
|
.BR lvmthin (7)
|
|
for a description of the "pool metadata spare" LV.
|
|
The same concept is used for cache pools.
|
|
|
|
.SS Automatic pool metadata LV
|
|
|
|
\&
|
|
|
|
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.
|
|
|
|
.B lvcreate -n CacheDataLV -L CacheSize VG
|
|
.br
|
|
.B lvconvert --type cache-pool VG/CacheDataLV
|
|
|
|
|
|
.SS Create a new cache LV without an existing origin LV
|
|
|
|
\&
|
|
|
|
A cache LV can be created using an existing cache pool without an existing
|
|
origin LV. A new origin LV is created and linked to the cache pool in a
|
|
single step.
|
|
|
|
.B lvcreate --type cache -L LargeSize -n CacheLV
|
|
.RS
|
|
.B --cachepool VG/CachePoolLV VG SlowPVs
|
|
.RE
|
|
|
|
|
|
.SS Single step cache pool LV creation
|
|
|
|
\&
|
|
|
|
A cache pool LV can be created with a single lvcreate command, rather than
|
|
using lvconvert on existing LVs. This one command creates a cache data
|
|
LV, a cache metadata LV, and combines the two into a cache pool LV.
|
|
|
|
.B lvcreate --type cache-pool -L CacheSize -n CachePoolLV VG FastPVs
|
|
|
|
|
|
.SS Convert existing LVs to cache types
|
|
|
|
\&
|
|
|
|
When an existing origin LV is converted to a cache LV, the specified cache
|
|
pool may be a normal LV, rather than a cache pool LV. In this case, lvm
|
|
will first convert the normal LV to a cache pool LV. A pool metadata LV
|
|
may optionally be specified.
|
|
|
|
.B lvcreate -n OriginLV -L LargeSize VG
|
|
.br
|
|
.B lvcreate -n CacheDataLV -L CacheSize VG
|
|
.br
|
|
.B lvconvert --type cache --cachepool VG/CataDataLV VG/OriginLV
|
|
|
|
This is equivalent to:
|
|
|
|
.B lvcreate -n OriginLV -L LargeSize VG
|
|
.br
|
|
.B lvcreate -n CacheDataLV -L CacheSize VG
|
|
.br
|
|
.B lvconvert --type cache-pool VG/CacheDataLV
|
|
.br
|
|
.B lvconvert --type cache --cachepool VG/CachePoolLV VG/OriginLV
|
|
|
|
|
|
.SS Cache metadata formats
|
|
|
|
\&
|
|
|
|
There are two disk formats for cache metadata. The metadata format can be
|
|
specified when a cache pool is created, and cannot be changed.
|
|
Format \fB2\fP has better performance; it is more compact, and stores
|
|
dirty bits in a separate btree, which improves the speed of shutting down
|
|
the cache.
|
|
With \fBauto\fP, lvm selects the best option provided by the current
|
|
dm-cache kernel target.
|
|
|
|
.B lvconvert --type cache-pool --cachemetadataformat auto|1|2
|
|
.RS
|
|
.B VG/CacheDataLV
|
|
.RE
|
|
|
|
|
|
.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)
|