cleanups

Author: ThomasWaldmann

docs/changes.rst

@@ -168,20 +168,7 @@ above.
 
 New features:
 
-- monitoring: ``borg create`` and ``borg prune`` now append a signed-and-encrypted state
-  report into the repository's ``monitoring/`` namespace (append-only, one object per run,
-  named by publish time). The new ``borg monitor`` command reads, verifies and decrypts
-  the reports from the (untrusted) repository server without the repository passphrase and
-  prints, per archive series and per maintenance command, the latest status and freshness
-  - so a later successful backup of one series cannot mask an earlier failed backup of
-  another. Restrict with ``--name`` (one series) or ``--command``. It exits non-zero if any
-  unit is missing, stale (older than ``--max-age``), unsigned or unsuccessful - so it can
-  drive alerting like a dead man's switch. ``--keep=N`` (default 500) deletes all but the N
-  newest report objects after reading (needs delete permission on the monitoring
-  namespace). All key material is derived from the existing borg key; run ``borg monitor
-  --key`` once on a host that has the key to obtain ``BORG_MONITORING_KEY`` for the
-  monitoring host. Reports are signed with Ed25519 and sealed with HPKE (RFC 9180), so the
-  server can neither forge nor read them, only relay them. Requires OpenSSL >= 3.2.
+- monitor: access encrypted/signed monitoring data in the repository, #9788
 - repo-create: split ``--encryption`` into orthogonal options. ``--encryption`` now
   selects only the cipher / AE algorithm (``none``, ``authenticated``, ``aes256-ocb``
   or ``chacha20-poly1305``), the new ``--id-hash`` selects the id hash function

docs/usage/general/environment.rst.inc

@@ -257,11 +257,12 @@ Directories and files:
         - you need to give a different path for different repositories.
         - you need to point to the correct key file matching the repository the command will operate on.
     BORG_MONITORING_KEY
-        Used by ``borg monitor`` (without ``--key``) on the monitoring host to verify and
-        decrypt the report a backup client published into the repository. Obtain its value
-        once, on a host that has the borg key, via ``borg monitor --key``. It only allows
-        verifying and decrypting reports, not creating them, and it does not grant access
-        to the backup data.
+        Used by ``borg monitor`` on the monitoring host to verify and decrypt
+        the reports backup clients published into the repository.
+        You can get the correct key value by running ``borg monitor --key`` on
+        a host that has access to the borg key.
+        This key can not be used to create reports, nor does it grant access
+        to backup data.
     TMPDIR
         This is where temporary files are stored (might need a lot of temporary space for some
         operations), see tempfile_ for details.

src/borg/archiver/create_cmd.py

@@ -10,6 +10,7 @@
 
 from ._common import with_repository, Highlander
 from .. import helpers
+from .. import monitoring
 from ..archive import Archive, is_special, SF_DATALESS
 from ..archive import BackupError, BackupOSError, BackupItemExcluded, backup_io, OsOpen, stat_update_check
 from ..archive import FilesystemObjectProcessors, MetadataCollector, ChunksProcessor
@@ -287,10 +288,6 @@ def create_inner(archive, cache, fso):
                     files_changed=args.files_changed,
                 )
                 create_inner(archive, cache, fso)
-                # Publish the monitoring report as the last action while the store is
-                # still open. The RC is only best-known here (a failure after this point
-                # won't be reflected); see borg/monitoring.py.
-                from .. import monitoring
 
                 monitoring.publish_command_report(
                     repository,
@@ -300,7 +297,7 @@ def create_inner(archive, cache, fso):
                     archive_id=archive.id,
                     stats=archive.stats.as_dict(),
                 )
-        else:
+        else:  # dry-run
             create_inner(None, None, None)
 
     def _process_any(self, *, path, parent_fd, name, st, fso, cache, read_special, dry_run, strip_prefix):

src/borg/archiver/monitor_cmd.py

@@ -34,10 +34,9 @@ def do_monitor(self, args, repository):
         series) or --command (e.g. create or prune). Neither the repository passphrase nor
         the borg key is needed for reading.
 
-        Reports accumulate as append-only objects; --keep=N deletes all but the N newest
-        after reading (this needs delete permission on the monitoring namespace).
+        Reports accumulate over time; --keep=N deletes all but the N newest after reading.
 
-        With --key (which does need the borg key) it instead derives and prints the
+        With --key (which does need the borg key), it derives and prints the
         BORG_MONITORING_KEY value for this repository, to be configured on the monitoring
         host. The printed value only allows verifying and decrypting reports, not creating
         them.
