Learn Borg Backup - Ecosystem: BorgWeb & Tools

#Introduction

Borg is a great CLI — but the operational world rarely stops at the CLI. Teams need a GUI for non-technical operators, integration with existing monitoring, and metrics for dashboards. Episode 19 maps the ecosystem around Borg: from the user-friendly BorgWeb and borgmatic as the configuration layer, to bridges into Nagios/Zabbix and Prometheus.

#BorgWeb: A GUI for Repositories

#What Is BorgWeb

BorgWeb is a web interface (Python-based) for managing Borg repositories. It gives operators a visual view: seeing the archive list, browsing contents, and performing restores without typing commands.

pip install borgweb

BorgWeb runs as an HTTP service and is configured to access specific repositories (e.g. a local repo on the same host, or a remote repo exposed via a mount). Its use case is real: a helpdesk that needs to restore a single file without shell access.

#When to Use It, When Not

• Fits: daily operations, self-service restores for non-DevOps teams, and quick inspections.
• Does not fit: as a replacement for automation. BorgWeb does not run backup schedules; it manages and restores. Automation remains borgmatic's job.

#borgmatic: The Configuration Layer

The borgmatic we built in episode 9 is the most important part of the ecosystem: it turns backup policy into a version-controllable YAML file and executes create → prune → compact → check in the right order. There is no reason to run manual backups when borgmatic can make them declarative.

#borg mount: FUSE Access

borg mount (episode 5) is the bridge between Borg and other tools. A mounted archive looks like a regular directory — browsable over NFS, backed up by other tools, or scanned by AV. A pattern often used in production: mount the newest archive, then verify its contents with standard tools before a full restore.

#Classic Monitoring Integration: Nagios/Zabbix

#The Wrapper Pattern

Nagios and Zabbix do not speak Borg — they need plugins that print an exit code and text. The standard pattern: a wrapper script runs the Borg operation, then prints output in the plugin format.

#!/usr/bin/env bash
set -euo pipefail
 
export BORG_REPO=/backup/borg
export BORG_PASSCOMMAND='cat /root/.borg-passphrase'
 
if borg list --last 1 > /dev/null 2>&1; then
    echo "OK - borg backup running normally"
    exit 0
else
    echo "CRITICAL - borg repository has a problem"
    exit 2
fi

Put it at /usr/lib/nagios/plugins/check_borg and register it as a command. Zabbix uses a similar pattern: user parameters or external scripts returning values (archive count, repo size, last archive time).

#Metrics Worth Monitoring

• Time of the last archive (staleness) — a late backup is the most common alarm.
• Repository size and disk space.
• The result of the last borg check.
• The exit code of the last backup (from the borgmatic log).

#Prometheus: The Textfile Collector

Prometheus' node_exporter has a textfile collector feature: text files in a specific directory are read and published as metrics. This is the cheapest way to export borgmatic status to Prometheus.

#!/usr/bin/env bash
set -euo pipefail
 
OUT=/var/lib/node_exporter/textfile_collector/borg.prom
TMP="$OUT.$$"
 
if borgmatic --verbosity 0 --stats 2>/dev/null; then
    STATUS=1
else
    STATUS=0
fi
 
cat > "$TMP" <<EOF
# HELP borg_backup_success Whether the last borgmatic backup succeeded
# TYPE borg_backup_success gauge
borg_backup_success $STATUS
EOF
 
mv "$TMP" "$OUT"

Once the exporter runs, the borg_backup_success metric appears on the node_exporter endpoint and can be pulled by Grafana/Alertmanager.

#Common Pitfalls

• BorgWeb hosted on a production server without authentication: a backup GUI = full control over data. Protect it with a reverse proxy + auth (BasicAuth/OIDC).
• Wrappers without exit codes: monitoring plugins need correct exit codes (0/1/2). Ignoring them kills alerting.
• Metrics without staleness: borg_backup_success only means something when evaluated with time() - last_success. A host that is completely dead "succeeds" without a fresh metric.
• Piling up tools without direction: borgmatic for automation, BorgWeb for operations, Prometheus for observability — one job each. Do not mix them.

#Closing

• BorgWeb gives a GUI to manage and restore repositories.
• borgmatic remains the center of automation; BorgWeb is not a schedule replacement.
• borg mount (FUSE) bridges Borg with other tools.
• Nagios/Zabbix are integrated via wrappers with correct exit codes.
• The Prometheus textfile collector exports backup status as metrics.
• Protect the GUI with authentication, and always export staleness metrics.

In episode 20 we build awareness: monitoring & alerting — monitoring borgmatic metrics, triggering alerts when a backup fails or is late, and sending notifications via Email/Slack/Telegram through borgmatic hooks and services like Healthchecks.