Name¶

borg-mount - Mounts an archive or an entire repository as a FUSE filesystem.

SYNOPSIS¶

borg [common options] mount [options] MOUNTPOINT [PATH...]

DESCRIPTION¶

This command mounts a repository or an archive as a FUSE filesystem. This can be useful for browsing or restoring individual files.

When restoring, take into account that the current FUSE implementation does not support special fs flags. On Linux, POSIX ACLs of the archived fs objects are exposed (read-only) via the system.posix_acl_access and system.posix_acl_default extended attributes, so tools like getfacl or rsync -A can read them from the mounted archive. Note that the mount does not enforce the ACLs for permission checks. On other platforms, ACLs are not supported.

When mounting a repository, there is one top directory per archive and the directory structure below these will be loaded on-demand from the repository when entering these directories, so expect some delay.

By default, these top directories are named like the archives; as the archives of a series all have the same name, -{id:.8} (the first 8 hex digits of the archive id) is appended whenever a name is not unique. To name them differently, set the BORG_MOUNT_ARCHIVE_DIR_FORMAT environment variable to a format string using the placeholders of borg repo-list --format, e.g. {name}-{time:%Y-%m-%dT%H:%M:%S} or {hostname}-{name}; names that are still not unique get -{id:.8} appended.

Note:

Unless the --foreground option is given, the command will run in the background until the filesystem is unmounted.

Performance tips:

The command borgfs provides a wrapper for borg mount. It is invoked as borgfs [REPOSITORY] MOUNTPOINT [PATH...], taking the repository as its first positional argument (if it is not given, -r / BORG_REPO is used). This can also be used in fstab entries: /path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0

To allow a regular user to use fstab entries, add the user option: /path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0

For FUSE configuration and mount options, see the mount.fuse(8) manual page.

Borg's default behavior is to use the archived user and group names of each file and map them to the system's respective user and group IDs. Alternatively, using numeric-ids will instead use the archived user and group IDs without any mapping.

The uid and gid mount options (implemented by Borg) can be used to override the user and group IDs of all files (i.e., borg mount -o uid=1000,gid=1000).

The man page references user_id and group_id mount options (implemented by FUSE) which specify the user and group ID of the mount owner (also known as the user who does the mounting). It is set automatically by libfuse (or the filesystem if libfuse is not used). However, you should not specify these manually. Unlike the uid and gid mount options, which affect all files, user_id and group_id affect the user and group ID of the mounted (base) directory.

Additional mount options supported by Borg:

On Windows, borg mount needs WinFsp <https://winfsp.dev/> and mfusepy. MOUNTPOINT must either be an unused drive (like X:) or a not yet existing directory (WinFsp creates it when mounting and removes it when unmounting). borg mount always stays in the foreground there and borg umount is not supported: to unmount, stop borg mount using Ctrl-C or Ctrl-Break. All files belong to the user who mounts, unless the uid / gid mount options (which are implemented by WinFsp there, not by Borg) say otherwise. ignore_permissions has no effect. WinFsp does not support hard link counts (they are always 1).

The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is intended for advanced users to tweak performance. It sets the number of cached data chunks; additional memory usage can be up to ~8 MiB times this number. The default is the number of CPU cores.

When the daemonized process receives a signal or crashes, it does not unmount. Unmounting in these cases could cause an active rsync or similar process to delete data unintentionally.

When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem, but other signals or crashes do not.

Debugging:

borg mount usually daemonizes and the daemon process sends stdout/stderr to /dev/null. Thus, you need to either use -f / --foreground to make it stay in the foreground and not daemonize, or use BORG_LOGGING_CONF to reconfigure the logger to output to a file.

OPTIONS¶

See borg-common(1) for common options of Borg commands.

SEE ALSO¶

borg-common(1), borg-umount(1), borg-extract(1)

Author¶

The Borg Collective