pschiffe/docker-borg

Docker image with BorgBackup client utility and sshfs support

Borg Docker Image

This Docker image includes the BorgBackup client utility and sshfs support. Borg is a deduplicating archiver with compression and authenticated encryption. It's very efficient, doesn't require regular full backups, and supports data pruning.

Docker Hub: https://hub.docker.com/r/pschiffe/borg

Source GitHub repository: https://github.com/pschiffe/docker-borg

---

If this project is useful to you, please consider sponsoring me to support maintenance and further development. Thank you!

Quick start

First, pull the image to keep it up to date. Then create and run the borg backup container. In this quick start, the /etc and /home directories from the host are bind mounted to the container as read only. These are the directories which will be backed up. The backed up data will be stored in the borg-repo Docker volume, and the data will be protected with the my-secret-pw password. If the host is using SELinux, use the --security-opt label:disable flag. This is because we don't want to relabel the /etc and /home directories, but we do want the container to have access to them. After the backup is done, data will be pruned according to the default policy and checked for errors. Borg runs in verbose mode within the container, which means it will print detailed output from the backup. At the end, the container is deleted. This is done using a separate docker rm command. We do this because the --rm option in docker run would also remove the Docker volumes, which we don't want. By deleting the container and pulling the image from the registry each time, we ensure the container is fresh for each backup run.

docker pull pschiffe/borg
docker run \
  -e BORG_REPO=/borg/repo \
  -e BORG_PASSPHRASE=my-secret-pw \
  -e BACKUP_DIRS=/borg/data \
  -e EXCLUDE='*/.cache*;*.tmp;/borg/data/etc/shadow' \
  -e COMPRESSION=lz4 \
  -e PRUNE=1 \
  -v borg-config:/root \
  -v borg-repo:/borg/repo \
  -v /etc:/borg/data/etc:ro \
  -v /home:/borg/data/home:ro \
  --security-opt label:disable \
  --name borg-backup \
  pschiffe/borg
docker rm borg-backup

More examples

Backup docker volumes to remote location (Borg must be running in server mode at that remote location):

docker run \
  -e BORG_REPO='user@hostname:/path/to/repo' \
  -e ARCHIVE=wordpress-$(date +%Y-%m-%d) \
  -e BORG_PASSPHRASE=my-secret-pw \
  -e BACKUP_DIRS=/borg/data \
  -e COMPRESSION=lz4 \
  -e PRUNE=1 \
  -v borg-config:/root \
  -v mariadb-data:/borg/data/mariadb:ro \
  -v wordpress-data:/borg/data/wordpress:ro \
  --name borg-backup \
  pschiffe/borg

Use sshfs if Borg is not installed on the remote location:

docker run \
  -e SSHFS='user@hostname:/path/to/repo' \
  -e SSHFS_PASSWORD=my-ssh-password \
  -e BORG_PASSPHRASE=my-secret-pw \
  -e BACKUP_DIRS=/borg/data \
  -e COMPRESSION=lz4 \
  -e PRUNE=1 \
  -v borg-config:/root \
  -v mariadb-data:/borg/data/mariadb:ro \
  -v wordpress-data:/borg/data/wordpress:ro \
  --cap-add SYS_ADMIN --device /dev/fuse --security-opt label:disable \
  --name borg-backup \
  pschiffe/borg

Using sshfs with ssh key authentication:

docker run \
  -e SSHFS='user@hostname:/path/to/repo' \
  -e SSHFS_IDENTITY_FILE=/root/ssh-key/key \
  -e SSHFS_GEN_IDENTITY_FILE=1 \
  -e BORG_PASSPHRASE=my-secret-pw \
  -e BACKUP_DIRS=/borg/data \
  -e COMPRESSION=lz4 \
  -e PRUNE=1 \
  -v borg-config:/root \
  -v mariadb-data:/borg/data/mariadb:ro \
  -v wordpress-data:/borg/data/wordpress:ro \
  --cap-add SYS_ADMIN --device /dev/fuse --security-opt label:disable \
  --name borg-backup \
  pschiffe/borg

Restoring files from a specific day to a folder on the host:

docker run \
  -e BORG_REPO='user@hostname:/path/to/repo' \
  -e ARCHIVE=wordpress-2016-05-25 \
  -e BORG_PASSPHRASE=my-secret-pw \
  -e EXTRACT_TO=/borg/restore \
  -e EXTRACT_WHAT=only/this/file \
  -v borg-config:/root \
  -v /opt/restore:/borg/restore \
  --security-opt label:disable \
  --name borg-backup \
  pschiffe/borg

To run a custom Borg command, use the following syntax:

