1LVMCACHE(7)                                                        LVMCACHE(7)
2
3
4

NAME

6       lvmcache — LVM caching
7
8

DESCRIPTION

10       An lvm(8) cache Logical Volume (LV) uses a small and fast LV to improve
11       the performance of a large and slow LV.  It does this  by  storing  the
12       frequently  used blocks on the faster LV.  LVM refers to the small fast
13       LV as a cache pool LV.  The large slow LV is called the origin LV.  Due
14       to  requirements  from dm-cache (the kernel driver), LVM further splits
15       the cache pool LV into two devices - the cache data LV and cache  meta‐
16       data  LV.   The  cache  data LV is where copies of data blocks are kept
17       from the origin LV to increase speed.  The cache metadata LV holds  the
18       accounting  information  that  specifies  where  data blocks are stored
19       (e.g.  on the origin LV or on the cache  data  LV).   Users  should  be
20       familiar with these LVs if they wish to create the best and most robust
21       cached LVs.  All of these associated LVs must be  in  the  same  Volume
22       Group (VG).
23
24

Cache Terms

26       origin LV           OriginLV      large slow LV
27       cache data LV       CacheDataLV   small fast LV for cache pool data
28       cache metadata LV   CacheMetaLV   small fast LV for cache pool metadata
29       cache pool LV       CachePoolLV   CacheDataLV + CacheMetaLV
30       cache LV            CacheLV       OriginLV + CachePoolLV
31
32

Cache Usage

34       The primary method for using a cache type LV:
35
36
37
38   0. create OriginLV
39       Create an LV or identify an existing LV to be the origin LV.
40
41       lvcreate -n OriginLV -L LargeSize VG SlowPVs
42
43       Example
44       # lvcreate -n lvol0 -L 100G vg /dev/slow
45
46
47
48   1. create CacheDataLV
49       Create  the  cache  data  LV.   This  LV will hold data blocks from the
50       OriginLV.  The size of this LV is the size of the  cache  and  will  be
51       reported as the size of the cache pool LV.
52
53       lvcreate -n CacheDataLV -L CacheSize VG FastPVs
54
55       Example
56       # lvcreate -n cache0 -L 10G vg /dev/fast
57
58
59
60   2. create CacheMetaLV
61       Create  the  cache metadata LV.  This LV will hold cache pool metadata.
62       The size of this LV should be 1000 times smaller than  the  cache  data
63       LV, with a minimum size of 8MiB.
64
65       lvcreate -n CacheMetaLV -L MetaSize VG FastPVs
66
67       Example
68       # lvcreate -n cache0meta -L 12M vg /dev/fast
69
70       # lvs -a vg
71         LV         VG   Attr       LSize   Pool Origin
72         cache0     vg   -wi-a-----  10.00g
73         cache0meta vg   -wi-a-----  12.00m
74         lvol0      vg   -wi-a----- 100.00g
75
76
77
78   3. create CachePoolLV
79       Combine  the  data and metadata LVs into a cache pool LV.  The behavior
80       of the cache pool LV can be set in this step.
81       CachePoolLV takes the name of CacheDataLV.
82       CacheDataLV is renamed CachePoolLV_cdata and becomes hidden.
83       CacheMetaLV is renamed CachePoolLV_cmeta and becomes hidden.
84
85       lvconvert --type cache-pool --poolmetadata VG/CacheMetaLV
86              VG/CacheDataLV
87
88       Example
89       # lvconvert --type cache-pool --poolmetadata vg/cache0meta vg/cache0
90
91       # lvs -a vg
92         LV              VG   Attr       LSize   Pool Origin
93         cache0          vg   Cwi---C---  10.00g
94         [cache0_cdata]  vg   Cwi-------  10.00g
95         [cache0_cmeta]  vg   ewi-------  12.00m
96         lvol0           vg   -wi-a----- 100.00g
97
98
99
100   4. create CacheLV
101       Create a cache LV by linking the cache pool LV to the origin  LV.   The
102       user  accessible  cache  LV  takes the name of the origin LV, while the
103       origin LV becomes a hidden LV with the name OriginLV_corig.   This  can
104       be done while the origin LV is in use.
105       CacheLV takes the name of OriginLV.
106       OriginLV is renamed OriginLV_corig and becomes hidden.
107
108       lvconvert --type cache --cachepool VG/CachePoolLV VG/OriginLV
109
110       Example
111       # lvconvert --type cache --cachepool vg/cache0 vg/lvol0
112
113       # lvs -a vg
114         LV              VG   Attr       LSize   Pool   Origin
115         cache0          vg   Cwi---C---  10.00g
116         [cache0_cdata]  vg   Cwi-ao----  10.00g
117         [cache0_cmeta]  vg   ewi-ao----  12.00m
118         lvol0           vg   Cwi-a-C--- 100.00g cache0 [lvol0_corig]
119         [lvol0_corig]   vg   -wi-ao---- 100.00g
120
121
122

