Using SSH (SFTP) Remotes with Docker Compose

This guide details how to configure a Backrest container to back up to a remote server using SSH (SFTP).

This is an advanced topic that assumes you have a basic familiarity with SSH, public key authentication, and Docker Compose.

Prerequisites

  • A working Docker Compose setup for Backrest.
  • An SSH client installed on your local machine (for setup).
  • A remote server with SSH enabled and a user account with write permissions to the backup location.

Setup

The strategy is to create SSH keys and configuration on your Docker host, then securely mount them read-only into the Backrest container.

All commands below should be run on the Docker host, in the same directory as your docker-compose.yml file.

Step 1: Create a Local Directory for SSH Config

First, create a directory to store your SSH key and configuration files. This keeps your Backrest-related files organized.

mkdir -p ./backrest/ssh

Step 2: Generate an SSH Key

Next, generate a new SSH key pair specifically for Backrest.

ssh-keygen -t ed25519 -f ./backrest/ssh/id_rsa -C "backrest-backup-key"

When prompted for a passphrase, you can leave it empty by pressing Enter. Using a passphrase adds another layer of security but requires more complex setup to use with an automated tool like Backrest.

Step 3: Copy the Public Key to Your Remote Server

Copy the public key to your remote server's authorized_keys file. The ssh-copy-id command is the easiest way to do this.

# Replace your-username and example.com with your remote server's details
ssh-copy-id -i ./backrest/ssh/id_rsa.pub your-username@example.com

Step 4: Create the SSH Config and Known Hosts Files

Create an SSH configuration file that Restic (inside the container) will use to connect.

# Create the config file
cat > ./backrest/ssh/config << EOF
Host backrest-remote
    HostName example.com
    User your-username
    IdentityFile /root/.ssh/id_rsa
    Port 22
EOF

# Add the server's fingerprint to known_hosts
ssh-keyscan -H example.com >> ./backrest/ssh/known_hosts

Important:

  • Host backrest-remote: This is a custom alias. You will use this name in the Backrest UI.
  • HostName: The actual IP address or hostname of your remote server.
  • User: The username on the remote server.
  • IdentityFile: This must be /root/.ssh/id_rsa. This is the path inside the container where the key will be mounted.
  • Port: The SSH port of your remote server.

Step 5: Set Secure Permissions

SSH requires that key and configuration files have strict permissions.

chmod 700 ./backrest/ssh
chmod 600 ./backrest/ssh/*

Step 6: Mount the SSH Directory in Docker Compose

Now, edit your docker-compose.yml to mount the backrest/ssh directory into the container. We mount it as read-only (:ro) for better security.

version: "3.8"
services:
  backrest:
    image: garethgeorge/backrest:latest
    container_name: backrest
    # ... other configuration ...
    volumes:
      - ./backrest/data:/data
      - ./backrest/config:/config
      - ./backrest/cache:/cache
      # ... other volumes ...
      - ./backrest/ssh:/root/.ssh:ro # Add this line
      - ./backrest/ssh:/.ssh:ro # Add this line if running rootless
    # ... rest of configuration ...

After saving the file, restart your container for the changes to take effect:

docker compose up -d --force-recreate

Step 7: Add the Repository in Backrest

  1. In the Backrest WebUI, navigate to Repositories and click Add Repository.
  2. For the Type, select Remote/Cloud.
  3. For the URL, enter sftp:backrest-remote:/path/to/your/repo.
    • Replace backrest-remote with the Host alias you defined in backrest/ssh/config.
    • Replace /path/to/your/repo with the absolute path on the remote server where you want to store backups.
  4. Enter a secure Password to encrypt your backup data. This is a new password for the repository itself, not your SSH key password.
  5. Click Initialize Repository.

Troubleshooting

  • Connection Errors: First, test your SSH connection from the host machine to isolate issues. This command uses the exact same configuration files that the container will use. 
    # This command should connect without asking for a password
ssh -vF ./backrest/ssh/config -o UserKnownHostsFile=./backrest/ssh/known_hosts backrest-remote
# -o UserKnownHostsFile ensures that ssh uses ony the public keys passed to the backrest container instead of the global public keys of the host.
    Attempt connection to the server from the container and compare the results : 
    # From the host open a bash terminal to the backrest container
docker exec -it backrest bash

    # Attempt to connect to the server via ssh. If prompt abort the command, saved keys would be ephemeral.
ssh -vF /root/.ssh/config backrest-remote
  • Permission Denied:
    • Double-check the file permissions set in Step 5.
    • Ensure the user on the remote server has write permissions to the repository path.
  • Check Logs: Review the Backrest application logs for detailed error messages from Restic.
Edit this page on GitHub
Table of Contents