Scheduling Automated Backups

Set up cron-based backup schedules with visual builder and execution tracking

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

1. Navigate to Schedules

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

2. Create New Schedule

   Click Create Schedule to open the schedule creation dialog.

3. Configure Basic Settings

   Schedule Name: Descriptive name (e.g., “Nightly Home Backup”)

   Description (optional): Additional notes about the schedule

   Enabled: Toggle to activate/deactivate schedule

4. Set Schedule Timing

   Choose how to define the schedule:

   Presets

   Select from common patterns:

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

   Visual Builder

   Build cron expression visually:

   • Minute: 0-59 or */N
   • Hour: 0-23 or */N
   • Day of Month: 1-31
   • Month: 1-12
   • Day of Week: 0-6 (Sun-Sat)

   Preview next 10 run times as you configure.

   Custom Expression

   Enter cron expression directly:

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

   Choose which repositories to back up:

   Single Repository: Select one repository

   Multiple Repositories: Select multiple repositories (run in sequence)

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

6. 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}

7. 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.

8. 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.

9. 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:

Hourly

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

0 2 * * *  # Daily at 2 AM
30 3 * * *  # Daily at 3:30 AM
0 0,12 * * *  # Twice daily (midnight and noon)

0 0 * * 0  # Weekly on Sunday at midnight
0 3 * * 1  # Weekly on Monday at 3 AM
0 2 * * 0,3,5  # Sunday, Wednesday, Friday at 2 AM

0 0 1 * *  # Monthly on 1st at midnight
0 3 15 * *  # Monthly on 15th at 3 AM
0 0 1,15 * *  # Twice monthly (1st and 15th)

0 9 * * 1-5  # Weekdays at 9 AM
0 6 * * 0,6  # Weekends at 6 AM
*/15 9-17 * * 1-5  # Every 15 min during business hours
0 2 1 */3 *  # Quarterly on 1st at 2 AM

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

1. Create schedule as normal
2. In Repositories section, select multiple repositories
3. Repositories are backed up sequentially in the order shown
4. 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:

1. Prune: Marks archives as deleted
2. 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:

1. Create schedule: “Weekly Maintenance”
2. Cron: 0 4 * * 0 (Sunday 4 AM)
3. Select repositories
4. Enable prune and compact
5. 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

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

Backup Job Logs

1. From execution history, click View Jobs
2. See individual backup jobs for each repository
3. 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

1. Navigate to Schedules
2. Click schedule name
3. Click Edit
4. Modify settings
5. Save changes

Changing cron expression updates “Next Run” time immediately.

Disable/Enable Schedule

Quick Toggle:

1. Navigate to Schedules
2. Click toggle switch next to schedule name

Via Edit:

1. Edit schedule
2. Toggle Enabled checkbox
3. Save

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

Run Schedule Manually

1. Navigate to Schedules
2. Click schedule name
3. Click Run Now
4. 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

1. Navigate to Schedules
2. Click schedule name
3. Click Duplicate
4. New schedule created with name “Copy of [Original Name]”
5. Edit and customize as needed

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

Delete Schedule

1. Navigate to Schedules
2. Click schedule name
3. Click Delete
4. 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

1. Navigate to Settings → Notifications
2. Add notification service (Email, Slack, Discord, etc.)
3. Create notification profile:
   • Name: “Backup Alerts”
   • Services: Select configured services
   • Events: Choose when to notify
     • ✅ Backup Started
     • ✅ Backup Success
     • ✅ Backup Failed
     • ✅ Backup Warning
4. 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:

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

Verify cron expression:

1. Edit schedule
2. Check “Next Runs” preview
3. 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:

1. Navigate to Backup Jobs
2. Find job from schedule (shows “scheduled_job_id”)
3. 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:

1. Navigate to Maintenance Jobs
2. View compact job status
3. Check progress messages

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

Hooks Fail

Review hook logs:

1. Find backup job from schedule
2. View logs for hook stderr output
3. 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:

1. Create test schedule with frequent interval (e.g., every 5 minutes)
2. Verify backups complete successfully
3. Check logs for warnings
4. Test restore from scheduled backup
5. 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: [e-mail]
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