Introduction

Rustic is a fast and secure backup program. In the following sections, we will present typical workflows, starting with installing, preparing a new repository, and making the first backup.

Note: Parts of this documentation are shamelessly copied from the restic documentation and then adapted to rustic as most workflows work in rustic exactly like restic. See also the restic documentation for more information about restic.

Contact

You can ask questions in the Discussions or have a look at the FAQ.

Contact	Where?
Issue Tracker	GitHub Issues
Discord
Discussions	GitHub Discussions

Contributing

Thank you for your interest in contributing to the rustic ecosystem!

We appreciate your help in making this project better.

Code of Conduct

Please review and abide by the general Rust Community Code of Conduct when contributing to this project. In the future, we might create our own Code of Conduct and supplement it at this location.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue on GitHub and provide as much detail as possible. Include steps to reproduce the bug and the expected behavior.

Issue and Pull Request labels

Our Issues and Pull Request labels follow the official Rust style:

A - Area
C - Category
D - Diagnostic
E - Call for participation
F - Feature
I - Issue e.g. I-crash
M - Meta
O - Operating systems
P - priorities e.g. P-{low, medium, high, critical}
PG - Project Group
perf - Performance
S - Status e.g. S-{blocked, experimental, inactive}
T - Team relevancy
WG - Working group

Suggesting Enhancements

If you have an idea for an enhancement or a new feature, we’d love to hear it! Open an issue on GitHub and describe your suggestion in detail.

Developer’s documentation

For more information about developing around rustic, see the developer’s documentation.

License

By contributing to rustic or any crates contained in this repository, you agree that your contributions will be licensed under:

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Frequently asked questions

Can I use rustic with my existing restic repositories?

Yes, you can. Rustic uses the same repository format as restic, so you can use rustic and restic on the same repository. The only thing you have to take care of is that you don’t run prune with restic and rustic at the same time.

What are the differences between rustic and restic?

Written in Rust instead of golang
Optimized for small resource usage (in particular memory usage, but also overall CPU usage)
Philosophy of development (release new features early)
New features (e.g. hot/cold repositories, lock-free pruning)
Some commands or options act a bit different or have slightly different syntax

Why is rustic written in Rust

Rust is a powerful language designed to build reliable and efficient software. This is a very good fit for a backup tool.

How does rustic work with cold storages like AWS Glacier?

If you want to use cold storage, make sure you always specify an extra repository --repo-hot which contains the hot data. This repository acts like a cache for all metadata, i.e. config/key/snapshot/index files and tree packs. As all commands except restore only need to access the metadata, they are fully functional but only need the cold storage to list files while everything else is read from the “hot repo”. Note that the “hot repo” on its own is not a valid rustic repository. The “cold repo”, however, contains all files and is nothing but a standard rustic repository.

If you additionally use a cache, you effectively have a first level cache on your local disc and a second level cache with the “hot repo”. Note that the “hot repo” can be also a remote repo, so hot/cold repositories also work for multiple rustic clients backing up to the same repository.

How does the lock-free prune work?

Like the prune within restic, rustic decides for each pack whether to keep it, remove it or repack it. Instead of removing packs, it however only marks the packs to remove in a separate index structure. Packs which are marked for removal are checked if they are really not needed and have been marked long enough ago. Depending on these checks they are either finally removed, recovered or kept in the state of being marked for removal.

This two-phase deletion is needed for rustic to work lock-free: If a backup runs parallel to a prune run (or forget --prune), it could be that prune decides that some blobs can be removed, but the parallel backup uses these blobs for the newly generated snapshot.

The time to hold marked packs should be long enough to guarantee that a possibly parallel backup run has finished in between. It can be set by the --keep-delete option and defaults to 23 hours. In any case, packs will be kept marked and only deleted by the next prune run.

Note that there is the option --instant-delete which circumvents this two-phase deletion. Only use this option, if you REALLY KNOW that there is no parallel access to your repo, else you risk losing data!

You said “rustic uses less resources than restic” but I’m observing the opposite

In general rustic uses less resources, but there may be some exceptions. For instance the crypto libraries of Rust and golang both have optimizations for some CPUs. But it might be that your CPU benefits from a golang optimization which is not present in the Rust implementation. If you observe some unexpected resource usage, please don’t hesitate to submit an issue.

Comparison between `rustic` and `restic`

General differences

	`restic`	`rustic`
