mirror of
https://github.com/borgmatic-collective/borgmatic.git
synced 2026-08-06 08:13:01 +02:00
Merge branch 'master' into patch-2
This commit is contained in:
Dan Helfman
+1
-1
@@ -4,7 +4,7 @@ COPY . /app
|
||||
RUN apk add --no-cache py3-pip py3-ruamel.yaml py3-ruamel.yaml.clib
|
||||
RUN pip install --no-cache /app && generate-borgmatic-config && chmod +r /etc/borgmatic/config.yaml
|
||||
RUN borgmatic --help > /command-line.txt \
|
||||
&& for action in init prune compact create check extract export-tar mount umount restore list info borg; do \
|
||||
&& for action in rcreate prune compact create check extract export-tar mount umount restore rlist list rinfo info borg; do \
|
||||
echo -e "\n--------------------------------------------------------------------------------\n" >> /command-line.txt \
|
||||
&& borgmatic "$action" --help >> /command-line.txt; done
|
||||
|
||||
|
||||
@@ -76,7 +76,7 @@ location:
|
||||
- /home
|
||||
|
||||
repositories:
|
||||
- me@buddys-server.org:backup.borg
|
||||
- ssh://me@buddys-server.org/./backup.borg
|
||||
|
||||
hooks:
|
||||
before_backup:
|
||||
|
||||
@@ -133,14 +133,13 @@ that you'd like supported.
|
||||
|
||||
To restore a database dump from an archive, use the `borgmatic restore`
|
||||
action. But the first step is to figure out which archive to restore from. A
|
||||
good way to do that is to use the `list` action:
|
||||
good way to do that is to use the `rlist` action:
|
||||
|
||||
```bash
|
||||
borgmatic list
|
||||
borgmatic rlist
|
||||
```
|
||||
|
||||
(No borgmatic `list` action? Try the old-style `--list`, or upgrade
|
||||
borgmatic!)
|
||||
(No borgmatic `rlist` action? Try `list` instead or upgrade borgmatic!)
|
||||
|
||||
That should yield output looking something like:
|
||||
|
||||
|
||||
@@ -27,9 +27,6 @@ borgmatic create
|
||||
borgmatic check
|
||||
```
|
||||
|
||||
(No borgmatic `prune`, `create`, or `check` actions? Try the old-style
|
||||
`--prune`, `--create`, or `--check`. Or upgrade borgmatic!)
|
||||
|
||||
You can run with only one of these actions provided, or you can mix and match
|
||||
any number of them in a single borgmatic run. This supports approaches like
|
||||
skipping certain actions while running others. For instance, this skips
|
||||
@@ -70,7 +67,9 @@ Here are the available checks from fastest to slowest:
|
||||
* `extract`: Performs an extraction dry-run of the most recent archive.
|
||||
* `data`: Verifies the data integrity of all archives contents, decrypting and decompressing all data (implies `archives` as well).
|
||||
|
||||
See [Borg's check documentation](https://borgbackup.readthedocs.io/en/stable/usage/check.html) for more information.
|
||||
See [Borg's check
|
||||
documentation](https://borgbackup.readthedocs.io/en/stable/usage/check.html)
|
||||
for more information.
|
||||
|
||||
### Check frequency
|
||||
|
||||
|
||||
@@ -9,14 +9,13 @@ eleventyNavigation:
|
||||
|
||||
When the worst happens—or you want to test your backups—the first step is
|
||||
to figure out which archive to extract. A good way to do that is to use the
|
||||
`list` action:
|
||||
`rlist` action:
|
||||
|
||||
```bash
|
||||
borgmatic list
|
||||
borgmatic rlist
|
||||
```
|
||||
|
||||
(No borgmatic `list` action? Try the old-style `--list`, or upgrade
|
||||
borgmatic!)
|
||||
(No borgmatic `rlist` action? Try `list` instead or upgrade borgmatic!)
|
||||
|
||||
That should yield output looking something like:
|
||||
|
||||
@@ -32,10 +31,9 @@ and therefore the latest timestamp, run a command like:
|
||||
borgmatic extract --archive host-2019-01-02T04:06:07.080910
|
||||
```
|
||||
|
||||
(No borgmatic `extract` action? Try the old-style `--extract`, or upgrade
|
||||
borgmatic!)
|
||||
(No borgmatic `extract` action? Upgrade borgmatic!)
|
||||
|
||||
With newer versions of borgmatic, you can simplify this to:
|
||||
Or simplify this to:
|
||||
|
||||
```bash
|
||||
borgmatic extract --archive latest
|
||||
@@ -43,7 +41,8 @@ borgmatic extract --archive latest
|
||||
|
||||
The `--archive` value is the name of the archive to extract. This extracts the
|
||||
entire contents of the archive to the current directory, so make sure you're
|
||||
in the right place before running the command.
|
||||
in the right place before running the command—or see below about the
|
||||
`--destination` flag.
|
||||
|
||||
|
||||
## Repository selection
|
||||
@@ -65,13 +64,15 @@ everything from an archive. To do that, tack on one or more `--path` values.
|
||||
For instance:
|
||||
|
||||
```bash
|
||||
borgmatic extract --archive host-2019-... --path path/1 path/2
|
||||
borgmatic extract --archive latest --path path/1 path/2
|
||||
```
|
||||
|
||||
Note that the specified restore paths should not have a leading slash. Like a
|
||||
whole-archive extract, this also extracts into the current directory. So for
|
||||
example, if you happen to be in the directory `/var` and you run the `extract`
|
||||
command above, borgmatic will extract `/var/path/1` and `/var/path/2`.
|
||||
whole-archive extract, this also extracts into the current directory by
|
||||
default. So for example, if you happen to be in the directory `/var` and you
|
||||
run the `extract` command above, borgmatic will extract `/var/path/1` and
|
||||
`/var/path/2`.
|
||||
|
||||
|
||||
## Extract to a particular destination
|
||||
|
||||
@@ -80,7 +81,7 @@ extract files to a particular destination directory, use the `--destination`
|
||||
flag:
|
||||
|
||||
```bash
|
||||
borgmatic extract --archive host-2019-... --destination /tmp
|
||||
borgmatic extract --archive latest --destination /tmp
|
||||
```
|
||||
|
||||
When using the `--destination` flag, be careful not to overwrite your system's
|
||||
@@ -104,7 +105,7 @@ archive as a [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace)
|
||||
filesystem, you can use the `borgmatic mount` action. Here's an example:
|
||||
|
||||
```bash
|
||||
borgmatic mount --archive host-2019-... --mount-point /mnt
|
||||
borgmatic mount --archive latest --mount-point /mnt
|
||||
```
|
||||
|
||||
This mounts the entire archive on the given mount point `/mnt`, so that you
|
||||
@@ -127,7 +128,7 @@ your archive, use the `--path` flag, similar to the `extract` action above.
|
||||
For instance:
|
||||
|
||||
```bash
|
||||
borgmatic mount --archive host-2019-... --mount-point /mnt --path var/lib
|
||||
borgmatic mount --archive latest --mount-point /mnt --path var/lib
|
||||
```
|
||||
|
||||
When you're all done exploring your files, unmount your mount point. No
|
||||
|
||||
@@ -37,20 +37,35 @@ borgmatic --stats
|
||||
## Existing backups
|
||||
|
||||
borgmatic provides convenient actions for Borg's
|
||||
[list](https://borgbackup.readthedocs.io/en/stable/usage/list.html) and
|
||||
[info](https://borgbackup.readthedocs.io/en/stable/usage/info.html)
|
||||
[`list`](https://borgbackup.readthedocs.io/en/stable/usage/list.html) and
|
||||
[`info`](https://borgbackup.readthedocs.io/en/stable/usage/info.html)
|
||||
functionality:
|
||||
|
||||
|
||||
```bash
|
||||
borgmatic list
|
||||
borgmatic info
|
||||
```
|
||||
|
||||
You can change the output format of `borgmatic list` by specifying your own using `--format $FORMAT`. Refer to the official [borg list --format specs]( https://borgbackup.readthedocs.io/en/stable/usage/list.html#the-format-specifier-syntax) for available options.
|
||||
You can change the output format of `borgmatic list` by specifying your own
|
||||
with `--format $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!)*
|
||||
|
||||
<span class="minilink minilink-addedin">New in borgmatic version 1.7.0</span>
|
||||
There are also `rlist` and `rinfo` actions for displaying repository
|
||||
information with Borg 2.x:
|
||||
|
||||
```bash
|
||||
borgmatic rlist
|
||||
borgmatic rinfo
|
||||
```
|
||||
|
||||
See the [borgmatic command-line
|
||||
reference](https://torsion.org/borgmatic/docs/reference/command-line/) for
|
||||
more information.
|
||||
|
||||
*(No borgmatic `list` or `info` actions? Try the old-style `--list` or
|
||||
`--info`. Or upgrade borgmatic!)*
|
||||
|
||||
### Searching for a file
|
||||
|
||||
|
||||
@@ -20,8 +20,8 @@ location:
|
||||
|
||||
# Paths of local or remote repositories to backup to.
|
||||
repositories:
|
||||
- 1234@usw-s001.rsync.net:backups.borg
|
||||
- k8pDxu32@k8pDxu32.repo.borgbase.com:repo
|
||||
- ssh://1234@usw-s001.rsync.net/./backups.borg
|
||||
- ssh://k8pDxu32@k8pDxu32.repo.borgbase.com/./repo
|
||||
- /var/lib/backups/local.borg
|
||||
```
|
||||
|
||||
|
||||
@@ -319,8 +319,8 @@ hooks:
|
||||
## Scripting borgmatic
|
||||
|
||||
To consume the output of borgmatic in other software, you can include an
|
||||
optional `--json` flag with `create`, `list`, or `info` to get the output
|
||||
formatted as JSON.
|
||||
optional `--json` flag with `create`, `rlist`, `rinfo`, or `info` to get the
|
||||
output formatted as JSON.
|
||||
|
||||
Note that when you specify the `--json` flag, Borg's other non-JSON output is
|
||||
suppressed so as not to interfere with the captured JSON. Also note that JSON
|
||||
@@ -329,9 +329,9 @@ output only shows up at the console, and not in syslog.
|
||||
|
||||
### Latest backups
|
||||
|
||||
All borgmatic actions that accept an "--archive" flag allow you to specify an
|
||||
archive name of "latest". This lets you get the latest archive without having
|
||||
to first run "borgmatic list" manually, which can be handy in automated
|
||||
All borgmatic actions that accept an `--archive` flag allow you to specify an
|
||||
archive name of `latest`. This lets you get the latest archive without having
|
||||
to first run `borgmatic rlist` manually, which can be handy in automated
|
||||
scripts. Here's an example:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -46,12 +46,11 @@ options, as that part is provided by borgmatic.
|
||||
You can also specify Borg options for relevant commands:
|
||||
|
||||
```bash
|
||||
borgmatic borg list --progress
|
||||
borgmatic borg rlist --short
|
||||
```
|
||||
|
||||
This runs Borg's `list` command once on each configured borgmatic
|
||||
repository. However, the native `borgmatic list` action should be preferred
|
||||
for most use.
|
||||
This runs Borg's `rlist` command once on each configured borgmatic repository.
|
||||
However, the native `borgmatic rlist` action should be preferred for most use.
|
||||
|
||||
What if you only want to run Borg on a single configured borgmatic repository
|
||||
when you've got several configured? Not a problem.
|
||||
@@ -63,7 +62,7 @@ borgmatic borg --repository repo.borg break-lock
|
||||
And what about a single archive?
|
||||
|
||||
```bash
|
||||
borgmatic borg --archive your-archive-name list
|
||||
borgmatic borg --archive your-archive-name rlist
|
||||
```
|
||||
|
||||
### Limitations
|
||||
|
||||
@@ -186,32 +186,39 @@ files via configuration management, or you want to double check that your hand
|
||||
edits are valid.
|
||||
|
||||
|
||||
## Initialization
|
||||
## Repository creation
|
||||
|
||||
Before you can create backups with borgmatic, you first need to initialize 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:
|
||||
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:
|
||||
|
||||
```bash
|
||||
sudo borgmatic init --encryption repokey
|
||||
```
|
||||
|
||||
(No borgmatic `init` action? Try the old-style `--init` flag, or upgrade
|
||||
borgmatic!)
|
||||
<span class="minilink minilink-addedin">New in borgmatic version 1.7.0</span>
|
||||
Or, with Borg 2.x:
|
||||
|
||||
```bash
|
||||
sudo borgmatic rcreate --encryption repokey-aes-ocb
|
||||
```
|
||||
|
||||
(Note that `repokey-chacha20-poly1305` may be faster than `repokey-aes-ocb` on
|
||||
certain platforms like ARM64.)
|
||||
|
||||
This uses the borgmatic configuration file you created above to determine
|
||||
which local or remote repository to create, and encrypts it with the
|
||||
encryption passphrase specified there if one is provided. Read about [Borg
|
||||
encryption
|
||||
modes](https://borgbackup.readthedocs.io/en/stable/usage/init.html#encryption-modes)
|
||||
modes](https://borgbackup.readthedocs.io/en/stable/usage/init.html#encryption-mode-tldr)
|
||||
for the menu of available encryption modes.
|
||||
|
||||
Also, optionally check out the [Borg Quick
|
||||
Start](https://borgbackup.readthedocs.org/en/stable/quickstart.html) for more
|
||||
background about repository initialization.
|
||||
background about repository creation.
|
||||
|
||||
Note that borgmatic skips repository initialization if the repository already
|
||||
Note that borgmatic skips repository creation if the repository already
|
||||
exists. This supports use cases like ensuring a repository exists prior to
|
||||
performing a backup.
|
||||
|
||||
@@ -221,8 +228,8 @@ key-based SSH access to the desired user account on the remote host.
|
||||
|
||||
## Backups
|
||||
|
||||
Now that you've configured borgmatic and initialized a repository, it's a
|
||||
good idea to test that borgmatic is working. So to run borgmatic and start a
|
||||
Now that you've configured borgmatic and created a repository, it's a good
|
||||
idea to test that borgmatic is working. So to run borgmatic and start a
|
||||
backup, you can invoke it like this:
|
||||
|
||||
```bash
|
||||
@@ -230,7 +237,7 @@ sudo borgmatic create --verbosity 1 --files --stats
|
||||
```
|
||||
|
||||
(No borgmatic `--files` flag? It's only present in newer versions of
|
||||
borgmatic. So try leaving it out, or upgrade borgmatic!)
|
||||
borgmatic. So try leaving it out or upgrade borgmatic!)
|
||||
|
||||
The `--verbosity` flag makes borgmatic show the steps it's performing. The
|
||||
`--files` flag lists each file that's new or changed since the last backup.
|
||||
|
||||
+85
-3
@@ -1,11 +1,11 @@
|
||||
---
|
||||
title: How to upgrade borgmatic
|
||||
title: How to upgrade borgmatic and Borg
|
||||
eleventyNavigation:
|
||||
key: 📦 Upgrade borgmatic
|
||||
key: 📦 Upgrade borgmatic/Borg
|
||||
parent: How-to guides
|
||||
order: 12
|
||||
---
|
||||
## Upgrading
|
||||
## Upgrading borgmatic
|
||||
|
||||
In general, all you should need to do to upgrade borgmatic is run the
|
||||
following:
|
||||
@@ -115,3 +115,85 @@ sudo pip3 install --user borgmatic
|
||||
|
||||
That's it! borgmatic will continue using your /etc/borgmatic configuration
|
||||
files.
|
||||
|
||||
|
||||
## Upgrading Borg
|
||||
|
||||
To upgrade to a new version of Borg, you can generally install a new version
|
||||
the same way you installed the previous version, paying attention to any
|
||||
instructions included with each Borg release changelog linked from the
|
||||
[releases page](https://github.com/borgbackup/borg/releases). However, some
|
||||
more major Borg releases require additional steps that borgmatic can help
|
||||
with.
|
||||
|
||||
|
||||
### Borg 1.2 to 2.0
|
||||
|
||||
<span class="minilink minilink-addedin">New in borgmatic version 1.7.0</span>
|
||||
Upgrading Borg from 1.2 to 2.0 requires manually upgrading your existing Borg
|
||||
1 repositories before use with Borg or borgmatic. Here's how you can
|
||||
accomplish that.
|
||||
|
||||
Start by upgrading borgmatic as described above to at least version 1.7.0 and
|
||||
Borg to 2.0. Then, rename your repository in borgmatic's configuration file to
|
||||
a new repository path. The repository upgrade process does not occur
|
||||
in-place; you'll create a new repository with a copy of your old repository's
|
||||
data.
|
||||
|
||||
Let's say your original borgmatic repository configuration file looks something
|
||||
like this:
|
||||
|
||||
```yaml
|
||||
location:
|
||||
repositories:
|
||||
- original.borg
|
||||
```
|
||||
|
||||
Change it to a new (not yet created) repository path:
|
||||
|
||||
```yaml
|
||||
location:
|
||||
repositories:
|
||||
- upgraded.borg
|
||||
```
|
||||
|
||||
Then, run the `rcreate` action (formerly `init`) to create that new Borg 2
|
||||
repository:
|
||||
|
||||
```bash
|
||||
borgmatic rcreate --verbosity 1 --encryption repokey-aes-ocb \
|
||||
--source-repository original.borg --repository upgraded.borg
|
||||
```
|
||||
|
||||
(Note that `repokey-chacha20-poly1305` may be faster than `repokey-aes-ocb` on
|
||||
certain platforms like ARM64.)
|
||||
|
||||
This creates an empty repository and doesn't actually transfer any data yet.
|
||||
The `--source-repository` flag is necessary to reuse key material from your
|
||||
Borg 1 repository so that the subsequent data transfer can work.
|
||||
|
||||
To transfer data from your original Borg 1 repository to your newly created
|
||||
Borg 2 repository:
|
||||
|
||||
```bash
|
||||
borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
|
||||
original.borg --repository upgraded.borg --dry-run
|
||||
borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
|
||||
original.borg --repository upgraded.borg
|
||||
borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
|
||||
original.borg --repository upgraded.borg --dry-run
|
||||
```
|
||||
|
||||
The first command with `--dry-run` tells you what Borg is going to do during
|
||||
the transfer, the second command actually performs the transfer/upgrade (this
|
||||
might take a while), and the final command with `--dry-run` again provides
|
||||
confirmation of success—or tells you if something hasn't been transferred yet.
|
||||
|
||||
Note that by omitting the `--upgrader` flag, you can also do archive transfers
|
||||
between Borg 2 repositories without upgrading, even down to individual
|
||||
archives. For more on that functionality, see the [Borg transfer
|
||||
documentation](https://borgbackup.readthedocs.io/en/2.0.0b1/usage/transfer.html).
|
||||
|
||||
That's it! Now you can use your new Borg 2 repository as normal with
|
||||
borgmatic. If you've got multiple repositories, repeat the above process for
|
||||
each.
|
||||
|
||||
Reference in New Issue
Block a user