Skip to content

Updating BBS

Jump to bottom
Marc Pope edited this page Aug 7, 2026 · 2 revisions

Updating BBS

BBS provides automated update mechanisms for the server software, agents, and Borg binaries. Updates can be performed via the web interface or command line.

Update Types

BBS manages three types of updates:

  1. Server Updates: BBS web application and backend code
  2. Agent Updates: bbs-agent.py script on client machines
  3. Borg Updates: Borg binary versions on client machines

Server Updates

Checking for Updates

BBS automatically checks for updates daily, or you can manually check:

  1. Navigate to Settings → Updates tab
  2. Click Check for Updates button
  3. BBS queries the GitHub Releases API for the latest version
  4. Comparison shows:
    • Current Version: Installed version (from VERSION file)
    • Available Version: Latest release on GitHub
    • Status: Up to date or Update Available

Settings → Updates tab showing version comparison

Update Check Details:

  • Queries: https://api.github.com/repos/marcpope/borgbackupserver/releases/latest
  • Compares semantic versions (e.g., 0.9.3-beta vs. 0.9.4-beta)
  • Shows release notes link for available update

Updating via Web Interface

If an update is available:

  1. Click Upgrade to vX.Y.Z button
  2. Confirm the upgrade
  3. BBS executes /var/www/bbs/bin/bbs-update in the background
  4. Update progress is shown
  5. Page automatically refreshes when complete

What Happens During Update:

  1. Git fetch from remote repository
  2. Checkout latest release tag
  3. Run composer install (update PHP dependencies)
  4. Execute database migrations from migrations/ directory
  5. Fix file permissions and ownership
  6. Restart PHP-FPM service
  7. Clear caches

Downtime:

  • Typically 10-30 seconds
  • Agents continue polling (jobs in progress continue)
  • Users may see brief connection interruption

Updating via Command Line

SSH to the BBS server and run:

sudo /var/www/bbs/bin/bbs-update

What It Does:

  • Fetches latest code from GitHub
  • Checks out the latest release tag (e.g., v0.9.4-beta)
  • Runs migrations
  • Updates dependencies
  • Restarts services

Output:

BBS Update Script
=================
Checking for updates...
Current version: 0.9.3-beta
Latest version: 0.9.4-beta
Update available!

Fetching updates from GitHub...
Checking out v0.9.4-beta...
Installing dependencies...
Running migrations...
Migration 2024-01-15_add_2fa.sql applied.
Fixing permissions...
Restarting PHP-FPM...
Update complete!

Current version: 0.9.4-beta

Update to Specific Version

To update to a specific release tag:

sudo /var/www/bbs/bin/bbs-update /var/www/bbs v0.9.3-beta

Usage: bbs-update [path] [tag]

Parameters:

  • path: BBS installation directory (default: /var/www/bbs/)
  • tag: Git tag to checkout (omit for latest release)

Update to Development Branch (Beta Server)

To pull the latest code from the main branch (for testing):

sudo /var/www/bbs/bin/bbs-update /var/www/bbs main

Use Case: Beta/staging server running latest development code

Warning: Only use main branch on test servers, not production

Agent Updates

Agent Version Management

BBS tracks agent versions to ensure compatibility:

  • Server Agent Version: Defined in agent/bbs-agent.py (AGENT_VERSION constant)
  • Client Agent Versions: Reported by each agent on heartbeat
  • Version mismatch warnings appear if agents are outdated

Viewing Agent Version Status

Navigate to Settings → Updates tab:

Agent Version Distribution Table:

Version Count Status
1.7.3 45 Current
1.7.2 5 Outdated
1.7.1 2 Outdated

Out of Date Counter: Shows number of agents not running current version

Updating a Single Agent

  1. Navigate to client detail page
  2. Click Update Agent button (top-right)
  3. Confirm the update
  4. BBS queues an update_agent job
  5. Monitor progress in Queue → Job detail

Update Process:

  1. Agent receives update_agent job
  2. Agent downloads latest bbs-agent.py from server: GET /api/agent/download
  3. Validates downloaded script (checksum, syntax check)
  4. Backs up current script: bbs-agent.py.bak
  5. Replaces script with new version
  6. Restarts agent service: systemctl restart bbs-agent
  7. Reports success to server

Job Duration: 1-2 minutes

Bulk Update All Agents

To update all agents at once:

  1. Navigate to Settings → Updates tab
  2. Click Update All Agents button
  3. Confirm bulk update
  4. BBS queues update_agent jobs for all online agents
  5. Monitor progress in Queue

Considerations:

  • Only online agents are updated (offline agents update on next connection)
  • Updates run in parallel (up to max concurrent jobs limit)
  • Failed updates can be retried individually

Best Practice: Test agent update on 1-2 non-critical clients before bulk updating

Borg Binary Updates

Borg Version Management

