sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget?/translations/zh_CN/admin-guide/device-mapper/thin-provisioningmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/zh_TW/admin-guide/device-mapper/thin-provisioningmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/it_IT/admin-guide/device-mapper/thin-provisioningmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/ja_JP/admin-guide/device-mapper/thin-provisioningmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/ko_KR/admin-guide/device-mapper/thin-provisioningmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/pt_BR/admin-guide/device-mapper/thin-provisioningmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/sp_SP/admin-guide/device-mapper/thin-provisioningmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hThin provisioningh]hThin provisioning}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhY/var/lib/git/docbuild/linux/Documentation/admin-guide/device-mapper/thin-provisioning.rsthKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hzThis document describes a collection of device-mapper targets that between them implement thin-provisioning and snapshots.h]hzThis document describes a collection of device-mapper targets that between them implement thin-provisioning and snapshots.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXThe main highlight of this implementation, compared to the previous implementation of snapshots, is that it allows many virtual devices to be stored on the same data volume. This simplifies administration and allows the sharing of data between volumes, thus reducing disk usage.h]hXThe main highlight of this implementation, compared to the previous implementation of snapshots, is that it allows many virtual devices to be stored on the same data volume. This simplifies administration and allows the sharing of data between volumes, thus reducing disk usage.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hXAnother significant feature is support for an arbitrary depth of recursive snapshots (snapshots of snapshots of snapshots ...). The previous implementation of snapshots did this by chaining together lookup tables, and so performance was O(depth). This new implementation uses a single data structure to avoid this degradation with depth. Fragmentation may still be an issue, however, in some scenarios.h]hXAnother significant feature is support for an arbitrary depth of recursive snapshots (snapshots of snapshots of snapshots ...). The previous implementation of snapshots did this by chaining together lookup tables, and so performance was O(depth). This new implementation uses a single data structure to avoid this degradation with depth. Fragmentation may still be an issue, however, in some scenarios.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hiMetadata is stored on a separate device from data, giving the administrator some freedom, for example to:h]hiMetadata is stored on a separate device from data, giving the administrator some freedom, for example to:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh bullet_list)}(hhh](h list_item)}(heImprove metadata resilience by storing metadata on a mirrored volume but data on a non-mirrored one. h]h)}(hdImprove metadata resilience by storing metadata on a mirrored volume but data on a non-mirrored one.h]hdImprove metadata resilience by storing metadata on a mirrored volume but data on a non-mirrored one.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h4Improve performance by storing the metadata on SSD. h]h)}(h3Improve performance by storing the metadata on SSD.h]h3Improve performance by storing the metadata on SSD.}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj5ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKhhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hStatush]hStatus}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj]hhhhhK!ubh)}(hThese targets are considered safe for production use. But different use cases will have different performance characteristics, for example due to fragmentation of the data volume.h]hThese targets are considered safe for production use. But different use cases will have different performance characteristics, for example due to fragmentation of the data volume.}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hj]hhubh)}(hIf you find this software is not performing as expected please mail dm-devel@redhat.com with details and we'll try our best to improve things for you.h](hDIf you find this software is not performing as expected please mail }(hj|hhhNhNubh reference)}(hdm-devel@redhat.comh]hdm-devel@redhat.com}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurimailto:dm-devel@redhat.comuh1jhj|ubhA with details and we’ll try our best to improve things for you.}(hj|hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK'hj]hhubh)}(hXUserspace tools for checking and repairing the metadata have been fully developed and are available as 'thin_check' and 'thin_repair'. The name of the package that provides these utilities varies by distribution (on a Red Hat distribution it is named 'device-mapper-persistent-data').h]hX)Userspace tools for checking and repairing the metadata have been fully developed and are available as ‘thin_check’ and ‘thin_repair’. The name of the package that provides these utilities varies by distribution (on a Red Hat distribution it is named ‘device-mapper-persistent-data’).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK+hj]hhubeh}(h]statusah ]h"]statusah$]h&]uh1hhhhhhhhK!ubh)}(hhh](h)}(hCookbookh]hCookbook}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK1ubh)}(hThis section describes some quick recipes for using thin provisioning. They use the dmsetup program to control the device-mapper driver directly. End users will be advised to use a higher-level volume manager such as LVM2 once support has been added.h]hThis section describes some quick recipes for using thin provisioning. They use the dmsetup program to control the device-mapper driver directly. End users will be advised to use a higher-level volume manager such as LVM2 once support has been added.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK3hjhhubh)}(hhh](h)}(h Pool deviceh]h Pool device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK9ubh)}(hThe pool device ties together the metadata volume and the data volume. It maps I/O linearly to the data volume and updates the metadata via two mechanisms:h]hThe pool device ties together the metadata volume and the data volume. It maps I/O linearly to the data volume and updates the metadata via two mechanisms:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK;hjhhubj)}(hhh](j)}(h%Function calls from the thin targets h]h)}(h$Function calls from the thin targetsh]h$Function calls from the thin targets}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK?hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hpDevice-mapper 'messages' from userspace which control the creation of new virtual devices amongst other things. h]h)}(hoDevice-mapper 'messages' from userspace which control the creation of new virtual devices amongst other things.h]hsDevice-mapper ‘messages’ from userspace which control the creation of new virtual devices amongst other things.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKAhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jSjTuh1jhhhK?hjhhubeh}(h] pool-deviceah ]h"] pool deviceah$]h&]uh1hhjhhhhhK9ubh)}(hhh](h)}(hSetting up a fresh pool deviceh]hSetting up a fresh pool device}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj5hhhhhKEubh)}(hSetting up a pool device requires a valid metadata device, and a data device. If you do not have an existing metadata device you can make one by zeroing the first 4k to indicate empty metadata.h]hSetting up a pool device requires a valid metadata device, and a data device. If you do not have an existing metadata device you can make one by zeroing the first 4k to indicate empty metadata.}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKGhj5hhubh block_quote)}(h1dd if=/dev/zero of=$metadata_dev bs=4096 count=1 h]h)}(h0dd if=/dev/zero of=$metadata_dev bs=4096 count=1h]h0dd if=/dev/zero of=$metadata_dev bs=4096 count=1}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKKhjVubah}(h]h ]h"]h$]h&]uh1jThhhKKhj5hhubh)}(hThe amount of metadata you need will vary according to how many blocks are shared between thin devices (i.e. through snapshots). If you have less sharing than average you'll need a larger-than-average metadata device.h]hThe amount of metadata you need will vary according to how many blocks are shared between thin devices (i.e. through snapshots). If you have less sharing than average you’ll need a larger-than-average metadata device.}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKMhj5hhubh)}(hX6As a guide, we suggest you calculate the number of bytes to use in the metadata device as 48 * $data_dev_size / $data_block_size but round it up to 2MiB if the answer is smaller. If you're creating large numbers of snapshots which are recording large amounts of change, you may find you need to increase this.h]hX8As a guide, we suggest you calculate the number of bytes to use in the metadata device as 48 * $data_dev_size / $data_block_size but round it up to 2MiB if the answer is smaller. If you’re creating large numbers of snapshots which are recording large amounts of change, you may find you need to increase this.}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKQhj5hhubh)}(h}The largest size supported is 16GiB: If the device is larger, a warning will be issued and the excess space will not be used.h]h}The largest size supported is 16GiB: If the device is larger, a warning will be issued and the excess space will not be used.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKWhj5hhubeh}(h]setting-up-a-fresh-pool-deviceah ]h"]setting up a fresh pool deviceah$]h&]uh1hhjhhhhhKEubh)}(hhh](h)}(hReloading a pool tableh]hReloading a pool table}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK[ubh)}(hX$You may reload a pool's table, indeed this is how the pool is resized if it runs out of space. (N.B. While specifying a different metadata device when reloading is not forbidden at the moment, things will go wrong if it does not route I/O to exactly the same on-disk location as previously.)h]hX&You may reload a pool’s table, indeed this is how the pool is resized if it runs out of space. (N.B. While specifying a different metadata device when reloading is not forbidden at the moment, things will go wrong if it does not route I/O to exactly the same on-disk location as previously.)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hjhhubeh}(h]reloading-a-pool-tableah ]h"]reloading a pool tableah$]h&]uh1hhjhhhhhK[ubh)}(hhh](h)}(hUsing an existing pool deviceh]hUsing an existing pool device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKdubh literal_block)}(hdmsetup create pool \ --table "0 20971520 thin-pool $metadata_dev $data_dev \ $data_block_size $low_water_mark"h]hdmsetup create pool \ --table "0 20971520 thin-pool $metadata_dev $data_dev \ $data_block_size $low_water_mark"}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhKhhjhhubh)}(hXJ$data_block_size gives the smallest unit of disk space that can be allocated at a time expressed in units of 512-byte sectors. $data_block_size must be between 128 (64KiB) and 2097152 (1GiB) and a multiple of 128 (64KiB). $data_block_size cannot be changed after the thin-pool is created. People primarily interested in thin provisioning may want to use a value such as 1024 (512KiB). People doing lots of snapshotting may want a smaller value such as 128 (64KiB). If you are not zeroing newly-allocated data, a larger $data_block_size in the region of 262144 (128MiB) is suggested.h]hXJ$data_block_size gives the smallest unit of disk space that can be allocated at a time expressed in units of 512-byte sectors. $data_block_size must be between 128 (64KiB) and 2097152 (1GiB) and a multiple of 128 (64KiB). $data_block_size cannot be changed after the thin-pool is created. People primarily interested in thin provisioning may want to use a value such as 1024 (512KiB). People doing lots of snapshotting may want a smaller value such as 128 (64KiB). If you are not zeroing newly-allocated data, a larger $data_block_size in the region of 262144 (128MiB) is suggested.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKlhjhhubh)}(hX $low_water_mark is expressed in blocks of size $data_block_size. If free space on the data device drops below this level then a dm event will be triggered which a userspace daemon should catch allowing it to extend the pool device. Only one such event will be sent.h]hX $low_water_mark is expressed in blocks of size $data_block_size. If free space on the data device drops below this level then a dm event will be triggered which a userspace daemon should catch allowing it to extend the pool device. Only one such event will be sent.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKvhjhhubh)}(hNo special event is triggered if a just resumed device's free space is below the low water mark. However, resuming a device always triggers an event; a userspace daemon should verify that free space exceeds the low water mark when handling this event.h]hNo special event is triggered if a just resumed device’s free space is below the low water mark. However, resuming a device always triggers an event; a userspace daemon should verify that free space exceeds the low water mark when handling this event.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK{hjhhubh)}(hA low water mark for the metadata device is maintained in the kernel and will trigger a dm event if free space on the metadata device drops below it.h]hA low water mark for the metadata device is maintained in the kernel and will trigger a dm event if free space on the metadata device drops below it.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]using-an-existing-pool-deviceah ]h"]using an existing pool deviceah$]h&]uh1hhjhhhhhKdubh)}(hhh](h)}(hUpdating on-disk metadatah]hUpdating on-disk metadata}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj*hhhhhKubh)}(hXeOn-disk metadata is committed every time a FLUSH or FUA bio is written. If no such requests are made then commits will occur every second. This means the thin-provisioning target behaves like a physical disk that has a volatile write cache. If power is lost you may lose some recent writes. The metadata should always be consistent in spite of any crash.h]hXeOn-disk metadata is committed every time a FLUSH or FUA bio is written. If no such requests are made then commits will occur every second. This means the thin-provisioning target behaves like a physical disk that has a volatile write cache. If power is lost you may lose some recent writes. The metadata should always be consistent in spite of any crash.}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj*hhubh)}(hXIf data space is exhausted the pool will either error or queue IO according to the configuration (see: error_if_no_space). If metadata space is exhausted or a metadata operation fails: the pool will error IO until the pool is taken offline and repair is performed to 1) fix any potential inconsistencies and 2) clear the flag that imposes repair. Once the pool's metadata device is repaired it may be resized, which will allow the pool to return to normal operation. Note that if a pool is flagged as needing repair, the pool's data and metadata devices cannot be resized until repair is performed. It should also be noted that when the pool's metadata space is exhausted the current metadata transaction is aborted. Given that the pool will cache IO whose completion may have already been acknowledged to upper IO layers (e.g. filesystem) it is strongly suggested that consistency checks (e.g. fsck) be performed on those layers when repair of the pool is required.h]hXIf data space is exhausted the pool will either error or queue IO according to the configuration (see: error_if_no_space). If metadata space is exhausted or a metadata operation fails: the pool will error IO until the pool is taken offline and repair is performed to 1) fix any potential inconsistencies and 2) clear the flag that imposes repair. Once the pool’s metadata device is repaired it may be resized, which will allow the pool to return to normal operation. Note that if a pool is flagged as needing repair, the pool’s data and metadata devices cannot be resized until repair is performed. It should also be noted that when the pool’s metadata space is exhausted the current metadata transaction is aborted. Given that the pool will cache IO whose completion may have already been acknowledged to upper IO layers (e.g. filesystem) it is strongly suggested that consistency checks (e.g. fsck) be performed on those layers when repair of the pool is required.}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj*hhubeh}(h]updating-on-disk-metadataah ]h"]updating on-disk metadataah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hThin provisioningh]hThin provisioning}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj_hhhhhKubhenumerated_list)}(hhh]j)}(h*Creating a new thinly-provisioned volume. h]h)}(h)Creating a new thinly-provisioned volume.h]h)Creating a new thinly-provisioned volume.}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjuubah}(h]h ]h"]h$]h&]uh1jhjrhhhhhNubah}(h]h ]h"]h$]h&]enumtype lowerromanprefixhsuffix)uh1jphj_hhhhhKubjU)}(hX}To create a new thinly- provisioned volume you must send a message to an active pool device, /dev/mapper/pool in this example:: dmsetup message /dev/mapper/pool 0 "create_thin 0" Here '0' is an identifier for the volume, a 24-bit number. It's up to the caller to allocate and manage these identifiers. If the identifier is already in use, the message will fail with -EEXIST. h](h)}(hTo create a new thinly- provisioned volume you must send a message to an active pool device, /dev/mapper/pool in this example::h]h~To create a new thinly- provisioned volume you must send a message to an active pool device, /dev/mapper/pool in this example:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubj)}(h2dmsetup message /dev/mapper/pool 0 "create_thin 0"h]h2dmsetup message /dev/mapper/pool 0 "create_thin 0"}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjubh)}(hHere '0' is an identifier for the volume, a 24-bit number. It's up to the caller to allocate and manage these identifiers. If the identifier is already in use, the message will fail with -EEXIST.h]hHere ‘0’ is an identifier for the volume, a 24-bit number. It’s up to the caller to allocate and manage these identifiers. If the identifier is already in use, the message will fail with -EEXIST.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jThhhKhj_hhubjq)}(hhh]j)}(h#Using a thinly-provisioned volume. h]h)}(h"Using a thinly-provisioned volume.h]h"Using a thinly-provisioned volume.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]jjjhjjstartKuh1jphj_hhhhhKubjU)}(hThinly-provisioned volumes are activated using the 'thin' target:: dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0" The last parameter is the identifier for the thinp device. h](h)}(hBThinly-provisioned volumes are activated using the 'thin' target::h]hEThinly-provisioned volumes are activated using the ‘thin’ target:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubj)}(h?dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0"h]h?dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0"}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjubh)}(h:The last parameter is the identifier for the thinp device.h]h:The last parameter is the identifier for the thinp device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jThhhKhj_hhubeh}(h]id1ah ]h"]h$]thin provisioningah&]uh1hhjhhhhhK referencedKubh)}(hhh](h)}(hInternal snapshotsh]hInternal snapshots}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+hhhhhKubjq)}(hhh]j)}(hCreating an internal snapshot. h]h)}(hCreating an internal snapshot.h]hCreating an internal snapshot.}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj?ubah}(h]h ]h"]h$]h&]uh1jhj<hhhhhNubah}(h]h ]h"]h$]h&]jjjhjjuh1jphj+hhhhhKubjU)}(hXSnapshots are created with another message to the pool. N.B. If the origin device that you wish to snapshot is active, you must suspend it before creating the snapshot to avoid corruption. This is NOT enforced at the moment, so please be careful! :: dmsetup suspend /dev/mapper/thin dmsetup message /dev/mapper/pool 0 "create_snap 1 0" dmsetup resume /dev/mapper/thin Here '1' is the identifier for the volume, a 24-bit number. '0' is the identifier for the origin device. h](h)}(h7Snapshots are created with another message to the pool.h]h7Snapshots are created with another message to the pool.}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj]ubh)}(hN.B. If the origin device that you wish to snapshot is active, you must suspend it before creating the snapshot to avoid corruption. This is NOT enforced at the moment, so please be careful!h]hN.B. If the origin device that you wish to snapshot is active, you must suspend it before creating the snapshot to avoid corruption. This is NOT enforced at the moment, so please be careful!}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj]ubj)}(hudmsetup suspend /dev/mapper/thin dmsetup message /dev/mapper/pool 0 "create_snap 1 0" dmsetup resume /dev/mapper/thinh]hudmsetup suspend /dev/mapper/thin dmsetup message /dev/mapper/pool 0 "create_snap 1 0" dmsetup resume /dev/mapper/thin}hj}sbah}(h]h ]h"]h$]h&]jjuh1jhhhKhj]ubh)}(hiHere '1' is the identifier for the volume, a 24-bit number. '0' is the identifier for the origin device.h]hqHere ‘1’ is the identifier for the volume, a 24-bit number. ‘0’ is the identifier for the origin device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj]ubeh}(h]h ]h"]h$]h&]uh1jThhhKhj+hhubjq)}(hhh]j)}(hUsing an internal snapshot. h]h)}(hUsing an internal snapshot.h]hUsing an internal snapshot.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]jjjhjjjKuh1jphj+hhhhhKubjU)}(hX1Once created, the user doesn't have to worry about any connection between the origin and the snapshot. Indeed the snapshot is no different from any other thinly-provisioned device and can be snapshotted itself via the same method. It's perfectly legal to have only one of them active, and there's no ordering requirement on activating or removing them both. (This differs from conventional device-mapper snapshots.) Activate it exactly the same way as any other thinly-provisioned volume:: dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1" h](h)}(hXOnce created, the user doesn't have to worry about any connection between the origin and the snapshot. Indeed the snapshot is no different from any other thinly-provisioned device and can be snapshotted itself via the same method. It's perfectly legal to have only one of them active, and there's no ordering requirement on activating or removing them both. (This differs from conventional device-mapper snapshots.)h]hXOnce created, the user doesn’t have to worry about any connection between the origin and the snapshot. Indeed the snapshot is no different from any other thinly-provisioned device and can be snapshotted itself via the same method. It’s perfectly legal to have only one of them active, and there’s no ordering requirement on activating or removing them both. (This differs from conventional device-mapper snapshots.)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hIActivate it exactly the same way as any other thinly-provisioned volume::h]hHActivate it exactly the same way as any other thinly-provisioned volume:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubj)}(h?dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"h]h?dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjubeh}(h]h ]h"]h$]h&]uh1jThhhKhj+hhubeh}(h]internal-snapshotsah ]h"]internal snapshotsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hExternal snapshotsh]hExternal snapshots}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hYou can use an external **read only** device as an origin for a thinly-provisioned volume. Any read to an unprovisioned area of the thin device will be passed through to the origin. Writes trigger the allocation of new blocks as usual.h](hYou can use an external }(hj hhhNhNubhstrong)}(h **read only**h]h read only}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh device as an origin for a thinly-provisioned volume. Any read to an unprovisioned area of the thin device will be passed through to the origin. Writes trigger the allocation of new blocks as usual.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hOne use case for this is VM hosts that want to run guests on thinly-provisioned volumes but have the base image on another device (possibly shared between many VMs).h]hOne use case for this is VM hosts that want to run guests on thinly-provisioned volumes but have the base image on another device (possibly shared between many VMs).}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hYou must not write to the origin device if you use this technique! Of course, you may write to the thin device and take internal snapshots of the thin volume.h]hYou must not write to the origin device if you use this technique! Of course, you may write to the thin device and take internal snapshots of the thin volume.}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjq)}(hhh]j)}(h*Creating a snapshot of an external device h]h)}(h)Creating a snapshot of an external deviceh]h)Creating a snapshot of an external device}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjNubah}(h]h ]h"]h$]h&]uh1jhjKhhhhhNubah}(h]h ]h"]h$]h&]jjjhjjuh1jphjhhhhhKubjU)}(hThis is the same as creating a thin device. You don't mention the origin at this stage. :: dmsetup message /dev/mapper/pool 0 "create_thin 0" h](h)}(hWThis is the same as creating a thin device. You don't mention the origin at this stage.h]hYThis is the same as creating a thin device. You don’t mention the origin at this stage.}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjlubj)}(h2dmsetup message /dev/mapper/pool 0 "create_thin 0"h]h2dmsetup message /dev/mapper/pool 0 "create_thin 0"}hj~sbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjlubeh}(h]h ]h"]h$]h&]uh1jThhhKhjhhubjq)}(hhh]j)}(h(Using a snapshot of an external device. h]h)}(h'Using a snapshot of an external device.h]h'Using a snapshot of an external device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]jjjhjjjKuh1jphjhhhhhKubjU)}(hAppend an extra parameter to the thin target specifying the origin:: dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image" N.B. All descendants (internal snapshots) of this snapshot require the same extra origin parameter. h](h)}(hDAppend an extra parameter to the thin target specifying the origin::h]hCAppend an extra parameter to the thin target specifying the origin:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubj)}(hJdmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image"h]hJdmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image"}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjubh)}(hcN.B. All descendants (internal snapshots) of this snapshot require the same extra origin parameter.h]hcN.B. All descendants (internal snapshots) of this snapshot require the same extra origin parameter.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jThhhKhjhhubeh}(h]external-snapshotsah ]h"]external snapshotsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h Deactivationh]h Deactivation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hKAll devices using a pool must be deactivated before the pool itself can be.h]hKAll devices using a pool must be deactivated before the pool itself can be.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h;dmsetup remove thin dmsetup remove snap dmsetup remove poolh]h;dmsetup remove thin dmsetup remove snap dmsetup remove pool}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubeh}(h] deactivationah ]h"] deactivationah$]h&]uh1hhjhhhhhKubeh}(h]cookbookah ]h"]cookbookah$]h&]uh1hhhhhhhhK1ubh)}(hhh](h)}(h Referenceh]h Reference}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,hhhhhMubh)}(hhh](h)}(h'thin-pool' targeth]h‘thin-pool’ target}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj=hhhhhMubjq)}(hhh](j)}(hXConstructor :: thin-pool \ [ []*] Optional feature arguments: skip_block_zeroing: Skip the zeroing of newly-provisioned blocks. ignore_discard: Disable discard support. no_discard_passdown: Don't pass discards down to the underlying data device, but just remove the mapping. read_only: Don't allow any changes to be made to the pool metadata. This mode is only available after the thin-pool has been created and first used in full read/write mode. It cannot be specified on initial thin-pool creation. error_if_no_space: Error IOs, instead of queueing, if no space. Data block size must be between 64KiB (128 sectors) and 1GiB (2097152 sectors) inclusive. h](h)}(h Constructorh]h Constructor}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjQubjU)}(hXi:: thin-pool \ [ []*] Optional feature arguments: skip_block_zeroing: Skip the zeroing of newly-provisioned blocks. ignore_discard: Disable discard support. no_discard_passdown: Don't pass discards down to the underlying data device, but just remove the mapping. read_only: Don't allow any changes to be made to the pool metadata. This mode is only available after the thin-pool has been created and first used in full read/write mode. It cannot be specified on initial thin-pool creation. error_if_no_space: Error IOs, instead of queueing, if no space. Data block size must be between 64KiB (128 sectors) and 1GiB (2097152 sectors) inclusive. h](j)}(hthin-pool \ [ []*]h]hthin-pool \ [ []*]}hjgsbah}(h]h ]h"]h$]h&]jjuh1jhhhM hjcubh)}(hOptional feature arguments:h]hOptional feature arguments:}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjcubjU)}(hX?skip_block_zeroing: Skip the zeroing of newly-provisioned blocks. ignore_discard: Disable discard support. no_discard_passdown: Don't pass discards down to the underlying data device, but just remove the mapping. read_only: Don't allow any changes to be made to the pool metadata. This mode is only available after the thin-pool has been created and first used in full read/write mode. It cannot be specified on initial thin-pool creation. error_if_no_space: Error IOs, instead of queueing, if no space. h]hdefinition_list)}(hhh](hdefinition_list_item)}(hBskip_block_zeroing: Skip the zeroing of newly-provisioned blocks. h](hterm)}(hskip_block_zeroing:h]hskip_block_zeroing:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjubh definition)}(hhh]h)}(h-Skip the zeroing of newly-provisioned blocks.h]h-Skip the zeroing of newly-provisioned blocks.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubj)}(h)ignore_discard: Disable discard support. h](j)}(hignore_discard:h]hignore_discard:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjubj)}(hhh]h)}(hDisable discard support.h]hDisable discard support.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubj)}(hjno_discard_passdown: Don't pass discards down to the underlying data device, but just remove the mapping. h](j)}(hno_discard_passdown:h]hno_discard_passdown:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjubj)}(hhh]h)}(hTDon't pass discards down to the underlying data device, but just remove the mapping.h]hVDon’t pass discards down to the underlying data device, but just remove the mapping.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubj)}(hread_only: Don't allow any changes to be made to the pool metadata. This mode is only available after the thin-pool has been created and first used in full read/write mode. It cannot be specified on initial thin-pool creation. h](j)}(h read_only:h]h read_only:}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM!hjubj)}(hhh]h)}(hDon't allow any changes to be made to the pool metadata. This mode is only available after the thin-pool has been created and first used in full read/write mode. It cannot be specified on initial thin-pool creation.h]hDon’t allow any changes to be made to the pool metadata. This mode is only available after the thin-pool has been created and first used in full read/write mode. It cannot be specified on initial thin-pool creation.}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj1ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM!hjubj)}(h@error_if_no_space: Error IOs, instead of queueing, if no space. h](j)}(herror_if_no_space:h]herror_if_no_space:}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM$hjNubj)}(hhh]h)}(h,Error IOs, instead of queueing, if no space.h]h,Error IOs, instead of queueing, if no space.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM$hj`ubah}(h]h ]h"]h$]h&]uh1jhjNubeh}(h]h ]h"]h$]h&]uh1jhhhM$hjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jThhhMhjcubh)}(hYData block size must be between 64KiB (128 sectors) and 1GiB (2097152 sectors) inclusive.h]hYData block size must be between 64KiB (128 sectors) and 1GiB (2097152 sectors) inclusive.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hjcubeh}(h]h ]h"]h$]h&]uh1jThhhM hjQubeh}(h]h ]h"]h$]h&]uh1jhjNhhhhhNubj)}(hX Status :: / / ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space needs_check|- metadata_low_watermark transaction id: A 64-bit number used by userspace to help synchronise with metadata from volume managers. used data blocks / total data blocks If the number of free blocks drops below the pool's low water mark a dm event will be sent to userspace. This event is edge-triggered and it will occur only once after each resume so volume manager writers should register for the event and then check the target's status. held metadata root: The location, in blocks, of the metadata root that has been 'held' for userspace read access. '-' indicates there is no held root. discard_passdown|no_discard_passdown Whether or not discards are actually being passed down to the underlying device. When this is enabled when loading the table, it can get disabled if the underlying device doesn't support it. ro|rw|out_of_data_space If the pool encounters certain types of device failures it will drop into a read-only metadata mode in which no changes to the pool metadata (like allocating new blocks) are permitted. In serious cases where even a read-only mode is deemed unsafe no further I/O will be permitted and the status will just contain the string 'Fail'. The userspace recovery tools should then be used. error_if_no_space|queue_if_no_space If the pool runs out of data or metadata space, the pool will either queue or error the IO destined to the data device. The default is to queue the IO until more space is added or the 'no_space_timeout' expires. The 'no_space_timeout' dm-thin-pool module parameter can be used to change this timeout -- it defaults to 60 seconds but may be disabled using a value of 0. needs_check A metadata operation has failed, resulting in the needs_check flag being set in the metadata's superblock. The metadata device must be deactivated and checked/repaired before the thin-pool can be made fully operational again. '-' indicates needs_check is not set. metadata_low_watermark: Value of metadata low watermark in blocks. The kernel sets this value internally but userspace needs to know this value to determine if an event was caused by crossing this threshold. h](h)}(hStatush]hStatus}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hjubj)}(h / / ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space needs_check|- metadata_low_watermarkh]h / / ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space needs_check|- metadata_low_watermark}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhM.hjubj)}(hhh](j)}(hjtransaction id: A 64-bit number used by userspace to help synchronise with metadata from volume managers. h](j)}(htransaction id:h]htransaction id:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM5hjubj)}(hhh]h)}(hYA 64-bit number used by userspace to help synchronise with metadata from volume managers.h]hYA 64-bit number used by userspace to help synchronise with metadata from volume managers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM5hjubj)}(hX6used data blocks / total data blocks If the number of free blocks drops below the pool's low water mark a dm event will be sent to userspace. This event is edge-triggered and it will occur only once after each resume so volume manager writers should register for the event and then check the target's status. h](j)}(h$used data blocks / total data blocksh]h$used data blocks / total data blocks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM;hjubj)}(hhh]h)}(hXIf the number of free blocks drops below the pool's low water mark a dm event will be sent to userspace. This event is edge-triggered and it will occur only once after each resume so volume manager writers should register for the event and then check the target's status.h]hXIf the number of free blocks drops below the pool’s low water mark a dm event will be sent to userspace. This event is edge-triggered and it will occur only once after each resume so volume manager writers should register for the event and then check the target’s status.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM8hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM;hjubj)}(hheld metadata root: The location, in blocks, of the metadata root that has been 'held' for userspace read access. '-' indicates there is no held root. h](j)}(hheld metadata root:h]hheld metadata root:}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM@hj$ubj)}(hhh]h)}(hThe location, in blocks, of the metadata root that has been 'held' for userspace read access. '-' indicates there is no held root.h]hThe location, in blocks, of the metadata root that has been ‘held’ for userspace read access. ‘-’ indicates there is no held root.}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM>hj6ubah}(h]h ]h"]h$]h&]uh1jhj$ubeh}(h]h ]h"]h$]h&]uh1jhhhM@hjubj)}(hdiscard_passdown|no_discard_passdown Whether or not discards are actually being passed down to the underlying device. When this is enabled when loading the table, it can get disabled if the underlying device doesn't support it. h](j)}(h$discard_passdown|no_discard_passdownh]h$discard_passdown|no_discard_passdown}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMEhjSubj)}(hhh]h)}(hWhether or not discards are actually being passed down to the underlying device. When this is enabled when loading the table, it can get disabled if the underlying device doesn't support it.h]hWhether or not discards are actually being passed down to the underlying device. When this is enabled when loading the table, it can get disabled if the underlying device doesn’t support it.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChjeubah}(h]h ]h"]h$]h&]uh1jhjSubeh}(h]h ]h"]h$]h&]uh1jhhhMEhjubj)}(hXro|rw|out_of_data_space If the pool encounters certain types of device failures it will drop into a read-only metadata mode in which no changes to the pool metadata (like allocating new blocks) are permitted. In serious cases where even a read-only mode is deemed unsafe no further I/O will be permitted and the status will just contain the string 'Fail'. The userspace recovery tools should then be used. h](j)}(hro|rw|out_of_data_spaceh]hro|rw|out_of_data_space}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMOhjubj)}(hhh](h)}(hIf the pool encounters certain types of device failures it will drop into a read-only metadata mode in which no changes to the pool metadata (like allocating new blocks) are permitted.h]hIf the pool encounters certain types of device failures it will drop into a read-only metadata mode in which no changes to the pool metadata (like allocating new blocks) are permitted.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjubh)}(hIn serious cases where even a read-only mode is deemed unsafe no further I/O will be permitted and the status will just contain the string 'Fail'. The userspace recovery tools should then be used.h]hIn serious cases where even a read-only mode is deemed unsafe no further I/O will be permitted and the status will just contain the string ‘Fail’. The userspace recovery tools should then be used.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMOhjubj)}(hXerror_if_no_space|queue_if_no_space If the pool runs out of data or metadata space, the pool will either queue or error the IO destined to the data device. The default is to queue the IO until more space is added or the 'no_space_timeout' expires. The 'no_space_timeout' dm-thin-pool module parameter can be used to change this timeout -- it defaults to 60 seconds but may be disabled using a value of 0. h](j)}(h#error_if_no_space|queue_if_no_spaceh]h#error_if_no_space|queue_if_no_space}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMWhjubj)}(hhh]h)}(hXrIf the pool runs out of data or metadata space, the pool will either queue or error the IO destined to the data device. The default is to queue the IO until more space is added or the 'no_space_timeout' expires. The 'no_space_timeout' dm-thin-pool module parameter can be used to change this timeout -- it defaults to 60 seconds but may be disabled using a value of 0.h]hXzIf the pool runs out of data or metadata space, the pool will either queue or error the IO destined to the data device. The default is to queue the IO until more space is added or the ‘no_space_timeout’ expires. The ‘no_space_timeout’ dm-thin-pool module parameter can be used to change this timeout -- it defaults to 60 seconds but may be disabled using a value of 0.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMWhjubj)}(hXneeds_check A metadata operation has failed, resulting in the needs_check flag being set in the metadata's superblock. The metadata device must be deactivated and checked/repaired before the thin-pool can be made fully operational again. '-' indicates needs_check is not set. h](j)}(h needs_checkh]h needs_check}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM^hjubj)}(hhh]h)}(hX A metadata operation has failed, resulting in the needs_check flag being set in the metadata's superblock. The metadata device must be deactivated and checked/repaired before the thin-pool can be made fully operational again. '-' indicates needs_check is not set.h]hXA metadata operation has failed, resulting in the needs_check flag being set in the metadata’s superblock. The metadata device must be deactivated and checked/repaired before the thin-pool can be made fully operational again. ‘-’ indicates needs_check is not set.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhj ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM^hjubj)}(hmetadata_low_watermark: Value of metadata low watermark in blocks. The kernel sets this value internally but userspace needs to know this value to determine if an event was caused by crossing this threshold. h](j)}(hmetadata_low_watermark:h]hmetadata_low_watermark:}(hj! hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMchj ubj)}(hhh]h)}(hValue of metadata low watermark in blocks. The kernel sets this value internally but userspace needs to know this value to determine if an event was caused by crossing this threshold.h]hValue of metadata low watermark in blocks. The kernel sets this value internally but userspace needs to know this value to determine if an event was caused by crossing this threshold.}(hj2 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMahj/ ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMchjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjNhhhNhNubj)}(h Messages h]h)}(hMessagesh]hMessages}(hj\ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMehjX ubah}(h]h ]h"]h$]h&]uh1jhjNhhhhhNubeh}(h]h ]h"]h$]h&]jjjhjjuh1jphj=hhhhhM ubjU)}(hX,create_thin Create a new thinly-provisioned device. is an arbitrary unique 24-bit identifier chosen by the caller. create_snap Create a new snapshot of another thinly-provisioned device. is an arbitrary unique 24-bit identifier chosen by the caller. is the identifier of the thinly-provisioned device of which the new device will be a snapshot. delete Deletes a thin device. Irreversible. set_transaction_id Userland volume managers, such as LVM, need a way to synchronise their external metadata with the internal metadata of the pool target. The thin-pool target offers to store an arbitrary 64-bit transaction id and return it on the target's status line. To avoid races you must provide what you think the current transaction id is when you change it with this compare-and-swap message. reserve_metadata_snap Reserve a copy of the data mapping btree for use by userland. This allows userland to inspect the mappings as they were when this message was executed. Use the pool's status command to get the root block associated with the metadata snapshot. release_metadata_snap Release a previously reserved copy of the data mapping btree. h]j)}(hhh](j)}(hcreate_thin Create a new thinly-provisioned device. is an arbitrary unique 24-bit identifier chosen by the caller. h](j)}(hcreate_thin h]hcreate_thin }(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMjhj} ubj)}(hhh]h)}(hoCreate a new thinly-provisioned device. is an arbitrary unique 24-bit identifier chosen by the caller.h]hoCreate a new thinly-provisioned device. is an arbitrary unique 24-bit identifier chosen by the caller.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhhj ubah}(h]h ]h"]h$]h&]uh1jhj} ubeh}(h]h ]h"]h$]h&]uh1jhhhMjhjz ubj)}(hXcreate_snap Create a new snapshot of another thinly-provisioned device. is an arbitrary unique 24-bit identifier chosen by the caller. is the identifier of the thinly-provisioned device of which the new device will be a snapshot. h](j)}(h create_snap h]h create_snap }(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMqhj ubj)}(hhh]h)}(hCreate a new snapshot of another thinly-provisioned device. is an arbitrary unique 24-bit identifier chosen by the caller. is the identifier of the thinly-provisioned device of which the new device will be a snapshot.h]hCreate a new snapshot of another thinly-provisioned device. is an arbitrary unique 24-bit identifier chosen by the caller. is the identifier of the thinly-provisioned device of which the new device will be a snapshot.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMmhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMqhjz ubj)}(h6delete Deletes a thin device. Irreversible. h](j)}(hdelete h]hdelete }(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMthj ubj)}(hhh]h)}(h%Deletes a thin device. Irreversible.h]h%Deletes a thin device. Irreversible.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMthj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMthjz ubj)}(hXset_transaction_id Userland volume managers, such as LVM, need a way to synchronise their external metadata with the internal metadata of the pool target. The thin-pool target offers to store an arbitrary 64-bit transaction id and return it on the target's status line. To avoid races you must provide what you think the current transaction id is when you change it with this compare-and-swap message. h](j)}(h(set_transaction_id h]h(set_transaction_id }(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM}hj ubj)}(hhh]h)}(hXUserland volume managers, such as LVM, need a way to synchronise their external metadata with the internal metadata of the pool target. The thin-pool target offers to store an arbitrary 64-bit transaction id and return it on the target's status line. To avoid races you must provide what you think the current transaction id is when you change it with this compare-and-swap message.h]hXUserland volume managers, such as LVM, need a way to synchronise their external metadata with the internal metadata of the pool target. The thin-pool target offers to store an arbitrary 64-bit transaction id and return it on the target’s status line. To avoid races you must provide what you think the current transaction id is when you change it with this compare-and-swap message.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMwhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhM}hjz ubj)}(hX reserve_metadata_snap Reserve a copy of the data mapping btree for use by userland. This allows userland to inspect the mappings as they were when this message was executed. Use the pool's status command to get the root block associated with the metadata snapshot. h](j)}(hreserve_metadata_snaph]hreserve_metadata_snap}(hj= hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhj9 ubj)}(hhh]h)}(hReserve a copy of the data mapping btree for use by userland. This allows userland to inspect the mappings as they were when this message was executed. Use the pool's status command to get the root block associated with the metadata snapshot.h]hReserve a copy of the data mapping btree for use by userland. This allows userland to inspect the mappings as they were when this message was executed. Use the pool’s status command to get the root block associated with the metadata snapshot.}(hjN hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjK ubah}(h]h ]h"]h$]h&]uh1jhj9 ubeh}(h]h ]h"]h$]h&]uh1jhhhMhjz ubj)}(hTrelease_metadata_snap Release a previously reserved copy of the data mapping btree. h](j)}(hrelease_metadata_snaph]hrelease_metadata_snap}(hjl hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjh ubj)}(hhh]h)}(h=Release a previously reserved copy of the data mapping btree.h]h=Release a previously reserved copy of the data mapping btree.}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjz ubah}(h]h ]h"]h$]h&]uh1jhjh ubeh}(h]h ]h"]h$]h&]uh1jhhhMhjz ubeh}(h]h ]h"]h$]h&]uh1jhjv ubah}(h]h ]h"]h$]h&]uh1jThhhMghj=hhubeh}(h]thin-pool-targetah ]h"]'thin-pool' targetah$]h&]uh1hhj,hhhhhMubh)}(hhh](h)}(h 'thin' targeth]h‘thin’ target}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubjq)}(hhh]j)}(hXConstructor :: thin [] pool dev: the thin-pool device, e.g. /dev/mapper/my_pool or 253:0 dev id: the internal device identifier of the device to be activated. external origin dev: an optional block device outside the pool to be treated as a read-only snapshot origin: reads to unprovisioned areas of the thin target will be mapped to this device. h](h)}(h Constructorh]h Constructor}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubjU)}(hX:: thin [] pool dev: the thin-pool device, e.g. /dev/mapper/my_pool or 253:0 dev id: the internal device identifier of the device to be activated. external origin dev: an optional block device outside the pool to be treated as a read-only snapshot origin: reads to unprovisioned areas of the thin target will be mapped to this device. h](j)}(h0thin []h]h0thin []}hj sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj ubj)}(hhh](j)}(hBpool dev: the thin-pool device, e.g. /dev/mapper/my_pool or 253:0 h](j)}(h pool dev:h]h pool dev:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhj ubj)}(hhh]h)}(h7the thin-pool device, e.g. /dev/mapper/my_pool or 253:0h]h7the thin-pool device, e.g. /dev/mapper/my_pool or 253:0}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMhj ubj)}(hFdev id: the internal device identifier of the device to be activated. h](j)}(hdev id:h]hdev id:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhj ubj)}(hhh]h)}(h=the internal device identifier of the device to be activated.h]h=the internal device identifier of the device to be activated.}(hj* hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj' ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMhj ubj)}(hexternal origin dev: an optional block device outside the pool to be treated as a read-only snapshot origin: reads to unprovisioned areas of the thin target will be mapped to this device. h](j)}(hexternal origin dev:h]hexternal origin dev:}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjD ubj)}(hhh]h)}(han optional block device outside the pool to be treated as a read-only snapshot origin: reads to unprovisioned areas of the thin target will be mapped to this device.h]han optional block device outside the pool to be treated as a read-only snapshot origin: reads to unprovisioned areas of the thin target will be mapped to this device.}(hjY hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjV ubah}(h]h ]h"]h$]h&]uh1jhjD ubeh}(h]h ]h"]h$]h&]uh1jhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jThhhMhj ubeh}(h]h ]h"]h$]h&]uh1jhj hhhhhNubah}(h]h ]h"]h$]h&]jjjhjjuh1jphj hhhhhMubh)}(hX/The pool doesn't store any size against the thin devices. If you load a thin target that is smaller than you've been using previously, then you'll have no access to blocks mapped beyond the end. If you load a target that is bigger than before, then extra blocks will be provisioned as and when needed.h]hX5The pool doesn’t store any size against the thin devices. If you load a thin target that is smaller than you’ve been using previously, then you’ll have no access to blocks mapped beyond the end. If you load a target that is bigger than before, then extra blocks will be provisioned as and when needed.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubjq)}(hhh]j)}(hX`Status If the pool has encountered device errors and failed, the status will just contain the string 'Fail'. The userspace recovery tools should then be used. In the case where is 0, there is no highest mapped sector and the value of is unspecified.h](h)}(hStatush]hStatus}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubj)}(hhh]j)}(h If the pool has encountered device errors and failed, the status will just contain the string 'Fail'. The userspace recovery tools should then be used. h](j)}(h+ h]h+ }(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhj ubj)}(hhh]h)}(hIf the pool has encountered device errors and failed, the status will just contain the string 'Fail'. The userspace recovery tools should then be used.h]hIf the pool has encountered device errors and failed, the status will just contain the string ‘Fail’. The userspace recovery tools should then be used.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubh)}(hIn the case where is 0, there is no highest mapped sector and the value of is unspecified.h]hIn the case where is 0, there is no highest mapped sector and the value of is unspecified.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1jhj hhhhhNubah}(h]h ]h"]h$]h&]jjjhjjjKuh1jphj hhhhhMubeh}(h] thin-targetah ]h"] 'thin' targetah$]h&]uh1hhj,hhhhhMubeh}(h] referenceah ]h"] referenceah$]h&]uh1hhhhhhhhMubeh}(h]thin-provisioningah ]h"]h$]j(ah&]uh1hhhhhhhhKj*Kubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj: error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(thin provisioningNjZjWjjj)j&j2j/jjjjj'j$j\jYjjjjj!jj j j j j j u nametypes}(j~ jZjj)j2jjj'j\jjj!j j j uh}(j hjWhjj]j&jj/jjj5jjj$jjYj*j$j_jj+jjjjj j,j j=j j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jH KsRparse_messages](hsystem_message)}(hhh]h)}(h4Duplicate implicit target name: "thin provisioning".h]h8Duplicate implicit target name: “thin provisioning”.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]j$alevelKtypeINFOsourcehʌlineKuh1j hj_hhhhhKubj )}(hhh]h)}(h;Enumerated list start value not ordinal-1: "ii" (ordinal 2)h]h?Enumerated list start value not ordinal-1: “ii” (ordinal 2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej sourcehʌlineKuh1j hj_hhhhhKubj )}(hhh]h)}(h;Enumerated list start value not ordinal-1: "ii" (ordinal 2)h]h?Enumerated list start value not ordinal-1: “ii” (ordinal 2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej sourcehʌlineKuh1j hj+hhhhhKubj )}(hhh]h)}(h;Enumerated list start value not ordinal-1: "ii" (ordinal 2)h]h?Enumerated list start value not ordinal-1: “ii” (ordinal 2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej sourcehʌlineKuh1j hjhhhhhKubj )}(hhh]h)}(h;Enumerated list start value not ordinal-1: "ii" (ordinal 2)h]h?Enumerated list start value not ordinal-1: “ii” (ordinal 2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej sourcehʌlineKuh1j hj hhhhhMubetransform_messages] transformerN include_log] decorationNhhub.