Restoring Files by Mounting and Browsing a Borg Archive
Reviewed in August 2023
This article assumes that you have set up a backup workflow to a local or remote Borg repository. Now you would like to restore files from it. Borg offers two different ways to restore files. The borg mount command allows you to browse multiple archives and find exactly the file you are looking for. Due to some overhead from the FUSE mount library, the speed can be slower when restoring a large number of files. This is where borg extract comes in. If you already know which files you need, it can quickly restore large quantities of data including all metadata.
Prerequisites
Section titled “Prerequisites”You should already have Borg installed and know how to use the command line. If you didn’t install Borg yet, have a look at this previous guide.
Step 1 - Set up FUSE
Section titled “Step 1 - Set up FUSE”The FUSE library allows mounting arbitrary file systems into user space. It’s available for all popular systems. The official Borg docs have a detailed overview for each system. You will need two parts: the actual FUSE library and Python wrappers for it.
For macOS: Install the FUSE library from Homebrew.
$ brew install --cask macfuseFor Debian/Ubuntu: The FUSE library is available from the main package repository.
$ sudo apt-get install libfuse-dev fuse pkg-configFor Red Hat/CentOS: FUSE is available from the official repository.
$ yum install fuse-devel fuse pkgconfigStep 2 - Install Borg with FUSE support
Section titled “Step 2 - Install Borg with FUSE support”FUSE support is an optional add-on for Borg. Install it like this:
$ pip3 install 'borgbackup[llfuse]'On macOS, you could also use Borg’s FUSE-enabled Tap.
Step 3 - Validate Installation and Repository
Section titled “Step 3 - Validate Installation and Repository”Next make sure everything is installed properly and you have access to the backup repo.
$ borg info ssh://w66xh7lj@w66xh7lj.repo.borgbase.com/./repoYou should see output similar to this. If you get an error, be sure that you have access to the repository. If your repo is encrypted, it will also ask you for the password or keyfile.
Repository ID: daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90ebLocation: ssh://w66xh7lj@w66xh7lj.repo.borgbase.com/./repoEncrypted: Yes (repokey BLAKE2b)Cache: /Users/manu/.cache/borg/daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90ebSecurity dir: /Users/manu/.config/borg/security/daf2e2b94a1b57f0effc96939813ef58d0af04414f92f87c3e092a99adaa90eb------------------------------------------------------------------------------ Original size Compressed size Deduplicated sizeAll archives: 665.90 MB 577.88 MB 68.41 MB
Unique chunks Total chunksChunk index: 1359 6711If you installed Borg and llfuse via PIP, you can also validate the packages are installed
$ pip freeze | grep llfuse$ pip freeze | grep borgbackupStep 4 - Mounting the Backup
Section titled “Step 4 - Mounting the Backup”The borg mount command allows for simple browsing and restoring individual files without their complete metadata. This is great to restore a few documents or images.
First create a new folder as mount point. Since we’re not working with root permissions, we won’t use /mnt. Instead any empty folder in your home directory will suffice.
$ mkdir borg-mountNext mount the whole repository into the newly created folder. This will give us a view of all archives in the repository.
$ borg mount ssh://w66xh7lj@w66xh7lj.repo.borgbase.com/./repo borg-mountIf there was no error, you should now see all your archives in the borg-mount folder:
$ ls -l borg-mountDepending on the archive names used, the output could look like this.
drwxr-xr-x 1 manu staff 0 Feb 16 12:04 nyx2-test-repo-2019-02-16T12:04:06drwxr-xr-x 1 manu staff 0 Mar 5 13:12 nyx2-test-repo-2019-03-05T13:12:04drwxr-xr-x 1 manu staff 0 Mar 19 22:36 nyx2-test-repo-2019-03-19T22:36:07drwxr-xr-x 1 manu staff 0 Mar 25 23:29 nyx2-test-repo-2019-03-25T23:29:35drwxr-xr-x 1 manu staff 0 Mar 26 23:02 nyx2-test-repo-2019-03-26T23:01:57drwxr-xr-x 1 manu staff 0 Mar 27 09:21 nyx2-test-repo-2019-03-27T09:21:42You can now browse this folder structure and copy the files you need.
For more information on mounting, check out the official Borg documentation.