Mounts a backup directory as a read-only filesystem so that ordinary Unix commands can be used to access your backup files. With the mount feature, you are never locked in to the HashBackup storage format: all of your historical backup data is accessible to any Unix command. Your backup data can be directly accessed to meet legal and electronic discovery requirements. The mount command is not yet available on sharded backups.

$ hb mount [-c backupdir] <mountpoint> [-f] [-a] `[-B blocksize]
           [--cache cachedir[,lock]] [--cachesize cachesize]

The mount command runs until the filesystem is unmounted with the fusermount -u <mountpoint> (Linux) or umount <mountpoint> (Mac/BSD) command. When the cache-size-limit config option is left at the default of -1 or the --cache option is used, new backups can be taken while the backup directory is mounted and will show up in the mounted filesystem. When the cache-size-limit config option is >= 0 and --cache is not used, mount has to lock the backup directory because backup data may need to be downloaded from remote destinations.

The -a option gives all users access to the mounted backup filesystem. Without this option, only the user mounting the backup directory has access to it; even root won’t have access unless it did the mount. Either way, standard Unix permissions are always checked on the mounted backup filesystem, keeping backup data secure.

When cache-size-limit is >= 0, not all arc files are local and the mount command will use selective download if supported by the destination. This downloads blocks of arc files as user files are accessed via the mount. If selective download is not supported on your destination, entire arc files are downloaded. No downloads are required to access file attribute data such as filename, date modified, size, etc., so the Unix find command for example does not download data and will run quickly. Downloading only occurs when reading data from user files via the mounted filesystem.

The -B option sets the minimum download block size for selective download. Larger block sizes increase throughput but may also increase latency (the delay before a file is available) and download fees because more data might be downloaded than is actually needed. The default block size is -B64K to minimize costs. Block sizes -B1M or -B4M usually increase performance. There is no limit on the download block size. Storage services with higher latency (the delay for a request to be completed) will benefit from higher block sizes since fewer requests are needed to retrieve backup data. Each backup version appears as a timestamped subdirectory of the mountpoint, YYYY-MM-DD-HHMM-r#, for example:

$ ls mnt
2013-03-28-1219-r0    2013-03-28-1219-r1    2013-03-28-1220-r2    2013-03-28-1220-r3    2013-03-28-1221-r4    latest

The directory latest includes all current files from every version. Without -f, only the files that were actually backed up in each version will appear within the timestamped subdirectories to make it easier to find and compare changes between versions. As a shorthand, the directories in the mountpoint can also be accessed with just a version number, so cd mnt/0 is the same as cd mnt/2013-03-28-1219-r0.

The -f option makes each version appear to be a complete point in time backup. With -f, there may be files in the r2 subdirectory that were actually backed up in versions 0 or 1. This can be useful to archive or export specific backup versions using other tools such as tar, cpio, rsync, etc.

All system commands should work normally within the read-only mounted filesystem, and all of the original file attributes such as modification time, access time, extended attributes, and permissions, are preserved: you can use the Unix find command to quickly look for files that have a certain age, use grep to search through files by keywords or patterns, use your favorite diff command to compare two versions of a file, or use the tar command to create a backup of the latest directory, exporting a complete copy of your most recent backup.

Cache Directory

When the cache-size-limit config option is >= 0, some arc (backup data) files are stored locally in the backup directory and some are on remote destinations and have to be downloaded to the backup directory during restore. This poses challenges:

  • the backup directory may be on a small disk, like an SSD, and might not have room to download all of the data needed to do a large restore.

  • during a restore, the backup directory has to be locked since the cache of arc files might be changing. This lock prevents backup and restore or two different restores from running simultaneously.

Mount’s `--cache option solves these problems. It specifies a separate directory used for storing downloaded data needed during the restore. If the cache directory already exists and matches the backup directory version, some downloaded data can be reused and the cache directory will remain after the mount command. If the cache directory doesn’t exist when mount starts, it will be created and then deleted when mount finishes. So to use the cache directory for several mounts, create it beforehand.

The --cache option has an optional modifier ,lock that can be added to request locking the main backup directory. This allows using arc files already in the backup directory instead of downloading them again. If ,lock is not used, backup directory arc files can only be reused if the cache directory is on the same disk as the backup directory, allowing hard linking.

The --cachesize option expands the mount cache beyond the default size. The default size is the greater of the config options cache-size-limit or 2 x (arc-size-limit + 10MB).

Mounting At Boot

This tip is from a customer (thanks Daniel!): to mount your backup during Linux startup, add a line to /etc/fstab. The first path is to the HB backup directory; the second path is where you want the backup mounted:

/mnt/datastore/server /mnt/server hb ro 0 0

If running in a container, you may also need to add:

@reboot mount /mnt/server

Then create /sbin/mount.hb and use chmod +x to make it an executable shell script:

/usr/local/bin/hb mount -c $1 $2 -a -f -Bxxx > /dev/null &

You may want to use >blah.out 2>blah.err to capture stdout and stderr to files.


  • ACLs will not be visible in the mounted backup filesystem on Mac & BSD systems because FUSE does not support ACLs

  • ACLs will be visible in the mounted backup filesystem on Linux systems because they are stored as extended attributes

  • The ctrl c interrupt key usually doesn’t work; use ctrl \ instead, but you must still unmount the filesystem after mount quits

  • to run in the background with no output, use: $ hb mount -c backupdir mnt >/dev/null 2>&1 &

  • to run in the background with all output to mount.out, use: $ hb mount -c backupdir mnt >mount.out 2>&1 &

  • add user_allow_other to /etc/fuse.conf to use the -a option, allowing anyone to access the mount (Linux)

  • add the userid running hb mount to the fuse group to give access to the fusermount command (Linux)

  • or, chmod o+rx /bin/fusermount to enable anyone to access the fusermount command


  • the mount command requires that the FUSE kernel module and shared library are installed on your system

  • the FUSE library is GPL licensed so cannot be included in the HB binary

  • on Linux and BSD, FUSE can be installed with your package manager

  • on Linux, the FUSE kernel module is usually already installed

  • the main FUSE repository is:

  • for OSX, see:

  • the older version of FUSE for OSX is called MacFUSE

  • install the MacFUSE compatibility layer with OSXFUSE