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 FIXME How big must $metadata_dev be?
  73
  74 Reloading a pool table
  75 ----------------------
  76
  77 You may reload a pool's table, indeed this is how the pool is resized
  78 if it runs out of space.  (N.B. While specifying a different metadata
  79 device when reloading is not forbidden at the moment, things will go
  80 wrong if it does not route I/O to exactly the same on-disk location as
  81 previously.)
  82
  83 Using an existing pool device
  84 -----------------------------
  85
  86     dmsetup create pool \
  87         --table "0 20971520 thin-pool $metadata_dev $data_dev \
  88                  $data_block_size $low_water_mark"
  89
  90 $data_block_size gives the smallest unit of disk space that can be
  91 allocated at a time.  As with all sizes passed to device-mapper, this
  92 is expressed in units of 512-byte sectors.  People primarily
  93 interested in thin provisioning may want to use a value such as 1024.
  94 People doing lots of snapshotting may want a smaller value such as
  95 128.  $data_block_size must be the same for the lifetime of the
  96 metadata device.
  97
  98 $low_water_mark is expressed in 512-byte sectors.  If free space on
  99 the data device drops below this level then a dm event will be
 100 triggered which a userspace daemon should catch allowing it to
 101 extend the pool device.  Only one such event will be sent.
 102
 103 FIXME - Do we get a second event after a table reload when you're
 104 already over the threshold?
 105
 106 Thin provisioning
 107 -----------------
 108
 109 i) Creating a new thinly-provisioned volume.
 110
 111   To create a new thinly- provisioned volume you must send a message to an
 112   active pool device, /dev/mapper/pool in this example.
 113
 114     dmsetup message /dev/mapper/pool 0 "create_thin 0"
 115
 116   Here '0' is an identifier for the volume, a 24-bit number.  It's up
 117   to the caller to allocate and manage these identifiers.  If the
 118   identifier is already in use, the message will fail.
 119 FIXME With what error?
 120
 121 ii) Using a thinly-provisioned volume.
 122
 123   Thinly-provisioned volumes are activated using the 'thin' target:
 124
 125     dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0"
 126
 127   The last parameter is the identifier for the thinp device.
 128
 129 Internal snapshots
 130 ------------------
 131
 132 i) Creating an internal snapshot.
 133
 134   Snapshots are created with another message to the pool.
 135
 136   If the origin device that you wish to snapshot is active, you must
 137   suspend it before creating the snapshot.
 138 FIXME What happens if you don't?
 139
 140     dmsetup suspend /dev/mapper/thin
 141     dmsetup message /dev/mapper/pool 0 "create_snap 1 0"
 142     dmsetup resume /dev/mapper/thin
 143
 144   Here '1' is the identifier for the volume, a 24-bit number.  '0' is the
 145   identifier for the origin device.
 146
 147 ii) Using an internal snapshot.
 148
 149   Once created, the user doesn't have to worry about any connection
 150   between the origin and the snapshot.  Indeed the snapshot is no
 151   different from any other thinly-provisioned device and can be
 152   snapshotted itself via the same method.  It's perfectly legal to
 153   have only one of them active, and there's no ordering requirement on
 154   activating or removing them both.  (This differs from conventional
 155   device-mapper snapshots.)
 156
 157   Activate it exactly the same way as any other thinly-provisioned volume:
 158
 159     dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"
 160
 161 Deactivation
 162 ------------
 163
 164 All devices using a pool must be deactivated before the pool itself
 165 can be.
 166
 167     dmsetup remove thin
 168     dmsetup remove snap
 169     dmsetup remove pool
 170
 171 Reference
 172 =========
 173
 174 'thin-pool' target
 175 ------------------
 176
 177 i) Constructor
 178
 179     thin-pool <metadata dev> <data dev> <data block size (sectors)> \
 180               <low water mark (sectors)> [<number of feature args> [<arg>]*]
 181
 182     Optional feature arguments:
 183     - 'skip_block_zeroing': skips the zeroing of newly-provisioned blocks.
 184
 185     Data block size must be between 64KB (128 sectors) and 1GB
 186     (2097152 sectors) inclusive.
 187
 188 ii) Status
 189
 190     <transaction id> <used metadata sectors>/<total metadata sectors>
 191     <used data sectors>/<total data sectors> <held metadata root>
 192
 193
 194     transaction id:
 195         A 64-bit number used by userspace to help synchronise with metadata
 196         from volume managers.
 197
 198     used data sectors / total data sectors
 199         If the number of free sectors drops below the pool's low water mark a
 200         dm event will be sent to userspace.  This event is edge-triggered and
 201         it will occur only once after each resume so volume manager writers
 202         should register for the event and then check the target's status.
 203
 204     held metadata root:
 205         The location, in sectors, of the metadata root that has been
 206         'held' for userspace read access.  '-' indicates there is no
 207         held root.  This feature is not yet implemented so '-' is
 208         always returned.
 209
 210 iii) Messages
 211
 212     create_thin <dev id>
 213
 214         Create a new thinly-provisioned device.
 215         <dev id> is an arbitrary unique 24-bit identifier chosen by
 216         the caller.
 217
 218     create_snap <dev id> <origin id>
 219
 220         Create a new snapshot of another thinly-provisioned device.
 221         <dev id> is an arbitrary unique 24-bit identifier chosen by
 222         the caller.
 223         <origin id> is the identifier of the thinly-provisioned device
 224         of which the new device will be a snapshot.
 225
 226     delete <dev id>
 227
 228         Deletes a thin device.  Irreversible.
 229
 230     trim <dev id> <new size in sectors>
 231
 232         Delete mappings from the end of a thin device.  Irreversible.
 233         You might want to use this if you're reducing the size of
 234         your thinly-provisioned device.  In many cases, due to the
 235         sharing of blocks between devices, it is not possible to
 236         determine in advance how much space 'trim' will release.  (In
 237         future a userspace tool might be able to perform this
 238         calculation.)
 239
 240     set_transaction_id <current id> <new id>
 241
 242         Userland volume managers, such as LVM, need a way to
 243         synchronise their external metadata with the internal metadata of the
 244         pool target.  The thin-pool target offers to store an
 245         arbitrary 64-bit transaction id and return it on the target's
 246         status line.  To avoid races you must provide what you think
 247         the current transaction id is when you change it with this
 248         compare-and-swap message.
 249
 250 'thin' target
 251 -------------
 252
 253 i) Constructor
 254
 255     thin <pool dev> <dev id>
 256
 257     pool dev:
 258         the thin-pool device, e.g. /dev/mapper/my_pool or 253:0
 259
 260     dev id:
 261         the internal device identifier of the device to be
 262         activated.
 263
 264 The pool doesn't store any size against the thin devices.  If you
 265 load a thin target that is smaller than you've been using previously,
 266 then you'll have no access to blocks mapped beyond the end.  If you
 267 load a target that is bigger than before, then extra blocks will be
 268 provisioned as and when needed.
 269
 270 If you wish to reduce the size of your thin device and potentially
 271 regain some space then send the 'trim' message to the pool.
 272
 273 ii) Status
 274
 275      <nr mapped sectors> <highest mapped sector>