cnix

nixshare

Summary

nixshare declares NFS and CIFS shares whose server is named as a network peer instead of a hardcoded address, plus a watchdog that detects a stuck automount attempt and force-unmounts it before it hangs the session. The server side exports a ZFS-carried tree matrix over kernel NFSv4 and Samba, fully declaratively.

The address half comes from the peer layer’s LAN and overlay failover; the watchdog covers what that layer cannot, namely an in-flight mount that is already taking too long. Client and server are independent: a host can serve without importing the client schema and vice versa.

What it is

  • Client core (nixosModules.core, nixosModules.default): the nixshare.shares and watchdog schema plus a protocol-agnostic watchdog timer and oneshot (see modules/core.nix).
  • Client providers: nixosModules.nfs-provider, nixosModules.cifs-provider, and nixosModules.fscache-provider, each declaring its own mounts because NFS and CIFS option shapes differ.
  • Server providers: nixosModules.nfs-server-provider and nixosModules.cifs-server-provider as full NixOS service modules.
  • System-manager rendering of the same surface, a cluster module rendered through the real consumer factory, health and watchdog packages in pkgs/, and checks (checks/cluster-eval.nix, checks/cluster-render.nix) with fixture scripts in tests/.

It is not a network overlay, peer health checker, or filesystem itself. It consumes peer names and ZFS datasets owned elsewhere.

How it works

Each share names its server as a peer; the peer layer keeps host resolution pointed at whichever transport currently works, so shares gain failover with no address logic of their own. The watchdog watches mount attempts against nixshare.establishTimeoutSec and unsticks them proactively rather than leaving the operator to discover a wedged session and reach for manual unmounts.

Providers translate the shared schema into concrete systemd mounts and automounts per protocol. The server modules manage the NFS server, Samba, and discovery services for ZFS-carried exports. The cluster module defines into the real app grammar and is rendered in checks through the actual factory, so an empty render surface would be caught rather than passing on flake syntax alone.

How to configure it

Import core plus exactly the providers the host needs, then declare shares under the observed surface in modules/core.nix and the provider files:

  • nixshare.shares.<name> — peer server name plus protocol parameters.
  • nixshare.establishTimeoutSec — watchdog patience per mount attempt.
  • nixshare.watchdog.alertCommand — optional hook on intervention.
  • nixshare.providers.*.enable — per-protocol client participation.
  • Server shares under the NFS and CIFS server provider options.

Review examples/all and the tests/ fixture scripts before enabling the watchdog on a host with interactive mounts.

Tutorial

This example uses invented values against the real option interface from the referenced revision. The interface shape below was evaluated with the actual nixosModules.default and nixosModules.nfs-provider modules at the pinned revision using synthetic values only; nothing was mounted.

# Synthetic example: invented peer and share choices.
{
  imports = [
    inputs.nixshare.nixosModules.default
    inputs.nixshare.nixosModules.nfs-provider
  ];
 
  nixshare = {
    enable = true;
    shares.demo-media = {
      protocol = "nfs";
      peer = "demo-peer";
      remotePath = "/exports/demo";
      mountpoint = "/mnt/demo-media";
    };
  };
}

Enabling happens once at the top level; shares carry no per-share enable. A share names its protocol explicitly and always carries a mountpoint.

Checking watchdog state uses the packaged helper:

# Synthetic example: public placeholder only.
nixshare-health --once

Treat peer names as the only server identity; no literal server address belongs in a share definition.

Evidence and limits

This page is bound to public revision eca4cbd43e25e075565912c43f5adaae1d24b92e. That tree contains the flake outputs, modules/core.nix, modules/providers/, modules/nixos/, modules/system-manager/, modules/cluster.nix, modules/zfs-names.nix, pkgs/nixshare-health.nix, pkgs/nixshare-watchdog.nix, checks/, examples/all, and the tests/ fixtures discussed above.

CNIX has not independently established a successful evaluation, render, mount, failover, or watchdog intervention for that revision. The tutorial interface above was evaluated against the real modules at that revision with synthetic values: top-level enable, protocol, peer, and mountpoint pass type checking and the share renders without assertion failures. Peer failover integration, server export behavior, and cluster rendering are described from source structure, not from reproduced runs.

nixshare owns share definitions, provider rendering, and stuck-mount recovery only. Peer reachability and health checking, tiny-VM server policy, notification of interventions, and shell environment are sibling concerns with their own revision-addressed concepts. Its relationship to other Corbet Nix projects is currently a shared design direction, not evidence of runtime integration.