add brief description of disaster recovery

diff --git a/docs/recovery.rst b/docs/recovery.rst
new file mode 100644 (file)
index 0000000..f05283e
--- /dev/null
+++ b/docs/recovery.rst
@@ -0,0 +1,37 @@
+The “disaster recovery” mode serves as a blunt instrument to retrieve data
+from damaged backup sets.
+
+In itself, the mechanism is not very sophisticated. It operates by ignoring
+errors in the various validations performed on the individual layers: e. g. the
+GCM tag, the gzip CRC32, tar header checksums. Recovery requires a valid index
+file to access objects in the tarballs directly by their offsets instead of
+iterating contents in a linear fashion. Should extraction of an object fail,
+Deltatar will skip ahead to the next one. The assumption is always that the
+offsets of objects in the corrupted archive did not move.
+
+On the command line, recovery mode is entered by passing the parameter
+``--recover``. Deltatar will then require that an index be specified as well.
+Apart from that, the invocation is the same as with ``--restore``.
+
+::
+    $ python3 backup.py --recover --mode '#gz' --targetpath     \
+            /tmp/corrupt/out --indexes                          \
+            /tmp/corrupt/in/bfull-2017-08-14-1441.index.gz
+
+After extraction is complete, Deltatar will emit a list of the files whose
+corruption was detected. Note that some corruptions may go undetected without
+GCM encryption. Plaintext, uncompressed tarballs are especially susceptible
+since only the object headers are checksummed.
+
+Depending on which part of an object the corruption affected the results can
+be quite damaging, especially if compression is involved. Garbled output may
+look like this:
+
+    6876REF,06875) VPNCONN_XAUTH_SER2ER_EN72:"72.1"ad
+    6877REF,06875) VPNCONN_SECUR")
+    C42"ESP"
+    6878REF,06875) VPNCONN_RETRIES72.1"3d
+    6879REF,06875) VPNCONN_REMOTE_TYPE72.1"CUSTOMd
+
+Needless to say, care must be taken to inspect the files reported damaged.
+