Install Guide

A step-by-step walkthrough for standing up a BackupBloc server and attaching Linux or macOS clients to it. The entire flow is driven by two scripts — install-server.sh and install-agent.sh (or install-agent-mac.sh) — and takes roughly ten minutes end-to-end.

descriptionOverview

BackupBloc has two pieces you install, plus an optional third for off-site resilience:

1. Backup server — one host that runs rest-server (repository storage), the Flask management API, the admin web UI, and nginx as the TLS-terminating reverse proxy.
2. Backup agent — one install per machine you want to back up. The agent is just restic plus a systemd timer (Linux) or LaunchDaemon (macOS) that runs snapshots on a schedule and reports status back to the server.
3. DR server optional — a second server in another location that keeps an append-only, off-site mirror of your backups. See Disaster recovery.

All encryption happens on the agent side, so the server never sees plaintext. The server just stores encrypted, content-addressed blobs.

checklistRequirements

hubArchitecture

┌─────────────────────── BACKUP SERVER ──────────────────────────┐
│                                                                 │
│   nginx :443        ──►   backup-api :5000   (Flask, mgmt)      │
│   nginx :443/restic ──►   rest-server :8000  (restic repo I/O)  │
│                           │                                     │
│                           ▼                                     │
│                    /var/lib/restic-repos/                       │
│                      ├── default/                               │
│                      └── offsite/                               │
└─────────────────────────────────────────────────────────────────┘
         ▲
         │ HTTPS (restic backup + admin heartbeat)
         │
┌─── AGENTS ──────────────────────────────────────────────────────┐
│  web-01 (Linux)    db-01 (Linux)    MacBook (macOS)             │
│  systemd timer     systemd timer     launchd                    │
└─────────────────────────────────────────────────────────────────┘

dns1 · Backup server — prepare the host

Provision a fresh Linux VM or dedicated machine. Point DNS at it if you plan to use a hostname (required for Let's Encrypt). Open the ports in the table below inbound.

terminalRun the server installer

curl -fsSL https://backupbloc.com/downloads/backupbloc-server.tar.gz -o backupbloc-server.tar.gz
tar -xzf backupbloc-server.tar.gz
cd backupbloc-serverCopy

sudo ./install-server.shCopy

Access Points:
  Admin UI:    https://backup.example.com:8080
  REST Server: https://backup.example.com:8000

Credentials:
  Username: admin
  Password: xxxxxxxxxxxxxxxxxxx

task_altVerify the services

Three systemd units should be active (running):

systemctl status restic-rest-server restic-api nginxCopy

If any are red, check their logs:

journalctl -u restic-rest-server -n 50 --no-pager
journalctl -u restic-api          -n 50 --no-pagerCopy

loginFirst login

verified_user2 · Backup agent — authorise first

Every agent needs to be authorised before it can register. BackupBloc supports two styles:

• Server license (IP-bound) — for fixed servers with a static public IP. You pre-authorise the IP in the admin UI under Clients → Add Server. The agent installer reads the public IP at runtime, the server validates it, and credentials are returned automatically — no password entry.
• Personal key — for laptops and roaming machines. You generate a BB-XXXXXXXX-XXXXXXXX key in the admin UI under Clients → Personal Licenses and paste it into the installer.

memoryLinux agent install

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-agent.sh)Copy

systemctl status restic-backup.timer
systemctl list-timers | grep resticCopy

laptop_macmacOS agent install

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-agent-mac.sh)Copy

sudo launchctl list | grep backupbloc
log show --predicate 'process == "bash"' --last 5m --infoCopy

fact_checkVerify the first backup

1. Open the admin UI → Clients. The new host should appear with a green dot within ~60 seconds of install.
2. Click it → Snapshots. The first snapshot should show up after the scheduled run (or immediately, since the installer triggers an initial run).
3. Pick a snapshot → Browse files to confirm the content looks right. You can restore individual files or whole directories from here.

restoreRestoring files

Restore from any snapshot to one of three destinations — the original client, the backup server itself, or a brand-new / different server (for rebuilding a machine that has failed). The same chooser appears whether you restore from the primary backup or from a DR copy.

Restoring to a new / replacement server

This is the disaster-recovery path: a server failed, you've built a replacement, and you want its data back on it. Choose New / other server, then one of:

