Skip to content

Remote Storage

Jump to bottom
Marc Pope edited this page Apr 24, 2026 · 3 revisions

Remote Storage (SSH)

BBS supports creating borg repositories on remote SSH hosts like rsync.net, BorgBase, Hetzner Storage Box, and any SSH-accessible server with borg installed. Agents back up directly to the remote host at native speed — no backup data flows through the BBS server. After each backup completes, catalog metadata is streamed back to BBS so that the file browser and search remain fully functional for restores.

Overview

What It Does:

  • Stores borg repositories on remote SSH hosts instead of the BBS server's local disk
  • Agents connect directly to the remote host for backups and restores
  • BBS server connects over SSH for maintenance operations (prune, compact, check)
  • SSH private keys are encrypted at rest with AES-256-GCM

Why Use It:

  • Geographic Redundancy: Store backups in a different physical location without S3
  • Provider Choice: Use dedicated borg hosting from rsync.net, BorgBase, Hetzner, etc.
  • Cost Effective: Many providers offer inexpensive append-only borg storage
  • Simplicity: No S3, rclone, or object storage configuration required — just SSH

How It Works

Architecture

Normal (local) flow:
  Agent --SSH--> BBS Server --borg create--> /var/bbs/home/repo

Remote SSH flow:
  Agent --SSH--> Remote Host --borg create--> ssh://user@host/./repo
  BBS Server --SSH--> Remote Host  (for prune/compact/check)

With remote storage, backup data never touches the BBS server. The agent connects directly to the remote host to create archives. The BBS server connects to the remote host separately for server-side maintenance operations like prune, compact, and check.

Data Flow

  1. Backups: The agent receives the remote SSH key in its task payload, writes it to a temporary file, and runs borg create directly against the remote host
  2. Restores: Same direct connection — the agent extracts files from the remote repository
  3. Maintenance: The BBS server SSH's to the remote host to run prune, compact, check, and other borg operations
  4. Monitoring: Archive listings and file catalogs are populated by the BBS server querying the remote repo over SSH

Compatible Providers

Provider Port Remote Borg Path Base Path Notes
rsync.net 22 borg1 ./ Dedicated borg hosting, append-only support
BorgBase 22 (default) ./repo Borg-specific hosting with monitoring
Hetzner Storage Box 23 (default) ./backups Affordable storage with SSH access
Any SSH server Custom Custom Custom Any server with borg installed

Setup

Step 1: Configure a Remote SSH Host

Remote SSH host configurations are managed globally in Settings and can be reused across multiple repositories and clients.

  1. Navigate to Settings → Remote Storage tab
  2. Click Add Host
  3. Fill in the connection details:
Field Required Description Example
Name Yes Descriptive name for this host rsync.net Production
Provider Preset No Auto-fills common settings rsync.net, BorgBase, Hetzner
Host Yes Hostname or IP address ch-s010.rsync.net
Port Yes SSH port (default: 22) 22 (rsync.net), 23 (Hetzner)
Username Yes SSH username 12345 (rsync.net account number)
Base Path No Base directory on remote host ./ (default, relative to home)
SSH Private Key Yes PEM-format private key Paste full key including headers
Remote Borg Path No Custom borg binary name borg1 (required for rsync.net)
  1. Click Add Host

Provider Presets

Selecting a provider preset auto-fills the Port, Base Path, and Remote Borg Path fields:

  • rsync.net: Port 22, Base Path ./, Remote Borg Path borg1
  • BorgBase: Port 22, Base Path ./repo
  • Hetzner Storage Box: Port 23, Base Path ./backups
  • Custom: All fields blank for manual entry

Step 2: Test the Connection

After adding a host, verify connectivity:

  1. Click the plug icon on the host card
  2. BBS will SSH to the host and run borg --version (or the custom borg binary)
  3. A green success message shows the borg version installed on the remote host
  4. A red error message indicates connection or borg availability issues

Step 3: Create a Remote Repository

  1. Navigate to Clients → Select a client → Repos tab
  2. Click Create Repository
  3. In the Storage dropdown, select Remote SSH
  4. In the Remote Host dropdown, select your configured host
  5. Enter a repository name and choose encryption settings
  6. Click Create Repository

BBS will run borg init on the remote host over SSH. If initialization succeeds, the repository is ready for backups.

