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