ZeroFS

• Find the ZeroFS on Ubuntu 24.04 LTS image in the Azure Marketplace and select Create.
• Choose your subscription, resource group and region.
• Select a VM size (Standard_B2s or larger) and provide your SSH public key for the azureuser account.
• On the Networking tab, allow inbound 443 and 80 from the networks that should reach the service, and 22 from your management network only.
• Leave the data disk that ships with the image in place. It is mounted at /srv/zerofs and holds the object store and cache.
• Choose Review + create. First boot takes about a minute while the VM generates its own secrets and initializes the filesystem.

az group create --name zerofs-rg --location eastus
az vm image terms accept --urn sac1647283583153:zerofs-ubuntu-24-04:default:latest
az vm create \
  --resource-group zerofs-rg \
  --name zerofs-vm \
  --image sac1647283583153:zerofs-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group zerofs-rg --name zerofs-vm --port 443 --priority 1001
az vm open-port --resource-group zerofs-rg --name zerofs-vm --port 80 --priority 1002

Every VM generates its own web credential on first boot. It is written to a root-only file:

sudo cat /root/zerofs-credentials.txt

The file lists the administrator username, the password and the URL to open:

ZEROFS_UI_USER=admin ZEROFS_UI_PASSWORD=<a unique 24 character password generated on this VM> ZEROFS_URL=https://<your VM address>/ ZEROFS_MOUNTPOINT=/mnt/zerofs

Back up the encryption password. ZEROFS_PASSWORD in /etc/zerofs/zerofs.env is the key that encrypts everything stored in the object store. Without it, the stored data cannot be decrypted, and SecureAnyCloud cannot recover it for you. Copy it somewhere safe before you put real data on this filesystem:

sudo grep '^ZEROFS_PASSWORD=' /etc/zerofs/zerofs.env

Open https://<your VM address>/ in a browser. The certificate is self-signed and generated for this VM, so your browser warns you once. Accept it, or replace the certificate as described in Step 14. Sign in with the username and password from Step 3.

You land on the file manager, which shows the real contents of the ZeroFS filesystem.

Double-click a file to open it. Text files open in an editor, and Ctrl+S writes the buffer back through the filesystem. Drag-and-drop uploads work, including whole folders. Dragging entries onto another tab moves them instead of copying them.

Opening the seeded README.txt reads its bytes back out of the encrypted object store and displays them.

Ctrl+F searches the current directory, recursing up to ten levels. A plain query is a case-insensitive substring match. A query containing * or ? is a glob, and /pattern/ is a regular expression.

The Monitor view streams live statistics: total operations, bytes read and written, storage used, inode count, throughput and IOPS. It also shows a file access tracer with recent operations.

The Terminal view boots a small Linux VM inside your browser with the ZeroFS filesystem mounted at /mnt. It is useful for quick file operations without opening an SSH session. The guest has no network device, so files move in and out only through the mounted filesystem.

This terminal can read and write everything on the filesystem. That is one of the main reasons the Web UI is never exposed without authentication on this image.

ZeroFS is already mounted at /mnt/zerofs over the in-kernel 9P client. Treat it like any other filesystem:

ls -la /mnt/zerofs/ mount | grep ' /mnt/zerofs '

echo "hello from the sac deployment guide" | sudo tee /mnt/zerofs/hello.txt sync cat /mnt/zerofs/hello.txt
sudo rm -f /mnt/zerofs/hello.txt

The mount reports no fixed size, because the capacity of a ZeroFS filesystem is whatever its object store provides. On this image the bundled store is bounded by the 40 GiB data volume. Check the real backing capacity with:

df -h /srv/zerofs

Files placed in the .nbd directory are exposed as raw block devices. You can put a conventional filesystem or a database on top of object storage:

sudo mkdir -p /mnt/zerofs/.nbd
sudo truncate -s 1G /mnt/zerofs/.nbd/volume1 ls -lh /mnt/zerofs/.nbd/
sudo rm -f /mnt/zerofs/.nbd/volume1

The NBD server listens on 127.0.0.1:10809. Attach the device from the same VM, or reach it from elsewhere over an SSH tunnel as in Step 10.

