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

A more detailed comparison can be found in the comparison table.

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.

More details

rustic doesn’t support single repositories/buckets which have objects that can be in different “states” (something like this is not contained in the restic REST protocol; rclone therefore isn’t able to provide this kind of information).

So, to use S3 glacier, you should use 2 buckets: A hot one which is always accessible and a cold one where all object should be transitioned/transferred directly to Glacier when they are stored. The “hot” objects are then in fact stored in both buckets, but this shouldn’t be much overhead as it is only metadata which usually is less than 1% of the repo size. (The side effect is that the cold repo contains a full restic-compatible repository; if you warm up it completely, you can use it a standard repository within rustic and even restic).

TL;DR: I think you have to do the following:

To store data (e.g. init or backup command):

Create a regular bucket and use it as repo-hot
Create a bucket for cold and configure it to store data directly in Glacier (don’t know if you can configure this in rclone or in AWS)

To retrieve data (e.g. restore):

configure warm-up-command such that objects from the cold buckets are restored, see e.g https://docs.aws.amazon.com/AmazonS3/latest/userguide/restoring-objects.html. That is, the config file should look have a line like warm-up-command = 'aws s3api restore-object --bucket BUCKET --key path/data/%id --restore-request '{"Days":25,"GlacierJobParameters":{"Tier":"Standard"}}' ' (may need some adaption)
configure a suitable warm-up-wait to ensure that the data is warmed up and can be accessed after that
Note: All commands which need to read cold data now will warm this data up and wait for the given time before processing the data

removing cold data (prune) This actually should work out of the box, but note that by default prune doesn’t repack any cold pack file; instead it keeps them until the last blob within is no longer used.

to do more repacking, have a look at the repack-cacheable option which does allow to repack cold pack files.
Use the keep-pack option if you have some minimum holding duration, i.e. if you would get charged if you remove objects too early. This option ensures that only pack files older than the given time will be removed.

Once you get a working configuration, please share it in the main repository so other users can use it as well!

Are all operations lock free?

Yes, all operations are designed lock-free. This means all commands can run parallel. This is especially true for multiple backup runs and backup runs parallel to prune. However, make sure that each individual backup run won’t take longer as the --keep-delete option (default: 23h) if you run prune parallel to backup - and that you don’t use --instant-delete.

Of course, any read-only command also safely runs parallel to any other command.

Multiple parallel forget or prune runs are designed to work, too. But I have to admit that we have not tested this in detail so far. Because of this and other reasons (like ACLs to set up and scheduling) I would recommend to schedule forget and prune for the whole repository using a single host to do so. However feedback on this with multiple parallel runs is highly appreciated.

There is one general caveat: Error handling is not perfect yet in rustic and we may run into cases where parallel runs may throw errors. E.g. the combination forget/check may lead to check trying to load just-removed snapshots. Or forget/forget may want to remove a just-removed snapshots which then fails. These are however all cases which should not affect the general repository consistency. If you encounter such an error handling problem, please report it in our issue tracker!

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.

File exclusion for Windows Defender

If you are on Windows and you are using Windows Defender, you might want to exclude the rustic.exe binary from being scanned to speed up all operations. This can be done by adding an exclusion in the Windows Security settings. Here is how you can do it on the command line (elevated):

Add-MpPreference -ExclusionProcess "rustic.exe"

Pass environment variables to RCLONE

Environment variables are set by rustic before calling a subcommand, e.g. rclone or commands defined in the repository options. For example, to set the RCLONE_FAST_LIST environment variable you add the following to your <profile>.toml:

[global.env]
RCLONE_FAST_LIST = "true"

Make sure to check the latest config documentation for the correct syntax.

Comparison between `rustic` and `restic`

Note that we regularly update this document to compare the latest versions of rustic and restic. Currently, we compare restic 0.17.3 with rustic 0.9.5.

General differences

	`restic`	`rustic`
programming language	Go	Rust
development philosopy	conservative with changes	moving fast, add new features early
test coverage	✅	❌ (42% in rustic_core)
returns error code	✅	(✅) only 0 or 1; not all commands support it
available as library	❌	✅ rustic_core

Core features introduced by rustic

rustic’s goal is to implement all functionality/features restic offers - and make some of them even better. It also implements new features which are missing in restic.

This section is an advertisement of the most important features uniquely introduced by rustic. Some have been already adopted by restic.

