Managing Clients

Managing Clients

Clients represent the individual machines you want to back up. Each client runs the BBS agent software, which communicates with the BBS server to execute backup and restore jobs.

Client List Page

The client list page (/clients) provides an overview of all registered backup clients.

Features

• Search bar: Filter clients by name, hostname, IP address, or operating system
• Stat cards: Quick summary of total clients, online count, offline count, and total storage
• Client table: Displays all clients with the following columns:
  • Status: Visual indicator (online/offline/setup/error)
  • Name: Client display name
  • Hostname: System hostname reported by the agent
  • IP Address: Last known IP address
  • OS: Operating system (e.g., Ubuntu 22.04)
  • Agent Version: Currently installed agent version
  • Borg Version: Currently installed BorgBackup version
  • Repositories: Number of repositories configured
  • Total Size: Combined size of all repositories for this client

Status Indicators

• Green (online): Agent has checked in within the last 5 minutes
• Gray (offline): Agent hasn't been seen for more than 5 minutes
• Blue (setup): Client is newly created and agent hasn't connected yet
• Red (error): Agent reported an error or is in a problematic state

Adding a Client

To add a new backup client:

1. Click the Add Client button on the client list page
2. Enter a Name for the client (e.g., "Web Server 01", "Database Server - Production")
3. If you're an administrator, you can assign an Owner (which user account owns this client)
4. Click Create Client

Upon creation, BBS automatically generates:

• A unique API key for agent authentication
• An SSH key pair (Ed25519) for secure borg repository access
• A dedicated Unix user account (bbs-{agent-id}) on the server

The API key is displayed once after creation. You'll need this key to configure the agent on the client machine. See Agent-Setup for installation instructions.

Client Detail Page

Click on any client in the list to access the detailed client view. The detail page is organized into tabs:

Overview Tab

Displays system information and current status:

• System Information:

  • Hostname
  • Operating system and version
  • Last heartbeat timestamp
  • Current IP address
  • Uptime

• Software Versions:

  • BBS agent version (with "Update Available" indicator if outdated)
  • BorgBackup version
  • Python version

• Statistics:

  • Total repositories
  • Total backup size
  • Total archives
  • Last successful backup

Plugins Tab

Configure and enable plugins for this specific client. Plugins extend BBS functionality with features like:

• MySQL Database Backup: Automatically dump MySQL databases before backup
• PostgreSQL Database Backup: Automatically dump PostgreSQL databases before backup
• Shell Hooks: Run custom scripts before/after backup
• S3 Sync: Automatically sync backups to Amazon S3 or compatible storage
• Email Notifications: Send email alerts on backup success/failure
• Health Checks: Ping external monitoring services (e.g., healthchecks.io)

For each plugin:

• Enable/Disable toggle
• Configure button to set plugin-specific settings
• Link to saved configurations (plugin configs can be reused across multiple clients)

Repositories Tab

Lists all BorgBackup repositories configured for this client. See Repositories for detailed information about creating and managing repositories.

Features:

• Create New Repository button
• Repository list showing:
  • Repository name
  • Encryption mode
  • Size
  • Archive count
  • Last backup timestamp
• Actions: View, Edit, Delete

Schedules Tab

Manages backup plans and schedules. See Backup-Plans for detailed information about creating and configuring backup plans.

Features:

• Create New Plan button
• List of configured backup plans showing:
  • Plan name
  • Repository
  • Schedule frequency
  • Last run time
  • Next run time
  • Status (enabled/disabled)
• Actions for each plan:
  • Run Now: Trigger an immediate backup
  • Edit: Modify plan settings
  • Toggle: Enable/disable the schedule
  • Delete: Remove the plan

Restore Tab

Browse backup archives and restore files. See Restoring-Files for detailed information about the restore process.

Features:

• List of all recovery points (archives)
• File browser for exploring archive contents
• File search across all archives
• Restore options (original location, alternate directory, or download)

Editing Clients

To edit a client:

1. Navigate to the client detail page
2. Click the Edit button
3. Modify the client name or owner
4. Click Save Changes

Deleting Clients

To delete a client:

1. Navigate to the client detail page
2. Click the Delete button
3. Confirm the deletion

Warning: Deleting a client will delete all data associated with that client. Make sure you want to do that.

Updating Agent or Borg Version

BBS can remotely update the agent or BorgBackup software on client machines:

1. Navigate to the client detail page (Overview tab)
2. If an update is available, you'll see an Update Available badge
3. Click Update Agent or Update Borg
4. Confirm the update

The update is queued as a task, and the agent will download and install the new version on its next poll cycle. The agent will automatically restart after updating itself.

---

Next: Agent-Setup | Repositories | Backup-Plans