Backup Jobs

Backup jobs (also called backup schedules) automate the process of backing up volumes to repositories on a recurring schedule. Each job defines what to back up, where to store it, when to run, and how long to keep snapshots.

Creating a Backup Job

Navigate to Backups

Click Backups in the sidebar to view all backup schedules.

Create New Schedule

Click the New Backup Schedule button.

Configure Basic Settings

Name: Descriptive name for the backup job (e.g., “Daily Media Backup”)
Volume: Select the volume to back up
Repository: Choose the destination repository
Enabled: Toggle to activate/deactivate the schedule

Set Schedule

Configure when the backup should run using a cron expression.Common examples:

Daily at 2 AM: 0 2 * * *
Every 6 hours: 0 */6 * * *
Weekly on Sunday at midnight: 0 0 * * 0
Monthly on the 1st at 3 AM: 0 3 1 * *

Zerobyte provides a visual cron editor to help you build schedules without memorizing cron syntax.

Configure Retention Policy (Optional)

Define how long to keep snapshots. See Retention Policies below.

Set Backup Filters (Optional)

Configure include/exclude patterns to control what gets backed up. See Backup Filters below.

Add Tags (Optional)

Add custom tags to snapshots for easier organization and filtering.

Save Schedule

Click Create Schedule to save. The next backup time will be calculated automatically.

Backup Schedule Configuration

Cron Expressions

Cron expressions define when backups run. The format is:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *

Examples:

Expression	Description
`0 2 * * *`	Daily at 2:00 AM
`0 /4 * *`	Every 4 hours
`30 3 * * 1`	Every Monday at 3:30 AM
`0 0 1,15 * *`	1st and 15th of month at midnight
`0 0 * * 0`	Every Sunday at midnight
`/15 * * *`	Every 15 minutes

Consider your server’s timezone when setting schedules. The container uses the timezone set in the TZ environment variable.

One File System

Enable this option to prevent backups from crossing filesystem boundaries. Useful when backing up directories that might contain mount points. Use case: When backing up /home, prevent including /home/user/mnt if it’s a separate mount.

Retention Policies

Retention policies automatically clean up old snapshots to manage storage usage. Configure multiple rules to keep different snapshot types.

Retention Rules

Keep Last: Keep the most recent N snapshots
Keep Hourly: Keep the last snapshot for each of the last N hours
Keep Daily: Keep the last snapshot for each of the last N days
Keep Weekly: Keep the last snapshot for each of the last N weeks
Keep Monthly: Keep the last snapshot for each of the last N months
Keep Yearly: Keep the last snapshot for each of the last N years
Keep Within Duration: Keep all snapshots within a time period (e.g., “7d”, “3m”, “1y”)

Retention Policy Examples

Simple: Keep Last 7 Backups

{
  "keepLast": 7
}

Keeps only the 7 most recent snapshots, regardless of when they were created.

Tiered: 7 Daily + 4 Weekly + 12 Monthly

{
  "keepDaily": 7,
  "keepWeekly": 4,
  "keepMonthly": 12
}

Last 7 days: one snapshot per day
Last 4 weeks: one snapshot per week
Last 12 months: one snapshot per month

Duration-Based: Keep 30 Days

{
  "keepWithinDuration": "30d"
}

Keeps all snapshots from the last 30 days.Valid duration units:

h - hours (e.g., “24h”)
d - days (e.g., “7d”)
w - weeks (e.g., “4w”)
m - months (e.g., “3m”)
y - years (e.g., “1y”)

Comprehensive: Long-Term Storage

{
  "keepLast": 3,
  "keepDaily": 7,
  "keepWeekly": 4,
  "keepMonthly": 12,
  "keepYearly": 5
}

Always keep last 3 backups
Last 7 days: one snapshot per day
Last 4 weeks: one snapshot per week
Last 12 months: one snapshot per month
Last 5 years: one snapshot per year

Retention rules can be combined. A snapshot is kept if it matches ANY rule, ensuring you never accidentally delete important backups.

Applying Retention Policies

Retention policies are automatically applied after each successful backup. You can also manually trigger retention cleanup:

Navigate to the backup schedule
Click Run Retention (forget)
Review the snapshots that will be removed
Confirm the operation

Manually deleting snapshots cannot be undone. Always verify retention policies in a test environment before applying them to production data.

Backup Filters

Control which files and directories are included in backups using pattern matching.

Include Patterns

Explicitly include specific files or directories. When include patterns are set, only matching files are backed up. Examples:

/documents/**
/photos/**/*.jpg
/config.yaml

Exclude Patterns

Exclude specific files or directories from backups. Common exclusions:

**/.git/
**/node_modules/
**/*.tmp
**/*.log
**/cache/**
**/.cache/**
**/Thumbs.db
**/.DS_Store

Wildcards:

* - Matches any characters except /
** - Matches any characters including /
? - Matches exactly one character
[abc] - Matches one character from the set
[a-z] - Matches one character from the range

Exclude If Present

Skip directories containing a specific file. Useful for letting applications opt-out of backups. Example:

.nobackup
NOBACKUP

If Zerobyte encounters a directory containing .nobackup, it skips that entire directory.

Pattern Examples

Exclude All Video Files

**/*.mp4
**/*.avi
**/*.mkv
**/*.mov

Exclude Temporary and Cache Files

**/.cache/**
**/cache/**
**/tmp/**
**/*.tmp
**/*.temp
**/*.cache

