1LVMTHIN(7)                                                          LVMTHIN(7)
2
3
4

NAME

6       lvmthin — LVM thin provisioning
7
8

DESCRIPTION

10       Blocks  in a standard lvm(8) Logical Volume (LV) are allocated when the
11       LV is created, but blocks in a thin provisioned  LV  are  allocated  as
12       they  are  written.   Because of this, a thin provisioned LV is given a
13       virtual size, and can then be much  larger  than  physically  available
14       storage.   The amount of physical storage provided for thin provisioned
15       LVs can be increased later as the need arises.
16
17       Blocks in a standard LV are allocated (during creation) from the Volume
18       Group  (VG),  but blocks in a thin LV are allocated (during use) from a
19       special "thin pool LV".  The thin pool LV contains blocks  of  physical
20       storage,  and blocks in thin LVs just reference blocks in the thin pool
21       LV.
22
23       A thin pool LV must be created before thin LVs can  be  created  within
24       it.   A  thin pool LV is created by combining two standard LVs: a large
25       data LV that will hold blocks for thin LVs, and a metadata LV that will
26       hold  metadata.   The  metadata tracks which data blocks belong to each
27       thin LV.
28
29       Snapshots of thin LVs are efficient because the data blocks common to a
30       thin LV and any of its snapshots are shared.  Snapshots may be taken of
31       thin LVs or of other thin snapshots.  Blocks common to recursive  snap‐
32       shots are also shared in the thin pool.  There is no limit to or degra‐
33       dation from sequences of snapshots.
34
35       As thin LVs or snapshot LVs are written to, they consume data blocks in
36       the  thin  pool.   As  free data blocks in the pool decrease, more free
37       blocks may need to be supplied.  This is done  by  extending  the  thin
38       pool data LV with additional physical space from the VG.  Removing thin
39       LVs or snapshots from the thin pool can also free blocks  in  the  thin
40       pool.   However, removing LVs is not always an effective way of freeing
41       space in a thin pool because the amount is limited  to  the  number  of
42       blocks not shared with other LVs in the pool.
43
44       Incremental  block allocation from thin pools can cause thin LVs to be‐
45       come fragmented.  Standard LVs generally avoid this problem by allocat‐
46       ing all the blocks at once during creation.
47
48
49

Thin Terms

51       ThinDataLV
52              thin data LV
53              large LV created in a VG
54              used by thin pool to store ThinLV blocks
55
56
57       ThinMetaLV
58              thin metadata LV
59              small LV created in a VG
60              used by thin pool to track data block usage
61
62
63       ThinPoolLV
64              thin pool LV
65              combination of ThinDataLV and ThinMetaLV
66              contains ThinLVs and SnapLVs
67
68
69       ThinLV
70              thin LV
71              created from ThinPoolLV
72              appears blank after creation
73
74
75       SnapLV
76              snapshot LV
77              created from ThinPoolLV
78              appears as a snapshot of another LV after creation
79
80
81
82

Thin Usage

84       The primary method for using lvm thin provisioning:
85
86
87   1. create ThinDataLV
88       Create an LV that will hold thin pool data.
89
90       lvcreate -n ThinDataLV -L LargeSize VG
91
92       Example
93       # lvcreate -n pool0 -L 10G vg
94
95
96   2. create ThinMetaLV
97       Create an LV that will hold thin pool metadata.
98
99       lvcreate -n ThinMetaLV -L SmallSize VG
100
101       Example
102       # lvcreate -n pool0meta -L 1G vg
103
104       # lvs
105         LV        VG Attr       LSize
106         pool0     vg -wi-a----- 10.00g
107         pool0meta vg -wi-a----- 1.00g
108
109
110   3. create ThinPoolLV
111       Combine the data and metadata LVs into a thin pool LV.
112       ThinDataLV is renamed to hidden ThinPoolLV_tdata.
113       ThinMetaLV is renamed to hidden ThinPoolLV_tmeta.
114       The new ThinPoolLV takes the previous name of ThinDataLV.
115
116       lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
117
118       Example
119       # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
120
121       # lvs vg/pool0
122         LV    VG Attr       LSize  Pool Origin Data% Meta%
123         pool0 vg twi-a-tz-- 10.00g      0.00   0.00
124
125       # lvs -a
126         LV            VG Attr       LSize
127         pool0         vg twi-a-tz-- 10.00g
128         [pool0_tdata] vg Twi-ao---- 10.00g
129         [pool0_tmeta] vg ewi-ao---- 1.00g
130
131
132   4. create ThinLV
133       Create a new thin LV from the thin pool LV.
134       The thin LV is created with a virtual size.
135       Multiple new thin LVs may be created in the thin pool.
136       Thin LV names must be unique in the VG.
137       The '--type thin' option is inferred from the virtual size option.
138       The --thinpool argument specifies which thin pool will
139       contain the ThinLV.
140
141       lvcreate -n ThinLV -V VirtualSize --thinpool ThinPoolLV VG
142
143       Example
144       Create a thin LV in a thin pool:
145       # lvcreate -n thin1 -V 1T --thinpool pool0 vg
146
147       Create another thin LV in the same thin pool:
148       # lvcreate -n thin2 -V 1T --thinpool pool0 vg
149
150       # lvs vg/thin1 vg/thin2
151         LV    VG Attr       LSize Pool  Origin Data%
152         thin1 vg Vwi-a-tz-- 1.00t pool0        0.00
153         thin2 vg Vwi-a-tz-- 1.00t pool0        0.00
154
155
156   5. create SnapLV
157       Create snapshots of an existing ThinLV or SnapLV.
158       Do not specify -L, --size when creating a thin snapshot.
159       A size argument will cause an old COW snapshot to be created.
160
161       lvcreate -n SnapLV --snapshot VG/ThinLV
162       lvcreate -n SnapLV --snapshot VG/PrevSnapLV
163
164       Example
165       Create first snapshot of an existing ThinLV:
166       # lvcreate -n thin1s1 -s vg/thin1
167
168       Create second snapshot of the same ThinLV:
169       # lvcreate -n thin1s2 -s vg/thin1
170
171       Create a snapshot of the first snapshot:
172       # lvcreate -n thin1s1s1 -s vg/thin1s1
173
174       # lvs vg/thin1s1 vg/thin1s2 vg/thin1s1s1
175         LV        VG Attr       LSize Pool  Origin
176         thin1s1   vg Vwi---tz-k 1.00t pool0 thin1
177         thin1s2   vg Vwi---tz-k 1.00t pool0 thin1
178         thin1s1s1 vg Vwi---tz-k 1.00t pool0 thin1s1
179
180
181   6. activate SnapLV
182       Thin  snapshots are created with the persistent "activation skip" flag,
183       indicated by the "k" attribute.  Use -K with lvchange  or  vgchange  to
184       activate thin snapshots with the "k" attribute.
185
186       lvchange -ay -K VG/SnapLV
187
188       Example
189       # lvchange -ay -K vg/thin1s1
190
191       # lvs vg/thin1s1
192         LV      VG Attr       LSize Pool  Origin
193         thin1s1 vg Vwi-a-tz-k 1.00t pool0 thin1
194
195