@@ -138,21 +137,19 @@ def build_parser_monitor(self, subparsers, common_parser, mid_common_parser):
 
         monitor_epilog = process_epilog(
             """
-        Read or export trusted monitoring state of a repository.
+        Read trusted monitoring state of a repository.
 
-        Backup-side commands publish a small signed-and-encrypted state report into the
-        repository after each run. Because each report is signed with a key derived from
-        the borg key, the (untrusted) repository server can neither forge nor read it - it
-        can only relay it. A monitoring system can therefore pull and verify the reports
-        from the same server without the repository passphrase.
+        Borg client commands publish a signed-and-encrypted state report into the
+        repository after each run. Only borg monitor can read these reports using
+        the monitoring key.
 
         Setup (once, on a host that has the borg key)::
 
-            BORG_MONITORING_KEY=$(borg monitor --key)
+            borg monitor --key  # this outputs the monitoring key
 
-        Then, on the monitoring host, with that value exported as BORG_MONITORING_KEY::
+        Then, on the monitoring host::
 
-            borg monitor
+            BORG_MONITORING_KEY=<that key> borg monitor
 
         This verifies and decrypts the reports and prints, per archive series (and per
         maintenance command), the latest status and its age. It exits with a non-zero code
@@ -199,6 +196,6 @@ def build_parser_monitor(self, subparsers, common_parser, mid_common_parser):
             default=monitoring.DEFAULT_KEEP,
             metavar="N",
             help="after reading, delete all but the N newest report objects "
-            f"(needs delete permission; 0 = do not clean up; default: {monitoring.DEFAULT_KEEP})",
+            f"(0 = do not clean up; default: {monitoring.DEFAULT_KEEP})",
         )
         subparser.add_argument("--json", action="store_true", help="format output as JSON")

src/borg/archiver/prune_cmd.py

@@ -4,6 +4,7 @@
 from operator import attrgetter
 import os
 
+from .. import monitoring
 from ._common import with_repository, Highlander
 from ..constants import *  # NOQA
 from ..helpers import ArchiveFormatter, interval, sig_int, ProgressIndicatorPercent, CommandError, Error
@@ -233,9 +234,6 @@ def do_prune(self, args, repository, manifest):
             raise Error("Got Ctrl-C / SIGINT.")
 
         if not args.dry_run:
-            # Publish the monitoring report as the last action while the store is open.
-            from .. import monitoring
-
             monitoring.publish_command_report(
                 repository,
                 manifest.key,

src/borg/crypto/monitoring.py

@@ -50,8 +50,8 @@ def _derive_seed(key, domain):
 def client_material(key):
     """Client half: (ed25519_sign_seed, hpke_recipient_public).
 
-    Used by the publishing side to sign with the Ed25519 secret seed and seal to the
-    monitor's HPKE public key.
+    Used by the publishing side to sign with the Ed25519 secret seed and seal
+    to the monitor's HPKE public key.
     """
     sign_seed = _derive_seed(key, SIGN_DOMAIN)
     seal_seed = _derive_seed(key, SEAL_DOMAIN)
@@ -62,8 +62,8 @@ def client_material(key):
 def monitor_material(key):
     """Monitor half: (ed25519_verify_public, hpke_recipient_secret).
 
-    This is everything the monitoring system needs to verify + decrypt and nothing more:
-    it cannot derive the signing secret or the borg key from it.
+    This is everything the monitoring system needs to verify and decrypt and
+    nothing more: it cannot derive the signing secret or the borg key from it.
     """
     sign_seed = _derive_seed(key, SIGN_DOMAIN)
     seal_seed = _derive_seed(key, SEAL_DOMAIN)

src/borg/monitoring.py

@@ -23,9 +23,14 @@
 import time
 from binascii import hexlify
 
+from borgstore.store import ItemInfo
+from borgstore.store import ObjectNotFound as StoreObjectNotFound
+
 from . import __version__
 from .constants import EXIT_SUCCESS, EXIT_WARNING, EXIT_WARNING_BASE, EXIT_SIGNAL_BASE
 from .crypto import monitoring as mon_crypto
+from .helpers import bin_to_hex, get_ec
+from .helpers.time import archive_ts_now
 
 logger = logging.getLogger(__name__)
 
@@ -135,9 +140,6 @@ def publish_command_report(repository, key, command, *, archive=None, archive_id
     after the store is closed; see borg/monitoring.py). Call this as the last action while
     the store is still open. *archive_id* is binary; it is hex-encoded for the report.
     """
-    from .helpers import bin_to_hex, get_ec
-    from .helpers.time import archive_ts_now
-
     report = build_report(
         command=command,
         repo_id=bin_to_hex(repository.id),
@@ -152,8 +154,6 @@ def publish_command_report(repository, key, command, *, archive=None, archive_id
 
 def list_names(repository):
     """Return all monitoring object names, oldest first (names sort chronologically)."""
-    from borgstore.store import ItemInfo
-
     names = [ItemInfo(*info).name for info in repository.store_list(STORE_NAMESPACE)]
     names.sort()
     return names
@@ -165,8 +165,6 @@ def iter_reports(repository, monitor_key):
     Each report is verified and decrypted; an unverifiable one raises (it is not silently
     skipped) so tampering surfaces.
     """
-    from borgstore.store import ObjectNotFound as StoreObjectNotFound
-
     for name in list_names(repository):
         try:
             data = repository.store_load(f"{STORE_NAMESPACE}/{name}")
@@ -181,8 +179,6 @@ def prune_reports(repository, keep):
     Needs delete permission on the monitoring namespace; on a permission error (e.g. a
     read-only monitoring host) it warns and stops rather than failing the command.
     """
-    from borgstore.store import ObjectNotFound as StoreObjectNotFound
-
     if keep is None or keep <= 0:
         return 0  # 0 (or negative) disables cleanup
     names = list_names(repository)