From 810b65589ff78eb8208176cdfc997fb61c633011 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Fri, 15 Nov 2024 22:23:49 -0800 Subject: [PATCH] Documentation for runtime/state directory changes (#934). --- docs/how-to/backup-your-databases.md | 59 +++++++++++++-------- docs/how-to/deal-with-very-large-backups.md | 5 ++ docs/how-to/inspect-your-backups.md | 8 +-- 3 files changed, 46 insertions(+), 26 deletions(-) diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index f2162754..57eb68df 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -63,28 +63,9 @@ dump formats, which can't stream and therefore do consume temporary disk space. Additionally, prior to borgmatic 1.5.3, all database dumps consumed temporary disk space.) -New in version 1.9.0 To support -this, borgmatic creates temporary streaming database dumps within -`/run/user/$UID/borgmatic` by default (where `$UID` is the current user's ID). -To customize the `/run/user/$UID` portion of this path, set the -`user_runtime_directory` option in borgmatic's configuration. Alternatively, -set the `XDG_RUNTIME_DIR` environment variable (often already set to -`/run/user/$UID`). - -Prior to version 1.9.0 -borgmatic created temporary streaming database dumps within the `~/.borgmatic` -directory by default. At that time, the path was configurable by the -`borgmatic_source_directory` configuration option (now deprecated). - -New in version 1.9.1In addition -to `XDG_RUNTIME_DIR`, borgmatic also uses the `TMPDIR` or `TEMP` environment -variable if set. `TMPDIR` is available on macOS, while `TEMP` is often -available on other platforms. - -Also note that using a database hook implicitly enables the -`read_special` configuration option (even if it's disabled in your -configuration) to support this dump and restore streaming. See Limitations -below for more on this. +Also note that using a database hook implicitly enables the `read_special` +configuration option (even if it's disabled in your configuration) to support +this dump and restore streaming. See Limitations below for more on this. Here's a more involved example that connects to remote databases: @@ -132,6 +113,40 @@ additional customization of the options passed to database commands (when listing databases, restoring databases, etc.). +### Runtime directory + +New in version 1.9.0 To support +streaming database dumps to Borg, borgmatic uses a runtime directory for +temporary file storage, probing the following locations (in order) to find it: + + 1. The `user_runtime_directory` borgmatic configuration option. + 2. The `XDG_RUNTIME_DIR` environment variable, usually `/run/user/$UID` + (where `$UID` is the current user's ID), automatically set by PAM on Linux + for a user with a session. + 3. New in version 1.9.2The + `RUNTIME_DIRECTORY` environment variable, set by systemd if + `RuntimeDirectory=borgmatic` is added to borgmatic's systemd service file. + 4. New in version 1.9.1The + `TMPDIR` environment variable, set on macOS for a user with a session, + among other operating systems. + 5. New in version 1.9.1The + `TEMP` environment variable, set on various systems. + 6. New in version 1.9.2 + Hard-coded `/tmp`. Prior to + version 1.9.2This was instead hard-coded to `/run/user/$UID`. + +Regardless of the runtime directory selected, borgmatic stores its files +within a `borgmatic` subdirectory of the runtime directory. Additionally, in +the case of `TMPDIR`, `TEMP`, and the hard-coded `/tmp`, borgmatic creates a +randomly named subdirectory in an effort to reduce path collisions in shared +system temporary directories. + +Prior to version 1.9.0 +borgmatic created temporary streaming database dumps within the `~/.borgmatic` +directory by default. At that time, the path was configurable by the +`borgmatic_source_directory` configuration option (now deprecated). + + ### All databases If you want to dump all databases on a host, use `all` for the database name: diff --git a/docs/how-to/deal-with-very-large-backups.md b/docs/how-to/deal-with-very-large-backups.md index fbef5912..7c76766d 100644 --- a/docs/how-to/deal-with-very-large-backups.md +++ b/docs/how-to/deal-with-very-large-backups.md @@ -240,6 +240,11 @@ this frequency logic, borgmatic records check timestamps within the portion of this path, set the `user_state_directory` configuration option. Alternatively, set the `XDG_STATE_HOME` environment variable. +New in version 1.9.2The +`STATE_DIRECTORY` environment variable also works for this purpose. It's set +by systemd if `StateDirectory=borgmatic` is added to borgmatic's systemd +serivce file. + Prior to version 1.9.0 borgmatic recorded check timestamps within the `~/.borgmatic` directory. At that time, the path was configurable by the `borgmatic_source_directory` diff --git a/docs/how-to/inspect-your-backups.md b/docs/how-to/inspect-your-backups.md index 8b3676db..e28dc807 100644 --- a/docs/how-to/inspect-your-backups.md +++ b/docs/how-to/inspect-your-backups.md @@ -119,10 +119,10 @@ archive, regardless of the user who performs the backup. (Note that Borg doesn't store the leading `/`.) With Borg version 1.2 and -earlierDatabase dump files are stored at `/var/run/$UID/borgmatic` -(where `$UID` is the current user's ID) unless overridden by the -`user_runtime_directory` configuration option or the `XDG_STATE_HOME` -environment variable. +earlierDatabase dump files are stored at a path dependent on the +[runtime +directory](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#runtime-directory) +in use at the time the archive was created. Prior to borgmatic version 1.9.0Database dump files were instead stored at `~/.borgmatic` within