Overview

The Shares page (Storage → Shares, or via the app drawer) lets you re-export any storage WolfStack can reach as an SMB or NFS share to your LAN. The point: drop a WolfStack node on top of anything — a local directory, a CephFS pool, an existing NAS, a VM running its own SAN — and clients see a normal network share with WolfStack’s auth and management on top.

Shares are cluster-aware: the panel aggregates every share across every node, and with a Federation entry it aggregates across separate WolfStack clusters too — one pane of glass for every site you manage.

Available from Homelab tier upwards. Community can configure shares but the daemon-config write requires the api_keys licence feature for federation.

Sources you can re-export

A share has one source. Pick from:

TypeWhat it points atPerformance tier
Local directoryAny path on the serving node (/etc, /proc, /sys, /dev, /boot are blocked for safety)fast
WolfDisk volumeA volume mounted by WolfDisk under /mnt/wolfdisk/<volume_id>, optionally with a subpathfast
CephFSA filesystem on a Ceph cluster you’ve already registered, optionally with a subpathfast
SMB re-exportAn existing SMB share on another box (Synology, QNAP, TrueNAS, another Linux samba server). Auth via guest, or username/password/domainmedium
NFS re-exportAn NFS export from another servermedium

Share names are unique per node — the name becomes both the SMB share name and the /exports/<name> NFS path, so the dashboard refuses a duplicate rather than letting two shares silently serve each other’s data.

Each share gets a performance tier badge (fast / ok / slow / cold) so you don’t accidentally back a VM disk with an S3-fronted share.

Protocols

  • SMB — via host-installed Samba. Windows / Mac / Linux all just work. Optional Apple Time Machine support, server-side recycle bin, configurable workgroup.
  • NFS — via host-installed nfs-kernel-server, serving NFSv3 and v4 clients alike. Each share publishes at a clean path — server:/exports/<share-name> — with a unique, stable fsid generated per share (so exports work on any filesystem, including ones without their own UUID). An advanced field lets you append extra exports(5) options like no_root_squash if you need them.
  • Both at once is fine — the same source path is exported through both daemons.

WolfStack writes per-share config snippets at /etc/samba/wolfstack-gateways.d/<id>.conf and /etc/exports.d/wolfstack-<id>.exports, then reloads smbd / runs exportfs -ra. Your existing /etc/samba/smb.conf is left alone aside from one include = ... line added on first use.

Missing tools? WolfStack never auto-installs. If samba or nfs-kernel-server isn’t present on the serving node, the Shares page surfaces a banner with the exact apt-get install / pacman -S command for your distro.

Auth

Two modes:

  • Anonymous — anyone on the LAN, optionally writable. NFS exports work in this mode (NFSv3/v4-sys is IP-based).
  • Users — one or more usernames with per-user read-only / writable flags. SMB only (NFS is skipped with a clear UI reason; AD/Kerberos lands in v1.2). After saving, you set passwords from the share detail pane — plaintext is piped straight into smbpasswd and never persisted by WolfStack. Only Samba’s tdbsam holds the hash.

Removing a user from a share via Edit (or deleting the share) automatically prunes their tdbsam entry — your operator-created Samba accounts are protected from this prune; only users WolfStack created itself are eligible.

Network-level controls: per-share allow / deny CIDR lists. Empty allow list = anyone on the LAN.

Federation — manage shares across separate clusters

The Shares page already aggregates every node in your cluster. Federation lets you connect other WolfStack clusters — different sites, different admin domains — and see all their shares alongside yours.

Setup is one-way and operator-controlled:

  1. On the cluster you want to read from: Settings → API Keys → + New key, scope = read. Copy it.
  2. On your cluster: Storage → Shares → expand Connected clusters → + Add cluster.
  3. Paste the remote cluster’s base URL (e.g. https://wolfstack.example.com:8553) and the API key. Tick Allow self-signed TLS certificate if relevant.
  4. WolfStack pings the remote, shows ✓ on success or the full TLS / HTTP error chain on failure. From then on, the Shares page surfaces every share from every connected cluster.

Federated shares are read-only from this dashboard — clicking through opens a panel pointing you at the originating cluster’s dashboard for edits. Cross-cluster edit is a v2 feature.

Errors don’t silently disappear: an unreachable federation surfaces as a red placeholder row in the Shares list with the exact reason (TLS mismatch, 401, connection refused, …) so a broken connection is impossible to miss.

Security & defaults

  • Path-traversal guards on every subpath field — .., leading slashes, and null bytes are rejected at config save AND a runtime safe_join blocks symlink-escape tricks.
  • SMB workgroup and share name pass through a strict whitelist before being written to smb.conf; injection via embedded newlines is impossible.
  • Share names follow Samba section-name rules (A-Z, a-z, 0-9, hyphen, underscore, ≤ 63 chars).
  • Cluster ownership: only the node a share was created on actually serves it. Peers hold the config so the panel can surface it but never write Samba snippets locally — no double-serving, no diverged tdbsam.
  • Audit log: every create / edit / delete / disable / enable / reload / password-set carries the operator’s username ((by paulc)) into the Tasks panel.

Quick walkthrough

  1. Storage → Shares → + New Share.
  2. Step 1 — Name and source. Enter a share name. Either pick a discovered source from the dropdown (WolfDisk volumes, CephFS filesystems, “Local directory on this node”) or expand Custom source for SMB/NFS re-exports with a free-form path.
  3. Step 2 — Protocols and auth. Tick SMB, NFS, or both. Pick anonymous or users. For users mode, add usernames with read/write flags.
  4. Step 3 — Options and confirm. Read-only, guest OK, recycle bin, Time Machine, allowed CIDRs, SMB workgroup. Summary card shows what you’re about to create.
  5. Click Create Share. For users mode, the dashboard prompts you for each user’s password immediately after creation.

Connect from clients:

Linux:   sudo mount -t cifs //wolfstack.local/myshare /mnt -o user=alice
Mac:     open smb://wolfstack.local/myshare
Windows: \\wolfstack.local\myshare
NFS:     sudo mount -t nfs wolfstack.local:/exports/myshare /mnt

What it does NOT do (yet)

  • Failover / aggregate / sharded modes — v1.0 is single-source. Modelled in the data shape so config files don’t need migration when those phases land.
  • Multi-node serve / CTDB clustering — one node serves each share. v2.0.
  • AD / Kerberos auth — v1.2.
  • iSCSI / NVMe-oF block targets — v2.0.
  • SSHFS / S3 / RBD / container-volume / VM-export sources — modelled, mount path returns “reserved for a future release”.
Esc