From cf472302dc5dffc244097a09c198b38651269136 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Oct 2024 14:12:53 +0200 Subject: [PATCH 1/5] docs: better link modern return codes, fixes #8370 --- docs/usage/general/return-codes.rst.inc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/usage/general/return-codes.rst.inc b/docs/usage/general/return-codes.rst.inc index e908c9283..b4547b62b 100644 --- a/docs/usage/general/return-codes.rst.inc +++ b/docs/usage/general/return-codes.rst.inc @@ -18,3 +18,5 @@ Return code Meaning If you use ``--show-rc``, the return code is also logged at the indicated level as the last log entry. + +The modern exit codes (return codes, "rc") are documented there: :ref:`msgid` From cbbfc35db0ef2211b547bc84fd13d7d21300d273 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Oct 2024 14:35:21 +0200 Subject: [PATCH 2/5] docs: mount: document on-demand loading, perf tips, fixes #7173 --- src/borg/archiver.py | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 4fe2ff540..90797d1d2 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -3083,10 +3083,25 @@ class Archiver: # borg mount mount_epilog = process_epilog(""" - This command mounts an archive as a FUSE filesystem. This can be useful for - browsing an archive or restoring individual files. Unless the ``--foreground`` - option is given the command will run in the background until the filesystem - is ``umounted``. + 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 ``umounted``. + + Performance tips: + + - when doing a "whole repository" mount: + do not enter archive dirs 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: From 278c266e7c2092a2f722733c0ba0929ca6a1c0a1 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Oct 2024 19:23:58 +0200 Subject: [PATCH 3/5] docs: add readme of the binaries "as is" as of 1.4.0 --- docs/binaries/00_README.txt | 80 +++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/binaries/00_README.txt diff --git a/docs/binaries/00_README.txt b/docs/binaries/00_README.txt new file mode 100644 index 000000000..045f82266 --- /dev/null +++ b/docs/binaries/00_README.txt @@ -0,0 +1,80 @@ +Binary BorgBackup builds +======================== + +The binaries are supposed to work on the specified platform without installing +any dependencies. + + +Download the correct files +-------------------------- + +amd64 / x86_64 architecture +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +borg-linux-glibc236 Linux (built on Debian 12 "Bookworm" with glibc 2.36) +borg-linux-glibc231 Linux (built on Debian 11 "Bullseye" with glibc 2.31) +borg-linux-glibc228 Linux (built on Debian 10 "Buster" with glibc 2.28) + Note: you can also try them on other Linuxes with other glibc + versions - as long as the glibc is compatible, they will work. + If it doesn't work, try a borg 1.2.x binary. + +borg-macos1012 macOS (built on macOS Sierra 10.12 with latest macFUSE from brew) + To avoid signing issues download the file via command line OR + remove the "quarantine" attribute after downloading: + $ xattr -dr com.apple.quarantine borg-macos.tgz + +borg-freebsd13 FreeBSD (built on FreeBSD 13) +borg-freebsd14 FreeBSD (built on FreeBSD 14) + +*.tgz similar to above, but built as a directory with files, + not as a single self-extracting binary. +*.asc GnuPG signatures for * + + +Verifying your download +----------------------- + +Please check the GPG signature to make sure you received the binary as I have +built it. + +To check the GPG signature, download both the binary and the corresponding +*.asc file and then (on the shell) type, e.g.: + + gpg --recv-keys 9F88FB52FAF7B393 + gpg --verify borg-freebsd.asc borg-freebsd + +The files are signed by: + +Thomas Waldmann +GPG key fingerprint: 6D5B EF9A DD20 7580 5747 B70F 9F88 FB52 FAF7 B393 + +My fingerprint is also in the footer of all my borgbackup mailing list posts. + + +Installing +---------- + +It is suggested that you rename or symlink the binary to just "borg". + +On UNIX-like platforms, /usr/local/bin/ or ~/bin/ is a nice place for it, +but you can invoke it from every place by giving a full path to it. + +Make sure the file is readable and executable (chmod +rx borg on UNIX-like +platforms). + + +Reporting issues +---------------- +If you find issues, please open a ticket on our issue tracker: + +https://github.com/borgbackup/borg/issues/ + +There, please give: +- the version number (it is displayed if you invoke borg -V) +- the sha256sum of the binary +- a good description of what the issue is +- a good description of how to reproduce your issue +- a traceback with system info (if you have one) +- your precise platform (CPU, 32/64bit?), OS, distribution, release +- your python and (g)libc version + From 1b878ab546c33a32cddc3509d943da7c5a1d779a Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Oct 2024 14:01:58 +0200 Subject: [PATCH 4/5] binary: using the directory build is faster, fixes #8008 --- docs/binaries/00_README.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/binaries/00_README.txt b/docs/binaries/00_README.txt index 045f82266..8727ac31d 100644 --- a/docs/binaries/00_README.txt +++ b/docs/binaries/00_README.txt @@ -27,7 +27,9 @@ borg-freebsd13 FreeBSD (built on FreeBSD 13) borg-freebsd14 FreeBSD (built on FreeBSD 14) *.tgz similar to above, but built as a directory with files, - not as a single self-extracting binary. + not as a single self-extracting binary. using the directory + build is faster and doesn't need as much space in the temp + directory as the one-file build. *.asc GnuPG signatures for * From 2230932c020aa706d19f0c85f9b01f32072139f7 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Oct 2024 14:23:21 +0200 Subject: [PATCH 5/5] docs: borg/borgfs detects internally under which name it was invoked, fixes #8207 --- docs/binaries/00_README.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/binaries/00_README.txt b/docs/binaries/00_README.txt index 8727ac31d..ea5d80cdc 100644 --- a/docs/binaries/00_README.txt +++ b/docs/binaries/00_README.txt @@ -57,6 +57,8 @@ Installing ---------- It is suggested that you rename or symlink the binary to just "borg". +If you need "borgfs", just also symlink it to the same binary, it will +detect internally under which name it was invoked. On UNIX-like platforms, /usr/local/bin/ or ~/bin/ is a nice place for it, but you can invoke it from every place by giving a full path to it.