lee/backrest
1
0
Fork 0
mirror of https://github.com/garethgeorge/backrest.git synced 2025-10-30 12:17:03 +00:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

docs: cleanup the ssh remotes guide

Browse Source
This commit is contained in:
Gareth
2025-09-07 00:38:45 -07:00
parent 899f30c9bb
commit edf992e701
1 changed files with 84 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
docs/content/3.cookbooks/4.ssh-remote.md
View File

@@ -1,123 +1,126 @@
# SSH Remote
# Using SSH (SFTP) Remotes with Docker Compose
This guide will walk you through the creation of a remote repository using SSH.
This guide details how to configure a Backrest container to back up to a remote server using SSH (SFTP).
Before beginning, be aware that SSH remotes are an advanced topic and basic familiarity with SSH and Unix shell is assumed.
This is an advanced topic that assumes you have a basic familiarity with SSH, public key authentication, and Docker Compose.
## Prerequisites
- SSH client installed on your local machine
- Access to a remote server with SSH enabled
- Basic understanding of SSH key authentication
- Sufficient storage space on the remote server
- 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
### Step 1: Create SSH Configuration Directory
The strategy is to create SSH keys and configuration on your Docker host, then securely mount them read-only into the Backrest container.
First, create a directory to store your SSH configuration files:
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.
```bash
mkdir -p ~/.config/backrest/ssh
mkdir -p ./backrest/ssh
```
### Step 2: Configure SSH Connection
### Step 2: Generate an SSH Key
Create an SSH config file to define your connection parameters:
Next, generate a new SSH key pair specifically for Backrest.
```bash
cat > ~/.config/backrest/ssh/config << EOF
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.
```bash
# 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.
```bash
# Create the config file
cat > ./backrest/ssh/config << EOF
Host backrest-remote
Hostname example.com
Port 22
HostName example.com
User your-username
IdentityFile ~/.config/backrest/ssh/id_rsa
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
```
Replace:
- `backrest-remote` with a memorable name for this connection
- `example.com` with your server's hostname or IP address
- `22` with your SSH port (if different from the default)
- `your-username` with your username on the remote server
**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 3: Generate SSH Key (if needed)
### Step 5: Set Secure Permissions
If you don't already have an SSH key to use, generate one:
SSH requires that key and configuration files have strict permissions.
```bash
ssh-keygen -f ~/.config/backrest/ssh/id_rsa -C "backrest-backup-key"
chmod 700 ./backrest/ssh
chmod 600 ./backrest/ssh/*
```
### Step 4: Add Key to Remote Server
### Step 6: Mount the SSH Directory in Docker Compose
Copy your public key to the remote server:
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.
```bash
ssh-copy-id -i ~/.config/backrest/ssh/id_rsa.pub your-username@example.com
```
### Step 5: Generate Known Hosts File
Create a known_hosts file with your server's fingerprint:
```bash
ssh-keyscan -H example.com > ~/.config/backrest/ssh/known_hosts
```
### Step 6: Set Permissions
Set the appropriate permissions for your SSH files:
```bash
chmod 700 ~/.config/backrest/ssh
chmod 600 ~/.config/backrest/ssh/*
```
If you're running Backrest as root or in a container, you may need to adjust ownership:
```bash
# Only if running as root or in a container
sudo chown -R root:root ~/.config/backrest/ssh/
```
### Step 7: Configure Backrest
#### For Docker Installations
If you're running Backrest in Docker, update your `compose.yml` to mount the SSH directory:
```yml
```yaml
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 ...
- ~/.config/backrest/ssh:/root/.ssh
- ./backrest/ssh:/root/.ssh:ro # Add this line
# ... rest of configuration ...
```
#### For Native Installations
After saving the file, restart your container for the changes to take effect:
For native installations, Backrest will use the SSH directory you specified in the previous steps.
```bash
docker compose up -d --force-recreate
```
### Step 8: Add Repository in Backrest
### Step 7: Add the Repository in Backrest
In the Backrest web interface:
1. Click "Add Repository"
2. Select "SFTP" as the repository type
3. Enter the repository URL in the format: `sftp:backrest-remote:/path/to/backup/location`
- `backrest-remote` is the host name from your SSH config
- `/path/to/backup/location` is the directory on the remote server where backups will be stored
4. Set the SSH directory to: `~/.config/backrest/ssh` (or `/root/.ssh` if running in Docker)
5. Enter your repository password (this is for encrypting backups, not your SSH password)
6. Click "Initialize Repository" (or "Connect to Existing" if the repository already exists)
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
If you encounter connection issues:
1. Check that your SSH key has the correct permissions: `chmod 600 ~/.config/backrest/ssh/id_rsa`
2. Verify you can connect manually: `ssh -F ~/.config/backrest/ssh/config backrest-remote`
3. Ensure the remote directory exists and is writable
4. Check Backrest logs for detailed error messages
- **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.
```bash
# This command should connect without asking for a password
ssh -F ./backrest/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.