# rustic — Fast, restic-compatible Backups in Rust

> Practical guide to rustic — fast, encrypted, deduplicated backups in Rust, compatible with restic repositories and adding configuration profiles.

Source: https://www.jpkc.com/db/en/cheatsheets/backup-sync/rustic/

<!-- PROSE:intro -->
rustic is a backup tool written in Rust that produces fast, encrypted, deduplicated snapshots – while staying fully compatible with existing restic repositories, so you can move between the two tools seamlessly. On top of what restic offers, rustic adds TOML configuration profiles, native cold-storage support and richer retention rules. This guide walks you through the commands you reach for daily: initialising a repository, creating backups, browsing snapshots, restoring data and pruning old states.
<!-- PROSE:intro:end -->

## Repository Initialization

`rustic init -r <repo>` — Initialize a new local repository at the given path.

```bash
rustic init -r /mnt/backup/myrepo
```

`rustic -r sftp:<user>@<host>:<path> init` — Initialize a repository on a remote server via SFTP.

```bash
rustic -r sftp:user@server.com:/backup/repo init
```

`rustic -r opendal:s3 -o s3.bucket=<bucket> -o s3.region=<region> init` — Initialize an S3-compatible repository via the OpenDAL backend.

```bash
rustic -r opendal:s3 -o s3.bucket=my-backups -o s3.region=eu-central-1 init
```

`rustic -r rclone:<remote>:<path> init` — Initialize a repository via rclone (uses any rclone-configured backend).

```bash
rustic -r rclone:gdrive:backups/rustic init
```

`rustic init --set-compression <level>` — Initialize with a specific compression level (-1 to 22, default uses zstd auto).

```bash
rustic init -r /mnt/backup/repo --set-compression 3
```

## Configuration Profiles

`rustic -P <profile> <command>` — Run a command using a named profile from ~/.config/rustic/<profile>.toml or /etc/rustic/<profile>.toml.

```bash
rustic -P daily backup
```

`[repository] in <profile>.toml` — Profile section defining repository, password-file, no-cache, and other repo-wide options (TOML).

```bash
[repository]
repository = "/mnt/backup/repo"
password-file = "/etc/rustic/pw"
```

`[backup] / [[backup.snapshots]] in <profile>.toml` — Pre-configured backup sources with sources, tags, excludes — invoked via 'rustic backup' without arguments.

```bash
[[backup.snapshots]]
sources = ["/home", "/etc"]
tag = ["daily"]
```

`[forget] in <profile>.toml` — Default retention rules — applied by 'rustic forget' without flags.

```bash
[forget]
keep-daily = 7
keep-weekly = 4
```

## Creating Backups

`rustic -r <repo> backup <path>` — Back up a file or directory to the repository.

```bash
rustic -r /mnt/backup/repo backup /home/user
```

`rustic -r <repo> backup <path1> <path2>` — Back up multiple paths in a single snapshot.

```bash
rustic -r /mnt/backup/repo backup /home/user /etc
```

`rustic backup --tag <tag> <path>` — Add one or more tags to the snapshot for filtering and retention.

```bash
rustic backup --tag daily --tag web /var/www
```

`rustic backup --label <label> <path>` — Set a label on the snapshot (useful to group snapshots from different sources).

```bash
rustic backup --label production /var/www
```

`rustic backup --glob <pattern> <path>` — Exclude files or directories matching the given glob pattern.

```bash
rustic backup --glob '!**/node_modules' /home/user/projects
```

`rustic backup --glob-file <file> <path>` — Read include/exclude glob patterns from a file (one per line, prefix '!' to exclude).

```bash
rustic backup --glob-file ~/.rusticignore /home/user
```

`rustic backup --files-from <listfile> <path>` — Read additional files and directories to back up from a file.

```bash
rustic backup --files-from /etc/rustic/includes.txt
```

`rustic backup --as-path <virtual-path> <path>` — Store the backup under a different (virtual) path inside the snapshot. Useful for renamed sources.

```bash
rustic backup --as-path /home/user /mnt/restore/home/user
```

`rustic backup --json <path>` — Emit machine-readable JSON progress output for scripting and monitoring.

```bash
rustic backup --json /home/user | jq .
```

`rustic backup --dry-run <path>` — Show what would be backed up without writing to the repository.

```bash
rustic backup --dry-run /home/user
```

## Listing & Inspecting Snapshots

`rustic -r <repo> snapshots` — List all snapshots in the repository.

```bash
rustic -r /mnt/backup/repo snapshots
```

`rustic snapshots --filter-tag <tag>` — List snapshots filtered by tag.

```bash
rustic snapshots --filter-tag daily
```

