Restic Deployment & Usage Guide

1. Prerequisites

System Requirements

• OS: Linux, macOS, Windows, FreeBSD, or OpenBSD
• Architecture: AMD64, ARM64, ARM, or others supported by Go
• Go: Version 1.21 or later (only for building from source)
• Memory: Minimum 256MB RAM (varies by repository size and concurrency)

Backend Prerequisites

Depending on your backup destination:

Windows-Specific

• For Volume Shadow Copy Service (VSS) snapshots: Administrator privileges
• PowerShell or Command Prompt with elevated rights

2. Installation

Option A: Pre-built Binaries (Recommended)

Download from GitHub Releases:

# Linux/macOS
wget https://github.com/restic/restic/releases/download/v0.16.0/restic_0.16.0_linux_amd64.bz2
bunzip2 restic_0.16.0_linux_amd64.bz2
chmod +x restic_0.16.0_linux_amd64
sudo mv restic_0.16.0_linux_amd64 /usr/local/bin/restic

# Verify
restic version

Option B: Build from Source

# Clone repository
git clone https://github.com/restic/restic.git
cd restic

# Build (requires Go 1.21+)
go build -o restic ./cmd/restic

# Run directly
./restic version

# Install system-wide (optional)
sudo cp restic /usr/local/bin/

Option C: Package Managers

# macOS (Homebrew)
brew install restic

# Debian/Ubuntu
sudo apt-get install restic

# Windows (Scoop)
scoop install restic

# Windows (Chocolatey)
choco install restic

3. Configuration

Restic uses environment variables for configuration. Create a secure environment file (e.g., /etc/restic/env or ~/.restic/env):

Essential Variables

# Repository location (required)
# Local: /path/to/repo
# SFTP: sftp:user@host:/path/to/repo
# S3: s3:s3.amazonaws.com/bucket_name
# REST: rest:http://host:8000/
export RESTIC_REPOSITORY="s3:s3.amazonaws.com/my-backup-bucket"

# Password/Encryption key (required)
# Option 1: Direct password (less secure)
export RESTIC_PASSWORD="your-secure-password-here"

# Option 2: Path to password file (recommended)
export RESTIC_PASSWORD_FILE="/etc/restic/password.txt"

# Option 3: Command to retrieve password (for secret managers)
export RESTIC_PASSWORD_COMMAND="pass show backups/restic"

# Cache directory (optional, defaults to ~/.cache/restic)
export RESTIC_CACHE_DIR="/var/cache/restic"

Backend-Specific Configuration

Amazon S3 / MinIO:

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="secret..."
export AWS_DEFAULT_REGION="us-east-1"
# For MinIO:
# export AWS_ENDPOINT_URL="http://minio-server:9000"

Backblaze B2:

export B2_ACCOUNT_ID="your-account-id"
export B2_ACCOUNT_KEY="your-account-key"

Azure Blob Storage:

export AZURE_ACCOUNT_NAME="myaccount"
export AZURE_ACCOUNT_KEY="primary-or-secondary-access-key"

SFTP:

# Uses standard SSH keys (~/.ssh/id_rsa) or SSH agent
# For custom key:
export RESTIC_REPOSITORY="sftp:user@host:/backups/repo"
# SSH options via ~/.ssh/config or:
export RESTIC_SFTP_COMMAND="ssh -i /path/to/key user@host -s sftp"

Initialize Repository

# Initialize (one-time setup)
restic init

# With specific options
restic init --repo /mnt/backup/repo --copy-chunker-parameters

Critical: Store the password securely. Losing the password means irrecoverable data loss.

4. Build & Run

Development Build

cd restic

# Standard build
go build -o restic-dev ./cmd/restic

# With debug symbols
go build -gcflags="all=-N -l" -o restic-debug ./cmd/restic

# Run tests
go test ./...

# Run specific package tests
go test ./internal/archiver/...

Local Execution

# Backup current directory
./restic-dev backup .

# Backup with exclusions
./restic-dev backup ~/documents --exclude="*.tmp" --exclude-file=~/excludes.txt

# Compression modes (auto, off, max, fastest, better)
./restic-dev backup ~/data --compression=max

# Custom pack size (4MB to 128MB, default 16MB)
./restic-dev backup ~/data --pack-size=64

Exit Codes

Reference for scripting:

• 0: Success
• 1: Fatal error (no snapshot created)
• 3: Some source data could not be read (incomplete snapshot)
• 10: Repository does not exist
• 11: Repository is locked (concurrent access)
• 12: Wrong password

5. Deployment

Automated Backup Strategy