docker run \
  -e BORG_REPO='user@hostname:/path/to/repo' \
  -e BORG_PASSPHRASE=my-secret-pw \
  -e BORG_PARAMS='list ::2016-05-26' \
  -v borg-config:/root \
  --name borg-backup \
  pschiffe/borg

Environment variables

Description of all accepted environment variables follows.

Core variables

BORG_REPO - repository location

ARCHIVE - archive parameter for Borg repository. If empty, defaults to "${HOSTNAME}_$(date +%Y-%m-%d)". For more info see Borg documentation

BACKUP_DIRS - directories to back up

EXCLUDE - paths/patterns to exclude from backup. Paths must be separated by ;. For example: -e EXCLUDE='/my path/one;/path two;*.tmp'

BORG_PARAMS - run custom borg command inside of the container. If this variable is set, default commands are not executed, only the one specified in BORG_PARAMS. For example list or list ::2016-05-26. In both examples, repo is not specified, because borg understands the BORG_REPO env var and uses it by default

BORG_SKIP_CHECK - set to 1 if you want to skip the borg check command at the end of the backup

Compression

COMPRESSION - compression to use. Defaults to lz4. More info

Encryption

BORG_PASSPHRASE - repokey mode password. Defaults to none. Only the repokey mode encryption is supported by this Docker image. More info

Extracting (restoring) files

EXTRACT_TO - directory where to extract (restore) borg archive. If this variable is set, default commands are not executed, only the extraction is done. Repo and archive are specified with BORG_REPO and ARCHIVE variables. More info

EXTRACT_WHAT - subset of files and directories which should be extracted

Pruning

PRUNE - if set, prune the repository after backup. Empty by default. More info

PRUNE_PREFIX - filter data to prune by prefix of the archive. Empty by default - prune all data

KEEP_DAILY - keep specified number of daily backups. Defaults to 7

KEEP_WEEKLY - keep specified number of weekly backups. Defaults to 4

KEEP_MONTHLY - keep specified number of monthly backups. Defaults to 6

SSHFS

SSHFS - sshfs destination in form of user@host:/path. When using sshfs, container needs special permissions: --cap-add SYS_ADMIN --device /dev/fuse and if using SELinux: --security-opt label:disable or apparmor: --security-opt apparmor:unconfined

SSHFS_PASSWORD - password for ssh authentication

SSHFS_IDENTITY_FILE - path to ssh key

SSHFS_GEN_IDENTITY_FILE - if set, generates ssh key pair if SSHFS_IDENTITY_FILE is set and the key file doesn't exist. After generating the key, the public part of the key is printed to stdout and the container stops, so you have the chance to configure the server part before creating the first backup

Logging

LOGGING_LEVEL - Borg's logging level, defaults to --info

DEBUG - enable debug mode, 0 or 1, defaults to 0

SHOW_PROGRESS - show Borg's progress information, 0 or 1, defaults to 0

docker-borg's Issues

Script comments

Also in case you did not notice, I commented on borgbackup/borg#4372 and noticed some security-relevant stuff you may also want to consider to change…

ssh mode with key read: Connection reset by peer

Hi, I attempt to use docker-borg unsuccessfully with ssh key authentication:

docker run \
  -e SSHFS='backupuser@remotemachine:/home/backupuser
  -e SSHFS_IDENTITY_FILE=/root/ssh-key/key \
  -e BACKUP_DIRS=/borg/data \
  -e PRUNE=1 \
  -v borg-config:/root \
  --cap-add SYS_ADMIN --device /dev/fuse --security-opt label:disable --security-opt apparmor:unconfined \
  --name borg-backup \
  pschiffe/borg

I get the error message read: Connection reset by peer

SSH and SSHFS run separately, do the ssh key authentication properly on the remote machine.

Many thanks for your help.

