src/ceph/doc/dev/rbd-diff.rst

   1 RBD Incremental Backup
   2 ======================
   3
   4 This is a simple streaming file format for representing a diff between
   5 two snapshots (or a snapshot and the head) of an RBD image.
   6
   7 Header
   8 ~~~~~~
   9
  10 "rbd diff v1\\n"
  11
  12 Metadata records
  13 ~~~~~~~~~~~~~~~~
  14
  15 Every record has a one byte "tag" that identifies the record type,
  16 followed by some other data.
  17
  18 Metadata records come in the first part of the image.  Order is not
  19 important, as long as all the metadata records come before the data
  20 records.
  21
  22 From snap
  23 ---------
  24
  25 - u8: 'f'
  26 - le32: snap name length
  27 - snap name
  28
  29 To snap
  30 -------
  31
  32 - u8: 't'
  33 - le32: snap name length
  34 - snap name
  35
  36 Size
  37 ----
  38
  39 - u8: 's'
  40 - le64: (ending) image size
  41
  42 Data Records
  43 ~~~~~~~~~~~~
  44
  45 These records come in the second part of the sequence.
  46
  47 Updated data
  48 ------------
  49
  50 - u8: 'w'
  51 - le64: offset
  52 - le64: length
  53 - length bytes of actual data
  54
  55 Zero data
  56 ---------
  57
  58 - u8: 'z'
  59 - le64: offset
  60 - le64: length
  61
  62
  63 Final Record
  64 ~~~~~~~~~~~~
  65
  66 End
  67 ---
  68
  69 - u8: 'e'
  70
  71
  72 Header
  73 ~~~~~~
  74
  75 "rbd diff v2\\n"
  76
  77 Metadata records
  78 ~~~~~~~~~~~~~~~~
  79
  80 Every record has a one byte "tag" that identifies the record type,
  81 followed by length of data, and then some other data.
  82
  83 Metadata records come in the first part of the image.  Order is not
  84 important, as long as all the metadata records come before the data
  85 records.
  86
  87 In v2, we have the following metadata in each section:
  88 (1 Bytes) tag.
  89 (8 Bytes) length.
  90 (n Bytes) data.
  91
  92 In this way, we can skip the unrecognized tag.
  93
  94 From snap
  95 ---------
  96
  97 - u8: 'f'
  98 - le64: length of appending data (4 + length)
  99 - le32: snap name length
 100 - snap name
 101
 102 To snap
 103 -------
 104
 105 - u8: 't'
 106 - le64: length of appending data (4 + length)
 107 - le32: snap name length
 108 - snap name
 109
 110 Size
 111 ----
 112
 113 - u8: 's'
 114 - le64: length of appending data (8)
 115 - le64: (ending) image size
 116
 117 Data Records
 118 ~~~~~~~~~~~~
 119
 120 These records come in the second part of the sequence.
 121
 122 Updated data
 123 ------------
 124
 125 - u8: 'w'
 126 - le64: length of appending data (8 + 8 + length)
 127 - le64: offset
 128 - le64: length
 129 - length bytes of actual data
 130
 131 Zero data
 132 ---------
 133
 134 - u8: 'z'
 135 - le64: length of appending data (8 + 8)
 136 - le64: offset
 137 - le64: length
 138
 139
 140 Final Record
 141 ~~~~~~~~~~~~
 142
 143 End
 144 ---
 145
 146 - u8: 'e'