The local storage backend stores backups on the local filesystem. It’s ideal for external drives, NAS devices, or development/testing.
Configuration
Basic Setup
Initialize a repository with local storage:
cloudstic init -store local -store-path /path/to/backup
Environment Variables
CLOUDSTIC_STORE_PATH
string
default:"./backup_store"
Path to the backup directory
Examples
External Drive
Network Share
Environment Variables
# Initialize on an external drive
cloudstic init -store local -store-path /mnt/backup-drive/cloudstic
# Backup to the external drive
cloudstic backup -source local -source-path ~/Documents
# Mount a network share (example)
sudo mount -t cifs //nas.local/backup /mnt/nas
# Initialize on the network share
cloudstic init -store local -store-path /mnt/nas/cloudstic
# Backup
cloudstic backup -source local -source-path ~/Projects
# Set via environment variables
export CLOUDSTIC_STORE=local
export CLOUDSTIC_STORE_PATH=/backup/cloudstic
# Initialize (no flags needed)
cloudstic init
# Backup
cloudstic backup -source local -source-path ~/Data
Features
Atomic Writes
The local store uses atomic writes for safety:
- Data is written to a temporary file with
.tmp suffix
- The temporary file is renamed to the final path
- On POSIX systems, rename is atomic
This ensures backups are never corrupted by interrupted writes.
Directory Structure
The local store creates this structure:
backup_store/
├── chunk/
│ └── <sha256> # Raw data chunks
├── content/
│ └── <sha256> # Chunk manifests
├── filemeta/
│ └── <sha256> # File metadata
├── node/
│ └── <sha256> # HAMT nodes
├── snapshot/
│ └── <sha256> # Snapshots
├── index/
│ ├── latest # Latest snapshot pointer
│ ├── snapshots # Snapshot catalog
│ └── packs # Pack catalog (if packfiles enabled)
├── keys/
│ ├── 0-password # Password key slot
│ └── 1-recovery # Recovery key slot (optional)
└── config # Repository config
- Fast I/O: Direct filesystem access
- No network latency: Eliminates network round-trips
- Efficient deduplication: Fast local lookups
For networked filesystems (NFS, CIFS), performance depends on network speed and latency.
Best Practices
External Drives
NAS/Network Storage
Pros:
- Fast local backups
- No cloud costs
- Physical control
Considerations:
- Keep drive disconnected when not in use
- Store securely (encryption protects data)
- Test restore regularly
Pros:
- Centralized storage
- Always available
- Can back up multiple machines
Considerations:
- Network performance matters
- Ensure NAS has redundancy (RAID)
- Consider off-site backup copy
Permissions
Ensure the backup directory has appropriate permissions:
# Create with restricted permissions
mkdir -p /backup/cloudstic
chmod 700 /backup/cloudstic
# Initialize
cloudstic init -store local -store-path /backup/cloudstic
Monitoring Disk Space
Monitor available space to avoid backup failures:
# Check disk usage
df -h /backup/cloudstic
# Check repository size
du -sh /backup/cloudstic
cloudstic prune regularly to reclaim space from deleted snapshots.
Troubleshooting
Permission Denied
If you see “permission denied” errors:
# Check directory ownership
ls -la /path/to/backup
# Fix ownership if needed
sudo chown -R $USER:$USER /path/to/backup
Disk Full
If the backup fails with “no space left on device”:
- Check available space:
df -h /backup
- Run prune to reclaim space:
cloudstic prune
- Consider forgetting old snapshots:
cloudstic forget --keep-last 10 --prune
Network Mount Issues
For network mounts that disconnect:
# Use autofs or systemd automount for reliability
# Example /etc/fstab entry:
//nas.local/backup /mnt/nas cifs credentials=/etc/nas.creds,uid=1000,gid=1000 0 0