The NFS, 9P and NBD servers are unauthenticated protocols, so they are deliberately bound to loopback and are not reachable across the network. To mount the filesystem from another machine, forward the port over SSH from your client and mount through the tunnel. Run these commands on the client, not on the appliance:

$ ssh -i ~/.ssh/id_rsa -N -L 5564:127.0.0.1:5564 azureuser@<your VM address> $
sudo mount -t 9p -o trans=tcp,port=5564,version=9p2000.L,cache=mmap,access=user 127.0.0.1 /mnt/zerofs

If you would rather expose a protocol port directly on a private network, bind it to the VM's private address in /etc/zerofs/config.toml. Restrict it with a Network Security Group rule to the specific source range that needs it. Never expose these ports to the public internet, because they carry no authentication of their own.

The bundled object store makes the appliance work immediately, but the reason to run ZeroFS is usually your own object storage. Repointing is a configuration change and a restart. Doing so starts a brand-new, empty filesystem. The data already in the bundled store is not migrated, so copy anything you want to keep off /mnt/zerofs first.

Azure Blob Storage

Edit the [storage] section of /etc/zerofs/config.toml and replace the [aws] block with an [azure] block:

[storage] url = "azure://<your-container>/zerofs-data" encryption_password = "${ZEROFS_PASSWORD}" [azure] storage_account_name = "${AZURE_STORAGE_ACCOUNT_NAME}" storage_account_key = "${AZURE_STORAGE_ACCOUNT_KEY}"

Then add the account credentials to /etc/zerofs/zerofs.env. Keep the existing ZEROFS_PASSWORD line unchanged. Then restart the services:

$
sudo tee -a /etc/zerofs/zerofs.env <<'EOF' AZURE_STORAGE_ACCOUNT_NAME=<your-storage-account> AZURE_STORAGE_ACCOUNT_KEY=<your-storage-account-key> EOF $
sudo systemctl restart zerofs zerofs-mount $
sudo systemctl status zerofs --no-pager

Consider granting the VM a managed identity and using it in place of a stored account key.

Amazon S3 or any S3-compatible store

[storage] url = "s3://<your-bucket>/zerofs-data" encryption_password = "${ZEROFS_PASSWORD}" [aws] access_key_id = "${AWS_ACCESS_KEY_ID}" secret_access_key = "${AWS_SECRET_ACCESS_KEY}" default_region = "us-east-1"

Amazon S3 implements conditional writes natively, which is what ZeroFS needs for fencing. On real S3 you can therefore remove the conditional_put line from the [aws] block and stop the local coordinator:

$
sudo systemctl disable --now redis-server

Keep conditional_put pointing at Redis for any S3-compatible store that does not correctly implement conditional writes. ZeroFS checks this at startup and refuses to run against a store that would silently lose the guarantee. If it starts, the guarantee holds.

Choose a hot storage class

Whatever backend you use, keep it on a hot, standard access tier. Archive tiers make the filesystem unusable. Infrequent-access tiers charge retrieval on the constant reads ZeroFS performs, which usually costs more rather than less.

Confirm that every service is running:

systemctl is-active zerofs.service zerofs-mount.service garage.service redis-server.service nginx.service

Expected output:

active active active active active

Confirm the network exposure. Only 22, 80 and 443 face the network. Everything else is on loopback:

ss -tlnH | awk '{print $4}' | sort -u

Expected output:

0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:10809 127.0.0.1:2049 127.0.0.1:3901 127.0.0.1:3910 127.0.0.1:3913 127.0.0.1:5564 127.0.0.1:6379 127.0.0.1:7000 127.0.0.1:8080 127.0.0.53%lo:53 127.0.0.54:53 [::1]:6379 [::]:22 [::]:443 [::]:80

Only 22, 80 and 443 are bound to a routable address. Everything ZeroFS serves is on loopback: the Web UI on 8080, 9P on 5564, NFS on 2049, NBD on 10809 and the admin RPC on 7000. So are the bundled object store (3901, 3910, 3913), Redis (6379) and the local DNS stub (53).

