ZeroFS

https://www.zerofs.net/docs
Admin
ZeroFS makes S3 storage feel like a real filesystem, providing file-level access via NFS and 9P and...
Tokens:68,091
Snippets:539
Trust Score:5.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Go client library

Source: https://www.zerofs.net/docs/client-libraries

Install the ZeroFS Go client using go get.

```bash
go get github.com/Barre/ZeroFS/zerofs/zerofs-ffi/bindings/go
```

--------------------------------

### Initialize and Start PostgreSQL

Source: https://www.zerofs.net/docs/postgresql-in-the-browser

Commands to set up the environment, initialize the database, and start the PostgreSQL server within the terminal tab.

```bash
# From another machine or the file manager, copy a static 32-bit x86
# (i386) PostgreSQL build onto the ZeroFS filesystem, e.g. into /postgres

# Then from the terminal tab:
export PATH=/mnt/postgres/bin:$PATH
export LD_LIBRARY_PATH=/mnt/postgres/lib

initdb -D /mnt/pgdata
pg_ctl -D /mnt/pgdata -l /mnt/pgdata/logfile start
psql -d postgres
```

--------------------------------

### Start the ZeroFS server

Source: https://www.zerofs.net/docs/9p-access

Launch the server using the specified configuration file.

```bash
zerofs run --config zerofs.toml
```

--------------------------------

### Go client usage example

Source: https://www.zerofs.net/docs/client-libraries

Demonstrates connecting to a ZeroFS socket and performing common filesystem operations in Go.

```go
import (
	"log"

	zerofs "github.com/Barre/ZeroFS/zerofs/zerofs-ffi/bindings/go"
)

fs, err := zerofs.ClientConnect("unix:/run/zerofs/9p.sock")
if err != nil {
	log.Fatal(err)
}
defer fs.Close()

must := func(err error) { if err != nil { log.Fatal(err) } }

must(fs.CreateDirAll("/demo", 0o755))
must(fs.Write("/demo/notes.txt", []byte("hello from zerofs")))

data, err := fs.Read("/demo/notes.txt")
must(err)
meta, err := fs.Metadata("/demo/notes.txt")
must(err)
log.Printf("%d bytes, size=%d, isFile=%v", len(data), meta.Size, meta.IsFile())

// Stream the directory with a range-over-func iterator.
dir, err := fs.OpenDir("/demo")
must(err)
defer dir.Close()
for entry, err := range dir.Entries() {
	must(err)
	log.Println(entry.Name)
}
```

--------------------------------

### Install Python client library

Source: https://www.zerofs.net/docs/client-libraries

Install the ZeroFS Python client using pip.

```bash
pip install zerofs-client
```

--------------------------------

### Install TypeScript/Node client library

Source: https://www.zerofs.net/docs/client-libraries

Install the ZeroFS TypeScript/Node client using npm.

```bash
npm install zerofs-client
```

--------------------------------

### Python client usage example

Source: https://www.zerofs.net/docs/client-libraries

Demonstrates connecting to a ZeroFS socket and performing common filesystem operations.

```python
import zerofs_client

async with await zerofs_client.Client.connect("unix:/run/zerofs/9p.sock") as fs:
    await fs.create_dir_all("/demo", 0o755)
    await fs.write("/demo/notes.txt", b"hello from zerofs")

    data = await fs.read("/demo/notes.txt")
    meta = await fs.metadata("/demo/notes.txt")
    print(len(data), meta.size, meta.is_file())

    # A File handle for positioned I/O.
    async with await fs.open("/demo/data.bin", zerofs_client.OpenOptions(write=True, create=True)) as f:
        await f.write_at(0, b"\x00" * 4096)
        await f.sync_all()

    # Stream the directory entry by entry.
    async with await fs.open_dir("/demo") as d:
        async for entry in d:
            print(entry.name)

    await fs.rename("/demo/notes.txt", "/demo/notes.md")
    await fs.remove_file("/demo/notes.md")
    await fs.remove_dir_all("/demo")
```

--------------------------------

### Example ZeroFS TOML configuration with cache, storage, and NFS server

Source: https://www.zerofs.net/docs/configuration

Example TOML configuration showing required `[cache]`, `[storage]`, and `[servers]` tables. All `*_gb` sizes are decimal gigabytes. Unknown keys are rejected.

```toml
# 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

# Server configuration (required table, every subsection optional)
[servers.nfs]
addresses = ["127.0.0.1:2049"]

```

--------------------------------

### TypeScript/Node client usage example

Source: https://www.zerofs.net/docs/client-libraries

Demonstrates connecting to a ZeroFS socket and performing common filesystem operations using TypeScript.