• Registered agent — the replacement already has the BackupBloc agent installed. Pick it from the list; the manager restores onto it.
• By SSH details — the replacement has no agent yet. Enter its IP/hostname and SSH port. First authorise the manager's key on it (the dialog shows the exact command):

  mkdir -p /root/.ssh && echo 'ssh-ed25519 AAAA…' >> /root/.ssh/authorized_keys && chmod 600 /root/.ssh/authorized_keysCopy

Set the destination path on the new server — use / for a full system recovery, or a staging folder (e.g. /var/tmp/recovery) to copy specific data across first. The manager SSHes in, installs restic if missing, then restores either directly (the new server pulls the repo over the network — fast) or via relay (the manager restores and streams the files over SSH) if the new server can't reach the backup server's REST port. The path is chosen automatically and shown live.

delete_foreverUninstall the agent

When you decommission a machine, run the uninstaller on the host and remove the client in the panel. Doing only one of those leaves the other side polling / accumulating noise.

Linux

One-line install/uninstall — downloads from the CDN and runs:

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/uninstall-agent.sh)Copy

If the host is air-gapped, copy uninstall-agent.sh across and run sudo bash uninstall-agent.sh.

The script stops + disables the systemd units (restic-backup.timer, restic-mysql-backup.timer, restic-restore-poller.timer), removes the cron entry if present, deletes the binaries under /usr/local/bin, and clears /etc/restic-agent + /var/log/restic-agent.

macOS

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/uninstall-agent-mac.sh)Copy

Tears down the LaunchDaemon (com.backupbloc.agent), removes the binaries, and clears the agent config + logs the same way.

Manual one-liner (if you can't fetch the script)

sudo systemctl disable --now restic-backup.timer restic-mysql-backup.timer restic-restore-poller.timer 2>/dev/null
sudo rm -f /etc/systemd/system/restic-{backup,mysql-backup,restore-poller}.{service,timer}
sudo rm -f /usr/local/bin/restic-{backup,mysql-backup,progress-reporter,restore-reporter,restore-poller,validate-license}
sudo rm -rf /etc/restic-agent /var/log/restic-agent /etc/cron.d/restic-restore-poller
sudo systemctl daemon-reloadCopy

Then in the panel

1. Open Clients, find the row, click Delete.
2. Choose Remove client, keep backups if you want to retain the snapshots (restorable forever) — or Remove + delete all backups to also delete the repository on the server.
3. Either choice revokes the agent's license entry, so even if the uninstaller didn't run, the agent stops backing up on its next license re-check (within 24 h).

cloud_sync3 · Disaster recovery (DR)

Disaster recovery keeps a second, off-site copy of your backups on a separate server — so even if the main backup server is lost, corrupted, or its repository is wiped, your data survives. A DR server holds an append-only mirror of selected repositories: new backup data is copied to it on a schedule, but anything deleted or pruned on the main server is never deleted on the DR. Accidental deletions and ransomware can't propagate.

The whole feature is managed from the existing admin UI under Disaster Recovery → DR Servers — there is no second panel to log in to.

schemaHow it works

┌──────────── MAIN BACKUP SERVER ────────────┐        ┌─────────── DR SERVER ───────────┐
│  /var/lib/restic-repos/  (canonical)        │        │  /var/lib/restic-repos/ (mirror) │
│        │                                    │  SSH   │        ▲                         │
│        └── rclone copy (append-only) ───────┼────────┼────────┘                         │
│            every 5 min … 6 h, per repo      │ (SFTP) │  append-only rest-server :8000   │
└─────────────────────────────────────────────┘        └──────────────────────────────────┘
            restore / browse  ◄──────────────────────────────  (restic over SSH)

• Append-only — replication uses rclone copy (never sync), so files removed on the main server are kept on the DR.
• Snapshots copied last — data and indexes are copied before snapshot files, so the DR copy is always a valid, restorable repository even mid-sync.
• All over SSH — the main server reaches the DR with its existing trigger key. No extra credentials travel the network in cleartext.
• Same encryption — the DR holds the identical encrypted repo, so the main server's existing repo password unlocks it for restores. Nothing new to manage.

checklistDR requirements

rocket_launchOption A — Set up a new DR node (recommended)

This provisions a blank server into a full DR node automatically: it installs restic, rclone, and an append-only rest-server, authorises the main server, and registers itself so it appears in your panel.

bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-dr.sh) \
  --manager https://backup.example.com --token BB-DR-XXXXXXXXXXXXCopy

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-dr.sh) \
  --manager https://backup.example.com --token BB-DR-XXXXXXXXXXXXCopy

lanOption B — Add an existing server by SSH

