💾 WolfDisk

Overview

WolfDisk is a distributed file system that provides easy-to-use shared and replicated storage across Linux machines. Mount a shared directory on any number of servers and have your data automatically synchronised. Built on the same proven consensus mechanisms as WolfScale.

🎬 Watch the overview video: WolfDisk on YouTube

Key Features

• FUSE-based — Mount as a regular Linux directory using FUSE3
• Content-addressed deduplication — Automatic deduplication via SHA256 hashing
• Chunk-based storage — Large files split into 4 MB chunks for efficient transfer and sync
• Leader / Follower / Client modes — Flexible node roles for any deployment
• Auto-discovery — UDP multicast for automatic peer discovery on LAN
• Automatic leader election & failover — Deterministic election with 2-second failover
• Delta sync — Incremental catchup — only missed changes are transferred
• S3-compatible REST API — Optional S3 gateway for any S3 client
• LZ4 compression — Compressed network replication
• Symlink support — Full POSIX symlink support
• IBM Power ready — Pure Rust dependencies, builds natively on ppc64le

Node Roles

Every WolfDisk node operates in one of four roles:

Quick Install

The interactive installer handles dependencies, compilation, configuration, and systemd service setup:

curl -sSL https://raw.githubusercontent.com/wolfsoftwaresystemsltd/WolfScale/main/wolfdisk/setup.sh | bash

The installer will prompt you for:

• Node ID — Unique identifier (defaults to hostname)
• Role — auto, leader, follower, or client
• Bind IP address — IP to listen on (auto-detected)
• Discovery method — Auto-discovery (UDP multicast), manual peers, or standalone
• Mount path — Where to mount the filesystem (default: /mnt/wolfdisk)

Manual Installation

Prerequisites

• Linux with FUSE3 support
• Rust toolchain (rustup)

Install Dependencies

# Ubuntu / Debian
sudo apt install libfuse3-dev fuse3

# Fedora / RHEL
sudo dnf install fuse3-devel fuse3

Build & Install

git clone https://github.com/wolfsoftwaresystemsltd/WolfScale.git
cd WolfScale/wolfdisk
cargo build --release
sudo cp target/release/wolfdisk /usr/local/bin/
sudo cp target/release/wolfdiskctl /usr/local/bin/

Usage

1. Initialize Data Directory

wolfdisk init -d /var/lib/wolfdisk

2. Mount the Filesystem

# Foreground (for testing)
sudo wolfdisk mount -m /mnt/wolfdisk

# As a systemd service (recommended)
sudo systemctl start wolfdisk

3. Check Status

wolfdiskctl status

4. Use It Like Any Directory

# Write files
echo "Hello, WolfDisk!" > /mnt/wolfdisk/hello.txt
cp /var/log/syslog /mnt/wolfdisk/

# Read files — automatically available on all nodes
cat /mnt/wolfdisk/hello.txt
ls -la /mnt/wolfdisk/

Configuration

WolfDisk is configured via /etc/wolfdisk/config.toml. The installer creates this file for you, or you can edit it manually:

[node]
id = "node1"                    # Unique node identifier
role = "auto"                   # auto, leader, follower, or client
bind = "0.0.0.0:9500"           # IP and port for cluster communication
data_dir = "/var/lib/wolfdisk"  # Where chunks and index are stored

[cluster]
# Auto-discovery (recommended for LAN)
discovery = "udp://239.255.0.1:9501"

# Or manual peers (for cross-subnet / WAN)
# peers = ["192.168.1.10:9500", "192.168.1.11:9500"]

[replication]
mode = "shared"       # "shared" or "replicated"
factor = 3            # Number of copies (replicated mode)
chunk_size = 4194304  # 4 MB chunks

[mount]
path = "/mnt/wolfdisk"
allow_other = true    # Allow other users to access the mount

# Optional: S3-compatible API
[s3]
enabled = true
bind = "0.0.0.0:9878"
# access_key = "your-access-key"   # optional auth
# secret_key = "your-secret-key"   # optional auth

Configuration Sections

Architecture

WolfDisk is composed of several layers that work together:

┌───────────────────────────────────────────────────────────────┐
│                      Linux Applications                       │
├───────────────────────────────────────────────────────────────┤
│                    mount /mnt/wolfdisk                         │
├───────────────────────────────────────────────────────────────┤
│                       FUSE (fuser)                             │
├───────────────────────────────────────────────────────────────┤
│                     WolfDisk Core                              │
│  ┌─────────────┐  ┌───────────────┐  ┌──────────────────────┐ │
│  │  File Index  │  │  Chunk Store  │  │ Replication Engine   │ │
│  │  (metadata)  │  │   (SHA256)    │  │ (leader election)    │ │
│  └─────────────┘  └───────────────┘  └──────────────────────┘ │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │              S3-Compatible API (optional)                  │ │
│  │         ListBuckets / Get / Put / Delete Objects           │ │
│  └───────────────────────────────────────────────────────────┘ │
├───────────────────────────────────────────────────────────────┤
│       Network Layer: Discovery + Peer Manager + Protocol       │
└───────────────────────────────────────────────────────────────┘

How It Works

1. FUSE Layer — Applications read/write to /mnt/wolfdisk like a normal directory. The FUSE driver intercepts all filesystem calls.
2. Chunk Store — Files are split into 4 MB chunks, each identified by its SHA256 hash. Identical data is automatically deduplicated.
3. File Index — Maps file paths to their chunk references, permissions, size, and modification times.
4. Replication Engine — Synchronises chunks and index updates across nodes. Handles leader election and failover.
5. Network Layer — UDP multicast for peer discovery, TCP for data transfer. LZ4 compression for network efficiency.

