Logo

Configuration Guide

ZeroFS uses TOML configuration files for all settings. This guide covers all available configuration options to help you configure ZeroFS for your specific use case.

Getting Started

Create a configuration file using the init command:

zerofs init

This creates a template configuration file that you can customize.

Configuration File Structure

Basic Configuration

# Cache configuration (required)
[cache]
dir = "/var/cache/zerofs"        # Directory for caching data
disk_size_gb = 10.0              # Maximum disk cache size in GB
memory_size_gb = 2.0             # Memory cache size in GB (optional)

# Storage configuration (required)
[storage]
url = "s3://bucket/path"         # Storage backend URL
encryption_password = "your-secure-password"  # Encryption password

Storage Backends

AWS S3

[storage]
url = "s3://my-bucket/zerofs-data"
encryption_password = "secure-password-here"

[aws]
access_key_id = "AKIAIOSFODNN7EXAMPLE"
secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
region = "us-east-1"              # Optional, defaults to us-east-1
endpoint = "https://s3.amazonaws.com"  # Optional for S3-compatible services
allow_http = false                # Set to true for non-HTTPS endpoints

For S3-compatible services like MinIO or Cloudflare R2, set the endpoint field to the service endpoint.

Azure Blob Storage

[storage]
url = "azure://container/path"
encryption_password = "secure-password-here"

[azure]
storage_account_name = "myaccount"
storage_account_key = "your-account-key"

Local Filesystem

[storage]
url = "file:///path/to/storage"
encryption_password = "secure-password-here"

# No additional backend configuration needed

Network Services

NFS Server

[servers.nfs]
addresses = ["0.0.0.0:2049"]  # Bind addresses (default: ["127.0.0.1:2049"])

9P Server

[servers.ninep]
addresses = ["0.0.0.0:5564"]  # Bind addresses (default: ["127.0.0.1:5564"])
socket = "/tmp/zerofs.sock"  # Unix socket path (optional)

NBD Server

[servers.nbd]
addresses = ["0.0.0.0:10809"]  # Bind addresses (default: ["127.0.0.1:10809"])
socket = "/tmp/zerofs-nbd.sock"  # Unix socket path (optional)

Complete Examples

Basic S3 Configuration

# /etc/zerofs/zerofs.toml
[cache]
dir = "/var/cache/zerofs"
disk_size_gb = 10.0

[storage]
url = "s3://my-bucket/zerofs-data"
encryption_password = "your-secure-password"

[aws]
access_key_id = "AKIAIOSFODNN7EXAMPLE"
secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

[servers.nfs]
addresses = ["0.0.0.0:2049"]

High-Performance Configuration

# /etc/zerofs/zerofs-performance.toml
[cache]
dir = "/nvme/zerofs-cache"    # Use fast NVMe storage
disk_size_gb = 100.0
memory_size_gb = 16.0          # Large memory cache

[storage]
url = "s3://high-performance-bucket/data"
encryption_password = "very-secure-password-here"

[aws]
access_key_id = "your-key"
secret_access_key = "your-secret"
region = "us-east-1"

[servers.nfs]
addresses = ["0.0.0.0:2049"]

[servers.nbd]
addresses = ["0.0.0.0:10809"]
socket = "/tmp/zerofs-nbd.sock"  # Unix socket for better local performance

S3-Compatible Services

[cache]
dir = "/var/cache/zerofs"
disk_size_gb = 10.0

[storage]
url = "s3://my-bucket/path"
encryption_password = "secure-password"

[aws]
access_key_id = "minioadmin"
secret_access_key = "minioadmin"
endpoint = "https://minio.example.com"
allow_http = true  # Set to true if using HTTP

Running ZeroFS

With Configuration File

# Start ZeroFS with a config file
zerofs run --config /etc/zerofs/zerofs.toml

# Or use the shorthand
zerofs run -c zerofs.toml

Password Management

To change the encryption password:

# Change password interactively
zerofs change-password --config zerofs.toml

# The command will:
# 1. Prompt for the new password
# 2. Update encrypted data with the new password
# 3. You'll need to update the config file manually

After changing the password, update the encryption_password field in your configuration file.

Environment Variable Substitution

Configuration values can reference environment variables using ${VAR} syntax:

[storage]
url = "s3://my-bucket/data"
encryption_password = "${ZEROFS_PASSWORD}"

[aws]
access_key_id = "${AWS_ACCESS_KEY_ID}"
secret_access_key = "${AWS_SECRET_ACCESS_KEY}"

This is useful for:

  • Keeping secrets out of configuration files
  • Using the same config across environments
  • Integration with secret management systems

System Integration

systemd Service

Create /etc/systemd/system/zerofs.service:

[Unit]
Description=ZeroFS S3 Filesystem
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/zerofs run --config /etc/zerofs/zerofs.toml
Restart=always
RestartSec=5
# Optional: Load environment variables for substitution
EnvironmentFile=-/etc/zerofs/zerofs.env

[Install]
WantedBy=multi-user.target

If using environment variable substitution, create /etc/zerofs/zerofs.env:

ZEROFS_PASSWORD=your-secure-password
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret

Docker

# Create config file
cat > zerofs.toml <<EOF
[cache]
dir = "/cache"
disk_size_gb = 10.0

[storage]
url = "s3://bucket/path"
encryption_password = "\${ZEROFS_PASSWORD}"

[aws]
access_key_id = "\${AWS_ACCESS_KEY_ID}"
secret_access_key = "\${AWS_SECRET_ACCESS_KEY}"

[servers.nfs]
addresses = ["0.0.0.0:2049"]
EOF

# Run container
docker run -d \
  -e ZEROFS_PASSWORD='secure-password' \
  -e AWS_ACCESS_KEY_ID='your-key' \
  -e AWS_SECRET_ACCESS_KEY='your-secret' \
  -v $(pwd)/zerofs.toml:/config/zerofs.toml:ro \
  -v /tmp/cache:/cache \
  -p 2049:2049 \
  ghcr.io/barre/zerofs:latest run --config /config/zerofs.toml

Configuration Best Practices

  1. Restrict permissions: chmod 600 /etc/zerofs/zerofs.toml
  2. Use environment variables for secrets: Keep passwords out of config files
  3. Version control: Track config files (without secrets) in git
  4. Use strong passwords: Generate with openssl rand -base64 32
  5. Separate environments: Use different config files for dev/staging/prod

Logging Configuration

Set log levels using the RUST_LOG environment variable:

# Set log level (default: error,zerofs=info)
export RUST_LOG='zerofs=debug'

# Common log levels:
# - error: Only errors
# - warn: Warnings and errors
# - info: Informational messages (default for zerofs)
# - debug: Detailed debugging
# - trace: Very detailed tracing

# Run with custom logging
RUST_LOG=zerofs=debug zerofs run -c zerofs.toml

Next Steps

Get started with ZeroFS

Troubleshooting guide

Was this page helpful?