BBS manages Borg binary versions across all agents:

  • Available Versions: List of Borg releases synced from GitHub
  • Target Version: The version BBS will install on new agents
  • Client Versions: Current Borg version on each agent

Syncing Available Borg Versions

BBS can fetch the latest Borg releases from GitHub:

  1. Navigate to Settings → Borg Versions tab
  2. Click Sync Borg Versions button
  3. BBS queries borgbackup/borg GitHub Releases API
  4. New versions are added to the available versions list

Frequency: Manual (run when you want to make a new Borg version available)

Available Versions Table:

Version Release Date Agents Using Actions
1.4.0 2024-01-10 0 Set as Target
1.2.7 2023-12-05 30 Set as Target
1.2.6 2023-11-15 20 Set as Target

Setting Target Borg Version

Choose which Borg version agents should use:

  1. Find desired version in the table
  2. Click Set as Target
  3. Target version is highlighted (green badge)
  4. New agents will install this version automatically
  5. Existing agents can be updated to this version

Recommendation: Use the latest stable Borg version unless there's a compatibility issue

Updating Borg on a Single Agent

  1. Navigate to client detail page
  2. Click Update Borg button
  3. Confirm update
  4. BBS queues an update_borg job
  5. Monitor progress in Queue

Update Process:

  1. Agent receives update_borg job with target version
  2. Agent attempts Method 1: Binary Download
    • Downloads pre-compiled Borg binary from GitHub releases
    • Validates checksum
    • Installs to /usr/local/bin/borg
    • Verifies: borg --version
  3. If binary download fails, Method 2: Pip Install
    • Runs: pip3 install borgbackup=={target_version}
    • Verifies installation
  4. Reports success to server

Job Duration: 2-5 minutes (binary download is faster than pip)

Bulk Update Borg on All Agents

  1. Navigate to Settings → Borg Versions tab
  2. Set target version (if not already set)
  3. Click Update Borg on All Agents
  4. Confirm bulk update
  5. BBS queues update_borg jobs for all agents
  6. Monitor progress in Queue

Important:

  • All agents will be updated to the target version
  • Backup jobs will pause during Borg update
  • Failed updates can be retried

Borg Installation Methods

Method 1: Binary Download (Preferred)

How It Works:

  • Downloads pre-compiled Borg binary from GitHub releases
  • URL: https://github.com/borgbackup/borg/releases/download/{version}/borg-linux64
  • Fast, no compilation required
  • Works on most Linux distributions (glibc-based)

Advantages:

  • Fast installation (download only)
  • No dependencies required (Python, pip, compilers)
  • Consistent across distributions

