% resteasy(8) % Jakob Odersky % February 2020 # NAME resteasy \- plug and play backups with borg # SYNOPSIS **resteasy** `` `[]` # 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** `` : 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 # , 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 # 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/