README

   1 dm-merge
   2 --------
   3
   4 dm-merge is a simple tool to apply changes recorded in a copy-on-write
   5 exception table. It can be effectively used to either "commit" the changes into
   6 the source (as made with simple snapshot target) or "rollback" (reverting to a
   7 state the snapshot was created; as made with snapshot linked to snapshot-origin
   8 target). And while LVM snapshots are simply (maybe not so simply, actually) the
   9 latter case, it can revert a logical volume to the exact state it was when the
  10 snapshot was taken.
  11
  12 dm-merge simply reads an exception table and applies the changes back to the
  13 source
  14
  15 It can be thought of as a C port of Lars Ellenberg's 'list_exception_chunks'
  16 perl script [1]. I liked the idea very much.
  17
  18
  19
  20 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  21
  22 Disclaimer: be warned: the tool was only tested on X86 and X86_64 little endian
  23 machines! It is still experimental. Use at _your_ _own_ risk! Before using it,
  24 you should understand how device-mapper, LVM and snapshots work.
  25
  26 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  27
  28
  29
  30 1. Usage
  31 --------
  32
  33 dm-merge [options] -i <snapshot_device> [ -o <output_device> ]
  34
  35 Options:
  36 -f              REALLY do it (no dry run)
  37 -d              Print dd lines as list_exception_chunks.pl would
  38 -D              Try to use O_DIRECT
  39 -v              Be verbose (more '-v's increase verbosity)
  40 -i <file>       Input (snapshot) COW (copy-on-write) filename
  41 -o <file>       Output (the device being snapshoted) filename
  42
  43
  44
  45 2. Scenarios
  46 ------------
  47
  48 2.1 Reverting (LVM) snapshot
  49 ----------------------------
  50
  51 Suppose you have a logical volume ${lv} in a virtual group ${vg} and a snapshot
  52 ${sn} of ${lv} made by something like:
  53
  54     lvcreate -L ${some_size} -n ${sn} ${vg}/${lv}
  55
  56 As long as ${sn} isn't full it will behave like ${lv} at the time the snapshot
  57 was taken.
  58
  59 Now you make some changes to ${lv} and realize you'd like to revert to the
  60 state of ${sn}. This is when dm-merge comes into play.
  61
  62 With dm-merge you have basically two options:
  63
  64 1) make the changes while ${lv} is "inactive" (recommended)
  65
  66 2) keep ${lv} "active" and attempt the changes (for the adventurous)
  67
  68
  69 2.1.1 dm-merge and inactive ${lv}
  70 ---------------------------------
  71
  72
  73 1) Duplicate the tables of ${lv} and snapshot storage:
  74
  75     dmsetup ${vg}-${lv}-real | dmsetup create tmp_lv
  76     dmsetup ${vg}-${sn}-cow | dmsetup create tmp_cow
  77
  78 2) Deactivate the LV (the mappings will disappear, that's why we duplicate the
  79 tables):
  80
  81     lvchange -a n ${vg}/${lv}
  82
  83 3) Flush buffers (better safe than sorry):
  84
  85     blockdev --flushbufs /dev/mapper/{tmp_lv,tmp_cow}
  86
  87 4) Make sure nothing else touches the data (it should _not_ be mounted!):
  88
  89     ...
  90
  91 5) First (purely informative; non-destructive) dm-merge run. See if the numbers
  92 look reasonable...
  93
  94     dm-merge -i /dev/mapper/tmp_cow -o /dev/mapper/tmp_lv -vd
  95
  96 6) If everything seems OK, do it:
  97
  98     dm-merge -i /dev/mapper/tmp_cow -o /dev/mapper/tmp_lv -f
  99
 100 7) Flush buffers (better safe than sorry):
 101
 102     blockdev --flushbufs /dev/mapper/{tmp_lv,tmp_cow}
 103
 104 8) Now it should be done. You may remove the temporary mapping then:
 105
 106     dmsetup remove tmp_lv
 107     dmsetup remove tmp_cow
 108
 109 9) The original snapshot may not be necessary anymore (it will show the same
 110 data as the ${lv} now), so you can remove it:
 111
 112     lvremove ${vg}/${sn}
 113
 114 10) Activate the LV again:
 115
 116     lvchange -a y ${vg}/${lv}
 117
 118
 119
 120 2.1.2 dm-merge and active ${lv}
 121 -------------------------------
 122
 123 1) Make sure nothing else touches the data (it should _not_ be mounted!);
 124 perhaps "dmsetup suspend" could help a little...:
 125
 126     ...
 127
 128 2) Flush buffers (better safe than sorry):
 129
 130     blockdev --flushbufs /dev/mapper/${vg}-${sn}* /dev/mapper/${vg}-${lv}*
 131
 132 3) First (purely informative; non-destructive) dm-merge run. See if the numbers
 133 look reasonable...
 134
 135     dm-merge -i /dev/mapper/${vg}-${sn}-cow -o /dev/mapper/${vg}-${lv}-real -vd
 136
 137 4) If everything seems OK, do it:
 138
 139     dm-merge -i /dev/mapper/${vg}-${sn}-cow -o /dev/mapper/${vg}-${lv}-real -f
 140
 141 5) Flush buffers (better safe than sorry):
 142
 143     blockdev --flushbufs /dev/mapper/${vg}-${sn}* /dev/mapper/${vg}-${lv}*
 144
 145 6) The original snapshot may not be necessary anymore (it will show the same
 146 data as the LV now, so you can remove it):
 147
 148     lvremove ${vg}/${sn}
 149
 150
 151
 152 2.2 Applying a copy-on-write back to the source ("commit")
 153 ----------------------------------------------------------
 154
 155 With device mapper and the "snapshot" target (dm-snapshot != LVM snapshot [2]),
 156 you can simply create a mapping that "redirects" all writes to a different
 157 device so the source stays intact. So when not changed, data is read from the
 158 source device; when changed, it is read from a special device (exception
 159 table).
 160
 161 So you have some data mapping ${data}, a COW storage ${cow_s} and a dm-snapshot
 162 mapping ${sn} [3] created with something like:
 163
 164     echo "0 $(blockdev --getsize /path/to/${data}) snapshot /path/to/${data} /path/to/${cow_s} P 8" | dmsetup create ${sn}
 165
 166 Now all writes made to /dev/mapper/${sn} go to /path/to/${cow_s}.
 167
 168 Imagine you are testing a program inside ${sn}. After testing you'd like to
 169 apply the changes made in ${sn} back into ${data}.
 170
 171 Here comes dm-merge.
 172
 173 1) Make sure nothing else touches the data (it should _not_ be mounted!) ...
 174
 175     ...
 176
 177 2) Flush buffers (better safe than sorry):
 178
 179     blockdev --flushbufs /path/to/${data} /path/to/${cow_s} /dev/mapper/${sn}
 180
 181 3) First (purely informative; non-destructive) dm-merge run. See if the numbers
 182 look reasonable...
 183
 184     dm-merge -i /path/to/${cow_s} -o /path/to/${data} -vd
 185
 186 4) If everything seems OK, do it:
 187
 188     dm-merge -i /path/to/${cow_s} -o /path/to/${data} -f
 189
 190 5) Flush buffers (better safe than sorry):
 191
 192     blockdev --flushbufs /path/to/${data} /path/to/${cow_s} /dev/mapper/${sn}
 193
 194
 195
 196
 197 -----
 198
 199 [1] http://article.gmane.org/gmane.linux.lvm.general/9899
 200
 201 [2] LVM snapshots need "snapshot" and "snapshot-origin" dm targets to
 202 accomplish the goal.
 203
 204 [3] Neither ${data} nor ${cow_s} has to be a device-mapper device (for the
 205 simplest case). But if you want to do some clever tricks (such as table
 206 changing so ${sn} takes place of ${data}; as shown at
 207 http://linuxgazette.net/114/kapil.html), you'd need them to be.
 208
 209