Documentation/admin-guide/device-mapper/era.rst

   1 ======
   2 dm-era
   3 ======
   4
   5 Introduction
   6 ============
   7
   8 dm-era is a target that behaves similar to the linear target.  In
   9 addition it keeps track of which blocks were written within a user
  10 defined period of time called an 'era'.  Each era target instance
  11 maintains the current era as a monotonically increasing 32-bit
  12 counter.
  13
  14 Use cases include tracking changed blocks for backup software, and
  15 partially invalidating the contents of a cache to restore cache
  16 coherency after rolling back a vendor snapshot.
  17
  18 Constructor
  19 ===========
  20
  21 era <metadata dev> <origin dev> <block size>
  22
  23  ================ ======================================================
  24  metadata dev     fast device holding the persistent metadata
  25  origin dev       device holding data blocks that may change
  26  block size       block size of origin data device, granularity that is
  27                   tracked by the target
  28  ================ ======================================================
  29
  30 Messages
  31 ========
  32
  33 None of the dm messages take any arguments.
  34
  35 checkpoint
  36 ----------
  37
  38 Possibly move to a new era.  You shouldn't assume the era has
  39 incremented.  After sending this message, you should check the
  40 current era via the status line.
  41
  42 take_metadata_snap
  43 ------------------
  44
  45 Create a clone of the metadata, to allow a userland process to read it.
  46
  47 drop_metadata_snap
  48 ------------------
  49
  50 Drop the metadata snapshot.
  51
  52 Status
  53 ======
  54
  55 <metadata block size> <#used metadata blocks>/<#total metadata blocks>
  56 <current era> <held metadata root | '-'>
  57
  58 ========================= ==============================================
  59 metadata block size       Fixed block size for each metadata block in
  60                           sectors
  61 #used metadata blocks     Number of metadata blocks used
  62 #total metadata blocks    Total number of metadata blocks
  63 current era               The current era
  64 held metadata root        The location, in blocks, of the metadata root
  65                           that has been 'held' for userspace read
  66                           access. '-' indicates there is no held root
  67 ========================= ==============================================
  68
  69 Detailed use case
  70 =================
  71
  72 The scenario of invalidating a cache when rolling back a vendor
  73 snapshot was the primary use case when developing this target:
  74
  75 Taking a vendor snapshot
  76 ------------------------
  77
  78 - Send a checkpoint message to the era target
  79 - Make a note of the current era in its status line
  80 - Take vendor snapshot (the era and snapshot should be forever
  81   associated now).
  82
  83 Rolling back to an vendor snapshot
  84 ----------------------------------
  85
  86 - Cache enters passthrough mode (see: dm-cache's docs in cache.txt)
  87 - Rollback vendor storage
  88 - Take metadata snapshot
  89 - Ascertain which blocks have been written since the snapshot was taken
  90   by checking each block's era
  91 - Invalidate those blocks in the caching software
  92 - Cache returns to writeback/writethrough mode
  93
  94 Memory usage
  95 ============
  96
  97 The target uses a bitset to record writes in the current era.  It also
  98 has a spare bitset ready for switching over to a new era.  Other than
  99 that it uses a few 4k blocks for updating metadata::
 100
 101    (4 * nr_blocks) bytes + buffers
 102
 103 Resilience
 104 ==========
 105
 106 Metadata is updated on disk before a write to a previously unwritten
 107 block is performed.  As such dm-era should not be effected by a hard
 108 crash such as power failure.
 109
 110 Userland tools
 111 ==============
 112
 113 Userland tools are found in the increasingly poorly named
 114 thin-provisioning-tools project:
 115
 116     https://github.com/jthornber/thin-provisioning-tools