borg mount¶

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

positional arguments
	`MOUNTPOINT`	where to mount the filesystem
	`PATH`	paths to extract; patterns are supported
options
	`-f`, `--foreground`	stay in foreground, do not daemonize
	`-o`	extra mount options
	`--numeric-ids`	use numeric user and group identifiers from archives
Common options
Archive filters — Archive filters can be applied to repository targets.
	`-a PATTERN`, `--match-archives PATTERN`	only consider archives matching all patterns. See “borg help match-archives”.
	`--sort-by KEYS`	Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
	`--first N`	consider the first N archives after other filters are applied
	`--last N`	consider the last N archives after other filters are applied
	`--oldest TIMESPAN`	consider archives between the oldest archive’s timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
	`--newest TIMESPAN`	consider archives between the newest archive’s timestamp and (newest - TIMESPAN), e.g., 7d or 12m.
	`--older TIMESPAN`	consider archives older than (now - TIMESPAN), e.g., 7d or 12m.
	`--newer TIMESPAN`	consider archives newer than (now - TIMESPAN), e.g., 7d or 12m.
Include/Exclude options
	`-e PATTERN`, `--exclude PATTERN`	exclude paths matching PATTERN
	`--exclude-from EXCLUDEFILE`	read exclude patterns from EXCLUDEFILE, one per line
	`--pattern PATTERN`	include/exclude paths matching PATTERN
	`--patterns-from PATTERNFILE`	read include/exclude patterns from PATTERNFILE, one per line
	`--strip-components NUMBER`	Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.

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 and ACLs.

When mounting a repository, the top directories will be named like the archives and the directory structure below these will be loaded on-demand from the repository when entering these directories, so expect some delay.

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

Performance tips:

When doing a “whole repository” mount: do not enter archive directories if not needed; this avoids on-demand loading.
Only mount a specific archive, not the whole repository.
Only mount specific paths in a specific archive, not the complete archive.

The command borgfs provides a wrapper for borg mount. 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:

versions: when used with a repository mount, this gives a merged, versioned view of the files in the archives. EXPERIMENTAL; layout may change in the future.
allow_damaged_files: by default, damaged files (where chunks are missing) will return EIO (I/O error) when trying to read the related parts of the file. Set this option to replace the missing parts with all-zero bytes.
ignore_permissions: for security reasons the default_permissions mount option is internally enforced by Borg. ignore_permissions can be given to not enforce default_permissions.

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.

borg umount¶

borg [common options] umount [options] MOUNTPOINT

positional arguments
	`MOUNTPOINT`	mountpoint of the filesystem to unmount
Common options

Description¶

This command unmounts a FUSE filesystem that was mounted with borg mount.

This is a convenience wrapper that just calls the platform-specific shell command - usually this is either umount or fusermount -u.

Examples¶

# Mounting the repository shows all archives.
# Archives are loaded lazily, expect some delay when navigating to an archive
# for the first time.
$ borg mount /tmp/mymountpoint
$ ls /tmp/mymountpoint
root-2016-02-14 root-2016-02-15
$ borg umount /tmp/mymountpoint

# The "versions view" merges all archives in the repository
# and provides a versioned view on files.
$ borg mount -o versions /tmp/mymountpoint
$ ls -l /tmp/mymountpoint/home/user/doc.txt/
total 24
-rw-rw-r-- 1 user group 12357 Aug 26 21:19 doc.cda00bc9.txt
-rw-rw-r-- 1 user group 12204 Aug 26 21:04 doc.fa760f28.txt
$ borg umount /tmp/mymountpoint

# Archive filters are supported.
# These are especially handy for the "versions view",
# which does not support lazy processing of archives.
$ borg mount -o versions --match-archives 'sh:*-my-home' --last 10 /tmp/mymountpoint

# Exclusion options are supported.
# These can speed up mounting and lower memory needs significantly.
$ borg mount /path/to/repo /tmp/mymountpoint only/that/path
$ borg mount --exclude '...' /tmp/mymountpoint

borgfs¶

$ echo '/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
$ mount /tmp/myrepo
$ ls /tmp/myrepo
root-2016-02-01 root-2016-02-15

Note

borgfs will be automatically provided if you used a distribution package or pip to install Borg. Users of the standalone binary will have to manually create a symlink (see Standalone Binary).