The Settings page provides centralized configuration for all BBS system-wide options. Access Settings via the Settings link in the navigation bar (admin only).

Settings are organized into tabs:

1. General — Core system settings
2. Email Settings — SMTP configuration and email notification toggles
3. Push Notifications — Push alerts via Discord, Slack, Telegram, Pushover, and 100+ services
4. Templates — Reusable backup templates
5. Remote Storage — Remote SSH host configurations (rsync.net, BorgBase, Hetzner, etc.)
6. S3 Backups — S3 sync global configuration
7. Update — BBS and agent version management
8. Borg Version — Borg binary version control

Screenshot: Settings page showing all tabs

Core system configuration options.

Screenshot: General tab showing all settings

Setting: Fully qualified domain name or IP address of the BBS server

Example: bbs.example.com or 192.168.1.100

Usage: Used in agent configuration, email links, and API endpoints

Important: Change this if you move BBS to a different domain or IP

Setting: Toggle for SSL/HTTPS enforcement

Options:

• Enabled: Redirect all HTTP to HTTPS, use secure cookies
• Disabled: Allow HTTP connections (LAN deployments only)

Default: Enabled (if installed with SSL certificate)

Note: Requires valid SSL certificate. Use --no-ssl during installation for LAN-only deployments.

Setting: Base directory for Borg repositories on the BBS server

Default: /var/bbs/repos/

Format: Absolute path ending with /

Important:

• Directory must exist and be writable by web server user (www-data)
• Changing this does NOT move existing repositories (manual migration required)
• Ensure sufficient disk space

Setting: Maximum number of jobs that can run simultaneously

Default: 4

Range: 1-50

Considerations:

• Low values (1-2): Prevents resource exhaustion on small servers
• Medium values (4-8): Balanced for typical deployments
• High values (10+): Large installations with many agents and powerful server

Impact:

