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
    # ... 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 -F ./backrest/ssh/config backrest-remote
  

  Copy to clipboard
• 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.