If you already have a server you want to use (and prefer to install the tools yourself, or just point at an existing box), add it by SSH details instead. The main server reaches out to it.

mkdir -p /root/.ssh && echo 'ssh-ed25519 AAAA…' >> /root/.ssh/authorized_keys && chmod 600 /root/.ssh/authorized_keysCopy

syncAssign replication

Choose which client repositories replicate to the DR server, and how often.

restoreRestore / failover from the DR

If you need data back from the off-site copy — for example a file that was deleted and later pruned from the main server — restore directly from the DR.

dnsRebuild a failed server onto a fresh machine

When a source server is lost entirely, build a replacement, install the OS, then restore its data onto it directly. This works from either the primary backup (main server's Snapshots → Restore) or the off-site DR copy (DR → Manage replication → Restore) — both offer the same New / other server destination.

mkdir -p /root/.ssh && echo 'ssh-ed25519 AAAA…' >> /root/.ssh/authorized_keys && chmod 600 /root/.ssh/authorized_keysCopy

emergency_homeRecovering when the whole site / main server is down

The flows above assume the backup server is reachable to drive the restore. But what if the entire data centre holding the source servers and the backup server goes down? For that, each DR node carries everything needed to recover on its own:

• Recovery bundle — alongside the backup data, the manager replicates the repository decryption passwords and config (users, agents, settings) to the DR node, into /etc/backupbloc-recovery/. Without these the off-site copy would be unreadable ciphertext; with them the DR node can decrypt and restore by itself. This syncs automatically after each replication.
• Standby recovery panel — the DR installer also puts a read/restore-only copy of the BackupBloc panel on the DR node. It does not replicate or accept backups, and it keeps working even when the primary and the licence server are unreachable.

Use the standby panel

export RESTIC_PASSWORD="$(cat /etc/backupbloc-recovery/<repo>.password)"
restic -r /var/lib/restic-repos/<repo> snapshots
restic -r /var/lib/restic-repos/<repo> restore latest --target /recoveryCopy

groupUser roles

BackupBloc has two built-in roles. Both roles log in to the same admin UI — the interface simply adapts to what each role is allowed to do.

Creating a client user

shieldThe client user panel

When a client-role user logs in, the interface hides all admin-only navigation and takes them directly to the Backup Now page. The page is split into two columns:

The header also gains a green Backup Now button that navigates back to this page from any other section of the UI.

play_circleBackup Now — how it works

Backup Now creates an on-demand snapshot without waiting for the scheduled timer. It is available to both admin users (per-client trigger button on the Clients page) and client users (their dedicated panel).

Backup types

Scoped paths

By default, Backup Now backs up everything configured for that client. You can narrow the scope by typing one or more absolute paths into the What to back up tag-input and pressing Enter after each one:

# Example — back up only the web root and the database export directory
/var/www/mysite
/var/backups/mysql

The paths are passed directly to restic backup. Leave the input empty to use the client's default configured paths.

Technical flow

1. The UI posts POST /api/backup/trigger with { client, full, paths }.
2. The server queues the request in /etc/restic-manager/triggers.json.
3. The agent's restore-poller daemon (running every 30–60 seconds via systemd timer) polls GET /api/backup/trigger/pending, finds the queued job, and ACKs it immediately to prevent duplicate runs.
4. The agent runs restic backup with the specified arguments and streams progress back via POST /api/backup/progress.
5. The UI polls GET /api/backup/status every 4 seconds and updates the status ring in real time.

securitySecurity hardening

The following hardening changes have been applied to the codebase. Each addresses a specific vulnerability class found during an internal security audit.

Shell injection via eval removed

Risk: The agent scripts (restic-backup, restic-mysql-backup, restic-restore-poller) previously used eval to build and run restic commands from environment variables. A malicious value in any variable (e.g. BACKUP_PATHS) could inject arbitrary shell commands that would be executed as root.

Fix: All eval calls replaced with explicit Bash arrays. Variables are word-split via read -ra and expanded as "${ARRAY[@]}", which is safe even if values contain spaces or shell metacharacters.

# Before — vulnerable
eval restic backup $BACKUP_PATHS --tag $CLIENT_ID

# After — safe
RESTIC_CMD=(restic backup)
read -ra _BP <<< "${BACKUP_PATHS:-}"
[[ ${#_BP[@]} -gt 0 ]] && RESTIC_CMD+=("${_BP[@]}")
RESTIC_CMD+=(--tag "${CLIENT_ID}")
"${RESTIC_CMD[@]}"Copy

TLS certificate verification enforced

Risk: All curl calls in the agent scripts used -sk (skip TLS verification). This allowed a network-position attacker to MITM the connection between the agent and the backup server and intercept or modify responses.

Fix: The -k flag has been removed from every curl call. When a custom CA bundle is present at /etc/restic-agent/ca.crt (e.g. for self-signed server certificates) it is passed via --cacert; otherwise the system trust store is used.

CURL_TLS=()
[[ -f /etc/restic-agent/ca.crt ]] && CURL_TLS=(--cacert /etc/restic-agent/ca.crt)

# Every curl call now includes ${CURL_TLS[@]}
curl -s "${CURL_TLS[@]}" --max-time 15 \
  "${API_BASE}/api/health"Copy

Agent update scripts verified before execution

Risk: The restore-poller downloaded update-agent.sh from backupbloc.com and ran it directly with bash. A compromised CDN, DNS hijack, or HTTP downgrade could deliver a malicious script that would run as root on every agent.

Fix: The poller now downloads both the update script and a detached RSA signature (.sig), and verifies it against the public key at /etc/restic-agent/update-pubkey.pem before executing. The public key is installed both by the agent installer and by every update bundle, and the matching private key never leaves the release machine. If the signature is missing or fails to verify, the download is deleted and the update is skipped.

PUBKEY=/etc/restic-agent/update-pubkey.pem
if [[ -f "$PUBKEY" ]] && \
   openssl dgst -sha256 -verify "$PUBKEY" \
     -signature "$_UPDATE_SIG" "$_UPDATE_SCRIPT"; then
  bash "$_UPDATE_SCRIPT"
else
  # Signature missing or invalid — refuse to execute
  rm -f "$_UPDATE_SCRIPT" "$_UPDATE_SIG"
fiCopy

SQL injection in MySQL backup script prevented

Risk: The restic-mysql-backup script interpolated the database name directly into a MySQL query string. A database name containing SQL metacharacters (e.g. a backtick or semicolon) could break out of the query context.

Fix: Database names are validated against a strict allowlist regex (^[a-zA-Z0-9_-]+$) before use. Any name that does not match is logged and skipped.

if [[ ! "$DB_NAME" =~ ^[a-zA-Z0-9_-]+$ ]]; then
  log "WARN  Skipping database with unsafe name: ${DB_NAME}"
  continue
fiCopy

Repository password endpoint authenticated

Risk: The POST /api/repos/<id>/password endpoint — used by the agent installer to register the repository encryption password — accepted any request without verifying that the caller was a known, registered agent. An unauthenticated attacker who could reach the API could overwrite any repository's password.

Fix: The endpoint now requires a valid client_id in the request body, checks it against the registered agents database (/etc/restic-manager/agents.json), and verifies that the target repository's config file actually exists before updating the password.

Login rate limiting

Risk: The POST /api/auth/login endpoint had no brute-force protection. An attacker could make unlimited login attempts.

Fix: flask-limiter (≥ 3.5.0) is now installed in the server virtualenv and applies a limit of 10 login attempts per minute per IP. If the package is unavailable (e.g. during an in-place update) the limit degrades gracefully to a no-op rather than crashing the API.

# /opt/restic-manager/venv/bin/pip install "flask-limiter>=3.5.0"
# Added to server/requirements.txt

Session TTL reduced to 24 hours

Risk: Login session tokens previously lasted 7 days. A stolen token (e.g. from browser storage or a compromised machine) had a long exploitation window.

Fix: _SESSION_TTL reduced from 86400 * 7 to 86400 (24 hours). All existing sessions are unaffected until they next authenticate.

Restore path whitelist

Risk: The POST /api/restore/jobs endpoint accepted any absolute path as the restore target. An authenticated user (or a compromised session) could request a restore to /etc/restic-manager/ or another sensitive path, overwriting system config.

Fix: A RESTORE_ALLOWED_PREFIXES environment variable (comma-separated list of safe root paths) is checked before any restore job is accepted. Paths outside the whitelist are rejected with a 400 error.

# In /etc/restic-manager/config.env:
RESTORE_ALLOWED_PREFIXES=/home,/var/www,/opt/sites,/tmp/restore

If RESTORE_ALLOWED_PREFIXES is not set, restore jobs are accepted without path restriction (preserving backward compatibility with existing deployments). It is strongly recommended to set this variable in production.

Structured audit log

Risk: Previously there was no record of who performed sensitive operations (login, password change, backup trigger, restore request, user creation/deletion).

Fix: An _audit() function now appends a JSON line to /var/log/restic-manager/audit.log for every privileged action. Each entry includes a UTC timestamp, the action name, the actor (username or system), the source IP, and any relevant detail.

# Example audit.log entries
{"ts":"2026-05-09T03:12:44Z","action":"login_ok","actor":"admin","ip":"203.0.113.5","detail":""}
{"ts":"2026-05-09T03:14:01Z","action":"backup_trigger","actor":"admin","ip":"203.0.113.5","detail":"client=web-01 full=false"}
{"ts":"2026-05-09T03:44:17Z","action":"restore_job_queued","actor":"client1","ip":"10.0.0.2","detail":"snap=abc12345 target=/tmp/restore"}
{"ts":"2026-05-09T04:00:05Z","action":"user_deleted","actor":"admin","ip":"203.0.113.5","detail":"target=olduser"}

The log file is append-only (created with mode 0600, owned by root). Rotate it with logrotate or ship it to a centralised SIEM for alerting.

folder_openFile layout reference

Server

Linux agent

macOS agent

DR node

settingsService management

# --- SERVER ---
systemctl restart restic-rest-server  # restic repo server
systemctl restart restic-api          # Flask mgmt API
systemctl restart nginx               # reverse proxy + UI

# --- LINUX AGENT ---
systemctl status  restic-backup.timer
systemctl start   restic-backup.service   # run now
journalctl -u     restic-backup.service -n 50

# --- macOS AGENT ---
sudo launchctl kickstart -k system/com.backupbloc.agent
sudo launchctl list | grep backupbloc

# --- DR NODE ---
systemctl status  restic-rest-server      # append-only repo server
tail -f /var/log/restic-manager/dr/*.log  # replication logs (on the MAIN server)Copy

bug_reportTroubleshooting

Server installer stops at Let's Encrypt

Make sure port 80 is open to the public internet and DNS for the domain resolves to this host. Certbot runs standalone and binds port 80 itself — nothing else can be there.

Server UI loads but login fails

Check journalctl -u restic-api -n 50. The most common causes are: cryptography missing from the venv (rerun the installer or pip install cryptography), or the admin hash in /etc/restic-server/users uses a format rest-server doesn't accept (only bcrypt and APR1-MD5 are supported — the installer picks one automatically).

Agent fails at "fetching REST credentials"

The license bootstrap endpoint returned an error. Either the IP hasn't been authorised (server license), the personal key is wrong / revoked, or the agent can't reach the server on port 443. curl -v https://SERVER/api/health from the agent will tell you which.

Agent registers but no snapshots appear

1. Trigger a run: sudo systemctl start restic-backup.service (Linux) or sudo launchctl kickstart -k system/com.backupbloc.agent (macOS).
2. Check the log: journalctl -u restic-backup.service -n 100 or /var/log/backupbloc/.
3. If restic complains about unable to open config file, the repository wasn't initialised. On the server: RESTIC_PASSWORD=<pass> restic init --repo /var/lib/restic-repos/<name>.

macOS agent skips user directories

Almost always Full Disk Access. Re-check System Settings → Privacy & Security → Full Disk Access — restic and /bin/bash must both be present and toggled on.

Certbot renewal didn't restart the services

The installer drops a deploy-hook at /etc/letsencrypt/renewal-hooks/deploy/restic-perms-restart.sh. Verify it exists and is executable. Run certbot renew --dry-run — it should print "deploy hook" in the output.

DR server stuck on "Awaiting SSH key"

The main server can't SSH into the DR yet. Run the authorise command shown in the panel on the DR host (it appends the main server's key to /root/.ssh/authorized_keys), confirm the SSH port matches what you entered, then click Test connection. From the main server you can sanity-check with ssh -i /etc/restic-manager/trigger_key root@DR_IP echo ok.

DR replication shows "failed"

Open Manage replication → View log for the repo. Common causes: the DR ran out of disk (free space is shown on the server card), rclone/restic not installed on a manually-added DR, or a transient SSH drop (the next scheduled sync retries automatically). The replication is append-only, so a failed run never damages the existing DR copy.

Restore from DR can't read the copy

The main server reads the DR repository over SSH with restic's SFTP backend. Ensure the DR is Online (Test connection) and that the repo password file exists on the main server at /etc/restic-manager/<repo>.password — it's the same password used for the live repository.