Backup Plans

Backup Plans

A backup plan defines what to back up, where to store it, when to run backups, and how long to keep them. Each plan belongs to a specific client and targets one repository.

What is a Backup Plan?

A backup plan consists of:

• Source paths: Directories and files to back up
• Exclusions: Patterns for files/directories to skip
• Repository: Where to store the backup archives
• Schedule: When to run backups automatically
• Retention policy: How many backups to keep and for how long
• Plugins: Optional pre/post backup hooks (database dumps, S3 sync, etc.)

Creating a Backup Plan

To create a new backup plan:

1. Navigate to the client detail page
2. Click the Schedules tab
3. Click Create New Plan
4. Configure the plan settings (see below)
5. Click Save Plan

Screenshot: Backup plan creation form showing all configuration options

Plan Name

A descriptive name for the plan (e.g., "Daily System Backup", "Hourly Database Snapshots", "Weekly Full Backup").

Repository

Select the target repository from the dropdown. The list shows only repositories that belong to the current client.

If you haven't created a repository yet, see Repositories for instructions.

Directories

Specify the paths to back up. You can enter paths in two formats:

One path per line:

/etc
/var/www
/home

Space-separated on a single line:

/etc /var/www /home

Tips:

• Use absolute paths (starting with /)
• Include parent directories rather than many individual files (more efficient)
• Consider using backup templates (see below) for common directory sets

Exclusions

Specify files and directories to exclude from the backup using borg patterns. Common patterns:

Exclude specific directories:

*/node_modules
*/__pycache__
*/.cache
*/tmp

Exclude by extension:

*.log
*.tmp
*.swp
*.pyc

Exclude hidden files:

.*

Exclude system directories:

/proc
/sys
/dev
/run
/tmp

Pattern syntax:

• * matches anything except /
• ** matches anything including /
• ? matches any single character
• [abc] matches any character in the set
• Patterns are matched against the full path

For more information, see the BorgBackup patterns documentation.

Compression

BBS supports all borg compression specs. The compression field accepts a free-text value with autocomplete suggestions for common options:

Spec	Description
lz4	Very fast, low compression (default)
zstd	Balanced speed and compression (default level 3)
zstd,N	Zstandard with level 1-22 (e.g., zstd,10 for higher compression)
zlib	Medium speed, medium compression (default level 6)
zlib,N	Zlib with level 0-9
lzma	Slow, high compression (default level 6)
lzma,N	LZMA with level 0-9 (e.g., lzma,6 for ~4x space reduction over lz4)
auto,C,L	Auto-detect: only compress compressible data (e.g., auto,lzma,6)
obfuscate,S,C	Add size obfuscation with encryption (e.g., obfuscate,110,none)
none	No compression

Click the Help link next to the compression field for the full borg compression documentation.

Tips:

• lz4 is a good default — fast with minimal CPU impact
• zstd or zstd,3 offers a good balance for most workloads
• lzma,6 gives the best compression ratio but is significantly slower
• auto,* modes skip compression for already-compressed data (images, videos, archives), saving CPU time

Schedule Frequency

Choose when backups should run automatically:

Manual

• No automatic scheduling
• Backups run only when triggered manually via "Run Now" button
• Useful for on-demand backups or testing

Hourly

• Runs at specified minutes past each hour
• Options: 0, 15, 30, or 45 minutes past the hour
• Example: "15" runs at 00:15, 01:15, 02:15, etc.

Daily

• Runs once per day at a specified time
• Enter time in 24-hour format (e.g., "03:00" for 3 AM)
• Best for most production backups

Weekly

• Runs once per week on a specified day and time
• Choose day: Monday through Sunday
• Enter time in 24-hour format
• Good for full system backups

Monthly

• Runs once per month on a specified day and time
• Choose day: 1-28 (days 29-31 are avoided to ensure the backup runs every month)
• Enter time in 24-hour format
• Useful for long-term archive snapshots

Note: All times are in the server's timezone. Scheduled jobs are queued by the BBS scheduler (cron-driven), and the agent picks them up on its next poll cycle.

Retention Policy

The retention policy determines how long backups are kept using borg's prune command. BBS supports these retention options:

• Keep last N minutes: Number of minutely archives to keep (default: 0)
• Keep last N hours: Number of hourly archives to keep (default: 0)
• Keep last N days: Number of daily archives to keep (default: 7)
• Keep last N weeks: Number of weekly archives to keep (default: 4)
• Keep last N months: Number of monthly archives to keep (default: 6)
• Keep last N years: Number of yearly archives to keep (default: 0)

How retention works:

After each backup, borg automatically runs the prune command with your specified retention policy. Borg intelligently selects which archives to keep based on:

1. The time interval (minute, hour, day, week, month, year)
2. The number you specified for each interval
3. The archive timestamps

Example retention policy:

Keep last 7 days: 7
Keep last 4 weeks: 4
Keep last 6 months: 6

This keeps:

• 7 most recent daily backups
• 4 weekly backups (one per week for the last 4 weeks)
• 6 monthly backups (one per month for the last 6 months)

Older archives are automatically deleted during the prune operation.

Best Practices:

• Match retention to your recovery time objectives (RTO) and recovery point objectives (RPO)
• Consider regulatory requirements for data retention
• Balance storage costs against the need for long-term recovery points
• For critical data, keep at least 7 days, 4 weeks, and 6 months
• For databases with frequent changes, consider hourly retention

Plugins

Optionally attach plugins to extend backup functionality:

