1dm_bow (backup on write) 2======================== 3 4dm_bow is a device mapper driver that uses the free space on a device to back up 5data that is overwritten. The changes can then be committed by a simple state 6change, or rolled back by removing the dm_bow device and running a command line 7utility over the underlying device. 8 9dm_bow has three states, set by writing ‘1’ or ‘2’ to /sys/block/dm-?/bow/state. 10It is only possible to go from state 0 (initial state) to state 1, and then from 11state 1 to state 2. 12 13State 0: dm_bow collects all trims to the device and assumes that these mark 14free space on the overlying file system that can be safely used. Typically the 15mount code would create the dm_bow device, mount the file system, call the 16FITRIM ioctl on the file system then switch to state 1. These trims are not 17propagated to the underlying device. 18 19State 1: All writes to the device cause the underlying data to be backed up to 20the free (trimmed) area as needed in such a way as they can be restored. 21However, the writes, with one exception, then happen exactly as they would 22without dm_bow, so the device is always in a good final state. The exception is 23that sector 0 is used to keep a log of the latest changes, both to indicate that 24we are in this state and to allow rollback. See below for all details. If there 25isn't enough free space, writes are failed with -ENOSPC. 26 27State 2: The transition to state 2 triggers replacing the special sector 0 with 28the normal sector 0, and the freeing of all state information. dm_bow then 29becomes a pass-through driver, allowing the device to continue to be used with 30minimal performance impact. 31 32Usage 33===== 34dm-bow takes one command line parameter, the name of the underlying device. 35 36dm-bow will typically be used in the following way. dm-bow will be loaded with a 37suitable underlying device and the resultant device will be mounted. A file 38system trim will be issued via the FITRIM ioctl, then the device will be 39switched to state 1. The file system will now be used as normal. At some point, 40the changes can either be committed by switching to state 2, or rolled back by 41unmounting the file system, removing the dm-bow device and running the command 42line utility. Note that rebooting the device will be equivalent to unmounting 43and removing, but the command line utility must still be run 44 45Details of operation in state 1 46=============================== 47 48dm_bow maintains a type for all sectors. A sector can be any of: 49 50SECTOR0 51SECTOR0_CURRENT 52UNCHANGED 53FREE 54CHANGED 55BACKUP 56 57SECTOR0 is the first sector on the device, and is used to hold the log of 58changes. This is the one exception. 59 60SECTOR0_CURRENT is a sector picked from the FREE sectors, and is where reads and 61writes from the true sector zero are redirected to. Note that like any backup 62sector, if the sector is written to directly, it must be moved again. 63 64UNCHANGED means that the sector has not been changed since we entered state 1. 65Thus if it is written to or trimmed, the contents must first be backed up. 66 67FREE means that the sector was trimmed in state 0 and has not yet been written 68to or used for backup. On being written to, a FREE sector is changed to CHANGED. 69 70CHANGED means that the sector has been modified, and can be further modified 71without further backup. 72 73BACKUP means that this is a free sector being used as a backup. On being written 74to, the contents must first be backed up again. 75 76All backup operations are logged to the first sector. The log sector has the 77format: 78-------------------------------------------------------- 79| Magic | Count | Sequence | Log entry | Log entry | … 80-------------------------------------------------------- 81 82Magic is a magic number. Count is the number of log entries. Sequence is 0 83initially. A log entry is 84 85----------------------------------- 86| Source | Dest | Size | Checksum | 87----------------------------------- 88 89When SECTOR0 is full, the log sector is backed up and another empty log sector 90created with sequence number one higher. The first entry in any log entry with 91sequence > 0 therefore must be the log of the backing up of the previous log 92sector. Note that sequence is not strictly needed, but is a useful sanity check 93and potentially limits the time spent trying to restore a corrupted snapshot. 94 95On entering state 1, dm_bow has a list of free sectors. All other sectors are 96unchanged. Sector0_current is selected from the free sectors and the contents of 97sector 0 are copied there. The sector 0 is backed up, which triggers the first 98log entry to be written. 99 100