Note: The "Remote SSH" option only appears in the Storage dropdown if you have at least one remote host configured in Settings.

Managing Remote Hosts

Editing a Host

  1. Go to Settings → Remote Storage
  2. Click the pencil icon on the host card
  3. Update the fields as needed
  4. Leave the SSH Private Key field blank to keep the existing key
  5. Click Save

Deleting a Host

  1. Go to Settings → Remote Storage
  2. Click the trash icon on the host card
  3. Confirm the deletion

Deletion is blocked if any repositories still reference this host. Delete or migrate those repositories first.

Using Remote Repositories

Backups

Remote repositories work identically to local repositories for backup purposes:

  1. Create a backup plan that targets the remote repository
  2. Schedule it as you would any backup plan
  3. The agent backs up directly to the remote host

The only difference is the data path — instead of flowing through the BBS server, data goes directly from the agent to the remote host.

Restores

All restore types work with remote repositories:

  • File restore: Browse archives, select files, restore to the agent
  • MySQL restore: Extract database dumps from remote archives and import
  • PostgreSQL restore: Extract database dumps from remote archives and import

Maintenance

All server-side maintenance operations work over SSH:

  • Prune: Removes old archives per retention policy
  • Compact: Reclaims space after pruning
  • Check: Verifies repository integrity
  • Repair: Fixes repository errors
  • Break Lock: Removes stale locks
  • Catalog Sync: Rebuilds archive listing from remote repo
  • Catalog Rebuild: Rebuilds file catalog from remote repo

These are queued and executed by the BBS server, which SSH's to the remote host to run the borg commands.

S3 Sync

Remote repositories do not support S3 offsite sync — they are already offsite. The S3 Offsite Mirror section is hidden on remote repository detail pages. If an S3 sync job is queued for a remote repository, it completes immediately with a skip message.

Repository Detail Page

Remote repositories display differently on the detail page:

  • Badge: A blue "Remote SSH" badge appears next to the repository name
  • Location: Shows user@host:port instead of a local filesystem path
  • Config Name: The remote host configuration name appears in parentheses
  • S3 Section: Hidden (not applicable for remote repos)
  • Maintenance: All maintenance buttons work normally (operations run over SSH)

SSH Key Security

Encryption at Rest

SSH private keys are encrypted using AES-256-GCM before being stored in the database. The encryption uses BBS's APP_KEY from the server configuration.

Key Handling During Operations

Agent-side (backups and restores):

  1. The BBS server decrypts the SSH key and includes it in the task payload sent to the agent
  2. The agent writes the key to a temporary file (/tmp/bbs-remote-ssh-key) with 0600 permissions
  3. BORG_RSH is configured to use this temporary key file
  4. After the borg operation completes (or fails), the temporary key file is deleted in a finally block

Server-side (maintenance):

  1. The BBS server decrypts the SSH key
  2. Writes it to a temporary file with 0600 permissions
  3. Runs borg commands with BORG_RSH pointing to the temporary key
  4. Deletes the temporary key file after the operation

Best Practices

  • Use a dedicated SSH key pair for BBS — do not reuse keys from other systems
  • Grant the key minimal permissions on the remote host (borg-only access if supported)
  • Enable append-only mode on the remote host — see Append-Only Mode on Remote Hosts below
  • Rotate SSH keys periodically by editing the host configuration in Settings

Append-Only Mode on Remote Hosts

Append-only is the single most important defense against ransomware hitting your backups. It lets a client write new archives but forbids deleting or modifying existing ones. Even a fully compromised agent — stolen SSH key, ransomware, hostile insider — can add backups but cannot erase the ones already on disk.

How BBS handles it for local storage

For repositories stored directly on the BBS server, append-only is enforced automatically. Every agent SSH key installed on BBS is registered with a forced command (bbs-ssh-gate) that execs borg serve --append-only --restrict-to-path <tenant>. The agent cannot bypass it — even if it tries to issue a borg delete, the server-side borg serve refuses.

Prune and compact still work because they run from the BBS server itself, which holds a separately-privileged key path.

How to enable it on remote hosts

When the repository lives on a third-party SSH host (rsync.net, BorgBase, Hetzner, etc.), BBS does not control the remote's authorized_keys file, so the forced command has to be configured on the remote side. Every major borg-friendly provider supports this; the setup is a one-time edit.

The pattern (from the upstream borg docs) is:

