DOCSEARCHbyAlgolia
Submit Docs

Borg Backup Server (BBS)

repository·main·Indexed 42 days ago

https://github.com/marcpope/borgbackupserver

A self-hosted web application for centrally managing BorgBackup across Linux, Mac, and Windows endpoints. It utilizes a split-plane architecture with a Python agent polling via HTTPS and data transfers via SSH, enabling operation behind firewalls and NAT. Features include an append-only security model, a companion iOS app (BBS Manager), and a suite of CLI tools for installation, 2FA reset, database migration, and repository escrow.

Tokens
12.3K
Snippets
37
Records
54
Agent score
55%

What's inside Borg Backup Server

  1. Understand the Borg Backup Server Architecture

    main

    Borg Backup Server uses a split-plane architecture to manage backups across multiple endpoints (Linux, Mac, and Windows) without requiring inbound connections to the agents, making it compatible with firewalls and NAT.

    Core Components

    • Control Plane (HTTPS): The lightweight agent polls the server over HTTPS to check for new tasks, report progress, and provide status updates.
    • Data Plane (SSH): Actual backup and restore data is transferred via SSH using borg serve.
    • Security Model: The system implements an append-only security model. Agents are permitted to perform backups or restores but are restricted from deleting or pruning archives. Pruning operations are executed server-side.
    • Agent Requirements: The agent is a Python 3-based tool (using only the standard library) that runs on the endpoint.

  2. Quick Start with Borg Backup Server

    main

    Borg Backup Server (BBS) can be installed using one of two primary methods depending on your environment. Detailed step-by-step guides for both are available on the project Wiki.

    Installation Options

    • Bare Metal / VM: Recommended for fresh Ubuntu servers (supports 22.04, 24.04, and 26.04 LTS). The process uses a single installer command and includes a browser-based setup wizard to configure the database, admin account, and storage.
    • Docker: Uses pre-built images available on Docker Hub. This is ideal for rapid deployment (approx. 30 seconds) and involves configuring docker-compose, storage volumes, and a reverse proxy.
    • Unraid: A Community Applications template is provided. You can add it via Docker → Add Container → Template. It maps the necessary web/SSH ports and the /var/bbs data path, defaulting APP_URL and SSH_PORT to the host values.

    Refer to the official Wiki for the specific commands and configuration steps for your chosen path.

  3. BBS Manager Mobile App Integration

    main

    BBS Manager is a native companion app available on the Apple App Store for managing your Borg Backup Server from an iOS device. It provides native push notifications for failed backups and server status.

    To connect the mobile app to your server, navigate to Settings → Push Service within the BBS web interface.

  4. Understand the contents of a BBS backup archive

    main

    A successful backup creates a timestamped tar.gz archive containing the following components necessary for a full system restore:

    • dump.sql: A full MySQL dump (automatically excludes catalog tables to prevent lock contention).
    • env: The config/.env file containing APP_KEY, database credentials, and other environment variables.
    • version: The BBS version string at the time of backup.
    • ssh-host-keys/: System SSH host keys (prevents "host key changed" errors for connected agents).
    • cron: The scheduler cron job definition (/etc/cron.d/bbs-scheduler).
    • sudoers/: Sudoers files providing www-data privileges (/etc/sudoers.d/bbs-ssh-helper).

  5. Agent API Authentication and Session Behavior

    main

    The application distinguishes between browser-based requests and Agent API requests to optimize performance and storage:

    • Agent API Routes: Any request starting with /api/agent/ is treated as an agent request. These routes do not start a PHP session. Instead, agents are expected to authenticate using a Bearer token. This prevents the creation of thousands of orphan session files caused by frequent agent polling.
    • Browser/UI Routes: Standard UI routes and other API routes (like /api/templates/{id}) use standard PHP sessions for authentication via requireAuth().

  6. Install the bbs-ssh-helper CLI

    main

    To install the bbs-ssh-helper tool, copy the binary to /usr/local/bin, set executable permissions, and configure sudo to allow the www-data user to run it without a password. This is required for the web server to manage Unix users and Borg operations.

    cp bin/bbs-ssh-helper /usr/local/bin/bbs-ssh-helper
