From 2453ecad424c713403dabf4c276333ff4a65d4cd Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Tue, 11 Jul 2023 22:10:57 -0700 Subject: [PATCH] More documentation updates based on section removal (#721). --- .../_includes/components/suggestion-link.html | 4 +- ...reparation-and-cleanup-steps-to-backups.md | 60 ++++---- ...movable-drive-or-an-intermittent-server.md | 20 +-- docs/how-to/backup-your-databases.md | 141 +++++++++--------- docs/how-to/deal-with-very-large-backups.md | 32 ++-- docs/how-to/develop-on-borgmatic.md | 6 +- docs/how-to/inspect-your-backups.md | 2 +- docs/how-to/make-per-application-backups.md | 80 +++++----- docs/how-to/monitor-your-backups.md | 94 +++++++----- docs/how-to/provide-your-passwords.md | 22 +-- docs/how-to/upgrade.md | 12 +- docs/reference/command-line.md | 2 +- 12 files changed, 243 insertions(+), 232 deletions(-) diff --git a/docs/_includes/components/suggestion-link.html b/docs/_includes/components/suggestion-link.html index 2c2d142..073b888 100644 --- a/docs/_includes/components/suggestion-link.html +++ b/docs/_includes/components/suggestion-link.html @@ -1,5 +1,5 @@

Improve this documentation

Have an idea on how to make this documentation even better? Use our issue tracker to send your -feedback!

+href="https://torsion.org/borgmatic/#support-and-contributing">issue +tracker to send your feedback!

diff --git a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md index eeba2e0..37806f2 100644 --- a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md +++ b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md @@ -21,11 +21,10 @@ running backups, and specify `after_backup` hooks to perform cleanup steps afterwards. Here's an example: ```yaml -hooks: - before_backup: - - mount /some/filesystem - after_backup: - - umount /some/filesystem +before_backup: + - mount /some/filesystem +after_backup: + - umount /some/filesystem ``` If your command contains a special YAML character such as a colon, you may @@ -33,11 +32,23 @@ need to quote the entire string (or use a [multiline string](https://yaml-multiline.info/)) to avoid an error: ```yaml -hooks: - before_backup: - - "echo Backup: start" +before_backup: + - "echo Backup: start" ``` +There are additional hooks that run before/after other actions as well. For +instance, `before_prune` runs before a `prune` action for a repository, while +`after_prune` runs after it. + +Prior to version 1.8.0 Put +these options in the `hooks:` section of your configuration. + +New in version 1.7.0 The +`before_actions` and `after_actions` hooks run before/after all the actions +(like `create`, `prune`, etc.) for each repository. These hooks are a good +place to run per-repository steps like mounting/unmounting a remote +filesystem. + New in version 1.6.0 The `before_backup` and `after_backup` hooks each run once per repository in a configuration file. `before_backup` hooks runs right before the `create` @@ -46,16 +57,6 @@ but not if an error occurs in a previous hook or in the backups themselves. (Prior to borgmatic 1.6.0, these hooks instead ran once per configuration file rather than once per repository.) -There are additional hooks that run before/after other actions as well. For -instance, `before_prune` runs before a `prune` action for a repository, while -`after_prune` runs after it. - -New in version 1.7.0 The -`before_actions` and `after_actions` hooks run before/after all the actions -(like `create`, `prune`, etc.) for each repository. These hooks are a good -place to run per-repository steps like mounting/unmounting a remote -filesystem. - ## Variable interpolation @@ -64,11 +65,13 @@ variables into the hook command. Here's an example that assumes you provide a separate shell script: ```yaml -hooks: - after_prune: - - record-prune.sh "{configuration_filename}" "{repository}" +after_prune: + - record-prune.sh "{configuration_filename}" "{repository}" ``` +Prior to version 1.8.0 Put +this option in the `hooks:` section of your configuration. + In this example, when the hook is triggered, borgmatic interpolates runtime values into the hook command: the borgmatic configuration filename and the paths of the current Borg repository. Here's the full set of supported @@ -92,13 +95,15 @@ You can also use `before_everything` and `after_everything` hooks to perform global setup or cleanup: ```yaml -hooks: - before_everything: - - set-up-stuff-globally - after_everything: - - clean-up-stuff-globally +before_everything: + - set-up-stuff-globally +after_everything: + - clean-up-stuff-globally ``` +Prior to version 1.8.0 Put +these options in the `hooks:` section of your configuration. + `before_everything` hooks collected from all borgmatic configuration files run once before all configuration files (prior to all actions), but only if there is a `create` action. An error encountered during a `before_everything` hook @@ -109,6 +114,7 @@ but only if there is a `create` action. It runs even if an error occurs during a backup or a backup hook, but not if an error occurs during a `before_everything` hook. + ## Error hooks borgmatic also runs `on_error` hooks if an error occurs, either when creating @@ -116,6 +122,7 @@ a backup or running a backup hook. See the [monitoring and alerting documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/) for more information. + ## Hook output Any output produced by your hooks shows up both at the console and in syslog @@ -123,6 +130,7 @@ Any output produced by your hooks shows up both at the console and in syslog href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/">inspecting your backups. + ## Security An important security note about hooks: borgmatic executes all hook commands diff --git a/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md b/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md index 6bcc895..a7c9b20 100644 --- a/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md +++ b/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md @@ -62,11 +62,13 @@ the external `findmnt` utility to see whether the drive is mounted before proceeding. ```yaml -hooks: - before_backup: - - findmnt /mnt/removable > /dev/null || exit 75 +before_backup: + - findmnt /mnt/removable > /dev/null || exit 75 ``` +Prior to version 1.8.0 Put this +option in the `hooks:` section of your configuration. + What this does is check if the `findmnt` command errors when probing for a particular mount point. If it does error, then it returns exit code 75 to borgmatic. borgmatic logs the soft failure, skips all further actions in that @@ -89,19 +91,11 @@ before_backup: - ping -q -c 1 buddys-server.org > /dev/null || exit 75 ``` -Prior to version 1.8.0 Put the -first two options in the `location:` section of your configuration and the -`before_backup` option within the `hooks:` section. - -Prior to version 1.7.10 Omit -the `path:` portion of the `repositories` list. - Or to only run backups if the battery level is high enough: ```yaml -hooks: - before_backup: - - is_battery_percent_at_least.sh 25 +before_backup: + - is_battery_percent_at_least.sh 25 ``` (Writing the battery script is left as an exercise to the reader.) diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index b8aeca9..4708e0a 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -18,31 +18,32 @@ prior to running backups. For example, here is everything you need to dump and backup a couple of local PostgreSQL databases and a MySQL/MariaDB database. ```yaml -hooks: - postgresql_databases: - - name: users - - name: orders - mysql_databases: - - name: posts +postgresql_databases: + - name: users + - name: orders +mysql_databases: + - name: posts ``` +Prior to version 1.8.0 Put +these and other database options in the `hooks:` section of your +configuration. + New in version 1.5.22 You can also dump MongoDB databases. For example: ```yaml -hooks: - mongodb_databases: - - name: messages +mongodb_databases: + - name: messages ``` New in version 1.7.9 Additionally, you can dump SQLite databases. For example: ```yaml -hooks: - sqlite_databases: - - name: mydb - path: /var/lib/sqlite3/mydb.sqlite +sqlite_databases: + - name: mydb + path: /var/lib/sqlite3/mydb.sqlite ``` As part of each backup, borgmatic streams a database dump for each configured @@ -54,7 +55,7 @@ temporary disk space.) To support this, borgmatic creates temporary named pipes in `~/.borgmatic` by default. To customize this path, set the `borgmatic_source_directory` option -in the `location` section of borgmatic's configuration. +in borgmatic's configuration. Also note that using a database hook implicitly enables both the `read_special` and `one_file_system` configuration settings (even if they're @@ -64,35 +65,34 @@ See Limitations below for more on this. Here's a more involved example that connects to remote databases: ```yaml -hooks: - postgresql_databases: - - name: users - hostname: database1.example.org - - name: orders - hostname: database2.example.org - port: 5433 - username: postgres - password: trustsome1 - format: tar - options: "--role=someone" - mysql_databases: - - name: posts - hostname: database3.example.org - port: 3307 - username: root - password: trustsome1 - options: "--skip-comments" - mongodb_databases: - - name: messages - hostname: database4.example.org - port: 27018 - username: dbuser - password: trustsome1 - authentication_database: mongousers - options: "--ssl" - sqlite_databases: - - name: mydb - path: /var/lib/sqlite3/mydb.sqlite +postgresql_databases: + - name: users + hostname: database1.example.org + - name: orders + hostname: database2.example.org + port: 5433 + username: postgres + password: trustsome1 + format: tar + options: "--role=someone" +mysql_databases: + - name: posts + hostname: database3.example.org + port: 3307 + username: root + password: trustsome1 + options: "--skip-comments" +mongodb_databases: + - name: messages + hostname: database4.example.org + port: 27018 + username: dbuser + password: trustsome1 + authentication_database: mongousers + options: "--ssl" +sqlite_databases: + - name: mydb + path: /var/lib/sqlite3/mydb.sqlite ``` See your [borgmatic configuration @@ -106,13 +106,12 @@ listing databases, restoring databases, etc.). If you want to dump all databases on a host, use `all` for the database name: ```yaml -hooks: - postgresql_databases: - - name: all - mysql_databases: - - name: all - mongodb_databases: - - name: all +postgresql_databases: + - name: all +mysql_databases: + - name: all +mongodb_databases: + - name: all ``` Note that you may need to use a `username` of the `postgres` superuser for @@ -120,6 +119,9 @@ this to work with PostgreSQL. The SQLite hook in particular does not consider "all" a special database name. +Prior to version 1.8.0 Put +these options in the `hooks:` section of your configuration. + New in version 1.7.6 With PostgreSQL and MySQL, you can optionally dump "all" databases to separate files instead of one combined dump file, allowing more convenient restores of @@ -127,13 +129,12 @@ individual databases. Enable this by specifying your desired database dump `format`: ```yaml -hooks: - postgresql_databases: - - name: all - format: custom - mysql_databases: - - name: all - format: sql +postgresql_databases: + - name: all + format: custom +mysql_databases: + - name: all + format: sql ``` ### Containers @@ -143,15 +144,17 @@ problem—configure borgmatic to connect to the container's name on its exposed port. For instance: ```yaml -hooks: - postgresql_databases: - - name: users - hostname: your-database-container-name - port: 5433 - username: postgres - password: trustsome1 +postgresql_databases: + - name: users + hostname: your-database-container-name + port: 5433 + username: postgres + password: trustsome1 ``` +Prior to version 1.8.0 Put +these options in the `hooks:` section of your configuration. + But what if borgmatic is running on the host? You can still connect to a database container if its ports are properly exposed to the host. For instance, when running the database container, you can specify `--publish @@ -179,8 +182,7 @@ hooks: password: trustsome1 ``` -You can alter the ports in these examples to suit your particular database -system. +Alter the ports in these examples to suit your particular database system. ### No source directories @@ -428,10 +430,9 @@ You can add any additional flags to the `options:` in your database configuration. Here's an example: ```yaml -hooks: - mysql_databases: - - name: posts - options: "--single-transaction --quick" +mysql_databases: + - name: posts + options: "--single-transaction --quick" ``` ### borgmatic hangs during backup diff --git a/docs/how-to/deal-with-very-large-backups.md b/docs/how-to/deal-with-very-large-backups.md index 48199b9..96064c1 100644 --- a/docs/how-to/deal-with-very-large-backups.md +++ b/docs/how-to/deal-with-very-large-backups.md @@ -65,19 +65,20 @@ configure borgmatic to run repository checks only. Configure this in the `consistency` section of borgmatic configuration: ```yaml -consistency: - checks: - - name: repository +checks: + - name: repository ``` +Prior to version 1.8.0 Put +this option in the `consistency:` section of your configuration. + Prior to version 1.6.2 The `checks` option was a plain list of strings without the `name:` part, and borgmatic ran each configured check every time checks were run. For example: ```yaml -consistency: - checks: - - repository +checks: + - repository ``` @@ -103,14 +104,16 @@ optionally configure checks to run on a periodic basis rather than every time borgmatic runs checks. For instance: ```yaml -consistency: - checks: - - name: repository - frequency: 2 weeks - - name: archives - frequency: 1 month +checks: + - name: repository + frequency: 2 weeks + - name: archives + frequency: 1 month ``` +Prior to version 1.8.0 Put +this option in the `consistency:` section of your configuration. + This tells borgmatic to run the `repository` consistency check at most once every two weeks for a given repository and the `archives` check at most once a month. The `frequency` value is a number followed by a unit of time, e.g. "3 @@ -173,9 +176,8 @@ this option in the `consistency:` section of your configuration. was a plain list of strings without the `name:` part. For instance: ```yaml -consistency: - checks: - - disabled +checks: + - disabled ``` If you have multiple repositories in your borgmatic configuration file, diff --git a/docs/how-to/develop-on-borgmatic.md b/docs/how-to/develop-on-borgmatic.md index 391d795..bd219bb 100644 --- a/docs/how-to/develop-on-borgmatic.md +++ b/docs/how-to/develop-on-borgmatic.md @@ -7,7 +7,7 @@ eleventyNavigation: --- ## Source code -To get set up to hack on borgmatic, first clone it via HTTPS or SSH: +To get set up to develop on borgmatic, first clone it via HTTPS or SSH: ```bash git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git @@ -21,8 +21,8 @@ git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git Then, install borgmatic "[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)" -so that you can run borgmatic commands while you're hacking on them to -make sure your changes work. +so that you can run borgmatic actions during development to make sure your +changes work. ```bash cd borgmatic diff --git a/docs/how-to/inspect-your-backups.md b/docs/how-to/inspect-your-backups.md index c1e509b..314e0c7 100644 --- a/docs/how-to/inspect-your-backups.md +++ b/docs/how-to/inspect-your-backups.md @@ -60,7 +60,7 @@ with `--format`. Refer to the [borg list --format documentation](https://borgbackup.readthedocs.io/en/stable/usage/list.html#the-format-specifier-syntax) for available values. -*(No borgmatic `list` or `info` actions? Upgrade borgmatic!)* +(No borgmatic `list` or `info` actions? Upgrade borgmatic!) New in borgmatic version 1.7.0 There are also `rlist` and `rinfo` actions for displaying repository diff --git a/docs/how-to/make-per-application-backups.md b/docs/how-to/make-per-application-backups.md index cae2fa2..62a1c3e 100644 --- a/docs/how-to/make-per-application-backups.md +++ b/docs/how-to/make-per-application-backups.md @@ -104,11 +104,12 @@ to filter archives when running supported actions. For instance, let's say that you have this in your configuration: ```yaml -storage: - ... - archive_name_format: {hostname}-user-data-{now} +archive_name_format: {hostname}-user-data-{now} ``` +Prior to version 1.8.0 Put +this option in the `storage:` section of your configuration. + borgmatic considers `{now}` an emphemeral data placeholder that will probably change per archive, while `{hostname}` won't. So it turns the example value into `{hostname}-user-data-*` and applies it to filter down the set of @@ -124,10 +125,8 @@ If this behavior isn't quite smart enough for your needs, you can use the filtering archives. For example: ```yaml -storage: - ... - archive_name_format: {hostname}-user-data-{now} - match_archives: sh:myhost-user-data-* +archive_name_format: {hostname}-user-data-{now} +match_archives: sh:myhost-user-data-* ``` For Borg 1.x, use a shell pattern for the `match_archives` value and see the @@ -190,7 +189,7 @@ When a configuration include is a relative path, borgmatic loads it from either the current working directory or from the directory containing the file doing the including. -Note that this form of include must be a YAML value rather than a key. For +Note that this form of include must be a value rather than an option name. For example, this will not work: ```yaml @@ -201,7 +200,7 @@ repositories: !include /etc/borgmatic/common_checks.yaml ``` -But if you do want to merge in a YAML key *and* its values, keep reading! +But if you do want to merge in a option name *and* its values, keep reading! ## Include merging @@ -238,11 +237,6 @@ Once this include gets merged in, the resulting configuration would have all of the options from the original configuration file *and* the options from the include. -Prior to version 1.6.0 When the -same option appeared in both the local file and the merged include, the local -file's value took precedence—meaning the included value was ignored in favor -of the local one. But see below about deep merge in version 1.6.0+. - Note that this `<<` include merging syntax is only for merging in mappings (configuration options and their values). But if you'd like to include a single value directly, please see the above about standard includes. @@ -261,29 +255,30 @@ at all levels in the two configuration files. This allows you to include common configuration—up to full borgmatic configuration files—while overriding only the parts you want to customize. -For instance, here's an example of a main configuration file that pulls in two -retention options via an include and then overrides one of them locally: +For instance, here's an example of a main configuration file that pulls in +options via an include and then overrides one of them locally: ```yaml <<: !include /etc/borgmatic/common.yaml -location: - ... +constants: + hostname: myhostname -retention: - keep_daily: 5 +repositories: + - path: repo.borg ``` This is what `common.yaml` might look like: ```yaml -retention: - keep_hourly: 24 - keep_daily: 7 +constants: + prefix: myprefix + hostname: otherhost ``` Once this include gets merged in, the resulting configuration would have a -`keep_hourly` value of `24` and an overridden `keep_daily` value of `5`. +`prefix` value of `myprefix` and an overridden `hostname` value of +`myhostname`. When there's an option collision between the local file and the merged include, the local file's option takes precedence. @@ -301,21 +296,22 @@ configuration file, you can omit it with an `!omit` tag. For instance: ```yaml <<: !include /etc/borgmatic/common.yaml -location: - source_directories: - - !omit /home - - /var +source_directories: + - !omit /home + - /var ``` And `common.yaml` like this: ```yaml -location: - source_directories: - - /home - - /etc +source_directories: + - /home + - /etc ``` +Prior to version 1.8.0 Put +this option in the `location:` section of your configuration. + Once this include gets merged in, the resulting configuration will have a `source_directories` value of `/etc` and `/var`—with `/home` omitted. @@ -328,16 +324,15 @@ an example of some things not to do: ```yaml <<: !include /etc/borgmatic/common.yaml -location: - source_directories: - # Do not do this! It will not work. "!omit" belongs before "/home". - - /home !omit +source_directories: + # Do not do this! It will not work. "!omit" belongs before "/home". + - /home !omit - # Do not do this either! "!omit" only works on scalar list items. - repositories: !omit - # Also do not do this for the same reason! This is a list item, but it's - # not a scalar. - - !omit path: repo.borg +# Do not do this either! "!omit" only works on scalar list items. +repositories: !omit + # Also do not do this for the same reason! This is a list item, but it's + # not a scalar. + - !omit path: repo.borg ``` Additionally, the `!omit` tag only works in a configuration file that also @@ -451,9 +446,6 @@ What this does is load your configuration files, and for each one, disregard the configured value for the `remote_path` option, and use the value of `/usr/local/bin/borg1` instead. -Prior to version 1.8.0 Don't -forget to specify the section (like `location:`) that any option is in. - You can even override nested values or multiple values at once. For instance: ```bash diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md index 517f9c7..2be61c6 100644 --- a/docs/how-to/monitor-your-backups.md +++ b/docs/how-to/monitor-your-backups.md @@ -89,19 +89,20 @@ notifications or take other actions, so you can get alerted as soon as something goes wrong. Here's a not-so-useful example: ```yaml -hooks: - on_error: - - echo "Error while creating a backup or running a backup hook." +on_error: + - echo "Error while creating a backup or running a backup hook." ``` +Prior to version 1.8.0 Put +this option in the `hooks:` section of your configuration. + The `on_error` hook supports interpolating particular runtime variables into the hook command. Here's an example that assumes you provide a separate shell script to handle the alerting: ```yaml -hooks: - on_error: - - send-text-message.sh "{configuration_filename}" "{repository}" +on_error: + - send-text-message.sh "{configuration_filename}" "{repository}" ``` In this example, when the error occurs, borgmatic interpolates runtime values @@ -135,11 +136,13 @@ URL" for your project. Here's an example: ```yaml -hooks: - healthchecks: - ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a +healthchecks: + ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a ``` +Prior to version 1.8.0 Put +this option in the `hooks:` section of your configuration. + With this hook in place, borgmatic pings your Healthchecks project when a backup begins, ends, or errors. Specifically, after the `before_backup` @@ -179,11 +182,13 @@ API URL" for your monitor. Here's an example: ```yaml -hooks: - cronitor: - ping_url: https://cronitor.link/d3x0c1 +cronitor: + ping_url: https://cronitor.link/d3x0c1 ``` +Prior to version 1.8.0 Put +this option in the `hooks:` section of your configuration. + With this hook in place, borgmatic pings your Cronitor monitor when a backup begins, ends, or errors. Specifically, after the `before_backup` @@ -208,11 +213,13 @@ URL" for your monitor. Here's an example: ```yaml -hooks: - cronhub: - ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031 +cronhub: + ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031 ``` +Prior to version 1.8.0 Put +this option in the `hooks:` section of your configuration. + With this hook in place, borgmatic pings your Cronhub monitor when a backup begins, ends, or errors. Specifically, after the `before_backup` @@ -251,11 +258,13 @@ Here's an example: ```yaml -hooks: - pagerduty: - integration_key: a177cad45bd374409f78906a810a3074 +pagerduty: + integration_key: a177cad45bd374409f78906a810a3074 ``` +Prior to version 1.8.0 Put +this option in the `hooks:` section of your configuration. + With this hook in place, borgmatic creates a PagerDuty event for your service whenever backups fail. Specifically, if an error occurs during a `create`, `prune`, `compact`, or `check` action, borgmatic sends an event to PagerDuty @@ -291,31 +300,34 @@ An example configuration is shown here, with all the available options, includin [tags](https://ntfy.sh/docs/publish/#tags-emojis): ```yaml -hooks: - ntfy: - topic: my-unique-topic - server: https://ntfy.my-domain.com - start: - title: A Borgmatic backup started - message: Watch this space... - tags: borgmatic - priority: min - finish: - title: A Borgmatic backup completed successfully - message: Nice! - tags: borgmatic,+1 - priority: min - fail: - title: A Borgmatic backup failed - message: You should probably fix it - tags: borgmatic,-1,skull - priority: max - states: - - start - - finish - - fail +ntfy: + topic: my-unique-topic + server: https://ntfy.my-domain.com + start: + title: A Borgmatic backup started + message: Watch this space... + tags: borgmatic + priority: min + finish: + title: A Borgmatic backup completed successfully + message: Nice! + tags: borgmatic,+1 + priority: min + fail: + title: A Borgmatic backup failed + message: You should probably fix it + tags: borgmatic,-1,skull + priority: max + states: + - start + - finish + - fail ``` +Prior to version 1.8.0 Put +the `ntfy:` option in the `hooks:` section of your configuration. + + ## Scripting borgmatic To consume the output of borgmatic in other software, you can include an diff --git a/docs/how-to/provide-your-passwords.md b/docs/how-to/provide-your-passwords.md index 76f89d8..99b56e4 100644 --- a/docs/how-to/provide-your-passwords.md +++ b/docs/how-to/provide-your-passwords.md @@ -20,10 +20,12 @@ pull your repository passphrase, your database passwords, or any other option values from environment variables. For instance: ```yaml -storage: - encryption_passphrase: ${MY_PASSPHRASE} +encryption_passphrase: ${MY_PASSPHRASE} ``` +Prior to version 1.8.0 Put +this option in the `storage:` section of your configuration. + This uses the `MY_PASSPHRASE` environment variable as your encryption passphrase. Note that the `{` `}` brackets are required. `$MY_PASSPHRASE` by itself will not work. @@ -38,12 +40,14 @@ configuration](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/) the same approach applies. For example: ```yaml -hooks: - postgresql_databases: - - name: users - password: ${MY_DATABASE_PASSWORD} +postgresql_databases: + - name: users + password: ${MY_DATABASE_PASSWORD} ``` +Prior to version 1.8.0 Put +this option in the `hooks:` section of your configuration. + This uses the `MY_DATABASE_PASSWORD` environment variable as your database password. @@ -53,8 +57,7 @@ password. If you'd like to set a default for your environment variables, you can do so with the following syntax: ```yaml -storage: - encryption_passphrase: ${MY_PASSPHRASE:-defaultpass} +encryption_passphrase: ${MY_PASSPHRASE:-defaultpass} ``` Here, "`defaultpass`" is the default passphrase if the `MY_PASSPHRASE` @@ -72,8 +75,7 @@ can escape it with a backslash. For instance, if your password is literally `${A}@!`: ```yaml -storage: - encryption_passphrase: \${A}@! +encryption_passphrase: \${A}@! ``` ### Related features diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md index 43a28cc..87e92ac 100644 --- a/docs/how-to/upgrade.md +++ b/docs/how-to/upgrade.md @@ -135,12 +135,6 @@ repositories: - path: original.borg ``` -Prior to version 1.8.0 This -option was found in the `location:` section of your configuration. - -Prior to version 1.7.10 Omit -the `path:` portion of the `repositories` list. - Change it to a new (not yet created) repository path: ```yaml @@ -148,6 +142,12 @@ repositories: - path: upgraded.borg ``` +Prior to version 1.8.0 This +option was found in the `location:` section of your configuration. + +Prior to version 1.7.10 Omit +the `path:` portion of the `repositories` list. + Then, run the `rcreate` action (formerly `init`) to create that new Borg 2 repository: diff --git a/docs/reference/command-line.md b/docs/reference/command-line.md index 5ef3836..78f8e7f 100644 --- a/docs/reference/command-line.md +++ b/docs/reference/command-line.md @@ -15,7 +15,7 @@ listed here do not have equivalents in borgmatic's [configuration file](https://torsion.org/borgmatic/docs/reference/configuration/). If you're using an older version of borgmatic, some of these flags may not be -present in that version, and you should instead use `borgmatic --help` or +present in that version and you should instead use `borgmatic --help` or `borgmatic [action name] --help` (where `[action name]` is the name of an action like `list`, `create`, etc.).