From 952334fecb21e3f74ce990f75ccab37b0042321b Mon Sep 17 00:00:00 2001 From: cupcakearmy Date: Fri, 16 Apr 2021 00:26:57 +0200 Subject: [PATCH] docs --- docs/markdown/_toc.md | 2 +- docs/markdown/cli/backup.md | 6 +++++- docs/markdown/cli/check.md | 8 ++------ docs/markdown/cli/forget.md | 6 ++++-- docs/markdown/cli/general.md | 23 +++++++++++------------ docs/markdown/examples.md | 10 +++------- docs/markdown/index.md | 8 -------- docs/markdown/location/cron.md | 2 -- docs/markdown/location/docker.md | 29 +++++++---------------------- docs/markdown/location/hooks.md | 4 +++- docs/markdown/qa.md | 6 ++++-- docs/markdown/quick.md | 15 ++++++++++----- 12 files changed, 50 insertions(+), 69 deletions(-) diff --git a/docs/markdown/_toc.md b/docs/markdown/_toc.md index 39a5f80..199003f 100644 --- a/docs/markdown/_toc.md +++ b/docs/markdown/_toc.md @@ -1,6 +1,6 @@ [Home](/) [Quick Start](/quick) -[Installation](/installation) + [Configuration](/config) > :Collapse label=Locations diff --git a/docs/markdown/cli/backup.md b/docs/markdown/cli/backup.md index 7820786..ddbdd0e 100644 --- a/docs/markdown/cli/backup.md +++ b/docs/markdown/cli/backup.md @@ -7,7 +7,11 @@ autorestic backup [-l, --location] [-a, --all] Performs a backup of all locations if the `-a` flag is passed. To only backup some locations pass one or more `-l` or `--location` flags. ```bash -autorestic backup -l my-location +# All +autorestic backup -a + +# Some +autorestic backup -l foo -l bar ``` > :ToCPrevNext diff --git a/docs/markdown/cli/check.md b/docs/markdown/cli/check.md index 4ae41e0..3280459 100644 --- a/docs/markdown/cli/check.md +++ b/docs/markdown/cli/check.md @@ -1,15 +1,11 @@ # Check ```bash -autorestic check [-b, --backend] [-a, --all] +autorestic check ``` -Cheks if one or more backend are configured properly and initializes them if they are not already. +Checks locations and backends are configured properly and initializes them if they are not already. This is mostly an internal command, but useful to verify if a backend is configured correctly. -```bash -autorestic check -b my-backend -``` - > :ToCPrevNext diff --git a/docs/markdown/cli/forget.md b/docs/markdown/cli/forget.md index a66adb8..e17e93a 100644 --- a/docs/markdown/cli/forget.md +++ b/docs/markdown/cli/forget.md @@ -1,11 +1,13 @@ # Forget ```bash -autorestic forget [-l, --location] [-a, --all] [--dry-run] +autorestic forget [-l, --location] [-a, --all] [--dry-run] [--prune] ``` -This will prune and remove old data form the backends according to the [keep policy you have specified for the location](/locations/forget) +This will prune and remove old data form the backends according to the [keep policy you have specified for the location](/location/forget) The `--dry-run` flag will do a dry run showing what would have been deleted, but won't touch the actual data. +The `--prune` flag will also [prune the data](https://restic.readthedocs.io/en/latest/060_forget.html#removing-backup-snapshots). This is a costly operation that can take longer, however it will free up the actual space. + > :ToCPrevNext diff --git a/docs/markdown/cli/general.md b/docs/markdown/cli/general.md index 842d19c..402458d 100644 --- a/docs/markdown/cli/general.md +++ b/docs/markdown/cli/general.md @@ -1,14 +1,6 @@ # General -## `--version` - -Prints the current version - -```bash -autorestic --version -``` - -## `--c, --config` +## `-c, --config` Specify the config file to be used. If omitted `autorestic` will search for for a `.autorestic.yml` in the current directory and your home directory. @@ -19,11 +11,18 @@ autorestic -c /path/to/my/config.yml ## `--ci` -> Available since version 0.22 +Run the CLI in CI Mode, which means there will be no interactivity, no colors and automatically sets the `--verbose` flag. -Run the CLI in CI Mode, which means there will be no interactivity. This can be useful when you want to run cron e.g. as all the output will be saved. ```bash -autorestic --ci +autorestic --ci backup -a +``` + +## `--verbose` + +Verbose mode will show the output of the native restic commands that are otherwise not printed out. Useful for debugging or logging in automated tasks. + +```bash +autorestic --verbose backup -a ``` diff --git a/docs/markdown/examples.md b/docs/markdown/examples.md index ca80aa0..3fd55c0 100644 --- a/docs/markdown/examples.md +++ b/docs/markdown/examples.md @@ -1,18 +1,14 @@ # 🐣 Examples -## Exec - -### List all the snapshots for all the backends +## List all the snapshots for all the backends ```bash autorestic exec -a -- snapshots ``` -### Unlock a locked repository - -If you accidentally cancelled a running operation this could be useful. +## Unlock a locked repository -Only do this if you know what you are doing. +This can come in handy if a backup process crashed or if it was accidentally cancelled. Then the repository would still be locked without an actual process using it. Only do this if you know what you are sure no other process is actually reading/writing to the repository of course. ```bash autorestic exec -b my-backend -- unlock diff --git a/docs/markdown/index.md b/docs/markdown/index.md index aad20f7..4b7f3f7 100644 --- a/docs/markdown/index.md +++ b/docs/markdown/index.md @@ -4,14 +4,6 @@ High backup level CLI utility for [restic](https://restic.net/). Autorestic is a wrapper around the amazing [restic](https://restic.net/). While being amazing the restic cli can be a bit overwhelming and difficult to manage if you have many different location that you want to backup to multiple locations. This utility is aimed at making this easier 🙂 - - -## ✈️ Roadmap - -~~I would like to make the official `1.0` release in the coming months. Until then please feel free to file issues or feature requests so that the tool is as flexible as possible :)~~ - -As of version `0.18` crons are supported wich where the last feature missing for a `1.0`. Will test this for a few weeks and then it's time for the first "real" release! 🎉 Also we now have waaay better docs 📒 - ## 🌈 Features - YAML config files, no CLI diff --git a/docs/markdown/location/cron.md b/docs/markdown/location/cron.md index 6b9badf..d796c2f 100644 --- a/docs/markdown/location/cron.md +++ b/docs/markdown/location/cron.md @@ -2,8 +2,6 @@ Often it is usefull to trigger backups autmatically. For this we can specify a `cron` attribute to each location. -> Available since version 0.18 - ```yaml | .autorestic.yml locations: my-location: diff --git a/docs/markdown/location/docker.md b/docs/markdown/location/docker.md index 5fb3683..3223779 100644 --- a/docs/markdown/location/docker.md +++ b/docs/markdown/location/docker.md @@ -2,10 +2,6 @@ autorestic supports docker volumes directly, without needing them to be mounted to the host filesystem. -> Available since version 0.13 - -Let see an example. - ```yaml | docker-compose.yml version: '3.7' @@ -22,37 +18,26 @@ services: ```yaml | .autorestic.yml locations: - hello: - from: 'volume:my-data' + - name: hello + from: volume:my-data to: - remote - options: - forget: - keep-last: 14 # Useful for limitations explained belowd backends: - remote: ... + - name: remote + # ... ``` Now you can backup and restore as always. ```bash -autorestic -l hello backup +autorestic backup -l hello ``` ```bash -autorestic -l hello restore +autorestic restore -l hello ``` -If the volume does not exist on restore, autorestic will create it for you and then fill it with the data. - -## Limitations - -Unfortunately there are some limitations when backing up directly from a docker volume without mounting the volume to the host: - -1. Incremental updates are not possible right now due to how the current docker mounting works. This means that it will take significantely more space. -2. Exclude patterns and files also do not work as restic only sees a compressed tarball as source and not the actual data. - -If you are curious or have ideas how to improve this, please [read more here](https://github.com/cupcakearmy/autorestic/issues/4#issuecomment-568771951). Any help is welcomed 🙂 +The volume has to exists whenever backing up or restoring. > :ToCPrevNext diff --git a/docs/markdown/location/hooks.md b/docs/markdown/location/hooks.md index 16c0696..ecfb199 100644 --- a/docs/markdown/location/hooks.md +++ b/docs/markdown/location/hooks.md @@ -1,6 +1,8 @@ # Hooks -Sometimes you might want to stop an app/db before backing up data and start the service again after the backup has completed. This is what the hooks are made for. Simply add them to your location config. You can have as many commands as you wish. +If you want to perform some commands before and/or after a backup, you can use hooks. + +They consist of a list of `before`/`after` commands that will be executed in the same directory as the target `from`. ```yml | .autorestic.yml locations: diff --git a/docs/markdown/qa.md b/docs/markdown/qa.md index 8446b0c..364d3e8 100644 --- a/docs/markdown/qa.md +++ b/docs/markdown/qa.md @@ -2,7 +2,9 @@ ## My config file was moved? -This happens when autorestic needs to write to the config file. This happend e.g. when we are generating a key for you. -Unfortunately during this process formatting and comments are lost. That is why autorestic will place a copy of your old config next to the one we are writing to. +This happens when autorestic needs to write to the config file: e.g. when we are generating a key for you. +Unfortunately during this process formatting and comments are lost because the `yaml` library used is not comment and/or format aware. + +That is why autorestic will place a copy of your old config next to the one we are writing to. > :ToCPrevNext diff --git a/docs/markdown/quick.md b/docs/markdown/quick.md index 6a3b015..ca87237 100644 --- a/docs/markdown/quick.md +++ b/docs/markdown/quick.md @@ -17,30 +17,35 @@ For a quick overview: - `locations` can be seen as the inputs and `backends` the output where the data is stored and backed up. - One `location` can have one or multiple `backends` for redudancy. - One `backend` can also be the target for multiple `locations`. -- **Backup the config file as it will contain the generated keys**. If you don't have a copy of that keys, the backups are useless as they are encrypted and data will be not recoverable. + +> **⚠️ WARNING ⚠️** +> +> Note that the data is automatically encrypted on the server. The key will be generated and added to your config file. Every backend will have a separate key. **You should keep a copy of the keys or config file somewhere in case your server dies**. Otherwise DATA IS LOST! ```yaml | .autorestic.yml locations: - home: + - name: home from: /home/me to: remote - important: + - name: important from: /path/to/important/stuff to: - remote - hdd backends: - remote: + - name: remote type: s3 path: 's3.amazonaws.com/bucket_name' + key: some-random-password-198rc79r8y1029c8yfewj8f1u0ef87yh198uoieufy AWS_ACCESS_KEY_ID: account_id AWS_SECRET_ACCESS_KEY: account_key - hdd: + - name: hdd type: local path: /mnt/my_external_storage + key: 'if not key is set it will be generated for you' ``` ## Check