Scheduling Automated Backups

Overview

Borg UI’s scheduler automates backups using cron expressions, allowing you to:

Schedule regular backups (hourly, daily, weekly, monthly)
Back up multiple repositories in a single schedule
Run pre/post backup scripts
Automatically prune and compact repositories
Track execution history and logs

Creating Your First Schedule

Navigate to Schedules

Click Schedules in the sidebar to access the schedule management page.

Create New Schedule

Click Create Schedule to open the schedule creation dialog.

Configure Basic Settings

Schedule Name: Descriptive name (e.g., “Nightly Home Backup”)Description (optional): Additional notes about the scheduleEnabled: Toggle to activate/deactivate schedule

Set Schedule Timing

Choose how to define the schedule:

Presets
Visual Builder
Custom Expression

Select from common patterns:

Every 5 minutes
Hourly
Daily at 2 AM
Weekly on Sunday
Monthly on 1st
Weekdays at 9 AM

Enter cron expression directly:

2 * * *  # Daily at 2 AM
*/30 * * * *  # Every 30 minutes
0 * * 0  # Weekly on Sunday midnight
3 1 * *  # Monthly on 1st at 3 AM

Select Repositories

Choose which repositories to back up:Single Repository: Select one repositoryMultiple Repositories: Select multiple repositories (run in sequence)

Multi-repository schedules back up each repository one after another, not simultaneously.

Configure Archive Naming (Optional)

Customize archive names using templates:

{job_name}-{now}
{repo_name}-{date}
backup-{timestamp}

Available Variables:

{job_name}: Schedule name
{repo_name}: Repository name
{now}: Full timestamp (2024-01-15T02:00:00)
{date}: Date only (2024-01-15)
{time}: Time only (02:00:00)
{timestamp}: Unix timestamp

Default template if not specified: {job_name}-{now}

Add Schedule-Level Hooks (Optional)

Run scripts before/after all backups:

Pre-Backup Script: Runs once before backing up any repository
Post-Backup Script: Runs once after all repositories complete
Run Repository Scripts: Enable to also run per-repository hooks

Schedule-level hooks are ideal for global preparation/cleanup tasks. See Backup Scripts guide for examples.

Configure Maintenance (Optional)

Automatically maintain repositories after backup:Prune Settings:

Run Prune After Backup: Remove old archives
Keep Hourly: Number of hourly backups to keep
Keep Daily: Number of daily backups (default: 7)
Keep Weekly: Number of weekly backups (default: 4)
Keep Monthly: Number of monthly backups (default: 6)
Keep Quarterly: Number of quarterly backups
Keep Yearly: Number of yearly backups (default: 1)

Compact Settings:

Run Compact After Prune: Reclaim disk space after pruning

Pruning removes old archives based on retention policy. Compacting frees up disk space by removing deleted archive data.

Create Schedule

Click Create to save the schedule.The schedule is now active and will run at the specified times.

Cron Expression Examples

Common scheduling patterns:

0 * * * *  # Every hour at minute 0
*/30 * * * *  # Every 30 minutes
0 */6 * * *  # Every 6 hours

Borg UI uses 5-field cron format (minute, hour, day, month, weekday). Use the visual builder to avoid syntax errors.

Multi-Repository Schedules

Schedule backups for multiple repositories in a single job:

Configuration

Create schedule as normal
In Repositories section, select multiple repositories
Repositories are backed up sequentially in the order shown
Drag to reorder execution sequence

Execution Flow

1. Schedule triggers at cron time
2. Run schedule-level pre-backup script (if configured)
3. For each repository:
   a. Run repository pre-backup script (if enabled)
   b. Execute backup
   c. Run repository post-backup script (if enabled)
   d. Run prune (if enabled)
   e. Run compact (if enabled)
4. Run schedule-level post-backup script (if configured)
5. Schedule completes

Benefits

Single schedule: Manage timing in one place
Sequential execution: Prevents resource contention
Unified monitoring: Track all backups together
Global hooks: Run setup/cleanup once for all repositories

For large repositories, consider separate schedules at different times to spread out system load.

Prune and Compact

Understanding Pruning

Pruning removes old archives according to retention policy: Retention Strategy Example:

Keep Hourly: 24    # Last 24 hours
Keep Daily: 7      # Last 7 days
Keep Weekly: 4     # Last 4 weeks
Keep Monthly: 6    # Last 6 months
Keep Yearly: 3     # Last 3 years

Borg automatically determines which archives to keep:

Newest archive in each time bucket is kept
Older archives are pruned
Multiple retention rules can apply to same archive

Understanding Compacting

Compacting reclaims disk space after pruning:

Prune: Marks archives as deleted
Compact: Removes deleted archive data and defragments repository

