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. Activate SnapLV
166 Thin snapshots are created with the persistent "activation skip" flag,
167 indicated by the "k" attribute. Use -K with lvchange or vgchange to
168 activate thin snapshots with the "k" attribute.
169 lvchange -ay -K VG/SnapLV
171 Example
173 # lvchange -ay -K vg/thin1s1
174 # lvs vg/thin1s1
176 LV VG Attr LSize Pool Origin
177 thin1s1 vg Vwi-a-tz-k 1.00t pool0 thin1
178
180 Automatic pool metadata LV
181 Specify devices for data and metadata LVs
182 Tolerate device failures using raid
183 Spare metadata LV
184 Metadata check and repair
185 Activation of thin snapshots
186 Removing thin pool LVs, thin LVs and snapshots
187 Manually manage free data space of thin pool LV
188 Manually manage free metadata space of a thin pool LV
189 Using fstrim to increase free space in a thin pool LV
190 Automatically extend thin pool LV
191 Data space exhaustion
192 Metadata space exhaustion
193 Automatic extend settings
194 Zeroing
195 Discard
196 Chunk size
197 Size of pool metadata LV
198 Create a thin snapshot of an external, read only LV
199 Convert a standard LV to a thin LV with an external origin
200 Single step thin pool LV creation
201 Single step thin pool LV and thin LV creation
202 Merge thin snapshots
203 XFS on snapshots
204 Automatic pool metadata LV
206 A thin data LV can be converted to a thin pool LV without specifying a
207 thin pool metadata LV. LVM automatically creates a metadata LV from
208 the same VG.
209 lvcreate -n ThinDataLV -L LargeSize VG
211 lvconvert --type thin-pool VG/ThinDataLV
212 Example
214 # lvcreate -n pool0 -L 10G vg
215 # lvconvert --type thin-pool vg/pool0
216 # lvs -a
218 pool0 vg twi-a-tz-- 10.00g
219 [pool0_tdata] vg Twi-ao---- 10.00g
220 [pool0_tmeta] vg ewi-ao---- 16.00m
221 Specify devices for data and metadata LVs
223 The data and metadata LVs in a thin pool are best created on separate
224 physical devices. To do that, specify the device name(s) at the end of
225 the lvcreate line. It can be especially helpful to use fast devices
226 for the metadata LV.
227 lvcreate -n ThinDataLV -L LargeSize VG LargePV
229 lvcreate -n ThinMetaLV -L SmallSize VG SmallPV
230 lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
231 Example
233 # lvcreate -n pool0 -L 10G vg /dev/sdA
234 # lvcreate -n pool0meta -L 1G vg /dev/sdB
235 # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
236 lvm.conf(5) thin_pool_metadata_require_separate_pvs
238 controls the default PV usage for thin pool creation.
239 Tolerate device failures using raid
241 To tolerate device failures, use raid for the pool data LV and pool
242 metadata LV. This is especially recommended for pool metadata LVs.
243 lvcreate --type raid1 -m 1 -n ThinMetaLV -L SmallSize VG PVA PVB
245 lvcreate --type raid1 -m 1 -n ThinDataLV -L LargeSize VG PVC PVD
246 lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
247 Example
249 # lvcreate --type raid1 -m 1 -n pool0 -L 10G vg /dev/sdA /dev/sdB
250 # lvcreate --type raid1 -m 1 -n pool0meta -L 1G vg /dev/sdC /dev/sdD
251 # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
252 Spare metadata LV
254 The first time a thin pool LV is created, lvm will create a spare meta‐
255 data LV in the VG. This behavior can be controlled with the option
256 --poolmetadataspare y|n. (Future thin pool creations will also attempt
257 to create the pmspare LV if none exists.)
258 To create the pmspare ("pool metadata spare") LV, lvm first creates an
260 LV with a default name, e.g. lvol0, and then converts this LV to a hid‐
261 den LV with the _pmspare suffix, e.g. lvol0_pmspare.
262 One pmspare LV is kept in a VG to be used for any thin pool.
264 The pmspare LV cannot be created explicitly, but may be removed explic‐
266 itly.
267 Example
269 # lvcreate -n pool0 -L 10G vg
270 # lvcreate -n pool0meta -L 1G vg
271 # lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0
272 # lvs -a
274 [lvol0_pmspare] vg ewi-------
275 pool0 vg twi---tz--
276 [pool0_tdata] vg Twi-------
277 [pool0_tmeta] vg ewi-------
278 The "Metadata check and repair" section describes the use of the pms‐
280 pare LV.
281 Metadata check and repair
283 If thin pool metadata is damaged, it may be repairable. Checking and
284 repairing thin pool metadata is analogous to running fsck/repair on a
285 file system.
286 When a thin pool LV is activated, lvm runs the thin_check command to
288 check the correctness of the metadata on the pool metadata LV.
289 lvm.conf(5) thin_check_executable
291 can be set to an empty string ("") to disable the thin_check step.
292 This is not recommended.
293 lvm.conf(5) thin_check_options
295 controls the command options used for the thin_check command.
296 If the thin_check command finds a problem with the metadata, the thin
298 pool LV is not activated, and the thin pool metadata needs to be re‐
299 paired.
300 Simple repair commands are not always successful. Advanced repair may
302 require editing thin pool metadata and lvm metadata. Newer versions of
303 the kernel and lvm tools may be more successful at repair. Report the
304 details of damaged thin metadata to get the best advice on recovery.
305 Command to repair a thin pool:
307 lvconvert --repair VG/ThinPoolLV
308 Repair performs the following steps:
310 1 Creates a new, repaired copy of the metadata.
312 lvconvert runs the thin_repair command to read damaged metadata from
313 the existing pool metadata LV, and writes a new repaired copy to the
314 VG's pmspare LV.
315 2 Replaces the thin pool metadata LV.
317 If step 1 is successful, the thin pool metadata LV is replaced with
318 the pmspare LV containing the corrected metadata. The previous thin
319 pool metadata LV, containing the damaged metadata, becomes visible
320 with the new name ThinPoolLV_metaN (where N is 0,1,...).
321 If the repair works, the thin pool LV and its thin LVs can be acti‐
323 vated. User should manually check if repaired thin pool kernel meta‐
324 data has all data for all lvm2 known LVs by individual activation of
325 every thin LV. When all works, user should continue with fsck of all
326 filesystems present on these volumes. Once the thin pool is considered
327 fully functional user may remove ThinPoolLV_metaN (the LV containing
328 the damaged thin pool metadata) for possible space reuse. For a better
329 performance it may be useful to pvmove the new repaired metadata LV
330 (written to previous pmspare volume) to a faster PV, e.g. SSD.
331 If the repair operation fails, the thin pool LV and its thin LVs are
333 not accessible and it may be necessary to restore their content from a
334 backup. In such case the content of unmodified original damaged Thin‐
335 PoolLV_metaN volume can be used by your support for more advanced re‐
336 covery methods.
337 If metadata is manually restored with thin_repair directly, the pool
339 metadata LV can be manually swapped with another LV containing new
340 metadata:
341 lvconvert --thinpool VG/ThinPoolLV --poolmetadata VG/NewThinMetaLV
343 Note: Thin pool metadata is compact so even small corruptions in them
345 may result in significant portions of mappings to be lost. It is rec‐
346 ommended to use fast resilient storage for them.
347 Activation of thin snapshots
349 When a thin snapshot LV is created, it is by default given the "activa‐
350 tion skip" flag. This flag is indicated by the "k" attribute displayed
351 by lvs:
352 # lvs vg/thin1s1
354 LV VG Attr LSize Pool Origin
355 thin1s1 vg Vwi---tz-k 1.00t pool0 thin1
356 This flag causes the snapshot LV to be skipped, i.e. not activated, by
358 normal activation commands. The skipping behavior does not apply to
359 deactivation commands.
360 A snapshot LV with the "k" attribute can be activated using the -K (or
362 --ignoreactivationskip) option in addition to the standard -ay (or
363 --activate y) option.
364 Command to activate a thin snapshot LV:
366 lvchange -ay -K VG/SnapLV
367 The persistent "activation skip" flag can be turned off during lvcre‐
369 ate, or later with lvchange using the -kn (or --setactivationskip n)
370 option. It can be turned on again with -ky (or --setactivationskip y).
371 When the "activation skip" flag is removed, normal activation commands
373 will activate the LV, and the -K activation option is not needed.
374 Command to create snapshot LV without the activation skip flag:
376 lvcreate -kn -n SnapLV -s VG/ThinLV
377 Command to remove the activation skip flag from a snapshot LV:
379 lvchange -kn VG/SnapLV
380 lvm.conf(5) auto_set_activation_skip
382 controls the default activation skip setting used by lvcreate.
383 Removing thin pool LVs, thin LVs and snapshots
385 Removing a thin LV and its related snapshots returns the blocks it used
386 to the thin pool LV. These blocks will be reused for other thin LVs
387 and snapshots.
388 Removing a thin pool LV removes both the data LV and metadata LV and
390 returns the space to the VG.
391 lvremove of thin pool LVs, thin LVs and snapshots cannot be reversed
393 with vgcfgrestore.
394 vgcfgbackup does not back up thin pool metadata.
396 Manually manage free data space of thin pool LV
398 The available free space in a thin pool LV can be displayed with the
399 lvs command. Free space can be added by extending the thin pool LV.
400 Command to extend thin pool data space:
402 lvextend -L Size VG/ThinPoolLV
403 Example
405 1. A thin pool LV is using 26.96% of its data blocks.
406 # lvs
407 LV VG Attr LSize Pool Origin Data%
408 pool0 vg twi-a-tz-- 10.00g 26.96
409 2. Double the amount of physical space in the thin pool LV.
411 # lvextend -L+10G vg/pool0
412 3. The percentage of used data blocks is half the previous value.
414 # lvs
415 LV VG Attr LSize Pool Origin Data%
416 pool0 vg twi-a-tz-- 20.00g 13.48
417 Other methods of increasing free data space in a thin pool LV include
419 removing a thin LV and its related snapshots, or running fstrim on the
420 file system using a thin LV.
421 Manually manage free metadata space of a thin pool LV
423 The available metadata space in a thin pool LV can be displayed with
424 the lvs -o+metadata_percent command.
425 Command to extend thin pool metadata space:
427 lvextend --poolmetadatasize Size VG/ThinPoolLV
428 Example
430 1. A thin pool LV is using 12.40% of its metadata blocks.
431 # lvs -oname,size,data_percent,metadata_percent vg/pool0
432 LV LSize Data% Meta%
433 pool0 20.00g 13.48 12.40
434 2. Display a thin pool LV with its component thin data LV and thin
436 metadata LV.
437 # lvs -a -oname,attr,size vg
438 LV Attr LSize
439 pool0 twi-a-tz-- 20.00g
440 [pool0_tdata] Twi-ao---- 20.00g
441 [pool0_tmeta] ewi-ao---- 12.00m
442 3. Double the amount of physical space in the thin metadata LV.
444 # lvextend --poolmetadatasize +12M vg/pool0
445 4. The percentage of used metadata blocks is half the previous value.
447 # lvs -a -oname,size,data_percent,metadata_percent vg
448 LV LSize Data% Meta%
449 pool0 20.00g 13.48 6.20
450 [pool0_tdata] 20.00g
451 [pool0_tmeta] 24.00m
452 Using fstrim to increase free space in a thin pool LV
454 Removing files in a file system on top of a thin LV does not generally
455 add free space back to the thin pool. Manually running the fstrim com‐
456 mand can return space back to the thin pool that had been used by re‐
457 moved files. fstrim uses discards and will not work if the thin pool
458 LV has discards mode set to ignore.
459 Example
461 A thin pool has 10G of physical data space, and a thin LV has a virtual
462 size of 100G. Writing a 1G file to the file system reduces the free
463 space in the thin pool by 10% and increases the virtual usage of the
464 file system by 1%. Removing the 1G file restores the virtual 1% to the
465 file system, but does not restore the physical 10% to the thin pool.
466 The fstrim command restores the physical space to the thin pool.
467 # lvs -a -oname,attr,size,pool_lv,origin,data_percent,metadata_percent vg
469 LV Attr LSize Pool Origin Data% Meta%
470 pool0 twi-a-tz-- 10.00g 47.01 21.03
471 thin1 Vwi-aotz-- 100.00g pool0 2.70
472 # df -h /mnt/X
474 Filesystem Size Used Avail Use% Mounted on
475 /dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X
476 # dd if=/dev/zero of=/mnt/X/1Gfile bs=4096 count=262144; sync
478 # lvs
480 pool0 vg twi-a-tz-- 10.00g 57.01 25.26
481 thin1 vg Vwi-aotz-- 100.00g pool0 3.70
482 # df -h /mnt/X
484 /dev/mapper/vg-thin1 99G 2.1G 92G 3% /mnt/X
485 # rm /mnt/X/1Gfile
487 # lvs
489 pool0 vg twi-a-tz-- 10.00g 57.01 25.26
490 thin1 vg Vwi-aotz-- 100.00g pool0 3.70
491 # df -h /mnt/X
493 /dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X
494 # fstrim -v /mnt/X
496 # lvs
498 pool0 vg twi-a-tz-- 10.00g 47.01 21.03
499 thin1 vg Vwi-aotz-- 100.00g pool0 2.70
500 The "Discard" section covers an option for automatically freeing data
502 space in a thin pool.
503 Automatically extend thin pool LV
505 The lvm daemon dmeventd (lvm2-monitor) monitors the data usage of thin
506 pool LVs and extends them when the usage reaches a certain level. The
507 necessary free space must exist in the VG to extend thin pool LVs.
508 Monitoring and extension of thin pool LVs are controlled independently.
509 — Monitoring —
511 When a thin pool LV is activated, dmeventd will begin monitoring it by
513 default.
514 Command to start or stop dmeventd monitoring a thin pool LV:
516 lvchange --monitor y|n VG/ThinPoolLV
517 The current dmeventd monitoring status of a thin pool LV can be dis‐
519 played with the command lvs -o+seg_monitor.
520 — Autoextending —
522 dmeventd should be configured to extend thin pool LVs before all data
524 space is used. Warnings are emitted through syslog when the use of a
525 thin pool reaches 80%, 85%, 90% and 95%. (See the section "Data space
526 exhaustion" for the effects of not extending a thin pool LV.) The
527 point at which dmeventd extends thin pool LVs, and the amount are con‐
528 trolled with two configuration settings:
529 lvm.conf(5) thin_pool_autoextend_threshold
531 is a percentage full value that defines when the thin pool LV should be
532 extended. Setting this to 100 disables automatic extension. The mini‐
533 mum value is 50.
534 lvm.conf(5) thin_pool_autoextend_percent
536 defines how much extra data space should be added to the thin pool LV
537 from the VG, in percent of its current size.
538 — Disabling —
540 There are multiple ways that extension of thin pools could be pre‐
542 vented:
543 • If the dmeventd daemon is not running, no monitoring or automatic ex‐
545 tension will occur.
546 • Even when dmeventd is running, all monitoring can be disabled with
548 the lvm.conf monitoring setting.
549 • To activate or create a thin pool LV without interacting with
551 dmeventd, the --ignoremonitoring option can be used. With this op‐
552 tion, the command will not ask dmeventd to monitor the thin pool LV.
553 • Setting thin_pool_autoextend_threshold to 100 disables automatic ex‐
555 tension of thin pool LVs, even if they are being monitored by
556 dmeventd.
557 Example
559 If thin_pool_autoextend_threshold is 70 and thin_pool_autoextend_per‐
560 cent is 20, whenever a pool exceeds 70% usage, it will be extended by
561 another 20%. For a 1G pool, using 700M will trigger a resize to 1.2G.
562 When the usage exceeds 840M, the pool will be extended to 1.44G, and so
563 on.
564 Data space exhaustion
566 When properly managed, thin pool data space should be extended before
567 it is all used (see the section "Automatically extend thin pool LV").
568 If thin pool data space is already exhausted, it can still be extended
569 (see the section "Manually manage free data space of thin pool LV".)
570 The behavior of a full thin pool is configurable with the --errorwhen‐
572 full y|n option to lvcreate or lvchange. The errorwhenfull setting ap‐
573 plies only to writes; reading thin LVs can continue even when data
574 space is exhausted.
575 Command to change the handling of a full thin pool:
577 lvchange --errorwhenfull y|n VG/ThinPoolLV
578 lvm.conf(5) error_when_full
580 controls the default error when full behavior.
581 The current setting of a thin pool LV can be displayed with the com‐
583 mand: lvs -o+lv_when_full.
584 The errorwhenfull setting does not effect the monitoring and autoextend
586 settings, and the monitoring/autoextend settings do not effect the er‐
587 rorwhenfull setting. It is only when monitoring/autoextend are not ef‐
588 fective that the thin pool becomes full and the errorwhenfull setting
589 is applied.
590 — errorwhenfull n —
592 This is the default. Writes to thin LVs are accepted and queued, with
594 the expectation that pool data space will be extended soon. Once data
595 space is extended, the queued writes will be processed, and the thin
596 pool will return to normal operation.
597 While waiting to be extended, the thin pool will queue writes for up to
599 60 seconds (the default). If data space has not been extended after
600 this time, the queued writes will return an error to the caller, e.g.
601 the file system. This can result in file system corruption for non-
602 journaled file systems that may require repair. When a thin pool re‐
603 turns errors for writes to a thin LV, any file system is subject to
604 losing unsynced user data.
605 The 60 second timeout can be changed or disabled with the dm-thin-pool
607 kernel module option no_space_timeout. This option sets the number of
608 seconds that thin pools will queue writes. If set to 0, writes will
609 not time out. Disabling timeouts can result in the system running out
610 of resources, memory exhaustion, hung tasks, and deadlocks. (The time‐
611 out applies to all thin pools on the system.)
612 — errorwhenfull y —
614 Writes to thin LVs immediately return an error, and no writes are
616 queued. In the case of a file system, this can result in corruption
617 that may require fs repair (the specific consequences depend on the
618 thin LV user.)
619 — data percent —
621 When data space is exhausted, the lvs command displays 100 under Data%
623 for the thin pool LV:
624 # lvs vg/pool0
626 LV VG Attr LSize Pool Origin Data%
627 pool0 vg twi-a-tz-- 512.00m 100.00
628 — causes —
630 A thin pool may run out of data space for any of the following reasons:
632 • Automatic extension of the thin pool is disabled, and the thin pool
634 is not manually extended. (Disabling automatic extension is not rec‐
635 ommended.)
636 • The dmeventd daemon is not running and the thin pool is not manually
638 extended. (Disabling dmeventd is not recommended.)
639 • Automatic extension of the thin pool is too slow given the rate of
641 writes to thin LVs in the pool. (This can be addressed by tuning the
642 thin_pool_autoextend_threshold and thin_pool_autoextend_percent. See
643 "Automatic extend settings".)
644 • The VG does not have enough free blocks to extend the thin pool.
646 Metadata space exhaustion
648 If thin pool metadata space is exhausted (or a thin pool metadata oper‐
649 ation fails), errors will be returned for IO operations on thin LVs.
650 When metadata space is exhausted, the lvs command displays 100 under
652 Meta% for the thin pool LV:
653 # lvs -o lv_name,size,data_percent,metadata_percent vg/pool0
655 LV LSize Data% Meta%
656 pool0 100.00
657 The same reasons for thin pool data space exhaustion apply to thin pool
659 metadata space.
660 Metadata space exhaustion can lead to inconsistent thin pool metadata
662 and inconsistent file systems, so the response requires offline check‐
663 ing and repair.
664 1. Deactivate the thin pool LV, or reboot the system if this is not
666 possible.
667 2. Repair thin pool with lvconvert --repair.
669 See "Metadata check and repair".
670 3. Extend pool metadata space with lvextend --poolmetadatasize.
672 See "Manually manage free metadata space of a thin pool LV".
673 4. Check and repair file system.
675 Automatic extend settings
677 Thin pool LVs can be extended according to preset values. The presets
678 determine if the LV should be extended based on how full it is, and if
679 so by how much. When dmeventd monitors thin pool LVs, it uses lvextend
680 with these presets. (See "Automatically extend thin pool LV".)
681 Command to extend a thin pool data LV using presets:
683 lvextend --use-policies VG/ThinPoolLV
684 The command uses these settings:
686 lvm.conf(5) thin_pool_autoextend_threshold
688 autoextend the LV when its usage exceeds this percent.
689 lvm.conf(5) thin_pool_autoextend_percent
691 autoextend the LV by this much additional space.
692 To see the default values of these settings, run:
694 lvmconfig --type default --withcomment
696 activation/thin_pool_autoextend_threshold
697 lvmconfig --type default --withcomment
699 activation/thin_pool_autoextend_percent
700 To change these values globally, edit lvm.conf(5).
702 To change these values on a per-VG or per-LV basis, attach a "profile"
704 to the VG or LV. A profile is a collection of config settings, saved
705 in a local text file (using the lvm.conf format). lvm looks for pro‐
706 files in the profile_dir directory, e.g. /etc/lvm/profile/. Once at‐
707 tached to a VG or LV, lvm will process the VG or LV using the settings
708 from the attached profile. A profile is named and referenced by its
709 file name.
710 To use a profile to customize the lvextend settings for an LV:
712 • Create a file containing settings, saved in profile_dir.
714 For the profile_dir location, run:
715 lvmconfig config/profile_dir
716 • Attach the profile to an LV, using the command:
718 lvchange --metadataprofile ProfileName VG/ThinPoolLV
719 • Extend the LV using the profile settings:
721 lvextend --use-policies VG/ThinPoolLV
722 Example
724 # lvmconfig config/profile_dir
725 profile_dir="/etc/lvm/profile"
726 # cat /etc/lvm/profile/pool0extend.profile
728 activation {
729 thin_pool_autoextend_threshold=50
730 thin_pool_autoextend_percent=10
731 }
732 # lvchange --metadataprofile pool0extend vg/pool0
734 # lvextend --use-policies vg/pool0
736 Notes
738 • A profile is attached to a VG or LV by name, where the name refer‐
740 ences a local file in profile_dir. If the VG is moved to another ma‐
741 chine, the file with the profile also needs to be moved.
742 • Only certain settings can be used in a VG or LV profile, see:
744 lvmconfig --type profilable-metadata.
745 • An LV without a profile of its own will inherit the VG profile.
747 • Remove a profile from an LV using the command:
749 lvchange --detachprofile VG/ThinPoolLV.
750 • Commands can also have profiles applied to them. The settings that
752 can be applied to a command are different than the settings that can
753 be applied to a VG or LV. See lvmconfig --type profilable-command.
754 To apply a profile to a command, write a profile, save it in the pro‐
755 file directory, and run the command using the option: --commandpro‐
756 file ProfileName.
757 Zeroing
759 When a thin pool provisions a new data block for a thin LV, the new
760 block is first overwritten with zeros. The zeroing mode is indicated
761 by the "z" attribute displayed by lvs. The option -Z (or --zero) can
762 be added to commands to specify the zeroing mode.
763 Command to set the zeroing mode when creating a thin pool LV:
765 lvconvert --type thin-pool -Z y|n
767 --poolmetadata VG/ThinMetaLV VG/ThinDataLV
768 Command to change the zeroing mode of an existing thin pool LV:
770 lvchange -Z y|n VG/ThinPoolLV
772 If zeroing mode is changed from "n" to "y", previously provisioned
774 blocks are not zeroed.
775 Provisioning of large zeroed chunks impacts performance.
777 lvm.conf(5) thin_pool_zero
779 controls the default zeroing mode used when creating a thin pool.
780 Discard
782 The discard behavior of a thin pool LV determines how discard requests
783 are handled. Enabling discard under a file system may adversely affect
784 the file system performance (see the section on fstrim for an alterna‐
785 tive.) Possible discard behaviors:
786 ignore: Ignore any discards that are received.
788 nopassdown: Process any discards in the thin pool itself and allow the
790 no longer needed extents to be overwritten by new data.
791 passdown: Process discards in the thin pool (as with nopassdown), and
793 pass the discards down the the underlying device. This is the default
794 mode.
795 Command to display the current discard mode of a thin pool LV:
797 lvs -o+discards VG/ThinPoolLV
798 Command to set the discard mode when creating a thin pool LV:
800 lvconvert --discards ignore|nopassdown|passdown
801 --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV
802 Command to change the discard mode of an existing thin pool LV:
804 lvchange --discards ignore|nopassdown|passdown VG/ThinPoolLV
805 Example
807 # lvs -o name,discards vg/pool0
808 pool0 passdown
809 # lvchange --discards ignore vg/pool0
811 lvm.conf(5) thin_pool_discards
813 controls the default discards mode used when creating a thin pool.
814 Chunk size
816 The size of data blocks managed by a thin pool can be specified with
817 the --chunksize option when the thin pool LV is created. The default
818 unit is KiB. The value must be a multiple of 64KiB between 64KiB and
819 1GiB.
820 When a thin pool is used primarily for the thin provisioning feature, a
822 larger value is optimal. To optimize for many snapshots, a smaller
823 value reduces copying time and consumes less space.
824 Command to display the thin pool LV chunk size:
826 lvs -o+chunksize VG/ThinPoolLV
828 Example
830 # lvs -o name,chunksize
831 pool0 64.00k
832 lvm.conf(5) thin_pool_chunk_size
834 controls the default chunk size used when creating a thin pool.
835 The default value is shown by:
837 lvmconfig --type default allocation/thin_pool_chunk_size
838 Size of pool metadata LV
840 The amount of thin metadata depends on how many blocks are shared be‐
841 tween thin LVs (i.e. through snapshots). A thin pool with many snap‐
842 shots may need a larger metadata LV. Thin pool metadata LV sizes can
843 be from 2MiB to approximately 16GiB.
844 When using lvcreate to create what will become a thin metadata LV, the
846 size is specified with the -L|--size option.
847 When an LVM command automatically creates a thin metadata LV, the size
849 is specified with the --poolmetadatasize option. When this option is
850 not given, LVM automatically chooses a size based on the data size and
851 chunk size.
852 It can be hard to predict the amount of metadata space that will be
854 needed, so it is recommended to start with a size of 1GiB which should
855 be enough for all practical purposes. A thin pool metadata LV can
856 later be manually or automatically extended if needed.
857 Configurable setting lvm.conf(5) allocation/thin_pool_crop_metadata
859 gives control over cropping to 15.81GiB to stay backward compatible
860 with older versions of lvm2. With enabled cropping there can be ob‐
861 served some problems when using volumes above this size with thin tools
862 (i.e. thin_repair). Cropping should be enabled only when compatibility
863 is required.
864 Create a thin snapshot of an external, read only LV
866 Thin snapshots are typically taken of other thin LVs or other thin
867 snapshot LVs within the same thin pool. It is also possible to take
868 thin snapshots of external, read only LVs. Writes to the snapshot are
869 stored in the thin pool, and the external LV is used to read unwritten
870 parts of the thin snapshot.
871 lvcreate -n SnapLV -s VG/ExternalOriginLV --thinpool VG/ThinPoolLV
873 Example
875 # lvchange -an vg/lve
876 # lvchange --permission r vg/lve
877 # lvcreate -n snaplve -s vg/lve --thinpool vg/pool0
878 # lvs vg/lve vg/snaplve
880 LV VG Attr LSize Pool Origin Data%
881 lve vg ori------- 10.00g
882 snaplve vg Vwi-a-tz-- 10.00g pool0 lve 0.00
883 Convert a standard LV to a thin LV with an external origin
885 A new thin LV can be created and given the name of an existing standard
886 LV. At the same time, the existing LV is converted to a read only ex‐
887 ternal LV with a new name. Unwritten portions of the thin LV are read
888 from the external LV. The new name given to the existing LV can be
889 specified with --originname, otherwise the existing LV will be given a
890 default name, e.g. lvol#.
891 Convert ExampleLV into a read only external LV with the new name NewEx‐
893 ternalOriginLV, and create a new thin LV that is given the previous
894 name of ExampleLV.
895 lvconvert --type thin --thinpool VG/ThinPoolLV
897 --originname NewExternalOriginLV VG/ExampleLV
898 Example
900 # lvcreate -n lv_example -L 10G vg
901 # lvs
903 lv_example vg -wi-a----- 10.00g
904 # lvconvert --type thin --thinpool vg/pool0
906 --originname lv_external --thin vg/lv_example
907 # lvs
909 LV VG Attr LSize Pool Origin
910 lv_example vg Vwi-a-tz-- 10.00g pool0 lv_external
911 lv_external vg ori------- 10.00g
912 Single step thin pool LV creation
914 A thin pool LV can be created with a single lvcreate command, rather
915 than using lvconvert on existing LVs. This one command creates a thin
916 data LV, a thin metadata LV, and combines the two into a thin pool LV.
917 lvcreate --type thin-pool -L LargeSize -n ThinPoolLV VG
919 Example
921 # lvcreate --type thin-pool -L8M -n pool0 vg
922 # lvs vg/pool0
924 LV VG Attr LSize Pool Origin Data%
925 pool0 vg twi-a-tz-- 8.00m 0.00
926 # lvs -a
928 pool0 vg twi-a-tz-- 8.00m
929 [pool0_tdata] vg Twi-ao---- 8.00m
930 [pool0_tmeta] vg ewi-ao---- 8.00m
931 Single step thin pool LV and thin LV creation
933 A thin pool LV and a thin LV can be created with a single lvcreate com‐
934 mand. This one command creates a thin data LV, a thin metadata LV,
935 combines the two into a thin pool LV, and creates a thin LV in the new
936 pool.
937 -L LargeSize specifies the physical size of the thin pool LV.
938 -V VirtualSize specifies the virtual size of the thin LV.
939 lvcreate --type thin -V VirtualSize -L LargeSize
941 -n ThinLV --thinpool VG/ThinPoolLV
942 Equivalent to:
944 lvcreate --type thin-pool -L LargeSize VG/ThinPoolLV
945 lvcreate -n ThinLV -V VirtualSize --thinpool VG/ThinPoolLV
946 Example
948 # lvcreate -L8M -V2G -n thin1 --thinpool vg/pool0
949 # lvs -a
951 pool0 vg twi-a-tz-- 8.00m
952 [pool0_tdata] vg Twi-ao---- 8.00m
953 [pool0_tmeta] vg ewi-ao---- 8.00m
954 thin1 vg Vwi-a-tz-- 2.00g pool0
955 Merge thin snapshots
957 A thin snapshot can be merged into its origin thin LV using the lvcon‐
958 vert --merge command. The result of a snapshot merge is that the ori‐
959 gin thin LV takes the content of the snapshot LV, and the snapshot LV
960 is removed. Any content that was unique to the origin thin LV is lost
961 after the merge.
962 Because a merge changes the content of an LV, it cannot be done while
964 the LVs are open, e.g. mounted. If a merge is initiated while the LVs
965 are open, the effect of the merge is delayed until the origin thin LV
966 is next activated.
967 lvconvert --merge VG/SnapLV
969 Example
971 # lvs vg
972 LV VG Attr LSize Pool Origin
973 pool0 vg twi-a-tz-- 10.00g
974 thin1 vg Vwi-a-tz-- 100.00g pool0
975 thin1s1 vg Vwi-a-tz-k 100.00g pool0 thin1
976 # lvconvert --merge vg/thin1s1
978 # lvs vg
980 LV VG Attr LSize Pool Origin
981 pool0 vg twi-a-tz-- 10.00g
982 thin1 vg Vwi-a-tz-- 100.00g pool0
983 Example
985 Delayed merging of open LVs.
986 # lvs vg
988 LV VG Attr LSize Pool Origin
989 pool0 vg twi-a-tz-- 10.00g
990 thin1 vg Vwi-aotz-- 100.00g pool0
991 thin1s1 vg Vwi-aotz-k 100.00g pool0 thin1
992 # df
994 /dev/mapper/vg-thin1 100G 33M 100G 1% /mnt/X
995 /dev/mapper/vg-thin1s1 100G 33M 100G 1% /mnt/Xs
996 # ls /mnt/X
998 file1 file2 file3
999 # ls /mnt/Xs
1000 file3 file4 file5
1001 # lvconvert --merge vg/thin1s1
1003 Logical volume vg/thin1s1 contains a filesystem in use.
1004 Delaying merge since snapshot is open.
1005 Merging of thin snapshot thin1s1 will occur on next activation.
1006 # umount /mnt/X
1008 # umount /mnt/Xs
1009 # lvs -a vg
1011 LV VG Attr LSize Pool Origin
1012 pool0 vg twi-a-tz-- 10.00g
1013 [pool0_tdata] vg Twi-ao---- 10.00g
1014 [pool0_tmeta] vg ewi-ao---- 1.00g
1015 thin1 vg Owi-a-tz-- 100.00g pool0
1016 [thin1s1] vg Swi-a-tz-k 100.00g pool0 thin1
1017 # lvchange -an vg/thin1
1019 # lvchange -ay vg/thin1
1020 # mount /dev/vg/thin1 /mnt/X
1022 # ls /mnt/X
1024 file3 file4 file5
1025 XFS on snapshots
1027 Mounting an XFS file system on a new snapshot LV requires attention to
1028 the file system's log state and uuid. On the snapshot LV, the xfs log
1029 will contain a dummy transaction, and the xfs uuid will match the uuid
1030 from the file system on the origin LV.
1031 If the snapshot LV is writable, mounting will recover the log to clear
1033 the dummy transaction, but will require skipping the uuid check:
1034 # mount /dev/VG/SnapLV /mnt -o nouuid
1036 After the first mount with the above approach, the UUID can subse‐
1038 quently be changed using:
1039 # xfs_admin -U generate /dev/VG/SnapLV
1041 # mount /dev/VG/SnapLV /mnt
1043 Once the UUID has been changed, the mount command will no longer re‐
1045 quire the nouuid option.
1046 If the snapshot LV is readonly, the log recovery and uuid check need to
1048 be skipped while mounting readonly:
1049 # mount /dev/VG/SnapLV /mnt -o ro,nouuid,norecovery
1051
1053 lvm(8), lvm.conf(5), lvmconfig(8), lvcreate(8), lvconvert(8),
1054 lvchange(8), lvextend(8), lvremove(8), lvs(8),
1055 thin_dump(8), thin_repair(8), thin_restore(8)
1057Red Hat, Inc LVM TOOLS 2.03.18(2)-git (2022-11-10) LVMTHIN(7)