Multihost Sync

Backrest supports syncing configuration and operation history between multiple instances. This allows you to monitor and manage backups across several machines from a single Backrest installation.

Concepts

Server: A Backrest instance that accepts connections from other instances. The server can push shared repos to clients and receive operation updates from them.

Client: A Backrest instance that connects to a server. The client sends its backup operation history to the server and can receive shared repo configurations.

Pairing Token: A one-time token generated by the server that allows a client to authenticate and register itself as an authorized client.

Shared Repo: A repository on the server marked as "shared." Its configuration is automatically pushed to all connected clients that have the Receive Shared Repos permission.

Setup Overview

The typical setup flow is:

1. Configure both instances with unique Instance IDs (Settings > General)
2. On the server, generate a pairing token with the desired permissions
3. On the client, add the server as a known host using the pairing token and the server's instance URL.
4. The client connects and is automatically registered as an authorized client on the server

Step 1: Generate a Pairing Token (Server)

1. Open Settings on the server instance
2. Scroll to the Multihost section
3. Under Pairing Tokens, click Generate
4. Configure the token:
   • Label: A human-readable name (e.g. "laptop-backup")
   • TTL: How long the token is valid (e.g. 15 minutes, 1 hour, or forever)
   • Max Uses: How many clients can pair with this token (0 = unlimited)
   • Permissions: What the paired client will be allowed to do (see Permissions below)
5. Copy the generated token string — it will look like <keyid>:<secret>#<instanceid>

TIP

Pairing tokens are consumed on use. Once a client has paired, the token is no longer needed. Generate short-lived tokens with limited uses for better security.

Step 2: Connect the Client

1. Open Settings on the client instance
2. Scroll to the Multihost section
3. Under Known Hosts, click Add
4. Paste the pairing token from the server
5. Enter the server's Instance URL (e.g. https://backrest.example.com:9898)
6. Save the configuration

The client will connect to the server, present the pairing secret, and be automatically registered as an authorized client. After pairing, the token is cleared and authentication uses public key identity going forward.

Permissions

Permissions control what a connected client can do. They are configured when generating a pairing token or by editing an authorized client's permissions after pairing.

Permission	Description
Read Operations	The client sends its operation history (backup results, errors, etc.) to the server. This enables centralized monitoring.
Read Config	The client can read repo and plan configuration from the server.
Read/Write Config	The client can read and write repo and plan configuration on the server.
Receive Shared Repos	The server automatically pushes all repos marked as "shared" to this client.

Scopes

Permissions (except Receive Shared Repos) can be scoped to specific repos or plans:

• All (*): Applies to all repos and plans
• Specific repo: repo:<repo_id> — applies only to the named repo
• Specific plan: plan:<plan_id> — applies only to the named plan
• Exclude repo: !repo:<repo_id> — applies to all except the named repo
• Exclude plan: !plan:<plan_id> — applies to all except the named plan

Shared Repos

Marking a repo as "shared" on the server causes its configuration to be automatically pushed to all authorized clients with the Receive Shared Repos permission. For a repo to be copied the client must both have the permission "Receive Shared Repos" on the host providing the repo, and must grant that host the "Receive Shared Repos" permission on the client as well (allowing the host to copy the repo into the client's config). The permission is required on both ends.

To share a repo:

1. Open the repo's settings on the server
2. Enable the Shared toggle
3. Save

When a shared repo is received by a client:

• The repo appears in the client's repo list with its originInstanceId set to the server's instance ID
• The repo is read-only on the client — it cannot be edited, only deleted
• Scheduling of maintenance tasks (prune, check, forget) is skipped for shared repos on the client — the server that owns the repo manages these operations
• The client can still run backups to the shared repo if it has plans configured for it

WARNING

Shared repos are identified by their GUID. If the client already has a local repo with the same GUID, the shared repo will be skipped to avoid conflicts.

Monitoring Sync Status

After setup, the server's Settings page shows the connection status of each authorized client. A green indicator means the client is currently connected and syncing.

The sync protocol uses a persistent bidirectional connection with:

• Heartbeats to detect disconnections
• Automatic reconnection with exponential backoff if the connection drops
• Manifest-based reconciliation to efficiently sync only changed operations

Typical Configurations

Centralized Monitoring

Push backup status from multiple machines to a single dashboard:

• Server permissions: Read Operations scoped to *
• Shared repos: Not needed — each client manages its own repos
• Result: Server's operation log shows backup results from all clients

Shared Repository

Multiple machines back up to the same repository, managed by the server:

• Server permissions: Receive Shared Repos + Read Operations scoped to *
• Server repo: Mark the target repo as Shared
• Result: Clients receive the repo config automatically. The server handles forget, prune, and check. Clients run their own backup plans against the shared repo.

Full Config Management

Server manages configuration for all clients:

• Server permissions: Read/Write Config scoped to * + Receive Shared Repos
• Result: The server can push config changes (repos and plans) to connected clients

Reverse Proxy

When exposing a Backrest server to remote clients, you only need to expose the sync RPC path. All other Backrest endpoints (UI, admin API, metrics, downloads) should remain on your trusted network.

Path to expose: /v1sync.BackrestSyncService/

This is the single bidirectional gRPC/Connect stream peers use to sync. The protocol runs its own post-quantum-safe encrypted transport on top of the connection, but you should still terminate TLS at the proxy.

Requirements:

• HTTP/2 end-to-end (or h2c to the upstream) — the sync stream is a long-lived bidi stream and will not work over HTTP/1.1.
• No response buffering on the proxy.
• Long timeouts (hours, not seconds) — the stream is intentionally persistent.
• No request/response size limits on the sync path.

Caddy

backrest.example.com {
    @sync path /v1sync.BackrestSyncService/*
    reverse_proxy @sync h2c://127.0.0.1:9898 {
        flush_interval -1
        transport http {
            read_timeout 24h
            write_timeout 24h
        }
    }
}

Replace 127.0.0.1:9898 with your Backrest instance's bind address. Any path other than /v1sync.BackrestSyncService/* will return 404, keeping the UI and admin API off the public internet.

If you also want to expose the UI publicly (not recommended without additional auth in front), add a second reverse_proxy block without the path matcher — but be aware this also exposes the admin API.

Troubleshooting

Client can't connect: Verify the Instance URL is reachable from the client. The URL should include the port (default 9898). If using a reverse proxy, ensure it supports HTTP/2 (needed for the bidirectional sync stream) and is configured to allow long polling requests (e.g. 10+ minutes). Disable any proxy timeouts or payload size limits that could interfere with the sync connection. Recommend using a modern reverse proxy like Caddy. See the Reverse Proxy section above for a working Caddy config.

Pairing fails: Check that the pairing token hasn't expired and hasn't exceeded its max uses. Generate a new token if needed.

Shared repo not appearing on client: Verify the client has the Receive Shared Repos permission. Check that the repo is marked as "shared" on the server. If the client already has a repo with the same GUID, the shared repo will be skipped.

Stale snapshots on client: When the server runs forget and removes snapshots, the client discovers this the next time it indexes snapshots for that repo (typically after a backup). If the client doesn't run backups to a shared repo, its snapshot list may show snapshots that the server has already forgotten until the next index operation.