1LVMTHIN(7) LVMTHIN(7)
2
6 lvmthin — LVM thin provisioning
7
9 Blocks in a standard lvm(8) Logical Volume (LV) are allocated when the
10 LV is created, but blocks in a thin provisioned LV are allocated as
11 they are written. Because of this, a thin provisioned LV is given a
12 virtual size, and can then be much larger than physically available
13 storage. The amount of physical storage provided for thin provisioned
14 LVs can be increased later as the need arises.
15 Blocks in a standard LV are allocated (during creation) from the Volume
17 Group (VG), but blocks in a thin LV are allocated (during use) from a
18 special "thin pool LV". The thin pool LV contains blocks of physical
19 storage, and blocks in thin LVs just reference blocks in the thin pool
20 LV.
21 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 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 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 Incremental block allocation from thin pools can cause thin LVs to be‐
44 come fragmented. Standard LVs generally avoid this problem by allocat‐
45 ing all the blocks at once during creation.
46
48 ThinDataLV
49 thin data LV
50 large LV created in a VG
51 used by thin pool to store ThinLV blocks
52 ThinMetaLV
54 thin metadata LV
55 small LV created in a VG
56 used by thin pool to track data block usage
57 ThinPoolLV
59 thin pool LV
60 combination of ThinDataLV and ThinMetaLV
61 contains ThinLVs and SnapLVs
62 ThinLV
64 thin LV
65 created from ThinPoolLV
66 appears blank after creation
67 SnapLV
69 snapshot LV
70 created from ThinPoolLV
71 appears as a snapshot of another LV after creation
72
74 The primary method for using lvm thin provisioning:
75 1. Create ThinDataLV
77 Create an LV that will hold thin pool data.
78 lvcreate -n ThinDataLV -L LargeSize VG
80 Example
82 # lvcreate -n pool0 -L 10G vg
83 2. Create ThinMetaLV
85 Create an LV that will hold thin pool metadata.
86 lvcreate -n ThinMetaLV -L SmallSize VG
88 Example
90 # lvcreate -n pool0meta -L 1G vg
91 # lvs
93 LV VG Attr LSize
94 pool0 vg -wi-a----- 10.00g
95 pool0meta vg -wi-a----- 1.00g
96 3. Create ThinPoolLV
98 Combine the data and metadata LVs into a thin pool LV.
99 ThinDataLV is renamed to hidden ThinPoolLV_tdata.
100 ThinMetaLV is renamed to hidden ThinPoolLV_tmeta.
101 The new ThinPoolLV takes the previous name of ThinDataLV.
102 lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
104 Example
106 # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
107 # lvs vg/pool0
109 LV VG Attr LSize Pool Origin Data% Meta%
110 pool0 vg twi-a-tz-- 10.00g 0.00 0.00
111 # lvs -a
113 LV VG Attr LSize
114 pool0 vg twi-a-tz-- 10.00g
115 [pool0_tdata] vg Twi-ao---- 10.00g
116 [pool0_tmeta] vg ewi-ao---- 1.00g
117 4. Create ThinLV
119 Create a new thin LV from the thin pool LV.
120 The thin LV is created with a virtual size.
121 Multiple new thin LVs may be created in the thin pool.
122 Thin LV names must be unique in the VG.
123 The '--type thin' option is inferred from the virtual size option.
124 The --thinpool argument specifies which thin pool will
125 contain the ThinLV.
126 lvcreate -n ThinLV -V VirtualSize --thinpool ThinPoolLV VG
128 Example
130 Create a thin LV in a thin pool:
131 # lvcreate -n thin1 -V 1T --thinpool pool0 vg
132 Create another thin LV in the same thin pool:
134 # lvcreate -n thin2 -V 1T --thinpool pool0 vg
135 # lvs vg/thin1 vg/thin2
137 LV VG Attr LSize Pool Origin Data%
138 thin1 vg Vwi-a-tz-- 1.00t pool0 0.00
139 thin2 vg Vwi-a-tz-- 1.00t pool0 0.00
140 5. Create SnapLV
142 Create snapshots of an existing ThinLV or SnapLV.
143 Do not specify -L, --size when creating a thin snapshot.
144 A size argument will cause an old COW snapshot to be created.
145 lvcreate -n SnapLV --snapshot VG/ThinLV
147 lvcreate -n SnapLV --snapshot VG/PrevSnapLV
148 Example
150 Create first snapshot of an existing ThinLV:
151 # lvcreate -n thin1s1 -s vg/thin1
152 Create second snapshot of the same ThinLV:
154 # lvcreate -n thin1s2 -s vg/thin1
155 Create a snapshot of the first snapshot:
157 # lvcreate -n thin1s1s1 -s vg/thin1s1
158 # lvs vg/thin1s1 vg/thin1s2 vg/thin1s1s1
160 LV VG Attr LSize Pool Origin
161 thin1s1 vg Vwi---tz-k 1.00t pool0 thin1
162 thin1s2 vg Vwi---tz-k 1.00t pool0 thin1
163 thin1s1s1 vg Vwi---tz-k 1.00t pool0 thin1s1
164 6. Create ThinLV with ThinPoolLV
166 Create a new thin LV together with thin pool LV and let lvm2 to allo‐
167 cate data and metadata volume.
168 lvcreate -T -n ThinLV -V VirtualSize -L PoolSize VG/ThinPoolLV
170 Example
172 Create a 50MiB thin LV and 10MiB thin pool:
173 # lvcreate -T -n thin -V 52M -L 12M vg/pool
174 # lvs -a vg
176 LV VG Attr LSize Pool Origin Data% Meta%
177 [lvol0_pmspare] vg ewi------- 4,00m
178 pool vg twi-aotz-- 12,00m 0,00 10,94
179 [pool_tdata] vg Twi-ao---- 12,00m
180 [pool_tmeta] vg ewi-ao---- 4,00m
181 thin vg Vwi-a-tz-- 52,00m pool 0,00
182 7. Activate SnapLV
184 Thin snapshots are created with the persistent "activation skip" flag,
185 indicated by the "k" attribute. Use -K with lvchange or vgchange to
186 activate thin snapshots with the "k" attribute. User can preset de‐
187 fault behavior with lvm.conf(5) auto_set_activation_skip.
188 lvchange -ay -K VG/SnapLV
190 Example
192 # lvchange -ay -K vg/thin1s1
193 # lvs vg/thin1s1
195 LV VG Attr LSize Pool Origin
196 thin1s1 vg Vwi-a-tz-k 1.00t pool0 thin1
197 8. Convert thick LV to thin LV
199 Convert existing thick LV (linear, stripe,...) to thin LV with move of
200 existing data to thin pool and using thin LV from such thin pool. Once
201 the volume is converted, user is using it like ordinary thin-pool.
202 Note: Conversion cannot be reverted and thin volume cannot be reverted
203 back to thick LV type.
204 lvconvert --type thin VG/ThickLV
206 Example
208 Create thick 12MiB LV.
209 # lvcreate -L 12M -n thick vg
210 Convert LV to a thin pool with chunk size 256KiB.
212 # lvconvert --thin --chunksize 256K vg/thick
213 # lvs -o+chunksize vg
215 LV VG Attr LSize Pool Origin Data% Meta%
216 Chunk
217 thick vg Vwi-a-tz-- 12,00m thick_tpool0 100,00
218 0
219 thick_tpool0 vg twi---tz-- 12,00m 100,00 10,94
220 256,00k
221
223 Automatic pool metadata LV
224 Specify devices for data and metadata LVs
225 Tolerate device failures using raid
226 Spare metadata LV
227 Metadata check and repair
228 Activation of thin snapshots
229 Removing thin pool LVs, thin LVs and snapshots
230 Manually manage free data space of thin pool LV
231 Manually manage free metadata space of a thin pool LV
232 Using fstrim to increase free space in a thin pool LV
233 Automatically extend thin pool LV
234 Data space exhaustion
235 Metadata space exhaustion
236 Automatic extend settings
237 Zeroing
238 Discard
239 Chunk size
240 Size of pool metadata LV
241 Create a thin snapshot of an external, read only LV
242 Convert a standard LV to a thin LV with an external origin
243 Single step thin pool LV creation
244 Single step thin pool LV and thin LV creation
245 Merge thin snapshots
246 XFS on snapshots
247 Automatic pool metadata LV
249 A thin data LV can be converted to a thin pool LV without specifying a
250 thin pool metadata LV. LVM automatically creates a metadata LV from
251 the same VG.
252 lvcreate -n ThinDataLV -L LargeSize VG
254 lvconvert --type thin-pool VG/ThinDataLV
255 Example
257 # lvcreate -n pool0 -L 10G vg
258 # lvconvert --type thin-pool vg/pool0
259 # lvs -a
261 pool0 vg twi-a-tz-- 10.00g
262 [pool0_tdata] vg Twi-ao---- 10.00g
263 [pool0_tmeta] vg ewi-ao---- 16.00m
264 Specify devices for data and metadata LVs
266 The data and metadata LVs in a thin pool are best created on separate
267 physical devices. To do that, specify the device name(s) at the end of
268 the lvcreate line. It can be especially helpful to use fast devices
269 for the metadata LV.
270 lvcreate -n ThinDataLV -L LargeSize VG LargePV
272 lvcreate -n ThinMetaLV -L SmallSize VG FastPV
273 lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
274 Example
276 # lvcreate -n pool0 -L 10G vg /dev/sdA
277 # lvcreate -n pool0meta -L 1G vg /dev/sdB
278 # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
279 lvm.conf(5) thin_pool_metadata_require_separate_pvs
281 controls the default PV usage for thin pool creation.
282 Tolerate device failures using raid
284 To tolerate device failures, use raid for the pool data LV and pool
285 metadata LV. This is especially recommended for pool metadata LVs.
286 lvcreate --type raid1 -m 1 -n ThinMetaLV -L SmallSize VG PVA PVB
288 lvcreate --type raid1 -m 1 -n ThinDataLV -L LargeSize VG PVC PVD
289 lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
290 Example
292 # lvcreate --type raid1 -m 1 -n pool0 -L 10G vg /dev/sdA /dev/sdB
293 # lvcreate --type raid1 -m 1 -n pool0meta -L 1G vg /dev/sdC /dev/sdD
294 # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
295 Spare metadata LV
297 The first time a thin pool LV is created, lvm will create a spare meta‐
298 data LV in the VG. This behavior can be controlled with the option
299 --poolmetadataspare y|n. (Future thin pool creations will also attempt
300 to create the pmspare LV if none exists.)
301 To create the pmspare ("pool metadata spare") LV, lvm first creates an
303 LV with a default name, e.g. lvol0, and then converts this LV to a hid‐
304 den LV with the _pmspare suffix, e.g. lvol0_pmspare.
305 One pmspare LV is kept in a VG to be used for any thin pool.
307 The pmspare LV cannot be created explicitly, but may be removed explic‐
309 itly.
310 Example
312 # lvcreate -n pool0 -L 10G vg
313 # lvcreate -n pool0meta -L 1G vg
314 # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
315 # lvs -a
317 [lvol0_pmspare] vg ewi-------
318 pool0 vg twi---tz--
319 [pool0_tdata] vg Twi-------
320 [pool0_tmeta] vg ewi-------
321 The "Metadata check and repair" section describes the use of the pms‐
323 pare LV.
324 Metadata check and repair
326 If thin pool metadata is damaged, it may be repairable. Checking and
327 repairing thin pool metadata is analogous to running fsck/repair on a
328 file system.
329 When a thin pool LV is activated, lvm runs the thin_check(8) command to
331 check the correctness of the metadata on the pool metadata LV.
332 lvm.conf(5) thin_check_executable
334 can be set to an empty string ("") to disable the thin_check(8) step.
335 This is not recommended.
336 lvm.conf(5) thin_check_options
338 controls the command options used for the thin_check(8) command.
339 If the thin_check(8) command finds a problem with the metadata, the
341 thin pool LV is not activated, and the thin pool metadata needs to be
342 repaired.
343 Simple repair commands are not always successful. Advanced repair may
345 require editing thin pool metadata and lvm metadata. Newer versions of
346 the kernel and lvm tools may be more successful at repair. Report the
347 details of damaged thin metadata to get the best advice on recovery.
348 Command to repair a thin pool:
350 lvconvert --repair VG/ThinPoolLV
351 Repair performs the following steps:
353 1 Creates a new, repaired copy of the metadata.
355 lvconvert runs the thin_repair(8) command to read damaged metadata
356 from the existing pool metadata LV, and writes a new repaired copy
357 to the VG's pmspare LV.
358 2 Replaces the thin pool metadata LV.
360 If step 1 is successful, the thin pool metadata LV is replaced with
361 the pmspare LV containing the corrected metadata. The previous thin
362 pool metadata LV, containing the damaged metadata, becomes visible
363 with the new name ThinPoolLV_metaN (where N is 0,1,...).
364 If the repair works, the thin pool LV and its thin LVs can be acti‐
366 vated. User should manually check if repaired thin pool kernel meta‐
367 data has all data for all lvm2 known LVs by individual activation of
368 every thin LV. When all works, user should continue with fsck of all
369 filesystems present on these volumes. Once the thin pool is considered
370 fully functional user may remove ThinPoolLV_metaN (the LV containing
371 the damaged thin pool metadata) for possible space reuse. For a better
372 performance it may be useful to pvmove the new repaired metadata LV
373 (written to previous pmspare volume) to a faster PV, e.g. SSD.
374 If the repair operation fails, the thin pool LV and its thin LVs are
376 not accessible and it may be necessary to restore their content from a
377 backup. In such case the content of unmodified original damaged Thin‐
378 PoolLV_metaN volume can be used by your support for more advanced re‐
379 covery methods.
380 If metadata is manually restored with thin_repair(8) directly, the pool
382 metadata LV can be manually swapped with another LV containing new
383 metadata:
384 lvconvert --thinpool VG/ThinPoolLV --poolmetadata VG/NewThinMetaLV
386 Note: Thin pool metadata is compact so even small corruptions in them
388 may result in significant portions of mappings to be lost. It is rec‐
389 ommended to use fast resilient storage for them.
390 Activation of thin snapshots
392 When a thin snapshot LV is created, it is by default given the "activa‐
393 tion skip" flag. This flag is indicated by the "k" attribute displayed
394 by lvs:
395 # lvs vg/thin1s1
397 LV VG Attr LSize Pool Origin
398 thin1s1 vg Vwi---tz-k 1.00t pool0 thin1
399 This flag causes the snapshot LV to be skipped, i.e. not activated, by
401 normal activation commands. The skipping behavior does not apply to
402 deactivation commands.
403 A snapshot LV with the "k" attribute can be activated using the -K (or
405 --ignoreactivationskip) option in addition to the standard -ay (or
406 --activate y) option.
407 Command to activate a thin snapshot LV:
409 lvchange -ay -K VG/SnapLV
410 The persistent "activation skip" flag can be turned off during lvcre‐
412 ate, or later with lvchange using the -kn (or --setactivationskip n)
413 option. It can be turned on again with -ky (or --setactivationskip y).
414 When the "activation skip" flag is removed, normal activation commands
416 will activate the LV, and the -K activation option is not needed.
417 Command to create snapshot LV without the activation skip flag:
419 lvcreate -kn -n SnapLV -s VG/ThinLV
420 Command to remove the activation skip flag from a snapshot LV:
422 lvchange -kn VG/SnapLV
423 lvm.conf(5) auto_set_activation_skip
425 controls the default activation skip setting used by lvcreate.
426 Removing thin pool LVs, thin LVs and snapshots
428 Removing a thin LV and its related snapshots returns the blocks it used
429 to the thin pool LV. These blocks will be reused for other thin LVs
430 and snapshots.
431 Removing a thin pool LV removes both the data LV and metadata LV and
433 returns the space to the VG.
434 lvremove of thin pool LVs, thin LVs and snapshots cannot be reversed
436 with vgcfgrestore.
437 vgcfgbackup does not back up thin pool metadata.
439 Manually manage free data space of thin pool LV
441 The available free space in a thin pool LV can be displayed with the
442 lvs command. Free space can be added by extending the thin pool LV.
443 Command to extend thin pool data space:
445 lvextend -L Size VG/ThinPoolLV
446 Example
448 1. A thin pool LV is using 26.96% of its data blocks.
449 # lvs
450 LV VG Attr LSize Pool Origin Data%
451 pool0 vg twi-a-tz-- 10.00g 26.96
452 2. Double the amount of physical space in the thin pool LV.
454 # lvextend -L+10G vg/pool0
455 3. The percentage of used data blocks is half the previous value.
457 # lvs
458 LV VG Attr LSize Pool Origin Data%
459 pool0 vg twi-a-tz-- 20.00g 13.48
460 Other methods of increasing free data space in a thin pool LV include
462 removing a thin LV and its related snapshots, or running fstrim on the
463 file system using a thin LV.
464 Manually manage free metadata space of a thin pool LV
466 The available metadata space in a thin pool LV can be displayed with
467 the lvs -o+metadata_percent command.
468 Command to extend thin pool metadata space:
470 lvextend --poolmetadatasize Size VG/ThinPoolLV
471 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 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 3. Double the amount of physical space in the thin metadata LV.
487 # lvextend --poolmetadatasize +12M vg/pool0
488 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 Using fstrim to increase free space in a thin pool LV
497 Removing files in a file system on top of a thin LV does not generally
498 add free space back to the thin pool. Manually running the fstrim com‐
499 mand can return space back to the thin pool that had been used by re‐
500 moved files. fstrim uses discards and will not work if the thin pool
501 LV has discards mode set to ignore.
502 Example
504 A thin pool has 10G of physical data space, and a thin LV has a virtual
505 size of 100G. Writing a 1G file to the file system reduces the free
506 space in the thin pool by 10% and increases the virtual usage of the
507 file system by 1%. Removing the 1G file restores the virtual 1% to the
508 file system, but does not restore the physical 10% to the thin pool.
509 The fstrim command restores the physical space to the thin pool.
510 # lvs -a -oname,attr,size,pool_lv,origin,data_percent,metadata_percent vg
512 LV Attr LSize Pool Origin Data% Meta%
513 pool0 twi-a-tz-- 10.00g 47.01 21.03
514 thin1 Vwi-aotz-- 100.00g pool0 2.70
515 # df -h /mnt/X
517 Filesystem Size Used Avail Use% Mounted on
518 /dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X
519 # dd if=/dev/zero of=/mnt/X/1Gfile bs=4096 count=262144; sync
521 # lvs
523 pool0 vg twi-a-tz-- 10.00g 57.01 25.26
524 thin1 vg Vwi-aotz-- 100.00g pool0 3.70
525 # df -h /mnt/X
527 /dev/mapper/vg-thin1 99G 2.1G 92G 3% /mnt/X
528 # rm /mnt/X/1Gfile
530 # lvs
532 pool0 vg twi-a-tz-- 10.00g 57.01 25.26
533 thin1 vg Vwi-aotz-- 100.00g pool0 3.70
534 # df -h /mnt/X
536 /dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X
537 # fstrim -v /mnt/X
539 # lvs
541 pool0 vg twi-a-tz-- 10.00g 47.01 21.03
542 thin1 vg Vwi-aotz-- 100.00g pool0 2.70
543 The "Discard" section covers an option for automatically freeing data
545 space in a thin pool.
546 Automatically extend thin pool LV
548 The lvm daemon dmeventd (lvm2-monitor) monitors the data usage of thin
549 pool LVs and extends them when the usage reaches a certain level. The
550 necessary free space must exist in the VG to extend thin pool LVs.
551 Monitoring and extension of thin pool LVs are controlled independently.
552 — Monitoring —
554 When a thin pool LV is activated, dmeventd will begin monitoring it by
556 default.
557 Command to start or stop dmeventd monitoring a thin pool LV:
559 lvchange --monitor y|n VG/ThinPoolLV
560 The current dmeventd monitoring status of a thin pool LV can be dis‐
562 played with the command lvs -o+seg_monitor.
563 — Autoextending —
565 dmeventd should be configured to extend thin pool LVs before all data
567 space is used. Warnings are emitted through syslog when the use of a
568 thin pool reaches 80%, 85%, 90% and 95%. (See the section "Data space
569 exhaustion" for the effects of not extending a thin pool LV.) The
570 point at which dmeventd extends thin pool LVs, and the amount are con‐
571 trolled with two configuration settings:
572 lvm.conf(5) thin_pool_autoextend_threshold
574 is a percentage full value that defines when the thin pool LV should be
575 extended. Setting this to 100 disables automatic extension. The mini‐
576 mum value is 50.
577 lvm.conf(5) thin_pool_autoextend_percent
579 defines how much extra data space should be added to the thin pool LV
580 from the VG, in percent of its current size.
581 — Disabling —
583 There are multiple ways that extension of thin pools could be pre‐
585 vented:
586 • If the dmeventd daemon is not running, no monitoring or automatic ex‐
588 tension will occur.
589 • Even when dmeventd is running, all monitoring can be disabled with
591 the lvm.conf monitoring setting.
592 • To activate or create a thin pool LV without interacting with
594 dmeventd, the --ignoremonitoring option can be used. With this op‐
595 tion, the command will not ask dmeventd to monitor the thin pool LV.
596 • Setting thin_pool_autoextend_threshold to 100 disables automatic ex‐
598 tension of thin pool LVs, even if they are being monitored by
599 dmeventd.
600 Example
602 If thin_pool_autoextend_threshold is 70 and thin_pool_autoextend_per‐
603 cent is 20, whenever a pool exceeds 70% usage, it will be extended by
604 another 20%. For a 1G pool, using 700M will trigger a resize to 1.2G.
605 When the usage exceeds 840M, the pool will be extended to 1.44G, and so
606 on.
607 Data space exhaustion
609 When properly managed, thin pool data space should be extended before
610 it is all used (see the section "Automatically extend thin pool LV").
611 If thin pool data space is already exhausted, it can still be extended
612 (see the section "Manually manage free data space of thin pool LV".)
613 The behavior of a full thin pool is configurable with the --errorwhen‐
615 full y|n option to lvcreate or lvchange. The errorwhenfull setting ap‐
616 plies only to writes; reading thin LVs can continue even when data
617 space is exhausted.
618 Command to change the handling of a full thin pool:
620 lvchange --errorwhenfull y|n VG/ThinPoolLV
621 lvm.conf(5) error_when_full
623 controls the default error when full behavior.
624 The current setting of a thin pool LV can be displayed with the com‐
626 mand: lvs -o+lv_when_full.
627 The errorwhenfull setting does not effect the monitoring and autoextend
629 settings, and the monitoring/autoextend settings do not effect the er‐
630 rorwhenfull setting. It is only when monitoring/autoextend are not ef‐
631 fective that the thin pool becomes full and the errorwhenfull setting
632 is applied.
633 — errorwhenfull n —
635 This is the default. Writes to thin LVs are accepted and queued, with
637 the expectation that pool data space will be extended soon. Once data
638 space is extended, the queued writes will be processed, and the thin
639 pool will return to normal operation.
640 While waiting to be extended, the thin pool will queue writes for up to
642 60 seconds (the default). If data space has not been extended after
643 this time, the queued writes will return an error to the caller, e.g.
644 the file system. This can result in file system corruption for non-
645 journaled file systems that may require repair. When a thin pool re‐
646 turns errors for writes to a thin LV, any file system is subject to
647 losing unsynced user data.
648 The 60 second timeout can be changed or disabled with the dm-thin-pool
650 kernel module option no_space_timeout. This option sets the number of
651 seconds that thin pools will queue writes. If set to 0, writes will
652 not time out. Disabling timeouts can result in the system running out
653 of resources, memory exhaustion, hung tasks, and deadlocks. (The time‐
654 out applies to all thin pools on the system.)
655 — errorwhenfull y —
657 Writes to thin LVs immediately return an error, and no writes are
659 queued. In the case of a file system, this can result in corruption
660 that may require fs repair (the specific consequences depend on the
661 thin LV user.)
662 — data percent —
664 When data space is exhausted, the lvs command displays 100 under Data%
666 for the thin pool LV:
667 # lvs vg/pool0
669 LV VG Attr LSize Pool Origin Data%
670 pool0 vg twi-a-tz-- 512.00m 100.00
671 — causes —
673 A thin pool may run out of data space for any of the following reasons:
675 • Automatic extension of the thin pool is disabled, and the thin pool
677 is not manually extended. (Disabling automatic extension is not rec‐
678 ommended.)
679 • The dmeventd daemon is not running and the thin pool is not manually
681 extended. (Disabling dmeventd is not recommended.)
682 • Automatic extension of the thin pool is too slow given the rate of
684 writes to thin LVs in the pool. (This can be addressed by tuning the
685 thin_pool_autoextend_threshold and thin_pool_autoextend_percent. See
686 "Automatic extend settings".)
687 • The VG does not have enough free blocks to extend the thin pool.
689 Metadata space exhaustion
691 If thin pool metadata space is exhausted (or a thin pool metadata oper‐
692 ation fails), errors will be returned for IO operations on thin LVs.
693 When metadata space is exhausted, the lvs command displays 100 under
695 Meta% for the thin pool LV:
696 # lvs -o lv_name,size,data_percent,metadata_percent vg/pool0
698 LV LSize Data% Meta%
699 pool0 100.00
700 The same reasons for thin pool data space exhaustion apply to thin pool
702 metadata space.
703 Metadata space exhaustion can lead to inconsistent thin pool metadata
705 and inconsistent file systems, so the response requires offline check‐
706 ing and repair.
707 1. Deactivate the thin pool LV, or reboot the system if this is not
709 possible.
710 2. Repair thin pool with lvconvert --repair.
712 See "Metadata check and repair".
713 3. Extend pool metadata space with lvextend --poolmetadatasize.
715 See "Manually manage free metadata space of a thin pool LV".
716 4. Check and repair file system.
718 Automatic extend settings
720 Thin pool LVs can be extended according to preset values. The presets
721 determine if the LV should be extended based on how full it is, and if
722 so by how much. When dmeventd monitors thin pool LVs, it uses lvextend
723 with these presets. (See "Automatically extend thin pool LV".)
724 Command to extend a thin pool data LV using presets:
726 lvextend --use-policies VG/ThinPoolLV
727 The command uses these settings:
729 lvm.conf(5) thin_pool_autoextend_threshold
731 autoextend the LV when its usage exceeds this percent.
732 lvm.conf(5) thin_pool_autoextend_percent
734 autoextend the LV by this much additional space.
735 To see the default values of these settings, run:
737 lvmconfig --type default --withcomment
739 activation/thin_pool_autoextend_threshold
740 lvmconfig --type default --withcomment
742 activation/thin_pool_autoextend_percent
743 To change these values globally, edit lvm.conf(5).
745 To change these values on a per-VG or per-LV basis, attach a "profile"
747 to the VG or LV. A profile is a collection of config settings, saved
748 in a local text file (using the lvm.conf format). lvm looks for pro‐
749 files in the profile_dir directory, e.g. /etc/lvm/profile/. Once at‐
750 tached to a VG or LV, lvm will process the VG or LV using the settings
751 from the attached profile. A profile is named and referenced by its
752 file name.
753 To use a profile to customize the lvextend settings for an LV:
755 • Create a file containing settings, saved in profile_dir.
757 For the profile_dir location, run:
758 lvmconfig config/profile_dir
759 • Attach the profile to an LV, using the command:
761 lvchange --metadataprofile ProfileName VG/ThinPoolLV
762 • Extend the LV using the profile settings:
764 lvextend --use-policies VG/ThinPoolLV
765 Example
767 # lvmconfig config/profile_dir
768 profile_dir="/etc/lvm/profile"
769 # cat /etc/lvm/profile/pool0extend.profile
771 activation {
772 thin_pool_autoextend_threshold=50
773 thin_pool_autoextend_percent=10
774 }
775 # lvchange --metadataprofile pool0extend vg/pool0
777 # lvextend --use-policies vg/pool0
779 Notes
781 • A profile is attached to a VG or LV by name, where the name refer‐
783 ences a local file in profile_dir. If the VG is moved to another ma‐
784 chine, the file with the profile also needs to be moved.
785 • Only certain settings can be used in a VG or LV profile, see:
787 lvmconfig --type profilable-metadata.
788 • An LV without a profile of its own will inherit the VG profile.
790 • Remove a profile from an LV using the command:
792 lvchange --detachprofile VG/ThinPoolLV.
793 • Commands can also have profiles applied to them. The settings that
795 can be applied to a command are different than the settings that can
796 be applied to a VG or LV. See lvmconfig --type profilable-command.
797 To apply a profile to a command, write a profile, save it in the pro‐
798 file directory, and run the command using the option: --commandpro‐
799 file ProfileName.
800 Zeroing
802 When a thin pool provisions a new data block for a thin LV, the new
803 block is first overwritten with zeros. The zeroing mode is indicated
804 by the "z" attribute displayed by lvs. The option -Z (or --zero) can
805 be added to commands to specify the zeroing mode.
806 Command to set the zeroing mode when creating a thin pool LV:
808 lvconvert --type thin-pool -Z y|n
810 --poolmetadata VG/ThinMetaLV VG/ThinDataLV
811 Command to change the zeroing mode of an existing thin pool LV:
813 lvchange -Z y|n VG/ThinPoolLV
815 If zeroing mode is changed from "n" to "y", previously provisioned
817 blocks are not zeroed.
818 Provisioning of large zeroed chunks impacts performance.
820 lvm.conf(5) thin_pool_zero
822 controls the default zeroing mode used when creating a thin pool.
823 Discard
825 The discard behavior of a thin pool LV determines how discard requests
826 are handled. Enabling discard under a file system may adversely affect
827 the file system performance (see the section on fstrim for an alterna‐
828 tive.) Possible discard behaviors:
829 ignore: Ignore any discards that are received.
831 nopassdown: Process any discards in the thin pool itself and allow the
833 no longer needed extents to be overwritten by new data.
834 passdown: Process discards in the thin pool (as with nopassdown), and
836 pass the discards down the the underlying device. This is the default
837 mode.
838 Command to display the current discard mode of a thin pool LV:
840 lvs -o+discards VG/ThinPoolLV
841 Command to set the discard mode when creating a thin pool LV:
843 lvconvert --discards ignore|nopassdown|passdown
844 --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
845 Command to change the discard mode of an existing thin pool LV:
847 lvchange --discards ignore|nopassdown|passdown VG/ThinPoolLV
848 Example
850 # lvs -o name,discards vg/pool0
851 pool0 passdown
852 # lvchange --discards ignore vg/pool0
854 lvm.conf(5) thin_pool_discards
856 controls the default discards mode used when creating a thin pool.
857 Chunk size
859 The size of data blocks managed by a thin pool can be specified with
860 the --chunksize option when the thin pool LV is created. The default
861 unit is KiB. The value must be a multiple of 64KiB between 64KiB and
862 1GiB.
863 When a thin pool is used primarily for the thin provisioning feature, a
865 larger value is optimal. To optimize for many snapshots, a smaller
866 value reduces copying time and consumes less space.
867 Command to display the thin pool LV chunk size:
869 lvs -o+chunksize VG/ThinPoolLV
871 Example
873 # lvs -o name,chunksize
874 pool0 64.00k
875 lvm.conf(5) thin_pool_chunk_size
877 controls the default chunk size used when creating a thin pool.
878 The default value is shown by:
880 lvmconfig --type default allocation/thin_pool_chunk_size
881 Size of pool metadata LV
883 The amount of thin metadata depends on how many blocks are shared be‐
884 tween thin LVs (i.e. through snapshots). A thin pool with many snap‐
885 shots may need a larger metadata LV. Thin pool metadata LV sizes can
886 be from 2MiB to approximately 16GiB.
887 When using lvcreate to create what will become a thin metadata LV, the
889 size is specified with the -L|--size option.
890 When an LVM command automatically creates a thin metadata LV, the size
892 is specified with the --poolmetadatasize option. When this option is
893 not given, LVM automatically chooses a size based on the data size and
894 chunk size.
895 It can be hard to predict the amount of metadata space that will be
897 needed, so it is recommended to start with a size of 1GiB which should
898 be enough for all practical purposes. A thin pool metadata LV can
899 later be manually or automatically extended if needed.
900 Configurable setting lvm.conf(5) allocation/thin_pool_crop_metadata
902 gives control over cropping to 15.81GiB to stay backward compatible
903 with older versions of lvm2. With enabled cropping there can be ob‐
904 served some problems when using volumes above this size with thin tools
905 (i.e. thin_repair(8)). Cropping should be enabled only when compati‐
906 bility is required.
907 Create a thin snapshot of an external, read only LV
909 Thin snapshots are typically taken of other thin LVs or other thin
910 snapshot LVs within the same thin pool. It is also possible to take
911 thin snapshots of external, read only LVs. Writes to the snapshot are
912 stored in the thin pool, and the external LV is used to read unwritten
913 parts of the thin snapshot.
914 lvcreate -n SnapLV -s VG/ExternalOriginLV --thinpool VG/ThinPoolLV
916 Example
918 # lvchange -an vg/lve
919 # lvchange --permission r vg/lve
920 # lvcreate -n snaplve -s vg/lve --thinpool vg/pool0
921 # lvs vg/lve vg/snaplve
923 LV VG Attr LSize Pool Origin Data%
924 lve vg ori------- 10.00g
925 snaplve vg Vwi-a-tz-- 10.00g pool0 lve 0.00
926 Convert a standard LV to a thin LV with an external origin
928 A new thin LV can be created and given the name of an existing standard
929 LV. At the same time, the existing LV is converted to a read only ex‐
930 ternal LV with a new name. Unwritten portions of the thin LV are read
931 from the external LV. The new name given to the existing LV can be
932 specified with --originname, otherwise the existing LV will be given a
933 default name, e.g. lvol#.
934 Convert ExampleLV into a read only external LV with the new name NewEx‐
936 ternalOriginLV, and create a new thin LV that is given the previous
937 name of ExampleLV.
938 lvconvert --type thin --thinpool VG/ThinPoolLV
940 --originname NewExternalOriginLV VG/ExampleLV
941 Example
943 # lvcreate -n lv_example -L 10G vg
944 # lvs
946 lv_example vg -wi-a----- 10.00g
947 # lvconvert --type thin --thinpool vg/pool0
949 --originname lv_external --thin vg/lv_example
950 # lvs
952 LV VG Attr LSize Pool Origin
953 lv_example vg Vwi-a-tz-- 10.00g pool0 lv_external
954 lv_external vg ori------- 10.00g
955 Single step thin pool LV creation
957 A thin pool LV can be created with a single lvcreate command, rather
958 than using lvconvert on existing LVs. This one command creates a thin
959 data LV, a thin metadata LV, and combines the two into a thin pool LV.
960 lvcreate --type thin-pool -L LargeSize -n ThinPoolLV VG
962 Example
964 # lvcreate --type thin-pool -L8M -n pool0 vg
965 # lvs vg/pool0
967 LV VG Attr LSize Pool Origin Data%
968 pool0 vg twi-a-tz-- 8.00m 0.00
969 # lvs -a
971 pool0 vg twi-a-tz-- 8.00m
972 [pool0_tdata] vg Twi-ao---- 8.00m
973 [pool0_tmeta] vg ewi-ao---- 8.00m
974 Single step thin pool LV and thin LV creation
976 A thin pool LV and a thin LV can be created with a single lvcreate com‐
977 mand. This one command creates a thin data LV, a thin metadata LV,
978 combines the two into a thin pool LV, and creates a thin LV in the new
979 pool.
980 -L LargeSize specifies the physical size of the thin pool LV.
981 -V VirtualSize specifies the virtual size of the thin LV.
982 lvcreate --type thin -V VirtualSize -L LargeSize
984 -n ThinLV --thinpool VG/ThinPoolLV
985 Equivalent to:
987 lvcreate --type thin-pool -L LargeSize VG/ThinPoolLV
988 lvcreate -n ThinLV -V VirtualSize --thinpool VG/ThinPoolLV
989 Example
991 # lvcreate -L8M -V2G -n thin1 --thinpool vg/pool0
992 # lvs -a
994 pool0 vg twi-a-tz-- 8.00m
995 [pool0_tdata] vg Twi-ao---- 8.00m
996 [pool0_tmeta] vg ewi-ao---- 8.00m
997 thin1 vg Vwi-a-tz-- 2.00g pool0
998 Merge thin snapshots
1000 A thin snapshot can be merged into its origin thin LV using the lvcon‐
1001 vert --merge command. The result of a snapshot merge is that the ori‐
1002 gin thin LV takes the content of the snapshot LV, and the snapshot LV
1003 is removed. Any content that was unique to the origin thin LV is lost
1004 after the merge.
1005 Because a merge changes the content of an LV, it cannot be done while
1007 the LVs are open, e.g. mounted. If a merge is initiated while the LVs
1008 are open, the effect of the merge is delayed until the origin thin LV
1009 is next activated.
1010 lvconvert --merge VG/SnapLV
1012 Example
1014 # lvs vg
1015 LV VG Attr LSize Pool Origin
1016 pool0 vg twi-a-tz-- 10.00g
1017 thin1 vg Vwi-a-tz-- 100.00g pool0
1018 thin1s1 vg Vwi-a-tz-k 100.00g pool0 thin1
1019 # lvconvert --merge vg/thin1s1
1021 # lvs vg
1023 LV VG Attr LSize Pool Origin
1024 pool0 vg twi-a-tz-- 10.00g
1025 thin1 vg Vwi-a-tz-- 100.00g pool0
1026 Example
1028 Delayed merging of open LVs.
1029 # lvs vg
1031 LV VG Attr LSize Pool Origin
1032 pool0 vg twi-a-tz-- 10.00g
1033 thin1 vg Vwi-aotz-- 100.00g pool0
1034 thin1s1 vg Vwi-aotz-k 100.00g pool0 thin1
1035 # df
1037 /dev/mapper/vg-thin1 100G 33M 100G 1% /mnt/X
1038 /dev/mapper/vg-thin1s1 100G 33M 100G 1% /mnt/Xs
1039 # ls /mnt/X
1041 file1 file2 file3
1042 # ls /mnt/Xs
1043 file3 file4 file5
1044 # lvconvert --merge vg/thin1s1
1046 Logical volume vg/thin1s1 contains a filesystem in use.
1047 Delaying merge since snapshot is open.
1048 Merging of thin snapshot thin1s1 will occur on next activation.
1049 # umount /mnt/X
1051 # umount /mnt/Xs
1052 # lvs -a vg
1054 LV VG Attr LSize Pool Origin
1055 pool0 vg twi-a-tz-- 10.00g
1056 [pool0_tdata] vg Twi-ao---- 10.00g
1057 [pool0_tmeta] vg ewi-ao---- 1.00g
1058 thin1 vg Owi-a-tz-- 100.00g pool0
1059 [thin1s1] vg Swi-a-tz-k 100.00g pool0 thin1
1060 # lvchange -an vg/thin1
1062 # lvchange -ay vg/thin1
1063 # mount /dev/vg/thin1 /mnt/X
1065 # ls /mnt/X
1067 file3 file4 file5
1068 XFS on snapshots
1070 Mounting an XFS file system on a new snapshot LV requires attention to
1071 the file system's log state and uuid. On the snapshot LV, the xfs log
1072 will contain a dummy transaction, and the xfs uuid will match the uuid
1073 from the file system on the origin LV.
1074 If the snapshot LV is writable, mounting will recover the log to clear
1076 the dummy transaction, but will require skipping the uuid check:
1077 # mount /dev/VG/SnapLV /mnt -o nouuid
1079 After the first mount with the above approach, the UUID can subse‐
1081 quently be changed using:
1082 # xfs_admin -U generate /dev/VG/SnapLV
1084 # mount /dev/VG/SnapLV /mnt
1085 Once the UUID has been changed, the mount command will no longer re‐
1087 quire the nouuid option.
1088 If the snapshot LV is readonly, the log recovery and uuid check need to
1089 be skipped while mounting readonly:
1090 # mount /dev/VG/SnapLV /mnt -o ro,nouuid,norecovery
1092
1094 lvm(8), lvm.conf(5), lvmconfig(8), lvcreate(8), lvconvert(8),
1095 lvchange(8), lvextend(8), lvremove(8), lvs(8),
1096 thin_check(8), thin_dump(8), thin_repair(8), thin_restore(8)
1098Red Hat, Inc LVM TOOLS 2.03.22(2) (2023-08-02) LVMTHIN(7)