programming language	Go	Rust
test coverage	✅	❌ (only few tests implemented)
config profile support	❌ (wrapper tools available)	✅
locking	lock files in repository	lock-free operations, two-phase pruning
cold storage	❌ (no direct support, may work in special cases)	✅ (full support including warm-up of needed data)
in-repo config	❌	✅ (see below for details)
logging	`-v` or `--quiet`, no log-file support	`--log-level`, supports log-file output
returns error code	✅	❌
available as library	❌	✅ rustic_core

Storage backends

backend	`restic`	`rustic`
`local`	✅ (built-in)	✅ (built-in)
`sftp`	✅ (using external `ssh` command)	✅ (built-in using `opendal`, windows not supported)
`rest`	✅ (built-in)	✅ (built-in)
`s3`	✅ (built-in)	✅ (built-in using `opendal`)
`swift`	✅ (built-in)	✅ (built-in using `opendal`)
`b2`	✅ (built-in)	✅ (built-in using `opendal`)
`azure`	✅ (built-in)	✅ (built-in using `opendal`)
`gs`	✅ (built-in)	✅ (built-in using `opendal`)
`dropbox`	❌	✅ (built-in using `opendal`)
`ftp`	❌	✅ (built-in using `opendal`)
`gdrive`	❌	✅ (built-in using `opendal`)
`onedrive`	❌	✅ (built-in using `opendal`)
`webdav`	❌	✅ (built-in using `opendal`)
`opendal` (other services)	❌	✅ (built-in using `opendal`)
`rclone`	✅ (via stdin, using external `rclone` command)	✅ (via http on localhost, using external `rclone` command)

Commands

command	`restic`	`rustic`
`backup`	✅	✅
`cache`	✅	❌
`cat`	✅	✅
`config`	❌ (no in-repo config)	✅
`check`	✅	✅
`copy`	✅	✅
`diff`	✅	✅
`dump`	✅	✅
`find`	✅	❌
`forget`	✅	✅
`generate`	✅	✅ `completions`
`init`	✅	✅
`key list`	✅	❌
`key add`	✅	✅
`key remove`	✅	❌
`key passwd`	✅	❌
`list`	✅	✅
`ls`	✅	✅
`merge`	❌	✅
`migrate`	✅	❌ (not needed; repo version migration via `config`)
`mount`	✅	❌ (WIP)
`prune`	✅	✅
`recover`	✅	❌
`repair index`	✅	✅
`repair packs`	✅	❌
`repair snapshots`	✅	✅
`repoinfo`	❌	✅
`restore`	✅	✅
`rewrite`	✅	❌
`self-update`	✅	✅
`show-config`	❌	✅
`snapshots`	✅	✅
`stats`	✅	❌ (but there is `repoinfo`)
`tag`	✅	✅
`unlock`	✅	lock-free
`webdav`	❌	✅

Information saved in snapshots

information	`restic`	`rustic`
from repo design info	✅	✅
program version used	✅	✅
summary (size,…)	❌ (WIP)	✅
used command	❌	✅
label	❌	✅
description	❌	✅
delete (protection)	❌	✅

General options

option	`restic`	`rustic`
`--cacert`	✅	❌
`--cache-dir`	✅	✅ (or in config profile)
`--cleanup-cache`	✅	❌
`--compression`	✅ (auto,max,off); needed in every call	✅ (-7..22) configure once in in-repo config
`--dry-run`	✅	✅ (or in config profile)
`--json`	✅	✅
`--key-hint`	✅	❌
`--limit-download`	✅	❌
`--limit-upload`	✅	❌
`--log-file`	❌	✅ (or in config profile)
`--no-cache`	✅	✅ (or in config profile)
`--no-extra-verify`	✅ needed in every call	✅ configure once using `config`
`--no-lock`	✅	✅ all operations are lock-free
`--no-progress`	❌	✅ (or in config profile)
`--progress-intervall`	✅ (via env variable)	✅ (or in config profile)
`--option`	✅ as cmd arg or env variable	✅ via config profile or env variable
`--pack-size`	✅ fix limit; needed in every call	✅ fix or dynamic limit, configure once in in-repo config
`--password-command`	✅	✅ (or in config profile)
`--password-file`	✅	✅ (or in config profile)
`--quiet`	✅	✅
`--repo`	✅	✅ (or in config profile)
`--repo-hot`	❌ (no cold-storage support)	✅ (or in config profile)
`--repository-file`	✅	❌ (use `repository` in config profile instead)
`--retry-lock`	✅	not needed; lock-free
`--tls-client-cert`	✅	❌
`--use-profile`	❌ (no config profile support)	✅ (or in config profile for recursively using profiles)
`--verbose` (multiple times)	✅	✅ `--log-level`
`--warm-up`	❌ (no cold-storage support)	✅ (or in config profile)