command="borg serve --append-only --restrict-to-path /path/to/repo",restrict ssh-ed25519 AAAA… backup-client
  • command="…" — forces every SSH session from this key to run borg serve --append-only, ignoring whatever the client asked for.
  • --restrict-to-path — limits access to a specific repository path. If you omit this the key can reach any repo on the account.
  • restrict — disables port forwarding, X11, PTY, and other SSH features the key doesn't need.

You can even mix modes by using different keys: one append-only key for BBS, and a separate full-access key you keep offline for occasional manual pruning.

rsync.net

  1. SSH in with a full-access key: ssh <account>@<your-server>.rsync.net
  2. Open .ssh/authorized_keys and find the line for the key you gave to BBS
  3. Prepend the forced command: 
    command="borg1 serve --append-only --restrict-to-path /data/home/<account>",restrict ssh-ed25519 AAAA… bbs-agent
    Note: rsync.net uses borg1 (not borg) as the binary name — same as BBS's Remote Borg Path setting.
  4. Save. Next BBS backup will still work; any delete/prune attempt from the agent will be rejected by borg serve.
  5. Run prune/compact from BBS's own maintenance buttons — those use the server-side key path which BBS also forces through borg serve, but without --append-only, so cleanup still works.

BorgBase

BorgBase has first-class UI support — no authorized_keys editing required:

  1. Log in to the BorgBase dashboard
  2. Go to Account → SSH Keys
  3. Find the key you added for BBS and check Append-only
  4. Save

Done. BorgBase rewrites the forced command on its side.

Hetzner Storage Box

Hetzner exposes a standard authorized_keys file via SFTP. Their borg access docs cover the SSH setup; the append-only addition is the command= prefix.

  1. Connect with SFTP: sftp -P 23 u<XXXXXX>@u<XXXXXX>.your-storagebox.de
  2. Download .ssh/authorized_keys locally: get .ssh/authorized_keys
  3. Edit the line for the BBS key: 
    command="borg serve --append-only --restrict-to-path /home/backups",restrict ssh-ed25519 AAAA… bbs-agent
    Adjust the path to match the Base Path you configured in BBS (default: ./backups, which resolves to /home/backups on the box).
  4. Upload it back: put authorized_keys .ssh/authorized_keys
  5. Your next BBS backup will still succeed; destructive commands are rejected.

Custom SSH server

On any Linux box running your own SSH + borg, edit the BBS key's line in the user's ~/.ssh/authorized_keys:

command="borg serve --append-only --restrict-to-path /srv/backups/bbs",restrict ssh-ed25519 AAAA… bbs-agent

This is the same pattern BBS itself uses internally — it's the canonical borg ransomware-resistance configuration.

What to expect afterward

  • Backups: keep working normally. The agent doesn't know or care that the server refuses deletes.
  • Prune / compact (from BBS): will fail against the offsite repo if you forced --append-only on the only key BBS has. You have two choices:
    • Accept that offsite retention is handled manually (log in with a full-access key when you need to clean up).
    • Keep two separate keys: one append-only key installed in BBS as the agent/backup path, and a separate full-access key used only for maintenance. BBS currently wires one key per remote host, so if you go the two-key route, the simpler option is to let retention happen on the BBS-local copy and treat the offsite copy as archival.
  • Restores: still work fine. Borg extract reads from the repo; nothing about append-only blocks reads.

Verifying it's working

After enabling append-only, try to delete an archive manually from a client machine:

borg delete ssh://user@host/./repo::test-archive

You should see:

Remote: Cannot delete archives when --append-only is set

If the delete succeeds, the forced command isn't being applied — double-check the authorized_keys syntax (no line breaks, correct quoting around the command).

Provider Setup Guides

rsync.net

rsync.net provides dedicated borg hosting with optional append-only mode.

  1. Get your account: Sign up at rsync.net and note your account number (used as username)
  2. Add your SSH key: Upload your public key via the rsync.net web portal
  3. Configure BBS:
    • Host: Your assigned server (e.g., ch-s010.rsync.net)
    • Port: 22
    • Username: Your account number (e.g., 12345)
    • Base Path: ./
    • Remote Borg Path: borg1 (required — rsync.net uses borg1 for BorgBackup 1.x)
  4. Test Connection: Should show borg version 1.x

