path: root/resteasy.8.md

% 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/