```typescript
import { Client, openOptions, isFile } from "zerofs-client";

await using fs = await Client.connect("unix:/run/zerofs/9p.sock");

await fs.createDirAll("/demo", 0o755);
await fs.write("/demo/notes.txt", new TextEncoder().encode("hello from zerofs"));

const data = await fs.read("/demo/notes.txt");
const meta = await fs.metadata("/demo/notes.txt");
console.log(data.length, meta.size, isFile(meta));

// A File handle for positioned I/O.
await using f = await fs.open("/demo/data.bin", openOptions({ write: true, create: true }));
await f.writeAt(0n, new Uint8Array(4096));
await f.syncAll();

// Stream the directory entry by entry.
await using dir = await fs.openDir("/demo");
for await (const entry of dir) console.log(entry.name);

await fs.rename("/demo/notes.txt", "/demo/notes.md");
await fs.removeFile("/demo/notes.md");
await fs.removeDirAll("/demo");
```

--------------------------------

### Install zerofs-kernel-client on Debian/Ubuntu

Source: https://www.zerofs.net/docs/kernel-client

Adds the ZeroFS repository and installs the zerofs and zerofs-kernel-client packages. The kernel-client package registers with DKMS and downloads a signed, boot-tested module for the installed kernel. Requires matching kernel headers.

```bash
curl -fsSL https://pkgs.zerofs.net/zerofs.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/zerofs.gpg
echo 'deb [signed-by=/usr/share/keyrings/zerofs.gpg] https://pkgs.zerofs.net/deb stable main' \
  | sudo tee /etc/apt/sources.list.d/zerofs.list >/dev/null
sudo apt update
sudo apt install zerofs zerofs-kernel-client

```

--------------------------------

### Run ZeroFS with a configuration file

Source: https://www.zerofs.net/docs/configuration

CLI commands to start ZeroFS with a config file. Use `zerofs run --config /etc/zerofs/zerofs.toml` or the shorthand `zerofs run -c zerofs.toml`.

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

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

```

--------------------------------

### Start ZeroFS Writer and Read-Only Replicas

Source: https://www.zerofs.net/docs/read-replicas

Commands to launch the primary read-write instance and subsequent read-only replica instances using the same configuration file.

```bash
# Read-write instance (exactly one)
zerofs run -c zerofs.toml

# Read-only instances (any number)
zerofs run -c zerofs.toml --read-only
```

--------------------------------

### Deploy ZeroFS CSI gateway with gateway-example.yaml

Source: https://www.zerofs.net/docs/kubernetes-csi

Downloads the example manifest, then applies it after editing both nodes' Secrets to use identical storage url and encryption_password plus credentials. The manifest creates the zerofs namespace, per-node config Secrets, per-node Services (9P on 5564, admin RPC on 7000, replication on 9000), and a single-replica StatefulSet for each node.

```bash
curl -fsSLO https://raw.githubusercontent.com/Barre/ZeroFS/main/zerofs/zerofs-csi/deploy/gateway-example.yaml
# Edit both nodes' Secrets: identical storage url and encryption_password, plus credentials.
kubectl apply -f gateway-example.yaml

```

--------------------------------

### Go ClientConnect example

Source: https://www.zerofs.net/docs/high-availability

Connect to a ZeroFS HA pair from Go using the zerofs.ClientConnect function. Pass both node addresses as a comma-separated string.

```go
zerofs.ClientConnect("node-a:5564,node-b:5564")
```

--------------------------------

### Python connect example

Source: https://www.zerofs.net/docs/high-availability

Connect to a ZeroFS HA pair from Python using the zerofs_client.Client.connect method. Pass both node addresses as a comma-separated string.

```python
await zerofs_client.Client.connect("node-a:5564,node-b:5564")
```

--------------------------------

### Connect NBD export over TCP

Source: https://www.zerofs.net/docs/nbd-devices

Install `nbd-client`, load the kernel module, and connect the export. Uses `-N database` to select the export.

```bash
sudo modprobe nbd
sudo nbd-client 127.0.0.1 10809 /dev/nbd0 -N database
sudo nbd-client -check /dev/nbd0
lsblk /dev/nbd0
```

--------------------------------

### Azure Blob Storage Configuration

Source: https://www.zerofs.net/docs/configuration

Example configuration for connecting to an Azure Blob Storage container using account name and key credentials.

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

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

--------------------------------

### Run zerofs monitor dashboard

Source: https://www.zerofs.net/docs/monitoring

Commands to start the live stats dashboard. The first uses default 250 ms interval; the second sets a 1000 ms interval. The server clamps intervals below 250 ms to 250 ms.

```bash
zerofs monitor -c zerofs.toml

# Refresh every second instead of
# the default 250 ms
zerofs monitor -c zerofs.toml --interval 1000

