Learn Borg Backup - Restore & Extract

#Introduction

After the first backup in episode 4, it is time to face the real question: can you actually restore that data? Many teams run backups routinely for years but only find out their backups are broken when a disaster actually happens. This episode makes sure you master borg extract and borg mount, plus the restore-testing habit that saves careers.

#Extract: Restoring Data

#How It Works

borg extract reads an archive and writes files to the current working directory (cwd). You cannot choose the destination directory via an argument — so controlling the cwd is the first step:

mkdir -p /tmp/restore
cd /tmp/restore
borg extract /backup/borg::"web-01-2026-08-13T10:30:00"

The entire archive contents (/home, /etc) will be pulled into /tmp/restore, with the original path structure.

#Dry-run and Planning

Before a large extraction, first confirm what will be extracted:

borg extract --dry-run --list /backup/borg::"web-01-2026-08-13T10:30:00" --path home/arman

--dry-run writes nothing; --list shows the files that would be restored.

#Selective Extraction with --path

Not every disaster needs a full restore. Losing a single file is handled fine with selective extraction:

cd /tmp/restore
borg extract /backup/borg::"web-01-2026-08-13T10:30:00" \
  --path home/arman/dokumen

• --path can be repeated for multiple paths at once.
• --strip-components N removes the first N path components — useful if you want to move files to a new location without the full structure:

cd /tmp/restore
borg extract /backup/borg::"web-01-2026-08-13T10:30:00" \
  --path etc/nginx \
  --strip-components 1

As a result, the contents of etc/nginx are placed directly in /tmp/restore/nginx.

#Mount: Browsing Archives via FUSE

#The Concept

borg mount maps an archive as a regular directory using FUSE. You can browse, copy specific files, even run search tools — without a full restore. This is the fastest way to answer the question "which file was lost?".

mkdir -p /mnt/borg
borg mount /backup/borg::"web-01-2026-08-13T10:30:00" /mnt/borg
ls /mnt/borg

All archives can also be mounted at once by omitting the archive name:

borg mount /backup/borg /mnt/borg
ls /mnt/borg

Each archive appears as a subdirectory. Unmount with:

borg umount /mnt/borg

FUSE is a read-only mechanism — you cannot write to an archive, which is a property we actually want (episode 2).

#Alternative: borg export-tar

To hand backups to someone else in a universal format, export them as a tarball:

borg export-tar /backup/borg::"web-01-2026-08-13T10:30:00" backup.tar.gz

The resulting tar.gz can be moved anywhere and opened with plain tar.

#Best Practice: A Proper Restore

#Restore to a Clean Directory

Never extract an archive into a directory that still contains active files — files deleted from the source will not be deleted from the cwd, and old files can mix with new ones. Always create an empty directory, like the /tmp/restore example, then verify.

#Verify the Results

After extraction, verify that the result is genuinely usable:

cd /tmp/restore
test -f etc/nginx/nginx.conf && echo "config OK"
ls -la home/arman/dokumen | head

For thorough verification, compare the checksums of important files between the source and the restore result — or simply prove the application can be started from the restored result.

#Common Pitfalls

• Extracting into the wrong directory: borg extract always writes to the cwd. Make sure you cd first, then extract.
• Full restore onto a live system: overwriting a running system with old files can corrupt its state. Restore to a staging area, test, then move it over.
• Forgetting the passphrase/key: without the key, there is no extract. Another reminder for episode 7.
• Assuming mount is writable: archives are read-only; to modify, extract to a directory first.

#Closing

• borg extract restores data to the cwd; always cd to a clean directory first.
• --path and --strip-components give you selective control.
• borg mount (FUSE) opens an archive as a read-only directory for quick browsing.
• borg export-tar produces a universal archive for moving around.
• Verify the results and schedule routine restore drills.

In episode 6 we optimize storage: zstd, lz4, and zlib compression — understanding the CPU vs space trade-off, choosing compression levels, and reading the compression ratio from borg info.