`rustic` in-repo config options

option	`restic`	`rustic`
`append_only`	❌	✅
`compression`	✅ (by `--compression`)	✅
`treepack_size`	❌ (only all packs: `--pack-size`)	✅
`treepack_growfactor`	❌	✅
`treepack_size_limit`	❌	✅
`datapack_size`	❌ (only all packs: `--pack-size`)	✅
`datapack_growfactor`	❌	✅
`datapack_size_limit`	❌	✅
`min_packsize_tolerate_percent`	❌ (hardcoded 80% for `prune --repack-small`)	✅
`max_packsize_tolerate_percent`	❌	✅
`extra_verify`	✅ (default, can be unset using `--no-extra-verify`)	✅ (default)

Snapshot filtering

filter	`restic`	`rustic` (options also in config profile)
by host	✅ `--host`	✅ `--filter-host`
by label	❌	✅ `--filter-label`
by paths	✅ `--paths`	✅ `--filter-paths`
by tags	✅ `--tags`	✅ `--filter-tags`
custom	❌	✅ `--filter-fn` (using Rhai)

Comparison of important commands

`init`

option	`restic`	`rustic`
`--copy-chunker-params`	✅	❌ (not needed, see `copy` command)
`--from-*`	✅	❌ (not needed, see `copy` command)
`--hostname`	❌ (always sets hostname)	✅
`--repository-version`	✅	✅ (use `--set-version`)
`--set-*`	❌ (no in-repo config support)	✅
`--username`	❌ (always sets username)	✅
`--with-created`	❌ (always sets creation time)	✅

`backup`

general	`restic`	`rustic`
allow to backup relative paths	❌	✅

option	`restic`	`rustic` (options also in config profile)
`--as-path`	❌	✅
`--command`	❌	✅
`--custom-ignorefile`	❌	✅
`--description`	❌	✅
`--description-from`	❌	✅
`--delete-never`	❌	✅
`--delete-after`	❌	✅
`--exclude`	✅	✅ `--glob`
`--exclude-file`	✅	✅ `--glob-file`
`--exclude-caches`	✅	❌ (use `--exclude-if-present`)
`--exclude-if-present`	✅ (+ support for header parsing)	✅ (no header parsing)
`--exclude-larger-than`	✅	✅
`--files-from`	✅	❌
`--files-from-raw`	✅	❌
`--files-from-verbatim`	✅	❌
`--force`	✅	✅
`--git-ignore`	❌ (roadmap: 0.19)	✅
`--group-by`	✅ (host/paths/tags)	✅ (host/label/paths/tags)
`--host`	✅	✅
`--iexclude`	✅	✅ `--iglob`
`--iexclude-file`	✅	✅ `--iglob-file`
`--ignore-ctime`	✅	✅
`--ignore-inode`	✅	✅
`--ignore-devid`	❌	✅
`--init`	❌	✅
`--label`	❌	✅
`--no-require-git`	❌ (no `--git-ignore`)	✅
`--no-scan`	✅	✅
`--one-file-system`	✅	✅
`--parent`	✅	✅
`--read-concurrency`	✅	❌ (hardcoded)
`--skip-identical-parent`	❌	✅
`--stdin`	✅	✅ (use `-` as backup source)
`--stdin-filename`	✅	✅
`--tag`	✅	✅
`--time`	✅	✅
`--with-atime`	✅	✅

`restore`

general	`restic`	`rustic`
scan and use already existing files	❌ (roadmap: 0.17)	✅
resumable restore	❌ (roadmap: 0.17)	✅
restore hard links	✅	❌
`<snapshotID>:<subfolder>` syntax	✅	✅
`<snapshotID>:<subfolder>/file` syntax	❌	✅

option	`restic`	`rustic`
filtering options for `latest`	✅	✅
`--delete`	❌	✅
`--exclude`	✅	✅ `--glob`
`--iexclude`	✅	✅ `--iglob`
`--iinclude`	✅	✅ `--iglob`
`--include`	✅	✅ `--glob`
`--no-ownership`	❌	✅
`--numeric-id`	❌	✅
`--sparse`	✅	❌
`--target`	✅	✅ (give target as second CLI argument)
`--verify`	✅	❌ (but `diff` can be used to verify after)
`--verify-existing`	❌ (no scanning of existing files)	✅

