---
title: Backups
description: Learn how backup jobs connect volumes to repositories with scheduling, retention policies, and restore capabilities
---

Learn how backup jobs connect volumes to repositories with scheduling, retention policies, and restore capabilities.

## What are backup jobs?

A backup job is the central piece of Zerobyte. It defines four things:

- **What** to back up, a [volume](/docs/concepts/volumes) (your data source)
- **Where** to store it, a [repository](/docs/concepts/repositories) (your encrypted storage destination)
- **When** to run, a cron schedule
- **How long** to keep snapshots, a retention policy

Each time a backup job runs, Restic creates an incremental, encrypted snapshot of the volume's contents and stores it in the repository.

## Creating a backup job

To create a backup job, navigate to **Backups** in the sidebar and click **Create a backup job**. First choose a volume, then fill in the backup form:

- **Backup name**, a descriptive name for the job (e.g., "Daily Database Backup")
- **Backup repository**, select from your configured repositories
- **Backup frequency**, choose `Manual only`, `Hourly`, `Daily`, `Weekly`, `Specific days`, or `Custom (Cron)`
- **Retention policy**, optionally define how many snapshots to keep

<Callout type="info">
  Choose **Manual only** if you want to create the job without scheduled runs and trigger it yourself.
</Callout>

## Scheduling

Backup jobs use **cron expressions** to define when they run. Cron syntax gives you precise control over scheduling.

### Common cron patterns

| Cron Expression   | Schedule                     |
| ----------------- | ---------------------------- |
| `0 2 * * *`       | Daily at 2:00 AM             |
| `0 2 * * 0`       | Weekly on Sunday at 2:00 AM  |
| `0 2 1 * *`       | Monthly on the 1st at 2:00 AM |
| `0 */6 * * *`     | Every 6 hours                |
| `0 0 * * 1-5`     | Weekdays at midnight         |

<Callout type="info">
  The timezone for cron schedules is controlled by the `TZ` environment variable set on the Zerobyte container. If `TZ` is not set, the system defaults to UTC.
</Callout>

## Retention policies

Retention policies control how long snapshots are kept. After each backup, Restic automatically prunes snapshots that fall outside the defined policy, freeing up storage space.

You can configure the following retention rules:

| Rule           | Description                                |
| -------------- | ------------------------------------------ |
| **Keep Last**    | Number of most recent snapshots to keep    |
| **Keep Daily**   | Number of daily snapshots to keep          |
| **Keep Weekly**  | Number of weekly snapshots to keep         |
| **Keep Monthly** | Number of monthly snapshots to keep        |
| **Keep Yearly**  | Number of yearly snapshots to keep         |

### Example retention policy

A balanced policy for most workloads:

- **Keep Daily**: 7, one snapshot per day for the past week
- **Keep Weekly**: 4, one snapshot per week for the past month
- **Keep Monthly**: 6, one snapshot per month for the past half year
- **Keep Yearly**: 1, one snapshot per year for long-term archival

<Callout type="info">
  Retention rules are additive. A snapshot that satisfies any rule is kept. Restic determines which snapshots best represent each time period automatically.
</Callout>

## Include and exclude paths

By default, the entire volume is backed up. You can refine this with include and exclude patterns.

### Include paths

Specify subdirectories within the volume to back up. Only these paths will be included in the snapshot.

### Exclude patterns

Exclude files or directories that do not need to be backed up. Common patterns:

- `*.tmp`, temporary files
- `node_modules/`, dependency directories
- `.cache/`, cache directories
- `*.log`, log files

<Callout type="warn">
  Exclude patterns use Restic's pattern matching. Test your patterns after the first backup by browsing the snapshot contents to confirm the right files are included.
</Callout>

## Compression

Backups inherit the compression mode from the repository they write to. Compression is configured per repository and applies to all backup jobs targeting that repository.

Available modes are **auto** (default), **off**, and **max**. See [Repositories](/docs/concepts/repositories) for details on each mode.

## Running backups

There are two ways to run a backup job:

- **Scheduled**, the job runs automatically according to its cron schedule. No intervention required.
- **Manual**, click **Backup now** on any backup job to trigger it immediately, regardless of the schedule.

Both methods produce identical snapshots. Manual runs are useful for verifying a new backup job or creating an extra snapshot before a major change.

<Callout type="info">
  You can monitor backup progress in real time through the web interface. Zerobyte streams file counts, data processed, and upload progress as the backup runs.
</Callout>

## Backup webhooks

Backup jobs can run optional HTTP webhooks immediately before and after Restic. Pre-backup webhooks are useful for preparing the source, such as pausing a service or creating a dump. Post-backup webhooks are useful for cleanup, such as resuming a service after the snapshot.

