1 files changed, 186 insertions, 0 deletions
diff --git a/resteasy.8.md b/resteasy.8.md
new file mode 100644
index 0000000..94ed5aa
--- /dev/null
+++ b/resteasy.8.md
@@ -0,0 +1,186 @@
+% resteasy(8)
+% Jakob Odersky <jakob@odersky.com>
+% February 2020
+
+# NAME
+
+resteasy \- plug and play backups with borg
+
+# SYNOPSIS
+
+**resteasy** `<command>` `[<args>]`
+
+# DESCRIPTION
+
+Resteasy is a set of commands and services around Borg Backup. It provides a
+system for automating backups to external hard drives without user interaction.
+
+The idea is that a user simply plugs in a prepared drive, and a backup is
+automatically started.
+
+Note that although resteasy supports backing up the same system to many prepared
+drives, only one may be connected at a time. This is because resteasy is geared
+towards simple command invocation and hence always mounts drives to a hardcoded
+location. No data loss will occur if multiple drives are connected at the same
+time (and any currently running backups will not be interrupted), however many
+resteasy commands will not work until only one compatible drive is connected.
+
+## Internals
+
+Resteasy works with GPT-formatted (GUID Partition Table) drives. When a block
+device with a partition type of 8e8e0bae-5627-4acd-8fd9-70873806d42e is
+detected, it is mounted and a backup is created using borg.
+
+Resteasy is implemented as a set of many individual commands (see [RESTEASY
+COMMANDS](#RESTEASY-COMMANDS) section). Their implementation structure is
+heavily inspired by Git.
+
+See also the output of **systemctl cat resteasy.service** for a list of commands
+the automatic backup service runs, and **/usr/libexec/resteasy/** for their
+implementations.
+
+## Security Considerations
+
+Automatically mounting and executing a backup when a drive is connected has
+security implications. An attacker could simply insert a resteasy drive to
+exfiltrate all data. Note however that this vector is mitigated because:
+
+1. Resteasy uses encrypted borg repositories.
+2. Physical access is required for this attack.
+3. Someone with physical access could do something much more nefarious, for
+   example steal the machine.
+
+# OPTIONS
+
+**--exec-path** 
+: Path to wherever your core resteasy programs are installed. This will print
+the current setting and then exit.
+
+# RESTEASY COMMANDS
+
+Resteasy is divided into high level ("porcelain") commands and low level
+("plumbing") commands.
+
+# HIGH-LEVEL COMMANDS
+
+**resteasy-inhibit**
+
+: Pause the automatic backup service temporarily, until **resteasy-uninhibit** is
+called or the system is rebooted. Note that this will also stop any backups that
+are in progress.
+
+**resteasy-init**
+
+: Initialize a borg repository. The drive containing the repository should have
+previously been mounted with **resteasy-mount**.
+
+**resteasy-mount** `[ro]`
+
+: Find and mount a connected resteasy drive. Resteasy drives are GPT partitions
+identified by type UUID `8e8e0bae-5627-4acd-8fd9-70873806d42e`.
+
+**resteasy-prepare-drive** `<drive>`
+
+:   Prepare a drive to be recognized by the resteasy system.
+
+    Once prepared, drives will trigger automatic mounts and backups. It is hence
+    recommended that the autobackup service be inhibited before running this
+    operation (otherwise a backup will be attempted on an uninitialized repo,
+    causing an error to be reported). **Note that this operation reformats the
+    drive.**
+
+**resteasy-umount**
+
+: Unmount a previously mounted resteasy drive.
+
+**resteasy-uninhibit**
+
+: Resume the automatic backup service. Note that this will NOT start new backup
+runs; any connected resteasy drives must be disconnected and reconnected to
+start a new backup.
+
+# LOW-LEVEL COMMANDS
+
+**resteasy-find-uuid**
+
+: Find the GPT partition UUID of a connected resteasy drive. Note that exactly
+one resteasy drive mamusty be connected to the system. This command will fail if
+it detects more than one.
+
+**resteasy-run-backup**
+
+: Trigger a backup. Note that this is typically not run by the user but by the
+init system when a resteasy drive is connected. It requires that a drive be
+mounted with **resteasy-mount** beforehand.
+
+# FILES
+
+/etc/resteasy
+
+: Contains the passphrase used by borg to encrypt backups. Trailing new lines
+are stripped.
+
+# EXAMPLES
+
+## Prepare a New Drive
+
+```
+# temporarily stop the automatic backup service
+resteasy inhibit
+
+# <connect drive>, assumed /dev/sdc in this example
+
+# set the passphrase for encrypting resteasy backups
+echo "1234" > /etc/resteasy
+
+# wipe and prepare the new drive to be recognized by resteasy
+resteasy prepare-drive /dev/sdc
+
+# initialize new borg repo
+resteasy mount
+resteasy init
+resteasy umount
+
+# re-enable automatic backup service
+resteasy uninhibit
+```
+
+## Create a Backup
+
+Simply plug in the drive!
+
+You can watch backup logs by running:
+
+```
+journalctl -u resteasy.service -f
+```
+
+Unplug drive when done.
+
+## Create a Backup Manually
+  
+```
+resteasy mount
+resteasy run-backup
+resteasy umount
+```
+
+## Restore Data
+
+```
+resteasy inhibit
+# <connect resteasy drive>
+resteasy mount ro
+
+# perform restore operations
+# e.g. borg mount /run/resteasy/mounts/... /mnt
+# borg extract...
+# ...
+
+resteasy umount
+resteasy uninhibit
+```
+
+# SEE ALSO
+
+Borg Backup https://borgbackup.readthedocs.io/en/stable/