borgbackup 2.0.0b8__tar.gz → 2.0.0b10__tar.gz

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 -   repo: https://github.com/psf/black
-    rev: 23.1.0
+    rev: 24.8.0
     hooks:
     -   id: black
 - repo: https://github.com/astral-sh/ruff-pre-commit

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/Brewfile

@@ -2,7 +2,7 @@ brew 'pkg-config'
 brew 'zstd'
 brew 'lz4'
 brew 'xxhash'
-brew 'openssl@1.1'
+brew 'openssl@3.0'
 
 # osxfuse (aka macFUSE) is only required for "borg mount",
 # but won't work on github actions' workers.

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/CHANGES.rst

@@ -12,8 +12,8 @@ This section provides information about security and corruption issues.
 Upgrade Notes
 =============
 
-borg 1.2.x to borg 2.0
-----------------------
+borg 1.2.x/1.4.x to borg 2.0
+----------------------------
 
 Compatibility notes:
 
@@ -21,11 +21,11 @@ Compatibility notes:
 
   We tried to put all the necessary "breaking" changes into this release, so we
   hopefully do not need another breaking release in the near future. The changes
-  were necessary for improved security, improved speed, unblocking future
-  improvements, getting rid of legacy crap / design limitations, having less and
-  simpler code to maintain.
+  were necessary for improved security, improved speed and parallelism,
+  unblocking future improvements, getting rid of legacy crap and design
+  limitations, having less and simpler code to maintain.
 