`rustic snapshots --filter-host <hostname>` — List snapshots from a specific host.

```bash
rustic snapshots --filter-host webserver01
```

`rustic snapshots --json` — Output snapshot list as JSON for scripting.

```bash
rustic snapshots --json | jq '.[].id'
```

`rustic ls <snapshot-id>` — List files inside a specific snapshot.

```bash
rustic ls a1b2c3d4
```

`rustic ls latest` — List files inside the most recent snapshot.

```bash
rustic ls latest
```

`rustic diff <snapshot1> <snapshot2>` — Show file differences between two snapshots.

```bash
rustic diff a1b2c3d4 latest
```

`rustic cat <type> <id>` — Print the raw decoded content of a repository object (snapshot, tree, blob, config).

```bash
rustic cat snapshot a1b2c3d4
```

## Restoring Data

`rustic restore <snapshot-id> <target>` — Restore a full snapshot to the given target directory.

```bash
rustic restore a1b2c3d4 /tmp/restore
```

`rustic restore latest <target>` — Restore the latest snapshot.

```bash
rustic restore latest /tmp/restore
```

`rustic restore latest:/<path> <target>` — Restore only a sub-path from the latest snapshot.

```bash
rustic restore latest:/home/user/Documents /tmp/restore
```

`rustic restore --glob <pattern> <snapshot> <target>` — Restore only files matching a glob pattern (prefix '!' to exclude).

```bash
rustic restore --glob '!**/*.log' latest /tmp/restore
```

`rustic restore --dry-run <snapshot> <target>` — Show what would be restored without writing files.

```bash
rustic restore --dry-run latest /tmp/restore
```

`rustic restore --delete <snapshot> <target>` — Delete files in the target that do not exist in the snapshot (mirror restore).

```bash
rustic restore --delete latest /var/www
```

`rustic dump <snapshot>:<file>` — Print the content of a single file from a snapshot to stdout.

```bash
rustic dump latest:/etc/nginx/nginx.conf
```

## Mount Snapshots (FUSE)

`rustic mount <mountpoint>` — Mount all snapshots as a read-only virtual filesystem (requires FUSE).

```bash
rustic mount /mnt/rustic
```

`rustic mount <snapshot-id> <mountpoint>` — Mount a single snapshot as a read-only filesystem.

```bash
rustic mount latest /mnt/rustic
```

## Forget & Prune (Retention)

*`rustic forget` and `rustic prune` remove snapshots and unreferenced data permanently – always preview the effect first with `--dry-run`.*

`rustic forget --keep-last <n>` — Keep only the n most recent snapshots and mark the rest for removal.

```bash
rustic forget --keep-last 7
```

`rustic forget --keep-daily <n> --keep-weekly <n> --keep-monthly <n>` — Apply a standard retention policy: keep n daily/weekly/monthly snapshots.

```bash
rustic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12
```

`rustic forget --keep-within <duration>` — Keep all snapshots created within the given duration (e.g., 7d, 4w, 6m, 1y).

```bash
rustic forget --keep-within 30d
```

`rustic forget --keep-tag <tag>` — Always keep snapshots that carry the given tag.

```bash
rustic forget --keep-tag important
```

`rustic forget --filter-tag <tag> --keep-last <n>` — Apply retention only to snapshots with a specific tag.

```bash
rustic forget --filter-tag daily --keep-last 7
```

`rustic forget --dry-run --keep-daily <n>` — Preview which snapshots would be removed without deleting them.

```bash
rustic forget --dry-run --keep-daily 7
```

`rustic forget --keep-daily 7 --prune` — Apply retention and immediately prune unreferenced data from the repository.

```bash
rustic forget --keep-daily 7 --prune
```

`rustic prune` — Remove data no longer referenced by any snapshot. Use --instant-delete to skip the safety delay.

```bash
rustic prune
```

## Repository Maintenance

`rustic check` — Check the repository for errors and verify metadata integrity.

```bash
rustic check
```

`rustic check --read-data` — Verify all pack files by reading and decrypting their contents (slow, thorough).

```bash
rustic check --read-data
```

`rustic check --read-data-subset <n>%` — Verify a percentage of the data. Useful for staggered/scheduled verification.

```bash
rustic check --read-data-subset 10%
```

`rustic repair index` — Rebuild the repository index. Use if the index is lost or corrupted.

```bash
rustic repair index
```

`rustic repair snapshots` — Repair snapshots whose data is partially missing (creates fixed copies, originals stay).

```bash
rustic repair snapshots
```

`rustic repoinfo` — Show repository information: pack/blob counts, totals, compression ratio.

```bash
rustic repoinfo
```

