Rename to match module name. --- Documentation/device-mapper/dm-thin.txt | 249 ++++++++++++++++++++++ Documentation/device-mapper/thin-provisioning.txt | 249 ---------------------- 2 files changed, 249 insertions(+), 249 deletions(-) Index: linux-3.0-rc7/Documentation/device-mapper/dm-thin.txt =================================================================== --- /dev/null +++ linux-3.0-rc7/Documentation/device-mapper/dm-thin.txt @@ -0,0 +1,249 @@ +Introduction +============ + +This document descibes a collection of device-mapper targets that +between them implement thin provisioning and snapshots. + +The main highlight of this implementation, compared to the previous +implementation of snapshots, is it allows many virtual devices to be +stored on the same data volume. Simplifying administration and +allowing sharing of data between volumes (thus reducing disk usage). + +Another big feature is support for 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 so we won't get this degradation with depth +(fragmentation may be an issue however in some scenarios). + +Metadata is stored on a separate device from data, this gives the +administrator a bit more freedom. For instance: + +- Improve metadata resilience by storing metadata on a mirrored volume + but data on a non-mirrored one. + +- Improve performance by storing the metadata on an SSD. + + +Status +====== + +These targets are very much in the EXPERIMENTAL state. Do not use in +production. + +_Do_ experiment with it and give us feedback. Different use cases +will have different performance characteristics (for example due to +fragmentation of the data volume). If 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. + + +Cookbook +======== + +This section describes some quick recipes for using thin provisioning +using the dmsetup program to control the device-mapper driver +directly. End users are advised to use a higher level volume manager +such as LVM2. + + +Pool device +----------- + +The pool device ties together the metadata volume and the data volume. +It linearly maps to the data volume, and updates the metadata via two +mechanisms: + +- Function calls from the thin targets + +- device-mapper 'messages' from userland which control creation of new + virtual devices among other things. + + +Setting up a fresh pool device +------------------------------ + +Setting 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. + + dd if=/dev/zero of=$metadata_dev bs=4096 count=1 + +Reloading a pool table +---------------------- + +You may reload a pool's table, indeed this is how the pool is resized +if it runs out of space. Its advisable that you reload with a pool +target that points to the same metadata area. + + +Using an existing pool device +----------------------------- + + dmsetup create pool --table "0 20971520 thin-pool $metadata_dev $data_dev $data_block_size $low_water_mark" + +The $data_block_size gives the smallest unit of disk space that can be +allocated at a time. This is expressed in 512 byte sectors. People +primarily interested in thin provisioning may want to set this larger +(e.g., 1024). People doing lots of snapshotting may want it smaller +(e.g., 128). $data_block_size must be the same for the lifetime of +the metadata device. + +The $low_water_mark is expressed in 512 byte sectors, if free space on +the data device drops below this level then a dm event will be sent to +userland which should extend the pool device. + + +Thin provisioning +----------------- + +i) Creating a new thinly provisioned volume + + To create a new thin provision volume you must send a message to an + active pool device. + + dmsetup message /dev/mapper/pool 0 "new-thin 0" + + Here '0' is an identifier for the volume (32bit range). It's up to + the caller to allocate and manage these identifiers. If there's a + collision the message will fail. + +ii) Using a thinp volume + + Thin provisioned volumes are instanced using the 'thin' target. + + dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0" + + The last parameter is the 32bit identifier for the thinp device. + + +Internal snapshots +------------------ + +i) Creating an internal snapshot + + Snapshots are created with another message to the pool. + + You _must_ suspend the origin device before creating the snapshot. + If the origin hasn't been instanced via the 'thin' target then you + may proceed without doing anything. + + dmsetup suspend /dev/mapper/thin + dmsetup message /dev/mapper/pool 0 "new-snap 1 0" + dmsetup resume /dev/mapper/thin + + Here '1' is an identifier for the volume (32bit range). '0' is the + identifier for the origin device. + +ii) Using an internal snapshot + + Once 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/removing them both. + + Activate exactly the same way as any other thin provisioned volume. + + dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1" + +Teardown +-------- + +Always teardown the pool last. + + dmsetup remove thin + dmsetup remove snap + dmsetup remove pool + + +Reference +========= + +'thin-pool' target +------------------ + +i) Constructor + + thin-pool + + + +AGK FIXME Define this + [number of feature args> []*] + + Optional feature arguments: + - 'skip_block_zeroing': skips the zeroing of newly-provisioned blocks. + +ii) Status + + + + where, + + - transaction id: A 64bit number used by userland to help + synchronise with metadata from volume managers. + + - held metadata root: The location, in sectors, of the metadata + root that has been 'held' for userland read access. '-' + indicates there is no held root. + + - data free space in sectors: If this drops below the pool's low + water mark a dm event will be sent to userland. This event is + edge triggered, it will occur only once, so volume manager + writers should register for the event, then double check the + status of the target. + +iii) Messages + + new-thin + + Create a new thin provisioned device. is an arbitrary + unique 32 bit number, chosen by the caller. + + new-snap + + Create a new snapshot of another thin device. is the + dev id of the thin dev that you wish to snap. + + del + + Deletes a thin device. Irreversible. + + trim + + Delete mappings from the back of a thin device. Irreversible. You + might want to do this if you're shrinking the size of your thin + device. + + trans-id + + Userland volume managers, such as LVM, need a way to synchonise + their external metadata with the internal metadata of the pool + target. The minimal facilities that pool provides is offering to + store a 64bit transaction id (which is available on the pool + targets status line). To avoid races you must provide what you + think the current transaction id is when you change it (compare and + swap). + +'thin' target +------------- + + thin + + pool dev: the path to the pool (eg, /dev/mapper/my_pool) + dev id: the internal device identifier (32bit value) + + 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 wont be able to access mapped blocks beyond the end. If + load a target that is bigger than previously used, then extra blocks + will be provisioned as and when needed. + + If you wish to shrink your thin device and potentially regain some + data blocks then use the 'trim' message to the pool. + +i) Status + + Index: linux-3.0-rc7/Documentation/device-mapper/thin-provisioning.txt =================================================================== --- linux-3.0-rc7.orig/Documentation/device-mapper/thin-provisioning.txt +++ /dev/null @@ -1,249 +0,0 @@ -Introduction -============ - -This document descibes a collection of device-mapper targets that -between them implement thin provisioning and snapshots. - -The main highlight of this implementation, compared to the previous -implementation of snapshots, is it allows many virtual devices to be -stored on the same data volume. Simplifying administration and -allowing sharing of data between volumes (thus reducing disk usage). - -Another big feature is support for 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 so we won't get this degradation with depth -(fragmentation may be an issue however in some scenarios). - -Metadata is stored on a separate device from data, this gives the -administrator a bit more freedom. For instance: - -- Improve metadata resilience by storing metadata on a mirrored volume - but data on a non-mirrored one. - -- Improve performance by storing the metadata on an SSD. - - -Status -====== - -These targets are very much in the EXPERIMENTAL state. Do not use in -production. - -_Do_ experiment with it and give us feedback. Different use cases -will have different performance characteristics (for example due to -fragmentation of the data volume). If 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. - - -Cookbook -======== - -This section describes some quick recipes for using thin provisioning -using the dmsetup program to control the device-mapper driver -directly. End users are advised to use a higher level volume manager -such as LVM2. - - -Pool device ------------ - -The pool device ties together the metadata volume and the data volume. -It linearly maps to the data volume, and updates the metadata via two -mechanisms: - -- Function calls from the thin targets - -- device-mapper 'messages' from userland which control creation of new - virtual devices among other things. - - -Setting up a fresh pool device ------------------------------- - -Setting 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. - - dd if=/dev/zero of=$metadata_dev bs=4096 count=1 - -Reloading a pool table ----------------------- - -You may reload a pool's table, indeed this is how the pool is resized -if it runs out of space. Its advisable that you reload with a pool -target that points to the same metadata area. - - -Using an existing pool device ------------------------------ - - dmsetup create pool --table "0 20971520 thin-pool $metadata_dev $data_dev $data_block_size $low_water_mark" - -The $data_block_size gives the smallest unit of disk space that can be -allocated at a time. This is expressed in 512 byte sectors. People -primarily interested in thin provisioning may want to set this larger -(e.g., 1024). People doing lots of snapshotting may want it smaller -(e.g., 128). $data_block_size must be the same for the lifetime of -the metadata device. - -The $low_water_mark is expressed in 512 byte sectors, if free space on -the data device drops below this level then a dm event will be sent to -userland which should extend the pool device. - - -Thin provisioning ------------------ - -i) Creating a new thinly provisioned volume - - To create a new thin provision volume you must send a message to an - active pool device. - - dmsetup message /dev/mapper/pool 0 "new-thin 0" - - Here '0' is an identifier for the volume (32bit range). It's up to - the caller to allocate and manage these identifiers. If there's a - collision the message will fail. - -ii) Using a thinp volume - - Thin provisioned volumes are instanced using the 'thin' target. - - dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0" - - The last parameter is the 32bit identifier for the thinp device. - - -Internal snapshots ------------------- - -i) Creating an internal snapshot - - Snapshots are created with another message to the pool. - - You _must_ suspend the origin device before creating the snapshot. - If the origin hasn't been instanced via the 'thin' target then you - may proceed without doing anything. - - dmsetup suspend /dev/mapper/thin - dmsetup message /dev/mapper/pool 0 "new-snap 1 0" - dmsetup resume /dev/mapper/thin - - Here '1' is an identifier for the volume (32bit range). '0' is the - identifier for the origin device. - -ii) Using an internal snapshot - - Once 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/removing them both. - - Activate exactly the same way as any other thin provisioned volume. - - dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1" - -Teardown --------- - -Always teardown the pool last. - - dmsetup remove thin - dmsetup remove snap - dmsetup remove pool - - -Reference -========= - -'thin-pool' target ------------------- - -i) Constructor - - thin-pool - - - -AGK FIXME Define this - [number of feature args> []*] - - Optional feature arguments: - - 'skip_block_zeroing': skips the zeroing of newly-provisioned blocks. - -ii) Status - - - - where, - - - transaction id: A 64bit number used by userland to help - synchronise with metadata from volume managers. - - - held metadata root: The location, in sectors, of the metadata - root that has been 'held' for userland read access. '-' - indicates there is no held root. - - - data free space in sectors: If this drops below the pool's low - water mark a dm event will be sent to userland. This event is - edge triggered, it will occur only once, so volume manager - writers should register for the event, then double check the - status of the target. - -iii) Messages - - new-thin - - Create a new thin provisioned device. is an arbitrary - unique 32 bit number, chosen by the caller. - - new-snap - - Create a new snapshot of another thin device. is the - dev id of the thin dev that you wish to snap. - - del - - Deletes a thin device. Irreversible. - - trim - - Delete mappings from the back of a thin device. Irreversible. You - might want to do this if you're shrinking the size of your thin - device. - - trans-id - - Userland volume managers, such as LVM, need a way to synchonise - their external metadata with the internal metadata of the pool - target. The minimal facilities that pool provides is offering to - store a 64bit transaction id (which is available on the pool - targets status line). To avoid races you must provide what you - think the current transaction id is when you change it (compare and - swap). - -'thin' target -------------- - - thin - - pool dev: the path to the pool (eg, /dev/mapper/my_pool) - dev id: the internal device identifier (32bit value) - - 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 wont be able to access mapped blocks beyond the end. If - load a target that is bigger than previously used, then extra blocks - will be provisioned as and when needed. - - If you wish to shrink your thin device and potentially regain some - data blocks then use the 'trim' message to the pool. - -i) Status - -