Documentation/device-mapper/thin-provisioning.txt

   1 Introduction
   2 ============
   3
   4 This document descibes a collection of device-mapper targets that
   5 between them implement thin-provisioning and snapshots.
   6
   7 The main highlight of this implementation, compared to the previous
   8 implementation of snapshots, is that it allows many virtual devices to
   9 be stored on the same data volume.  This simplifies administration and
  10 allows the sharing of data between volumes, thus reducing disk usage.
  11
  12 Another significant feature is support for an arbitrary depth of
  13 recursive snapshots (snapshots of snapshots of snapshots ...).  The
  14 previous implementation of snapshots did this by chaining together
  15 lookup tables, and so performance was O(depth).  This new
  16 implementation uses a single data structure to avoid this degradation
  17 with depth.  Fragmentation may still be an issue, however, in some
  18 scenarios.
  19
  20 Metadata is stored on a separate device from data, giving the
  21 administrator some freedom, for example to:
  22
  23 - Improve metadata resilience by storing metadata on a mirrored volume
  24   but data on a non-mirrored one.
  25
  26 - Improve performance by storing the metadata on SSD.
  27
  28 Status
  29 ======
  30
  31 These targets are very much still in the EXPERIMENTAL state.  Please
  32 do not yet rely on them in production.  But do experiment and offer us
  33 feedback.  Different use cases will have different performance
  34 characteristics, for example due to fragmentation of the data volume.
  35
  36 If you find this software is not performing as expected please mail
  37 dm-devel@redhat.com with details and we'll try our best to improve
  38 things for you.
  39
  40 Userspace tools for checking and repairing the metadata are under
  41 development.
  42
  43 Cookbook
  44 ========
  45
  46 This section describes some quick recipes for using thin provisioning.
  47 They use the dmsetup program to control the device-mapper driver
  48 directly.  End users will be advised to use a higher-level volume
  49 manager such as LVM2 once support has been added.
  50
  51 Pool device
  52 -----------
  53
  54 The pool device ties together the metadata volume and the data volume.
  55 It maps I/O linearly to the data volume and updates the metadata via
  56 two mechanisms:
  57
  58 - Function calls from the thin targets
  59
  60 - Device-mapper 'messages' from userspace which control the creation of new
  61   virtual devices amongst other things.
  62
  63 Setting up a fresh pool device
  64 ------------------------------
  65
  66 Setting up a pool device requires a valid metadata device, and a
  67 data device.  If you do not have an existing metadata device you can
  68 make one by zeroing the first 4k to indicate empty metadata.
  69
  70     dd if=/dev/zero of=$metadata_dev bs=4096 count=1
  71
  72 The amount of metadata you need will vary according to how many blocks
  73 are shared between thin devices (i.e. through snapshots).  If you have
  74 less sharing than average you'll need a larger-than-average metadata device.
  75
  76 As a guide, we suggest you calculate the number of bytes to use in the
  77 metadata device as 48 * $data_dev_size / $data_block_size but round it up
  78 to 2MB if the answer is smaller.  The largest size supported is 16GB.
  79
  80 If you're creating large numbers of snapshots which are recording large
  81 amounts of change, you may need find you need to increase this.
  82
  83 Reloading a pool table
  84 ----------------------
  85
  86 You may reload a pool's table, indeed this is how the pool is resized
  87 if it runs out of space.  (N.B. While specifying a different metadata
  88 device when reloading is not forbidden at the moment, things will go
  89 wrong if it does not route I/O to exactly the same on-disk location as
  90 previously.)
  91
  92 Using an existing pool device
  93 -----------------------------
  94
  95     dmsetup create pool \
  96         --table "0 20971520 thin-pool $metadata_dev $data_dev \
  97                  $data_block_size $low_water_mark"
  98
  99 $data_block_size gives the smallest unit of disk space that can be
 100 allocated at a time expressed in units of 512-byte sectors.  People
 101 primarily interested in thin provisioning may want to use a value such
 102 as 1024 (512KB).  People doing lots of snapshotting may want a smaller value
 103 such as 128 (64KB).  If you are not zeroing newly-allocated data,
 104 a larger $data_block_size in the region of 256000 (128MB) is suggested.
 105 $data_block_size must be the same for the lifetime of the
 106 metadata device.
 107
 108 $low_water_mark is expressed in blocks of size $data_block_size.  If
 109 free space on the data device drops below this level then a dm event
 110 will be triggered which a userspace daemon should catch allowing it to
 111 extend the pool device.  Only one such event will be sent.
 112
 113 No special event is triggered if a just resumed device's free space is below
 114 the low water mark. However, resuming a device always triggers an
 115 event; a userspace daemon should verify that free space exceeds the low
 116 water mark when handling this event.
 117
 118 Thin provisioning
 119 -----------------
 120
 121 i) Creating a new thinly-provisioned volume.
 122
 123   To create a new thinly- provisioned volume you must send a message to an
 124   active pool device, /dev/mapper/pool in this example.
 125
 126     dmsetup message /dev/mapper/pool 0 "create_thin 0"
 127
 128   Here '0' is an identifier for the volume, a 24-bit number.  It's up
 129   to the caller to allocate and manage these identifiers.  If the
 130   identifier is already in use, the message will fail with -EEXIST.
 131
 132 ii) Using a thinly-provisioned volume.
 133
 134   Thinly-provisioned volumes are activated using the 'thin' target:
 135
 136     dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0"
 137
 138   The last parameter is the identifier for the thinp device.
 139
 140 Internal snapshots
 141 ------------------
 142
 143 i) Creating an internal snapshot.
 144
 145   Snapshots are created with another message to the pool.
 146
 147   N.B.  If the origin device that you wish to snapshot is active, you
 148   must suspend it before creating the snapshot to avoid corruption.
 149   This is NOT enforced at the moment, so please be careful!
 150
 151     dmsetup suspend /dev/mapper/thin
 152     dmsetup message /dev/mapper/pool 0 "create_snap 1 0"
 153     dmsetup resume /dev/mapper/thin
 154
 155   Here '1' is the identifier for the volume, a 24-bit number.  '0' is the
 156   identifier for the origin device.
 157
 158 ii) Using an internal snapshot.
 159
 160   Once created, the user doesn't have to worry about any connection
 161   between the origin and the snapshot.  Indeed the snapshot is no
 162   different from any other thinly-provisioned device and can be
 163   snapshotted itself via the same method.  It's perfectly legal to
 164   have only one of them active, and there's no ordering requirement on
 165   activating or removing them both.  (This differs from conventional
 166   device-mapper snapshots.)
 167
 168   Activate it exactly the same way as any other thinly-provisioned volume:
 169
 170     dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"
 171
 172 Deactivation
 173 ------------
 174
 175 All devices using a pool must be deactivated before the pool itself
 176 can be.
 177
 178     dmsetup remove thin
 179     dmsetup remove snap
 180     dmsetup remove pool
 181
 182 Reference
 183 =========
 184
 185 'thin-pool' target
 186 ------------------
 187
 188 i) Constructor
 189
 190     thin-pool <metadata dev> <data dev> <data block size (sectors)> \
 191               <low water mark (blocks)> [<number of feature args> [<arg>]*]
 192
 193     Optional feature arguments:
 194     - 'skip_block_zeroing': skips the zeroing of newly-provisioned blocks.
 195
 196     Data block size must be between 64KB (128 sectors) and 1GB
 197     (2097152 sectors) inclusive.
 198
 199
 200 ii) Status
 201
 202     <transaction id> <used metadata blocks>/<total metadata blocks>
 203     <used data blocks>/<total data blocks> <held metadata root>
 204
 205
 206     transaction id:
 207         A 64-bit number used by userspace to help synchronise with metadata
 208         from volume managers.
 209
 210     used data blocks / total data blocks
 211         If the number of free blocks drops below the pool's low water mark a
 212         dm event will be sent to userspace.  This event is edge-triggered and
 213         it will occur only once after each resume so volume manager writers
 214         should register for the event and then check the target's status.
 215
 216     held metadata root:
 217         The location, in sectors, of the metadata root that has been
 218         'held' for userspace read access.  '-' indicates there is no
 219         held root.  This feature is not yet implemented so '-' is
 220         always returned.
 221
 222 iii) Messages
 223
 224     create_thin <dev id>
 225
 226         Create a new thinly-provisioned device.
 227         <dev id> is an arbitrary unique 24-bit identifier chosen by
 228         the caller.
 229
 230     create_snap <dev id> <origin id>
 231
 232         Create a new snapshot of another thinly-provisioned device.
 233         <dev id> is an arbitrary unique 24-bit identifier chosen by
 234         the caller.
 235         <origin id> is the identifier of the thinly-provisioned device
 236         of which the new device will be a snapshot.
 237
 238     delete <dev id>
 239
 240         Deletes a thin device.  Irreversible.
 241
 242     trim <dev id> <new size in sectors>
 243
 244         Delete mappings from the end of a thin device.  Irreversible.
 245         You might want to use this if you're reducing the size of
 246         your thinly-provisioned device.  In many cases, due to the
 247         sharing of blocks between devices, it is not possible to
 248         determine in advance how much space 'trim' will release.  (In
 249         future a userspace tool might be able to perform this
 250         calculation.)
 251
 252     set_transaction_id <current id> <new id>
 253
 254         Userland volume managers, such as LVM, need a way to
 255         synchronise their external metadata with the internal metadata of the
 256         pool target.  The thin-pool target offers to store an
 257         arbitrary 64-bit transaction id and return it on the target's
 258         status line.  To avoid races you must provide what you think
 259         the current transaction id is when you change it with this
 260         compare-and-swap message.
 261
 262 'thin' target
 263 -------------
 264
 265 i) Constructor
 266
 267     thin <pool dev> <dev id>
 268
 269     pool dev:
 270         the thin-pool device, e.g. /dev/mapper/my_pool or 253:0
 271
 272     dev id:
 273         the internal device identifier of the device to be
 274         activated.
 275
 276 The pool doesn't store any size against the thin devices.  If you
 277 load a thin target that is smaller than you've been using previously,
 278 then you'll have no access to blocks mapped beyond the end.  If you
 279 load a target that is bigger than before, then extra blocks will be
 280 provisioned as and when needed.
 281
 282 If you wish to reduce the size of your thin device and potentially
 283 regain some space then send the 'trim' message to the pool.
 284
 285 ii) Status
 286
 287      <nr mapped sectors> <highest mapped sector>