User Guide

Using Plugins

Extend your backup workflow with database dumps, custom scripts, and cloud sync. Plugins run automatically before and after each backup.

How Plugins Work

Plugins are attached to backup plans and execute automatically during the backup workflow:

  1. Pre-backup — Shell hooks run, then database dumps (MySQL/PostgreSQL) are created
  2. Backup — Borg creates the archive, including any dump files
  3. Post-backup — Shell hooks run after backup completes
  4. Post-prune — S3 sync mirrors the repository to cloud storage

Enabling Plugins

Plugins must be enabled on a per-client basis before use:

  1. Navigate to the client detail page
  2. Click the Plugins tab
  3. Toggle the desired plugins to Enabled
  4. Click Add Configuration to create a named configuration
Plugins tab in Borg Backup Server showing enable toggles and configuration cards
Screenshot coming soon

MySQL Database Backup

Automatically dumps MySQL/MariaDB databases before each backup. Dump files are included in the Borg archive and can be restored with one click from the Restore tab.

Configuration

  • Database Host — Hostname or IP (default: localhost)
  • Port — MySQL port (default: 3306)
  • Username/Password — MySQL credentials (encrypted in BBS)
  • Databases — Comma-separated list, or "all" for all databases
  • Dump Directory — Where to store dump files on the client

Restoring: From the Restore tab, select an archive containing database dumps and click Restore Database. Choose which databases to restore and enter the target server credentials.

PostgreSQL Database Backup

Automatically dumps PostgreSQL databases before each backup using pg_dump in custom format (compressed). Configuration and restore workflow are identical to MySQL.

Shell Script Hook

Run custom shell scripts before and/or after backups. Useful for stopping/starting services, flushing caches, or triggering external workflows.

Configuration

  • Pre-backup Script — Path to a script that runs before borg create
  • Post-backup Script — Path to a script that runs after backup (success or failure)
  • Working Directory — Directory to run scripts from
  • Timeout — Maximum execution time in seconds
Tip: Pre-backup scripts that return a non-zero exit code will abort the backup. This is a safety feature — if your pre-backup database dump fails, the backup won't proceed with potentially inconsistent data.

S3 Offsite Sync

Mirrors Borg repositories to S3-compatible cloud storage (AWS S3, Wasabi, Backblaze B2, DigitalOcean Spaces, and more) for offsite disaster recovery.

Configuration

  • Endpoint — S3 API endpoint URL
  • Region — Storage region
  • Bucket Name — Target bucket (must already exist)
  • Access Key / Secret Key — S3 credentials (encrypted in BBS)
  • Bandwidth Limit — Optional upload speed limit (e.g., "10M" for 10 MB/s)

S3 sync runs incrementally after each prune — only changed files are uploaded. You can restore repositories from S3 if local data is lost.

Named Configurations

Plugin configurations are named and reusable. Create a configuration once (e.g., "Production MySQL") and attach it to multiple backup plans. This ensures consistency and makes maintenance easier — update one configuration to affect all plans using it.

Testing Configurations

Before running a production backup, click the Test button next to any configuration. BBS queues a test job that verifies connectivity, credentials, and permissions without running a full backup.

Attaching Plugins to Plans

When creating or editing a backup plan, select your plugin configurations from the dropdown menus in the Plugins section. A single plan can use multiple plugins simultaneously (e.g., MySQL dump + shell hook + S3 sync).

← Previous Restoring Files