thin-provisioning.rst 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427
  1. =================
  2. Thin provisioning
  3. =================
  4. Introduction
  5. ============
  6. This document describes a collection of device-mapper targets that
  7. between them implement thin-provisioning and snapshots.
  8. The main highlight of this implementation, compared to the previous
  9. implementation of snapshots, is that it allows many virtual devices to
  10. be stored on the same data volume. This simplifies administration and
  11. allows the sharing of data between volumes, thus reducing disk usage.
  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. Metadata is stored on a separate device from data, giving the
  20. administrator some freedom, for example to:
  21. - Improve metadata resilience by storing metadata on a mirrored volume
  22. but data on a non-mirrored one.
  23. - Improve performance by storing the metadata on SSD.
  24. Status
  25. ======
  26. These targets are considered safe for production use. But different use
  27. cases will have different performance characteristics, for example due
  28. to fragmentation of the data volume.
  29. If you find this software is not performing as expected please mail
  30. dm-devel@redhat.com with details and we'll try our best to improve
  31. things for you.
  32. Userspace tools for checking and repairing the metadata have been fully
  33. developed and are available as 'thin_check' and 'thin_repair'. The name
  34. of the package that provides these utilities varies by distribution (on
  35. a Red Hat distribution it is named 'device-mapper-persistent-data').
  36. Cookbook
  37. ========
  38. This section describes some quick recipes for using thin provisioning.
  39. They use the dmsetup program to control the device-mapper driver
  40. directly. End users will be advised to use a higher-level volume
  41. manager such as LVM2 once support has been added.
  42. Pool device
  43. -----------
  44. The pool device ties together the metadata volume and the data volume.
  45. It maps I/O linearly to the data volume and updates the metadata via
  46. two mechanisms:
  47. - Function calls from the thin targets
  48. - Device-mapper 'messages' from userspace which control the creation of new
  49. virtual devices amongst other things.
  50. Setting up a fresh pool device
  51. ------------------------------
  52. Setting up a pool device requires a valid metadata device, and a
  53. data device. If you do not have an existing metadata device you can
  54. make one by zeroing the first 4k to indicate empty metadata.
  55. dd if=/dev/zero of=$metadata_dev bs=4096 count=1
  56. The amount of metadata you need will vary according to how many blocks
  57. are shared between thin devices (i.e. through snapshots). If you have
  58. less sharing than average you'll need a larger-than-average metadata device.
  59. As a guide, we suggest you calculate the number of bytes to use in the
  60. metadata device as 48 * $data_dev_size / $data_block_size but round it up
  61. to 2MB if the answer is smaller. If you're creating large numbers of
  62. snapshots which are recording large amounts of change, you may find you
  63. need to increase this.
  64. The largest size supported is 16GB: If the device is larger,
  65. a warning will be issued and the excess space will not be used.
  66. Reloading a pool table
  67. ----------------------
  68. You may reload a pool's table, indeed this is how the pool is resized
  69. if it runs out of space. (N.B. While specifying a different metadata
  70. device when reloading is not forbidden at the moment, things will go
  71. wrong if it does not route I/O to exactly the same on-disk location as
  72. previously.)
  73. Using an existing pool device
  74. -----------------------------
  75. ::
  76. dmsetup create pool \
  77. --table "0 20971520 thin-pool $metadata_dev $data_dev \
  78. $data_block_size $low_water_mark"
  79. $data_block_size gives the smallest unit of disk space that can be
  80. allocated at a time expressed in units of 512-byte sectors.
  81. $data_block_size must be between 128 (64KB) and 2097152 (1GB) and a
  82. multiple of 128 (64KB). $data_block_size cannot be changed after the
  83. thin-pool is created. People primarily interested in thin provisioning
  84. may want to use a value such as 1024 (512KB). People doing lots of
  85. snapshotting may want a smaller value such as 128 (64KB). If you are
  86. not zeroing newly-allocated data, a larger $data_block_size in the
  87. region of 256000 (128MB) is suggested.
  88. $low_water_mark is expressed in blocks of size $data_block_size. If
  89. free space on the data device drops below this level then a dm event
  90. will be triggered which a userspace daemon should catch allowing it to
  91. extend the pool device. Only one such event will be sent.
  92. No special event is triggered if a just resumed device's free space is below
  93. the low water mark. However, resuming a device always triggers an
  94. event; a userspace daemon should verify that free space exceeds the low
  95. water mark when handling this event.
  96. A low water mark for the metadata device is maintained in the kernel and
  97. will trigger a dm event if free space on the metadata device drops below
  98. it.
  99. Updating on-disk metadata
  100. -------------------------
  101. On-disk metadata is committed every time a FLUSH or FUA bio is written.
  102. If no such requests are made then commits will occur every second. This
  103. means the thin-provisioning target behaves like a physical disk that has
  104. a volatile write cache. If power is lost you may lose some recent
  105. writes. The metadata should always be consistent in spite of any crash.
  106. If data space is exhausted the pool will either error or queue IO
  107. according to the configuration (see: error_if_no_space). If metadata
  108. space is exhausted or a metadata operation fails: the pool will error IO
  109. until the pool is taken offline and repair is performed to 1) fix any
  110. potential inconsistencies and 2) clear the flag that imposes repair.
  111. Once the pool's metadata device is repaired it may be resized, which
  112. will allow the pool to return to normal operation. Note that if a pool
  113. is flagged as needing repair, the pool's data and metadata devices
  114. cannot be resized until repair is performed. It should also be noted
  115. that when the pool's metadata space is exhausted the current metadata
  116. transaction is aborted. Given that the pool will cache IO whose
  117. completion may have already been acknowledged to upper IO layers
  118. (e.g. filesystem) it is strongly suggested that consistency checks
  119. (e.g. fsck) be performed on those layers when repair of the pool is
  120. required.
  121. Thin provisioning
  122. -----------------
  123. i) Creating a new thinly-provisioned volume.
  124. To create a new thinly- provisioned volume you must send a message to an
  125. active pool device, /dev/mapper/pool in this example::
  126. dmsetup message /dev/mapper/pool 0 "create_thin 0"
  127. Here '0' is an identifier for the volume, a 24-bit number. It's up
  128. to the caller to allocate and manage these identifiers. If the
  129. identifier is already in use, the message will fail with -EEXIST.
  130. ii) Using a thinly-provisioned volume.
  131. Thinly-provisioned volumes are activated using the 'thin' target::
  132. dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0"
  133. The last parameter is the identifier for the thinp device.
  134. Internal snapshots
  135. ------------------
  136. i) Creating an internal snapshot.
  137. Snapshots are created with another message to the pool.
  138. N.B. If the origin device that you wish to snapshot is active, you
  139. must suspend it before creating the snapshot to avoid corruption.
  140. This is NOT enforced at the moment, so please be careful!
  141. ::
  142. dmsetup suspend /dev/mapper/thin
  143. dmsetup message /dev/mapper/pool 0 "create_snap 1 0"
  144. dmsetup resume /dev/mapper/thin
  145. Here '1' is the identifier for the volume, a 24-bit number. '0' is the
  146. identifier for the origin device.
  147. ii) Using an internal snapshot.
  148. Once created, the user doesn't have to worry about any connection
  149. between the origin and the snapshot. Indeed the snapshot is no
  150. different from any other thinly-provisioned device and can be
  151. snapshotted itself via the same method. It's perfectly legal to
  152. have only one of them active, and there's no ordering requirement on
  153. activating or removing them both. (This differs from conventional
  154. device-mapper snapshots.)
  155. Activate it exactly the same way as any other thinly-provisioned volume::
  156. dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"
  157. External snapshots
  158. ------------------
  159. You can use an external **read only** device as an origin for a
  160. thinly-provisioned volume. Any read to an unprovisioned area of the
  161. thin device will be passed through to the origin. Writes trigger
  162. the allocation of new blocks as usual.
  163. One use case for this is VM hosts that want to run guests on
  164. thinly-provisioned volumes but have the base image on another device
  165. (possibly shared between many VMs).
  166. You must not write to the origin device if you use this technique!
  167. Of course, you may write to the thin device and take internal snapshots
  168. of the thin volume.
  169. i) Creating a snapshot of an external device
  170. This is the same as creating a thin device.
  171. You don't mention the origin at this stage.
  172. ::
  173. dmsetup message /dev/mapper/pool 0 "create_thin 0"
  174. ii) Using a snapshot of an external device.
  175. Append an extra parameter to the thin target specifying the origin::
  176. dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image"
  177. N.B. All descendants (internal snapshots) of this snapshot require the
  178. same extra origin parameter.
  179. Deactivation
  180. ------------
  181. All devices using a pool must be deactivated before the pool itself
  182. can be.
  183. ::
  184. dmsetup remove thin
  185. dmsetup remove snap
  186. dmsetup remove pool
  187. Reference
  188. =========
  189. 'thin-pool' target
  190. ------------------
  191. i) Constructor
  192. ::
  193. thin-pool <metadata dev> <data dev> <data block size (sectors)> \
  194. <low water mark (blocks)> [<number of feature args> [<arg>]*]
  195. Optional feature arguments:
  196. skip_block_zeroing:
  197. Skip the zeroing of newly-provisioned blocks.
  198. ignore_discard:
  199. Disable discard support.
  200. no_discard_passdown:
  201. Don't pass discards down to the underlying
  202. data device, but just remove the mapping.
  203. read_only:
  204. Don't allow any changes to be made to the pool
  205. metadata. This mode is only available after the
  206. thin-pool has been created and first used in full
  207. read/write mode. It cannot be specified on initial
  208. thin-pool creation.
  209. error_if_no_space:
  210. Error IOs, instead of queueing, if no space.
  211. Data block size must be between 64KB (128 sectors) and 1GB
  212. (2097152 sectors) inclusive.
  213. ii) Status
  214. ::
  215. <transaction id> <used metadata blocks>/<total metadata blocks>
  216. <used data blocks>/<total data blocks> <held metadata root>
  217. ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space
  218. needs_check|- metadata_low_watermark
  219. transaction id:
  220. A 64-bit number used by userspace to help synchronise with metadata
  221. from volume managers.
  222. used data blocks / total data blocks
  223. If the number of free blocks drops below the pool's low water mark a
  224. dm event will be sent to userspace. This event is edge-triggered and
  225. it will occur only once after each resume so volume manager writers
  226. should register for the event and then check the target's status.
  227. held metadata root:
  228. The location, in blocks, of the metadata root that has been
  229. 'held' for userspace read access. '-' indicates there is no
  230. held root.
  231. discard_passdown|no_discard_passdown
  232. Whether or not discards are actually being passed down to the
  233. underlying device. When this is enabled when loading the table,
  234. it can get disabled if the underlying device doesn't support it.
  235. ro|rw|out_of_data_space
  236. If the pool encounters certain types of device failures it will
  237. drop into a read-only metadata mode in which no changes to
  238. the pool metadata (like allocating new blocks) are permitted.
  239. In serious cases where even a read-only mode is deemed unsafe
  240. no further I/O will be permitted and the status will just
  241. contain the string 'Fail'. The userspace recovery tools
  242. should then be used.
  243. error_if_no_space|queue_if_no_space
  244. If the pool runs out of data or metadata space, the pool will
  245. either queue or error the IO destined to the data device. The
  246. default is to queue the IO until more space is added or the
  247. 'no_space_timeout' expires. The 'no_space_timeout' dm-thin-pool
  248. module parameter can be used to change this timeout -- it
  249. defaults to 60 seconds but may be disabled using a value of 0.
  250. needs_check
  251. A metadata operation has failed, resulting in the needs_check
  252. flag being set in the metadata's superblock. The metadata
  253. device must be deactivated and checked/repaired before the
  254. thin-pool can be made fully operational again. '-' indicates
  255. needs_check is not set.
  256. metadata_low_watermark:
  257. Value of metadata low watermark in blocks. The kernel sets this
  258. value internally but userspace needs to know this value to
  259. determine if an event was caused by crossing this threshold.
  260. iii) Messages
  261. create_thin <dev id>
  262. Create a new thinly-provisioned device.
  263. <dev id> is an arbitrary unique 24-bit identifier chosen by
  264. the caller.
  265. create_snap <dev id> <origin id>
  266. Create a new snapshot of another thinly-provisioned device.
  267. <dev id> is an arbitrary unique 24-bit identifier chosen by
  268. the caller.
  269. <origin id> is the identifier of the thinly-provisioned device
  270. of which the new device will be a snapshot.
  271. delete <dev id>
  272. Deletes a thin device. Irreversible.
  273. set_transaction_id <current id> <new id>
  274. Userland volume managers, such as LVM, need a way to
  275. synchronise their external metadata with the internal metadata of the
  276. pool target. The thin-pool target offers to store an
  277. arbitrary 64-bit transaction id and return it on the target's
  278. status line. To avoid races you must provide what you think
  279. the current transaction id is when you change it with this
  280. compare-and-swap message.
  281. reserve_metadata_snap
  282. Reserve a copy of the data mapping btree for use by userland.
  283. This allows userland to inspect the mappings as they were when
  284. this message was executed. Use the pool's status command to
  285. get the root block associated with the metadata snapshot.
  286. release_metadata_snap
  287. Release a previously reserved copy of the data mapping btree.
  288. 'thin' target
  289. -------------
  290. i) Constructor
  291. ::
  292. thin <pool dev> <dev id> [<external origin dev>]
  293. pool dev:
  294. the thin-pool device, e.g. /dev/mapper/my_pool or 253:0
  295. dev id:
  296. the internal device identifier of the device to be
  297. activated.
  298. external origin dev:
  299. an optional block device outside the pool to be treated as a
  300. read-only snapshot origin: reads to unprovisioned areas of the
  301. thin target will be mapped to this device.
  302. The pool doesn't store any size against the thin devices. If you
  303. load a thin target that is smaller than you've been using previously,
  304. then you'll have no access to blocks mapped beyond the end. If you
  305. load a target that is bigger than before, then extra blocks will be
  306. provisioned as and when needed.
  307. ii) Status
  308. <nr mapped sectors> <highest mapped sector>
  309. If the pool has encountered device errors and failed, the status
  310. will just contain the string 'Fail'. The userspace recovery
  311. tools should then be used.
  312. In the case where <nr mapped sectors> is 0, there is no highest
  313. mapped sector and the value of <highest mapped sector> is unspecified.