Skip to content

Plugins

Jump to bottom
Marc Pope edited this page Feb 3, 2026 · 1 revision

Plugins

BBS plugins extend backup functionality by adding pre-backup actions, post-backup actions, and specialized backup capabilities. Plugins allow you to customize the backup workflow for each client's specific needs.

Plugin System Overview

The BBS plugin architecture consists of:

  • Plugin Types: Built-in plugins provided by BBS (MySQL, PostgreSQL, Shell Hook, S3 Sync)
  • Plugin Configurations: Named, reusable configurations for each plugin type
  • Backup Plan Association: Plugins are attached to backup plans, not directly to clients
  • Per-Client Enablement: Each plugin must be enabled on a per-client basis before use

How Plugins Work

When a backup job runs:

  1. BBS checks which plugins are attached to the backup plan
  2. The agent receives plugin instructions along with the backup job
  3. Pre-backup plugins execute first (e.g., database dumps, custom scripts)
  4. Borg creates the backup archive
  5. Post-backup plugins execute (e.g., notifications, cleanup scripts)
  6. Post-prune plugins execute after pruning completes (e.g., S3 sync)

Available Plugins

1. MySQL Backup (mysql_dump)

Purpose: Automatically dump MySQL databases before backup

Use Cases:

  • WordPress, Joomla, Drupal site backups
  • Production database backups
  • E-commerce platforms (WooCommerce, Magento)
  • Custom application databases

How It Works:

  • Executes mysqldump before Borg runs
  • Creates .sql files in a specified dump directory
  • Borg includes the dump files in the backup archive
  • Enables one-click MySQL restoration from the BBS web interface

Configuration Parameters:

  • Database host and port
  • Username and password
  • Database names (comma-separated or "all")
  • Dump directory path

See Database-Backups for detailed MySQL backup documentation.

2. PostgreSQL Backup (pg_dump)

Purpose: Automatically dump PostgreSQL databases before backup

Use Cases:

  • Django application databases
  • Rails application databases
  • Data warehouses and analytics platforms
  • Custom PostgreSQL applications

How It Works:

  • Executes pg_dump before Borg runs
  • Creates .dump files in custom format (compressed)
  • Borg includes the dump files in the backup archive
  • Enables one-click PostgreSQL restoration from the BBS web interface

Configuration Parameters:

  • Database host and port
  • Username and password
  • Database names (comma-separated or "all")
  • Dump directory path

See Database-Backups for detailed PostgreSQL backup documentation.

3. Shell Script Hook (shell_hook)

Purpose: Run custom shell scripts before and/or after backups

Use Cases:

  • Stop/start applications for consistent backups
  • Export application state or logs
  • Notify external monitoring systems
  • Custom cleanup or preparation tasks
  • Trigger webhooks or API calls

How It Works:

  • Pre-backup script: Runs before borg create
  • Post-backup script: Runs after backup completes (success or failure)
  • Scripts run as the agent user on the client machine
  • Environment variables provide context (backup status, archive name, etc.)

Configuration Parameters:

Parameter Description Example
Configuration Name Descriptive name "Stop Nginx Before Backup"
Pre-backup Script Shell script to run before backup /opt/scripts/pre-backup.sh
Post-backup Script Shell script to run after backup /opt/scripts/post-backup.sh
Working Directory Directory to run scripts from /var/www/app
Timeout Maximum execution time (seconds) 300
Run as User Unix user to run scripts as (optional) www-data

Environment Variables Available to Scripts:

BBS_BACKUP_STATUS=success    # or "failed"
BBS_ARCHIVE_NAME=2024-01-15_10-30-00
BBS_REPO_PATH=/var/bbs/repos/12
BBS_BACKUP_PLAN=Daily Backup
BBS_CLIENT_NAME=web-server-01

Example Pre-backup Script:

#!/bin/bash
# Stop Nginx to ensure consistent filesystem state
systemctl stop nginx

# Flush Redis to disk
redis-cli save

# Export application state
/opt/app/bin/export-state.sh

exit 0  # Return 0 for success, non-zero for failure

Example Post-backup Script:

#!/bin/bash
# Restart services
systemctl start nginx

# Send notification
if [ "$BBS_BACKUP_STATUS" = "success" ]; then
    curl -X POST https://monitoring.example.com/webhook \
        -d "status=success&archive=$BBS_ARCHIVE_NAME"