Cache Removal

124   Split a cache pool LV off of a cache LV
125
126
127       A  cache pool LV can be disconnected from a cache LV, leaving an unused
128       cache pool LV, and an uncached origin LV.   This  command  writes  back
129       data from the cache pool to the origin LV when necessary.
130
131       lvconvert --splitcache VG/CacheLV
132
133
134   Removing a cache pool LV without removing its linked origin LV
135
136
137       This  writes back data from the cache pool to the origin LV when neces‐
138       sary, then removes the cache pool LV, leaving the uncached origin LV.
139
140       lvremove VG/CachePoolLV
141
142       An alternative command that also disconnects the cache  pool  from  the
143       cache LV, and deletes the cache pool:
144
145       lvconvert --uncache VG/CacheLV
146
147       Example
148       # lvs vg
149         LV     VG   Attr       LSize   Pool   Origin
150         cache0 vg   Cwi---C---  10.00g
151         lvol0  vg   Cwi-a-C--- 100.00g cache0 [lvol0_corig]
152
153       # lvremove vg/cache0
154
155       # lvs vg
156         LV    VG   Attr       LSize   Pool Origin
157         lvol0 vg   -wi-a----- 100.00g
158
159
160   Removing a cache LV: both origin LV and the cache pool LV
161
162
163       Removing  a  cache  LV  removes both the origin LV and the linked cache
164       pool LV.
165
166       lvremove VG/CacheLV
167
168
169

Cache Topics

