Logo

Quickstart

This guide will get you up and running with ZeroFS in minutes. We'll cover installation, basic configuration, and mounting your first S3-backed filesystem. By the end, you'll have a fully functional filesystem that stores data in S3 while feeling like local storage.

Before you begin, ensure you have access to an S3-compatible storage service and the necessary credentials (access key ID and secret access key). For quick testing without external storage, you can use file:/// URLs to store data locally.

Installation

ZeroFS is distributed as a single static binary. Choose your installation method:

# Download the latest release for your platform
# These binaries are optimized with Profile-Guided Optimization (PGO) for best performance
curl -LO https://github.com/Barre/ZeroFS/releases/latest/download/zerofs-pgo-multiplatform.tar.gz

# Extract the archive
tar -xzf zerofs-multiplatform.tar.gz

# Make the binary executable and move it to PATH
chmod +x zerofs-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)
sudo mv zerofs-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) /usr/local/bin/zerofs

# Clean up the archive
rm zerofs-multiplatform.tar.gz

Configuration

Create a configuration file for ZeroFS:

# Initialize a config file
zerofs init

# This creates a template you can customize

Edit the configuration file with your settings:

[cache]
dir = "/var/cache/zerofs"
disk_size_gb = 10.0
memory_size_gb = 2.0    # Optional memory cache

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

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

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

See all configuration options

Start ZeroFS

Now start ZeroFS with your configuration:

# Start ZeroFS with configuration file
zerofs run --config zerofs.toml

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

Mount the Filesystem

With ZeroFS running, mount it using standard NFS tools. Linux users can also use 9P for better performance:

# Create mount point
sudo mkdir -p /mnt/zerofs

# Mount ZeroFS
sudo mount -t nfs -o async,nolocks,vers=3,tcp,port=2049,mountport=2049 127.0.0.1:/ /mnt/zerofs

Using NBD Block Devices

If you enabled NBD support, you can create and access block devices dynamically:

# First, ensure NBD is configured in your TOML:
# [servers.nbd]
# addresses = ["127.0.0.1:10809"]

# Mount the filesystem (if not already mounted)
sudo mount -t nfs -o vers=3,async,nolock 127.0.0.1:/ /mnt/zerofs

# Create a block device file
sudo mkdir -p /mnt/zerofs/.nbd
sudo truncate -s 10G /mnt/zerofs/.nbd/my-device

# Install nbd-client if needed
sudo apt-get install nbd-client  # Debian/Ubuntu
sudo yum install nbd              # RHEL/CentOS

# Connect to the NBD device
sudo nbd-client 127.0.0.1 10809 /dev/nbd0 -N my-device

# Create filesystem
sudo mkfs.ext4 /dev/nbd0

# Mount the block device
sudo mkdir -p /mnt/nbd0
sudo mount /dev/nbd0 /mnt/nbd0

Learn more about NBD devices

Verify It's Working

Test your new filesystem:

# Check mount
df -h /mnt/zerofs

# Create a test file
echo "Hello from ZeroFS!" > /mnt/zerofs/test.txt

# Read it back
cat /mnt/zerofs/test.txt

# Check file metadata
ls -la /mnt/zerofs/

Learn about NFS operations

What's Next?

Congratulations! You now have a fully functional filesystem backed by S3. Here are some next steps:

Was this page helpful?