.TH "LVMTHIN" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\""

.SH NAME
lvmthin \(em LVM thin provisioning

.SH DESCRIPTION

Blocks in a standard logical volume are allocated when the LV is created,
but blocks in a thin provisioned logical volume are allocated as they are
written.  Because of this, a thin provisioned LV is given a virtual size,
and can then be much larger than physically available storage.  The amount
of physical storage provided for thin provisioned LVs can be increased
later as the need arises.

Blocks in a standard LV are allocated (during creation) from the VG, but
blocks in a thin LV are allocated (during use) from a special "thin pool
LV".  The thin pool LV contains blocks of physical storage, and blocks in
thin LVs just reference blocks in the thin pool LV.

A thin pool LV must be created before thin LVs can be created within it.
A thin pool LV is created by combining two standard LVs: a large data LV
that will hold blocks for thin LVs, and a metadata LV that will hold
metadata.  The metadata tracks which data blocks belong to each thin LV.

Snapshots of thin LVs are efficient because the data blocks common to a
thin LV and any of its snapshots are shared.  Snapshots may be taken of
thin LVs or of other thin snapshots.  Blocks common to recursive snapshots
are also shared in the thin pool.  There is no limit to or degradation
from sequences of snapshots.

As thin LVs or snapshot LVs are written to, they consume data blocks in
the thin pool.  As free data blocks in the pool decrease, more free blocks
may need to be supplied.  This is done by extending the thin pool data LV
with additional physical space from the VG.  Removing thin LVs or
snapshots from the thin pool can also free blocks in the thin pool.
However, removing LVs is not always an effective way of freeing space in a
thin pool because the amount is limited to the number of blocks not shared
with other LVs in the pool.

Incremental block allocation from thin pools can cause thin LVs to become
fragmented.  Standard LVs generally avoid this problem by allocating all
the blocks at once during creation.


.SH Thin Terms

.TP
ThinDataLV
.br
thin data LV
.br
large LV created in a VG
.br
used by thin pool to store ThinLV blocks

.TP
ThinMetaLV
.br
thin metadata LV
.br
small LV created in a VG
.br
used by thin pool to track data block usage

.TP
ThinPoolLV
.br
thin pool LV
.br
combination of ThinDataLV and ThinMetaLV
.br
contains ThinLVs and SnapLVs

.TP
ThinLV
.br
thin LV
.br
created from ThinPoolLV
.br
appears blank after creation

.TP
SnapLV
.br
snapshot LV
.br
created from ThinPoolLV
.br
appears as a snapshot of another LV after creation


.SH Thin Usage

The primary method for using lvm thin provisioning:

.SS 1. create ThinDataLV

Create an LV that will hold thin pool data.

.B lvcreate \-n ThinDataLV \-L LargeSize VG

.I Example
.br
# lvcreate \-n pool0 \-L 10G vg

.SS 2. create ThinMetaLV

Create an LV that will hold thin pool metadata.

.B lvcreate \-n ThinMetaLV \-L SmallSize VG

.I Example
.br
# lvcreate \-n pool0meta \-L 1G vg

# lvs
  LV        VG Attr       LSize
  pool0     vg -wi-a----- 10.00g
  pool0meta vg -wi-a----- 1.00g

.SS 3. create ThinPoolLV

.nf
Combine the data and metadata LVs into a thin pool LV.
ThinDataLV is renamed to hidden ThinPoolLV_tdata.
ThinMetaLV is renamed to hidden ThinPoolLV_tmeta.
The new ThinPoolLV takes the previous name of ThinDataLV.
.fi

.B lvconvert \-\-type thin-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV

.I Example
.br
# lvconvert \-\-type thin-pool \-\-poolmetadata vg/pool0meta vg/pool0

# lvs vg/pool0
  LV    VG Attr       LSize  Pool Origin Data% Meta%
  pool0 vg twi-a-tz-- 10.00g      0.00   0.00

# lvs \-a
  LV            VG Attr       LSize
  pool0         vg twi-a-tz-- 10.00g
  [pool0_tdata] vg Twi-ao---- 10.00g
  [pool0_tmeta] vg ewi-ao---- 1.00g

.SS 4. create ThinLV

.nf
Create a new thin LV from the thin pool LV.
The thin LV is created with a virtual size.
Multiple new thin LVs may be created in the thin pool.
Thin LV names must be unique in the VG.
The '--type thin' option is inferred from the virtual size option.
The --thinpool argument specifies which thin pool will
contain the ThinLV.
.fi

.B lvcreate \-n ThinLV \-V VirtualSize \-\-thinpool VG/ThinPoolLV

.I Example
.br
Create a thin LV in a thin pool:
.br
# lvcreate \-n thin1 \-V 1T \-\-thinpool vg/pool0

Create another thin LV in the same thin pool:
.br
# lvcreate \-n thin2 \-V 1T \-\-thinpool vg/pool0

# lvs vg/thin1 vg/thin2
  LV    VG Attr       LSize Pool  Origin Data%
  thin1 vg Vwi-a-tz-- 1.00t pool0        0.00
  thin2 vg Vwi-a-tz-- 1.00t pool0        0.00

.SS 5. create SnapLV

Create snapshots of an existing ThinLV or SnapLV.
.br
Do not specify
.BR \-L ", " \-\-size
when creating a thin snapshot.
.br
A size argument will cause an old COW snapshot to be created.

.B lvcreate \-n SnapLV \-s VG/ThinLV
.br
.B lvcreate \-n SnapLV \-s VG/PrevSnapLV

.I Example
.br
Create first snapshot of an existing ThinLV:
.br
# lvcreate \-n thin1s1 \-s vg/thin1

Create second snapshot of the same ThinLV:
.br
# lvcreate \-n thin1s2 \-s vg/thin1

Create a snapshot of the first snapshot:
.br
# lvcreate \-n thin1s1s1 \-s vg/thin1s1

# lvs vg/thin1s1 vg/thin1s2 vg/thin1s1s1
  LV        VG Attr       LSize Pool  Origin
  thin1s1   vg Vwi---tz-k 1.00t pool0 thin1
  thin1s2   vg Vwi---tz-k 1.00t pool0 thin1
  thin1s1s1 vg Vwi---tz-k 1.00t pool0 thin1s1

.SS 6. activate SnapLV

Thin snapshots are created with the persistent "activation skip"
flag, indicated by the "k" attribute.  Use \-K with lvchange
or vgchange to activate thin snapshots with the "k" attribute.

.B lvchange \-ay \-K VG/SnapLV

.I Example
.br
# lvchange \-ay \-K vg/thin1s1

# lvs vg/thin1s1
  LV      VG Attr       LSize Pool  Origin
  thin1s1 vg Vwi-a-tz-k 1.00t pool0 thin1

.SH Thin Topics

.B Alternate syntax for specifying type thin\-pool
.br
.B Automatic pool metadata LV
.br
.B Specify devices for data and metadata LVs
.br
.B Tolerate device failures using raid
.br
.B Spare metadata LV
.br
.B Metadata check and repair
.br
.B Activation of thin snapshots
.br
.B Removing thin pool LVs, thin LVs and snapshots
.br
.B Manually manage free data space of thin pool LV
.br
.B Manually manage free metadata space of a thin pool LV
.br
.B Using fstrim to increase free space in a thin pool LV
.br
.B Automatically extend thin pool LV
.br
.B Data space exhaustion
.br
.B Metadata space exhaustion
.br
.B Automatic extend settings
.br
.B Zeroing
.br
.B Discard
.br
.B Chunk size
.br
.B Size of pool metadata LV
.br
.B Create a thin snapshot of an external, read only LV
.br
.B Convert a standard LV to a thin LV with an external origin
.br
.B Single step thin pool LV creation
.br
.B Single step thin pool LV and thin LV creation
.br
.B Merge thin snapshots
.br
.B XFS on snapshots

\&

.SS Alternate syntax for specifying type thin\-pool

\&

The fully specified syntax for creating a thin pool LV shown above is:

.B lvconvert \-\-type thin-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV

An existing LV is converted to a thin pool by changing its type to
thin-pool.  An alternate syntax may be used for the same operation:

.B lvconvert \-\-thinpool VG/ThinDataLV \-\-poolmetadata VG/ThinMetaLV

The thin-pool type is inferred by lvm; the --thinpool option is not an
alias for --type thin-pool.  The use of the --thinpool option here is
different from the use of the --thinpool option when creating a thin LV,
where it specifies the pool in which the thin LV is created.


.SS Automatic pool metadata LV

\&

A thin data LV can be converted to a thin pool LV without specifying a
thin pool metadata LV.  LVM automatically creates a metadata LV from the
same VG.

.B lvcreate \-n ThinDataLV \-L LargeSize VG
.br
.B lvconvert \-\-type thin\-pool VG/ThinDataLV

.I Example
.br
.nf
# lvcreate \-n pool0 \-L 10G vg
# lvconvert \-\-type thin\-pool vg/pool0

# lvs \-a
  pool0           vg          twi-a-tz--  10.00g
  [pool0_tdata]   vg          Twi-ao----  10.00g
  [pool0_tmeta]   vg          ewi-ao----  16.00m
.fi


.SS Specify devices for data and metadata LVs

\&

The data and metadata LVs in a thin pool are best created on
separate physical devices.  To do that, specify the device name(s)
at the end of the lvcreate line.  It can be especially helpful
to use fast devices for the metadata LV.

.B lvcreate \-n ThinDataLV \-L LargeSize VG LargePV
.br
.B lvcreate \-n ThinMetaLV \-L SmallSize VG SmallPV
.br
.B lvconvert \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV

.I Example
.br
.nf
# lvcreate \-n pool0 \-L 10G vg /dev/sdA
# lvcreate \-n pool0meta \-L 1G vg /dev/sdB
# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0
.fi

.BR lvm.conf (5)
.B thin_pool_metadata_require_separate_pvs
.br
controls the default PV usage for thin pool creation.

\&

.SS Tolerate device failures using raid

\&

To tolerate device failures, use raid for the pool data LV and
pool metadata LV.  This is especially recommended for pool metadata LVs.

.B lvcreate \-\-type raid1 \-m 1 \-n ThinMetaLV \-L SmallSize VG PVA PVB
.br
.B lvcreate \-\-type raid1 \-m 1 \-n ThinDataLV \-L LargeSize VG PVC PVD
.br
.B lvconvert \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV

.I Example
.br
.nf
# lvcreate \-\-type raid1 \-m 1 \-n pool0 \-L 10G vg /dev/sdA /dev/sdB
# lvcreate \-\-type raid1 \-m 1 \-n pool0meta \-L 1G vg /dev/sdC /dev/sdD
# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0
.fi


.SS Spare metadata LV

\&

The first time a thin pool LV is created, lvm will create a spare
metadata LV in the VG.  This behavior can be controlled with the
option \-\-poolmetadataspare y|n.  (Future thin pool creations will
also attempt to create the pmspare LV if none exists.)

To create the pmspare ("pool metadata spare") LV, lvm first creates
an LV with a default name, e.g. lvol0, and then converts this LV to
a hidden LV with the _pmspare suffix, e.g. lvol0_pmspare.

One pmspare LV is kept in a VG to be used for any thin pool.

The pmspare LV cannot be created explicitly, but may be removed
explicitly.

.I Example
.br
.nf
# lvcreate \-n pool0 \-L 10G vg
# lvcreate \-n pool0meta \-L 1G vg
# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0

# lvs \-a
  [lvol0_pmspare] vg          ewi-------
  pool0           vg          twi---tz--
  [pool0_tdata]   vg          Twi-------
  [pool0_tmeta]   vg          ewi-------
.fi

The "Metadata check and repair" section describes the use of
the pmspare LV.


.SS Metadata check and repair

\&

If thin pool metadata is damaged, it may be repairable.
Checking and repairing thin pool metadata is analagous to
running fsck on a file system.

When a thin pool LV is activated, lvm runs the thin_check command
to check the correctness of the metadata on the pool metadata LV.

.BR lvm.conf (5)
.B thin_check_executable
.br
can be set to an empty string ("") to disable the thin_check step.
This is not recommended.

.BR lvm.conf (5)
.B thin_check_options
.br
controls the command options used for the thin_check command.

If the thin_check command finds a problem with the metadata,
the thin pool LV is not activated, and the thin pool metadata needs
to be repaired.

Simple repair commands are not always successful.  Advanced repair may
require editing thin pool metadata and lvm metadata.  Newer versions of
the kernel and lvm tools may be more successful at repair.  Report the
details of damaged thin metadata to get the best advice on recovery.

Command to repair a thin pool:
.br
.B lvconvert \-\-repair VG/ThinPoolLV

Repair performs the following steps:

1. Creates a new, repaired copy of the metadata.
.br
lvconvert runs the thin_repair command to read damaged metadata
from the existing pool metadata LV, and writes a new repaired
copy to the VG's pmspare LV.

2. Replaces the thin pool metadata LV.
.br
If step 1 is successful, the thin pool metadata LV is replaced
with the pmspare LV containing the corrected metadata.
The previous thin pool metadata LV, containing the damaged metadata,
becomes visible with the new name ThinPoolLV_tmetaN (where N is 0,1,...).

If the repair works, the thin pool LV and its thin LVs can be activated,
and the LV containing the damaged thin pool metadata can be removed.
It may be useful to move the new metadata LV (previously pmspare) to a
better PV.

If the repair does not work, the thin pool LV and its thin LVs are lost.

If metadata is manually restored with thin_repair directly,
the pool metadata LV can be manually swapped with another LV
containing new metadata:

.B lvconvert \-\-thinpool VG/ThinPoolLV \-\-poolmetadata VG/NewThinMetaLV


.SS Activation of thin snapshots

\&

When a thin snapshot LV is created, it is by default given the
"activation skip" flag.  This flag is indicated by the "k" attribute
displayed by lvs:

.nf
# lvs vg/thin1s1
  LV         VG  Attr       LSize Pool  Origin
  thin1s1    vg  Vwi---tz-k 1.00t pool0 thin1
.fi

This flag causes the snapshot LV to be skipped, i.e. not activated,
by normal activation commands.  The skipping behavior does not
apply to deactivation commands.

A snapshot LV with the "k" attribute can be activated using
the \-K (or \-\-ignoreactivationskip) option in addition to the
standard \-ay (or \-\-activate y) option.

Command to activate a thin snapshot LV:
.br
.B lvchange \-ay \-K VG/SnapLV

The persistent "activation skip" flag can be turned off during
lvcreate, or later with lvchange using the \-kn
(or \-\-setactivationskip n) option.
It can be turned on again with \-ky (or \-\-setactivationskip y).

When the "activation skip" flag is removed, normal activation
commands will activate the LV, and the \-K activation option is
not needed.

Command to create snapshot LV without the activation skip flag:
.br
.B lvcreate \-kn \-n SnapLV \-s VG/ThinLV

Command to remove the activation skip flag from a snapshot LV:
.br
.B lvchange \-kn VG/SnapLV

.BR lvm.conf (5)
.B auto_set_activation_skip
.br
controls the default activation skip setting used by lvcreate.


.SS Removing thin pool LVs, thin LVs and snapshots

\&

Removing a thin LV and its related snapshots returns the blocks it
used to the thin pool LV.  These blocks will be reused for other
thin LVs and snapshots.

Removing a thin pool LV removes both the data LV and metadata LV
and returns the space to the VG.

lvremove of thin pool LVs, thin LVs and snapshots cannot be
reversed with vgcfgrestore.

vgcfgbackup does not back up thin pool metadata.


.SS Manually manage free data space of thin pool LV

\&

The available free space in a thin pool LV can be displayed
with the lvs command.  Free space can be added by extending
the thin pool LV.

Command to extend thin pool data space:
.br
.B lvextend \-L Size VG/ThinPoolLV

.I Example
.br
.nf
1. A thin pool LV is using 26.96% of its data blocks.
# lvs
  LV    VG           Attr       LSize   Pool  Origin Data%
  pool0 vg           twi-a-tz--  10.00g               26.96

2. Double the amount of physical space in the thin pool LV.
# lvextend \-L+10G vg/pool0

3. The percentage of used data blocks is half the previous value.
# lvs
  LV    VG           Attr       LSize   Pool  Origin Data%
  pool0 vg           twi-a-tz--  20.00g               13.48
.fi

Other methods of increasing free data space in a thin pool LV
include removing a thin LV and its related snapsots, or running
fstrim on the file system using a thin LV.


.SS Manually manage free metadata space of a thin pool LV

\&

The available metadata space in a thin pool LV can be displayed
with the lvs \-o+metadata_percent command.

Command to extend thin pool metadata space:
.br
.B lvextend \-\-poolmetadatasize Size VG/ThinPoolLV

.I Example
.br
1. A thin pool LV is using 12.40% of its metadata blocks.
.nf
# lvs \-oname,size,data_percent,metadata_percent vg/pool0
  LV    LSize   Data%  Meta%
  pool0  20.00g  13.48  12.40
.fi

2. Display a thin pool LV with its component thin data LV and thin metadata LV.
.nf
# lvs \-a \-oname,attr,size vg
  LV              Attr       LSize
  pool0           twi-a-tz--  20.00g
  [pool0_tdata]   Twi-ao----  20.00g
  [pool0_tmeta]   ewi-ao----  12.00m
.fi

3. Double the amount of physical space in the thin metadata LV.
.nf
# lvextend \-\-poolmetadatasize +12M vg/pool0
.fi

4. The percentage of used metadata blocks is half the previous value.
.nf
# lvs \-a \-oname,size,data_percent,metadata_percent vg
  LV              LSize   Data%  Meta%
  pool0            20.00g  13.48   6.20
  [pool0_tdata]    20.00g
  [pool0_tmeta]    24.00m
.fi


.SS Using fstrim to increase free space in a thin pool LV

\&

Removing files in a file system on top of a thin LV does not
generally add free space back to the thin pool.  Manually running
the fstrim command can return space back to the thin pool that had
been used by removed files.  fstrim uses discards and will not work
if the thin pool LV has discards mode set to ignore.

.I Example
.br
A thin pool has 10G of physical data space, and a thin LV has a virtual
size of 100G.  Writing a 1G file to the file system reduces the
free space in the thin pool by 10% and increases the virtual usage
of the file system by 1%.  Removing the 1G file restores the virtual
1% to the file system, but does not restore the physical 10% to the
thin pool.  The fstrim command restores the physical space to the thin pool.

.nf
# lvs \-a \-oname,attr,size,pool_lv,origin,data_percent,metadata_percent vg
LV              Attr       LSize   Pool  Origin Data%  Meta%
pool0           twi-a-tz--  10.00g               47.01  21.03
thin1           Vwi-aotz-- 100.00g pool0          2.70

# df \-h /mnt/X
Filesystem            Size  Used Avail Use% Mounted on
/dev/mapper/vg-thin1   99G  1.1G   93G   2% /mnt/X

# dd if=/dev/zero of=/mnt/X/1Gfile bs=4096 count=262144; sync

# lvs
pool0           vg   twi-a-tz--  10.00g               57.01  25.26
thin1           vg   Vwi-aotz-- 100.00g pool0          3.70

# df \-h /mnt/X
/dev/mapper/vg-thin1   99G  2.1G   92G   3% /mnt/X

# rm /mnt/X/1Gfile

# lvs
pool0           vg   twi-a-tz--  10.00g               57.01  25.26
thin1           vg   Vwi-aotz-- 100.00g pool0          3.70

# df \-h /mnt/X
/dev/mapper/vg-thin1   99G  1.1G   93G   2% /mnt/X

# fstrim \-v /mnt/X

# lvs
pool0           vg   twi-a-tz--  10.00g               47.01  21.03
thin1           vg   Vwi-aotz-- 100.00g pool0          2.70
.fi

The "Discard" section covers an option for automatically freeing data
space in a thin pool.


.SS Automatically extend thin pool LV

\&

The lvm daemon dmeventd (lvm2-monitor) monitors the data usage of thin
pool LVs and extends them when the usage reaches a certain level.  The
necessary free space must exist in the VG to extend thin pool LVs.
Monitoring and extension of thin pool LVs are controlled independently.

.I monitoring

When a thin pool LV is activated, dmeventd will begin monitoring it by
default.

Command to start or stop dmeventd monitoring a thin pool LV:
.br
.B lvchange \-\-monitor {y|n} VG/ThinPoolLV

The current dmeventd monitoring status of a thin pool LV can be displayed
with the command lvs -o+seg_monitor.

.I autoextend

dmeventd should be configured to extend thin pool LVs before all data
space is used.  Warnings are emitted through syslog when the use of a thin
pool reaches 80%, 85%, 90% and 95%.  (See the section "Data space
exhaustion" for the effects of not extending a thin pool LV.)  The point
at which dmeventd extends thin pool LVs, and the amount are controlled
with two configuration settings:

.BR lvm.conf (5)
.B thin_pool_autoextend_threshold
.br
is a percentage full value that defines when the thin pool LV should be
extended.  Setting this to 100 disables automatic extention.  The minimum
value is 50.

.BR lvm.conf (5)
.B thin_pool_autoextend_percent
.br
defines how much extra data space should be added to the thin pool LV from
the VG, in percent of its current size.

.I disabling

There are multiple ways that extension of thin pools could be prevented:

.IP \[bu] 2
If the dmeventd daemon is not running, no monitoring or automatic
extension will occur.

.IP \[bu]
Even when dmeventd is running, all monitoring can be disabled with the
lvm.conf monitoring setting.

.IP \[bu]
To activate or create a thin pool LV without interacting with dmeventd,
the --ignoremonitoring option can be used.  With this option, the command
will not ask dmeventd to monitor the thin pool LV.

.IP \[bu]
Setting thin_pool_autoextend_threshould to 100 disables automatic
extension of thin pool LVs, even if they are being monitored by dmeventd.

.P

.I Example
.br
If thin_pool_autoextend_threshold is 70 and thin_pool_autoextend_percent is 20,
whenever a pool exceeds 70% usage, it will be extended by another 20%.
For a 1G pool, using 700M will trigger a resize to 1.2G. When the usage exceeds
840M, the pool will be extended to 1.44G, and so on.


.SS Data space exhaustion

\&

When properly managed, thin pool data space should be extended before it
is all used (see the section "Automatically extend thin pool LV").  If
thin pool data space is already exhausted, it can still be extended (see
the section "Manually manage free data space of thin pool LV".)

The behavior of a full thin pool is configurable with the --errorwhenfull
y|n option to lvcreate or lvchange.  The errorwhenfull setting applies
only to writes; reading thin LVs can continue even when data space is
exhausted.

Command to change the handling of a full thin pool:
.br
.B lvchange --errorwhenfull {y|n} VG/ThinPoolLV

.BR lvm.conf (5)
.B error_when_full
.br
controls the default error when full behavior.

The current setting of a thin pool LV can be displayed with the command:
lvs -o+lv_when_full.

The errorwhenfull setting does not effect the monitoring and autoextend
settings, and the monitoring/autoextend settings do not effect the
errorwhenfull setting.  It is only when monitoring/autoextend are not
effective that the thin pool becomes full and the errorwhenfull setting is
applied.

.I errorwhenfull n

This is the default.  Writes to thin LVs are accepted and queued, with the
expectation that pool data space will be extended soon.  Once data space
is extended, the queued writes will be processed, and the thin pool will
return to normal operation.

While waiting to be extended, the thin pool will queue writes for up to 60
seconds (the default).  If data space has not been extended after this
time, the queued writes will return an error to the caller, e.g. the file
system.  This can result in file system corruption for non-journaled file
systems that may require fsck.  When a thin pool returns errors for writes
to a thin LV, any file system is subject to losing unsynced user data.

The 60 second timeout can be changed or disabled with the dm\-thin\-pool
kernel module option
.B no_space_timeout.
This option sets the number of seconds that thin pools will queue writes.
If set to 0, writes will not time out.  Disabling timeouts can result in
the system running out of resources, memory exhaustion, hung tasks, and
deadlocks.  (The timeout applies to all thin pools on the system.)

.I errorwhenfull y

Writes to thin LVs immediately return an error, and no writes are queued.
In the case of a file system, this can result in corruption that may
require fsck (the specific consequences depend on the thin LV user.)

.I data percent

When data space is exhausted, the lvs command displays 100 under Data% for
the thin pool LV:

.nf
# lvs vg/pool0
  LV     VG           Attr       LSize   Pool  Origin Data%
  pool0  vg           twi-a-tz-- 512.00m              100.00
.fi

.I causes

A thin pool may run out of data space for any of the following reasons:

.IP \[bu] 2
Automatic extension of the thin pool is disabled, and the thin pool is not
manually extended.  (Disabling automatic extension is not recommended.)

.IP \[bu]
The dmeventd daemon is not running and the thin pool is not manually
extended.  (Disabling dmeventd is not recommended.)

.IP \[bu]
Automatic extension of the thin pool is too slow given the rate of writes
to thin LVs in the pool.  (This can be addressed by tuning the
thin_pool_autoextend_threshold and thin_pool_autoextend_percent.
See "Automatic extend settings".)

.IP \[bu]
The VG does not have enough free blocks to extend the thin pool.

.P

.SS Metadata space exhaustion

\&

If thin pool metadata space is exhausted (or a thin pool metadata
operation fails), errors will be returned for IO operations on thin LVs.

When metadata space is exhausted, the lvs command displays 100 under Meta%
for the thin pool LV:

.nf
# lvs \-o lv_name,size,data_percent,metadata_percent vg/pool0
  LV    LSize Data%  Meta%
  pool0              100.00
.fi

The same reasons for thin pool data space exhaustion apply to thin pool
metadata space.

Metadata space exhaustion can lead to inconsistent thin pool metadata and
inconsistent file systems, so the response requires offline checking and
repair.

1. Deactivate the thin pool LV, or reboot the system if this is not possible.

2. Repair thin pool with lvconvert \-\-repair.
.br
   See "Metadata check and repair".

3. Extend pool metadata space with lvextend \-\-poolmetadatasize.
.br
   See "Manually manage free metadata space of a thin pool LV".

4. Check and repair file system with fsck.


.SS Automatic extend settings

\&

Thin pool LVs can be extended according to preset values.  The presets
determine if the LV should be extended based on how full it is, and if so
by how much.  When dmeventd monitors thin pool LVs, it uses lvextend with
these presets.  (See "Automatically extend thin pool LV".)

Command to extend a thin pool data LV using presets:
.br
.B lvextend \-\-use\-policies VG/ThinPoolLV

The command uses these settings:

.BR lvm.conf (5)
.B thin_pool_autoextend_threshold
.br
autoextend the LV when its usage exceeds this percent.

.BR lvm.conf (5)
.B thin_pool_autoextend_percent
.br
autoextend the LV by this much additional space.

To see the default values of these settings, run:

.B lvmconfig \-\-type default \-\-withcomment
.RS
.B activation/thin_pool_autoextend_threshold
.RE

.B lvmconfig \-\-type default \-\-withcomment
.RS
.B activation/thin_pool_autoextend_percent
.RE

To change these values globally, edit
.BR lvm.conf (5).

To change these values on a per-VG or per-LV basis, attach a "profile" to
the VG or LV.  A profile is a collection of config settings, saved in a
local text file (using the lvm.conf format).  lvm looks for profiles in
the profile_dir directory, e.g. /etc/lvm/profile/.  Once attached to a VG
or LV, lvm will process the VG or LV using the settings from the attached
profile.  A profile is named and referenced by its file name.

To use a profile to customize the lvextend settings for an LV:

.IP \[bu] 2
Create a file containing settings, saved in profile_dir.
For the profile_dir location, run:
.br
.B lvmconfig config/profile_dir

.IP \[bu] 2
Attach the profile to an LV, using the command:
.br
.B lvchange \-\-metadataprofile ProfileName VG/ThinPoolLV

.IP \[bu] 2
Extend the LV using the profile settings:
.br
.B lvextend \-\-use\-policies VG/ThinPoolLV

.P

.I Example
.br
.nf
# lvmconfig config/profile_dir
profile_dir="/etc/lvm/profile"

# cat /etc/lvm/profile/pool0extend.profile
activation {
        thin_pool_autoextend_threshold=50
        thin_pool_autoextend_percent=10
}

# lvchange --metadataprofile pool0extend vg/pool0

# lvextend --use-policies vg/pool0
.fi

.I Notes
.IP \[bu] 2
A profile is attached to a VG or LV by name, where the name references a
local file in profile_dir.  If the VG is moved to another machine, the
file with the profile also needs to be moved.

.IP \[bu] 2
Only certain settings can be used in a VG or LV profile, see:
.br
.B lvmconfig \-\-type profilable-metadata.

.IP \[bu] 2
An LV without a profile of its own will inherit the VG profile.

.IP \[bu] 2
Remove a profile from an LV using the command:
.br
.B lvchange --detachprofile VG/ThinPoolLV.

.IP \[bu] 2
Commands can also have profiles applied to them.  The settings that can be
applied to a command are different than the settings that can be applied
to a VG or LV.  See lvmconfig \-\-type profilable\-command.  To apply a
profile to a command, write a profile, save it in the profile directory,
and run the command using the option: \-\-commandprofile ProfileName.


.SS Zeroing

\&

When a thin pool provisions a new data block for a thin LV, the
new block is first overwritten with zeros.  The zeroing mode is
indicated by the "z" attribute displayed by lvs.  The option \-Z
(or \-\-zero) can be added to commands to specify the zeroing mode.

Command to set the zeroing mode when creating a thin pool LV:
.br
.B lvconvert \-\-type thin\-pool \-Z{y|n}
.br
.RS
.B \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV
.RE

Command to change the zeroing mode of an existing thin pool LV:
.br
.B lvchange \-Z{y|n} VG/ThinPoolLV

If zeroing mode is changed from "n" to "y", previously provisioned
blocks are not zeroed.

Provisioning of large zeroed chunks impacts performance.

.BR lvm.conf (5)
.B thin_pool_zero
.br
controls the default zeroing mode used when creating a thin pool.


.SS Discard

\&

The discard behavior of a thin pool LV determines how discard requests are
handled.  Enabling discard under a file system may adversely affect the
file system performance (see the section on fstrim for an alternative.)
Possible discard behaviors:

ignore: Ignore any discards that are received.

nopassdown: Process any discards in the thin pool itself and allow
the no longer needed extends to be overwritten by new data.

passdown: Process discards in the thin pool (as with nopassdown), and
pass the discards down the the underlying device.  This is the default
mode.

Command to display the current discard mode of a thin pool LV:
.br
.B lvs \-o+discards VG/ThinPoolLV

Command to set the discard mode when creating a thin pool LV:
.br
.B lvconvert \-\-discards {ignore|nopassdown|passdown}
.br
.RS
.B \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV
.RE

Command to change the discard mode of an existing thin pool LV:
.br
.B lvchange \-\-discards {ignore|nopassdown|passdown} VG/ThinPoolLV

.I Example
.br
.nf
# lvs \-o name,discards vg/pool0
pool0 passdown

# lvchange \-\-discards ignore vg/pool0
.fi

.BR lvm.conf (5)
.B thin_pool_discards
.br
controls the default discards mode used when creating a thin pool.


.SS Chunk size

\&

The size of data blocks managed by a thin pool can be specified with the
\-\-chunksize option when the thin pool LV is created.  The default unit
is KiB. The value must be a multiple of 64KiB between 64KiB and 1GiB.

When a thin pool is used primarily for the thin provisioning feature, a
larger value is optimal.  To optimize for many snapshots, a smaller value
reduces copying time and consumes less space.

Command to display the thin pool LV chunk size:
.br
.B lvs \-o+chunksize VG/ThinPoolLV

.I Example
.br
.nf
# lvs \-o name,chunksize
  pool0 64.00k
.fi

.BR lvm.conf (5)
.B thin_pool_chunk_size
.br
controls the default chunk size used when creating a thin pool.

The default value is shown by:
.br
.B lvmconfig \-\-type default allocation/thin_pool_chunk_size


.SS Size of pool metadata LV

\&

The amount of thin metadata depends on how many blocks are shared between
thin LVs (i.e. through snapshots).  A thin pool with many snapshots may
need a larger metadata LV.  Thin pool metadata LV sizes can be from 2MiB
to 16GiB.

When using lvcreate to create what will become a thin metadata LV, the
size is specified with the \-L|\-\-size option.

When an LVM command automatically creates a thin metadata LV, the size is
specified with the \-\-poolmetadatasize option.  When this option is not
given, LVM automatically chooses a size based on the data size and chunk
size.

It can be hard to predict the amount of metadata space that will be
needed, so it is recommended to start with a size of 1GiB which should be
enough for all practical purposes.  A thin pool metadata LV can later be
manually or automatically extended if needed.


.SS Create a thin snapshot of an external, read only LV

\&

Thin snapshots are typically taken of other thin LVs or other
thin snapshot LVs within the same thin pool.  It is also possible
to take thin snapshots of external, read only LVs.  Writes to the
snapshot are stored in the thin pool, and the external LV is used
to read unwritten parts of the thin snapshot.

.B lvcreate \-n SnapLV \-s VG/ExternalOriginLV \-\-thinpool VG/ThinPoolLV

.I Example
.br
.nf
# lvchange \-an vg/lve
# lvchange \-\-permission r vg/lve
# lvcreate \-n snaplve \-s vg/lve \-\-thinpool vg/pool0

# lvs vg/lve vg/snaplve
  LV      VG  Attr       LSize  Pool  Origin Data%
  lve     vg  ori------- 10.00g
  snaplve vg  Vwi-a-tz-- 10.00g pool0 lve      0.00
.fi


.SS Convert a standard LV to a thin LV with an external origin

\&

A new thin LV can be created and given the name of an existing
standard LV.  At the same time, the existing LV is converted to a
read only external LV with a new name.  Unwritten portions of the
thin LV are read from the external LV.
The new name given to the existing LV can be specified with
\-\-originname, otherwise the existing LV will be given a default
name, e.g. lvol#.

Convert ExampleLV into a read only external LV with the new name
NewExternalOriginLV, and create a new thin LV that is given the previous
name of ExampleLV.

.B lvconvert \-\-type thin \-\-thinpool VG/ThinPoolLV
.br
.RS
.B \-\-originname NewExternalOriginLV VG/ExampleLV
.RE

.I Example
.br
.nf
# lvcreate \-n lv_example \-L 10G vg

# lvs
  lv_example      vg          -wi-a-----  10.00g

# lvconvert \-\-type thin \-\-thinpool vg/pool0
          \-\-originname lv_external \-\-thin vg/lv_example

# lvs
  LV              VG          Attr       LSize   Pool  Origin
  lv_example      vg          Vwi-a-tz--  10.00g pool0 lv_external
  lv_external     vg          ori-------  10.00g
.fi


.SS Single step thin pool LV creation

\&

A thin pool LV can be created with a single lvcreate command,
rather than using lvconvert on existing LVs.
This one command creates a thin data LV, a thin metadata LV,
and combines the two into a thin pool LV.

.B lvcreate \-\-type thin\-pool \-L LargeSize \-n ThinPoolLV VG

.I Example
.br
.nf
# lvcreate \-\-type thin\-pool \-L8M -n pool0 vg

# lvs vg/pool0
  LV    VG  Attr       LSize Pool Origin Data%
  pool0 vg  twi-a-tz-- 8.00m               0.00

# lvs \-a
  pool0           vg          twi-a-tz--   8.00m
  [pool0_tdata]   vg          Twi-ao----   8.00m
  [pool0_tmeta]   vg          ewi-ao----   8.00m
.fi


.SS Single step thin pool LV and thin LV creation

\&

A thin pool LV and a thin LV can be created with a single
lvcreate command.  This one command creates a thin data LV,
a thin metadata LV, combines the two into a thin pool LV,
and creates a thin LV in the new pool.
.br
\-L LargeSize specifies the physical size of the thin pool LV.
.br
\-V VirtualSize specifies the virtual size of the thin LV.

.B lvcreate \-V VirtualSize \-L LargeSize
.RS
.B \-n ThinLV \-\-thinpool VG/ThinPoolLV
.RE

Equivalent to:
.br
.B lvcreate \-\-type thin\-pool \-L LargeSize VG/ThinPoolLV
.br
.B lvcreate \-n ThinLV \-V VirtualSize \-\-thinpool VG/ThinPoolLV

.I Example
.br
.nf
# lvcreate \-L8M \-V2G \-n thin1 \-\-thinpool vg/pool0

# lvs \-a
  pool0           vg          twi-a-tz--   8.00m
  [pool0_tdata]   vg          Twi-ao----   8.00m
  [pool0_tmeta]   vg          ewi-ao----   8.00m
  thin1           vg          Vwi-a-tz--   2.00g pool0
.fi


.SS Merge thin snapshots

\&

A thin snapshot can be merged into its origin thin LV using the lvconvert
\-\-merge command.  The result of a snapshot merge is that the origin thin
LV takes the content of the snapshot LV, and the snapshot LV is removed.
Any content that was unique to the origin thin LV is lost after the merge.

Because a merge changes the content of an LV, it cannot be done while the
LVs are open, e.g. mounted.  If a merge is initiated while the LVs are open,
the effect of the merge is delayed until the origin thin LV is next
activated.

.B lvconvert \-\-merge VG/SnapLV

.I Example
.br
.nf
# lvs vg
  LV      VG Attr       LSize   Pool  Origin
  pool0   vg twi-a-tz--  10.00g
  thin1   vg Vwi-a-tz-- 100.00g pool0
  thin1s1 vg Vwi-a-tz-k 100.00g pool0 thin1

# lvconvert \-\-merge vg/thin1s1

# lvs vg
  LV      VG Attr       LSize   Pool  Origin
  pool0   vg twi-a-tz--  10.00g
  thin1   vg Vwi-a-tz-- 100.00g pool0
.fi

.I Example
.br
.nf
Delayed merging of open LVs.

# lvs vg
  LV      VG Attr       LSize   Pool  Origin
  pool0   vg twi-a-tz--  10.00g
  thin1   vg Vwi-aotz-- 100.00g pool0
  thin1s1 vg Vwi-aotz-k 100.00g pool0 thin1

# df
/dev/mapper/vg-thin1            100G   33M  100G   1% /mnt/X
/dev/mapper/vg-thin1s1          100G   33M  100G   1% /mnt/Xs

# ls /mnt/X
file1 file2 file3
# ls /mnt/Xs
file3 file4 file5

# lvconvert \-\-merge vg/thin1s1
Logical volume vg/thin1s1 contains a filesystem in use.
Delaying merge since snapshot is open.
Merging of thin snapshot thin1s1 will occur on next activation.

# umount /mnt/X
# umount /mnt/Xs

# lvs \-a vg
  LV              VG   Attr       LSize   Pool  Origin
  pool0           vg   twi-a-tz--  10.00g
  [pool0_tdata]   vg   Twi-ao----  10.00g
  [pool0_tmeta]   vg   ewi-ao----   1.00g
  thin1           vg   Owi-a-tz-- 100.00g pool0
  [thin1s1]       vg   Swi-a-tz-k 100.00g pool0 thin1

# lvchange \-an vg/thin1
# lvchange \-ay vg/thin1

# mount /dev/vg/thin1 /mnt/X

# ls /mnt/X
file3 file4 file5
.fi


.SS XFS on snapshots

\&

Mounting an XFS file system on a new snapshot LV requires attention to the
file system's log state and uuid.  On the snapshot LV, the xfs log will
contain a dummy transaction, and the xfs uuid will match the uuid from the
file system on the origin LV.

If the snapshot LV is writable, mounting will recover the log to clear the
dummy transaction, but will require skipping the uuid check:

mount /dev/VG/SnapLV /mnt \-o nouuid

Or, the uuid can be changed on disk before mounting:

xfs_admin \-U generate /dev/VG/SnapLV
.br
mount /dev/VG/SnapLV /mnt

If the snapshot LV is readonly, the log recovery and uuid check need to be
skipped while mounting readonly:

mount /dev/VG/SnapLV /mnt \-o ro,nouuid,norecovery

.SH SEE ALSO
.BR lvm (8),
.BR lvm.conf (5),
.BR lvmconfig (8),
.BR lvcreate (8),
.BR lvconvert (8),
.BR lvchange (8),
.BR lvextend (8),
.BR lvremove (8),
.BR lvs (8),
.BR thin_dump (8),
.BR thin_repair (8)
.BR thin_restore (8)