From 5f10b1b2ca6bad521a4638128a0ff1cc3259063c Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Sun, 28 Apr 2024 16:55:24 -0700 Subject: [PATCH] Clarify database limitations. --- docs/how-to/backup-your-databases.md | 29 ++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index 8de3af32..05c48ecb 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -437,20 +437,21 @@ 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` 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. +4. When database hooks are enabled, borgmatic instructs Borg to consume +special files (via `--read-special`) to support database dump +streaming—regardless of the value of your `read_special` configuration option. +And because this can cause Borg to hang, borgmatic also automatically excludes +special files (and symlinks to them) that Borg may get stuck on. Even so, +there are still potential edge cases 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 manually excluding +those files. And if you explicitly set the `read-special` option to `true`, +borgmatic will opt you out of the auto-exclude feature entirely, but will +still instruct Borg to consume special files—you will just be on your own to +exclude them. Prior to version +1.7.3Special files were not auto-excluded, and you were responsible for +excluding them yourself. Common directories to exclude are `/dev` and `/run`, +but that may not be exhaustive. 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