Include Only Configuration Files

Include patterns:

**/*.yaml
**/*.yml
**/*.json
**/*.conf
**/*.config

Exclude Development Directories

**/node_modules/**
**/.git/**
**/.venv/**
**/venv/**
**/__pycache__/**
**/target/**
**/build/**
**/dist/**

Running Backups

Automatic Execution

Once enabled, backup schedules run automatically at the configured times. The next scheduled run time is shown on the backup schedule details page.

Manual Execution

Run a backup immediately without waiting for the schedule:

Navigate to the backup schedule
Click Run Now
Monitor the backup progress in real-time

Monitoring Progress

During a backup, Zerobyte displays:

Files scanned
Bytes processed
Upload speed
Estimated time remaining
Current file being backed up

Stopping Backups

To cancel a running backup:

Navigate to the backup schedule
Click Stop Backup
Confirm the cancellation

Stopping a backup is safe. Partial data is not committed to the repository, and you can retry the backup later.

Backup Mirrors

Mirrors automatically copy snapshots to additional repositories for redundancy.

Open Mirror Settings

Navigate to a backup schedule and click the Mirrors tab.

Add Mirror Repository

Select a secondary repository to mirror backups to.

Enable Mirror

Toggle the mirror to enable automatic copying after each successful backup.

Verify Compatibility

Zerobyte checks if repositories are compatible (same password/encryption).

Use mirrors to implement the 3-2-1 backup strategy: one local repository and one cloud repository.

Backup Tags

Tags help organize and filter snapshots. Common use cases:

Environment tags: production, development, staging
Application tags: database, media, documents
Purpose tags: daily, weekly, monthly

Example tags:

production
automated
media-server

Backup Status

Each backup schedule shows its status:

Success (green): Last backup completed successfully
Warning (yellow): Backup completed with warnings
Error (red): Last backup failed
In Progress (blue): Backup currently running

Click on a schedule to view:

Last backup time
Next scheduled backup time
Backup duration
Error messages (if any)
List of snapshots created by this schedule

Troubleshooting

Backup fails immediately

Verify the volume is mounted and accessible
Check repository connectivity and authentication
Review backup schedule settings for errors
Check container logs for detailed error messages

Backup takes too long

Reduce the amount of data by using exclude patterns
Check network bandwidth between Zerobyte and the repository
Consider backing up during off-peak hours
Use bandwidth limiting if competing with other services

Repository runs out of space

Review and adjust retention policies
Run retention cleanup manually to free space
Consider using a larger repository or archival storage
Check for failed backups creating orphaned data

Backups don't run on schedule

Verify the schedule is enabled
Check the cron expression is correct
Ensure container timezone (TZ) is set correctly
Check if a previous backup is still running (blocks new runs)

Files are missing from backups

Review include/exclude patterns
Check for directories with “exclude if present” markers
Verify file permissions allow reading
Ensure “one file system” isn’t excluding mounted directories

Best Practices

Schedule backups during off-hours

Run backups when systems are least active to minimize performance impact and ensure consistent data.

Use appropriate retention policies

Balance storage costs with recovery needs. More frequent recent backups, fewer older backups.

Test your backups regularly

Periodically restore files to verify backups are working correctly. See Restoring Data.

Monitor backup status

Set up notifications for failed backups. Don’t wait until you need a restore to discover backups aren’t working.

Use exclude patterns wisely

Exclude temporary files, caches, and other regeneratable data to reduce backup size and time.

Implement the 3-2-1 strategy

Use mirror repositories to keep copies in multiple locations (local + cloud).

Next Steps

Restore Data

Learn how to browse snapshots and restore files

Configure Notifications

Get alerts when backups succeed or fail

Get Started

Core Concepts

Configuration

Guides

Advanced

Creating a Backup Job

Backup Schedule Configuration

Cron Expressions

One File System

Retention Policies

Retention Rules

Retention Policy Examples

Applying Retention Policies

Backup Filters

Include Patterns

Exclude Patterns

Exclude If Present

Pattern Examples

Running Backups

Automatic Execution

Manual Execution

Monitoring Progress

Stopping Backups

Backup Mirrors

Backup Tags

Backup Status

Troubleshooting

Best Practices

Next Steps

Restore Data

Configure Notifications

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Advanced

​Creating a Backup Job

​Backup Schedule Configuration

​Cron Expressions

​One File System

​Retention Policies

​Retention Rules

​Retention Policy Examples

​Applying Retention Policies

​Backup Filters

​Include Patterns

​Exclude Patterns

​Exclude If Present

​Pattern Examples

​Running Backups

​Automatic Execution

​Manual Execution

​Monitoring Progress

​Stopping Backups

​Backup Mirrors

​Backup Tags

​Backup Status

​Troubleshooting

​Best Practices

​Next Steps

Restore Data

Configure Notifications

Build docs developers (and LLMs) love

Creating a Backup Job

Backup Schedule Configuration

Cron Expressions

One File System

Retention Policies

Retention Rules

Retention Policy Examples

Applying Retention Policies

Backup Filters

Include Patterns

Exclude Patterns

Exclude If Present

Pattern Examples

Running Backups

Automatic Execution

Manual Execution

Monitoring Progress

Stopping Backups

Backup Mirrors

Backup Tags

Backup Status

Troubleshooting

Best Practices

Next Steps