Thin Topics

197       Automatic pool metadata LV
198       Specify devices for data and metadata LVs
199       Tolerate device failures using raid
200       Spare metadata LV
201       Metadata check and repair
202       Activation of thin snapshots
203       Removing thin pool LVs, thin LVs and snapshots
204       Manually manage free data space of thin pool LV
205       Manually manage free metadata space of a thin pool LV
206       Using fstrim to increase free space in a thin pool LV
207       Automatically extend thin pool LV
208       Data space exhaustion
209       Metadata space exhaustion
210       Automatic extend settings
211       Zeroing
212       Discard
213       Chunk size
214       Size of pool metadata LV
215       Create a thin snapshot of an external, read only LV
216       Convert a standard LV to a thin LV with an external origin
217       Single step thin pool LV creation
218       Single step thin pool LV and thin LV creation
219       Merge thin snapshots
220       XFS on snapshots
221
222
223
224
225   Automatic pool metadata LV
226
227
228       A  thin data LV can be converted to a thin pool LV without specifying a
229       thin pool metadata LV.  LVM automatically creates a  metadata  LV  from
230       the same VG.
231
232       lvcreate -n ThinDataLV -L LargeSize VG
233       lvconvert --type thin-pool VG/ThinDataLV
234
235       Example
236       # lvcreate -n pool0 -L 10G vg
237       # lvconvert --type thin-pool vg/pool0
238
239       # lvs -a
240         pool0           vg          twi-a-tz--  10.00g
241         [pool0_tdata]   vg          Twi-ao----  10.00g
242         [pool0_tmeta]   vg          ewi-ao----  16.00m
243
244
245
246   Specify devices for data and metadata LVs
247
248
249       The  data  and metadata LVs in a thin pool are best created on separate
250       physical devices.  To do that, specify the device name(s) at the end of
251       the  lvcreate  line.   It can be especially helpful to use fast devices
252       for the metadata LV.
253
254       lvcreate -n ThinDataLV -L LargeSize VG LargePV
255       lvcreate -n ThinMetaLV -L SmallSize VG SmallPV
256       lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
257
258       Example
259       # lvcreate -n pool0 -L 10G vg /dev/sdA
260       # lvcreate -n pool0meta -L 1G vg /dev/sdB
261       # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
262
263       lvm.conf(5) thin_pool_metadata_require_separate_pvs
264       controls the default PV usage for thin pool creation.
265
266
267
268
269   Tolerate device failures using raid
270
271
272       To tolerate device failures, use raid for the pool  data  LV  and  pool
273       metadata LV.  This is especially recommended for pool metadata LVs.
274
275       lvcreate --type raid1 -m 1 -n ThinMetaLV -L SmallSize VG PVA PVB
276       lvcreate --type raid1 -m 1 -n ThinDataLV -L LargeSize VG PVC PVD
277       lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
278
279       Example
280       # lvcreate --type raid1 -m 1 -n pool0 -L 10G vg /dev/sdA /dev/sdB
281       # lvcreate --type raid1 -m 1 -n pool0meta -L 1G vg /dev/sdC /dev/sdD
282       # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
283
284
285
286   Spare metadata LV
287
288
289       The first time a thin pool LV is created, lvm will create a spare meta‐
290       data LV in the VG.  This behavior can be  controlled  with  the  option
291       --poolmetadataspare y|n.  (Future thin pool creations will also attempt
292       to create the pmspare LV if none exists.)
293
294       To create the pmspare ("pool metadata spare") LV, lvm first creates  an
295       LV with a default name, e.g. lvol0, and then converts this LV to a hid‐
296       den LV with the _pmspare suffix, e.g. lvol0_pmspare.
297
298       One pmspare LV is kept in a VG to be used for any thin pool.
299
300       The pmspare LV cannot be created explicitly, but may be removed explic‐
301       itly.
302
303       Example
304       # lvcreate -n pool0 -L 10G vg
305       # lvcreate -n pool0meta -L 1G vg
306       # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
307
308       # lvs -a
309         [lvol0_pmspare] vg          ewi-------
310         pool0           vg          twi---tz--
311         [pool0_tdata]   vg          Twi-------
312         [pool0_tmeta]   vg          ewi-------
313
314       The  "Metadata  check and repair" section describes the use of the pms‐
315       pare LV.
316
317
318
319   Metadata check and repair
320
321
322       If thin pool metadata is damaged, it may be repairable.   Checking  and
323       repairing  thin  pool metadata is analogous to running fsck/repair on a
324       file system.
325
326       When a thin pool LV is activated, lvm runs the  thin_check  command  to
327       check the correctness of the metadata on the pool metadata LV.
328
329       lvm.conf(5) thin_check_executable
330       can  be  set  to  an  empty string ("") to disable the thin_check step.
331       This is not recommended.
332
333       lvm.conf(5) thin_check_options
334       controls the command options used for the thin_check command.
335
336       If the thin_check command finds a problem with the metadata,  the  thin
337       pool  LV  is  not activated, and the thin pool metadata needs to be re‐
338       paired.
339
340       Simple repair commands are not always successful.  Advanced repair  may
341       require editing thin pool metadata and lvm metadata.  Newer versions of
342       the kernel and lvm tools may be more successful at repair.  Report  the
343       details of damaged thin metadata to get the best advice on recovery.
344
345       Command to repair a thin pool:
346       lvconvert --repair VG/ThinPoolLV
347
348       Repair performs the following steps:
349
350       1. Creates a new, repaired copy of the metadata.
351       lvconvert  runs  the  thin_repair command to read damaged metadata from
352       the existing pool metadata LV, and writes a new repaired  copy  to  the
353       VG's pmspare LV.
354
355       2. Replaces the thin pool metadata LV.
356       If step 1 is successful, the thin pool metadata LV is replaced with the
357       pmspare LV containing the corrected metadata.  The previous  thin  pool
358       metadata  LV, containing the damaged metadata, becomes visible with the
359       new name ThinPoolLV_metaN (where N is 0,1,...).
360
361       If the repair works, the thin pool LV and its thin  LVs  can  be  acti‐
362       vated.   User  should manually check if repaired thin pool kernel meta‐
363       data has all data for all lvm2 known LVs by  individual  activation  of
364       every  thin  LV.  When all works, user should continue with fsck of all
365       filesystems present these such volumes.  Once the thin pool is  consid‐
366       ered fully functional user may remove ThinPoolLV_metaN (the LV contain‐
367       ing the damaged thin pool metadata) for possible space  reuse.   For  a
368       better performance it may be useful to pvmove the new repaired metadata
369       LV (written to previous pmspare volume) to a better PV (i.e. SSD)
370
371       If the repair operation fails, the thin pool LV and its  thin  LVs  are
372       not  accessible and it may be necessary to restore their content from a
373       backup.  In such case the content of unmodified original damaged  Thin‐
374       PoolLV_metaN  volume  can be used by your support for more advanced re‐
375       covery methods.
376
377       If metadata is manually restored with thin_repair  directly,  the  pool
378       metadata  LV  can  be  manually  swapped with another LV containing new
379       metadata:
380
381       lvconvert --thinpool VG/ThinPoolLV --poolmetadata VG/NewThinMetaLV
382
383       Note: Thin pool metadata is compact so even small corruptions  in  them
384       may  result in significant portions of mappings to be lost.  It is rec‐
385       ommended to use fast resilient storage for them.
386
387
388   Activation of thin snapshots
389
390
391       When a thin snapshot LV is created, it is by default given the "activa‐
392       tion skip" flag.  This flag is indicated by the "k" attribute displayed
393       by lvs:
394
395       # lvs vg/thin1s1
396         LV         VG  Attr       LSize Pool  Origin
397         thin1s1    vg  Vwi---tz-k 1.00t pool0 thin1
398
399       This flag causes the snapshot LV to be skipped, i.e. not activated,  by
400       normal  activation  commands.   The skipping behavior does not apply to
401       deactivation commands.
402
403       A snapshot LV with the "k" attribute can be activated using the -K  (or
404       --ignoreactivationskip)  option  in  addition  to  the standard -ay (or
405       --activate y) option.
406
407       Command to activate a thin snapshot LV:
408       lvchange -ay -K VG/SnapLV
409
410       The persistent "activation skip" flag can be turned off  during  lvcre‐
411       ate,  or  later  with lvchange using the -kn (or --setactivationskip n)
412       option.  It can be turned on again with -ky (or --setactivationskip y).
413
414       When the "activation skip" flag is removed, normal activation  commands
415       will activate the LV, and the -K activation option is not needed.
416
417       Command to create snapshot LV without the activation skip flag:
418       lvcreate -kn -n SnapLV -s VG/ThinLV
419
420       Command to remove the activation skip flag from a snapshot LV:
421       lvchange -kn VG/SnapLV
422
423       lvm.conf(5) auto_set_activation_skip
424       controls the default activation skip setting used by lvcreate.
425
426
427
428   Removing thin pool LVs, thin LVs and snapshots
429
430
431       Removing a thin LV and its related snapshots returns the blocks it used
432       to the thin pool LV.  These blocks will be reused for  other  thin  LVs
433       and snapshots.
434
435       Removing  a  thin  pool LV removes both the data LV and metadata LV and
436       returns the space to the VG.
437
438       lvremove of thin pool LVs, thin LVs and snapshots  cannot  be  reversed
439       with vgcfgrestore.
440
441       vgcfgbackup does not back up thin pool metadata.
442
443
444
445   Manually manage free data space of thin pool LV
446
447
448       The  available  free  space in a thin pool LV can be displayed with the
449       lvs command.  Free space can be added by extending the thin pool LV.
450
451       Command to extend thin pool data space:
452       lvextend -L Size VG/ThinPoolLV
453
454       Example
455       1. A thin pool LV is using 26.96% of its data blocks.
456       # lvs
457         LV    VG           Attr       LSize   Pool  Origin Data%
458         pool0 vg           twi-a-tz--  10.00g               26.96
459
460       2. Double the amount of physical space in the thin pool LV.
461       # lvextend -L+10G vg/pool0
462
463       3. The percentage of used data blocks is half the previous value.
464       # lvs
465         LV    VG           Attr       LSize   Pool  Origin Data%
466         pool0 vg           twi-a-tz--  20.00g               13.48
467
468       Other methods of increasing free data space in a thin pool  LV  include
469       removing  a thin LV and its related snapshots, or running fstrim on the
470       file system using a thin LV.
471
472
473
474   Manually manage free metadata space of a thin pool LV
475
476
477       The available metadata space in a thin pool LV can  be  displayed  with
478       the lvs -o+metadata_percent command.
479
480       Command to extend thin pool metadata space:
481       lvextend --poolmetadatasize Size VG/ThinPoolLV
482
483       Example
484       1. A thin pool LV is using 12.40% of its metadata blocks.
485       # lvs -oname,size,data_percent,metadata_percent vg/pool0
486         LV    LSize   Data%  Meta%
487         pool0  20.00g  13.48  12.40
488
489       2.  Display  a  thin  pool  LV with its component thin data LV and thin
490       metadata LV.
491       # lvs -a -oname,attr,size vg
492         LV              Attr       LSize
493         pool0           twi-a-tz--  20.00g
494         [pool0_tdata]   Twi-ao----  20.00g
495         [pool0_tmeta]   ewi-ao----  12.00m
496
497       3. Double the amount of physical space in the thin metadata LV.
498       # lvextend --poolmetadatasize +12M vg/pool0
499
500       4. The percentage of used metadata blocks is half the previous value.
501       # lvs -a -oname,size,data_percent,metadata_percent vg
502         LV              LSize   Data%  Meta%
503         pool0            20.00g  13.48   6.20
504         [pool0_tdata]    20.00g
505         [pool0_tmeta]    24.00m
506
507
508
509   Using fstrim to increase free space in a thin pool LV
510
511
512       Removing files in a file system on top of a thin LV does not  generally
513       add free space back to the thin pool.  Manually running the fstrim com‐
514       mand can return space back to the thin pool that had been used  by  re‐
515       moved  files.   fstrim uses discards and will not work if the thin pool
516       LV has discards mode set to ignore.
517
518       Example
519       A thin pool has 10G of physical data space, and a thin LV has a virtual
520       size  of  100G.   Writing a 1G file to the file system reduces the free
521       space in the thin pool by 10% and increases the virtual  usage  of  the
522       file system by 1%.  Removing the 1G file restores the virtual 1% to the
523       file system, but does not restore the physical 10% to  the  thin  pool.
524       The fstrim command restores the physical space to the thin pool.
525
526       # lvs -a -oname,attr,size,pool_lv,origin,data_percent,metadata_percent vg
527       LV              Attr       LSize   Pool  Origin Data%  Meta%
528       pool0           twi-a-tz--  10.00g               47.01  21.03
529       thin1           Vwi-aotz-- 100.00g pool0          2.70
530
531       # df -h /mnt/X
532       Filesystem            Size  Used Avail Use% Mounted on
533       /dev/mapper/vg-thin1   99G  1.1G   93G   2% /mnt/X
534
535       # dd if=/dev/zero of=/mnt/X/1Gfile bs=4096 count=262144; sync
536
537       # lvs
538       pool0           vg   twi-a-tz--  10.00g               57.01  25.26
539       thin1           vg   Vwi-aotz-- 100.00g pool0          3.70
540
541       # df -h /mnt/X
542       /dev/mapper/vg-thin1   99G  2.1G   92G   3% /mnt/X
543
544       # rm /mnt/X/1Gfile
545
546       # lvs
547       pool0           vg   twi-a-tz--  10.00g               57.01  25.26
548       thin1           vg   Vwi-aotz-- 100.00g pool0          3.70
549
550       # df -h /mnt/X
551       /dev/mapper/vg-thin1   99G  1.1G   93G   2% /mnt/X
552
553       # fstrim -v /mnt/X
554
555       # lvs
556       pool0           vg   twi-a-tz--  10.00g               47.01  21.03
557       thin1           vg   Vwi-aotz-- 100.00g pool0          2.70
558
559       The  "Discard"  section covers an option for automatically freeing data
560       space in a thin pool.
561
562
563
564   Automatically extend thin pool LV
565
566
567       The lvm daemon dmeventd (lvm2-monitor) monitors the data usage of  thin
568       pool  LVs and extends them when the usage reaches a certain level.  The
569       necessary free space must exist in the VG  to  extend  thin  pool  LVs.
570       Monitoring and extension of thin pool LVs are controlled independently.
571
572       monitoring
573
574       When  a thin pool LV is activated, dmeventd will begin monitoring it by
575       default.
576
577       Command to start or stop dmeventd monitoring a thin pool LV:
578       lvchange --monitor {y|n} VG/ThinPoolLV
579
580       The current dmeventd monitoring status of a thin pool LV  can  be  dis‐
581       played with the command lvs -o+seg_monitor.
582
583       autoextend
584
585       dmeventd  should  be configured to extend thin pool LVs before all data
586       space is used.  Warnings are emitted through syslog when the use  of  a
587       thin  pool reaches 80%, 85%, 90% and 95%.  (See the section "Data space
588       exhaustion" for the effects of not extending  a  thin  pool  LV.)   The
589       point  at which dmeventd extends thin pool LVs, and the amount are con‐
590       trolled with two configuration settings:
591
592       lvm.conf(5) thin_pool_autoextend_threshold
593       is a percentage full value that defines when the thin pool LV should be
594       extended.  Setting this to 100 disables automatic extension.  The mini‐
595       mum value is 50.
596
597       lvm.conf(5) thin_pool_autoextend_percent
598       defines how much extra data space should be added to the thin  pool  LV
599       from the VG, in percent of its current size.
600
601       disabling
602
603       There  are  multiple  ways  that  extension of thin pools could be pre‐
604       vented:
605
606
607       • If the dmeventd daemon is not running, no monitoring or automatic ex‐
608         tension will occur.
609
610
611       • Even  when  dmeventd  is running, all monitoring can be disabled with
612         the lvm.conf monitoring setting.
613
614
615       • To activate or  create  a  thin  pool  LV  without  interacting  with
616         dmeventd,  the  --ignoremonitoring option can be used.  With this op‐
617         tion, the command will not ask dmeventd to monitor the thin pool LV.
618
619
620       • Setting thin_pool_autoextend_threshold to 100 disables automatic  ex‐
621         tension  of  thin  pool  LVs,  even  if  they  are being monitored by
622         dmeventd.
623
624
625       Example
626       If thin_pool_autoextend_threshold is 70  and  thin_pool_autoextend_per‐
627       cent  is  20, whenever a pool exceeds 70% usage, it will be extended by
628       another 20%.  For a 1G pool, using 700M will trigger a resize to  1.2G.
629       When the usage exceeds 840M, the pool will be extended to 1.44G, and so
630       on.
631
632
633
634   Data space exhaustion
635
636
637       When properly managed, thin pool data space should be  extended  before
638       it  is  all used (see the section "Automatically extend thin pool LV").
639       If thin pool data space is already exhausted, it can still be  extended
640       (see the section "Manually manage free data space of thin pool LV".)
641
642       The  behavior of a full thin pool is configurable with the --errorwhen‐
643       full y|n option to lvcreate or lvchange.  The errorwhenfull setting ap‐
644       plies  only  to  writes;  reading  thin LVs can continue even when data
645       space is exhausted.
646
647       Command to change the handling of a full thin pool:
648       lvchange --errorwhenfull {y|n} VG/ThinPoolLV
649
650       lvm.conf(5) error_when_full
651       controls the default error when full behavior.
652
653       The current setting of a thin pool LV can be displayed  with  the  com‐
654       mand: lvs -o+lv_when_full.
655
656       The errorwhenfull setting does not effect the monitoring and autoextend
657       settings, and the monitoring/autoextend settings do not effect the  er‐
658       rorwhenfull setting.  It is only when monitoring/autoextend are not ef‐
659       fective that the thin pool becomes full and the  errorwhenfull  setting
660       is applied.
661
662       errorwhenfull n
663
664       This  is the default.  Writes to thin LVs are accepted and queued, with
665       the expectation that pool data space will be extended soon.  Once  data
666       space  is  extended,  the queued writes will be processed, and the thin
667       pool will return to normal operation.
668
669       While waiting to be extended, the thin pool will queue writes for up to
670       60  seconds  (the  default).  If data space has not been extended after
671       this time, the queued writes will return an error to the  caller,  e.g.
672       the  file  system.   This can result in file system corruption for non-
673       journaled file systems that may require repair.  When a thin  pool  re‐
674       turns  errors  for  writes  to a thin LV, any file system is subject to
675       losing unsynced user data.
676
677       The 60 second timeout can be changed or disabled with the  dm-thin-pool
678       kernel  module option no_space_timeout.  This option sets the number of
679       seconds that thin pools will queue writes.  If set to  0,  writes  will
680       not  time out.  Disabling timeouts can result in the system running out
681       of resources, memory exhaustion, hung tasks, and deadlocks.  (The time‐
682       out applies to all thin pools on the system.)
683
684       errorwhenfull y
685
686       Writes  to  thin  LVs  immediately  return  an error, and no writes are
687       queued.  In the case of a file system, this can  result  in  corruption
688       that  may  require  fs  repair (the specific consequences depend on the
689       thin LV user.)
690
691       data percent
692
693       When data space is exhausted, the lvs command displays 100 under  Data%
694       for the thin pool LV:
695
696       # lvs vg/pool0
697         LV     VG           Attr       LSize   Pool  Origin Data%
698         pool0  vg           twi-a-tz-- 512.00m              100.00
699
700       causes
701
702       A thin pool may run out of data space for any of the following reasons:
703
704
705       • Automatic  extension  of the thin pool is disabled, and the thin pool
706         is not manually extended.  (Disabling automatic extension is not rec‐
707         ommended.)
708
709
710       • The  dmeventd daemon is not running and the thin pool is not manually
711         extended.  (Disabling dmeventd is not recommended.)
712
713
714       • Automatic extension of the thin pool is too slow given  the  rate  of
715         writes to thin LVs in the pool.  (This can be addressed by tuning the
716         thin_pool_autoextend_threshold and thin_pool_autoextend_percent.  See
717         "Automatic extend settings".)
718
719
720       • The VG does not have enough free blocks to extend the thin pool.
721
722
723   Metadata space exhaustion
724
725
726       If thin pool metadata space is exhausted (or a thin pool metadata oper‐
727       ation fails), errors will be returned for IO operations on thin LVs.
728
729       When metadata space is exhausted, the lvs command  displays  100  under
730       Meta% for the thin pool LV:
731
732       # lvs -o lv_name,size,data_percent,metadata_percent vg/pool0
733         LV    LSize Data%  Meta%
734         pool0              100.00
735
736       The same reasons for thin pool data space exhaustion apply to thin pool
737       metadata space.
738
739       Metadata space exhaustion can lead to inconsistent thin  pool  metadata
740       and  inconsistent file systems, so the response requires offline check‐
741       ing and repair.
742
743       1. Deactivate the thin pool LV, or reboot the system  if  this  is  not
744       possible.
745
746       2. Repair thin pool with lvconvert --repair.
747          See "Metadata check and repair".
748
749       3. Extend pool metadata space with lvextend --poolmetadatasize.
750          See "Manually manage free metadata space of a thin pool LV".
751
752       4. Check and repair file system.
753
754
755
756   Automatic extend settings
757
758
759       Thin  pool LVs can be extended according to preset values.  The presets
760       determine if the LV should be extended based on how full it is, and  if
761       so by how much.  When dmeventd monitors thin pool LVs, it uses lvextend
762       with these presets.  (See "Automatically extend thin pool LV".)
763
764       Command to extend a thin pool data LV using presets:
765       lvextend --use-policies VG/ThinPoolLV
766
767       The command uses these settings:
768
769       lvm.conf(5) thin_pool_autoextend_threshold
770       autoextend the LV when its usage exceeds this percent.
771
772       lvm.conf(5) thin_pool_autoextend_percent
773       autoextend the LV by this much additional space.
774
775       To see the default values of these settings, run:
776
777       lvmconfig --type default --withcomment
778              activation/thin_pool_autoextend_threshold
779
780       lvmconfig --type default --withcomment
781              activation/thin_pool_autoextend_percent
782
783       To change these values globally, edit lvm.conf(5).
784
785       To change these values on a per-VG or per-LV basis, attach a  "profile"
786       to  the  VG or LV.  A profile is a collection of config settings, saved
787       in a local text file (using the lvm.conf format).  lvm looks  for  pro‐
788       files  in  the profile_dir directory, e.g. /etc/lvm/profile/.  Once at‐
789       tached to a VG or LV, lvm will process the VG or LV using the  settings
790       from  the  attached  profile.  A profile is named and referenced by its
791       file name.
792
793       To use a profile to customize the lvextend settings for an LV:
794
795
796       • Create a file containing settings, saved  in  profile_dir.   For  the
797         profile_dir location, run:
798         lvmconfig config/profile_dir
799
800
801       • Attach the profile to an LV, using the command:
802         lvchange --metadataprofile ProfileName VG/ThinPoolLV
803
804
805       • Extend the LV using the profile settings:
806         lvextend --use-policies VG/ThinPoolLV
807
808
809       Example
810       # lvmconfig config/profile_dir
811       profile_dir="/etc/lvm/profile"
812
813       # cat /etc/lvm/profile/pool0extend.profile
814       activation {
815               thin_pool_autoextend_threshold=50
816               thin_pool_autoextend_percent=10
817       }
818
819       # lvchange --metadataprofile pool0extend vg/pool0
820
821       # lvextend --use-policies vg/pool0
822
823       Notes
824
825       • A  profile  is  attached to a VG or LV by name, where the name refer‐
826         ences a local file in profile_dir.  If the VG is moved to another ma‐
827         chine, the file with the profile also needs to be moved.
828
829
830       • Only certain settings can be used in a VG or LV profile, see:
831         lvmconfig --type profilable-metadata.
832
833
834       • An LV without a profile of its own will inherit the VG profile.
835
836
837       • Remove a profile from an LV using the command:
838         lvchange --detachprofile VG/ThinPoolLV.
839
840
841       • Commands  can  also have profiles applied to them.  The settings that
842         can be applied to a command are different than the settings that  can
843         be  applied  to a VG or LV.  See lvmconfig --type profilable-command.
844         To apply a profile to a command, write a profile, save it in the pro‐
845         file  directory,  and run the command using the option: --commandpro‐
846         file ProfileName.
847
848
849
850   Zeroing
851
852
853       When a thin pool provisions a new data block for a  thin  LV,  the  new
854       block  is  first overwritten with zeros.  The zeroing mode is indicated
855       by the "z" attribute displayed by lvs.  The option -Z (or  --zero)  can
856       be added to commands to specify the zeroing mode.
857
858       Command to set the zeroing mode when creating a thin pool LV:
859       lvconvert --type thin-pool -Z{y|n}
860              --poolmetadata VG/ThinMetaLV VG/ThinDataLV
861
862       Command to change the zeroing mode of an existing thin pool LV:
863       lvchange -Z{y|n} VG/ThinPoolLV
864
865       If  zeroing  mode  is  changed  from "n" to "y", previously provisioned
866       blocks are not zeroed.
867
868       Provisioning of large zeroed chunks impacts performance.
869
870       lvm.conf(5) thin_pool_zero
871       controls the default zeroing mode used when creating a thin pool.
872
873
874
875   Discard
876
877
878       The discard behavior of a thin pool LV determines how discard  requests
879       are handled.  Enabling discard under a file system may adversely affect
880       the file system performance (see the section on fstrim for an  alterna‐
881       tive.)  Possible discard behaviors:
882
883       ignore: Ignore any discards that are received.
884
885       nopassdown:  Process any discards in the thin pool itself and allow the
886       no longer needed extents to be overwritten by new data.
887
888       passdown: Process discards in the thin pool (as with  nopassdown),  and
889       pass  the discards down the the underlying device.  This is the default
890       mode.
891
892       Command to display the current discard mode of a thin pool LV:
893       lvs -o+discards VG/ThinPoolLV
894
895       Command to set the discard mode when creating a thin pool LV:
896       lvconvert --discards {ignore|nopassdown|passdown}
897              --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
898
899       Command to change the discard mode of an existing thin pool LV:
900       lvchange --discards {ignore|nopassdown|passdown} VG/ThinPoolLV
901
902       Example
903       # lvs -o name,discards vg/pool0
904       pool0 passdown
905
906       # lvchange --discards ignore vg/pool0
907
908       lvm.conf(5) thin_pool_discards
909       controls the default discards mode used when creating a thin pool.
910
911
912
913   Chunk size
914
915
916       The size of data blocks managed by a thin pool can  be  specified  with
917       the  --chunksize  option when the thin pool LV is created.  The default
918       unit is KiB. The value must be a multiple of 64KiB  between  64KiB  and
919       1GiB.
920
921       When a thin pool is used primarily for the thin provisioning feature, a
922       larger value is optimal.  To optimize for  many  snapshots,  a  smaller
923       value reduces copying time and consumes less space.
924
925       Command to display the thin pool LV chunk size:
926       lvs -o+chunksize VG/ThinPoolLV
927
928       Example
929       # lvs -o name,chunksize
930         pool0 64.00k
931
932       lvm.conf(5) thin_pool_chunk_size
933       controls the default chunk size used when creating a thin pool.
934
935       The default value is shown by:
936       lvmconfig --type default allocation/thin_pool_chunk_size
937
938
939
940   Size of pool metadata LV
941
942
943       The  amount  of thin metadata depends on how many blocks are shared be‐
944       tween thin LVs (i.e. through snapshots).  A thin pool with  many  snap‐
945       shots  may  need a larger metadata LV.  Thin pool metadata LV sizes can
946       be from 2MiB to approximately 16GiB.
947
948       When using lvcreate to create what will become a thin metadata LV,  the
949       size is specified with the -L--size option.
950
951       When  an LVM command automatically creates a thin metadata LV, the size
952       is specified with the --poolmetadatasize option.  When this  option  is
953       not  given, LVM automatically chooses a size based on the data size and
954       chunk size.
955
956       It can be hard to predict the amount of metadata  space  that  will  be
957       needed,  so it is recommended to start with a size of 1GiB which should
958       be enough for all practical purposes.  A  thin  pool  metadata  LV  can
959       later be manually or automatically extended if needed.
960
961       Configurable   setting  lvm.conf(5)  allocation/thin_pool_crop_metadata
962       gives control over cropping to 15.81GiB  to  stay  backward  compatible
963       with  older  versions  of  lvm2. With enabled cropping there can be ob‐
964       served some problems when using volumes above this size with thin tools
965       (i.e. thin_repair).  Cropping should be enabled only when compatibility
966       is required.
967
968
969
970   Create a thin snapshot of an external, read only LV
971
972
973       Thin snapshots are typically taken of other  thin  LVs  or  other  thin
974       snapshot  LVs  within  the same thin pool.  It is also possible to take
975       thin snapshots of external, read only LVs.  Writes to the snapshot  are
976       stored  in the thin pool, and the external LV is used to read unwritten
977       parts of the thin snapshot.
978
979       lvcreate -n SnapLV -s VG/ExternalOriginLV --thinpool VG/ThinPoolLV
980
981       Example
982       # lvchange -an vg/lve
983       # lvchange --permission r vg/lve
984       # lvcreate -n snaplve -s vg/lve --thinpool vg/pool0
985
986       # lvs vg/lve vg/snaplve
987         LV      VG  Attr       LSize  Pool  Origin Data%
988         lve     vg  ori------- 10.00g
989         snaplve vg  Vwi-a-tz-- 10.00g pool0 lve      0.00
990
991
992
993   Convert a standard LV to a thin LV with an external origin
994
995
996       A new thin LV can be created and given the name of an existing standard
997       LV.   At the same time, the existing LV is converted to a read only ex‐
998       ternal LV with a new name.  Unwritten portions of the thin LV are  read
999       from  the  external  LV.   The new name given to the existing LV can be
1000       specified with --originname, otherwise the existing LV will be given  a
1001       default name, e.g. lvol#.
1002
1003       Convert ExampleLV into a read only external LV with the new name NewEx‐
1004       ternalOriginLV, and create a new thin LV that  is  given  the  previous
1005       name of ExampleLV.
1006
1007       lvconvert --type thin --thinpool VG/ThinPoolLV
1008              --originname NewExternalOriginLV VG/ExampleLV
1009
1010       Example
1011       # lvcreate -n lv_example -L 10G vg
1012
1013       # lvs
1014         lv_example      vg          -wi-a-----  10.00g
1015
1016       # lvconvert --type thin --thinpool vg/pool0
1017                 --originname lv_external --thin vg/lv_example
1018
1019       # lvs
1020         LV              VG          Attr       LSize   Pool  Origin
1021         lv_example      vg          Vwi-a-tz--  10.00g pool0 lv_external
1022         lv_external     vg          ori-------  10.00g
1023
1024
1025
1026   Single step thin pool LV creation
1027
1028
1029       A  thin  pool  LV can be created with a single lvcreate command, rather
1030       than using lvconvert on existing LVs.  This one command creates a  thin
1031       data LV, a thin metadata LV, and combines the two into a thin pool LV.
1032
1033       lvcreate --type thin-pool -L LargeSize -n ThinPoolLV VG
1034
1035       Example
1036       # lvcreate --type thin-pool -L8M -n pool0 vg
1037
1038       # lvs vg/pool0
1039         LV    VG  Attr       LSize Pool Origin Data%
1040         pool0 vg  twi-a-tz-- 8.00m               0.00
1041
1042       # lvs -a
1043         pool0           vg          twi-a-tz--   8.00m
1044         [pool0_tdata]   vg          Twi-ao----   8.00m
1045         [pool0_tmeta]   vg          ewi-ao----   8.00m
1046
1047
1048
1049   Single step thin pool LV and thin LV creation
1050
1051
1052       A thin pool LV and a thin LV can be created with a single lvcreate com‐
1053       mand.  This one command creates a thin data LV,  a  thin  metadata  LV,
1054       combines  the two into a thin pool LV, and creates a thin LV in the new
1055       pool.
1056       -L LargeSize specifies the physical size of the thin pool LV.
1057       -V VirtualSize specifies the virtual size of the thin LV.
1058
1059       lvcreate --type thin -V VirtualSize -L LargeSize
1060              -n ThinLV --thinpool VG/ThinPoolLV
1061
1062       Equivalent to:
1063       lvcreate --type thin-pool -L LargeSize VG/ThinPoolLV
1064       lvcreate -n ThinLV -V VirtualSize --thinpool VG/ThinPoolLV
1065
1066       Example
1067       # lvcreate -L8M -V2G -n thin1 --thinpool vg/pool0
1068
1069       # lvs -a
1070         pool0           vg          twi-a-tz--   8.00m
1071         [pool0_tdata]   vg          Twi-ao----   8.00m
1072         [pool0_tmeta]   vg          ewi-ao----   8.00m
1073         thin1           vg          Vwi-a-tz--   2.00g pool0
1074
1075
1076
1077   Merge thin snapshots
1078
1079
1080       A thin snapshot can be merged into its origin thin LV using the  lvcon‐
1081       vert  --merge command.  The result of a snapshot merge is that the ori‐
1082       gin thin LV takes the content of the snapshot LV, and the  snapshot  LV
1083       is  removed.  Any content that was unique to the origin thin LV is lost
1084       after the merge.
1085
1086       Because a merge changes the content of an LV, it cannot be  done  while
1087       the  LVs are open, e.g. mounted.  If a merge is initiated while the LVs
1088       are open, the effect of the merge is delayed until the origin  thin  LV
1089       is next activated.
1090
1091       lvconvert --merge VG/SnapLV
1092
1093       Example
1094       # lvs vg
1095         LV      VG Attr       LSize   Pool  Origin
1096         pool0   vg twi-a-tz--  10.00g
1097         thin1   vg Vwi-a-tz-- 100.00g pool0
1098         thin1s1 vg Vwi-a-tz-k 100.00g pool0 thin1
1099
1100       # lvconvert --merge vg/thin1s1
1101
1102       # lvs vg
1103         LV      VG Attr       LSize   Pool  Origin
1104         pool0   vg twi-a-tz--  10.00g
1105         thin1   vg Vwi-a-tz-- 100.00g pool0
1106
1107       Example
1108       Delayed merging of open LVs.
1109
1110       # lvs vg
1111         LV      VG Attr       LSize   Pool  Origin
1112         pool0   vg twi-a-tz--  10.00g
1113         thin1   vg Vwi-aotz-- 100.00g pool0
1114         thin1s1 vg Vwi-aotz-k 100.00g pool0 thin1
1115
1116       # df
1117       /dev/mapper/vg-thin1            100G   33M  100G   1% /mnt/X
1118       /dev/mapper/vg-thin1s1          100G   33M  100G   1% /mnt/Xs
1119
1120       # ls /mnt/X
1121       file1 file2 file3
1122       # ls /mnt/Xs
1123       file3 file4 file5
1124
1125       # lvconvert --merge vg/thin1s1
1126       Logical volume vg/thin1s1 contains a filesystem in use.
1127       Delaying merge since snapshot is open.
1128       Merging of thin snapshot thin1s1 will occur on next activation.
1129
1130       # umount /mnt/X
1131       # umount /mnt/Xs
1132
1133       # lvs -a vg
1134         LV              VG   Attr       LSize   Pool  Origin
1135         pool0           vg   twi-a-tz--  10.00g
1136         [pool0_tdata]   vg   Twi-ao----  10.00g
1137         [pool0_tmeta]   vg   ewi-ao----   1.00g
1138         thin1           vg   Owi-a-tz-- 100.00g pool0
1139         [thin1s1]       vg   Swi-a-tz-k 100.00g pool0 thin1
1140
1141       # lvchange -an vg/thin1
1142       # lvchange -ay vg/thin1
1143
1144       # mount /dev/vg/thin1 /mnt/X
1145
1146       # ls /mnt/X
1147       file3 file4 file5
1148
1149
1150
1151   XFS on snapshots
1152
1153
1154       Mounting  an XFS file system on a new snapshot LV requires attention to
1155       the file system's log state and uuid.  On the snapshot LV, the xfs  log
1156       will  contain a dummy transaction, and the xfs uuid will match the uuid
1157       from the file system on the origin LV.
1158
1159       If the snapshot LV is writable, mounting will recover the log to  clear
1160       the dummy transaction, but will require skipping the uuid check:
1161
1162       mount /dev/VG/SnapLV /mnt -o nouuid
1163
1164       After  the  first  mount  with  the above approach, the UUID can subse‐
1165       quently be changed using:
1166
1167       xfs_admin -U generate /dev/VG/SnapLV
1168       mount /dev/VG/SnapLV /mnt
1169
1170       Once the UUID has been changed, the mount command will  no  longer  re‐
1171       quire the nouuid option.
1172
1173       If the snapshot LV is readonly, the log recovery and uuid check need to
1174       be skipped while mounting readonly:
1175
1176       mount /dev/VG/SnapLV /mnt -o ro,nouuid,norecovery
1177
1178

SEE ALSO

1180       lvm(8),   lvm.conf(5),   lvmconfig(8),    lvcreate(8),    lvconvert(8),
1181       lvchange(8),  lvextend(8),  lvremove(8), lvs(8), thin_dump(8), thin_re‐
1182       pair(8) thin_restore(8)
1183
1184
1185
1186
1187Red Hat, Inc           LVM TOOLS 2.03.11(2) (2021-01-08)            LVMTHIN(7)
Impressum