171   Tolerate device failures in a cache pool LV
172
173
174       Users who are concerned about the possibility of failures in their fast
175       devices  that could lead to data loss might consider making their cache
176       pool sub-LVs redundant.
177
178       Example
179       0. Create an origin LV we wish to cache
180       # lvcreate -L 10G -n lv1 vg /dev/slow
181
182       1. Create a 2-way RAID1 cache data LV
183       # lvcreate --type raid1 -m 1 -L 1G -n cache1 vg \
184            /dev/fast1 /dev/fast2
185
186       2. Create a 2-way RAID1 cache metadata LV
187       # lvcreate --type raid1 -m 1 -L 8M -n cache1meta vg \
188            /dev/fast1 /dev/fast2
189
190       3. Create a cache pool LV combining cache data LV and cache metadata LV
191       # lvconvert --type cache-pool --poolmetadata vg/cache1meta vg/cache1
192
193       4. Create a cached LV by combining the cache pool LV and origin LV
194       # lvconvert --type cache --cachepool vg/cache1 vg/lv1
195
196
197   Cache mode
198
199
200       The default cache mode is "writethrough".   Writethrough  ensures  that
201       any  data  written  will be stored both in the cache pool LV and on the
202       origin LV.  The loss of a device associated with the cache pool  LV  in
203       this case would not mean the loss of any data.
204
205       A  second  cache  mode  is  "writeback".  Writeback delays writing data
206       blocks from the cache pool back to  the  origin  LV.   This  mode  will
207       increase  performance,  but  the  loss  of a device associated with the
208       cache pool LV can result in lost data.
209
210       With the --cachemode option, the cache mode can be set when creating  a
211       cache  LV,  or changed on an existing cache LV.  The current cache mode
212       of a cache LV can be displayed with the cache_mode reporting option:
213
214       lvs -o+cache_mode VG/CacheLV
215
216       lvm.conf(5) allocation/cache_mode
217       defines the default cache mode.
218
219       Example
220       0. Create an origin LV we wish to cache (yours may already exist)
221       # lvcreate -L 10G -n lv1 vg /dev/slow
222
223       1. Create a cache data LV
224       # lvcreate -L 1G -n cache1 vg /dev/fast
225
226       2. Create a cache metadata LV
227       # lvcreate -L 8M -n cache1meta vg /dev/fast
228
229       3. Create a cache pool LV
230       # lvconvert --type cache-pool --poolmetadata vg/cache1meta vg/cache1
231
232       4. Create a cache LV by combining the cache pool LV and origin LV,
233          and use the writethrough cache mode.
234       # lvconvert --type cache --cachepool vg/cache1 \
235            --cachemode writethrough vg/lv1
236
237
238
239   Cache policy
240
241
242       The cache subsystem has additional per-LV parameters: the cache  policy
243       to  use,  and  possibly tunable parameters for the cache policy.  Three
244       policies are currently available: "smq" is the default policy, "mq"  is
245       an  older  implementation,  and "cleaner" is used to force the cache to
246       write back (flush) all cached writes to the origin LV.
247
248       The "mq" policy has a number of tunable parameters.  The  defaults  are
249       chosen  to be suitable for the majority of systems, but in special cir‐
250       cumstances, changing the settings can improve performance.
251
252       With the --cachepolicy and --cachesettings options,  the  cache  policy
253       and  settings  can  be  set  when creating a cache LV, or changed on an
254       existing cache LV (both options can be  used  together).   The  current
255       cache  policy  and  settings  of  a  cache LV can be displayed with the
256       cache_policy and cache_settings reporting options:
257
258       lvs -o+cache_policy,cache_settings VG/CacheLV
259
260       Example
261       Change the cache policy and settings of an existing cache LV.
262       # lvchange --cachepolicy mq --cachesettings \
263            'migration_threshold=2048 random_threshold=4' vg/lv1
264
265       lvm.conf(5) allocation/cache_policy
266       defines the default cache policy.
267
268       lvm.conf(5) allocation/cache_settings
269       defines the default cache settings.
270
271
272
273   Chunk size
274
275
276       The size of data blocks managed by a cache pool can be  specified  with
277       the  --chunksize option when the cache LV is created.  The default unit
278       is KiB. The value must be a multiple of 32KiB between 32KiB and 1GiB.
279
280       Using a chunk size that is too large can result in wasteful use of  the
281       cache,  where  small reads and writes can cause large sections of an LV
282       to be mapped into the cache.  However, choosing a chunk  size  that  is
283       too  small  can  result  in more overhead trying to manage the numerous
284       chunks that become mapped into the cache.  Overhead  can  include  both
285       excessive  CPU time searching for chunks, and excessive memory tracking
286       chunks.
287
288       Command to display the cache pool LV chunk size:
289       lvs -o+chunksize VG/CacheLV
290
291       lvm.conf(5) cache_pool_chunk_size
292       controls the default chunk size used when creating a cache LV.
293
294       The default value is shown by:
295       lvmconfig --type default allocation/cache_pool_chunk_size
296
297
298
299   Spare metadata LV
300
301
302       See lvmthin(7) for a description of the "pool metadata spare" LV.   The
303       same concept is used for cache pools.
304
305
306   Automatic pool metadata LV
307
308
309       A  cache data LV can be converted to cache pool LV without specifying a
310       cache pool metadata LV.  LVM will automatically create  a  metadata  LV
311       from the same VG.
312
313       lvcreate -n CacheDataLV -L CacheSize VG
314       lvconvert --type cache-pool VG/CacheDataLV
315
316
317
318   Create a new cache LV without an existing origin LV
319
320
321       A  cache  LV  can  be  created  using an existing cache pool without an
322       existing origin LV.  A new origin LV is created and linked to the cache
323       pool in a single step.
324
325       lvcreate --type cache -L LargeSize -n CacheLV
326              --cachepool VG/CachePoolLV VG SlowPVs
327
328
329
330   Single step cache pool LV creation
331
332
333       A  cache  pool LV can be created with a single lvcreate command, rather
334       than using lvconvert on existing LVs.  This one command creates a cache
335       data  LV,  a  cache metadata LV, and combines the two into a cache pool
336       LV.
337
338       lvcreate --type cache-pool -L CacheSize -n CachePoolLV VG FastPVs
339
340
341
342   Convert existing LVs to cache types
343
344
345       When an existing origin LV is converted to a cache  LV,  the  specified
346       cache  pool  may  be a normal LV, rather than a cache pool LV.  In this
347       case, lvm will first convert the normal LV to a cache pool LV.  A  pool
348       metadata LV may optionally be specified.
349
350       lvcreate -n OriginLV -L LargeSize VG
351       lvcreate -n CacheDataLV -L CacheSize VG
352       lvconvert --type cache --cachepool VG/CataDataLV VG/OriginLV
353
354       This is equivalent to:
355
356       lvcreate -n OriginLV -L LargeSize VG
357       lvcreate -n CacheDataLV -L CacheSize VG
358       lvconvert --type cache-pool VG/CacheDataLV
359       lvconvert --type cache --cachepool VG/CachePoolLV VG/OriginLV
360
361
362
363   Cache metadata formats
364
365
366       There are two disk formats for cache metadata.  The metadata format can
367       be specified when a cache pool is created, and cannot be changed.  For‐
368       mat 2 has better performance; it is more compact, and stores dirty bits
369       in a separate btree, which improves the  speed  of  shutting  down  the
370       cache.   With auto, lvm selects the best option provided by the current
371       dm-cache kernel target.
372
373       lvconvert --type cache-pool --cachemetadataformat auto|1|2
374              VG/CacheDataLV
375
376
377

SEE ALSO

379       lvm.conf(5), lvchange(8), lvcreate(8), lvdisplay(8), lvextend(8), lvre‐
380       move(8),  lvrename(8),  lvresize(8),  lvs(8),  vgchange(8), vgmerge(8),
381       vgreduce(8), vgsplit(8)
382
383
384
385Red Hat, Inc          LVM TOOLS 2.02.183(2) (2018-12-07)           LVMCACHE(7)
Impressum