Leader Election & Failover

WolfDisk uses deterministic leader election — no voting, no delays. The node with the lowest ID is always the leader.

How Failover Works

Initial State:
  node-a (leader) ←→ node-b (follower) ←→ node-c (follower)

node-a goes down:
  ❌ node-a         node-b detects timeout (2s)
                    node-b becomes leader (next lowest ID)

node-a returns:
  node-a syncs from node-b (gets missed changes)
  node-a becomes leader again (lowest ID)

• Heartbeat timeout — Nodes monitor the leader with a 2-second timeout
• Fast election — No voting or consensus delay; lowest node ID always wins
• Seamless reads — Followers continue serving reads during failover
• Explicit override — Set role = "leader" to force a specific node as leader

Sync & Replication

Write Replication

When the leader writes a file:

1. Local write — Leader stores chunks and updates the file index locally
2. Broadcast — Leader sends the index update and chunk data to all followers
3. Apply — Followers update their local index and store the chunks

Delta Sync (Catchup)

When a node starts or recovers from downtime, it performs an incremental sync:

Follower (version 45) → Leader: "SyncRequest(from_version=45)"
Leader (version 50)   → Follower: "SyncResponse(entries=[5 changes])"
Follower applies 5 changes, now at version 50

Only missed changes are transferred — a node that was down briefly doesn't need to re-download everything.

Read Caching

Followers cache chunks locally for fast reads:

• Cache hit — Chunk exists locally → return immediately
• Cache miss — Fetch chunk from leader → cache locally → return

Client Mode (Thin Client)

Client mode mounts the filesystem without storing any data locally. All reads and writes are forwarded to the leader over the network.

Client mode is ideal for:

• Workstations accessing shared files
• Containers that need cluster storage access
• Read-heavy applications where network latency is acceptable

S3-Compatible API

WolfDisk can optionally expose an S3-compatible REST API, allowing any S3 client (AWS CLI, rclone, MinIO Client, etc.) to read and write files. Both FUSE and S3 access the same underlying data — files written via FUSE are instantly visible through S3, and vice versa.

Enable S3

Add to /etc/wolfdisk/config.toml:

[s3]
enabled = true
bind = "0.0.0.0:9878"
# Optional authentication:
# access_key = "your-access-key"
# secret_key = "your-secret-key"

How It Maps

Supported Operations

Examples

# Using AWS CLI
aws --endpoint-url http://localhost:9878 s3 ls
aws --endpoint-url http://localhost:9878 s3 cp file.txt s3://mybucket/file.txt
aws --endpoint-url http://localhost:9878 s3 ls s3://mybucket/

# Using curl
curl http://localhost:9878/mybucket/myfile.txt
curl -X PUT --data-binary @file.txt http://localhost:9878/mybucket/file.txt

CLI Reference

wolfdisk (Service Daemon)

Options:

• --config PATH — Path to config file (default: /etc/wolfdisk/config.toml)

wolfdiskctl (Control Utility)

Options:

• -s, --status-file PATH — Path to status file (default: /var/lib/wolfdisk/cluster_status.json)

Systemd Service

The installer creates a systemd service for you automatically. Common commands:

# Start WolfDisk
sudo systemctl start wolfdisk

# Check status
sudo systemctl status wolfdisk

# View logs
sudo journalctl -u wolfdisk -f

# Enable on boot
sudo systemctl enable wolfdisk

# Restart after config change
sudo systemctl restart wolfdisk

Multi-Node Setup

A typical deployment has multiple nodes with different roles. All nodes with role = "auto" will automatically elect a leader.

Server 1 (will become leader — lowest ID)

[node]
id = "node-a"
role = "auto"
bind = "192.168.1.10:9500"
data_dir = "/var/lib/wolfdisk"

[cluster]
discovery = "udp://192.168.1.10:9501"

[mount]
path = "/mnt/shared"

Server 2–N (will become followers — higher IDs)

[node]
id = "node-b"          # Higher ID → follower
role = "auto"
bind = "192.168.1.11:9500"
data_dir = "/var/lib/wolfdisk"

[cluster]
discovery = "udp://192.168.1.11:9501"

[mount]
path = "/mnt/shared"

Workstation (client only — no storage)

[node]
id = "desktop"
role = "client"
bind = "192.168.1.50:9500"

[cluster]
peers = ["192.168.1.10:9500", "192.168.1.11:9500"]

[mount]
path = "/mnt/shared"

Troubleshooting

Mount fails with "Transport endpoint not connected"

The FUSE mount is stale. Unmount and remount:

sudo fusermount -u -z /mnt/wolfdisk
sudo systemctl restart wolfdisk

Permission denied on mount

Ensure user_allow_other is enabled:

echo "user_allow_other" | sudo tee -a /etc/fuse.conf

Peers not discovering each other

• Check that port 9500 (TCP) and 9501 (UDP) are open in your firewall
• For cross-subnet setups, use peers = [...] instead of UDP discovery
• Verify bind is set to an accessible IP, not 127.0.0.1

Status file not found

If wolfdiskctl status reports "Status file not found", the service is not running:

sudo systemctl start wolfdisk
sudo journalctl -u wolfdisk -f    # Check for errors

Client Reset

If a client node (not leader/follower!) has a stuck mount or corrupted cache, use the reset script:

sudo bash /opt/wolfscale-src/wolfdisk/reset_client.sh

Network Ports