`dump`

general	`restic`	`rustic`
dump files	✅	✅
dump dirs	✅	❌

option	`restic`	`rustic`
snapshot filtering options for `latest`	✅	✅
`--archive`	✅	❌ (no dumping of dirs)

`forget`

general	`restic`	`rustic`
allow to keep all XXX	✅	✅
respect “no delete” options in snapshot	❌	✅

option	`restic`	`rustic` (options also in config profile)
snapshot filtering options	✅	✅
`--keep-last`	✅	✅
`--keep-daily`	✅	✅
`--keep-weekly`	✅	✅
`--keep-monthly`	✅	✅
`--keep-quarter-yearly`	❌	✅
`--keep-half-yearly`	❌	✅
`--keep-yearly`	✅	✅
`--keep-within`	✅	✅
`--keep-within-hourly`	✅	✅
`--keep-within-daily`	✅	✅
`--keep-within-weekly`	✅	✅
`--keep-within-monthly`	✅	✅
`--keep-within-quarter-yearly`	❌	✅
`--keep-within-half-yearly`	❌	✅
`--keep-within-yearly`	✅	✅
`--keep-tag`	✅	✅
`--compact`	✅	❌
`--group-by`	✅ (host/paths/tags)	✅ (host/label/paths/tags)
`--prune`	✅	✅

`prune`

general	`restic`	`rustic`
prune plan without reading pack files	✅	✅
prune parallel to backup (two-phase prune)	❌ (roadmap: 0.19)	✅
different pack sizes for tree/data packs	❌	✅
resumable prune	❌ (roadmap: 0.17)	✅
(option to) resize packs	✅	✅

option	`restic`	`rustic`
`--fast-repack`	❌	✅
`--instant-delete`	✅ (default, no two-phase)	✅
`--keep-pack`	❌	✅
`--keep-delete`	❌ (no two-phase)	✅
`--max-repack-size`	✅	✅ `--max-repack` (size/%/unlimited)
`--max-unused`	✅	✅
`--repack-all`	❌	✅
`--repack-cacheable-only`	✅	✅
`--repack-small`	✅	✅ (default behavior; to unset use `--no-resize`)
`--repack-uncompressed`	✅	✅
`--unsafe-recover-no-free-space`	✅	✅ `--early-delete-index`

`check`

general	`restic`	`rustic`
check index files	✅	✅
check index vs packs	✅	✅
check snapshot files	✅	✅
(optionally) check pack files	✅	✅
cache policy	create temporary (use existing: roadmap 0.18)	use existing
check cache integrity	❌	✅
check hot/cold integrity	❌ (no cold storage support)	✅

option	`restic`	`rustic`
`--read-data`	✅	✅
`--read-data-subset`	✅	❌
`--trust-cache`	❌ (no cache integrity check)	✅
`--with-cache`	✅	✅ (default behavior)

`copy`

general	`restic`	`rustic`
source/target given by	CLI options	in config profile
multiple targets	❌	✅
check for matching chunker parameters	❌	✅

option	`restic`	`rustic`
snapshot filtering options	✅	✅
`--from-*`	✅ (target is `--repository`)	✅ (source is `--repository`, target in config profile)
`--init`	❌ (extra run of `init --copy-chunker-params`)	✅

`snapshots`

general	`restic`	`rustic`
summarize identical snapshots (like `+3`)	❌	✅
show summary information (sizes)	❌ (WIP)	✅

option	`restic`	`rustic`
snapshot filtering options	✅	✅
`--all`	❌	✅
`--compact`	✅	❌
`--group-by`	✅ (host/paths/tags)	✅ (host/label/paths/tags)
`--latest`	✅	❌
`--long`	❌	✅

`ls`

option	`restic`	`rustic`
snapshot filtering options for `latest`	✅	✅
`--glob`	❌	✅
`--glob-file`	❌	✅
`--human-readable`	✅	❌
`--iglob`	❌	✅
`--iglob-file`	❌	✅
`--long`	✅	✅
`--numeric-uid-gid`	❌	✅
`--summary`	❌	✅
`--recursive`	✅	✅

`diff`