-  You can use "borg transfer" to transfer archives from borg 1.1/1.2 repos to
+  You can use "borg transfer" to transfer archives from borg 1.2/1.4 repos to
   a new borg 2.0 repo, but it will need some time and space.
 
   Before using "borg transfer", you must have upgraded to borg >= 1.2.6 (or
@@ -58,10 +58,12 @@ Compatibility notes:
 
     - borg 2 repo commands:
 
-      - borg rcreate  # "repo create", was: borg init
-      - borg rlist  # "repo list"
-      - borg rinfo  # "repo info"
-      - borg rdelete  # "repo delete"
+      - borg repo-create  # was: borg init
+      - borg repo-list
+      - borg repo-info
+      - borg repo-delete
+      - borg repo-compress
+      - borg repo-space
     - borg 2 archive commands:
 
       - borg create ARCHIVE ...
@@ -84,6 +86,8 @@ Compatibility notes:
   - removed --nobsdflags (use --noflags)
   - removed --noatime (default now, see also --atime)
   - removed --save-space option (does not change behaviour)
+- removed --bypass-lock option
+- removed borg config command (only worked locally anyway)
 - using --list together with --progress is now disallowed (except with --log-json), #7219
 - the --glob-archives option was renamed to --match-archives (the short option
   name -a is unchanged) and extended to support different pattern styles:
@@ -114,14 +118,13 @@ Compatibility notes:
   fail now that somehow "worked" before (but maybe didn't work as intended due to
   the contradicting options).
 
-
 .. _changelog:
 
 Change Log 2.x
 ==============
 
-Version 2.0.0b8 (2024-02-20)
-----------------------------
+Version 2.0.0b10 (2024-09-09)
+-----------------------------
 
 Please note:
 
@@ -130,6 +133,99 @@ This is a beta release, only for testing - do not use for production repos.
 For upgrade and compatibility hints, please also read the section "Upgrade Notes"
 above.
 
+TL;DR: this is a huge change and the first very fundamental change in how borg
+works since ever:
+
+- you will need to create new repos.
+- likely more exciting than previous betas, definitely not for production.
+- remove "borg check --repair --archives-only" from your script in case you
+  added that for b9. "borg compact -v" now finds and deletes orphan chunks
+  and also outputs some new stats.
+
+New features:
+
+- borgstore based repository, file:, ssh: and sftp: for now, more possible.
+- repository stores objects separately now, not using segment files.
+  this has more fs overhead, but needs much less I/O because no segment
+  files compaction is required anymore. also, no repository index is
+  needed anymore because we can directly find the objects by their ID.
+- locking: new borgstore based repository locking with automatic stale
+  lock removal (if lock does not get refreshed, if lock owner process is dead).
+- simultaneous repository access for many borg commands except check/compact.
+  the cache lock for adhocwithfiles is still exclusive though, so use
+  BORG_CACHE_IMPL=adhoc if you want to try that out using only 1 machine
+  and 1 user (that implementation doesn't use a cache lock). When using
+  multiple client machines or users, it also works with the default cache.
+- delete/prune: much quicker now and can be undone.
+- check --repair --undelete-archives: bring archives back from the dead.
+- repo-space: manage reserved space in repository (avoid dead-end situation if
+  repository filesystem runs full).
+
+Bugs/issues fixed:
+
+- a lot! all linked from PR #8332.
+
+Other changes:
+
+- repository: remove transactions, solved differently and much simpler now
+  (convergence and write order primarily).
+- repository: replaced precise reference counting with "object exists in repo?"
+  and "garbage collection of unused objects".
+- cache: remove transactions, remove chunks cache.
+  removed LocalCache, BORG_CACHE_IMPL=local, solving all related issues.
+  as in beta 9, adhowwithfiles is the default implementation.
+- compact: needs the borg key now (run it clientside), -v gives nice stats.
+- transfer: archive transfers from borg 1.x need the --from-borg1 option
+- check: reimplemented / bigger changes.
+- code: got rid of a metric ton of not needed complexity.
+  when borg does not need to read borg 1.x repos/archives anymore, after
+  users have transferred their archives, even much more can be removed.
+- docs: updated / removed outdated stuff
+- renamed r* commands to repo-*
+
+
+Version 2.0.0b9 (2024-07-20)
+----------------------------
+
+New features:
+
+- add BORG_CACHE_IMPL, default is "adhocwithfiles" to test the new cache
+  implementation, featuring an adhoc non-persistent chunks cache and a
+  persistent files cache. See the docs for other values.
+
+  Requires to run "borg check --repair --archives-only" to delete orphaned
+  chunks before running "borg compact" to free space! These orphans are
+  expected due to the simplified refcounting with the AdHocFilesCache.
+- make BORG_EXIT_CODES="modern" the default, #8110
+- add BORG_USE_CHUNKS_ARCHIVE env var, #8280
+- automatically rebuild cache on exception, #5213
+
+Bug fixes:
+
+- fix Ctrl-C / SIGINT behaviour for pyinstaller-made binaries, #8155
+- delete: fix error handling with Ctrl-C
+- rcompress: fix error handling with Ctrl-C
+- delete: fix error handling when no archive is specified, #8256
+- setup.py: fix import error reporting for cythonize import, see #8208
+- create: deal with EBUSY, #8123
+- benchmark: inherit options --rsh --remote-path, #8099
+- benchmark: fix return value, #8113
+- key export: fix crash when no path is given, fix exception handling
+
+Other changes:
+
+- setup.py: detect noexec build fs issue, see #8208
+- improve acl_get / acl_set error handling (forward port from 1.4-maint)
+- allow msgpack 1.1.0
+- vagrant: use pyinstaller 6.7.0
+- use Python 3.11.9 for binary builds
+- require Cython 3.0.3 at least, #8133
+- docs: add non-root deployment strategy
+
+
+Version 2.0.0b8 (2024-02-20)
+----------------------------
+
 New features:
 
 - create: add the slashdot hack, update docs, #4685

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: borgbackup
-Version: 2.0.0b8
+Version: 2.0.0b10
 Summary: Deduplicated, encrypted, authenticated and compressed backups
 Author: The Borg Collective (see AUTHORS file)
 Maintainer-email: Thomas Waldmann <tw@waldmann-edv.de>
@@ -26,12 +26,14 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security :: Cryptography
 Classifier: Topic :: System :: Archiving :: Backup
 Requires-Python: >=3.9
 License-File: LICENSE
 License-File: AUTHORS
-Requires-Dist: msgpack<=1.0.7,>=1.0.3
+Requires-Dist: borgstore~=0.0.1
+Requires-Dist: msgpack<=1.1.0,>=1.0.3
 Requires-Dist: packaging
 Requires-Dist: platformdirs<5.0.0,>=3.0.0; sys_platform == "darwin"
 Requires-Dist: platformdirs<5.0.0,>=2.6.0; sys_platform != "darwin"
@@ -93,7 +95,7 @@ Main features
 **Speed**
   * performance-critical code (chunking, compression, encryption) is
     implemented in C/Cython
-  * local caching of files/chunks index data
+  * local caching
   * quick detection of unmodified files
 
 **Data encryption**
@@ -146,9 +148,9 @@ For ease of use, set the BORG_REPO environment variable::
 
     $ export BORG_REPO=/path/to/repo
 
-Create a new backup repository (see ``borg rcreate --help`` for encryption options)::
+Create a new backup repository (see ``borg repo-create --help`` for encryption options)::
 
-    $ borg rcreate -e repokey-aes-ocb
+    $ borg repo-create -e repokey-aes-ocb
 
 Create a new backup archive::
 

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/README.rst

@@ -3,12 +3,17 @@ This is borg2!
 
 Please note that this is the README for borg2 / master branch.
 
-borg2 is currently in beta testing.
-
 For the stable version's docs, please see there:
 
 https://borgbackup.readthedocs.io/en/stable/
 
+Borg2 is currently in beta testing and might get major and/or
+breaking changes between beta releases (and there is no beta to
+next-beta upgrade code, so you will have to delete and re-create repos).
+
+Thus, **DO NOT USE BORG2 FOR YOUR PRODUCTION BACKUPS!** Please help with
+testing it, but set it up *additionally* to your production backups.
+
 TODO: the screencasts need a remake using borg2, see there:
 
 https://github.com/borgbackup/borg/issues/6303
@@ -64,7 +69,7 @@ Main features
 **Speed**
   * performance-critical code (chunking, compression, encryption) is
     implemented in C/Cython
-  * local caching of files/chunks index data
+  * local caching
   * quick detection of unmodified files
 
 **Data encryption**
@@ -117,9 +122,9 @@ For ease of use, set the BORG_REPO environment variable::
 
     $ export BORG_REPO=/path/to/repo
 
-Create a new backup repository (see ``borg rcreate --help`` for encryption options)::
+Create a new backup repository (see ``borg repo-create --help`` for encryption options)::
 
-    $ borg rcreate -e repokey-aes-ocb
+    $ borg repo-create -e repokey-aes-ocb
 
 Create a new backup archive::
 

borgbackup-2.0.0b10/docs/binaries/00_README.txt

@@ -0,0 +1,78 @@
+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)
+                    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.4.x or 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-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-freebsd14.asc borg-freebsd14
+
+The files are signed by:
+
+Thomas Waldmann <tw@waldmann-edv.de>
+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
+

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/docs/borg_theme/css/borg.css

@@ -52,8 +52,7 @@ h1 {
 }
 
 .container.experimental,
-#debugging-facilities,
-#borg-recreate {
+#debugging-facilities {
     /* don't change text dimensions */
     margin: 0 -30px; /* padding below + border width */
     padding: 0 10px; /* 10 px visual margin between edge of text and the border */

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/docs/changes.rst

@@ -12,8 +12,8 @@ This section provides information about security and corruption issues.
 Upgrade Notes
 =============
 
-borg 1.2.x to borg 2.0
-----------------------
+borg 1.2.x/1.4.x to borg 2.0
+----------------------------
 
 Compatibility notes:
 
@@ -21,11 +21,11 @@ Compatibility notes:
 
   We tried to put all the necessary "breaking" changes into this release, so we
   hopefully do not need another breaking release in the near future. The changes
-  were necessary for improved security, improved speed, unblocking future
-  improvements, getting rid of legacy crap / design limitations, having less and
-  simpler code to maintain.
+  were necessary for improved security, improved speed and parallelism,
+  unblocking future improvements, getting rid of legacy crap and design
+  limitations, having less and simpler code to maintain.
 
-  You can use "borg transfer" to transfer archives from borg 1.1/1.2 repos to
+  You can use "borg transfer" to transfer archives from borg 1.2/1.4 repos to
   a new borg 2.0 repo, but it will need some time and space.
 
   Before using "borg transfer", you must have upgraded to borg >= 1.2.6 (or
@@ -58,10 +58,12 @@ Compatibility notes:
 
     - borg 2 repo commands:
 
-      - borg rcreate  # "repo create", was: borg init
-      - borg rlist  # "repo list"
-      - borg rinfo  # "repo info"
-      - borg rdelete  # "repo delete"
+      - borg repo-create  # was: borg init
+      - borg repo-list
+      - borg repo-info
+      - borg repo-delete
+      - borg repo-compress
+      - borg repo-space
     - borg 2 archive commands:
 
       - borg create ARCHIVE ...
@@ -84,6 +86,8 @@ Compatibility notes:
   - removed --nobsdflags (use --noflags)
   - removed --noatime (default now, see also --atime)
   - removed --save-space option (does not change behaviour)
+- removed --bypass-lock option
+- removed borg config command (only worked locally anyway)
 - using --list together with --progress is now disallowed (except with --log-json), #7219
 - the --glob-archives option was renamed to --match-archives (the short option
   name -a is unchanged) and extended to support different pattern styles:
@@ -114,14 +118,13 @@ Compatibility notes:
   fail now that somehow "worked" before (but maybe didn't work as intended due to
   the contradicting options).
 
-
 .. _changelog:
 
 Change Log 2.x
 ==============
 
-Version 2.0.0b8 (2024-02-20)
-----------------------------
+Version 2.0.0b10 (2024-09-09)
+-----------------------------
 
 Please note:
 
@@ -130,6 +133,99 @@ This is a beta release, only for testing - do not use for production repos.
 For upgrade and compatibility hints, please also read the section "Upgrade Notes"
 above.
 
+TL;DR: this is a huge change and the first very fundamental change in how borg
+works since ever:
+
+- you will need to create new repos.
+- likely more exciting than previous betas, definitely not for production.
+- remove "borg check --repair --archives-only" from your script in case you
+  added that for b9. "borg compact -v" now finds and deletes orphan chunks
+  and also outputs some new stats.
+
+New features:
+
+- borgstore based repository, file:, ssh: and sftp: for now, more possible.
+- repository stores objects separately now, not using segment files.
+  this has more fs overhead, but needs much less I/O because no segment
+  files compaction is required anymore. also, no repository index is
+  needed anymore because we can directly find the objects by their ID.
+- locking: new borgstore based repository locking with automatic stale
+  lock removal (if lock does not get refreshed, if lock owner process is dead).
+- simultaneous repository access for many borg commands except check/compact.
+  the cache lock for adhocwithfiles is still exclusive though, so use
+  BORG_CACHE_IMPL=adhoc if you want to try that out using only 1 machine
+  and 1 user (that implementation doesn't use a cache lock). When using
+  multiple client machines or users, it also works with the default cache.
+- delete/prune: much quicker now and can be undone.
+- check --repair --undelete-archives: bring archives back from the dead.
+- repo-space: manage reserved space in repository (avoid dead-end situation if
+  repository filesystem runs full).
+
+Bugs/issues fixed:
+
+- a lot! all linked from PR #8332.
+
+Other changes:
+
+- repository: remove transactions, solved differently and much simpler now
+  (convergence and write order primarily).
+- repository: replaced precise reference counting with "object exists in repo?"
+  and "garbage collection of unused objects".
+- cache: remove transactions, remove chunks cache.
+  removed LocalCache, BORG_CACHE_IMPL=local, solving all related issues.
+  as in beta 9, adhowwithfiles is the default implementation.
+- compact: needs the borg key now (run it clientside), -v gives nice stats.
+- transfer: archive transfers from borg 1.x need the --from-borg1 option
+- check: reimplemented / bigger changes.
+- code: got rid of a metric ton of not needed complexity.
+  when borg does not need to read borg 1.x repos/archives anymore, after
+  users have transferred their archives, even much more can be removed.
+- docs: updated / removed outdated stuff
+- renamed r* commands to repo-*
+
+
+Version 2.0.0b9 (2024-07-20)
+----------------------------
+
+New features:
+
+- add BORG_CACHE_IMPL, default is "adhocwithfiles" to test the new cache
+  implementation, featuring an adhoc non-persistent chunks cache and a
+  persistent files cache. See the docs for other values.
+
+  Requires to run "borg check --repair --archives-only" to delete orphaned
+  chunks before running "borg compact" to free space! These orphans are
+  expected due to the simplified refcounting with the AdHocFilesCache.
+- make BORG_EXIT_CODES="modern" the default, #8110
+- add BORG_USE_CHUNKS_ARCHIVE env var, #8280
+- automatically rebuild cache on exception, #5213
+
+Bug fixes:
+
+- fix Ctrl-C / SIGINT behaviour for pyinstaller-made binaries, #8155
+- delete: fix error handling with Ctrl-C
+- rcompress: fix error handling with Ctrl-C
+- delete: fix error handling when no archive is specified, #8256
+- setup.py: fix import error reporting for cythonize import, see #8208
+- create: deal with EBUSY, #8123
+- benchmark: inherit options --rsh --remote-path, #8099
+- benchmark: fix return value, #8113
+- key export: fix crash when no path is given, fix exception handling
+
+Other changes:
+
+- setup.py: detect noexec build fs issue, see #8208
+- improve acl_get / acl_set error handling (forward port from 1.4-maint)
+- allow msgpack 1.1.0
+- vagrant: use pyinstaller 6.7.0
+- use Python 3.11.9 for binary builds
+- require Cython 3.0.3 at least, #8133
+- docs: add non-root deployment strategy
+
+
+Version 2.0.0b8 (2024-02-20)
+----------------------------
+
 New features:
 
 - create: add the slashdot hack, update docs, #4685

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/docs/changes_1.x.rst

@@ -3469,7 +3469,7 @@ Other changes:
   - archiver tests: add check_cache tool - lints refcounts
 
 - fixed cache sync performance regression from 1.1.0b1 onwards, #1940
-- syncing the cache without chunks.archive.d (see :ref:`disable_archive_chunks`)
+- syncing the cache without chunks.archive.d
   now avoids any merges and is thus faster, #1940
 - borg check --verify-data: faster due to linear on-disk-order scan
 - borg debug-xxx commands removed, we use "debug xxx" subcommands now, #1627

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/docs/deployment/automated-local.rst

@@ -105,7 +105,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
     #
 
     # Options for borg create
-    BORG_OPTS="--stats --one-file-system --compression lz4 --checkpoint-interval 86400"
+    BORG_OPTS="--stats --one-file-system --compression lz4"
 
     # Set BORG_PASSPHRASE or BORG_PASSCOMMAND somewhere around here, using export,
     # if encryption is used.
@@ -150,7 +150,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
     fi
 
 Create the ``/etc/backups/autoeject`` file to have the script automatically eject the drive
-after creating the backup. Rename the file to something else (e.g. ``/etc/backup/autoeject-no``)
+after creating the backup. Rename the file to something else (e.g. ``/etc/backups/autoeject-no``)
 when you want to do something with the drive after creating backups (e.g running check).
 
 Create the ``/etc/backups/backup-suspend`` file if the machine should suspend after completing
@@ -177,7 +177,7 @@ Find the UUID of the file system that backups should be stored on::
 
     lsblk -o+uuid,label
 
-Note the UUID into the ``/etc/backup/backup.disks`` file.
+Note the UUID into the ``/etc/backups/backup.disks`` file.
 
 Mount the drive to /mnt/backup.
 
@@ -198,7 +198,7 @@ Security considerations
 -----------------------
 
 The script as shown above will mount any file system with an UUID listed in
-``/etc/backup/backup.disks``. The UUID check is a safety / annoyance-reduction
+``/etc/backups/backup.disks``. The UUID check is a safety / annoyance-reduction
 mechanism to keep the script from blowing up whenever a random USB thumb drive is connected.
 It is not meant as a security mechanism. Mounting file systems and reading repository
 data exposes additional attack surfaces (kernel file system drivers,

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/docs/deployment/hosting-repositories.rst

@@ -68,8 +68,6 @@ can be filled to the specified quota.
 If storage quotas are used, ensure that all deployed Borg releases
 support storage quotas.
 
-Refer to :ref:`internals_storage_quota` for more details on storage quotas.
-
 **Specificities: Append-only repositories**
 
 Running ``borg init`` via a ``borg serve --append-only`` server will **not**

borgbackup-2.0.0b10/docs/deployment/non-root-user.rst

@@ -0,0 +1,66 @@
+.. include:: ../global.rst.inc
+.. highlight:: none
+.. _non_root_user:
+
+================================
+Backing up using a non-root user
+================================
+
+This section describes how to run borg as a non-root user and still be able to
+backup every file on the system.
+
+Normally borg is run as the root user to bypass all filesystem permissions and
+be able to read all files. But in theory this also allows borg to modify or
+delete files on your system, in case of a bug for example.
+
+To eliminate this possibility, we can run borg as a non-root user and give it read-only
+permissions to all files on the system.
+
+
+Using Linux capabilities inside a systemd service
+=================================================
+
+One way to do so, is to use linux `capabilities
+<https://man7.org/linux/man-pages/man7/capabilities.7.html>`_ within a systemd
+service.
+
+Linux capabilities allow us to give parts of the privileges the root user has to
+a non-root user. This works on a per-thread level and does not give the permission
+to the non-root user as a whole.
+
+For this we need to run our backup script from a systemd service and use the `AmbientCapabilities
+<https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#AmbientCapabilities=>`_
+option added in systemd 229.
+
+A very basic unit file would look like this:
+
+::
+
+    [Unit]
+    Description=Borg Backup
+
+    [Service]
+    Type=oneshot
+    User=borg
+    ExecStart=/usr/local/sbin/backup.sh
+
+    AmbientCapabilities=CAP_DAC_READ_SEARCH
+
+The ``CAP_DAC_READ_SEARCH`` capability gives borg read-only access to all files and directories on the system.
+
+This service can then be started manually using ``systemctl start``, a systemd timer or other methods.
+
+Restore considerations
+======================
+
+When restoring files, the root user should be used. When using the non-root user, borg extract will
+change all files to be owned by the non-root user. Using borg mount will not allow the non-root user
+to access files that it would not have access to on the system itself.
+
+Other than that, the same restore process, that would be used when running the backup as root, can be used.
+
+.. warning::
+
+    When using a local repo and running borg commands as root, make sure to only use commands that do not
+    modify the repo itself, like extract or mount. Modifying the repo using the root user will break
+    the repo for the non-root user, since some files inside the repo will now be owned by root.

{borgbackup-2.0.0b8 → borgbackup-2.0.0b10}/docs/deployment.rst

@@ -14,3 +14,4 @@ This chapter details deployment strategies for the following scenarios.
    deployment/automated-local
    deployment/image-backup
    deployment/pull-backup
+   deployment/non-root-user