`rustic key list` — List all encryption keys stored in the repository.

```bash
rustic key list
```

`rustic key add` — Add a new encryption password to the repository.

```bash
rustic key add
```

`rustic copy --target <repo2>` — Copy snapshots to a second repository (3-2-1 backup strategy).

```bash
rustic copy --target sftp:user@offsite.com:/backup
```

## Tags & Snapshot Management

`rustic tag <snapshot-id> --add <tag>` — Add tags to existing snapshots without re-running backup.

```bash
rustic tag a1b2c3d4 --add archive
```

`rustic tag <snapshot-id> --remove <tag>` — Remove tags from existing snapshots.

```bash
rustic tag a1b2c3d4 --remove daily
```

`rustic tag --set <tag> <snapshot-id>` — Replace all tags of a snapshot with the given tag(s).

```bash
rustic tag --set archive a1b2c3d4
```

`rustic merge <snapshot1> <snapshot2>` — Merge two snapshots into a single new snapshot.

```bash
rustic merge a1b2c3d4 e5f6g7h8
```

## Environment Variables

`export RUSTIC_REPOSITORY=<path>` — Set the default repository so -r can be omitted.

```bash
export RUSTIC_REPOSITORY=/mnt/backup/repo
```

`export RUSTIC_PASSWORD=<password>` — Set the repository password directly. Handy for unattended/cron backups, but RUSTIC_PASSWORD_FILE or RUSTIC_PASSWORD_COMMAND are safer.

```bash
export RUSTIC_PASSWORD=mysecretpassword
```

`export RUSTIC_PASSWORD_FILE=<path>` — Read the repository password from a file.

```bash
export RUSTIC_PASSWORD_FILE=/etc/rustic/password.txt
```

`export RUSTIC_PASSWORD_COMMAND=<cmd>` — Run a command and use its stdout as the password.

```bash
export RUSTIC_PASSWORD_COMMAND='pass show rustic/main'
```

`export RUSTIC_USE_PROFILE=<profile>` — Default profile to load if -P is not specified.

```bash
export RUSTIC_USE_PROFILE=daily
```

`export RUSTIC_NO_PROGRESS=1` — Disable progress bars (useful in cron / non-TTY contexts).

```bash
export RUSTIC_NO_PROGRESS=1
```

## Common Recipes

`rustic -P daily backup && rustic -P daily forget --prune` — Run a daily backup and apply retention from a profile in one cron line.

```bash
0 3 * * * rustic -P daily backup && rustic -P daily forget --prune
```

`rustic snapshots --json | jq -r '.[-1][1][-1].id'` — Get the ID of the latest snapshot as a plain string.

```bash
rustic snapshots --json | jq -r '.[-1][1][-1].id'
```

`rustic backup --glob-file ~/.rusticignore --tag daily /home` — Daily backup of /home with excludes and a tag for retention policies.

```bash
rustic backup --glob-file ~/.rusticignore --tag daily /home
```

`rustic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune` — Standard retention policy: 7 daily, 4 weekly, 12 monthly snapshots.

```bash
rustic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune
```

`rustic copy --target <repo2> && rustic -r <repo2> check` — Sync to an offsite repo and verify it (3-2-1 strategy with integrity check).

```bash
rustic copy --target sftp:user@offsite:/backup && rustic -r sftp:user@offsite:/backup check
```

<!-- PROSE:outro -->
## Conclusion

rustic pairs the speed and memory safety of Rust with restic's proven, deduplicated repository format – an appealing choice when you build on restic but want configuration profiles and more convenience. Treat your repository password like any other secret, and always preview `forget`/`prune` with `--dry-run` first. And a backup you have never restored is only a guess: test `rustic restore` regularly.

## Further Reading

- [rustic – official website](https://rustic.cli.rs) – documentation, installation guide and configuration reference
- [rustic – GitHub project](https://github.com/rustic-rs/rustic) – source code, releases and issue tracker
- [restic documentation](https://restic.readthedocs.io/) – background on the compatible repository format
<!-- PROSE:outro:end -->

## Related Commands

- [restic](https://www.jpkc.com/db/en/cheatsheets/backup-sync/restic/) – the original; rustic is compatible with its repositories
- [borgbackup](https://www.jpkc.com/db/en/cheatsheets/backup-sync/borgbackup/) – deduplicating backup with compression and encryption
- [duplicity](https://www.jpkc.com/db/en/cheatsheets/backup-sync/duplicity/) – encrypted, incremental backups to many storage backends
- [rclone](https://www.jpkc.com/db/en/cheatsheets/backup-sync/rclone/) – sync files to numerous cloud storage providers