Important: rsync.net uses borg1 as the borg binary name, not borg. You must set the Remote Borg Path to borg1 or backups will fail.

BorgBase

BorgBase is a managed borg repository hosting service.

  1. Create a repository on BorgBase and note the SSH connection string
  2. Add your SSH key to BorgBase
  3. Configure BBS:
    • Host: Your BorgBase server hostname
    • Port: 22
    • Username: Your BorgBase repo identifier
    • Base Path: ./repo
    • Remote Borg Path: (leave blank)
  4. Test Connection: Should show the borg version

Hetzner Storage Box

Hetzner Storage Boxes support borg over SSH on port 23.

  1. Enable SSH on your Storage Box in the Hetzner Robot panel
  2. Add your SSH key via the Hetzner panel or ssh-copy-id
  3. Install borg on the Storage Box (if not pre-installed): 
    ssh -p 23 uXXXXXX@uXXXXXX.your-storagebox.de borg --version
  4. Configure BBS:
    • Host: uXXXXXX.your-storagebox.de
    • Port: 23
    • Username: uXXXXXX
    • Base Path: ./backups
    • Remote Borg Path: (leave blank)
  5. Test Connection: Should show the borg version

Custom SSH Server

Any server with borg installed can be used as a remote storage host.

  1. Install borg on the remote server
  2. Create a dedicated user for BBS backups
  3. Add the BBS SSH public key to the user's ~/.ssh/authorized_keys
  4. Configure BBS with the server's connection details
  5. Test Connection to verify borg is accessible

Troubleshooting

Test Connection Fails

Error: "Connection refused" or "Connection timed out"

Solutions:

  • Verify the hostname and port are correct
  • Check that SSH is enabled on the remote host
  • Verify firewall rules allow outbound SSH from the BBS server
  • Try connecting manually: ssh -p PORT user@host

Error: "Permission denied (publickey)"

Solutions:

  • Verify the SSH private key matches the public key on the remote host
  • Check that the key is in PEM format (starts with -----BEGIN)
  • Ensure the remote user's ~/.ssh/authorized_keys contains the corresponding public key
  • Check file permissions on the remote host (~/.ssh should be 700, authorized_keys should be 600)

Error: "borg: command not found" or similar

Solutions:

  • Verify borg is installed on the remote host
  • For rsync.net, set Remote Borg Path to borg1
  • For custom servers, ensure borg is in the user's PATH or specify the full path

Backup Fails with "Identity file not accessible"

Cause: The temporary SSH key file was not written before borg started.

Solutions:

  • Update to BBS v1.2.1 or later (this bug was fixed for database restores)
  • Check the agent log (/var/log/bbs-agent.log) for key write errors
  • Verify the agent has write permissions to /tmp/

Maintenance Operations Fail

Error: "Remote SSH config not found"

Solutions:

  • The remote host configuration may have been deleted
  • Check Settings → Remote Storage to verify the host exists
  • The repository may have an orphaned remote_ssh_config_id

Error: SSH timeout during prune/compact/check

Solutions:

  • Large repositories may take time — check if the operation is still running
  • Verify the BBS server can reach the remote host
  • Check for stale locks on the remote repository (use Break Lock)

Comparison: Remote SSH vs S3 Offsite Sync

Feature Remote SSH S3 Offsite Sync
Storage type SSH server with borg S3-compatible object storage
Data format Native borg repository Borg repository mirrored via rclone
Agent connection Direct to remote host Through BBS server (local repo)
Local copy on BBS No Yes (primary copy is local)
Deduplication Native borg dedup Borg dedup + rclone sync
Restore speed Direct from remote host Download from S3, then restore
Provider examples rsync.net, BorgBase, Hetzner AWS S3, Wasabi, Backblaze B2
Best for Primary offsite storage Secondary offsite copy
Append-only support Yes (provider-dependent) No (S3 lifecycle rules instead)

When to use Remote SSH: You want your primary (and only) repository to live on a remote host. No local disk usage on the BBS server.

When to use S3 Offsite Sync: You want a local repository on the BBS server with an additional cloud copy for disaster recovery.

You can use both: Create some repositories locally with S3 sync, and other repositories on remote SSH hosts. They are independent features.

Next: Repositories | S3-Offsite-Sync | Settings

📖 User Manual

Getting Started

Using BBS

Monitoring

Administration

Reference

Clone this wiki locally