Borgmatic Restore
A backup you have never tested is not a backup. It is a belief. You believe the files are there, you believe the encryption passphrase is correct, you believe the SSH key still works, you believe the archive contains what you think it contains. Until you actually pull something out and verify it, those are all assumptions.
This article covers how to restore from a borgmatic backup on February: listing archives, browsing their contents, extracting individual files, extracting directories, and doing a full restore. It also covers the harder scenario: restoring to a new machine when the original is gone.
Do this now, while nothing is broken and the stakes are low. The correct time to discover that the passphrase is saved incorrectly in KeePassXC is not when you actually need to get files back.
Before you start
You need three things to restore from the repository:
The SSH private key at /etc/borg/ssh/id_ed25519. Without this, the connection to the NAS cannot be established.
The repository passphrase from KeePassXC. Without this, the repository cannot be decrypted.
Network access to the NAS. For the local repository, this means being on the Burnage network. For the remote repository, this means the VPN to The Lighthouse being up.
If any of these three are missing, the repository is inaccessible. Confirming that all three are present and working is the first thing to do before attempting a restore.
Listing archives
Before restoring anything, confirm the archives are there.
sudo borgmatic list
This lists all archives across all configured repositories. The output looks something like:
local-nas: ssh://borg-backup@nas.burnage.yourdomain.net/...
------------------------------------------------------------------------------
february-2026-05-09T10:00:00.000000 Fri, 2026-05-09 10:00:00 [abc123...]
february-2026-05-10T10:00:00.000000 Sat, 2026-05-10 10:00:00 [def456...]
remote-nas: ssh://borg-backup@nas.lighthouse.yourdomain.net/...
------------------------------------------------------------------------------
february-2026-05-09T10:00:00.000000 Fri, 2026-05-09 10:00:00 [abc123...]
To list archives from a specific repository only:
sudo borgmatic list --repository local-nas
To see what is inside a specific archive:
sudo borgmatic list --archive latest
This lists every file in the most recent archive. On a server with a full /etc and /var/log, this will be a long list. Pipe it through grep to find something specific:
sudo borgmatic list --archive latest | grep hostname
Searching across archives
If you know a file existed but are not sure which archive has the version you want:
sudo borgmatic list --archive latest --find etc/ssh/sshd_config
The --find flag accepts glob patterns:
sudo borgmatic list --archive latest --find '*.conf'
Note the path has no leading slash. borgmatic strips the leading / when storing paths in the archive, so searches and extractions use the path without it.
Extracting a single file
The most common restore scenario: you need one file back, and you know which one.
sudo borgmatic extract --archive latest --path etc/hostname
By default, borgmatic extracts into the current directory, preserving the full path structure. If you run this from /tmp, it will create /tmp/etc/hostname. This is intentional: it prevents borgmatic from overwriting the live file without you explicitly moving it into place.
To extract to a specific destination:
sudo borgmatic extract --archive latest \
--path etc/hostname \
--destination /tmp/restore
The file will be at /tmp/restore/etc/hostname. Inspect it, confirm it is what you expect, then copy it to where it needs to go.
To extract from a specific repository rather than the first one in the config:
sudo borgmatic extract --archive latest \
--repository local-nas \
--path etc/hostname \
--destination /tmp/restore
Extracting a directory
Same command, broader path:
sudo borgmatic extract --archive latest \
--path etc/ssh \
--destination /tmp/restore
This extracts the entire /etc/ssh directory to /tmp/restore/etc/ssh/. Multiple paths can be specified:
sudo borgmatic extract --archive latest \
--path etc/ssh \
--path etc/borgmatic \
--destination /tmp/restore
Dry-run extraction
Before extracting anything, you can do a dry run to confirm the paths exist in the archive and see what would be extracted:
sudo borgmatic extract --archive latest \
--path etc/ssh \
--destination /tmp/restore \
--dry-run
This lists the files without writing anything to disk. Useful for confirming you have the right archive and the right path before committing.
Mounting an archive for browsing
For exploratory restores, where you want to browse the archive contents and copy individual files, mounting is more convenient than repeated extractions.
Create a mount point:
sudo mkdir -p /mnt/borg-restore
Mount the latest archive:
sudo borgmatic mount \
--archive latest \
--mount-point /mnt/borg-restore
The archive is now browseable as a regular filesystem:
ls /mnt/borg-restore/etc/
ls /mnt/borg-restore/var/log/
Copy files out as needed:
sudo cp /mnt/borg-restore/etc/ssh/sshd_config /tmp/sshd_config.bak
When done, unmount:
sudo borgmatic umount --mount-point /mnt/borg-restore
Mounting requires FUSE to be installed. On Ubuntu 24.04 it is installed by default, but if you get a FUSE-related error:
sudo apt install fuse
Extracting from a named archive
The --archive latest shortcut always uses the most recent archive. To restore from a specific point in time, use the archive name from borgmatic list:
sudo borgmatic extract \
--archive february-2026-05-09T10:00:00.000000 \
--path etc/ssh \
--destination /tmp/restore
This is the command to reach for when you need to recover a file that existed three days ago but was modified or deleted since.
Bootstrapping borgmatic config from the archive
borgmatic automatically stores its own configuration files inside each backup archive. If you have lost the borgmatic config and need to recover it from the archive, borgmatic can extract it directly without needing a config file to run:
sudo borgmatic config bootstrap \
--repository ssh://borg-backup@nas.burnage.yourdomain.net/volume1/BorgBackup/february \
--destination /tmp
This extracts the borgmatic config from the latest archive in the specified repository to /tmp/etc/borgmatic/config.yaml. You will need the SSH key and passphrase, and you will need to specify the passphrase via the BORG_PASSPHRASE environment variable since there is no config file for borgmatic to read it from:
sudo BORG_PASSPHRASE="your-passphrase-here" \
borgmatic config bootstrap \
--repository ssh://borg-backup@nas.burnage.yourdomain.net/volume1/BorgBackup/february \
--destination /tmp
Restoring to a new machine
The harder scenario: February is gone, and you need to restore to a fresh Ubuntu server. The process is:
1. Install Borg and borgmatic on the new machine, following the install article.
2. Restore the SSH key. The private key at /etc/borg/ssh/id_ed25519 needs to be on the new machine. This key should be stored somewhere other than the machine it backs up: KeePassXC attachments, a second encrypted device, or another server. If you do not have a copy of the SSH key, you cannot connect to the NAS repository. This is the single most important thing to have stored off-machine.
3. Bootstrap the borgmatic config from the repository, using the config bootstrap command above.
4. Restore the files you need, using borgmatic extract with the appropriate paths and a destination directory.
For a full restore, extract everything:
sudo borgmatic extract --archive latest --destination /tmp/restore
Then copy files into place from /tmp/restore. Do not extract directly to / on a running system unless you are very confident about what you are overwriting.
Making restore testing a habit
Add a calendar reminder to test a restore once a month. It does not have to be comprehensive: pick a file at random from borgmatic list --archive latest, extract it to /tmp, confirm it looks right, delete it. Five minutes. The point is confirming that the SSH key works, the passphrase is correct, the archive is readable, and the extraction command runs without error.
If the SSH private key is only on February, and February fails, the backup repository is inaccessible. Store a copy of
/etc/borg/ssh/id_ed25519somewhere that survives total loss of the server.