else
    curl -X POST https://monitoring.example.com/webhook \
        -d "status=failed&client=$BBS_CLIENT_NAME"
fi

exit 0

Creating a Shell Hook Configuration

  1. Navigate to client detail → Plugins tab
  2. Enable Shell Script Hook plugin
  3. Click Add Configuration
  4. Fill in the configuration:
    • Configuration name
    • Pre-backup script path (optional)
    • Post-backup script path (optional)
    • Working directory
    • Timeout (default: 300 seconds)
  5. Click Save

Screenshot: Shell Hook plugin configuration form

Important Notes for Shell Hooks

  • Scripts must be executable (chmod +x script.sh)
  • Scripts run as the agent user (typically bbs-agent)
  • Scripts must exist on the client machine, not the BBS server
  • Non-zero exit codes from pre-backup scripts will abort the backup
  • Post-backup scripts run regardless of backup success/failure
  • Use absolute paths for reliability
  • Test scripts manually before attaching to production backups

4. S3 Offsite Sync (s3_sync)

Purpose: Mirror Borg repositories to S3-compatible storage for offsite disaster recovery

Use Cases:

  • Offsite backup copies for disaster recovery
  • Geographic redundancy
  • Long-term archival in cloud storage
  • Compliance requirements for offsite backups

How It Works:

  • Uses rclone to mirror the Borg repository to S3
  • Automatically runs after successful prune operations
  • Incremental sync (only changed files are transferred)
  • Supports bandwidth limiting

Supported Storage Providers:

  • AWS S3
  • Wasabi
  • Backblaze B2
  • DigitalOcean Spaces
  • MinIO
  • Any S3-compatible object storage

Configuration Methods:

  1. Global S3 Settings (Settings → Offsite Storage): One set of credentials for all clients
  2. Named S3 Plugin Config: Per-client S3 credentials and buckets
  3. Inline Per-Plan Config: Unique S3 settings per backup plan

See S3-Offsite-Sync for detailed S3 sync documentation.

Enabling Plugins

Plugins must be enabled on a per-client basis before they can be used:

  1. Navigate to the client detail page
  2. Click the Plugins tab
  3. Toggle the desired plugins to Enabled
  4. Only enabled plugins can have configurations created

Screenshot: Plugins tab showing plugin enable/disable toggles

Named Configurations

Named configurations are reusable plugin settings that can be shared across multiple backup plans for the same client.

Benefits of Named Configurations

  • Reusability: Create once, use in multiple backup plans
  • Consistency: Same database credentials across all plans
  • Maintenance: Update one config to affect all plans using it
  • Organization: Descriptive names like "Production MySQL" or "Staging DB"

Creating a Named Configuration

  1. Client detail → Plugins tab
  2. Find the plugin you want to configure (must be enabled)
  3. Click Add Configuration
  4. Fill in the configuration form
  5. Give it a descriptive name
  6. Save

Screenshot: Plugin configuration list showing multiple named configs

Editing and Deleting Configurations

  • Edit: Click the edit icon next to a configuration
  • Delete: Click the delete icon (only if not attached to any backup plans)
  • In-Use Indicator: Configurations attached to plans show which plans use them

Configuration Sharing

  • Configurations are per-client (not global)
  • The same configuration can be used by multiple backup plans for the same client
  • Configurations cannot be shared across different clients
  • To use the same settings on multiple clients, create separate configurations for each

Attaching Plugins to Backup Plans

Plugins are activated by attaching their configurations to backup plans:

  1. Navigate to client detail → Backup Plans tab
  2. Create a new plan or edit an existing one
  3. Scroll to the Plugins section
  4. Select plugin configurations from the dropdowns:
    • MySQL Backup: Choose a MySQL config (if enabled)
    • PostgreSQL Backup: Choose a PostgreSQL config (if enabled)
    • Shell Hook: Choose a shell hook config (if enabled)
    • S3 Sync: Choose an S3 config (if enabled)
  5. Save the backup plan

Screenshot: Backup plan editor showing plugin configuration dropdowns

Multiple Plugins on One Plan

A single backup plan can use multiple plugins simultaneously:

  • Example: MySQL dump + Shell hook (to stop/start app) + S3 sync (for offsite copy)
  • Plugins execute in order: Pre-backup hooks → Database dumps → Backup → Post-backup hooks → S3 sync

