amorfo77/restic-backup-docker
1
0
Fork 0
mirror of https://github.com/lobaro/restic-backup-docker.git synced 2026-02-17 09:23:56 +00:00
Code Issues Projects Releases Wiki Activity

📚 Fix minor typos and formatting in README.

Browse Source
This commit is contained in:
Felix Sherrington-Kendall
2023-07-01 12:25:22 +02:00
committed by Tobias Kaupat
parent beb5fa841c
commit 389fcaa995
1 changed files with 37 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
README.md
View File

@@ -21,40 +21,38 @@ docker pull lobaro/restic-backup-docker:latest
## Hooks
If you need to execute a script before or after each backup or check,
you need to add your hook script in the container folder `/hooks`:
If you need to execute a script before or after each backup or check, you need to add your hook scripts in the container folder `/hooks`:
```
-v ~/home/user/hooks:/hooks
```
Call your pre backup script `pre-backup.sh` and post backup script `post-backup.sh`. You can also have separate scripts when running data verification checks `pre-check.sh` and `post-check.sh`
Please don't hesitate to report any issue you find. **Thanks.**
Call your pre-backup script `pre-backup.sh` and post-backup script `post-backup.sh`. You can also have separate scripts when running data verification checks `pre-check.sh` and `post-check.sh`.
Please don't hesitate to report any issues you find. **Thanks.**
# Test the container
Clone this repository
Clone this repository:
```
git clone https://github.com/Lobaro/restic-backup-docker.git
cd restic-backup-docker
```
Build the container. The container is named `backup-test`
Build the container (the container is named `backup-test`):
```
./build.sh
```
Run the container.
Run the container:
```
./run.sh
```
This will run the container `backup-test` with the name `backup-test`. Existing containers with that names are completly removed automatically.
This will run the container `backup-test` with the name `backup-test`. Existing containers with that name are completely removed automatically.
The container will backup `~/test-data` to a repository with password `test` at `~/test-repo` every minute. The repository is initialized automatically by the container. If you'd like to change the arguments passed to `restic init`, you can do so using the `RESTIC_INIT_ARGS` env variable.
To enter your container execute
The container will back up `~/test-data` to a repository with password `test` at `~/test-repo` every minute. The repository is initialized automatically by the container. If you'd like to change the arguments passed to `restic init`, you can do so using the `RESTIC_INIT_ARGS` env variable.
To enter your container execute:
```
docker exec -ti backup-test /bin/sh
```
@@ -62,43 +60,41 @@ docker exec -ti backup-test /bin/sh
Now you can use restic [as documented](https://restic.readthedocs.io/en/stable/), e.g. try to run `restic snapshots` to list all your snapshots.
## Logfiles
Logfiles are inside the container. If needed you can create volumes for them.
Logfiles are inside the container. If needed, you can create volumes for them.
```
docker logs
```
Shows `/var/log/cron.log`
Shows `/var/log/cron.log`.
Additionally you can see the the full log, including restic output, of the last execution in `/var/log/backup-last.log`. When the backup fails the log is copied to `/var/log/restic-error-last.log`. If configured, you can find the full output of the mail notification in `/var/log/mail-last.log`.
Additionally you can see the full log, including restic output, of the last execution in `/var/log/backup-last.log`. When the backup fails, the log is copied to `/var/log/restic-error-last.log`. If configured, you can find the full output of the mail notification in `/var/log/mail-last.log`.
# Use the running container
Assuming the container name is `restic-backup-var`
Assuming the container name is `restic-backup-var`, you can execute restic with:
You can execute restic with ` docker exec -ti restic-backup-var restic`
docker exec -ti restic-backup-var restic
## Backup
To execute a backup manually independent of the CRON run:
To execute a backup manually, independent of the CRON, run:
docker exec -ti restic-backup-var /bin/backup
Backup a single file or directory
Back up a single file or directory:
docker exec -ti restic-backup-var restic backup /data/path/to/dir --tag my-tag
## Data verification check
To verify backup integrity and consistency manually independent of the CRON run:
To verify backup integrity and consistency manually, independent of the CRON, run:
docker exec -ti restic-backup-var /bin/check
## Restore
You might want to mount a separate hostvolume at e.g. `/restore` to not override existing data while restoring.
You might want to mount a separate host volume at e.g. `/restore` to not override existing data while restoring.
Get your snapshot ID with
Get your snapshot ID with:
docker exec -ti restic-backup-var restic snapshots
@@ -106,30 +102,28 @@ e.g. `abcdef12`
docker exec -ti restic-backup-var restic restore --include /data/path/to/files --target / abcdef12
The target is `/` since all data backed up should be inside the host mounted `/data` dir. If you mount `/restore` you should set `--target /restore` and data will end up in `/restore/data/path/to/files`.
The target is `/` since all data backed up should be inside the host mounted `/data` dir. If you mount `/restore` you should set `--target /restore` and the data will end up in `/restore/data/path/to/files`.
# Customize the Container
The container is setup by setting [environment variables](https://docs.docker.com/engine/reference/run/#/env-environment-variables) and [volumes](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems).
The container is set up by setting [environment variables](https://docs.docker.com/engine/reference/run/#/env-environment-variables) and [volumes](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems).
## Environment variables
* `RESTIC_REPOSITORY` - the location of the restic repository. Default `/mnt/restic`. For S3: `s3:https://s3.amazonaws.com/BUCKET_NAME`
* `RESTIC_PASSWORD` - the password for the restic repository. Will also be used for restic init during first start when the repository is not initialized.
* `RESTIC_TAG` - Optional. To tag the images created by the container.
* `NFS_TARGET` - Optional. If set the given NFS is mounted, i.e. `mount -o nolock -v ${NFS_TARGET} /mnt/restic`. `RESTIC_REPOSITORY` must remain it's default value!
* `BACKUP_CRON` - A cron expression to run the backup. Note: cron daemon uses UTC time zone. Default: `0 */6 * * *` aka every 6 hours.
* `CHECK_CRON` - Optional. A cron expression to run data integrity check (`restic check`). If left unset data will not be checked. Note: cron daemon uses UTC time zone. Example: `0 23 * * 3` to run 11PM every Tuesday.
* `RESTIC_FORGET_ARGS` - Optional. Only if specified `restic forget` is run with the given arguments after each backup. Example value: `-e "RESTIC_FORGET_ARGS=--prune --keep-last 10 --keep-hourly 24 --keep-daily 7 --keep-weekly 52 --keep-monthly 120 --keep-yearly 100"`
* `RESTIC_INIT_ARGS` - Optional. Allows to specify extra arguments to `restic init` such as a password file with `--password-file`.
* `RESTIC_JOB_ARGS` - Optional. Allows to specify extra arguments to the back up job such as limiting bandwith with `--limit-upload` or excluding file masks with `--exclude`.
* `RESTIC_DATA_SUBSET` - Optional. You can pass value to `--read-data-subset` when repository check is run. If left unset only the structure of the repository is verified. Note: `CHECK_CRON` must be set for check to be run automatically.
* `NFS_TARGET` - Optional. If set, the given NFS is mounted, i.e. `mount -o nolock -v ${NFS_TARGET} /mnt/restic`. `RESTIC_REPOSITORY` must remain its default value!
* `BACKUP_CRON` - A cron expression to run the backup. Note: The cron daemon uses UTC time zone. Default: `0 */6 * * *` aka every 6 hours.
* `CHECK_CRON` - Optional. A cron expression to run data integrity check (`restic check`). If left unset, data will not be checked. Note: The cron daemon uses UTC time zone. Example: `0 23 * * 3` to run 11PM every Tuesday.
* `RESTIC_FORGET_ARGS` - Optional. Only if specified, `restic forget` is run with the given arguments after each backup. Example value: `-e "RESTIC_FORGET_ARGS=--prune --keep-last 10 --keep-hourly 24 --keep-daily 7 --keep-weekly 52 --keep-monthly 120 --keep-yearly 100"`
* `RESTIC_INIT_ARGS` - Optional. Allows specifying extra arguments to `restic init` such as a password file with `--password-file`.
* `RESTIC_JOB_ARGS` - Optional. Allows specifying extra arguments to the backup job such as limiting bandwith with `--limit-upload` or excluding file masks with `--exclude`.
* `RESTIC_DATA_SUBSET` - Optional. You can pass a value to `--read-data-subset` when a repository check is run. If left unset, only the structure of the repository is verified. Note: `CHECK_CRON` must be set for check to be run automatically.
* `AWS_ACCESS_KEY_ID` - Optional. When using restic with AWS S3 storage.
* `AWS_SECRET_ACCESS_KEY` - Optional. When using restic with AWS S3 storage.
* `TEAMS_WEBHOOK_URL` - Optional. If specified, the content of `/var/log/backup-last.log` and `/var/log/check-last.log` is sent to your Microsoft Teams channel after each backup and data integrity check.
* `MAILX_ARGS` - Optional. If specified, the content of `/var/log/backup-last.log` and `/var/log/check-last.log` is sent via mail after each backup and data integrity check using an *external SMTP*. To have maximum flexibility, you have to specify the mail/smtp parameters by your own. Have a look at the [mailx manpage](https://linux.die.net/man/1/mailx) for further information. Example value: `-e "MAILX_ARGS=-r 'from@example.de' -s 'Result of the last restic run' -S smtp='smtp.example.com:587' -S smtp-use-starttls -S smtp-auth=login -S smtp-auth-user='username' -S smtp-auth-password='password' 'to@example.com'"`.
* `MAILX_ARGS` - Optional. If specified, the content of `/var/log/backup-last.log` and `/var/log/check-last.log` is sent via mail after each backup and data integrity check using an *external SMTP*. To have maximum flexibility, you have to specify the mail/smtp parameters on your own. Have a look at the [mailx manpage](https://linux.die.net/man/1/mailx) for further information. Example value: `-e "MAILX_ARGS=-r 'from@example.de' -s 'Result of the last restic run' -S smtp='smtp.example.com:587' -S smtp-use-starttls -S smtp-auth=login -S smtp-auth-user='username' -S smtp-auth-password='password' 'to@example.com'"`.
* `OS_AUTH_URL` - Optional. When using restic with OpenStack Swift container.
* `OS_PROJECT_ID` - Optional. When using restic with OpenStack Swift container.
* `OS_PROJECT_NAME` - Optional. When using restic with OpenStack Swift container.
@@ -147,13 +141,13 @@ The container is setup by setting [environment variables](https://docs.docker.co
## Set the hostname
Since restic saves the hostname with each snapshot and the hostname of a docker container is derived from it's id you might want to customize this by setting the hostname of the container to another value.
Since restic saves the hostname with each snapshot and the hostname of a docker container is derived from its id, you might want to customize this by setting the hostname of the container to another value.
Set `--hostname` in the [network settings](https://docs.docker.com/engine/reference/run/#network-settings)
## Backup via SFTP
Since restic needs a **password less login** to the SFTP server make sure you can do `sftp user@host` from inside the container. If you can do so from your host system, the easiest way is to just mount your `.ssh` folder conaining the authorized cert into the container by specifying `-v ~/.ssh:/root/.ssh` as argument for `docker run`.
Since restic needs a **passwordless login** to the SFTP server, make sure you can do `sftp user@host` from inside the container. If you can do so from your host system, the easiest way is to just mount your `.ssh` folder containing the authorized cert into the container by specifying `-v ~/.ssh:/root/.ssh` as an argument for `docker run`.
Now you can simply specify the restic repository to be an [SFTP repository](https://restic.readthedocs.io/en/stable/Manual/#create-an-sftp-repository).
@@ -163,8 +157,9 @@ Now you can simply specify the restic repository to be an [SFTP repository](http
## Backup via OpenStack Swift
Restic can backup data to an OpenStack Swift container. Because Swift supports various authentication methods, credentials are passed through environment variables. In order to help integration with existing OpenStack installations, the naming convention of those variables follows the official Python Swift client.
Now you can simply specify the restic repository to be an [Swift repository](https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#openstack-swift).
Restic can back up data to an OpenStack Swift container. Because Swift supports various authentication methods, credentials are passed through environment variables. In order to help integration with existing OpenStack installations, the naming convention of those variables follows the official Python Swift client.
Now you can simply specify the restic repository to be a [Swift repository](https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#openstack-swift).
```
-e "RESTIC_REPOSITORY=swift:backup:/"
@@ -187,11 +182,11 @@ To use rclone as a backend for restic, simply add the rclone config file as a vo
Note that for some backends (Among them Google Drive and Microsoft OneDrive), rclone writes data back to the `rclone.conf` file. In this case it needs to be writable by Docker.
If the the container fails to write the new `rclone.conf` file with the error message `Failed to save config after 10 tries: Failed to move previous config to backup location`, add the entire `rclone` directory as volume: `-v /absolute/path/to/rclone-dir:/root/.config/rclone`.
If the container fails to write the new `rclone.conf` file with the error message `Failed to save config after 10 tries: Failed to move previous config to backup location`, add the entire `rclone` directory as a volume: `-v /absolute/path/to/rclone-dir:/root/.config/rclone`.
## Example docker-compose
This is example `docker-compose.yml`. Container will backup two directories to a SFTP server and check data integrity once a week.
This is an example `docker-compose.yml`. The container will back up two directories to an SFTP server and check data integrity once a week.
```
version: '3'