diff --git a/NEWS b/NEWS index a15d8755..e21c8db7 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,7 @@ +2.0.12.dev0 + * Add documentation on repositories, including SSH, Rclone, S3, and B2: + https://torsion.org/borgmatic/reference/configuration/repositories/ + 2.0.11 * #957: Document borgmatic's limitations around parallelism—both its own and Borg's. See the documentation for more information: diff --git a/docs/how-to/set-up-backups.md b/docs/how-to/set-up-backups.md index d763e601..1e30f856 100644 --- a/docs/how-to/set-up-backups.md +++ b/docs/how-to/set-up-backups.md @@ -214,15 +214,20 @@ edits are valid. Before you can create backups with borgmatic, you first need to create a Borg repository so you have a destination for your backup archives. (But skip this -step if you already have a Borg repository.) To create a repository, run a -command like the following with Borg 1.x: +step if you already have a Borg repository.) To create a repository, assuming +it's already [specified in borgmatic's +configuration](https://torsion.org/borgmatic/reference/configuration/repositories/), +run a command like the following with Borg 1.x: ```bash -sudo borgmatic init --encryption repokey +sudo borgmatic repo-create --encryption repokey ``` -New in borgmatic version 1.9.0 -Or, with Borg 2.x: +Prior to borgmatic version 1.9.0 +The `repo-create` action was called `init`. + +With Borg version 2.x Borg 2.x +uses more specific encryption modes like `repokey-aes-ocb`. For example: ```bash sudo borgmatic repo-create --encryption repokey-aes-ocb diff --git a/docs/reference/configuration/repositories.md b/docs/reference/configuration/repositories.md new file mode 100644 index 00000000..e6c9ab94 --- /dev/null +++ b/docs/reference/configuration/repositories.md @@ -0,0 +1,138 @@ +--- +title: Repositories +eleventyNavigation: + key: 🗃️ Repositories + parent: ⚙️ Configuration +--- + +Borg repositories are where your backups get stored. You can define them in +borgmatic's configuration via the `repositories` option, something like: + +```yaml +repositories: + - path: /path/to/first.borg + label: first + - path: /path/to/second.borg + label: second +``` + +Each repository has a `path` and an optional `label`. The [Borg repository URLs +documentation](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls) +has examples of valid repositories paths, but see below for some +borgmatic-specific examples. + +The `label` shows up in [logged +messages](https://torsion.org/borgmatic/reference/command-line/logging/) about +the repository and also serves as a way to refer to the repository via +the `--repository` flag on the command-line for supported +[actions](https://torsion.org/borgmatic/reference/command-line/actions/). + +When you run borgmatic's [`create` +action](https://torsion.org/borgmatic/reference/command-line/actions/create/), +it invokes Borg once for each configured repository in sequence. (So, not in +parallel.) That means—in each repository—borgmatic creates a single new backup +archive containing all of your [source +directories](https://torsion.org/borgmatic/reference/configuration/patterns-and-excludes/). + + +## SSH + +Backing up to a remote server via +[SSH](https://en.wikipedia.org/wiki/Secure_Shell) looks like: + +```yaml +repositories: + - path: ssh://user@host:port/./absolute/path/to/repo +``` + +Or relative to the remote user's home directory: + +```yaml +repositories: + - path: ssh://user@host:port/~/relative/path/to/repo +``` + +This assumes that you've already configured SSH access (e.g. public keys, known +hosts, authorized hosts, etc.) outside of borgmatic and that Borg is installed +on the server. + +With Borg version 2.xThe SSH +syntax is a little different: + +```yaml +repositories: + - path: ssh://user@host:port//absolute/path/to/repo +``` + +Or relative to the remote user's home directory: + + +```yaml +repositories: + - path: ssh://user@host:port/relative/path/to/repo +``` + +Also see the [`ssh_command` configuration +option](https://torsion.org/borgmatic/reference/configuration/) for overriding +the path to the SSH binary or passing it custom flags. For example: + +```yaml +ssh_command: ssh -i /path/to/private/key +``` + + +### SFTP + +[SFTP](https://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol) repositories +work just like SSH repositories, but with `sftp://` substituted for `ssh://`. + + +## Rclone + +New in Borg version 2.x If you're +using Borg 2, you can backup to repositories via [Rclone](https://rclone.org/), +which supports a large number of [cloud +providers](https://rclone.org/#providers). This means that Borg, via Rclone, +backs up directly to a cloud provider without having to create an intermediate +repository. + +The borgmatic configuration for Rclone looks like: + +```yaml +repositories: + - path: rclone:remote:path +``` + +Note the lack of "`//`" after `rclone:`. + +This configuration assumes that you've already [configured a corresponding +Rclone remote](https://rclone.org/docs/). + + +## S3 / B2 + +New in Borg version 2.x Borg 2 +supports storing repositories directly on [Amazon +S3](https://aws.amazon.com/s3/), [Backblaze +B2](https://www.backblaze.com/cloud-storage), or an S3-alike service, even +without the use of Rclone or an intermediate repository. The configuration for +that might look like one of the following: + +```yaml +repositories: + - path: s3:access_key_id:access_key_secret@/bucket/path + - path: b2:access_key_id:access_key_secret@schema://hostname:port/bucket/path +``` + +Note the lack of "`//`" after `s3:` or `b2:`. + +When selecting your cloud hosting provider, be aware that Amazon in particular +has [financially +supported](https://en.wikipedia.org/wiki/White_House_State_Ballroom) the Trump +regime. + + +## Related documentation + + * [How to make backups redundant](https://torsion.org/borgmatic/how-to/make-backups-redundant/) + * [How to provide your passwords](https://torsion.org/borgmatic/how-to/provide-your-passwords/) diff --git a/pyproject.toml b/pyproject.toml index d4d508c6..d237ab2e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "borgmatic" -version = "2.0.11" +version = "2.0.12.dev0" authors = [ { name="Dan Helfman", email="witten@torsion.org" }, ]