Expand description
A library for deduplicated and encrypted backups, using repositories as specified in the restic repository design
.
§Overview
This section gives a brief overview of the primary types in this crate:
The main type is the Repository
type which describes a way to access a repository.
It can be in different states and allows - depending on the state - various high-level
actions to be performed on the repository like listing snapshots, backing up or restoring.
Besides this, various *Option
types exist which allow to specify options for accessing a
Repository
or for the methods used within a Repository
. Those types usually offer
setter methods as well as implement serde::Serialize
and serde::Deserialize
.
Other main types are typically result types obtained by Repository
methods which sometimes
are also needed as input for other Repository
method, like computing a PrunePlan
and
performing it.
There are also lower level data types which represent the stored repository format or
help accessing/writing it. Those are collected in the repofile
module. These types typically
implement serde::Serialize
and serde::Deserialize
.
§Example - initialize a repository, backup to it and get snapshots
use rustic_backend::BackendOptions;
use rustic_core::{BackupOptions, ConfigOptions, KeyOptions, PathList,
Repository, RepositoryOptions, SnapshotOptions
};
// Initialize the repository in a temporary dir
let repo_dir = tempfile::tempdir().unwrap();
let repo_opts = RepositoryOptions::default()
.password("test");
// Initialize Backends
let backends = BackendOptions::default()
.repository(repo_dir.path().to_str().unwrap())
.to_backends()
.unwrap();
let key_opts = KeyOptions::default();
let config_opts = ConfigOptions::default();
let _repo = Repository::new(&repo_opts, &backends.clone()).unwrap().init(&key_opts, &config_opts).unwrap();
// We could have used _repo directly, but open the repository again to show how to open it...
let repo = Repository::new(&repo_opts, &backends).unwrap().open().unwrap();
// Get all snapshots from the repository
let snaps = repo.get_all_snapshots().unwrap();
// Should be zero, as the repository has just been initialized
assert_eq!(snaps.len(), 0);
// Turn repository state to indexed (for backup):
let repo = repo.to_indexed_ids().unwrap();
// Pre-define the snapshot-to-backup
let snap = SnapshotOptions::default()
.add_tags("tag1,tag2").unwrap()
.to_snapshot().unwrap();
// Specify backup options and source
let backup_opts = BackupOptions::default();
let source = PathList::from_string("src").unwrap().sanitize().unwrap();
// run the backup and return the snapshot pointing to the backup'ed data.
let snap = repo.backup(&backup_opts, &source, snap).unwrap();
// assert_eq!(&snap.paths, ["src"]);
// Get all snapshots from the repository
let snaps = repo.get_all_snapshots().unwrap();
// Should now be 1, we just created a snapshot
assert_eq!(snaps.len(), 1);
assert_eq!(snaps[0], snap);
§Crate features
This crate exposes a few features for controlling dependency usage.
-
cli - Enables support for CLI features by enabling
clap
andmerge
features. This feature is disabled by default. -
clap - Enables a dependency on the
clap
crate and enables parsing from the commandline. This feature is disabled by default. -
merge - Enables support for merging multiple values into one, which enables the
conflate
dependency. This is needed for parsing commandline arguments and merging them into one (e.g.config
). This feature is disabled by default. -
webdav - Enables a dependency on the
dav-server
andfutures
crate. This enables us to run aWebDAV
server asynchronously on the commandline. This feature is disabled by default.
Modules§
- archiver 🔒
- backend 🔒
- Module for backend related functionality.
- blob 🔒
- chunker 🔒
- commands 🔒
- The commands that can be run by the CLI.
- crypto 🔒
- error 🔒
- Error types and Result module.
- id 🔒
- The
Id
type and related functions - index 🔒
- progress 🔒
- repofile
- Structs which are saved in JSON or binary format in the repository
- repository 🔒
- vfs
- Virtual File System support - allows to act on the repository like on a file system
Macros§
- define_
new_ id_ struct - Generate newtypes for
Id
s identifying Repository files - impl_
blobid - Generate newtypes for
Id
s identifying packed blobs - impl_
repofile - Generate newtypes for
Id
s identifying Repository files implementingRepoFile
- impl_
repoid - Generate newtypes for
Id
s identifying Repository files
Structs§
- Backup
Options - Options for the
backup
command. - BlobId
- An Id identifying a “blob”
- Blob
Info - Information about blobs within
repoinfo
- Check
Options - Options for the
check
command - Command
Input - A command to be called which can be given as CLI option as well as in config files
CommandInput
implements Serialize/Deserialize as well as FromStr. - Config
Options - Options for the
config
command, used to set repository-wide options - Copy
Snapshot - This struct enhances
[SnapshotFile]
with the attributerelevant
which indicates if the snapshot is relevant for copying. - DataId
- An Id identifying a concat! (“blob of type”, stringify! (BlobType::Data))
- File
DirStats - Statistics for files or directories
- Find
Matches - Results from
find_matching_nodes
- Find
Node - Results from
find_node_from_path
- Forget
Group - All snapshots of a group with group and forget information
- Forget
Groups - A newtype for
[Vec<ForgetGroup>]
- Forget
Snapshot - This struct enhances
[SnapshotFile]
with the attributeskeep
andreasons
which indicates if the snapshot should be kept and why. - Full
Index - A full index containing [
Id
]s and locations for tree and data blobs. - HexId
- An
Id
in hexadecimal format - Id
Id
is the hash id of an object.- Index
Infos - Index information from
repoinfo
- Indexed
Status - The indexed status of a repository
- Keep
Options - Options which snapshots should be kept. Used by the
forget
command. - KeyOptions
- Options for the
key
command. These are used when creating a new key. - Local
Destination - Local destination, used when restoring.
- Local
Source - A
LocalSource
is a source from local paths which is used to be read from (i.e. to backup it). - Local
Source Filter Options LocalSourceFilterOptions
allow to filter a local source by various criteria.- Local
Source Save Options LocalSourceSaveOptions
describes how entries from a local source will be saved in the repository.- LsOptions
- Options for listing the
Nodes
of aTree
- NoProgress
- A dummy struct which shows no progress but only logs titles and end of a progress.
- NoProgress
Bars - Don’t show progress bars, only log rudimentary progress information.
- Open
Status - Open Status: This repository is open, i.e. the password has been checked and the decryption key is available.
- Pack
Info - Information about packs within
repoinfo
- Parent
Options backup
subcommand Options how the backup command uses a parent snapshot.- Path
List PathList
is a rustic-internal list ofPathBuf
s. It is used in thecrate::Repository::backup
command.- Prune
Options - Options for the
prune
command - Prune
Plan - A plan what should be repacked or removed by a
prune
run - Prune
Stats - Statistics about a
PrunePlan
- Read
Source Entry - Information about an entry to be able to open it.
- Repair
Index Options - Options for the
repair index
command - Repair
Snapshots Options - Options for the
repair snapshots
command - Repo
File Info - Information about a repository files of a given
FileType
- Repo
File Infos - Information about repository files
- Repository
- A
Repository
allows all kind of actions to be performed. - Repository
Backends - The backends a repository can be initialized and operated on
- Repository
Options - Options for using and opening a
Repository
- Restore
Options - Options for the
restore
command - Restore
Plan - Information about what will be restored.
- Restore
Stats - Restore statistics
- Rustic
Error - Errors that can result from rustic.
- Snapshot
Group SnapshotGroup
specifies the group after a grouping usingSnapshotGroupCriterion
.- Snapshot
Group Criterion SnapshotGroupCriterion
determines how to group snapshots.- Snapshot
Options - Options for creating a new
SnapshotFile
structure for a new backup snapshot. - String
List StringList
is a rustic-internal list of Strings. It is used withinSnapshotFile
- TreeId
- An Id identifying a concat! (“blob of type”, stringify! (BlobType::Tree))
Enums§
- Command
Input Error Kind CommandInputErrorKind
describes the errors that can be returned from theCommandInput
- Error
Kind ErrorKind
describes the errors that can happen while executing a high-level command.- File
Type - Type for describing the kind of a file that can occur.
- Limit
Option - Enum to specify a size limit
- Read
Subset Option - Options to specify which subset of packs will be read
- Severity
- Severity of an error, ranging from informational to fatal.
- Status
- Status of an error, indicating whether it is permanent, temporary, or persistent.
Constants§
- ALL_
FILE_ TYPES - All
FileType
s which are located in separated directories
Traits§
- Indexed
Full - A repository which is indexed such that all blob information is fully contained in the index.
- Indexed
Ids - A repository which is indexed such that all tree blobs are contained in the index
and additionally the
Id
s of data blobs are also contained in the index. - Indexed
Tree - A repository which is indexed such that all tree blobs are contained in the index.
- Open
- A repository which is open, i.e. the password has been checked and the decryption key is available.
- Packed
Id - A marker trait for Ids which identify Blobs in pack files
- Progress
- Trait to report progress information for any rustic action which supports that.
- Progress
Bars - Trait to start progress information report progress information for any rustic action which supports that.
- Read
Backend - Trait for backends that can read.
- Read
Source - Trait for backends that can read from a source.
- Read
Source Open - Trait for backends that can read and open sources. This trait is implemented by all backends that can read data and open from a source.
- Write
Backend - Trait for backends that can write. This trait is implemented by all backends that can write data.
Functions§
- compression_
level_ range - The accepted range of compression levels.
- last_
modified_ node - An ordering function returning the latest node by mtime
- max_
compression_ level - The maximum compression level allowed by zstd
Type Aliases§
- Rustic
Result - Result type that is being returned from methods that can fail and thus have
RusticError
s.