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

SEE ALSO

1160       lvm(8),   lvm.conf(5),   lvmconfig(8),    lvcreate(8),    lvconvert(8),
1161       lvchange(8),    lvextend(8),    lvremove(8),    lvs(8),   thin_dump(8),
1162       thin_repair(8) thin_restore(8)
1163
1164
1165
1166
1167Red Hat, Inc        LVM TOOLS 2.03.02(2)-RHEL8 (2019-01-04)         LVMTHIN(7)
Impressum