feature	`restic`	`rustic`
cold storage support	❌ (may work in special cases)	✅ (full support including warm-up of needed data)
config profile support	❌ (wrapper tools available)	✅
lock-free	❌ (roadmap: 0.19)	✅ (lock-free operations, two-phase pruning)
in-place restore	✅	✅
additional snapshot information	(✅) (partly added)	✅ (see below for details)
in-repo config	❌	✅ (see below for details)
`<snapshot>:<path>` syntax	✅ (most commands)	✅
new command: `merge`	❌	✅
new command: `webdav`	❌	✅
`diff` with local files	❌	✅
`backup` can use .gitignore	❌ (roadmap: 0.19)	✅
`backup` multiple snapshots at once	❌	✅
`check` uses existing cache	❌ (roadmap: 0.18)	✅
show file history	❌	✅ (`rustic find --path`)
more snapshot filter options	❌	✅ (see below for details)
allow to log to file	❌	✅
interactive mode (TUI)	❌	✅
log verbosity	`-v` or `--quiet`	`--log-level`

Supported 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`) (see here)
`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`	✅	✅ (linux only)
`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,…)	✅	✅
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)
`--insecure-no-password`	✅	✅ (empty passwords work without extra option)
`--insecure-tls`	✅	❌
`--json`	✅	✅
`--key-hint`	✅	❌
`--limit-download`	✅	(✅) (for opendal option `trottle`)
`--limit-upload`	✅	(✅) (for opendal option `trottle`)
`--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 exact pathlists	❌	✅ `--filter-paths-exact`
by tags	✅ `--tags`	✅ `--filter-tags`
by exact tagists	❌	✅ `--filter-tags-exact`
by date/time	❌	✅ `--filter-before`, `filter-after`
by size	❌	✅ `--filter-size`
by size added to repo	❌	✅ `--filter-size-added`
custom Rhai	❌	✅ `--filter-fn` (using Rhai)
custom `jq` syntax	❌	✅ `--filter-jq`

Comparison of important commands

`init`

option	`restic`	`rustic`
`--copy-chunker-params`	✅	(not needed, use `copy --init`)
`--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 create multiple snapshot in single run	❌	✅
allow to backup relative paths	(✅) full path in snapshots	✅

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)	✅ (but 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-if-unchanged`	✅	✅ `--skip-identical-parent`
`--stdin`	✅	✅ (use `-` as backup source)
`--stdin-filename`	✅	✅
`--stdin-from-command`	✅	✅
`--tag`	✅	✅
`--time`	✅	✅
`--with-atime`	✅	✅

`restore`

general	`restic`	`rustic`
scan and use already existing files	✅	✅
resumable restore	✅	✅
restore hard links	✅	❌
`<snapshotID>:<subfolder>` syntax	✅	✅
`<snapshotID>:<subfolder>/file` syntax	❌	✅
dry run support	✅	✅

option	`restic`	`rustic`
filtering options for `latest`	✅	✅
`--delete`	✅	✅
`--exclude`	✅	✅ `--glob`
`--iexclude`	✅	✅ `--iglob`
`--iinclude`	✅	✅ `--iglob`
`--include`	✅	✅ `--glob`
`--no-ownership`	❌	✅
`--numeric-id`	❌	✅
`--overwrite`	✅	❌ (missing functionality: if-newer, never)
`--sparse`	✅	❌
`--target`	✅	✅ (give target as second CLI argument)
`--verify`	✅	❌ (but `diff` can be used to verify after)
`--verify-existing`	✅ `--overwrite always`	✅

`dump`

general	`restic`	`rustic`
dump files	✅	✅
dump dirs	✅	✅
allow auto-detection of used format	❌	✅

option	`restic`	`rustic`
snapshot filtering options for `latest`	✅	✅
`--archive`	✅ (tar,zip)	✅ (tar,targz,zip,content,auto)
`--target`	✅	✅ `--file`

`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-minutely`	❌	✅
`--keep-hourly`	✅	✅
`--keep-daily`	✅	✅
`--keep-daily`	✅	✅
`--keep-weekly`	✅	✅
`--keep-monthly`	✅	✅
`--keep-quarter-yearly`	❌	✅
`--keep-half-yearly`	❌	✅
`--keep-yearly`	✅	✅
`--keep-within`	✅	✅
`--keep-within-minutely`	❌	✅
`--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`	✅	✅
`--usafe-allow-remove-all`	✅	✅ `--keep-none`
`--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	✅	✅
(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	✅	✅
only check given snapshots	❌	✅
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)	✅	✅

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`	✅	✅

`find`

general	`restic`	`rustic`
group and sort snapshots by date before finding	❌	✅
summarize snapshots with identical result (like `+3`)	❌	✅
fast searching for given full paths	❌	✅

option	`restic`	`rustic`
`--all`	❌ (no summarizing)	✅
`--blob`	✅	❌
`--glob`	✅ (give patterns as args)	✅
`--group-by`	❌	✅
`--ignore-case`	✅	✅ (`--iglob`)
`--long`	✅	❌ (default: long output)
`--newest`	✅	✅ use `--filter-before`
`--numeric-uid-gid`	❌ (default: numeric ids)	✅
`--oldest`	✅	✅ use `--filter-after`
`--pack`	✅	❌
`--path` (filter snapshots)	✅	✅ `--filter-path`
`--path` (full path to search)	❌	✅
`--show-pack-id`	✅	❌
`--show-misses`	❌	✅
`--snapshot`	✅	✅ (give ids as args)
`--tag`	✅	✅ `--filter-tags`
`--tree`	✅	❌

`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)	✅

