RepositoryOptions configures how rustic accesses and interacts with a repository, including caching, warm-up strategies, and performance tuning.
Type Definition
#[derive(Clone, Debug, Default, Deserialize, Serialize, Setters)]
pub struct RepositoryOptions {
pub no_cache: bool,
pub cache_dir: Option<PathBuf>,
pub warm_up: bool,
pub warm_up_command: Option<CommandInput>,
pub warm_up_wait_command: Option<CommandInput>,
pub warm_up_wait: Option<SignedDuration>,
pub warm_up_batch: Option<usize>,
}
Fields
no_cache
Disable the local cache entirely. When true, rustic will not cache any repository data locally, which may significantly impact performance but reduces disk usage.
RUSTIC_NO_CACHE
cache_dir
cache_dir
Option<PathBuf>
default:"None"
Custom cache directory path. If not set, rustic uses the platform’s standard cache location. Conflicts with no_cache.
RUSTIC_CACHE_DIR
warm_up
Enable automatic warm-up of data pack files. When true, rustic requests pack files without processing them to trigger caching in cloud storage systems or similar.
- Cold storage backends (e.g., AWS S3 Glacier)
- CDN or cache-based storage systems
- Improving restore performance
warm_up_command
warm_up_command
Option<CommandInput>
default:"None"
External command to execute for warming up pack files. The command string should include %id as a placeholder for the pack ID.
warm_up.
Example:
use rustic_core::RepositoryOptions;
let opts = RepositoryOptions::default()
.warm_up_command("aws s3api restore-object --bucket mybucket --key packs/%id".into());
warm_up_wait_command
warm_up_wait_command
Option<CommandInput>
default:"None"
Command to execute and wait for before considering warm-up complete. Also uses %id placeholder.
warm_up_wait
warm_up_wait
Option<SignedDuration>
default:"None"
Duration to wait after warm-up completes. Useful when storage systems need time to move data from cold to hot tier.
use rustic_core::RepositoryOptions;
use jiff::SignedDuration;
let opts = RepositoryOptions::default()
.warm_up_wait(SignedDuration::from_mins(10));
warm_up_batch
warm_up_batch
Option<usize>
default:"None"
Number of pack IDs to batch together when invoking warm-up commands. Higher values reduce the number of command invocations but may exceed command-line length limits.
Builder Methods
Thanks to the Setters derive macro, RepositoryOptions provides fluent builder methods:
pub fn no_cache(self, value: bool) -> Self
pub fn cache_dir(self, value: impl Into<Option<PathBuf>>) -> Self
pub fn warm_up(self, value: bool) -> Self
pub fn warm_up_command(self, value: impl Into<Option<CommandInput>>) -> Self
pub fn warm_up_wait_command(self, value: impl Into<Option<CommandInput>>) -> Self
pub fn warm_up_wait(self, value: impl Into<Option<SignedDuration>>) -> Self
pub fn warm_up_batch(self, value: impl Into<Option<usize>>) -> Self
Self for method chaining.
Usage Examples
Basic Usage
use rustic_core::{Repository, RepositoryOptions};
use rustic_backend::BackendOptions;
let backends = BackendOptions::default()
.repository("/tmp/repo")
.to_backends()?;
let opts = RepositoryOptions::default();
let repo = Repository::new(&opts, &backends)?;
Disable Cache
let opts = RepositoryOptions::default()
.no_cache(true);
let repo = Repository::new(&opts, &backends)?;
Custom Cache Directory
use std::path::PathBuf;
let opts = RepositoryOptions::default()
.cache_dir(PathBuf::from("/custom/cache/path"));
let repo = Repository::new(&opts, &backends)?;
Enable Warm-Up
let opts = RepositoryOptions::default()
.warm_up(true);
let repo = Repository::new(&opts, &backends)?;
Cold Storage Configuration
For AWS S3 Glacier or similar cold storage:
use rustic_core::RepositoryOptions;
use jiff::SignedDuration;
let opts = RepositoryOptions::default()
.warm_up_command(
"aws s3api restore-object --bucket mybucket --key packs/%id --restore-request Tier=Expedited"
)
.warm_up_wait(SignedDuration::from_hours(1))
.warm_up_batch(10);
let repo = Repository::new(&opts, &backends)?;
Hot/Cold Repository Setup
use rustic_backend::BackendOptions;
use rustic_core::RepositoryOptions;
// Set up hot and cold backends
let backends = BackendOptions::default()
.repository("/cold/storage/path") // Cold storage
.repo_hot("/hot/cache/path") // Fast access storage
.to_backends()?;
let opts = RepositoryOptions::default();
let repo = Repository::new(&opts, &backends)?;
Command-Line Integration
With the clap feature enabled, RepositoryOptions can be parsed from command-line arguments:
use clap::Parser;
use rustic_core::RepositoryOptions;
#[derive(Parser)]
struct Cli {
#[clap(flatten)]
repo_opts: RepositoryOptions,
}
let cli = Cli::parse();
let repo = Repository::new(&cli.repo_opts, &backends)?;
--no-cache - Disable cache--cache-dir <PATH> - Set cache directory--warm-up - Enable warm-up--warm-up-command <CMD> - Set warm-up command--warm-up-wait-command <CMD> - Set warm-up wait command--warm-up-wait <DURATION> - Set warm-up wait duration--warm-up-batch <SIZE> - Set warm-up batch size
Configuration File
With the merge feature, options can be loaded from configuration files:
use rustic_core::RepositoryOptions;
use serde::Deserialize;
// TOML configuration file:
// [repository]
// no-cache = false
// cache-dir = "/custom/cache"
// warm-up = true
// warm-up-batch = 5
let opts: RepositoryOptions = toml::from_str(config_content)?;
Cache Impact
- With cache (default): Faster repeated access, uses local disk space
- Without cache (
no_cache = true): Slower, no local disk usage
- Custom cache: Useful for controlling cache location (e.g., SSD vs HDD)
Warm-Up Strategies
Simple warm-up (warm_up = true):
RepositoryOptions::default().warm_up(true)
- Requests files without processing
- Good for CDN/cache systems
Command-based warm-up:
RepositoryOptions::default()
.warm_up_command("mycommand %id")
.warm_up_batch(10)
- Custom logic per storage system
- Batch processing reduces overhead
With wait time:
RepositoryOptions::default()
.warm_up(true)
.warm_up_wait(SignedDuration::from_mins(5))
- Allows storage tier migration
- Essential for cold storage (Glacier, Archive tier)
Best Practices
-
Use defaults for local storage:
RepositoryOptions::default()
-
Disable cache for single-use operations:
RepositoryOptions::default().no_cache(true)
-
Configure warm-up for cloud storage:
RepositoryOptions::default()
.warm_up(true)
.warm_up_wait(SignedDuration::from_mins(1))
-
Use custom cache for performance tuning:
RepositoryOptions::default()
.cache_dir("/fast/ssd/cache")
See Also
