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

NAME

6       lvmthin — LVM thin provisioning
7
8

DESCRIPTION

10       Blocks  in  a standard logical volume are allocated when the LV is cre‐
11       ated, but blocks in a thin provisioned logical volume 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  VG,
18       but blocks in a thin LV are allocated (during use) from a special "thin
19       pool LV".  The thin pool LV contains blocks of  physical  storage,  and
20       blocks in thin LVs just reference blocks in the thin pool LV.
21
22       A  thin  pool  LV must be created before thin LVs can be created within
23       it.  A thin pool LV is created by combining two standard LVs:  a  large
24       data LV that will hold blocks for thin LVs, and a metadata LV that will
25       hold metadata.  The metadata tracks which data blocks  belong  to  each
26       thin LV.
27
28       Snapshots of thin LVs are efficient because the data blocks common to a
29       thin LV and any of its snapshots are shared.  Snapshots may be taken of
30       thin  LVs or of other thin snapshots.  Blocks common to recursive snap‐
31       shots are also shared in the thin pool.  There is no limit to or degra‐
32       dation from sequences of snapshots.
33
34       As thin LVs or snapshot LVs are written to, they consume data blocks in
35       the thin pool.  As free data blocks in the  pool  decrease,  more  free
36       blocks  may  need  to  be supplied.  This is done by extending the thin
37       pool data LV with additional physical space from the VG.  Removing thin
38       LVs  or  snapshots  from the thin pool can also free blocks in the thin
39       pool.  However, removing LVs is not always an effective way of  freeing
40       space  in  a  thin  pool because the amount is limited to the number of
41       blocks not shared with other LVs in the pool.
42
43       Incremental block allocation from thin pools  can  cause  thin  LVs  to
44       become  fragmented.  Standard LVs generally avoid this problem by allo‐
45       cating all the blocks at once during creation.
46
47
48

Thin Terms

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

Thin Usage

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

Thin Topics

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

SEE ALSO

1178       lvm(8),    lvm.conf(5),    lvmconfig(8),   lvcreate(8),   lvconvert(8),
1179       lvchange(8),   lvextend(8),    lvremove(8),    lvs(8),    thin_dump(8),
1180       thin_repair(8) thin_restore(8)
1181
1182
1183
1184
1185Red Hat, Inc       LVM TOOLS 2.02.143(2)-RHEL6 (2016-12-13)         LVMTHIN(7)
Impressum