Run the built-in self test, which proves the whole appliance end to end:

sudo /usr/local/bin/zerofs-selftest

Expected output:

OK zerofs self-test passed: healthz 200, unauth / and /ws/9p 401, authed / 200 (ZeroFS Web UI), authed /ws/9p 101, ZeroFS + object store + Redis all loopback-only, Redis requires auth, filesystem write/read/delete round-trip OK

Prove a real round trip through the filesystem by writing a megabyte and reading it back:

sudo bash -c 'head -c 1048576 /dev/urandom > /tmp/rt.bin; cp /tmp/rt.bin /mnt/zerofs/rt.bin; sync; \
  A=$(sha256sum /tmp/rt.bin | cut -d" " -f1); B=$(sha256sum /mnt/zerofs/rt.bin | cut -d" " -f1); \
  [ "$A" = "$B" ] && echo "ROUND-TRIP OK $A" || echo "MISMATCH"; rm -f /mnt/zerofs/rt.bin /tmp/rt.bin'

The health endpoint is deliberately unauthenticated so that load balancer probes work:

curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/healthz

Expected output:

200

Port 80 redirects to HTTPS:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/

Expected output:

301

Everything else is refused without the per-instance credential, including the WebSocket that backs the file manager and the in-browser terminal:

curl -sk -o /dev/null -w 'web ui: %{http_code}\n' https://127.0.0.1/
curl -sk -o /dev/null -w '9p websocket: %{http_code}\n' https://127.0.0.1/ws/9p

Expected output:

web ui: 401 9p websocket: 401

With the credential, the same request succeeds:

sudo bash -c 'U=$(grep -m1 "^ZEROFS_UI_USER=" /root/zerofs-credentials.txt | cut -d= -f2-); \
  P=$(grep -m1 "^ZEROFS_UI_PASSWORD=" /root/zerofs-credentials.txt | cut -d= -f2-); \
  curl -sk -o /dev/null -w "authenticated: %{http_code}\n" -u "$U:$P" https://127.0.0.1/'

Expected output:

authenticated: 200

The image generates a self-signed certificate for this VM on first boot, with the VM address in its Subject Alternative Names. To use your own certificate, put it in place and reload nginx:

$
sudo cp /path/to/fullchain.pem /etc/nginx/tls/zerofs.crt $
sudo cp /path/to/privkey.pem /etc/nginx/tls/zerofs.key $
sudo chmod 0600 /etc/nginx/tls/zerofs.key $
sudo nginx -t && sudo systemctl reload nginx

To change the web password, rewrite the basic-authentication file with the bundled helper. Only the bcrypt hash is stored:

$
sudo /usr/local/sbin/zerofs-write-htpasswd admin '<a strong new password>' $
sudo systemctl reload nginx

Then update /root/zerofs-credentials.txt so that the recorded value stays accurate.

Print the installed ZeroFS version:

zerofs --version dpkg-query -W -f='zerofs deb version: ${Version}\n' zerofs

Expected output:

zerofs 2.3.2 zerofs deb version: 2.3.2

Key paths on the appliance:

• /etc/zerofs/config.toml: ZeroFS configuration (storage backend, cache and server ports).
• /etc/zerofs/zerofs.env: per-VM secrets, root only (encryption password, object store key, Redis password).
• /root/zerofs-credentials.txt: per-VM web credential and URL, root only.
• /mnt/zerofs: the ZeroFS filesystem, mounted on the VM.
• /srv/zerofs: the dedicated data volume that holds the object store and the cache.
• /etc/nginx/sites-available/sac-zerofs: the TLS and authentication front.
• /usr/local/bin/zerofs-selftest: the end-to-end appliance self test.

The image ships ZeroFS 2.3.2 from the project's own repository. Ubuntu's unattended upgrades act only on Ubuntu's own security origins, so ZeroFS is never upgraded automatically underneath you. Take a newer release deliberately when you are ready:

$
sudo apt-get update && sudo apt-get install --only-upgrade zerofs $
sudo systemctl restart zerofs zerofs-mount