chmod 755 /usr/local/bin/bbs-ssh-helper
echo "www-data ALL=(root) NOPASSWD: /usr/local/bin/bbs-ssh-helper, /var/www/bbs/bin/bbs-update" > /etc/sudoers.d/bbs-ssh-helper

  7. Configure bbs-ssh-gate in authorized_keys

    main

    The bbs-ssh-gate script acts as an SSH command dispatcher for BBS agent connections. It must be installed as a forced command in the authorized_keys file for all bbs-* users to ensure they can only execute specific allowed operations.

    When configuring authorized_keys, you must provide the user's home directory as the first argument to the script. Use the restrict option to limit the SSH session capabilities.

    command="/usr/local/bin/bbs-ssh-gate /var/bbs/home/3",restrict ssh-ed25519 AAAA...

  8. Restore a BBS database dump

    main

    To restore a backup created by bbs-dump onto a fresh installation, follow these steps:

    1. Run the BBS installer: bin/bbs-install.
    2. Copy the .tar.gz archive to the new server.
    3. Execute the migration restore command:
    sudo bash /var/www/bbs/bin/bbs-migrate-restore [path_to_archive]

  9. Run the BBS Self-Backup CLI tool

    main

    The bbs-backup script performs a comprehensive disaster recovery backup of the Borg Backup Server. It must be run with sudo (root privileges) because it accesses sensitive system files like SSH host keys, sudoers configurations, and database credentials.

    By default, the tool creates a timestamped .tar.gz archive in /var/bbs/backups and retains the 7 most recent backups, automatically deleting older ones.

    sudo /var/www/bbs/bin/bbs-backup [backup_dir]

  10. Install Borg Backup Server via the BBS Install Script

    main

    The bbs-install script is a CLI-based installation wizard designed for fresh Ubuntu 22.04+ servers. It automates the installation of system packages (Apache, PHP, MySQL, BorgBackup, ClickHouse, etc.), configures the web server, sets up SSL via Let's Encrypt, and prepares the database and system directories.

    Requirements:

    • Operating System: Ubuntu 22.04 or newer.
    • Permissions: Must be run with sudo.
    • Network: Port 80 must be free (or served by Apache) for SSL issuance.
    • DNS: The provided hostname must resolve to the server's IP if using SSL.

    After the script completes, you must visit the provided URL in a browser to complete the setup wizard (Admin account, Storage, etc.).

    sudo bash bbs-install [--hostname backups.example.com] [--no-ssl] [--email you@example.com]

  11. Automated tasks performed by bbs-update-run

    main

    When executed, bbs-update-run performs the following sequence of operations:

    1. PHP Dependencies: Runs composer install with --no-dev and --no-interaction. It specifically disables PCRE JIT (php -d pcre.jit=0) to prevent fatal errors in environments with restricted executable memory.
    2. File Ownership: Sets www-data:www-data ownership on the BBS directory and configures specific permissions for the config directory and .env file.
    3. SSH Helper: Installs/updates the bbs-ssh-helper to /usr/local/bin/ and runs install-gate and update-all-keys.
    4. PHP Configuration: Creates/updates a bbs.ini file in the PHP configuration directory to set max_execution_time = 300.
    5. ClickHouse Setup: Ensures the ClickHouse server is running, applies configuration overrides from the BBS directory, drops specific system log tables to maintain schema cleanliness, and runs the ClickHouse schema migrations.
    6. Permissions & SSH: Sets up Borg cache directories for www-data and individual bbs-* users. It ensures bbs-* users are in the www-data group and configures strict SSH directory permissions (e.g., 700 for .ssh, 600 for authorized_keys).
    7. Sudoers Configuration: Manages /etc/sudoers.d/bbs-ssh-helper to allow www-data to run the SSH helper and bbs-update without a password, and removes legacy bbs-borg sudoers files.
    8. Database Migrations: Executes migrate.php as the www-data user.
    9. Storage & Scheduler: Configures storage path permissions based on database settings and installs a flock-guarded cron job for scheduler.php in the www-data crontab.
    10. System Hardening & Services: Applies a systemd override for Apache to ensure visibility of /etc/sudoers and write access to /usr/local/bin on hardened systems (like Ubuntu 26.04+). Finally, it restarts PHP-FPM to clear OPcache.

  12. Use the bbs-export-repos CLI to export repository data

    main

    The bbs-export-repos tool exports a list of all repositories from a Borg Backup Server (BBS), including their passphrases and encryption modes. This is intended for escrow purposes: if the server is lost, the repositories on your storage are only recoverable with these passphrases.

    Security Note: When using the --output flag, the tool creates the file with 0600 permissions (read/write only by the owner) to ensure passphrases are not world-readable.

    Requirements:

    • Python 3
    • An API token with the "Display Secrets" capability (configured via Settings -> API -> New Token in the BBS web interface).
    # Basic export to stdout
./bbs-export-repos --url https://backup.example.com --token bbs_xxx

# Export to a JSON file
./bbs-export-repos --url https://backup.example.com --token bbs_xxx --format json -o repos.json

# Export an inventory (excluding passphrases) using environment variables
BBS_URL=https://backup.example.com BBS_TOKEN=bbs_xxx ./bbs-export-repos --no-secrets