Creating SSHFS fails when using SSHFS_PASSWORD with special characters (such as #)

In the entrypoint script borg-backup.sh there are two possible ways to mount the SSHFS, either by using an identity file or explicitly stating a password.

Latter has some problems with passwords containing characters such as "#":

SSHFS_PASSWORD="echo ${SSHFS_PASSWORD} |"
eval "${SSHFS_PASSWORD} sshfs ${SSHFS} /mnt/sshfs ${SSHFS_IDENTITY_FILE} ${SSHFS_PASSWORD_OPT}"

This would evaluate to:

echo XXXX#YYYY | sshfs ...

leading to just 'XXXX' echoed into nowhere and the rest of the line interpreted as a comment.

I believe it should be SSHFS_PASSWORD="echo \"${SSHFS_PASSWORD}\" |" to fix the issue, e.g. adding some quotes here around ${SSHFS_PASSWORD}.

Call `borg extract` with option `--progress` ?

Since restoring a Borg backup can take a while, I like to run the extract command with the option --progress . With this option the percentage of the already restored archive is shown.
Is there a way to configure Borg in the container to run with option --progress?

Christian

Ubuntu AppArmor prevents mounting of sshfs volume in container

After I was able to run the docker BorgBackup Image (with the great support of @pschiffe !) on WSL (Windows Subsystem for Linux) I tried to transfer the solution to a server.
But here I got the error message
fuse: mount failed: Permission denied
when starting the container.

I ggogled a bit and found that others had similar issues with fuse mounts in containers. They blamed AppArmor (afaik something similar to SELinux) and recommended to use the --security-opt apparmor:unconfined option.
I tried that and the docker-borg image worked on the server, too.
Thought that could be good information for you, @pschiffe .

I don't know enough about AppArmor (in fact almost nothing) to tell why it works on WSL without the additional option, but not on the server. Both run the same OS (Ubuntu 22.04.4 LTS). I assume some AppArmor default setting are different between both installations.

Update of docker image on dockerhub

Hi,
do you intend to keep the docker image on docker hub up to date ? The current borgbackup version 1.1.10 while the one provided in your image is the older one 1.1.8

Official docker image

Hello!

I've been using your script (partly) for years, and I'm really happy :) Thanks a lot for your work ;)

I'm now asking for upstream to have an official image, and created this PR.

I copied your script and README, and mentionned your name. I hope it is fine, if not, please let me know.

If you have comments, feel free to comment there. (and close this issue.

Can not init backup

Hello,

I am trying to run a backup with your borg container as described in the Readme with the following command:

docker run \
  -e SSHFS='user@hostname:/path/to/repo' \
  -e SSHFS_PASSWORD=my-ssh-password \
  -e BORG_PASSPHRASE=my-secret-pw \
  -e BACKUP_DIRS=/borg/data \
  -e COMPRESSION=lz4 \
  -e PRUNE=1 \
  -v borg-cache:/root/.cache/borg \
  -v mariadb-data:/borg/data/mariadb:ro \
  -v worpdress-data:/borg/data/wordpress:ro \
  --cap-add SYS_ADMIN --device /dev/fuse --security-opt label:disable \
  --name borg-backup \
  pschiffe/borg

There seems to be some issue with borg init, since it gives me this error message:

usage: borg init [-h] [--critical] [--error] [--warning] [--info] [--debug]
                 [--debug-topic TOPIC] [-p] [--log-json] [--lock-wait SECONDS]
                 [--show-version] [--show-rc] [--umask M] [--remote-path PATH]
                 [--remote-ratelimit RATE] [--consider-part-files]
                 [--debug-profile FILE] -e MODE [--append-only]
                 [--storage-quota QUOTA]
                 [REPOSITORY]
borg init: error: the following arguments are required: -e/--encryption

Any idea how I can fix this?

Cannot backup unencrypted repostitory

Hi,
When I'm trying to backup directory using unencrypted repository I'm getting "Attempting to access a previously unknown unencrypted repository" error.
I know that I could avoid that using BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK. However, I still feel that something is wrong. Due to this error I'm not fully sure that borg will use cache which is essential for me. Could you please help me with that issue?

How to reproduce? Run twice following commands

mkdir borg-archive borg-repo source-test

docker run -h foo --privileged \
-e "BACKUP_DIRS=/to-backup" \
-e BORG_REPO="/mnt/s3fs/backup" \
-e ARCHIVE="$(date +%Y-%m-%d--%H-%M-%S)" \
-v $(pwd)/borg-archive:/root/.cache/borg \
-v $(pwd)/source-test:/to-backup \
-v $(pwd)/borg-repo:/mnt/s3fs \
pschiffe/borg

Output:

matzz@matzz ~/test/test $ mkdir borg-archive borg-repo source-test
matzz@matzz ~/test/test $ docker run -h foo --privileged \
> -e "BACKUP_DIRS=/to-backup" \
> -e BORG_REPO="/mnt/s3fs/backup" \
> -e ARCHIVE="$(date +%Y-%m-%d--%H-%M-%S)" \
> -v $(pwd)/borg-archive:/root/.cache/borg \
> -v $(pwd)/source-test:/to-backup \
> -v $(pwd)/borg-repo:/mnt/s3fs \
> pschiffe/borg
Not using encryption. If you want to encrypt your files, set $BORG_PASSPHRASE variable.
ls: cannot access '/mnt/s3fs/backup': No such file or directory
Initializing repository at "/mnt/s3fs/backup"
Encryption NOT enabled.
Use the "--encryption=repokey|keyfile" to enable encryption.
Synchronizing chunks cache...
Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0.
Done.
terminating with success status, rc 0
------------------------------------------------------------------------------
Archive name: 2019-02-24--00-17-53
Archive fingerprint: f2a0ce71ff6d0593934330faa4e6d82c3a77a64e759e5d1a699aed72ae38170e
Time (start): Sat, 2019-02-23 23:17:54
Time (end):   Sat, 2019-02-23 23:17:54
Duration: 0.00 seconds
Number of files: 0
Utilization of max. archive size: 0%
------------------------------------------------------------------------------
                       Original size      Compressed size    Deduplicated size
This archive:                  556 B                524 B                524 B
All archives:                  556 B                524 B                524 B

                       Unique chunks         Total chunks
Chunk index:                       2                    2
------------------------------------------------------------------------------
terminating with success status, rc 0
Starting repository check
Starting repository index check
Completed repository check, no problems found.
Starting archive consistency check...
Analyzing archive 2019-02-24--00-17-53 (1/1)
Archive consistency check complete, no problems found.
terminating with success status, rc 0
matzz@matzz ~/test/test $ docker run -h foo --privileged \
> -e "BACKUP_DIRS=/to-backup" \
> -e BORG_REPO="/mnt/s3fs/backup" \
> -e ARCHIVE="$(date +%Y-%m-%d--%H-%M-%S)" \
> -v $(pwd)/borg-archive:/root/.cache/borg \
> -v $(pwd)/source-test:/to-backup \
> -v $(pwd)/borg-repo:/mnt/s3fs \
> pschiffe/borg
Not using encryption. If you want to encrypt your files, set $BORG_PASSPHRASE variable.
Warning: Attempting to access a previously unknown unencrypted repository!
Do you want to continue? [yN] Aborting.
Cache initialization aborted
terminating with error status, rc 2

locale warning while restoring

I got this warning while restoring a file:

Warning: File system encoding is "ascii", extracting non-ascii filenames will not be supported.
Hint: You likely need to fix your locale setup. E.g. install locales and use: LANG=en_US.UTF-8

It's from borg https://github.com/borgbackup/borg/blob/3db27f950e901fa6fcb679962a8432bd1ed059e0/src/borg/archiver.py#L626

Where to place the sshfs identity file

I'm a bit confused where to place the sshfs identity file (guess that's another term for the private SSH key used to connect to a remote server).
Do I put the host path to the key in the SSHFS_IDENTITY_FILE environment variable?
Or does the key need to be in one of the volumes mapped into the container and have to give that path inside the container to the SSHFS_IDENTITY_FILE variable?