```

--------------------------------

### Open a checkpoint with zerofs run --checkpoint

Source: https://www.zerofs.net/docs/checkpoints

Starts a read-only server for the named checkpoint. Mount or connect to one of the endpoints in `snapshot.toml` to inspect or copy files. If the read-write server is still running, give the checkpoint server its own NFS, 9P, NBD, Web UI, metrics, and RPC listeners to avoid listener conflicts.

```bash
zerofs run -c snapshot.toml --checkpoint before-migration

```

--------------------------------

### ZeroFS configuration with encryption password

Source: https://www.zerofs.net/docs/encryption

Configuration example showing how to set the storage URL and encryption password in a TOML file. ZeroFS generates a new DEK on first run.

```toml
# ZeroFS generates a new DEK on first run
[storage]
url = "s3://bucket/path"
encryption_password = "strong-password"

```

--------------------------------

### zerofs.toml cache configuration

Source: https://www.zerofs.net/docs/caching

Example configuration for the ZeroFS cache. Sets the cache directory, total disk budget, and optional memory budget. Sizes are in decimal GB (10^9 bytes).

```toml
[cache]
dir = "/var/cache/zerofs"
disk_size_gb = 10.0
memory_size_gb = 2.0  # optional

```

--------------------------------

### Install ZeroFS with APT (Debian/Ubuntu)

Source: https://www.zerofs.net/docs/quickstart

Installs ZeroFS on Debian/Ubuntu by adding the ZeroFS APT repository and installing the zerofs package. The package-manager installation also provides a disabled systemd unit and a configuration skeleton under /etc/zerofs.

```bash
curl -fsSL https://pkgs.zerofs.net/zerofs.gpg | sudo gpg --dearmor -o /usr/share/keyrings/zerofs.gpg
echo "deb [signed-by=/usr/share/keyrings/zerofs.gpg] https://pkgs.zerofs.net/deb stable main" | sudo tee /etc/apt/sources.list.d/zerofs.list
sudo apt update
sudo apt install zerofs

```

--------------------------------

### Verify ZeroFS kernel module installation

Source: https://www.zerofs.net/docs/kernel-client

Checks that the zerofs module is loaded and registered in the kernel's filesystem list.

```bash
modinfo zerofs
grep zerofs /proc/filesystems

```

--------------------------------

### Configure RPC settings for checkpoint commands (zerofs.toml)

Source: https://www.zerofs.net/docs/checkpoints

Checkpoint commands require the same `[servers.rpc]` settings as the running read-write ZeroFS process. The configuration generated by `zerofs init` already enables the RPC server on loopback and a local Unix socket.

```toml
[servers.rpc]
addresses = ["127.0.0.1:7000"]
unix_socket = "/tmp/zerofs.rpc.sock"

```

--------------------------------

### Generate default configuration template with zerofs init

Source: https://www.zerofs.net/docs/configuration

Run `zerofs init` to generate the default configuration template, which you then edit for your storage backend and listeners.

```bash
zerofs init

```

--------------------------------

### ConnectOptions

Source: https://www.zerofs.net/docs/client-libraries

Options for establishing a connection to the ZeroFS server.

```APIDOC
## ConnectOptions

### Description
Options for establishing a connection to the ZeroFS server.

### Fields
- **uid** (number) - Default: process euid. User ID.
- **gid** (number) - Default: process egid. Group ID.
- **uname** (string) - Default: $USER (informational). User name.
- **aname** (string) - Default: "" (the default export). Attachment name.
- **msize** (number) - Default: 1 MiB; server clamps to 10 MiB. Maximum message size.
- **connect_timeout_ms** (number) - Default: 30000; null waits indefinitely. Connection timeout in milliseconds.
```

--------------------------------

### TypeScript connect example

Source: https://www.zerofs.net/docs/high-availability

Connect to a ZeroFS HA pair from TypeScript using the Client.connect method. Pass both node addresses as a comma-separated string.

```typescript
await Client.connect("node-a:5564,node-b:5564")
```

--------------------------------

### Capabilities

Source: https://www.zerofs.net/docs/client-libraries

Live snapshot of connection capabilities.

```APIDOC
## Capabilities

### Description
Live snapshot of connection capabilities. Can change across reconnects; successfully connecting already guarantees the exact 9P2000.L.Z private dialect.

### Fields
- **msize** (number) - Maximum message size.
- **max_read_chunk** (number) - Maximum read chunk size.
- **max_write_chunk** (number) - Maximum write chunk size.
```

--------------------------------

### Rust connect_multi example

Source: https://www.zerofs.net/docs/high-availability

Connect to a ZeroFS HA pair from Rust using the connect_multi method. Pass both node addresses as a target set.

```rust
Client::connect_multi(&["node-a:5564".into(), "node-b:5564".into()]).await?
```

--------------------------------

### Configure and run ZeroFS in Docker

Source: https://www.zerofs.net/docs/configuration

Creates the zerofs.toml configuration file and executes the ZeroFS Docker container with environment variables passed for secret substitution.

```bash
# 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
```
Tokens:
Raw