Adding hosts¶
A host is a machine Backupkrake backs up. There are two kinds:
| Kind | Logs in as | Backs up | Typical use |
|---|---|---|---|
| Whole system | root |
absolute paths such as /etc, /home, /var |
your own servers, NAS, desktops |
| Home folder only | a normal user | paths inside that user's home folder | shared Unix systems, university logins, hosted shells |
The SSH keys¶
On first start Backupkrake creates three key pairs in config/ssh/:
| Key | File | Used for | Authorized on the client as |
|---|---|---|---|
| Backup key | id_ed25519 |
pulling backups, content checks | command="rrsync -ro /" (read only) |
| Restore key | id_ed25519_restore |
restores from the web UI (optional) | command="rrsync -wo /" (write only) |
| Offsite key | id_ed25519_offsite |
sftp: offsite repositories |
not on clients; see Offsite copies |
The Setup page shows the public keys and the ready-made authorized_keys lines.
rrsync is a small script that ships with rsync 3.2.4 and newer. Used as a forced command= in
authorized_keys, it allows nothing but rsync, in one direction (-ro read only, -wo write only), below one
directory. restrict additionally turns off port forwarding, agent forwarding and terminals. Even if
someone steals the backup key from the server, it can only read files from the client; it can't run
commands or change anything.
Separate keys mean the backup key never needs write access. Clients that you only back up, and never restore to through the UI, don't need the restore key at all.
Restricted or unrestricted key¶
Restricted (rrsync -ro) |
Unrestricted (plain key) | |
|---|---|---|
| Backups | ✓ | ✓ |
| Pre/post commands (database dumps, stopping containers) | ✗ | ✓ |
| What a stolen key can do | read files | everything root can |
Use the restricted line unless you need pre/post commands. You can tighten either variant further by
allowing it only from the backup server's address. Put from="192.168.1.5", at the start of the line:
from="192.168.1.5",command="rrsync -ro /",restrict ssh-ed25519 AAAA… backupkrake
Adding a whole-system host¶
1. Prepare the client¶
Install rsync:
apt install rsync # Debian / Ubuntu
dnf install rsync # Fedora / RHEL
pacman -S rsync # Arch
apk add rsync rrsync python3 # Alpine
Authorize the backup key for root. Copy the line from the Setup page; it looks like this:
mkdir -p /root/.ssh && chmod 700 /root/.ssh
echo 'command="rrsync -ro /",restrict ssh-ed25519 AAAA… backupkrake' >> /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys
Allow key logins for root in /etc/ssh/sshd_config, then reload sshd (systemctl reload ssh or sshd):
PermitRootLogin prohibit-password
prohibit-password allows keys only, never passwords.
Optional: to restore from the web UI, also add the restore key line from the Setup page:
command="rrsync -wo /",restrict ssh-ed25519 AAAA… backupkrake-restore
2. Add the host in the web UI¶
Hosts → Add host, choose Whole system, and fill in:
- Name: used as the snapshot folder name (
/data/hosts/<name>/). Letters, digits,.,_and-; it can't be changed later. - Address: hostname or IP address (IPv6 works too).
- SSH user:
root. - SSH port:
22, or whatever port sshd listens on. Nothing else is needed for a non-standard port.
The other sections are covered in Configuring backups. The defaults are a good start: paths
/etc /home /root /var /opt /srv /usr/local, caches and container storage excluded, a backup every night
at 02:00, and retention of 3 last, 7 daily, 4 weekly and 12 monthly snapshots.
3. Test the connection¶
On the host's page, click Test connection. It:
- connects with the backup key and lists
/with rsync, using the same ACL/xattr options as a real backup, and - checks with a harmless dry run whether the restore key is authorized too.
On first contact Backupkrake stores the client's SSH host key in config/ssh/known_hosts (trust on
first use). If the key changes later, connections are refused, because that may mean someone is
impersonating the client. After a legitimate reinstall, use Danger zone → Forget SSH host key on the
host's page.
The test page explains the common errors. More are in Troubleshooting.
4. Run the first backup¶
Click Back up now. The run page shows a live log and a progress bar. The first backup copies everything and can take hours for large hosts. Later ones only transfer what changed.
Adding a home-folder host¶
Use this for a machine where you only have a normal account. No root access is needed there.
- Add host and choose Home folder only. Enter your username. Paths are relative to your home
folder (
.= all of it,Documents= just that folder). Excludes are anchored at the home folder, e.g./.cache/. -
On that system, add this line to your
~/.ssh/authorized_keys(the form and the Setup page show the exact line):command="rrsync -ro .",restrict ssh-ed25519 AAAA… backupkrake.means your home folder, because ssh starts forced commands there. So the key can only read inside it. For restores, add the restore key withrrsync -wo .the same way. -
Test connection, then back up.
Notes:
- No
rrsyncthere? It's a Python script. Copy it to e.g.~/bin/rrsync(it needspython3) and use its full path incommand="…". - No Python either: use the plain key line. Relative paths still resolve in your home folder, but the key then has the same rights as your account.
- Permissions: sshd ignores
authorized_keysif~/.sshor the file is writable by others:chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys. - Rootless containers: Podman/Docker storage (
~/.local/share/containers/,~/.local/share/docker/) is excluded by default. Its files belong to container sub-UIDs your account can't read, and images can be pulled again. Back up important volumes explicitly, e.g. with a pre-commandpodman volume export(needs the plain key). - ACLs and extended attributes are off by default for these hosts, because many shared and non-Linux systems don't support them over rsync.
- Restores go to
~/.backupkrake-restore/…by default, inside your home folder where other users can't see them. - Be a good neighbour: respect the system's usage policy. A backup window and bandwidth limit keep the load low.
BSD, macOS and other Unix systems¶
Backupkrake only needs rsync and sshd on the client, so FreeBSD, NetBSD, OpenBSD and macOS work too.
- Install a current rsync from the system's package collection (
pkg install rsync,pkgin install rsync, Homebrew). macOS ships an oldopenrsyncthat doesn't understand all options. - If the package doesn't include
rrsync, copy the script from rsync's source tree (support/rrsync), make it executable, and use its full path in the key line. - Untick "Preserve ACLs and extended attributes". rsync builds without ACL support refuse the whole run. The connection test catches this, because it uses the same options.
- Root logins must be allowed for key authentication, as on Linux.
Editing and deleting hosts¶
Edit on a host's page changes all settings except the name. Changing the host kind (whole system ↔ home folder) changes the snapshot layout, so the next backup is a full copy.
Danger zone → Delete host removes the host and its schedule. Its snapshots stay in
/data/hosts/<name>/ unless you also tick also delete all snapshots. A running backup must be
cancelled first.
To rename a host, add a new one with the new name. You can move the old snapshot folder to the new name on the server's disk before the first backup, so that backup isn't a full copy:
docker compose stop
mv /srv/backups/hosts/oldname /srv/backups/hosts/newname
docker compose start
Pins and notes belong to the old host entry and are removed with it, so set them again on the new host.