{ "mode": "man", "parameter": "LVMTHIN", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/LVMTHIN/7/json", "generated": "2026-10-22T13:28:30Z", "sections": { "NAME": { "content": "lvmthin — LVM thin provisioning\n", "subsections": [] }, "DESCRIPTION": { "content": "Blocks in a standard lvm(8) Logical Volume (LV) are allocated when the LV is created, but\nblocks in a thin provisioned LV are allocated as they are written. Because of this, a thin\nprovisioned LV is given a virtual size, and can then be much larger than physically available\nstorage. The amount of physical storage provided for thin provisioned LVs can be increased\nlater as the need arises.\n\nBlocks in a standard LV are allocated (during creation) from the Volume Group (VG), but\nblocks in a thin LV are allocated (during use) from a special \"thin pool LV\". The thin pool\nLV contains blocks of physical storage, and blocks in thin LVs just reference blocks in the\nthin pool LV.\n\nA thin pool LV must be created before thin LVs can be created within it. A thin pool LV is\ncreated by combining two standard LVs: a large data LV that will hold blocks for thin LVs,\nand a metadata LV that will hold metadata. The metadata tracks which data blocks belong to\neach thin LV.\n\nSnapshots of thin LVs are efficient because the data blocks common to a thin LV and any of\nits snapshots are shared. Snapshots may be taken of thin LVs or of other thin snapshots.\nBlocks common to recursive snapshots are also shared in the thin pool. There is no limit to\nor degradation from sequences of snapshots.\n\nAs thin LVs or snapshot LVs are written to, they consume data blocks in the thin pool. As\nfree data blocks in the pool decrease, more free blocks may need to be supplied. This is\ndone by extending the thin pool data LV with additional physical space from the VG. Removing\nthin LVs or snapshots from the thin pool can also free blocks in the thin pool. However, re‐\nmoving LVs is not always an effective way of freeing space in a thin pool because the amount\nis limited to the number of blocks not shared with other LVs in the pool.\n\nIncremental block allocation from thin pools can cause thin LVs to become fragmented. Stan‐\ndard LVs generally avoid this problem by allocating all the blocks at once during creation.\n", "subsections": [] }, "THIN TERMS": { "content": "ThinDataLV\nthin data LV\nlarge LV created in a VG\nused by thin pool to store ThinLV blocks\n\nThinMetaLV\nthin metadata LV\nsmall LV created in a VG\nused by thin pool to track data block usage\n\nThinPoolLV\nthin pool LV\ncombination of ThinDataLV and ThinMetaLV\ncontains ThinLVs and SnapLVs\n\nThinLV\nthin LV\ncreated from ThinPoolLV\nappears blank after creation\n\nSnapLV\nsnapshot LV\ncreated from ThinPoolLV\nappears as a snapshot of another LV after creation\n", "subsections": [] }, "THIN USAGE": { "content": "The primary method for using lvm thin provisioning:\n", "subsections": [ { "name": "1. Create ThinDataLV", "content": "Create an LV that will hold thin pool data.\n" }, { "name": "lvcreate -n ThinDataLV -L LargeSize VG", "content": "Example\n# lvcreate -n pool0 -L 10G vg\n" }, { "name": "2. Create ThinMetaLV", "content": "Create an LV that will hold thin pool metadata.\n" }, { "name": "lvcreate -n ThinMetaLV -L SmallSize VG", "content": "Example\n# lvcreate -n pool0meta -L 1G vg\n\n# lvs\nLV VG Attr LSize\npool0 vg -wi-a----- 10.00g\npool0meta vg -wi-a----- 1.00g\n" }, { "name": "3. Create ThinPoolLV", "content": "Combine the data and metadata LVs into a thin pool LV.\nThinDataLV is renamed to hidden ThinPoolLVtdata.\nThinMetaLV is renamed to hidden ThinPoolLVtmeta.\nThe new ThinPoolLV takes the previous name of ThinDataLV.\n" }, { "name": "lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV", "content": "Example\n# lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0\n\n# lvs vg/pool0\nLV VG Attr LSize Pool Origin Data% Meta%\npool0 vg twi-a-tz-- 10.00g 0.00 0.00\n\n# lvs -a\nLV VG Attr LSize\npool0 vg twi-a-tz-- 10.00g\n[pool0tdata] vg Twi-ao---- 10.00g\n[pool0tmeta] vg ewi-ao---- 1.00g\n" }, { "name": "4. Create ThinLV", "content": "Create a new thin LV from the thin pool LV.\nThe thin LV is created with a virtual size.\nMultiple new thin LVs may be created in the thin pool.\nThin LV names must be unique in the VG.\nThe '--type thin' option is inferred from the virtual size option.\nThe --thinpool argument specifies which thin pool will\ncontain the ThinLV.\n" }, { "name": "lvcreate -n ThinLV -V VirtualSize --thinpool ThinPoolLV VG", "content": "Example\nCreate a thin LV in a thin pool:\n# lvcreate -n thin1 -V 1T --thinpool pool0 vg\n\nCreate another thin LV in the same thin pool:\n# lvcreate -n thin2 -V 1T --thinpool pool0 vg\n\n# lvs vg/thin1 vg/thin2\nLV VG Attr LSize Pool Origin Data%\nthin1 vg Vwi-a-tz-- 1.00t pool0 0.00\nthin2 vg Vwi-a-tz-- 1.00t pool0 0.00\n" }, { "name": "5. Create SnapLV", "content": "Create snapshots of an existing ThinLV or SnapLV.\nDo not specify -L, --size when creating a thin snapshot.\nA size argument will cause an old COW snapshot to be created.\n" }, { "name": "lvcreate -n SnapLV --snapshot VG/ThinLV", "content": "" }, { "name": "lvcreate -n SnapLV --snapshot VG/PrevSnapLV", "content": "Example\nCreate first snapshot of an existing ThinLV:\n# lvcreate -n thin1s1 -s vg/thin1\n\nCreate second snapshot of the same ThinLV:\n# lvcreate -n thin1s2 -s vg/thin1\n\nCreate a snapshot of the first snapshot:\n# lvcreate -n thin1s1s1 -s vg/thin1s1\n\n# lvs vg/thin1s1 vg/thin1s2 vg/thin1s1s1\nLV VG Attr LSize Pool Origin\nthin1s1 vg Vwi---tz-k 1.00t pool0 thin1\nthin1s2 vg Vwi---tz-k 1.00t pool0 thin1\nthin1s1s1 vg Vwi---tz-k 1.00t pool0 thin1s1\n" }, { "name": "6. Activate SnapLV", "content": "Thin snapshots are created with the persistent \"activation skip\" flag, indicated by the \"k\"\nattribute. Use -K with lvchange or vgchange to activate thin snapshots with the \"k\" at‐\ntribute.\n" }, { "name": "lvchange -ay -K VG/SnapLV", "content": "Example\n# lvchange -ay -K vg/thin1s1\n\n# lvs vg/thin1s1\nLV VG Attr LSize Pool Origin\nthin1s1 vg Vwi-a-tz-k 1.00t pool0 thin1\n" } ] }, "THIN TOPICS": { "content": "", "subsections": [ { "name": "Automatic pool metadata LV", "content": "" }, { "name": "Specify devices for data and metadata LVs", "content": "" }, { "name": "Tolerate device failures using raid", "content": "" }, { "name": "Spare metadata LV", "content": "" }, { "name": "Metadata check and repair", "content": "" }, { "name": "Activation of thin snapshots", "content": "" }, { "name": "Removing thin pool LVs, thin LVs and snapshots", "content": "" }, { "name": "Manually manage free data space of thin pool LV", "content": "" }, { "name": "Manually manage free metadata space of a thin pool LV", "content": "" }, { "name": "Using fstrim to increase free space in a thin pool LV", "content": "" }, { "name": "Automatically extend thin pool LV", "content": "" }, { "name": "Data space exhaustion", "content": "" }, { "name": "Metadata space exhaustion", "content": "" }, { "name": "Automatic extend settings", "content": "" }, { "name": "Zeroing", "content": "" }, { "name": "Discard", "content": "" }, { "name": "Chunk size", "content": "" }, { "name": "Size of pool metadata LV", "content": "" }, { "name": "Create a thin snapshot of an external, read only LV", "content": "" }, { "name": "Convert a standard LV to a thin LV with an external origin", "content": "" }, { "name": "Single step thin pool LV creation", "content": "" }, { "name": "Single step thin pool LV and thin LV creation", "content": "" }, { "name": "Merge thin snapshots", "content": "" }, { "name": "XFS on snapshots", "content": "" }, { "name": "Automatic pool metadata LV", "content": "A thin data LV can be converted to a thin pool LV without specifying a thin pool metadata LV.\nLVM automatically creates a metadata LV from the same VG.\n" }, { "name": "lvcreate -n ThinDataLV -L LargeSize VG", "content": "" }, { "name": "lvconvert --type thin-pool VG/ThinDataLV", "content": "Example\n# lvcreate -n pool0 -L 10G vg\n# lvconvert --type thin-pool vg/pool0\n\n# lvs -a\npool0 vg twi-a-tz-- 10.00g\n[pool0tdata] vg Twi-ao---- 10.00g\n[pool0tmeta] vg ewi-ao---- 16.00m\n" }, { "name": "Specify devices for data and metadata LVs", "content": "The data and metadata LVs in a thin pool are best created on separate physical devices. To\ndo that, specify the device name(s) at the end of the lvcreate line. It can be especially\nhelpful to use fast devices for the metadata LV.\n" }, { "name": "lvcreate -n ThinDataLV -L LargeSize VG LargePV", "content": "" }, { "name": "lvcreate -n ThinMetaLV -L SmallSize VG SmallPV", "content": "" }, { "name": "lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV", "content": "Example\n# lvcreate -n pool0 -L 10G vg /dev/sdA\n# lvcreate -n pool0meta -L 1G vg /dev/sdB\n# lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0\n\nlvm.conf(5) thinpoolmetadatarequireseparatepvs\ncontrols the default PV usage for thin pool creation.\n" }, { "name": "Tolerate device failures using raid", "content": "To tolerate device failures, use raid for the pool data LV and pool metadata LV. This is es‐\npecially recommended for pool metadata LVs.\n" }, { "name": "lvcreate --type raid1 -m 1 -n ThinMetaLV -L SmallSize VG PVA PVB", "content": "" }, { "name": "lvcreate --type raid1 -m 1 -n ThinDataLV -L LargeSize VG PVC PVD", "content": "" }, { "name": "lvconvert --type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV", "content": "Example\n# lvcreate --type raid1 -m 1 -n pool0 -L 10G vg /dev/sdA /dev/sdB\n# lvcreate --type raid1 -m 1 -n pool0meta -L 1G vg /dev/sdC /dev/sdD\n# lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0\n" }, { "name": "Spare metadata LV", "content": "The first time a thin pool LV is created, lvm will create a spare metadata LV in the VG.\nThis behavior can be controlled with the option --poolmetadataspare y|n. (Future thin pool\ncreations will also attempt to create the pmspare LV if none exists.)\n\nTo create the pmspare (\"pool metadata spare\") LV, lvm first creates an LV with a default\nname, e.g. lvol0, and then converts this LV to a hidden LV with the pmspare suffix, e.g.\nlvol0pmspare.\n\nOne pmspare LV is kept in a VG to be used for any thin pool.\n\nThe pmspare LV cannot be created explicitly, but may be removed explicitly.\n\nExample\n# lvcreate -n pool0 -L 10G vg\n# lvcreate -n pool0meta -L 1G vg\n# lvconvert --type thin-pool --poolmetadata vg/pool0meta vg/pool0\n\n# lvs -a\n[lvol0pmspare] vg ewi-------\npool0 vg twi---tz--\n[pool0tdata] vg Twi-------\n[pool0tmeta] vg ewi-------\n\nThe \"Metadata check and repair\" section describes the use of the pmspare LV.\n" }, { "name": "Metadata check and repair", "content": "If thin pool metadata is damaged, it may be repairable. Checking and repairing thin pool\nmetadata is analogous to running fsck/repair on a file system.\n\nWhen a thin pool LV is activated, lvm runs the thincheck command to check the correctness of\nthe metadata on the pool metadata LV.\n\nlvm.conf(5) thincheckexecutable\ncan be set to an empty string (\"\") to disable the thincheck step. This is not recommended.\n\nlvm.conf(5) thincheckoptions\ncontrols the command options used for the thincheck command.\n\nIf the thincheck command finds a problem with the metadata, the thin pool LV is not acti‐\nvated, and the thin pool metadata needs to be repaired.\n\nSimple repair commands are not always successful. Advanced repair may require editing thin\npool metadata and lvm metadata. Newer versions of the kernel and lvm tools may be more suc‐\ncessful at repair. Report the details of damaged thin metadata to get the best advice on re‐\ncovery.\n\nCommand to repair a thin pool:" }, { "name": "lvconvert --repair VG/ThinPoolLV", "content": "Repair performs the following steps:\n\n1 Creates a new, repaired copy of the metadata.\nlvconvert runs the thinrepair command to read damaged metadata from the existing pool\nmetadata LV, and writes a new repaired copy to the VG's pmspare LV.\n\n2 Replaces the thin pool metadata LV.\nIf step 1 is successful, the thin pool metadata LV is replaced with the pmspare LV con‐\ntaining the corrected metadata. The previous thin pool metadata LV, containing the dam‐\naged metadata, becomes visible with the new name ThinPoolLVmetaN (where N is 0,1,...).\n\nIf the repair works, the thin pool LV and its thin LVs can be activated. User should manu‐\nally check if repaired thin pool kernel metadata has all data for all lvm2 known LVs by indi‐\nvidual activation of every thin LV. When all works, user should continue with fsck of all\nfilesystems present on these volumes. Once the thin pool is considered fully functional user\nmay remove ThinPoolLVmetaN (the LV containing the damaged thin pool metadata) for possible\nspace reuse. For a better performance it may be useful to pvmove the new repaired metadata\nLV (written to previous pmspare volume) to a faster PV, e.g. SSD.\n\nIf the repair operation fails, the thin pool LV and its thin LVs are not accessible and it\nmay be necessary to restore their content from a backup. In such case the content of unmodi‐\nfied original damaged ThinPoolLVmetaN volume can be used by your support for more advanced\nrecovery methods.\n\nIf metadata is manually restored with thinrepair directly, the pool metadata LV can be manu‐\nally swapped with another LV containing new metadata:\n" }, { "name": "lvconvert --thinpool VG/ThinPoolLV --poolmetadata VG/NewThinMetaLV", "content": "Note: Thin pool metadata is compact so even small corruptions in them may result in signifi‐\ncant portions of mappings to be lost. It is recommended to use fast resilient storage for\nthem.\n" }, { "name": "Activation of thin snapshots", "content": "When a thin snapshot LV is created, it is by default given the \"activation skip\" flag. This\nflag is indicated by the \"k\" attribute displayed by lvs:\n\n# lvs vg/thin1s1\nLV VG Attr LSize Pool Origin\nthin1s1 vg Vwi---tz-k 1.00t pool0 thin1\n\nThis flag causes the snapshot LV to be skipped, i.e. not activated, by normal activation com‐\nmands. The skipping behavior does not apply to deactivation commands.\n\nA snapshot LV with the \"k\" attribute can be activated using the -K (or --ignoreactivation‐\nskip) option in addition to the standard -ay (or --activate y) option.\n\nCommand to activate a thin snapshot LV:" }, { "name": "lvchange -ay -K VG/SnapLV", "content": "The persistent \"activation skip\" flag can be turned off during lvcreate, or later with\nlvchange using the -kn (or --setactivationskip n) option. It can be turned on again with -ky\n(or --setactivationskip y).\n\nWhen the \"activation skip\" flag is removed, normal activation commands will activate the LV,\nand the -K activation option is not needed.\n\nCommand to create snapshot LV without the activation skip flag:" }, { "name": "lvcreate -kn -n SnapLV -s VG/ThinLV", "content": "Command to remove the activation skip flag from a snapshot LV:" }, { "name": "lvchange -kn VG/SnapLV", "content": "lvm.conf(5) autosetactivationskip\ncontrols the default activation skip setting used by lvcreate.\n" }, { "name": "Removing thin pool LVs, thin LVs and snapshots", "content": "Removing a thin LV and its related snapshots returns the blocks it used to the thin pool LV.\nThese blocks will be reused for other thin LVs and snapshots.\n\nRemoving a thin pool LV removes both the data LV and metadata LV and returns the space to the\nVG.\n\nlvremove of thin pool LVs, thin LVs and snapshots cannot be reversed with vgcfgrestore.\n\nvgcfgbackup does not back up thin pool metadata.\n" }, { "name": "Manually manage free data space of thin pool LV", "content": "The available free space in a thin pool LV can be displayed with the lvs command. Free space\ncan be added by extending the thin pool LV.\n\nCommand to extend thin pool data space:" }, { "name": "lvextend -L Size VG/ThinPoolLV", "content": "Example\n1. A thin pool LV is using 26.96% of its data blocks.\n# lvs\nLV VG Attr LSize Pool Origin Data%\npool0 vg twi-a-tz-- 10.00g 26.96\n\n2. Double the amount of physical space in the thin pool LV.\n# lvextend -L+10G vg/pool0\n\n3. The percentage of used data blocks is half the previous value.\n# lvs\nLV VG Attr LSize Pool Origin Data%\npool0 vg twi-a-tz-- 20.00g 13.48\n\nOther methods of increasing free data space in a thin pool LV include removing a thin LV and\nits related snapshots, or running fstrim on the file system using a thin LV.\n" }, { "name": "Manually manage free metadata space of a thin pool LV", "content": "The available metadata space in a thin pool LV can be displayed with the lvs -o+metadataper‐\ncent command.\n\nCommand to extend thin pool metadata space:" }, { "name": "lvextend --poolmetadatasize Size VG/ThinPoolLV", "content": "Example\n1. A thin pool LV is using 12.40% of its metadata blocks.\n# lvs -oname,size,datapercent,metadatapercent vg/pool0\nLV LSize Data% Meta%\npool0 20.00g 13.48 12.40\n\n2. Display a thin pool LV with its component thin data LV and thin metadata LV.\n# lvs -a -oname,attr,size vg\nLV Attr LSize\npool0 twi-a-tz-- 20.00g\n[pool0tdata] Twi-ao---- 20.00g\n[pool0tmeta] ewi-ao---- 12.00m\n\n3. Double the amount of physical space in the thin metadata LV.\n# lvextend --poolmetadatasize +12M vg/pool0\n\n4. The percentage of used metadata blocks is half the previous value.\n# lvs -a -oname,size,datapercent,metadatapercent vg\nLV LSize Data% Meta%\npool0 20.00g 13.48 6.20\n[pool0tdata] 20.00g\n[pool0tmeta] 24.00m\n" }, { "name": "Using fstrim to increase free space in a thin pool LV", "content": "Removing files in a file system on top of a thin LV does not generally add free space back to\nthe thin pool. Manually running the fstrim command can return space back to the thin pool\nthat had been used by removed files. fstrim uses discards and will not work if the thin pool\nLV has discards mode set to ignore.\n\nExample\nA thin pool has 10G of physical data space, and a thin LV has a virtual size of 100G. Writ‐\ning a 1G file to the file system reduces the free space in the thin pool by 10% and increases\nthe virtual usage of the file system by 1%. Removing the 1G file restores the virtual 1% to\nthe file system, but does not restore the physical 10% to the thin pool. The fstrim command\nrestores the physical space to the thin pool.\n\n# lvs -a -oname,attr,size,poollv,origin,datapercent,metadatapercent vg\nLV Attr LSize Pool Origin Data% Meta%\npool0 twi-a-tz-- 10.00g 47.01 21.03\nthin1 Vwi-aotz-- 100.00g pool0 2.70\n\n# df -h /mnt/X\nFilesystem Size Used Avail Use% Mounted on\n/dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X\n\n# dd if=/dev/zero of=/mnt/X/1Gfile bs=4096 count=262144; sync\n\n# lvs\npool0 vg twi-a-tz-- 10.00g 57.01 25.26\nthin1 vg Vwi-aotz-- 100.00g pool0 3.70\n\n# df -h /mnt/X\n/dev/mapper/vg-thin1 99G 2.1G 92G 3% /mnt/X\n\n# rm /mnt/X/1Gfile\n\n# lvs\npool0 vg twi-a-tz-- 10.00g 57.01 25.26\nthin1 vg Vwi-aotz-- 100.00g pool0 3.70\n\n# df -h /mnt/X\n/dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X\n\n# fstrim -v /mnt/X\n\n# lvs\npool0 vg twi-a-tz-- 10.00g 47.01 21.03\nthin1 vg Vwi-aotz-- 100.00g pool0 2.70\n\nThe \"Discard\" section covers an option for automatically freeing data space in a thin pool.\n" }, { "name": "Automatically extend thin pool LV", "content": "The lvm daemon dmeventd (lvm2-monitor) monitors the data usage of thin pool LVs and extends\nthem when the usage reaches a certain level. The necessary free space must exist in the VG\nto extend thin pool LVs. Monitoring and extension of thin pool LVs are controlled indepen‐\ndently.\n\n— Monitoring —\n\nWhen a thin pool LV is activated, dmeventd will begin monitoring it by default.\n\nCommand to start or stop dmeventd monitoring a thin pool LV:" }, { "name": "lvchange --monitor y|n VG/ThinPoolLV", "content": "The current dmeventd monitoring status of a thin pool LV can be displayed with the command\nlvs -o+segmonitor.\n\n— Autoextending —\n\ndmeventd should be configured to extend thin pool LVs before all data space is used. Warn‐\nings are emitted through syslog when the use of a thin pool reaches 80%, 85%, 90% and 95%.\n(See the section \"Data space exhaustion\" for the effects of not extending a thin pool LV.)\nThe point at which dmeventd extends thin pool LVs, and the amount are controlled with two\nconfiguration settings:\n\nlvm.conf(5) thinpoolautoextendthreshold\nis a percentage full value that defines when the thin pool LV should be extended. Setting\nthis to 100 disables automatic extension. The minimum value is 50.\n\nlvm.conf(5) thinpoolautoextendpercent\ndefines how much extra data space should be added to the thin pool LV from the VG, in percent\nof its current size.\n\n— Disabling —\n\nThere are multiple ways that extension of thin pools could be prevented:\n\n• If the dmeventd daemon is not running, no monitoring or automatic extension will occur.\n\n• Even when dmeventd is running, all monitoring can be disabled with the lvm.conf monitoring\nsetting.\n\n• To activate or create a thin pool LV without interacting with dmeventd, the --ignoremoni‐\ntoring option can be used. With this option, the command will not ask dmeventd to monitor\nthe thin pool LV.\n\n• Setting thinpoolautoextendthreshold to 100 disables automatic extension of thin pool\nLVs, even if they are being monitored by dmeventd.\n\nExample\nIf thinpoolautoextendthreshold is 70 and thinpoolautoextendpercent is 20, whenever a\npool exceeds 70% usage, it will be extended by another 20%. For a 1G pool, using 700M will\ntrigger a resize to 1.2G. When the usage exceeds 840M, the pool will be extended to 1.44G,\nand so on.\n" }, { "name": "Data space exhaustion", "content": "When properly managed, thin pool data space should be extended before it is all used (see the\nsection \"Automatically extend thin pool LV\"). If thin pool data space is already exhausted,\nit can still be extended (see the section \"Manually manage free data space of thin pool LV\".)\n\nThe behavior of a full thin pool is configurable with the --errorwhenfull y|n option to\nlvcreate or lvchange. The errorwhenfull setting applies only to writes; reading thin LVs can\ncontinue even when data space is exhausted.\n\nCommand to change the handling of a full thin pool:" }, { "name": "lvchange --errorwhenfull y|n VG/ThinPoolLV", "content": "lvm.conf(5) errorwhenfull\ncontrols the default error when full behavior.\n\nThe current setting of a thin pool LV can be displayed with the command: lvs -o+lvwhenfull.\n\nThe errorwhenfull setting does not effect the monitoring and autoextend settings, and the\nmonitoring/autoextend settings do not effect the errorwhenfull setting. It is only when mon‐\nitoring/autoextend are not effective that the thin pool becomes full and the errorwhenfull\nsetting is applied.\n\n— errorwhenfull n —\n\nThis is the default. Writes to thin LVs are accepted and queued, with the expectation that\npool data space will be extended soon. Once data space is extended, the queued writes will\nbe processed, and the thin pool will return to normal operation.\n\nWhile waiting to be extended, the thin pool will queue writes for up to 60 seconds (the de‐\nfault). If data space has not been extended after this time, the queued writes will return\nan error to the caller, e.g. the file system. This can result in file system corruption for\nnon-journaled file systems that may require repair. When a thin pool returns errors for\nwrites to a thin LV, any file system is subject to losing unsynced user data.\n\nThe 60 second timeout can be changed or disabled with the dm-thin-pool kernel module option\nnospacetimeout. This option sets the number of seconds that thin pools will queue writes.\nIf set to 0, writes will not time out. Disabling timeouts can result in the system running\nout of resources, memory exhaustion, hung tasks, and deadlocks. (The timeout applies to all\nthin pools on the system.)\n\n— errorwhenfull y —\n\nWrites to thin LVs immediately return an error, and no writes are queued. In the case of a\nfile system, this can result in corruption that may require fs repair (the specific conse‐\nquences depend on the thin LV user.)\n\n— data percent —\n\nWhen data space is exhausted, the lvs command displays 100 under Data% for the thin pool LV:\n\n# lvs vg/pool0\nLV VG Attr LSize Pool Origin Data%\npool0 vg twi-a-tz-- 512.00m 100.00\n\n— causes —\n\nA thin pool may run out of data space for any of the following reasons:\n\n• Automatic extension of the thin pool is disabled, and the thin pool is not manually ex‐\ntended. (Disabling automatic extension is not recommended.)\n\n• The dmeventd daemon is not running and the thin pool is not manually extended. (Disabling\ndmeventd is not recommended.)\n\n• Automatic extension of the thin pool is too slow given the rate of writes to thin LVs in\nthe pool. (This can be addressed by tuning the thinpoolautoextendthreshold and\nthinpoolautoextendpercent. See \"Automatic extend settings\".)\n\n• The VG does not have enough free blocks to extend the thin pool.\n" }, { "name": "Metadata space exhaustion", "content": "If thin pool metadata space is exhausted (or a thin pool metadata operation fails), errors\nwill be returned for IO operations on thin LVs.\n\nWhen metadata space is exhausted, the lvs command displays 100 under Meta% for the thin pool\nLV:\n\n# lvs -o lvname,size,datapercent,metadatapercent vg/pool0\nLV LSize Data% Meta%\npool0 100.00\n\nThe same reasons for thin pool data space exhaustion apply to thin pool metadata space.\n\nMetadata space exhaustion can lead to inconsistent thin pool metadata and inconsistent file\nsystems, so the response requires offline checking and repair.\n\n1. Deactivate the thin pool LV, or reboot the system if this is not possible.\n\n2. Repair thin pool with lvconvert --repair.\nSee \"Metadata check and repair\".\n\n3. Extend pool metadata space with lvextend --poolmetadatasize.\nSee \"Manually manage free metadata space of a thin pool LV\".\n\n4. Check and repair file system.\n" }, { "name": "Automatic extend settings", "content": "Thin pool LVs can be extended according to preset values. The presets determine if the LV\nshould be extended based on how full it is, and if so by how much. When dmeventd monitors\nthin pool LVs, it uses lvextend with these presets. (See \"Automatically extend thin pool\nLV\".)\n\nCommand to extend a thin pool data LV using presets:" }, { "name": "lvextend --use-policies VG/ThinPoolLV", "content": "The command uses these settings:\n\nlvm.conf(5) thinpoolautoextendthreshold\nautoextend the LV when its usage exceeds this percent.\n\nlvm.conf(5) thinpoolautoextendpercent\nautoextend the LV by this much additional space.\n\nTo see the default values of these settings, run:\n" }, { "name": "lvmconfig --type default --withcomment", "content": "activation/thinpoolautoextendthreshold\n" }, { "name": "lvmconfig --type default --withcomment", "content": "activation/thinpoolautoextendpercent\n\nTo change these values globally, edit lvm.conf(5).\n\nTo change these values on a per-VG or per-LV basis, attach a \"profile\" to the VG or LV. A\nprofile is a collection of config settings, saved in a local text file (using the lvm.conf\nformat). lvm looks for profiles in the profiledir directory, e.g. /etc/lvm/profile/. Once\nattached to a VG or LV, lvm will process the VG or LV using the settings from the attached\nprofile. A profile is named and referenced by its file name.\n\nTo use a profile to customize the lvextend settings for an LV:\n\n• Create a file containing settings, saved in profiledir.\nFor the profiledir location, run:\nlvmconfig config/profiledir\n\n• Attach the profile to an LV, using the command:\nlvchange --metadataprofile ProfileName VG/ThinPoolLV\n\n• Extend the LV using the profile settings:\nlvextend --use-policies VG/ThinPoolLV\n\nExample\n# lvmconfig config/profiledir\nprofiledir=\"/etc/lvm/profile\"\n\n# cat /etc/lvm/profile/pool0extend.profile\nactivation {\nthinpoolautoextendthreshold=50\nthinpoolautoextendpercent=10\n}\n\n# lvchange --metadataprofile pool0extend vg/pool0\n\n# lvextend --use-policies vg/pool0\n\nNotes\n\n• A profile is attached to a VG or LV by name, where the name references a local file in pro‐\nfiledir. If the VG is moved to another machine, the file with the profile also needs to\nbe moved.\n\n• Only certain settings can be used in a VG or LV profile, see:\nlvmconfig --type profilable-metadata.\n\n• An LV without a profile of its own will inherit the VG profile.\n\n• Remove a profile from an LV using the command:\nlvchange --detachprofile VG/ThinPoolLV.\n\n• Commands can also have profiles applied to them. The settings that can be applied to a\ncommand are different than the settings that can be applied to a VG or LV. See lvmconfig\n--type profilable-command. To apply a profile to a command, write a profile, save it in\nthe profile directory, and run the command using the option: --commandprofile ProfileName.\n" }, { "name": "Zeroing", "content": "When a thin pool provisions a new data block for a thin LV, the new block is first overwrit‐\nten with zeros. The zeroing mode is indicated by the \"z\" attribute displayed by lvs. The\noption -Z (or --zero) can be added to commands to specify the zeroing mode.\n\nCommand to set the zeroing mode when creating a thin pool LV:\n" }, { "name": "lvconvert --type thin-pool -Z y|n", "content": "--poolmetadata VG/ThinMetaLV VG/ThinDataLV\n\nCommand to change the zeroing mode of an existing thin pool LV:\n" }, { "name": "lvchange -Z y|n VG/ThinPoolLV", "content": "If zeroing mode is changed from \"n\" to \"y\", previously provisioned blocks are not zeroed.\n\nProvisioning of large zeroed chunks impacts performance.\n\nlvm.conf(5) thinpoolzero\ncontrols the default zeroing mode used when creating a thin pool.\n" }, { "name": "Discard", "content": "The discard behavior of a thin pool LV determines how discard requests are handled. Enabling\ndiscard under a file system may adversely affect the file system performance (see the section\non fstrim for an alternative.) Possible discard behaviors:\n\nignore: Ignore any discards that are received.\n\nnopassdown: Process any discards in the thin pool itself and allow the no longer needed ex‐\ntents to be overwritten by new data.\n\npassdown: Process discards in the thin pool (as with nopassdown), and pass the discards down\nthe the underlying device. This is the default mode.\n\nCommand to display the current discard mode of a thin pool LV:" }, { "name": "lvs -o+discards VG/ThinPoolLV", "content": "Command to set the discard mode when creating a thin pool LV:" }, { "name": "lvconvert --discards ignore|nopassdown|passdown", "content": "--type thin-pool --poolmetadata VG/ThinMetaLV VG/ThinDataLV\n\nCommand to change the discard mode of an existing thin pool LV:" }, { "name": "lvchange --discards ignore|nopassdown|passdown VG/ThinPoolLV", "content": "Example\n# lvs -o name,discards vg/pool0\npool0 passdown\n\n# lvchange --discards ignore vg/pool0\n\nlvm.conf(5) thinpooldiscards\ncontrols the default discards mode used when creating a thin pool.\n" }, { "name": "Chunk size", "content": "The size of data blocks managed by a thin pool can be specified with the --chunksize option\nwhen the thin pool LV is created. The default unit is KiB. The value must be a multiple of\n64KiB between 64KiB and 1GiB.\n\nWhen a thin pool is used primarily for the thin provisioning feature, a larger value is opti‐\nmal. To optimize for many snapshots, a smaller value reduces copying time and consumes less\nspace.\n\nCommand to display the thin pool LV chunk size:\n" }, { "name": "lvs -o+chunksize VG/ThinPoolLV", "content": "Example\n# lvs -o name,chunksize\npool0 64.00k\n\nlvm.conf(5) thinpoolchunksize\ncontrols the default chunk size used when creating a thin pool.\n\nThe default value is shown by:" }, { "name": "lvmconfig --type default allocation/thin_pool_chunk_size", "content": "" }, { "name": "Size of pool metadata LV", "content": "The amount of thin metadata depends on how many blocks are shared between thin LVs (i.e.\nthrough snapshots). A thin pool with many snapshots may need a larger metadata LV. Thin\npool metadata LV sizes can be from 2MiB to approximately 16GiB.\n\nWhen using lvcreate to create what will become a thin metadata LV, the size is specified with\nthe -L|--size option.\n\nWhen an LVM command automatically creates a thin metadata LV, the size is specified with the\n--poolmetadatasize option. When this option is not given, LVM automatically chooses a size\nbased on the data size and chunk size.\n\nIt can be hard to predict the amount of metadata space that will be needed, so it is recom‐\nmended to start with a size of 1GiB which should be enough for all practical purposes. A\nthin pool metadata LV can later be manually or automatically extended if needed.\n\nConfigurable setting lvm.conf(5) allocation/thinpoolcropmetadata gives control over crop‐\nping to 15.81GiB to stay backward compatible with older versions of lvm2. With enabled crop‐\nping there can be observed some problems when using volumes above this size with thin tools\n(i.e. thinrepair). Cropping should be enabled only when compatibility is required.\n" }, { "name": "Create a thin snapshot of an external, read only LV", "content": "Thin snapshots are typically taken of other thin LVs or other thin snapshot LVs within the\nsame thin pool. It is also possible to take thin snapshots of external, read only LVs.\nWrites to the snapshot are stored in the thin pool, and the external LV is used to read un‐\nwritten parts of the thin snapshot.\n" }, { "name": "lvcreate -n SnapLV -s VG/ExternalOriginLV --thinpool VG/ThinPoolLV", "content": "Example\n# lvchange -an vg/lve\n# lvchange --permission r vg/lve\n# lvcreate -n snaplve -s vg/lve --thinpool vg/pool0\n\n# lvs vg/lve vg/snaplve\nLV VG Attr LSize Pool Origin Data%\nlve vg ori------- 10.00g\nsnaplve vg Vwi-a-tz-- 10.00g pool0 lve 0.00\n" }, { "name": "Convert a standard LV to a thin LV with an external origin", "content": "A new thin LV can be created and given the name of an existing standard LV. At the same\ntime, the existing LV is converted to a read only external LV with a new name. Unwritten\nportions of the thin LV are read from the external LV. The new name given to the existing LV\ncan be specified with --originname, otherwise the existing LV will be given a default name,\ne.g. lvol#.\n\nConvert ExampleLV into a read only external LV with the new name NewExternalOriginLV, and\ncreate a new thin LV that is given the previous name of ExampleLV.\n" }, { "name": "lvconvert --type thin --thinpool VG/ThinPoolLV", "content": "--originname NewExternalOriginLV VG/ExampleLV\n\nExample\n# lvcreate -n lvexample -L 10G vg\n\n# lvs\nlvexample vg -wi-a----- 10.00g\n\n# lvconvert --type thin --thinpool vg/pool0\n--originname lvexternal --thin vg/lvexample\n\n# lvs\nLV VG Attr LSize Pool Origin\nlvexample vg Vwi-a-tz-- 10.00g pool0 lvexternal\nlvexternal vg ori------- 10.00g\n" }, { "name": "Single step thin pool LV creation", "content": "A thin pool LV can be created with a single lvcreate command, rather than using lvconvert on\nexisting LVs. This one command creates a thin data LV, a thin metadata LV, and combines the\ntwo into a thin pool LV.\n" }, { "name": "lvcreate --type thin-pool -L LargeSize -n ThinPoolLV VG", "content": "Example\n# lvcreate --type thin-pool -L8M -n pool0 vg\n\n# lvs vg/pool0\nLV VG Attr LSize Pool Origin Data%\npool0 vg twi-a-tz-- 8.00m 0.00\n\n# lvs -a\npool0 vg twi-a-tz-- 8.00m\n[pool0tdata] vg Twi-ao---- 8.00m\n[pool0tmeta] vg ewi-ao---- 8.00m\n" }, { "name": "Single step thin pool LV and thin LV creation", "content": "A thin pool LV and a thin LV can be created with a single lvcreate command. This one command\ncreates a thin data LV, a thin metadata LV, combines the two into a thin pool LV, and creates\na thin LV in the new pool.\n-L LargeSize specifies the physical size of the thin pool LV.\n-V VirtualSize specifies the virtual size of the thin LV.\n" }, { "name": "lvcreate --type thin -V VirtualSize -L LargeSize", "content": "-n ThinLV --thinpool VG/ThinPoolLV\n\nEquivalent to:" }, { "name": "lvcreate --type thin-pool -L LargeSize VG/ThinPoolLV", "content": "" }, { "name": "lvcreate -n ThinLV -V VirtualSize --thinpool VG/ThinPoolLV", "content": "Example\n# lvcreate -L8M -V2G -n thin1 --thinpool vg/pool0\n\n# lvs -a\npool0 vg twi-a-tz-- 8.00m\n[pool0tdata] vg Twi-ao---- 8.00m\n[pool0tmeta] vg ewi-ao---- 8.00m\nthin1 vg Vwi-a-tz-- 2.00g pool0\n" }, { "name": "Merge thin snapshots", "content": "A thin snapshot can be merged into its origin thin LV using the lvconvert --merge command.\nThe result of a snapshot merge is that the origin thin LV takes the content of the snapshot\nLV, and the snapshot LV is removed. Any content that was unique to the origin thin LV is\nlost after the merge.\n\nBecause a merge changes the content of an LV, it cannot be done while the LVs are open, e.g.\nmounted. If a merge is initiated while the LVs are open, the effect of the merge is delayed\nuntil the origin thin LV is next activated.\n" }, { "name": "lvconvert --merge VG/SnapLV", "content": "Example\n# lvs vg\nLV VG Attr LSize Pool Origin\npool0 vg twi-a-tz-- 10.00g\nthin1 vg Vwi-a-tz-- 100.00g pool0\nthin1s1 vg Vwi-a-tz-k 100.00g pool0 thin1\n\n# lvconvert --merge vg/thin1s1\n\n# lvs vg\nLV VG Attr LSize Pool Origin\npool0 vg twi-a-tz-- 10.00g\nthin1 vg Vwi-a-tz-- 100.00g pool0\n\nExample\nDelayed merging of open LVs.\n\n# lvs vg\nLV VG Attr LSize Pool Origin\npool0 vg twi-a-tz-- 10.00g\nthin1 vg Vwi-aotz-- 100.00g pool0\nthin1s1 vg Vwi-aotz-k 100.00g pool0 thin1\n\n# df\n/dev/mapper/vg-thin1 100G 33M 100G 1% /mnt/X\n/dev/mapper/vg-thin1s1 100G 33M 100G 1% /mnt/Xs\n\n# ls /mnt/X\nfile1 file2 file3\n# ls /mnt/Xs\nfile3 file4 file5\n\n# lvconvert --merge vg/thin1s1\nLogical volume vg/thin1s1 contains a filesystem in use.\nDelaying merge since snapshot is open.\nMerging of thin snapshot thin1s1 will occur on next activation.\n\n# umount /mnt/X\n# umount /mnt/Xs\n\n# lvs -a vg\nLV VG Attr LSize Pool Origin\npool0 vg twi-a-tz-- 10.00g\n[pool0tdata] vg Twi-ao---- 10.00g\n[pool0tmeta] vg ewi-ao---- 1.00g\nthin1 vg Owi-a-tz-- 100.00g pool0\n[thin1s1] vg Swi-a-tz-k 100.00g pool0 thin1\n\n# lvchange -an vg/thin1\n# lvchange -ay vg/thin1\n\n# mount /dev/vg/thin1 /mnt/X\n\n# ls /mnt/X\nfile3 file4 file5\n" }, { "name": "XFS on snapshots", "content": "Mounting an XFS file system on a new snapshot LV requires attention to the file system's log\nstate and uuid. On the snapshot LV, the xfs log will contain a dummy transaction, and the\nxfs uuid will match the uuid from the file system on the origin LV.\n\nIf the snapshot LV is writable, mounting will recover the log to clear the dummy transaction,\nbut will require skipping the uuid check:\n\n# mount /dev/VG/SnapLV /mnt -o nouuid\n\nAfter the first mount with the above approach, the UUID can subsequently be changed using:\n\n# xfsadmin -U generate /dev/VG/SnapLV\n\n# mount /dev/VG/SnapLV /mnt\n\nOnce the UUID has been changed, the mount command will no longer require the nouuid option.\n\nIf the snapshot LV is readonly, the log recovery and uuid check need to be skipped while\nmounting readonly:\n\n# mount /dev/VG/SnapLV /mnt -o ro,nouuid,norecovery\n" } ] }, "SEE ALSO": { "content": "lvm(8), lvm.conf(5), lvmconfig(8), lvcreate(8), lvconvert(8), lvchange(8), lvextend(8),\nlvremove(8), lvs(8),\n\nthindump(8), thinrepair(8), thinrestore(8)\n\nRed Hat, Inc LVM TOOLS 2.03.16(2) (2022-05-18) LVMTHIN(7)", "subsections": [] } }, "summary": "lvmthin — LVM thin provisioning", "flags": [], "examples": [], "see_also": [ { "name": "lvm", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lvm/8/json" }, { "name": "lvm.conf", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/lvm.conf/5/json" }, { "name": "lvmconfig", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lvmconfig/8/json" }, { "name": "lvcreate", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lvcreate/8/json" }, { "name": "lvconvert", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lvconvert/8/json" }, { "name": "lvchange", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lvchange/8/json" }, { "name": "lvextend", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lvextend/8/json" }, { "name": "lvremove", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lvremove/8/json" }, { "name": "lvs", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lvs/8/json" }, { "name": "thindump", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/thindump/8/json" }, { "name": "thinrepair", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/thinrepair/8/json" }, { "name": "thinrestore", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/thinrestore/8/json" } ] }