Limitations:

  • Linux x64 only (no ARM, 32-bit)
  • Requires glibc (doesn't work on musl-based systems like Alpine)

Method 2: Pip Install (Fallback)

How It Works:

  • Installs via Python pip: pip3 install borgbackup=={version}
  • Compiles Borg from source if no wheel available
  • Requires Python 3.6+ and pip

Advantages:

  • Works on any architecture (ARM, x64, x86)
  • Works on any Python-compatible OS

Limitations:

  • Slower (may compile from source)
  • Requires pip and development tools
  • May fail if Python/pip not installed

Agent Fallback Logic:

  1. Try binary download
  2. If fails (checksum mismatch, architecture incompatible), fall back to pip
  3. If pip fails, report error

Database Migrations

What Are Migrations?

Migrations are SQL scripts that update the database schema when BBS is updated.

Location: /var/www/bbs/migrations/

Format: YYYY-MM-DD_description.sql

Example:

migrations/
├── 2024-01-10_add_plugins_table.sql
├── 2024-01-15_add_2fa_columns.sql
└── 2024-01-20_add_s3_sync_config.sql

How Migrations Work

When bbs-update runs:

  1. Checks migrations_applied table for already-applied migrations
  2. Scans migrations/ directory for new .sql files
  3. Applies new migrations in alphabetical order
  4. Records each migration in migrations_applied table
  5. Reports success or failure

Migration Table:

CREATE TABLE migrations_applied (
    id INT AUTO_INCREMENT PRIMARY KEY,
    migration_name VARCHAR(255) NOT NULL,
    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Running Migrations Manually

If migrations fail during update:

sudo /var/www/bbs/bin/bbs-update /var/www/bbs main

This re-runs the update process, including migrations.

Checking Migration Status:

sudo mysql -e "SELECT * FROM bbs.migrations_applied ORDER BY applied_at DESC LIMIT 10;"

Manually Applying a Migration:

sudo mysql bbs < /var/www/bbs/migrations/2024-01-15_add_2fa_columns.sql
sudo mysql -e "INSERT INTO bbs.migrations_applied (migration_name) VALUES ('2024-01-15_add_2fa_columns.sql');"

Rollback and Downgrade

Rolling Back a Server Update

If an update causes issues, roll back to a previous version:

  1. Find Previous Version Tag:

    cd /var/www/bbs
git tag | tail -10

  2. Checkout Previous Version:

    sudo /var/www/bbs/bin/bbs-update /var/www/bbs v0.9.3-beta

  3. Restore Database (if migrations were applied):

    sudo /var/www/bbs/bin/bbs-restore /var/bbs/backups/bbs-backup-YYYY-MM-DD_HHMMSS.tar.gz

Important:

  • Only roll back if absolutely necessary (data loss risk)
  • Restore from backup created before the update
  • Database migrations are NOT automatically reversed

Downgrading Agents

To downgrade an agent to a previous version:

  1. Edit agent/bbs-agent.py on the server (change AGENT_VERSION to older version)
  2. Copy an older version of the agent script to /var/www/bbs/agent/bbs-agent.py
  3. Run Update Agent on affected clients

Note: Downgrades are rarely needed and may cause compatibility issues.

Downgrading Borg

To install an older Borg version:

  1. Navigate to Settings → Borg Versions
  2. Set an older version as target
  3. Click Update Borg on affected clients

Warning: Borg repositories may not be backward-compatible (newer Borg versions may create features that older versions cannot read).

Best Practices

Before Updating

  • Backup First: Ensure daily bbs-backup has run recently
  • Check Release Notes: Review GitHub release notes for breaking changes
  • Test in Staging: Update beta server first, verify functionality
  • Schedule Maintenance Window: Update during low-traffic periods
  • Notify Users: Inform users of brief downtime

During Updates

  • Monitor Logs: Watch /var/log/apache2/error.log for errors
  • Verify Migrations: Ensure all migrations apply successfully
  • Test Functionality: After update, create a test backup job
  • Check Agent Connectivity: Verify agents still connect after update

After Updates

  • Verify Version: Confirm current version matches expected version
  • Test Key Features: Create backup, restore, check queue
  • Monitor Notifications: Watch for error notifications
  • Review Logs: Check for unexpected warnings or errors

Agent Updates

  • Stagger Updates: Don't update all agents at once
  • Test First: Update 1-2 non-critical agents, verify success
  • Bulk Update: Once tested, bulk update remaining agents
  • Monitor Queue: Watch for failed update_agent jobs

Borg Updates

  • Read Borg Changelog: Check Borg release notes for compatibility issues
  • Test Backup: After updating Borg, run a test backup on an agent
  • Verify Restore: Test restore functionality with new Borg version
  • Avoid Major Version Jumps: Update incrementally (1.2.x → 1.3.x → 1.4.x)

Troubleshooting

Update Check Fails

Error: "Unable to check for updates"

Possible Causes:

  • No internet connection from BBS server
  • GitHub API rate limit exceeded
  • Firewall blocking outbound HTTPS

Solutions:

  • Verify internet connectivity: curl https://api.github.com
  • Check firewall rules (allow outbound port 443)
  • Wait 1 hour if rate limited (GitHub allows 60 requests/hour for unauthenticated)

Server Update Fails

Error: "Migration failed: Table already exists"

Cause: Migration already partially applied

Solution:

  • Manually mark migration as applied: 
    sudo mysql -e "INSERT INTO bbs.migrations_applied (migration_name) VALUES ('2024-01-15_add_2fa_columns.sql');"
  • Re-run update: sudo /var/www/bbs/bin/bbs-update

Error: "Composer install failed"

Cause: Missing PHP extensions or composer not installed

Solution:

  • Reinstall composer: sudo apt install composer
  • Verify PHP extensions: php -m | grep -E 'pdo|mysql|mbstring|curl'
  • Manually run: cd /var/www/bbs && sudo composer install

Agent Update Fails

Error: "Download failed: Connection timeout"

Cause: Agent cannot reach BBS server

Solution:

  • Verify agent can reach server: curl https://bbs.example.com/api/agent/download
  • Check firewall on agent and server
  • Retry update job

Error: "Service restart failed"

Cause: Agent service not configured or systemd issue

Solution:

  • SSH to client
  • Check service status: systemctl status bbs-agent
  • Manually restart: sudo systemctl restart bbs-agent
  • Verify service is enabled: sudo systemctl enable bbs-agent

Borg Update Fails

Error: "Binary download failed: Checksum mismatch"

Cause: Corrupted download or MITM attack

Solution:

  • Retry update (may be transient network issue)
  • Agent will automatically fall back to pip install
  • Verify network is secure (not intercepting HTTPS)

Error: "Pip install failed: No module named pip"

Cause: pip not installed on client

Solution:

  • SSH to client
  • Install pip: sudo apt install python3-pip
  • Retry Borg update job

Version Mismatch After Update

Issue: Settings → Updates shows old version after update

Cause: Browser cache showing old data

Solution:

  • Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
  • Check VERSION file directly: cat /var/www/bbs/VERSION

Related Documentation

📖 User Manual

Getting Started

Using BBS

Monitoring

Administration

Reference

Clone this wiki locally