Pre-backup hook failures stop the backup before Restic runs. Post-backup hook failures are recorded with the run result; a clean backup becomes a warning if the post hook fails.

For setup details and a container stop/start example, see [Backup Webhooks](/docs/guides/backup-webhooks).

## Backup status

The UI exposes two related status views:

- In the **Backups** list, the status dot shows **Active**, **Paused**, **Error**, **Warning**, or **Backup in progress**
- In the backup job details page, the last run status shows **Success**, **Error**, **Warning**, or **in progress**
- If a backup job has not completed a run yet, the details page shows no last run value

## Snapshots

Each successful backup creates a snapshot in the repository. Snapshots have several important properties:

- **Immutable**, once created, a snapshot cannot be modified
- **Incremental**, only changed data since the last snapshot is uploaded
- **Browsable**, you can explore snapshot contents directly in the web interface, viewing file sizes, modification times, and directory structure

The first backup uploads all data and may take longer. Subsequent backups are significantly faster because Restic deduplicates data at the chunk level and only transfers new or changed blocks.

## Restoring data

Zerobyte lets you browse snapshots, restore them back to a filesystem path, or download the selected contents directly.

For the complete restore workflow, overwrite modes, custom-target guidance, and mounted-volume permission caveats, see [Restoring Data](/docs/guides/restoring).

At a high level, restoring works like this:

<Steps>
  <Step>

### Navigate to the backup job

Go to **Backups** and select the job containing the data you need.

  </Step>

  <Step>

### Select a snapshot

Choose the snapshot from the time period you want to restore from.

  </Step>

  <Step>

### Browse and select files

Navigate the file tree and select the files or folders you want to restore.

  </Step>

  <Step>

### Choose a restore location

Decide whether to restore to the original location or specify a custom path.

  </Step>

  <Step>

### Restore

Click **Restore** and wait for the operation to complete.

  </Step>
</Steps>

<Callout type="warn">
  By default, restored files are placed back in their original location. This can overwrite current files. If you want to inspect the restored data before replacing anything, specify an alternate restore path.
</Callout>

## Mirror repositories

You can optionally copy snapshots to additional repositories after each backup. Mirrors provide:

- **Geographic redundancy**, store copies in different regions or data centers
- **Provider diversification**, avoid depending on a single cloud provider
- **Compliance**, meet data locality or regulatory requirements

Mirrors are configured per backup job. After each successful backup, snapshots are automatically copied to all enabled mirror repositories.

For a practical pattern that combines fast local restores with an offsite copy, see [3-2-1 Backup Strategy](/docs/guides/3-2-1-backup-strategy).

## Monitoring

The Zerobyte web interface provides visibility into each backup job:

- **Schedule**, the cron expression or `Manual only` configuration for the job
- **Last backup**, when the most recent run happened
- **Next backup**, when the job is expected to run next
- **Snapshot history**, the list of snapshots created for that job
- **Snapshot statistics**, data added, data stored, files processed, bytes processed, and duration for the selected snapshot
- **Restore actions**, restore or download data from the selected snapshot

## Best practices

<Accordions type="multiple">
  <Accordion title="Schedule backups during off-peak hours">
    Run backups when system load is lowest to minimize impact on production workloads. Late night or early morning schedules (e.g., `0 2 * * *`) work well for most setups.
  </Accordion>

  <Accordion title="Use retention policies to balance storage and history">
    Keeping every snapshot indefinitely wastes storage. A policy like 7 daily, 4 weekly, 6 monthly, and 1 yearly provides good coverage without excessive cost.
  </Accordion>

  <Accordion title="Test restores regularly">
    A backup is only valuable if you can restore from it. Periodically restore files to a test location to verify data integrity and familiarize yourself with the restore process.
  </Accordion>

  <Accordion title="Use exclude patterns for temporary files">
    Excluding directories like `node_modules/`, `.cache/`, and `*.tmp` files reduces backup size and duration without losing important data.
  </Accordion>

  <Accordion title="Monitor failed backups and set up notifications">
    Check the backup dashboard regularly for failed jobs. Configure notifications so you are alerted immediately when a backup fails rather than discovering it during a restore. See the [Notifications guide](/docs/guides/notifications) for destination setup, event routing, and delivery examples.
  </Accordion>
</Accordions>

## Next steps

<Cards>
  <Card title="Configuration" icon={<Settings />} href="/docs/configuration">
    Configure environment variables, Docker secrets, and deployment options
  </Card>

  <Card title="Troubleshooting" icon={<LifeBuoy />} href="/docs/troubleshooting">
    Diagnose and resolve common backup issues
  </Card>
</Cards>

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Card, Cards } from "../../../src/components/DocsCard";
import { Callout } from "fumadocs-ui/components/callout";
import { Settings, LifeBuoy } from "lucide-react";
