From 058af95d7099b7298f5f5336217d3c682996afa9 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Sat, 20 Apr 2024 14:53:41 -0700 Subject: [PATCH] Document limitation about using database hooks and "one_file_system" (#853). --- docs/how-to/backup-your-databases.md | 34 +++++++++++++++++----------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index dfb57cb..8de3af3 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -437,19 +437,27 @@ borgmatic's own configuration file. So include your configuration file in backups to avoid getting caught without a way to restore a database. 3. borgmatic does not currently support backing up or restoring multiple databases that share the exact same name on different hosts. -4. Because database hooks implicitly enable the `read_special` configuration, -any special files are excluded from backups (named pipes, block devices, -character devices, and sockets) to prevent hanging. Try a command like `find -/your/source/path -type b -or -type c -or -type p -or -type s` to find such -files. Common directories to exclude are `/dev` and `/run`, but that may not -be exhaustive. New in version -1.7.3 When database hooks are enabled, borgmatic automatically excludes -special files (and symlinks to special files) that may cause Borg to hang, so -generally you no longer need to manually exclude them. There are potential -edge cases though in which applications on your system create new special files -*after* borgmatic constructs its exclude list, resulting in Borg hangs. If that -occurs, you can resort to the manual excludes described above. And to opt out -of the auto-exclude feature entirely, explicitly set `read_special` to true. +4. Because database hooks implicitly enable the `read_special` option, any +special files are excluded from backups (named pipes, block devices, +character devices, and sockets) to prevent hanging. Try a command like +`find /your/source/path -type b -or -type c -or -type p -or -type s` to +find such files. Common directories to exclude are `/dev` and `/run`, but +that may not be exhaustive. New in +version 1.7.3 When database hooks are enabled, borgmatic +automatically excludes special files (and symlinks to special files) that +may cause Borg to hang, so generally you no longer need to manually exclude +them. There are potential edge cases though in which applications on your +system create new special files *after* borgmatic constructs its exclude +list, resulting in Borg hangs. If that occurs, you can resort to the manual +excludes described above. And to opt out of the auto-exclude feature +entirely, explicitly set `read_special` to true. +5. Database hooks also implicitly enable the `one_file_system` option, which +means Borg won't cross filesystem boundaries when looking for files to backup. +This is especially important when running borgmatic in a container, as +container volumes are mounted as separate filesystems. One work-around is to +explicitly add each mounted volume you'd like to backup to +`source_directories` instead of relying on Borg to include them implicitly via +a parent directory. ### Manual restoration