Local Filesystem Storage

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:/path/to/backup

The directory will be created automatically if it doesn’t exist.

Environment Variables

string

default:"local:./backup_store"

Storage backend URI. Use local:<path> to specify the backup directory path.

Examples

External Drive
Network Share
Environment Variables

# Initialize on an external drive
cloudstic init -store local:/mnt/backup-drive/cloudstic

# Backup to the external drive
cloudstic backup -source local:~/Documents

# Mount a network share (example)
sudo mount -t cifs //nas.local/backup /mnt/nas

# Initialize on the network share
cloudstic init -store local:/mnt/nas/cloudstic

# Backup
cloudstic backup -source local:~/Projects

# Set via environment variables
export CLOUDSTIC_STORE=local:/backup/cloudstic

# Initialize (no flags needed)
cloudstic init

# Backup
cloudstic backup -source local:~/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

Performance

Local storage offers the best performance:

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

Backup Media

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

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:/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

Use 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

Backup Command

Create backups with local storage

Prune Command

Reclaim disk space

S3 Storage

Use cloud storage instead

SFTP Storage

Use remote SSH storage

Get Started

Core Concepts

Sources

Storage Backends

Guides

Local Filesystem Storage

Configuration

Basic Setup

Environment Variables

Examples

Features

Atomic Writes

Directory Structure

Performance

Best Practices

Backup Media

Permissions

Monitoring Disk Space

Troubleshooting

Permission Denied

Disk Full

Network Mount Issues

Backup Command

Prune Command

S3 Storage

SFTP Storage

​Configuration

​Basic Setup

​Environment Variables

​Examples

​Features

​Atomic Writes

​Directory Structure

​Performance

​Best Practices

​Backup Media

​Permissions

​Monitoring Disk Space

​Troubleshooting

​Permission Denied

​Disk Full

​Network Mount Issues

​Related Resources

Backup Command

Prune Command

S3 Storage

SFTP Storage

Configuration

Basic Setup

Environment Variables

Examples

Features

Atomic Writes

Directory Structure

Performance

Best Practices

Backup Media

Permissions

Monitoring Disk Space

Troubleshooting

Permission Denied

Disk Full

Network Mount Issues

Related Resources