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.

rocket_launchClient quick start — back up your server

Everything you need to protect your first server. Your provider has already created your account and set your storage allowance — you handle the rest yourself, in about five minutes.

Before you start

• The panel URL, username and password your provider sent you.
• root / sudo access to the server (or laptop/PC) you want to back up.
• The network ports below open so your server can reach the backup server.

Ports to open

All the connections your server needs are outbound — from your server to the backup server. If you run a strict egress firewall (CSF, iptables, a cloud security group, etc.), allow the following. Most setups permit outbound traffic by default, in which case there's nothing to change.

1 · Log in and find your dashboard

2 · Add a server (get your install key)

3 · Install the agent on your server

SSH into your server as root (or use sudo) and run the one-line installer. It installs everything it needs — you don't need to install restic or anything else first.

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-agent.sh | tr -d '\r')Copy

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-agent-mac.sh | tr -d '\r')Copy

The installer asks a few questions. The important ones:

4 · Verify your first backup — and restoring

When the installer finishes it registers your server and kicks off the first backup automatically. Your server appears on your dashboard within a minute or two, and the first snapshot shows up under Snapshots. Your Account Storage will start to climb as data is stored.

To restore a file later: open Snapshots, pick the snapshot from the right date, browse into it, and download the file or folder you need. To back up on demand before making a risky change, use the Backup Now button.

Understanding your storage & server limits

Your plan has two limits, both shown on your dashboard:

• Storage allowance — the total backup space across all your servers. As you approach it you'll get warnings; at 100% new backups pause until you free space (delete old snapshots) or your provider raises it.
• Server limit — how many servers you can enrol. When you're at the limit, remove an unused key or ask your provider to raise it.

Need more storage or servers? Contact your provider — they can raise either limit on your account.

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. Authorisation happens under Licenses in the admin UI, in two styles:

• Client Access Key — for any machine without a static IP (laptops, home PCs, VPSs, or servers behind NAT). Generate a BB-XXXXXXXX-XXXXXXXX key under Licenses → Client Access Keys and paste it into the installer. Set Bill to account when generating it to auto-assign the machine to a client's account. Client-role users can also self-generate these from their own dashboard's Add a Server button, up to their plan's server limit.
• Server license (IP-bound) — for fixed servers with a static public IP. Pre-authorise the IP under Licenses → Server Licenses (IP) (also with an optional Bill to account). The installer reads the public IP at runtime, the server validates it, and credentials are returned automatically — no key entry.

memoryLinux agent install

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-agent.sh | tr -d '\r')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 | tr -d '\r')Copy

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

desktop_windowsWindows agent install

The Windows agent is a double-click installer (BackupBlocAgentSetup.exe). It installs restic, the BackupBloc agent (PowerShell, no other dependencies), and two Scheduled Tasks — a scheduled backup and a once-a-minute poller that powers Backup Now and restores. It works on Windows 10 / 11 and Windows Server 2016 or newer.

"C:\Program Files\BackupBloc\Validate-BackupBlocLicense.cmd"Copy

# See the scheduled tasks
schtasks /Query /TN "BackupBloc Backup"
schtasks /Query /TN "BackupBloc Poller"
# Logs
type C:\ProgramData\BackupBloc\logs\backup.logCopy

Desktop tray app

The Windows agent includes a system-tray widget (the BackupBloc logo next to the clock; look under the ▲ "show hidden icons" arrow, and drag it out to pin it). It runs as the logged-in user and needs no admin rights for day-to-day use. Double-click it for the status window, or right-click for the menu:

Open files (VSS)

Before each run the agent creates a Volume Shadow Copy so files held open by running apps (databases, Outlook .pst, etc.) are captured consistently. The first snapshot of a session can take a minute while Windows starts the Volume Shadow Copy service — the tray shows "Creating snapshot (VSS)" during that time; it isn't stuck.

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.

databaseDatabase (MySQL) backups

Alongside file backups, each agent can dump and back up its MySQL / MariaDB databases on their own schedule. Database snapshots are stored in the same repository as file backups but tagged separately, so they show up under their own Databases page. You manage this per server — admins for any server, client users for the servers they own.

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-agent.sh | tr -d '\r')Copy

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 | tr -d '\r')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 | tr -d '\r')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).

extensionControl-panel plugins

The cPanel and Webuzo plugins give every hosting account a self-service BackupBloc area inside their own control panel. From there an end user can browse their account's file snapshots, restore individual files or folders, restore their databases, and run an on-demand backup — all scoped to their own account, with no BackupBloc admin login and no SSH.

You install the plugin once on the hosting server (the same box that already runs the BackupBloc agent). It is a thin front end over the manager's existing API.

keyStep 1 · Create an API token

Both plugins authenticate to the manager with a long-lived API token. You generate this yourself — no BackupBloc admin needs to issue it for you.

dnsStep 2a · Install on cPanel / WHM

For a cPanel/WHM server (Jupiter theme) that already runs the BackupBloc Linux agent. CloudLinux + CageFS are supported.

cd /root
curl -fLO https://backupbloc.com/downloads/backupbloc-plugin-cpanel.tar.gz
tar -xzf backupbloc-plugin-cpanel.tar.gz
cd backupbloc-plugin-cpanel
bash install.shCopy

Uninstall: from the extracted folder, run bash uninstall.sh (add --purge to also remove /var/cpanel/backupbloc). Snapshots on the server are never touched.

dnsStep 2b · Install on Webuzo

For a Webuzo server that already runs the BackupBloc agent.

cd /root
curl -fLO https://backupbloc.com/downloads/backupbloc-plugin-webuzo.tar.gz
tar -xzf backupbloc-plugin-webuzo.tar.gz
cd backupbloc-plugin-webuzo
bash install.shCopy

Uninstall: run bash uninstall.sh from the extracted folder.

restoreStep 3 · Browse & restore (for end users)

This is what your hosting customers do inside their own panel. Open BackupBloc (cPanel: the tile under Files; Webuzo: the panel entry). There are three tabs, plus a Return to cPanel link in the header.

Restore a file or folder

1. On File Backups, pick a restore point and click Browse. These are the server's restore points; browsing shows only your account's files.
2. Navigate into folders using the breadcrumb, then click Restore next to any file or folder.
3. Confirm the prompt. The file is restored in place to its original location in your account, and a live progress bar tracks it.

Restore a database

1. Open the Databases tab — it lists only your account's databases (the <user>_ ones).
2. Click Restore on the one you want and confirm. The database is restored from the selected snapshot.

Run a backup now

On the Run Backup tab, click Run Now to back up your account on demand. A new snapshot for your account appears in File Backups once it completes.

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 | tr -d '\r') \
  --manager https://backup.example.com --token BB-DR-XXXXXXXXXXXXCopy

sudo bash <(curl -fsSL https://backupbloc.com/downloads/agent/install-dr.sh | tr -d '\r') \
  --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 to their own Dashboard. Everything they see is scoped to their account — they never see other tenants or the provider's server-wide figures.

Dashboard

• Account Storage — a donut showing space used against their plan quota (or "Unlimited" if none is set).
• Your Servers — servers enrolled versus their limit, an Add a Server button that self-generates a Client Access Key, and a Waiting for install list of keys not yet used (with Copy / Remove).
• Snapshots and Backed Up Data totals, plus read-only status cards for each of their servers.

The Your Servers (Clients) page is read-only for clients: they can view a server's status but not change its schedule, quota, owner, or delete it — those stay with the admin. The Backup Now page (below) is reached from the sidebar or the header button. It 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 Client Access 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.