← Back to branch summary

~ubuntu-branches/debian/sid/lvm2/sid

« back to all changes in this revision

Viewing changes to doc/kernel/thin-provisioning.txt

  • Committer: Package Import Robot
  • Author(s): Bastian Blank
  • Date: 2013-03-03 12:33:47 UTC
  • mfrom: (1.1.15)
  • Revision ID: package-import@ubuntu.com-20130303123347-smfwei6dodkdth55
Tags: 2.02.98-1
New upstream version.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/kernel/thin-provisioning.txt
1
1
Introduction
2
2
============
3
3
 
4
 
This document descibes a collection of device-mapper targets that
 
4
This document describes a collection of device-mapper targets that
5
5
between them implement thin-provisioning and snapshots.
6
6
 
7
7
The main highlight of this implementation, compared to the previous
75
75
 
76
76
As a guide, we suggest you calculate the number of bytes to use in the
77
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.
 
78
to 2MB if the answer is smaller.  If you're creating large numbers of
 
79
snapshots which are recording large amounts of change, you may find you
 
80
need to increase this.
79
81
 
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
The largest size supported is 16GB: If the device is larger,
 
83
a warning will be issued and the excess space will not be used.
82
84
 
83
85
Reloading a pool table
84
86
----------------------
167
169
 
168
170
    dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"
169
171
 
 
172
External snapshots
 
173
------------------
 
174
 
 
175
You can use an external _read only_ device as an origin for a
 
176
thinly-provisioned volume.  Any read to an unprovisioned area of the
 
177
thin device will be passed through to the origin.  Writes trigger
 
178
the allocation of new blocks as usual.
 
179
 
 
180
One use case for this is VM hosts that want to run guests on
 
181
thinly-provisioned volumes but have the base image on another device
 
182
(possibly shared between many VMs).
 
183
 
 
184
You must not write to the origin device if you use this technique!
 
185
Of course, you may write to the thin device and take internal snapshots
 
186
of the thin volume.
 
187
 
 
188
i) Creating a snapshot of an external device
 
189
 
 
190
  This is the same as creating a thin device.
 
191
  You don't mention the origin at this stage.
 
192
 
 
193
    dmsetup message /dev/mapper/pool 0 "create_thin 0"
 
194
 
 
195
ii) Using a snapshot of an external device.
 
196
 
 
197
  Append an extra parameter to the thin target specifying the origin:
 
198
 
 
199
    dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image"
 
200
 
 
201
  N.B. All descendants (internal snapshots) of this snapshot require the
 
202
  same extra origin parameter.
 
203
 
170
204
Deactivation
171
205
------------
172
206
 
189
223
              <low water mark (blocks)> [<number of feature args> [<arg>]*]
190
224
 
191
225
    Optional feature arguments:
192
 
    - 'skip_block_zeroing': skips the zeroing of newly-provisioned blocks.
 
226
 
 
227
      skip_block_zeroing: Skip the zeroing of newly-provisioned blocks.
 
228
 
 
229
      ignore_discard: Disable discard support.
 
230
 
 
231
      no_discard_passdown: Don't pass discards down to the underlying
 
232
                           data device, but just remove the mapping.
193
233
 
194
234
    Data block size must be between 64KB (128 sectors) and 1GB
195
235
    (2097152 sectors) inclusive.
237
277
 
238
278
        Deletes a thin device.  Irreversible.
239
279
 
240
 
    trim <dev id> <new size in sectors>
241
 
 
242
 
        Delete mappings from the end of a thin device.  Irreversible.
243
 
        You might want to use this if you're reducing the size of
244
 
        your thinly-provisioned device.  In many cases, due to the
245
 
        sharing of blocks between devices, it is not possible to
246
 
        determine in advance how much space 'trim' will release.  (In
247
 
        future a userspace tool might be able to perform this
248
 
        calculation.)
249
 
 
250
280
    set_transaction_id <current id> <new id>
251
281
 
252
282
        Userland volume managers, such as LVM, need a way to
257
287
        the current transaction id is when you change it with this
258
288
        compare-and-swap message.
259
289
 
 
290
    reserve_metadata_snap
 
291
 
 
292
        Reserve a copy of the data mapping btree for use by userland.
 
293
        This allows userland to inspect the mappings as they were when
 
294
        this message was executed.  Use the pool's status command to
 
295
        get the root block associated with the metadata snapshot.
 
296
 
 
297
    release_metadata_snap
 
298
 
 
299
        Release a previously reserved copy of the data mapping btree.
 
300
 
260
301
'thin' target
261
302
-------------
262
303
 
263
304
i) Constructor
264
305
 
265
 
    thin <pool dev> <dev id>
 
306
    thin <pool dev> <dev id> [<external origin dev>]
266
307
 
267
308
    pool dev:
268
309
        the thin-pool device, e.g. /dev/mapper/my_pool or 253:0
271
312
        the internal device identifier of the device to be
272
313
        activated.
273
314
 
 
315
    external origin dev:
 
316
        an optional block device outside the pool to be treated as a
 
317
        read-only snapshot origin: reads to unprovisioned areas of the
 
318
        thin target will be mapped to this device.
 
319
 
274
320
The pool doesn't store any size against the thin devices.  If you
275
321
load a thin target that is smaller than you've been using previously,
276
322
then you'll have no access to blocks mapped beyond the end.  If you