Plugin Execution Order

  1. Pre-backup phase:
    • Shell hook pre-backup script
    • MySQL dump
    • PostgreSQL dump
  2. Backup phase:
    • borg create runs
  3. Post-backup phase:
    • Shell hook post-backup script
  4. Post-prune phase (after prune jobs only):
    • S3 sync

Testing Plugin Configurations

Before running a production backup, test your plugin configurations:

  1. On the Plugins tab, find your configuration
  2. Click the Test button
  3. BBS queues a plugin_test job
  4. Monitor the test in Queue → Job Detail
  5. Review results:
    • Success: Plugin executed correctly
    • Failure: Check error log for issues

Screenshot: Plugin configuration card with Test button

What Testing Does

  • MySQL/PostgreSQL: Connects to database, performs a test dump, verifies dump files created
  • Shell Hook: Executes the scripts in a test environment, captures output and exit codes
  • S3 Sync: Tests S3 credentials, attempts to create a test file in the bucket

Common Test Failures

Plugin Error Solution
MySQL Connection refused Check host/port, verify MySQL is running
MySQL Access denied Verify username/password, check user privileges
PostgreSQL authentication failed Check credentials, review pg_hba.conf
Shell Hook Script not found Verify path is absolute and file exists on client
Shell Hook Permission denied Make script executable, check file permissions
S3 Sync Invalid credentials Verify access key and secret key
S3 Sync Bucket not found Check bucket name, ensure it exists

Plugin Job Types

Plugins create jobs that appear in the Queue:

Job Type Description When It Runs
backup Regular backup with plugin pre/post actions Scheduled or manual
plugin_test Test a plugin configuration Manual test button
restore_mysql Restore MySQL databases from archive Manual restore
restore_pg Restore PostgreSQL databases from archive Manual restore
s3_sync Sync repository to S3 After successful prune

Plugin Security

Credential Storage

  • All plugin credentials (database passwords, S3 keys) are encrypted using BBS's APP_KEY
  • Credentials are never logged or displayed in plain text
  • Agents receive decrypted credentials over HTTPS only when needed for job execution

Access Control

  • Only client owners (or admins) can view/edit plugin configurations
  • Regular users cannot see other users' client plugins
  • API keys authenticate agent-to-server communication

Script Execution Security (Shell Hooks)

  • Scripts run as the agent user (limited privileges)
  • Scripts cannot access BBS server resources
  • Scripts run in the context of the client machine only
  • Validate script sources before deployment
  • Use Run as User option carefully (requires sudo privileges for agent)

Best Practices

General Plugin Usage

  • Test First: Always test plugin configurations before production use
  • Name Clearly: Use descriptive names like "Production MySQL" not "Config 1"
  • Monitor Jobs: Check Queue regularly to ensure plugins execute successfully
  • Update Credentials: Rotate database passwords periodically, update configs accordingly

Performance Considerations

  • Database Dumps: Large databases increase pre-backup time. Monitor dump duration.
  • Shell Scripts: Keep scripts fast. Long-running scripts delay backups.
  • S3 Sync: Bandwidth limiting prevents saturating network connections
  • Concurrent Jobs: Multiple plugins on one plan execute sequentially, not in parallel

Maintenance

  • Remove Unused Configs: Delete configurations no longer attached to plans
  • Review Logs: Check job detail logs for plugin warnings or errors
  • Update Scripts: Keep shell hook scripts in version control
  • Document Configs: Add comments or notes in configuration names

Troubleshooting

Plugin Won't Enable

  • Cause: Missing dependencies on client (e.g., pg_dump not installed)
  • Solution: Install required software on client machine, restart agent

Configuration Test Fails

  • Cause: Incorrect credentials, unreachable services, missing directories
  • Solution: Verify all configuration parameters, check network connectivity, review error logs

Plugin Doesn't Execute During Backup

  • Cause: Configuration not attached to backup plan
  • Solution: Edit backup plan, select the plugin configuration in the Plugins section

Shell Hook Script Fails

  • Cause: Script syntax error, missing executable permission, incorrect path
  • Solution: Test script manually on client (bash /path/to/script.sh), check permissions (ls -l)

S3 Sync Slow or Failing

  • Cause: Bandwidth limits too restrictive, network issues, bucket permissions
  • Solution: Adjust bandwidth limit, verify S3 credentials, check bucket policies

Related Documentation

📖 User Manual

Getting Started

Using BBS

Monitoring

Administration

Reference

Clone this wiki locally