Systemd Timer (Linux)

Create /etc/systemd/system/restic-backup.service:

[Unit]
Description=Restic backup
After=network.target

[Service]
Type=oneshot
EnvironmentFile=/etc/restic/env
ExecStart=/usr/local/bin/restic backup /home /etc /var/www --exclude-file=/etc/restic/excludes.txt
ExecStartPost=/usr/local/bin/restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune
Restart=on-failure

Create /etc/systemd/system/restic-backup.timer:

[Unit]
Description=Daily restic backup

[Timer]
OnCalendar=daily
Persistent=true
RandomizedDelaySec=3600

[Install]
WantedBy=timers.target

Enable:

sudo systemctl enable --now restic-backup.timer

Cron (Universal)

# Edit crontab
crontab -e

# Daily at 2 AM with logging
0 2 * * * /usr/local/bin/restic backup /data --exclude-file=/etc/restic/excludes.txt >> /var/log/restic.log 2>&1 || echo "Backup failed" | mail -s "Backup Alert" admin@example.com

# Weekly cleanup
0 3 * * 0 /usr/local/bin/restic forget --keep-weekly 4 --keep-monthly 12 --prune

Deploying REST Server Backend

For centralized backup storage, deploy the restic REST server:

# Docker deployment
docker run -d -p 8000:8000 \
  -v /srv/backups:/data \
  -e OPTIONS="--htpasswd-file /data/.htpasswd --append-only" \
  --name rest-server \
  restic/rest-server

# Initialize client against server
export RESTIC_REPOSITORY="rest:http://user:pass@backup-server:8000/"
restic init

Production Considerations

Repository Maintenance:

# Check repository integrity (run periodically)
restic check

# Read data verification (slow but thorough)
restic check --read-data

# Cleanup old snapshots (retention policy)
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --keep-yearly 3 --prune

# Unlock if interrupted
restic unlock

Monitoring:

# JSON output for monitoring systems
restic backup /data --json

# Stats
restic stats
restic snapshots

Windows Service: Use NSSM or similar to run restic as a Windows service with VSS snapshots:

# Requires admin privileges for VSS
restic backup C:\Users\Documents --use-fs-snapshot

6. Troubleshooting

Authentication & Access

Error: Fatal: wrong password or no key found

• Verify RESTIC_PASSWORD or RESTIC_PASSWORD_FILE points to correct credential
• Check exit code 12

Error: repository is already locked (Exit code 11)

# Check for stale locks
restic list locks

# Remove stale lock (if no other restic process is running)
restic unlock
# Force unlock (dangerous - only if certain no other operations)
restic unlock --remove-all

Windows VSS Errors (E_ACCESSDENIED, 0x80070005)

• Run Command Prompt or PowerShell as Administrator
• Verify Volume Shadow Copy service is running
• Check Windows Event Logs for VSS errors

Backend Issues

S3: NoCredentialProviders

• Verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are exported
• Check IAM permissions (s3:GetObject, s3:PutObject, s3:DeleteObject, s3:ListBucket)

SFTP: Connection refused

• Verify SSH key permissions (chmod 600)
• Test connection: ssh user@host
• Use -v flag for verbose SSH debugging

Repository Not Found (Exit code 10)

# Verify repository path
echo $RESTIC_REPOSITORY
# For S3: Ensure bucket exists or use `restic init` first

Performance & Memory

High Memory Usage

• Reduce concurrency: --limit-upload=1000 (KB/s)
• Use smaller pack sizes: --pack-size=4
• Set GOGC=20 to trigger garbage collection more aggressively

Slow Backups

• Check compression level: --compression=fastest or --compression=off
• Verify network bandwidth to backend
• Use local cache: ensure RESTIC_CACHE_DIR has fast I/O

Dedupe Not Working

• Expected behavior: first backup is full, subsequent are incremental
• Verify files aren't changing (modification times, permissions)

Data Recovery

Restore Specific File

# List snapshots
restic snapshots

# Restore single file
restic restore 40dc1520 --target /tmp/restore --include "/path/to/file.txt"

# Restore with overwrite control
restic restore latest --target / --overwrite=if-changed

Mount Repository (Linux/macOS)

# Requires FUSE
mkdir /mnt/restic
restic mount /mnt/restic
# Browse snapshots at /mnt/restic/hosts/*/snapshots/

Repository Corruption

# Repair index
restic rebuild-index

# Recover raw data if repository is damaged
restic restore --verify-latest

Debug Mode

# Enable debug logging
export DEBUG_LOG=/tmp/restic-debug.log
restic backup /data