Skip to main content

Multi-Node Cluster

BackupX supports Master-Agent mode: backup tasks can be routed to specific nodes. The Agent runs the backup locally and uploads straight to storage. All connections are initiated by the Agent, so remote networks only need outbound HTTP access.

Architecture​

[Web Console] ─── JWT ──→ [Master (backupx)]
                              ↑  ↓
                              │  │ HTTP long-poll (token auth)
                              │  ↓
                         [Agent (backupx agent)]   ← runs on remote host
                              ↓
                     [70+ Storage Backends]
  • Protocol — HTTP long-polling; the Agent initiates every connection
  • Heartbeat — Agent reports every 15s; Master marks nodes offline after 45s of silence
  • Dispatch — Master persists run_task commands to a queue; Agent polls and claims them
  • Execution — Agent reuses the same BackupRunner (file / mysql / postgresql / sqlite / saphana) and uploads directly to storage
  • Security — Each node has its own token; the Agent never holds the Master's JWT secret or AES-256 key

Walkthrough​

1. Open the install wizard​

In the Web Console → Node Management → Add Node. You'll see a three-step wizard.

  • Step 1 — Node info. Give the node a name, or switch to batch mode and paste multiple names (one per line, max 50).
  • Step 2 — Deploy options. Pick install mode (systemd recommended, docker, or foreground for debugging), architecture (auto-detect by default), agent version (defaults to the master's version), TTL for the install link (5 min / 15 min / 1 h / 24 h), and download source (github direct, or the ghproxy mirror for mainland China).
  • Step 3 — Copy the command. A single curl ... | sudo sh line is shown with a live countdown. Click copy, paste into the target machine, and run with root privileges.

2. One-line install on the target host​

Example (systemd mode):

curl -fsSL https://master.example.com/install/Xk3p9...vM | sudo sh

The script runs automatically and:

  1. Detects OS and architecture (uname -m)
  2. Downloads the matching backupx binary from GitHub Release (or the ghproxy mirror)
  3. Installs to /opt/backupx-agent and creates a backupx system user
  4. Writes /etc/systemd/system/backupx-agent.service with the token baked into environment variables
  5. Runs systemctl enable --now backupx-agent
  6. Polls /api/v1/agent/self until the master confirms status: online (up to 30 s)

Reruns are idempotent — to upgrade or re-provision, simply generate a new install command and run it again. The one-time install link expires after its TTL or after first consumption, whichever is sooner.

3. Rotate agent tokens at any time​

Go to the node's action menu (︙) → Rotate Token. The new token is shown once and the old token remains valid for 24 h, allowing rolling restarts without downtime. After 24 h, the old token is rejected.

4. Batch deployment​

In Step 1 choose "Batch" and paste node names (one per line, max 50). Step 3 shows a table with one command per node plus a Download .sh button that bundles all commands into a shell script, convenient for SSH loops or Ansible tasks.

5. Route a task to the node​

In the Backup Tasks page, pick the target node when creating the task. When the task runs:

  • Local (nodeId=0) → Master executes in-process
  • Remote node → Master enqueues the command → Agent claims → Agent runs locally → uploads → reports back

Known limitations​

  • Encrypted backups don't work via Agent — the Agent doesn't hold Master's AES-256 key. Tasks with encrypt: true will fail if routed to an Agent
  • Directory browser timeout — remote dir listing is a synchronous RPC through the queue (15s default)
  • Dispatched command timeout — claimed-but-unfinished commands are marked timeout after 10 minutes

CLI reference​

backupx agent --help
  -master string    Master URL
  -token string     Agent auth token
  -config string    YAML config path (takes precedence over env)
  -temp-dir string  Local temp directory (default /tmp/backupx-agent)
  -insecure-tls     Skip TLS verification (testing only)

systemd unit​

/etc/systemd/system/backupx-agent.service
[Unit]
Description=BackupX Agent
After=network.target

[Service]
Type=simple
User=backupx
Environment="BACKUPX_AGENT_MASTER=https://master.example.com"
Environment="BACKUPX_AGENT_TOKEN=your-token"
ExecStart=/opt/backupx/backupx agent
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable --now backupx-agent
sudo journalctl -u backupx-agent -f