External Links

simple comparison of borg, restic and rustic blogpost.

Breaking Changes

This document lists all user facing breaking changes in rustic and provides guidance on how to migrate from one version to another.

0.9.0

Configuration File

Using String in `password-command` and `warm-up-command`

Using a String for password-command or warm-up-command have been re-allowed.

Note: The former version to give the command in an array is no longer supported. Instead of

password-command = ["echo", "password"]

please use either of

password-command = "echo password"
password-command = { command = "echo", args = ["password"] }

Copy Command

Targets for the copy command must now be given by using existing rustic config profile(s).

[copy]
targets = ["full", "rustic"]

Key Naming Conventions

Consistently apply singular and plural naming conventions for keys in the configuration file that accept an array of values. This change affects the following keys:

For [global]:

use-profile-> use-profiles in config profile

For [snapshot-filter] and [forget]:

filter-host -> filter-hosts in config profile
filter-label -> filter-labels in config profile

For [backup]:

glob -> globs in config profile
iglob -> iglobs in config profile
glob-file -> glob-files in config profile
iglob-file -> iglob-files in config profile
custom-ignore-file -> custom-ignore-files in config profile
tag-> tags in config profile
source -> sources in config profile
[[backup.sources]] -> [[backup.snapshots]] in config profile

For [forget]:

keep-tags -> now only array
keep-ids -> now only array

Update your configuration file accordingly, changing the key names from singular to plural. For cases, where the key name was plural before, the value must be wrapped in an array.

So, for example

[[backup.sources]]
tag = "important"
source = "~/folder1 ~/folder2"

becomes:

[[backup.snapshots]]
tags = ["important"]
sources = ["~/folder1", "~/folder2"]

Filters being affected are:

filter-hosts = ["host2"] # Default: []
filter-labels = ["label1"] # Default: []

The changes can be also derived from the PR that introduced this change. So you may want to take a look at the PR for more details.

Error Codes

This page lists the error codes that rustic and rustic_core can return. The error codes are grouped by the module that returns them.

`rustic_core`

C001 (Cryptography): Data decryption failed, MAC check failed.
C002 (Password): The password that has been entered, seems to be incorrect. No suitable key found for the given password. Please check your password and try again.
C003 (Verification): Verification failed: After decrypting and decompressing

C001

Data decryption failed, MAC check failed.

Possible Causes

The data has been corrupted.
The data has been tampered with.

Solutions

Restore the data from a backup.
If the data is still available, try to decrypt it again.

C002

The password that has been entered, seems to be incorrect. No suitable key found for the given password. Please check your password and try again.

Possible Causes

The password has been entered incorrectly.
The password has been changed.
A Keyfile has been changed or removed.

Solutions

Check the password and try again.
If the password has been changed, use the new password.
If a Keyfile has been changed or removed, restore the Keyfile or use a different one.

C003

Verification failed: After decrypting and decompressing the data changed! The data may be corrupted.\nPlease check the backend for corruption and try again. You can also try to run rustic check --read-data to check for corruption. This may take a long time.

Possible Causes

The data has been corrupted.
The backend has a bug.

Solutions

Check the backend for corruption.
Try running rustic check --read-data to check for corruption.
If the error persists, please report the issue to the (backend) developers for further investigation.

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