• Jobs beyond this limit remain in queued state
• Each agent runs one job at a time (jobs don't stack on the same agent)
• Higher limits increase server load (CPU, RAM, network, disk I/O)

Setting: How often agents poll the server for new jobs (in seconds)

Default: 60 (1 minute)

Range: 30-600 seconds

Considerations:

• Short intervals (30-60s): Jobs start quickly, more responsive
• Long intervals (300-600s): Reduces server load, suitable for scheduled backups
• Too short: increases server load unnecessarily
• Too long: delays job execution

Agent Offline Detection: Agents are marked offline after 3x this interval

Setting: User session expiration time (in hours)

Default: 720 (30 days)

Range: 1-8760 hours (1 hour to 1 year)

Considerations:

• Short timeouts (1-24h): More secure, requires frequent logins
• Long timeouts (720h): Convenient, less secure
• Sessions expire after idle time, not total time

Security: Enable 2FA for long session timeouts

Setting: Percentage of disk usage that triggers storage low notifications

Default: 90%

Range: 50-99%

Example: If set to 90%, a notification is generated when repository storage reaches 90% capacity

Recommendations:

• High-churn environments: Set to 85% to allow more reaction time
• Stable environments: 90% is appropriate
• Adjust based on how quickly your storage fills up

Setting: Require all users to enable 2FA

Options:

• Enabled: Users cannot log in without 2FA enabled
• Disabled: 2FA is optional

Default: Disabled

Behavior:

• When enabled, users without 2FA are redirected to setup page after login
• Users cannot access BBS until 2FA is configured
• Admins can still emergency-reset 2FA via CLI

Recommendation: Enable for production environments with sensitive data

Configure SMTP for email notifications. Emails are sent to all admin users when enabled events occur.

Click Test SMTP to verify your configuration. BBS sends a test email with subject [BBS] Test Email and reports success or failure.

Enable/disable email alerts for each of the 12 event types:

Note: For backup alerts via Discord, Slack, Telegram, Pushover, and other services, use the Push Notifications tab instead.

See Notifications for SMTP configuration examples and troubleshooting.

Send alerts to Discord, Telegram, Slack, Pushover, and 100+ other services using Apprise.

1. Click Add Service
2. Select a Service Type from the dropdown:
   • Pushover — Mobile push notifications
   • Discord — Channel webhooks
   • Slack — Workspace integrations
   • Telegram — Bot messages
   • Email — Direct SMTP delivery via Apprise
   • ntfy — Self-hosted or ntfy.sh
   • Custom — Any Apprise-compatible URL
3. Fill in the guided form fields for your chosen service
4. Select which events should trigger notifications for this service
5. Click Save

Each service has its own set of event subscriptions. Events are grouped into 6 categories (Backups, Restores, Clients, Repositories, Storage, Schedules) with color-coded badges:

• Green — Success events (Backup Completed, Restore Completed, Client Online, Compact Done, S3 Sync Done)
• Red — Failure events (Backup Failed, Restore Failed, Check Failed, S3 Sync Failed)
• Yellow — Warning events (Client Offline, Storage Low, Missed Schedule)

You can create multiple services with different event selections. For example:

• Discord — subscribe to failure events for your team channel
• Pushover — subscribe to everything for personal mobile alerts

Click the Test button next to any service to send a test notification and verify connectivity.

• Enable/Disable — Toggle individual services on or off without deleting them
• Edit — Modify service URL or event selections
• Delete — Remove a service permanently

Apprise must be installed on the BBS server: pip3 install apprise

See Notifications for detailed setup instructions and the full list of supported services.

Create reusable backup templates with predefined directory paths and exclusion patterns.

Screenshot: Templates tab showing template list

Templates are pre-configured sets of:

• Directories to back up: Common paths like /var/www/, /home/, /etc/
• Exclusion patterns: Files/directories to skip (e.g., *.log, node_modules/, cache directories)

Benefits:

• Consistency: Ensure all clients use the same backup configuration
• Efficiency: Create backup plans faster (select template instead of typing paths)
• Standardization: Enforce organizational backup policies

1. Click Add Template button
2. Fill in the form:
   • Template Name: Descriptive name (e.g., "WordPress Site", "MySQL Server")
   • Description: Optional notes about what this template is for
   • Directories: One path per line, absolute paths
   • Exclusions: One pattern per line (glob patterns supported)
3. Click Save

Screenshot: Template creation form

Name: WordPress Site

Directories:

/var/www/html
/var/www/vhosts
/etc/apache2

Exclusions:

*.log
wp-content/cache/
wp-content/uploads/cache/
.git/
node_modules/

Name: MySQL Database Server

Directories:

/var/lib/mysql
/etc/mysql
/var/backups/mysql

Exclusions:

*.log
mysql-bin.*
*.tmp

When creating or editing a backup plan:

1. Select a template from the Template dropdown
2. Template directories and exclusions are automatically populated
3. Modify as needed (template values are copied, not linked)
4. Save the backup plan

Screenshot: Backup plan form with template dropdown

• Edit: Click the edit icon next to a template
• Delete: Click the delete icon (templates can be deleted even if used by plans, since values are copied)
• Changes to templates do NOT affect existing backup plans (plans store a copy of the template values)

Manage BBS server and agent software updates.

Screenshot: Updates tab showing version information

Displays:

• Installed Version: Current BBS server version (from VERSION file)
• Available Version: Latest version on GitHub Releases
• Release Date: When the latest version was published
• Release Notes: Link to GitHub release notes

1. Click Check for Updates button
2. BBS queries GitHub Releases API for the latest version
3. Compares with installed version
4. Shows "Update Available" message if newer version exists

Frequency: Auto-check runs daily (via scheduler)

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 process:
   • Git fetch and checkout latest tag
   • Composer install (dependencies)
   • Run database migrations
   • Fix file permissions
   • Restart PHP-FPM
5. Refresh page to see new version

Screenshot: Upgrade button and confirmation dialog

Important:

• Backup BBS before upgrading (automatic daily backups via bin/bbs-backup)
• Review release notes for breaking changes
• Test in staging environment first (beta server)

Displays:

• Current Agent Version: Version in agent/bbs-agent.py constant
• Agents Out of Date: Count of agents not running the current version
• Agent Version Distribution: Table showing version and count

Bulk Update All Agents:

1. Click Update All Agents button
2. BBS queues update_agent jobs for all online agents
3. Agents download new script from server, validate, replace, and restart
4. Monitor progress in Queue

Update Single Agent:

• Go to client detail page
• Click Update Agent button
• Monitor job in Queue

Screenshot: Agent version table with Update All Agents button

See Updating-BBS for detailed update procedures.

Manage Borg binary versions across all agents.

Screenshot: Borg Versions tab

Displays a list of Borg versions that can be installed on agents:

• Version: Borg version number (e.g., 1.2.4, 1.4.0)
• Release Date: When this version was released
• Agents Using: Count of agents running this version
• Actions: Set as target version

BBS can fetch the latest Borg releases from GitHub:

1. Click Sync Borg Versions button
2. BBS queries borgbackup/borg GitHub Releases API
3. New versions are added to the list
4. Existing versions are updated

Frequency: Manual (run when you want to upgrade Borg)

Choose which Borg version agents should use:

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

Bulk Update:

1. Set target version
2. Click Update Borg on All Agents
3. BBS queues update_borg jobs for all agents
4. Agents download/install the target Borg version
5. Monitor progress in Queue

Single Agent Update:

• Go to client detail page
• Click Update Borg button

Agents install Borg using one of two methods:

1. Binary Download (preferred):

   • Downloads pre-compiled Borg binary from GitHub releases
   • Fast, reliable, no compilation required
   • Works on most Linux distributions

2. Pip Install (fallback):

   • Installs via pip3 install borgbackup
   • Used if binary download fails
   • Requires Python 3 and pip

Configuration:

• Set preferred method in agent configuration
• Agents automatically fall back to pip if binary fails

Screenshot: Borg version list with target version highlighted

Configure remote SSH hosts for creating borg repositories on external servers like rsync.net, BorgBase, and Hetzner Storage Box.

This tab displays a list of configured remote SSH host configurations. Each host can be used by multiple repositories across different clients.

1. Click Add Host
2. Optionally select a Provider Preset (rsync.net, BorgBase, Hetzner) to auto-fill common settings
3. Fill in:
   • Name: Descriptive name (e.g., "rsync.net Production")
   • Host: Hostname or IP address
   • Port: SSH port (default 22, Hetzner uses 23)
   • Username: SSH username
   • Base Path: Base directory on the remote host (default ./)
   • SSH Private Key: PEM-format private key (encrypted at rest)
   • Remote Borg Path: Custom borg binary name (e.g., borg1 for rsync.net)
4. Click Add Host

Click the plug icon on any host card to test connectivity. BBS will SSH to the host and run borg --version, reporting the borg version found or any connection errors.

• Edit: Click the pencil icon to modify settings. Leave the SSH key field blank to keep the existing key.
• Delete: Click the trash icon. Deletion is blocked if any repositories reference this host.

See Remote Storage for full setup guide, provider-specific instructions, and troubleshooting.

Configure global S3-compatible storage for offsite repository sync.

Screenshot: Offsite Storage tab with S3 configuration form

Verify S3 credentials before saving:

1. Click Test Connection
2. BBS attempts to:
   • Connect to S3 endpoint
   • List bucket contents
   • Create a test file
   • Delete the test file
3. Success or error message displayed

Common Errors:

• Access Denied: Invalid credentials or insufficient bucket permissions
• NoSuchBucket: Bucket doesn't exist or wrong region
• Connection Refused: Incorrect endpoint or firewall blocking

Screenshot: Test Connection button and success message

Setting: Enable automatic sync of BBS server backups to S3

Checkbox: "Sync server backups to S3"

Behavior:

• Daily server backups (from bin/bbs-backup) are uploaded to S3
• Synced to {bucket}/{prefix}/_server-backups/
• Keeps 7 most recent server backups in S3
• Enables complete disaster recovery (restore BBS server from S3)

Requirements: Global S3 settings must be configured and working

See S3-Offsite-Sync for detailed S3 configuration and troubleshooting.

Save Behavior:

• Click Save button at the bottom of each tab
• Settings are validated before saving
• Success or error message displayed
• Changes take effect immediately (no restart required)

Validation:

• Required fields must be filled
• Numeric fields must be within valid ranges
• Paths must be absolute and exist
• Email addresses must be valid format

All settings tabs are accessible only to users with admin role.

Regular users cannot:

• View Settings page
• Change system configuration
• Manage templates
• Update BBS or agents

Regular users can:

• Manage their own clients (if assigned)
• Create backup plans
• Configure plugin settings for their clients

Users can modify their own preferences at /profile:

• Email address
• Password
• Timezone
• 2FA settings
• Notification preferences

See User-Management for user role details.

• Poll Interval: Start with 60 seconds, increase if server load is high
• Max Concurrent Jobs: Start with 4, increase gradually based on server capacity
• Session Timeout: Use 24 hours for high-security environments, 720 hours for convenience
• Force 2FA: Enable for production servers with sensitive data

• Use Push Notifications: Set up at least one push service (Discord, Pushover, etc.) for immediate alerts
• Enable Critical Events: Always subscribe to Backup Failed, Agent Offline, and S3 Sync Failed
• Test Regularly: Periodically test push services and email delivery
• Monitor Spam: If using email, whitelist BBS from address to prevent spam filtering

• Standardize: Create templates for common server types (web, database, file server)
• Document: Add descriptions explaining what each template is for
• Review Periodically: Update templates as backup requirements change
• Test: Use templates on test clients before deploying to production

• Auto-Check: Leave auto-update check enabled (daily)
• Staging First: Test updates on beta server before production
• Backup Before Update: Ensure bin/bbs-backup has run recently
• Review Release Notes: Check for breaking changes or migration steps
• Stagger Agent Updates: Don't update all agents at once (test on a few first)

• Stay Current: Keep Borg up to date for security and bug fixes
• Test New Versions: Test new Borg versions on non-critical agents first
• Compatibility: Verify Borg version is compatible with your repositories (major version changes may break compatibility)

• Secure Credentials: Use dedicated S3 user with minimal permissions
• Test Connection: Always test before saving configuration
• Monitor Costs: Check S3 bill monthly, adjust retention or storage class if needed
• Enable Server Backup Sync: Critical for disaster recovery

Possible Causes:

• Validation errors in form fields
• Database connection issue
• Permission error

Solutions:

• Check for red error messages above form fields
• Ensure all required fields are filled
• Verify database is running: sudo systemctl status mysql
• Check /var/log/apache2/error.log for errors

See Notifications troubleshooting section for detailed SMTP debugging.

See S3-Offsite-Sync troubleshooting section for S3-specific issues.

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 allows outbound HTTPS (port 443)
• Wait 1 hour if rate limit exceeded (60 requests/hour for unauthenticated)

Possible Causes:

• Browser cache showing old values
• PHP-FPM cache not cleared

Solutions:

• Hard refresh browser: Ctrl+Shift+R
• Restart PHP-FPM: sudo systemctl restart php8.1-fpm
• Clear browser cache completely

• Notifications — Push and email notification configuration and troubleshooting
• Remote Storage — Remote SSH host setup and provider guides
• S3-Offsite-Sync — Detailed S3 setup and usage
• Updating-BBS — Update procedures for BBS and agents
• User-Management — User roles and permissions
• Two-Factor-Authentication — Configuring 2FA