MySQL Database Backup

Automatically dumps MySQL/MariaDB databases before the backup runs:

• Select databases to dump (or dump all)
• Dumps are stored in /tmp/bbs-mysql-dump/ and included in the backup
• Dumps are automatically cleaned up after backup completes

PostgreSQL Database Backup

Automatically dumps PostgreSQL databases before the backup runs:

• Select databases to dump (or dump all)
• Dumps are stored in /tmp/bbs-pg-dump/ and included in the backup
• Dumps are automatically cleaned up after backup completes

Shell Hooks

Run custom scripts before or after backups:

• Pre-backup script: Runs before borg create (e.g., stop services, flush caches)
• Post-backup script: Runs after borg create (e.g., restart services, send notifications)
• Scripts run as root on the client machine

S3 Sync

Automatically sync the repository to Amazon S3 or compatible storage after backup completes:

• Requires AWS credentials or compatible S3 service
• Provides off-site backup redundancy
• Runs asynchronously (backup completes before sync)

Email Notifications

Send email alerts on backup success or failure:

• Configure recipient addresses
• Choose notification triggers (failure only, or success and failure)

Health Checks

Ping external monitoring services (e.g., healthchecks.io) after successful backups:

• Provides external monitoring and alerting
• Helps ensure backups are running even if BBS has issues

Using Plugin Configurations:

Plugins use reusable configurations. For example, you can create a "Production MySQL" configuration once and attach it to multiple backup plans. To create a plugin configuration:

1. Go to Settings → Plugin Configurations
2. Click Add Configuration
3. Choose the plugin type
4. Enter configuration details
5. Save with a descriptive name

Then, when creating a backup plan, you can select this saved configuration from the dropdown.

Backup Templates

Administrators can create reusable directory and exclusion templates in Settings → Backup Templates. Templates provide pre-configured sets of paths and exclusions for common scenarios:

• Web Server: /var/www, /etc/apache2, /etc/nginx, with exclusions for logs and caches
• Database Server: /var/lib/mysql, /etc/mysql, with exclusions for temp files
• User Home Directories: /home, with exclusions for caches and temporary files

To use a template when creating a backup plan:

1. Click Load Template on the plan creation form
2. Select a template from the dropdown
3. The directories and exclusions fields are populated automatically
4. Customize as needed

Editing Backup Plans

To edit an existing backup plan:

1. Navigate to the client detail page → Schedules tab
2. Click Edit next to the plan
3. Modify any settings
4. Click Save Changes

Changes to the schedule frequency or retention policy take effect immediately. The next scheduled backup will use the updated configuration.

Toggling Schedules On/Off

You can temporarily disable a backup plan's schedule without deleting the plan:

1. Navigate to the client detail page → Schedules tab
2. Click the toggle switch next to the plan name
3. When disabled, automatic backups will not run, but you can still trigger manual backups

This is useful for:

• Temporarily pausing backups during maintenance
• Testing configuration changes without affecting the schedule
• Disabling backups for decommissioned systems without losing the configuration

Running a Backup Manually

To trigger an immediate backup regardless of the schedule:

1. Navigate to the client detail page → Schedules tab
2. Click Run Now next to the plan
3. The backup is queued immediately
4. The agent picks up the job on its next poll cycle (typically within 30 seconds)

Manual backups follow the same configuration as scheduled backups (same directories, exclusions, retention policy, etc.).

What Happens During a Backup

When a backup job runs, the following sequence occurs:

1. Job Queued

• BBS creates a backup job in the backup_jobs table with status queued
• The job includes all plan settings (directories, exclusions, retention, etc.)

2. Job Sent to Agent

• On the agent's next poll cycle, BBS returns the job with status sent
• Agent acknowledges receipt and marks the job as running

3. Pre-Backup Plugins

• If configured, the agent runs pre-backup plugins:
  • Database dumps (MySQL/PostgreSQL)
  • Pre-backup shell hooks
• Any errors in plugins cause the backup to fail immediately

4. Borg Create

• Agent executes borg create with the configured directories and exclusions
• Borg reads all specified files, deduplicates data, compresses, encrypts, and transfers to the repository
• Progress updates are sent to BBS every 10 seconds
• Archive name format: {hostname}-{timestamp} (e.g., webserver-2026-02-02T03:00:00)

5. Borg Prune

• Agent executes borg prune with the configured retention policy
• Old archives beyond the retention limits are marked for deletion
• Repository space is not reclaimed yet (happens during compact)

6. Borg Compact

• Agent executes borg compact to reclaim space from deleted archives
• This step can be skipped for faster backups if space reclamation isn't urgent

7. Post-Backup Plugins

• If configured, the agent runs post-backup plugins:
  • S3 sync (asynchronous, doesn't block job completion)
  • Post-backup shell hooks
  • Health check pings
  • Email notifications

8. Job Completed

• Agent marks the job as completed (or failed if errors occurred)
• Job statistics are recorded (duration, bytes transferred, files processed, etc.)
• The client's "Last Backup" timestamp is updated

9. Cleanup

• Temporary files (database dumps, etc.) are removed
• SSH connections are closed
• The agent returns to polling for new tasks

Typical Duration:

Backup duration depends on:

• Amount of data to back up
• Change rate since last backup (incremental)
• Network speed (if repository is remote)
• CPU performance (compression/encryption)
• Disk I/O speed

First backup (full): Several minutes to hours Subsequent backups (incremental): Seconds to minutes

---

Next: Restoring-Files | Repositories