Thanks a lot!

How to provide ssh key?

I'd love to use your image to backup to my rmeote borg repsoitory. But how to I provide an SSH key to the container so it can log into the remote repo?
Or is it only intended to use password within the BORG_REPO variable?

Truenas Scale fuse error

Hi,
i'm trying to run this container in TN Scale as a Pod.
I tried with the
SYS_ADMIN --device /dev/fuse
and without.
On truenas, i executed modprobe fuse, module is loaded (lsmod), and /dev/fuse exists on the host.

Error:
fuse: device not found, try 'modprobe fuse' first
(no more text)

Also passing /dev/fuse as voluem does not help.

Any idea?
Thanks

Key authentication not working when Borg/SSH is on another port

Hello, thanks for the awesome container!

When connecting to my remote repo with the container, I keep getting the following errors:

Connection closed by remote host. Is borg working on the server?
terminating with error status, rc 2

I'm using keys for authentication and have the keys (both id_rsa and id_rsa.pub) mounted under root/.ssh.

My remote repo is not on port 22, but 23.
So, for the REPO I have added the following: BORG_REPO='[email protected]:23/./backups/server'

I don't know how to fix this.
Thanks again!

EDIT: borg is on the server, because I can make backups to it with the local install of Borg.

EDIT2: When using a port different than 22, you need to specify ssh://[email protected]".
Withouth the ssh:// part the port gets ignored. I'm just unsure how this container parses that environment variable.
Because if I add ssh:// in front of it (ssh://[email protected]:23/./backups/server) I get the following:

Repository /'ssh:/[email protected]:23/./backups/server does not exist. terminating with error status, rc 2

Keep it up-to-date/add CI/CD

You should really keep your image up-to-date, possibly also add a CI to keep it up-to-date and automatically push updates.
Also GitHub provides Dependabot, though IÄm not sure it would catch these issues here…

The thing is, your image is the most popular on Docker Hub for Borg with >500k pulls.

E.g. here you use Fedora 31:

docker-borg/Dockerfile

Line 1 in 83811ab

FROM fedora:31

Fedora 31 is long outdated/unmaintained, so better upgrade that…