Compacting can take significant time on large repositories. It locks the repository during operation.

When to Run Maintenance

Run After Every Backup:

Small repositories (< 100 GB)
Frequent backups (hourly/daily)
Storage space is constrained

Run Less Frequently:

Large repositories (> 1 TB)
Weekly/monthly backups
Separate maintenance schedule

Separate Maintenance Schedule: For very large repositories, create dedicated maintenance schedules:

Create schedule: “Weekly Maintenance”
Cron: 0 4 * * 0 (Sunday 4 AM)
Select repositories
Enable prune and compact
Disable backup (maintenance only)

Borg UI supports maintenance-only schedules that skip backup and only run prune/compact.

Execution History and Logs

Viewing Past Executions

Navigate to Schedules
Click on a schedule
View Execution History tab:
- Execution timestamp
- Status (success, failed, running)
- Duration
- Repositories backed up
- Link to backup jobs

Backup Job Logs

From execution history, click View Jobs
See individual backup jobs for each repository
Click a job to view:
- Detailed progress
- Borg output
- Hook execution logs
- Error messages

Scheduled jobs show “scheduled_job_id” linking them back to the schedule that created them.

Managing Schedules

Edit Schedule

Navigate to Schedules
Click schedule name
Click Edit
Modify settings
Save changes

Changing cron expression updates “Next Run” time immediately.

Disable/Enable Schedule

Quick Toggle:

Navigate to Schedules
Click toggle switch next to schedule name

Via Edit:

Edit schedule
Toggle Enabled checkbox
Save

Disabled schedules are preserved but won’t execute until re-enabled.

Run Schedule Manually

Navigate to Schedules
Click schedule name
Click Run Now
Schedule executes immediately (doesn’t affect next scheduled run)

Manual runs are useful for testing schedules or running ad-hoc backups outside the normal schedule.

Duplicate Schedule

Navigate to Schedules
Click schedule name
Click Duplicate
New schedule created with name “Copy of [Original Name]”
Edit and customize as needed

Duplicating is useful for creating similar schedules with slight variations (e.g., different timing for different repositories).

Delete Schedule

Navigate to Schedules
Click schedule name
Click Delete
Confirm deletion

Deleting a schedule does not delete backup jobs created by it. Backup history is preserved.

Advanced Scheduling Patterns

Staggered Backups

Spread backups throughout the day to avoid resource spikes:

Schedule 1 (Critical Data):     0 */4 * * *  # Every 4 hours
Schedule 2 (User Documents):    30 */6 * * *  # Every 6 hours at :30
Schedule 3 (Logs):              0 0 * * *  # Daily at midnight
Schedule 4 (Media):             0 3 * * 0  # Weekly Sunday 3 AM

Tiered Retention

Different retention policies for different data: Critical Data (frequent, long retention):

Schedule: Every 4 hours
Prune:
  Hourly: 24
  Daily: 30
  Weekly: 12
  Monthly: 24
  Yearly: 5

User Documents (daily, medium retention):

Schedule: Daily at 2 AM
Prune:
  Daily: 14
  Weekly: 8
  Monthly: 6
  Yearly: 2

Logs (daily, short retention):

Schedule: Daily at midnight
Prune:
  Daily: 7
  Weekly: 4
  Monthly: 0
  Yearly: 0

Business Hours vs Off-Hours

Adjust backup frequency based on activity:

Business Hours (Frequent):  */15 9-17 * * 1-5  # Every 15 min, weekdays 9-5
Off-Hours (Less Frequent):  0 */2 * * *  # Every 2 hours
Weekends (Once Daily):      0 6 * * 0,6  # Weekends at 6 AM

Notifications

Borg UI integrates with 100+ notification services via Apprise:

Configure Schedule Notifications

Navigate to Settings → Notifications
Add notification service (Email, Slack, Discord, etc.)
Create notification profile:
- Name: “Backup Alerts”
- Services: Select configured services
- Events: Choose when to notify
  - ✅ Backup Started
  - ✅ Backup Success
  - ✅ Backup Failed
  - ✅ Backup Warning
Assign profile to repositories or schedules

See Notifications Guide for detailed configuration.

Monitoring and Alerts

Dashboard Overview

The dashboard shows:

Recent Backup Jobs: Latest executions with status
Upcoming Schedules: Next scheduled runs
Failed Jobs: Backups needing attention
Repository Health: Archive counts, sizes, last backup

MQTT Integration

Publish backup events to MQTT broker for external monitoring:

environment:
  - MQTT_BROKER=mqtt.example.com
  - MQTT_PORT=1883
  - MQTT_USERNAME=borgui
  - MQTT_PASSWORD=secret

Topics published:

