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

SEE ALSO

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