From 25796c96191433112f5463e08667b5dd7f175d96 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 24 Oct 2026 21:24:04 +0200 Subject: [PATCH] docs: automated-local: support multiple backup drives, fixes #9834 The udev rule matched a single partition table UUID, so only the first backup drive started the backup service, although run.sh accepts every file system UUID listed in backup.disks. Match on the file system UUID (the same UUID as in backup.disks) instead, document one rule line per backup drive (or "|" alternatives) and add the udev rule step to "Adding backup hard drives". Co-Authored-By: Claude Opus 5.5 --- docs/deployment/automated-local.rst | 34 +++++++++++++++++------------ 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/deployment/automated-local.rst b/docs/deployment/automated-local.rst index 839f039fc1..db240baaab 100644 --- a/docs/deployment/automated-local.rst +++ b/docs/deployment/automated-local.rst @@ -14,10 +14,10 @@ systemd and udev. Overview -------- -A udev rule is created to trigger on the addition of block devices. The rule contains a tag -that causes systemd to start a oneshot service. The oneshot service executes a script in -the standard systemd service environment, which automatically captures stdout/stderr and -logs it to the journal. +A udev rule is created to trigger on the addition of a file system on one of your registered +backup drives. The rule contains a tag that causes systemd to start a oneshot service. The +oneshot service executes a script in the standard systemd service environment, which +automatically captures stdout/stderr and logs it to the journal. The script mounts the added block device, if it is a registered backup drive, and creates backups on it. When done, it optionally unmounts the file system and spins the drive down, @@ -29,12 +29,16 @@ Configuring the system First, create the ``/etc/backups`` directory (as root). All configuration goes into this directory. -Find out the ID of the partition table of your backup disk (here assumed to be /dev/sdz): - lsblk --fs -o +PTUUID /dev/sdz +Then, create an empty ``/etc/backups/80-backup.rules`` file. It will contain one line per +backup drive, which you will add when adding backup drives (see below). Each line looks like +this (all on one line):: -Then, create ``/etc/backups/80-backup.rules`` with the following content (all on one line):: + ACTION=="add", SUBSYSTEM=="block", ENV{ID_FS_UUID}=="", TAG+="systemd", ENV{SYSTEMD_WANTS}+="automatic-backup.service" - ACTION=="add", SUBSYSTEM=="block", ENV{ID_PART_TABLE_UUID}=="", TAG+="systemd", ENV{SYSTEMD_WANTS}+="automatic-backup.service" +The rule matches the file system on the backup drive by its UUID, which is the same UUID +that you will also record in ``/etc/backups/backup.disks``. A single line can also match +several backup drives, if you separate their UUIDs with ``|``, e.g. +``ENV{ID_FS_UUID}=="|"``. The "systemd" tag in conjunction with the SYSTEMD_WANTS environment variable causes systemd to launch the "automatic-backup" service, which we will create next, as the file @@ -53,12 +57,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.). #!/bin/bash -ue - # The udev rule is not terribly accurate and may trigger our service before - # the kernel has finished probing partitions. Sleep for a bit to ensure - # the kernel is done. - # - # This can be avoided by using a more precise udev rule, e.g. matching - # a specific hardware path and partition. + # Give the system a moment to settle after the backup drive was connected. sleep 5 # @@ -179,6 +178,13 @@ Find the UUID of the file system that backups should be stored on:: Note the UUID into the ``/etc/backups/backup.disks`` file. +Add a line for this UUID to ``/etc/backups/80-backup.rules`` (see above), so that connecting +the drive starts the ``automatic-backup`` service, and reload the udev rules:: + + udevadm control --reload + +Every backup drive needs both: its UUID in ``backup.disks`` and a matching udev rule. + Mount the drive to /mnt/backup. Initialize a Borg repository at the location indicated by ``TARGET``::