Linux Agent Setup

Agent Setup

The BBS agent is a Python 3 script that runs on each machine you want to back up. It polls the BBS server for tasks, executes BorgBackup commands, and reports status back to the server.

What the Agent Does

The BBS agent:

• Polls the BBS server at regular intervals (default: every 30 seconds) to check for pending tasks
• Executes backup, restore, prune, and other borg commands when jobs are assigned
• Reports job progress and completion status back to the server
• Manages SSH keys for secure repository access
• Updates itself and BorgBackup when instructed by the server
• Sends system metrics (hostname, OS version, uptime, storage usage) as heartbeats

macOS users: See the dedicated macOS Agent Setup guide for Mac-specific instructions including Full Disk Access configuration.

Windows users: See the Windows Agent Setup guide for the Windows PowerShell installer and Windows Service setup.

Requirements

Before installing the agent, ensure the client machine meets these requirements:

• Python 3.6 or newer (Python 3.8+ recommended)
• Root or sudo access (required for system-wide backups and service installation)
• Network connectivity to the BBS server (HTTPS, typically port 443)
• BorgBackup will be installed automatically by the agent if not already present

Installation

Step 1: Create a Client in BBS

Before installing the agent, you must first create a client entry in the BBS web interface:

1. Log in to your BBS server
2. Navigate to Clients → Add Client
3. Enter a name for the client
4. Click Create Client
5. Copy the Install Script Code displayed after creation (you'll need this in the next step)

Step 2: Download and Install the Agent

On the client machine you want to back up, open a terminal or SSH into the machine, you'll need sudo access.

# Simple 1 Line Install:
curl -s https://backup.mydomain.com/get-agent | sudo bash -s -- --server https://beta.borgbackupserver.com --key YOUR_API_KEY

Replace:

• https://backup.mydomain.com with your BBS server URL
• YOUR_API_KEY with the API key copied from the BBS web interface

The installer will automatically setup the latest Agent software on your system, install borgbackup, cronjobs, etc.

Step 3: Verify Installation

After the first run, the agent will:

1. Create its configuration file at /etc/bbs-agent/config.ini
2. Download the SSH private key for repository access
3. Install itself as a systemd service
4. Start running in the background

Check that the agent is running:

sudo systemctl status bbs-agent

You should see output indicating the service is active and running. In the BBS web interface, the client status should change from "Setup" (blue) to "Online" (green) within a minute.

Configuration File

The agent configuration is stored at /etc/bbs-agent/config.ini:

[server]
url = https://backups.example.com
api_key = abc123...

[agent]
poll_interval = 30
log_level = INFO

Configuration Options

• url: The BBS server URL (must be HTTPS in production)
• api_key: Authentication key for this client (never share this key)
• poll_interval: How often to check for tasks, in seconds (default: 30)
• log_level: Logging verbosity (DEBUG, INFO, WARNING, ERROR)

You can manually edit this file and restart the agent service to apply changes:

sudo systemctl restart bbs-agent

Running as a Service

The agent automatically installs itself as a systemd service on first run. This ensures the agent starts on boot and restarts automatically if it crashes.

Service Management Commands

# Check agent status
sudo systemctl status bbs-agent

# Start the agent
sudo systemctl start bbs-agent

# Stop the agent
sudo systemctl stop bbs-agent

# Restart the agent
sudo systemctl restart bbs-agent

# View agent logs
sudo journalctl -u bbs-agent -f

# View last 100 log lines
sudo journalctl -u bbs-agent -n 100

How Polling Works

The agent operates on a simple polling cycle:

1. Poll: Agent sends a GET request to /api/agent/tasks on the BBS server
2. Receive: Server responds with any pending tasks (backup, restore, update, etc.)
3. Execute: Agent runs the task (e.g., executes borg create)
4. Report: Agent sends progress updates and final status to /api/agent/status
5. Wait: Agent sleeps for the poll interval, then repeats

This architecture means:

• No inbound connections to client machines are required (firewall-friendly)
• The agent controls all borg operations (server never directly accesses client filesystems)
• Job execution begins within seconds of being queued (based on poll interval)

SSH Key Exchange

For secure repository access, BBS uses SSH key authentication:

1. When you create a client in BBS, the server generates an Ed25519 SSH key pair
2. The public key is added to the authorized_keys file for the dedicated Unix user (bbs-{agent-id})
3. The private key is encrypted and stored in the database
4. When the agent first connects, it downloads and saves the private key to /etc/bbs-agent/ssh_key
5. All borg commands use this key for SSH authentication to the repository server

The SSH key is restricted to only execute borg serve commands, preventing unauthorized access to the server.

Troubleshooting Agent Connectivity

If the client shows as "Offline" or "Setup" in the BBS interface:

1. Check Agent Service Status

sudo systemctl status bbs-agent

If the service is not running, check the logs:

sudo journalctl -u bbs-agent -n 50

2. Verify Network Connectivity

Test that the client can reach the BBS server:

curl -I https://your-bbs-server

You should receive an HTTP 200 or 302 response. If not, check:

• Firewall rules (ensure HTTPS/443 is allowed outbound)
• DNS resolution
• Network routing

3. Verify API Key

Check that the API key in /etc/bbs-agent/config.ini matches the key shown in the BBS web interface (Client detail page → Settings).

4. Check Server URL

Ensure the url in /etc/bbs-agent/config.ini is correct and uses https:// (not http://).

5. Check Agent Logs

View detailed agent logs to identify specific errors:

sudo journalctl -u bbs-agent -f

Common errors:

• SSL certificate verification failed: Server is using a self-signed certificate. Either use a valid certificate or configure the agent to skip verification (not recommended)
• 403 Forbidden: Invalid API key
• Connection timeout: Firewall or network issue preventing connectivity
• 404 Not Found: Incorrect server URL

6. Test Manual Agent Run

Stop the service and run the agent manually to see real-time output:

sudo systemctl stop bbs-agent
sudo /usr/local/bin/bbs-agent.py --debug

This runs the agent in debug mode with verbose logging. Press Ctrl+C to stop, then restart the service:

sudo systemctl start bbs-agent

---

Next: Repositories | Backup-Plans