general	`restic`	`rustic`
allow `latest`	❌	✅
diff with local files	❌	✅
`<snapshotID>:<subfolder>` syntax	✅	✅
`<snapshotID>:<subfolder>/file` syntax	❌	✅

option	`restic`	`rustic`
snapshot filtering options for `latest`	❌ (no `latest` support)	✅
`--glob`	❌	✅
`--glob-file`	❌	✅
`--iglob`	❌	✅
`--iglob-file`	❌	✅
`--metadata`	✅	✅
`--no-content`	❌	✅
exclude options for local files	❌ (no diff with local files)	✅

Installation

Official Binaries

Stable Releases

cargo-binstall

cargo binstall rustic-rs

Windows

Scoop

scoop install rustic

You can download the latest stable release versions of rustic from the rustic release page. These builds are considered stable and releases are made regularly in a controlled manner.

There’s both pre-compiled binaries for different platforms as well as the source code available for download. Just download and run the one matching your system.

Once downloaded, the official binaries can be updated in place using the rustic self-update command (needs rustic 0.3.1 or later):

$ rustic  self-update
Checking target-arch... x86_64-unknown-linux-musl
Checking current version... v0.3.0-dev
Checking latest released version... v0.3.1
New release found! v0.3.0-dev --> v0.3.1
New release is *NOT* compatible

rustic release status:
    * Current exe: "/usr/local/bin/rustic"
    * New exe release: "rustic-v0.3.1-x86_64-unknown-linux-musl.tar.gz"
    * New exe download url: "https://api.github.com/repos/rustic/rustic/releases/assets/75146490"

The new release will be downloaded/extracted and the existing binary will be replaced.
Do you want to continue? [Y/n] Y
Downloading...
[00:00:00] [========================================] 4.29MiB/4.29MiB (0s) Done
Extracting archive... Done
Replacing binary file... Done
Update status: `0.3.1`!

Note: Please be aware that the user executing the rustic self-update command must have the permission to replace the rustic binary.

Unstable Builds

Another option is to use the nightly builds for the main branch, available on the nightly download page. These too are pre-compiled and ready to run, and a new version is built every night from the main branch of various repositories.

From Source

Beware: This installs the latest development version, which might be unstable.

rustic is written in Rust and you need a current Rust version.

In order to build rustic from source, execute the following steps:

Github

cargo install --git https://github.com/rustic-rs/rustic.git rustic-rs

crates.io

You can also directly install the latest crate from crates.io.

cargo install rustic-rs

Cross-compile

You can easily cross-compile rustic for all supported platforms, make sure that the cross-compile toolchain is installed for your target. Then run the build for your chosen target like this

cargo build --target aarch64-unknown-linux-gnu --release

Nightly builds

Nightly builds of rustic’s, rustic_server’s, and rustic_scheduler’s main branch are available here for download.

WARNING: These builds are not guaranteed to be stable, and may contain bugs. Use at your own risk.

Verification

Minisign/Rsign2

Install

rsign2 with cargo install rsign2 or
minisign with scoop install minisign (on Windows, check other installation instructions here).

Run

rsign verify <filename>.tar.gz \
  -x <filename>.tar.gz.sig \
  -P RWSWSCEJEEacVeCy0va71hlrVtiW8YzMzOyJeso0Bfy/ZXq5OryWi/8T

PGP

Download our public key or copy and paste it from below:

wget https://github.com/rustic-rs/nightly/raw/main/pub/pgp.pub

Check the fingerprint:

12B7166D9FD59124416952E34018C5DE3BF8C081

against the output of: gpg --show-keys <PUBLIC_KEY_FILE>

Import the key with gpg --import <PUBLIC_KEY_FILE>

Verify the signature with gpg --verify <filename>.tar.gz.asc <filename>.tar.gz

The output should say “Good Signature”.

Note: We use the .asc extension for the files because .sig was already taken for supporting minisign used by cargo-binstall.

Status

Download matrix

Platform	rustic	rustic_scheduler	rustic_server
Linux x86_64 / gnu	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑
Linux x86_64 / musl (static)	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑
Linux i686 / gnu	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑
Linux aarch64 / gnu	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑
Linux armv7 / raspberry pi	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑
MacOS x86_64	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑
MacOS aarch64	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	n.a., #6
Windows x86_64 / msvc (exp)	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑
Windows x86_64 / gnu (exp)	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑	⏬ #️⃣ 🔑

Repository version	Minimum rustic version	Major new features
`1`	any version
`2`	>=0.2.0	Compression support

rustic user documentation