borgui/backup/start
borgui/backup/progress
borgui/backup/complete
borgui/backup/failed

Troubleshooting

Schedule Not Running

Check schedule is enabled:

Navigate to Schedules
Verify toggle is “On”
Check “Next Run” time is in the future

Verify cron expression:

Edit schedule
Check “Next Runs” preview
If empty, expression may be invalid

Check system time:

docker exec borg-ui date

Ensure container time is correct and timezone is set.

Schedule Runs But Backup Fails

Review backup job logs:

Navigate to Backup Jobs
Find job from schedule (shows “scheduled_job_id”)
Review error messages

Common Issues:

Repository locked (previous backup still running)
Permissions denied (source directories not accessible)
Disk space exhausted
SSH connection failed (remote repositories)

Prune/Compact Hangs

Check repository lock:

borg break-lock /path/to/repository

Monitor compact progress:

Navigate to Maintenance Jobs
View compact job status
Check progress messages

Compact operations can take hours on large repositories. Avoid breaking locks unless process is truly stuck.

Hooks Fail

Review hook logs:

Find backup job from schedule
View logs for hook stderr output
Check hook exit codes

Common Hook Issues:

Script syntax errors
Timeouts (increase timeout in schedule settings)
Permission issues (Docker socket not mounted)
Missing dependencies

See Backup Scripts troubleshooting for detailed hook debugging.

Best Practices

Test Schedules Thoroughly

Before relying on schedules:

Create test schedule with frequent interval (e.g., every 5 minutes)
Verify backups complete successfully
Check logs for warnings
Test restore from scheduled backup
Update to production timing after validation

Use Descriptive Names

Schedule names should indicate:

What’s being backed up
Frequency
Purpose

Good examples:

“Hourly Database Snapshots”
“Daily Full Server Backup”
“Weekly Offsite Sync”

Avoid generic names like “Backup 1”, “Test”, “Schedule”.

Set Appropriate Retention

Balance between:

Disk space: More archives = more storage
Recovery granularity: More frequent backups = better point-in-time recovery
Compliance: Regulatory requirements for retention periods

Start conservative, adjust based on usage patterns.

Monitor Schedule Health

Regularly review:

Failed backup jobs
Growing repository sizes
Schedule drift (jobs taking longer than interval)
Hook execution times

Set up alerts for failures and warnings.

Document Schedule Purpose

Use the Description field to document:

Business requirements
Change history
Special considerations
Contact for issues

Example:

Critical database backups for payment processing.
Required by compliance (7-year retention).
Contact: [email protected]
Last updated: 2024-01-15

Next Steps

Backup Scripts

Add pre/post backup hooks to schedules

Notifications

Set up alerts for scheduled backups

Repository Maintenance

Optimize and verify scheduled backups

Remote Repositories

Schedule backups to remote storage

Getting Started

Core Features

Configuration

Guides

Deployment

Advanced

​Overview

​Creating Your First Schedule

​Cron Expression Examples

​Multi-Repository Schedules

​Configuration

​Execution Flow

​Benefits

​Prune and Compact

​Understanding Pruning

​Understanding Compacting

​When to Run Maintenance

​Execution History and Logs

​Viewing Past Executions

​Backup Job Logs

​Managing Schedules

​Edit Schedule

​Disable/Enable Schedule

​Run Schedule Manually

​Duplicate Schedule

​Delete Schedule

​Advanced Scheduling Patterns

​Staggered Backups

​Tiered Retention

​Business Hours vs Off-Hours

​Notifications

​Configure Schedule Notifications

​Monitoring and Alerts

​Dashboard Overview

​MQTT Integration

​Troubleshooting

​Schedule Not Running

​Schedule Runs But Backup Fails

​Prune/Compact Hangs

​Hooks Fail

​Best Practices

​Next Steps

Backup Scripts

Notifications

Repository Maintenance

Remote Repositories

Build docs developers (and LLMs) love

Overview

Creating Your First Schedule

Cron Expression Examples

Multi-Repository Schedules

Configuration

Execution Flow

Benefits

Prune and Compact

Understanding Pruning

Understanding Compacting

When to Run Maintenance

Execution History and Logs

Viewing Past Executions

Backup Job Logs

Managing Schedules

Edit Schedule

Disable/Enable Schedule

Run Schedule Manually

Duplicate Schedule

Delete Schedule

Advanced Scheduling Patterns

Staggered Backups

Tiered Retention

Business Hours vs Off-Hours

Notifications

Configure Schedule Notifications

Monitoring and Alerts

Dashboard Overview

MQTT Integration

Troubleshooting

Schedule Not Running

Schedule Runs But Backup Fails

Prune/Compact Hangs

Hooks Fail

Best Practices

Next Steps