Quickly Restore a Single File From a Borg Backup on an NFS Share -

BorgBackup is a popular deduplicating backup tool that works well with remote repositories. In many homelab or small‑business setups the backup repository lives on an NFS share because it’s easy to share across multiple hosts and integrates nicely with existing storage infrastructure. When a single file goes missing or gets corrupted, you want a fast, reliable way to pull it back without pulling the whole archive.

This walkthrough shows how to:

mount the NFS share with the right options
inspect a Borg repository that lives on NFS
restore a single file quickly
handle common pitfalls (permissions, stale handles, NFS locking)
secure the process with minimal friction

The examples assume a recent Debian‑based system (Debian 12 “Bookworm” or Ubuntu 24.04 “Noble Numbat”) but the commands work on any Linux that supports NFS and Borg.

On the NFS server (often a dedicated NAS or a VM), the export might look like:

# /etc/exports
# /mnt/borg-repo 192.168.1.0/24(rw,sync,no_subtree_check,root_squash)

sync forces the server to write changes to disk before replying, which is safer for backup data.
root_squash prevents root on the client from writing as root on the server, a small but useful security measure.

After editing, reload the export table:

sudo exportfs -ra

1.2. Mounting on the Client

Create a mount point and mount with options that match the export:

sudo mkdir -p /mnt/borg
sudo mount -t nfs4 -o vers=4.2,sec=krb5i,hard,intr,rsize=1048576,wsize=1048576 192.168.1.10:/mnt/borg-repo /mnt/borg

vers=4.2 forces NFSv4.2, which has better locking semantics.
sec=krb5i requires Kerberos authentication and integrity protection—recommended for any production environment.
hard and intr make the client retry on transient network failures.
rsize/wsize tune transfer size; 1 MiB is a good starting point.

Verify the mount:

df -h /mnt/borg

If you see “NFS” in the filesystem column, you’re good.

2. Borg Repository on NFS

Borg stores data in a directory tree. The repository’s root contains config, data, info, last, and a repo directory with the actual chunks.

2.1. Permissions

Borg expects the repository to be owned by the user that runs the backup process. On NFS, the UID/GID mapping must match on both sides. If you’re using a dedicated backup user:

sudo useradd -r -s /usr/sbin/nologin borgbackup
sudo chown -R borgbackup:borgbackup /mnt/borg

If the NFS server uses root_squash, the backup user must have a matching UID on the server. Use /etc/passwd or LDAP to keep them in sync.

2.2. Locking

NFSv4 implements advisory locking via fcntl. Borg uses fcntl locks to prevent concurrent writes. On older NFSv3 or misconfigured servers, locks can fail silently, leading to data corruption. That’s why we force vers=4.2 and sec=krb5i above.

3. Inspecting the Repository

Before restoring, you may want to list the archives and locate the file.

sudo -u borgbackup borg list /mnt/borg

Typical output:

2026-09-19T12:00:00Z  /etc
2026-09-18T12:00:00Z  /var
2026-09-17T12:00:00Z  /home

To see the contents of a specific archive:

sudo -u borgbackup borg list /mnt/borg::2026-09-19T12:00:00Z

If you only need to know whether a file exists, use --list with --prefix:

sudo -u borgbackup borg list /mnt/borg::2026-09-19T12:00:00Z --prefix /etc/ssh/sshd_config

If the file is present, Borg will print its path; otherwise, it will exit with code 1.

4. Restoring a Single File

The core command is borg extract. The syntax is:

borg extract [OPTIONS] REPOSITORY::ARCHIVE [PATHS...]

4.1. Basic Restore

sudo -u borgbackup borg extract /mnt/borg::2026-09-19T12:00:00Z /etc/ssh/sshd_config

Borg will:

Acquire a read lock on the repository.
Read the archive metadata.
Pull the necessary chunks over NFS.
Write the file to the current working directory (by default, the directory where the command is run).

If you want the file to land in its original location, run the command from the root of the filesystem:

cd /
sudo -u borgbackup borg extract /mnt/borg::2026-09-19T12:00:00Z /etc/ssh/sshd_config

4.2. Restoring to a Different Destination

Use --destination:

sudo -u borgbackup borg extract /mnt/borg::2026-09-19T12:00:00Z --destination /tmp/restore /etc/ssh/sshd_config

The file will appear as /tmp/restore/etc/ssh/sshd_config. This is handy when you’re testing the restore before overwriting the live file.

4.3. Restoring Multiple Files

You can list several paths:

sudo -u borgbackup borg extract /mnt/borg::2026-09-19T12:00:00Z /etc/ssh/sshd_config /etc/hosts

Or use globbing:

sudo -u borgbackup borg extract /mnt/borg::2026-09-19T12:00:00Z /etc/ssh/*.conf

Borg preserves directory structure automatically.

4.4. Avoiding Unwanted Files

If the archive contains a large directory tree and you only need a single file, use --exclude to skip everything else:

sudo -u borgbackup borg extract /mnt/borg::2026-09-19T12:00:00Z --exclude '**' /etc/ssh/sshd_config

The ** pattern matches all files; the explicit path overrides it.

5. Security Considerations

5.1. NFS Export

When you’re backing up sensitive data, make sure the NFS export is locked down. Don’t let the world read or write to it. If you’re using Kerberos, keep the realm and keytab up to date, and consider adding no_root_squash only for trusted hosts.

5.2. Borg Encryption

Borg supports client‑side encryption. If you’re storing the repository on an NFS share that’s accessible from multiple machines, enable encryption to keep the data safe even if someone mounts the share elsewhere.

borg init --encryption=repokey

linux open-source

Restoring a Single File from a Borg Backup on an NFS Share

1. Mounting the NFS Share

1.1. Exporting the Share