Server — Backup — Install

This article covers the February side of the backup setup. The NAS side, which involves installing Borgbackup on the receiving end, creating the backup user, and initialising the repository, is covered in the next article. The two articles are meant to be read together, but this one is written to stand alone so you can refer back to it without losing context.

This assumes the NAS is already set up and reachable over SSH with a dedicated backup user and an initialised Borg repository. If that is not done yet, read the NAS article first and come back.

Install Borgbackup and borgmatic

Both packages are available in Ubuntu’s standard repositories. Borgbackup is the backup engine itself; borgmatic is the wrapper that handles scheduling, configuration, and retention through a single YAML file.

sudo apt install borgbackup pipx
sudo pipx install borgmatic
sudo pipx ensurepath

Using pipx for borgmatic rather than apt keeps it isolated from system Python packages and tends to give a more recent version. Confirm both are available after installation:

borg --version
sudo borgmatic --version

Generate the SSH key

February needs to authenticate to the NAS without a password, so the backup can run unattended. Generate a dedicated SSH key for this purpose rather than reusing an existing one:

sudo ssh-keygen -t ed25519 -f /root/.ssh/id_borg -N "" -C "february-borg"

Running this as root matters. borgmatic runs as root by default for system backups, and the key needs to be in root’s SSH directory for the connection to work.

The -N "" flag creates the key without a passphrase. The key itself is the credential; adding a passphrase on top would require interactive entry every time the backup runs, which defeats the purpose of automation.

Copy the public key to the NAS backup user:

sudo ssh-copy-id -i /root/.ssh/id_borg.pub backup@your-nas

Test the connection before going any further:

sudo ssh -i /root/.ssh/id_borg backup@your-nas

If you get a shell, the SSH side is working. Exit before continuing.

Generate the repository passphrase

The Borg repository on the NAS is encrypted. You need a strong passphrase to initialise it and to access it later. Generate one now and store it somewhere safe before you do anything else. KeePassXC is the right place for it; write it in the Infrastructure vault under a clear name like “February Borg Repository Passphrase”.

openssl rand -base64 32

Do not lose this passphrase. If you lose it and the repository is your only copy of a config file you need, the repository is permanently inaccessible. Borg encryption is not breakable by brute force. This is intentional. Treat the passphrase accordingly.

Write the borgmatic config

Create the borgmatic configuration directory and generate a config file:

sudo mkdir -p /etc/borgmatic
sudo borgmatic config generate --destination /etc/borgmatic/config.yaml

The generated file is heavily commented and covers far more options than you need right now. Replace it with a clean working configuration:

repositories:
  - path: ssh://backup@your-nas/./february
    label: nas

source_directories:
  - /etc
  - /home
  - /var/lib/chirpstack
  - /var/lib/influxdb
  - /var/lib/mosquitto
  - /var/lib/homeassistant

exclude_patterns:
  - /var/lib/influxdb/wal
  - '**/.cache'
  - '**/node_modules'

ssh_command: ssh -i /root/.ssh/id_borg

encryption_passphrase: "your-passphrase-here"

compression: zstd

keep_daily: 7
keep_weekly: 4
keep_monthly: 6

checks:
  - name: repository
  - name: archives
    frequency: 2 weeks

A few things to note here.

The repository path ssh://backup@your-nas/./february uses the ./ notation to resolve the path relative to the backup user’s home directory on the NAS. Replace your-nas with the NAS hostname or IP, and february with whatever the repository directory is named.

The source_directories list covers February’s config files under /etc, home directories, and the data directories for ChirpStack, InfluxDB, Mosquitto, and Home Assistant. Adjust these paths to match where your services actually store their data. Check each service’s documentation or configuration if you are unsure.

The InfluxDB WAL exclusion is worth keeping. The write-ahead log is a transient file that changes constantly and does not restore cleanly from a mid-write backup. Excluding it keeps the backup clean and InfluxDB happy on restore.

The retention policy keeps seven daily backups, four weekly, and six monthly. That is a reasonable default for a homelab: granular recent history, a longer tail for catching things you did not notice immediately.

Set permissions on the config file to prevent other users reading the passphrase:

sudo chmod 600 /etc/borgmatic/config.yaml

Validate the config

Before running anything, check that borgmatic is happy with the configuration:

sudo borgmatic config validate

A clean validation means borgmatic can parse the file. It does not confirm the NAS connection or the repository; that comes next.

Initialise the repository

This creates the encrypted Borg repository on the NAS. It only needs to happen once:

sudo borgmatic init --encryption repokey-blake2

repokey-blake2 stores the encryption key inside the repository, protected by the passphrase. The alternative is keyfile, which stores the key locally on February. The tradeoff: repokey means the repository is self-contained but useless without the passphrase; keyfile adds a second secret to manage and back up separately. For a homelab setup with a strong passphrase stored in a password manager, repokey-blake2 is the simpler choice.

After initialisation, export the repo key as an additional backup:

sudo borg key export ssh://backup@your-nas/./february /root/borg-key-export.txt

Store this file somewhere other than February and the NAS. The password manager vault on your laptop is fine.

Run the first backup

sudo borgmatic create --verbosity 1 --list --stats

The first run will take longer than subsequent ones because it transfers everything. Watch the output for errors. When it completes, you should see a stats block showing the original size, compressed size, and deduplicated size of the archive. The compressed size will typically be significantly smaller than the original, and the deduplicated size of the second backup onwards will be smaller still.

Confirm the archive was created:

sudo borgmatic list

This lists all archives in the repository. You should see one entry named something like february-2026-05-09T15:00:00.000000.

What is next

The backup now works manually. The next steps, covered in the following articles, are:

Scheduling — running borgmatic automatically on a systemd timer so the backup happens daily without intervention.

Notifications — getting alerted when a backup fails rather than discovering the gap six months later when you need a restore.

Testing restores — verifying that the backup actually contains what you think it contains and that you can get it back out again.

None of those steps are optional. A backup that runs unmonitored and has never been tested is a backup you cannot rely on when it matters.