--- title: "How to Set Up Append-Only Borg Backups on Ubuntu 24.04" description: "Set up BorgBackup on Ubuntu 24.04 with a remote SSH repository in append-only mode, tuned compression, a systemd timer, safe pruning and tested restores." category: "Server Tools" language: en source: https://cubepath.com/docs/server-tools/borgbackup-advanced-strategies updated: 2026-09-25 --- # How to Set Up Append-Only Borg Backups on Ubuntu 24.04 BorgBackup (Borg) is a deduplicating backup program with authenticated encryption and configurable compression. It stores backups in a repository that can live on a remote server reached over SSH, where a restricted `borg serve` process accepts the data. In this tutorial you will back up an Ubuntu 24.04 server to a dedicated backup server using an **append-only** SSH key, so that an attacker who takes over the client cannot delete its backups. You will then automate the job with systemd, prune old archives safely from a trusted machine and test a restore. ## Prerequisites To follow this tutorial you need: - A **client**: the Ubuntu 24.04 server you want to back up, with a non-root user with `sudo` privileges. - A **backup server**: a second Ubuntu 24.04 machine with enough disk space, for example a CubePath VPS in another location, reachable over SSH as `backup.your_domain`. - An **admin machine** you trust, such as your workstation, with Borg installed. It will be the only place allowed to delete archives. Borg must be installed on both ends of an SSH connection, ideally in the same major version. Ubuntu 24.04 ships Borg 1.2, and the commands in this guide use Borg 1.x syntax. ## Step 1 - Installing Borg on the client and the backup server Run on both machines: ```bash sudo apt update sudo apt install borgbackup borg --version ``` ```output borg 1.2.8 ``` ## Step 2 - Preparing the backup server Create a dedicated user that owns all repositories. It needs a home directory for its SSH keys but will never log in with a shell: ```bash sudo useradd --system --create-home --home-dir /srv/borg --shell /bin/bash borg sudo install -d -o borg -g borg -m 0700 /srv/borg/.ssh sudo install -o borg -g borg -m 0600 /dev/null /srv/borg/.ssh/authorized_keys ``` The account keeps a shell because `sshd` runs the forced `borg serve` command through it. Every key you add will be restricted to that single command, so the shell is never reachable interactively. ## Step 3 - Creating a restricted SSH key for the client On the **client**, generate a key used only for backups. It has no passphrase because the timer runs unattended: ```bash sudo ssh-keygen -t ed25519 -N "" -C "borg@$(hostname)" -f /root/.ssh/borg_ed25519 sudo cat /root/.ssh/borg_ed25519.pub ``` On the **backup server**, add that public key to `/srv/borg/.ssh/authorized_keys`, prefixed with a forced command. Replace `web01` with the client's host name and paste the real key: ```bash sudo nano /srv/borg/.ssh/authorized_keys ``` ```text command="borg serve --append-only --restrict-to-path /srv/borg/web01",restrict ssh-ed25519 AAAAC3Nza...your_client_key borg@web01 ``` Each part matters: - `command="borg serve ..."` ignores whatever the client asks to run and always starts the Borg server. - `--append-only` makes the repository accept new data only. Deletions and prunes from this key are recorded in the transaction log but no data is ever removed. - `--restrict-to-path` confines the key to this client's repository, so one compromised client cannot read or touch another's backups. - `restrict` disables port forwarding, agent forwarding and TTY allocation. Back on the **client**, record the backup server's host key. Compare the fingerprint that `ssh-keyscan` prints with the one shown by `sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` on the backup server: ```bash ssh-keyscan -t ed25519 backup.your_domain | sudo tee -a /root/.ssh/known_hosts ``` ## Step 4 - Configuring and initializing the repository Keep the repository location, SSH options and passphrase in a root-only environment file that both your shell and systemd can load. Generate the repository passphrase: ```bash sudo install -d -m 0700 /etc/borg sudo sh -c 'openssl rand -base64 32 > /etc/borg/passphrase' sudo chmod 600 /etc/borg/passphrase ``` Create the environment file: ```bash sudo nano /etc/borg/borg.env ``` ```ini BORG_REPO="ssh://borg@backup.your_domain/srv/borg/web01" BORG_PASSCOMMAND="cat /etc/borg/passphrase" BORG_RSH="ssh -i /root/.ssh/borg_ed25519 -o ServerAliveInterval=60 -o ServerAliveCountMax=10" ``` `BORG_PASSCOMMAND` reads the passphrase from the file only when Borg needs it, instead of keeping it in an environment variable. The `ServerAlive` options keep long-running backups from being dropped by idle-connection timeouts. ```bash sudo chmod 600 /etc/borg/borg.env ``` Open a root shell and load the settings. The remaining client commands assume this shell: ```bash sudo -i set -a; source /etc/borg/borg.env; set +a ``` Initialize the repository with `repokey-blake2` encryption, which stores the encrypted key inside the repository and uses the fast BLAKE2b hash: ```bash borg init --encryption=repokey-blake2 ``` Borg prints no output on success. Confirm the repository exists: ```bash borg info ``` ```output Repository ID: 5c3e... Location: ssh://borg@backup.your_domain/srv/borg/web01 Encrypted: Yes (repokey BLAKE2b) ... ``` Export the key and keep it, together with the passphrase, somewhere outside both servers, such as your password manager: ```bash borg key export "$BORG_REPO" /root/borg-web01.key cat /root/borg-web01.key ``` > Warning: You need both the key and the passphrase to read your backups. If the repository's copy of the key is damaged and you have no export, the data is lost. ## Step 5 - Choosing a compression setting Borg compresses each chunk before encrypting it. The right algorithm depends on your data and CPU: | Setting | Speed | Ratio | Good for | | --- | --- | --- | --- | | `lz4` | Very fast | Low | Default in Borg 1.2; busy servers with little CPU to spare | | `zstd,3` | Fast | Good | Most servers: text, configs, database dumps | | `zstd,10` | Moderate | Better | Small uplinks where transfer time dominates | | `auto,zstd,6` | Varies | Good | Mixed data; skips already-compressed files such as JPEG or zip | | `lzma,6` | Slow | High | Cold archives where time does not matter | `auto,...` runs a quick test on each chunk and stores incompressible data without compression, which saves CPU on media files. This guide uses `auto,zstd,6`. Compression only applies to newly written chunks, so you can change it at any time without affecting existing archives. ## Step 6 - Writing the backup script A short script is the right tool here, because Borg uses exit code `1` for warnings (for example, a file changed while it was being read), which should not mark the job as failed. The script treats only real errors (code `2` and above) as failures. ```bash nano /usr/local/sbin/borg-backup ``` ```bash #!/usr/bin/env bash set -euo pipefail # Paths to back up; adjust to your server paths=(/etc /home /root /opt /var/www /var/backups) rc=0 borg create \ --stats --show-rc \ --compression auto,zstd,6 \ --one-file-system \ --exclude-caches \ --exclude '/home/*/.cache' \ --exclude '/root/.cache' \ --exclude 'sh:**/node_modules' \ "::{hostname}-{now:%Y-%m-%dT%H:%M:%S}" \ "${paths[@]}" || rc=$? if (( rc > 1 )); then echo "borg create failed with exit code ${rc}" >&2 exit "${rc}" fi exit 0 ``` The archive name `::{hostname}-{now:...}` uses the repository from `BORG_REPO` and Borg's own placeholders, so each archive is named like `web01-2026-09-25T03:00:00`. `--exclude-caches` skips directories that contain a `CACHEDIR.TAG` file, and `--one-file-system` keeps Borg out of other mounts. Make it executable and run it once: ```bash chmod 700 /usr/local/sbin/borg-backup /usr/local/sbin/borg-backup ``` ```output ------------------------------------------------------------------------------ Repository: ssh://borg@backup.your_domain/srv/borg/web01 Archive name: web01-2026-09-25T10:42:17 Number of files: 51023 Original size Compressed size Deduplicated size This archive: 1.72 GB 702.14 MB 688.90 MB ------------------------------------------------------------------------------ terminating with success status, rc 0 ``` > Note: Borg copies files, not running databases. Dump MySQL or PostgreSQL to `/var/backups` (with `mysqldump` or `pg_dump`) before the backup runs so the archive contains a consistent copy. ## Step 7 - Scheduling backups with systemd Create a oneshot service that loads the environment file and runs the script at low priority: ```bash nano /etc/systemd/system/borg-backup.service ``` ```ini [Unit] Description=BorgBackup to backup.your_domain Wants=network-online.target After=network-online.target [Service] Type=oneshot EnvironmentFile=/etc/borg/borg.env Environment=BORG_CACHE_DIR=/var/cache/borg CacheDirectory=borg Nice=10 IOSchedulingClass=idle ExecStart=/usr/local/sbin/borg-backup ``` `BORG_CACHE_DIR` points Borg's local chunk cache at `/var/cache/borg`, which systemd creates through `CacheDirectory`. Keeping the cache between runs is what makes incremental backups fast. Create the timer: ```bash nano /etc/systemd/system/borg-backup.timer ``` ```ini [Unit] Description=Daily BorgBackup [Timer] OnCalendar=*-*-* 02:00:00 RandomizedDelaySec=30min Persistent=true [Install] WantedBy=timers.target ``` Enable the timer and test the service: ```bash systemctl daemon-reload systemctl enable --now borg-backup.timer systemctl start borg-backup.service journalctl -u borg-backup.service -n 15 --no-pager ``` ```output borg-backup[31022]: terminating with success status, rc 0 systemd[1]: borg-backup.service: Deactivated successfully. ``` The first run through systemd rebuilds the cache in its new location, so it takes a little longer. Check the next run with `systemctl list-timers borg-backup.timer`. ## Step 8 - Pruning archives from a trusted machine The client's key is append-only, so any prune it runs frees no space. Retention is applied from your admin machine with a second key that has full access. On the **admin machine**, generate a key and show it: ```bash ssh-keygen -t ed25519 -f ~/.ssh/borg_admin -C "borg-admin" cat ~/.ssh/borg_admin.pub ``` On the **backup server**, add it to `/srv/borg/.ssh/authorized_keys` without `--append-only`: ```text command="borg serve --restrict-to-path /srv/borg",restrict ssh-ed25519 AAAAC3Nza...your_admin_key borg-admin ``` From the **admin machine**, preview what the retention policy would delete. Borg asks for the repository passphrase, which you paste from your password manager, so it is never stored anywhere else: ```bash export BORG_RSH="ssh -i ~/.ssh/borg_admin" REPO=ssh://borg@backup.your_domain/srv/borg/web01 borg list "$REPO" borg prune --dry-run --list --glob-archives 'web01-*' \ --keep-daily 7 --keep-weekly 4 --keep-monthly 12 "$REPO" ``` Before deleting anything, look at the archive list. If archives you expected are missing, or unexpected deletions appear, the client may have been compromised; investigate before pruning, because the append-only log is still able to roll back such changes. When the list looks right, prune and then compact. In Borg 1.2, `prune` only marks data as deleted, and `compact` actually frees the disk space: ```bash borg prune --list --glob-archives 'web01-*' \ --keep-daily 7 --keep-weekly 4 --keep-monthly 12 "$REPO" borg compact "$REPO" ``` Run this weekly or monthly, depending on how fast the repository grows. Check free space on the backup server with `df -h /srv/borg`. ## Step 9 - Verifying and restoring Check the repository's consistency from the client. A plain check is safe with the append-only key because it does not modify anything: ```bash borg check --show-rc ``` ```output terminating with success status, rc 0 ``` Once a month, add `--verify-data` to decrypt and verify every chunk. It reads the whole repository, so schedule it outside peak hours. To restore, list the archives and pick one: ```bash borg list ``` ```output web01-2026-09-24T02:14:51 Thu, 2026-09-24 02:14:52 [3a9f...] web01-2026-09-25T02:08:03 Fri, 2026-09-25 02:08:04 [8c21...] ``` `borg extract` writes into the current directory, so always change to an empty directory first. Restore `/etc/nginx` from the latest archive and compare it with the live copy (paths inside archives have no leading slash): ```bash mkdir -p /tmp/restore && cd /tmp/restore borg extract --list ::web01-2026-09-25T02:08:03 etc/nginx diff -r /etc/nginx /tmp/restore/etc/nginx && echo "identical" ``` ```output identical ``` For a full recovery, install Borg on a fresh server, recreate `/etc/borg/borg.env`, the passphrase file and an authorized SSH key, then extract the archive from `/`. ## Troubleshooting **`Failed to create/acquire the lock`.** A previous run was interrupted. Confirm no Borg process is running on either machine (`pgrep -a borg`), then run `borg break-lock`. **`Repository path not allowed`.** The path in `BORG_REPO` does not match `--restrict-to-path` in `authorized_keys`. Both must point to the same directory. **`Remote: Borg ... incompatible` or protocol errors.** The client and server run different major versions. Install the same Borg release on both. **The job fails with `Connection closed by remote host`.** Test the key by hand with `ssh -i /root/.ssh/borg_ed25519 borg@backup.your_domain`; you should get no shell, only a Borg error about unexpected input. If SSH itself fails, check the key line in `authorized_keys` and the server's `/var/log/auth.log`. ## Conclusion Your server now sends encrypted, deduplicated and compressed backups every night to a remote repository it can add to but never erase, retention is applied only from a trusted machine, and you have verified that files can be restored. As next steps, add an `OnFailure=` handler to alert you when the service fails, schedule a monthly `borg check --verify-data`, and consider borgmatic if you want to manage several repositories and database dumps from one YAML file.