Platform support
New line, in development. Membership depends on host capabilities. See the current runtime contract.
Cluster membership and roles depend on the host capabilities recorded by
ce/core/hostplat. Linux provides the mesh, fabric and voter capabilities.
macOS provides mesh through the daemon’s userspace WireGuard device on a utun.
The rule the codebase follows, everywhere:
A mutating operation outside the supported scope refuses with a coded error naming the missing kernel facility. A read/status operation answers truthfully that the thing is absent.
A refusal is never a silent no-op.
Status of this page: the refusals are tested, macOS is not verified
Section titled “Status of this page: the refusals are tested, macOS is not verified”Read the matrix below as a scope statement, not a passed acceptance test. Nothing described here has been run on a Mac.
What is tested: every refusal and every deliberate non-refusal, driven
from Linux through the hostplat seam (Override("darwin")), plus a
paired assertion per guard that the Linux path is unchanged. That covers
the guard logic and its wiring, which is what this boundary is.
What is not tested, and is inference rather than observation:
- that
/etc/fstabis present and writable on macOS in the shape the NFS teardown assumes; this claim is the sole justification for thedisableasymmetry below, and stock macOS does not ship an/etc/fstab; - that
launchctl bootstrap/dseditgroupbehave as the launchd arm assumes, and that a missingsystemctlsurfaces asexec: "systemctl": executable file not found.
The refusals do not depend on any of these being right (they fire before that code is reached), but the explanations in their messages do. Correct them if a Mac ever says otherwise.
Service supervision on macOS is wired: host activation dispatches
through a platform seam, and its launchd arm writes the LaunchDaemon
org.selfhostedcloud.shcd to /Library/LaunchDaemons and bootstraps it
into the system domain. Nothing packages that plist, so activation is
what creates it. Like everything else here, that path is exercised
against a fake command runner on Linux, not against launchd.
Host support matrix
Section titled “Host support matrix”| Host | Scope | Notes |
|---|---|---|
| Linux (amd64, arm64) | Everything. Single node and multi-node, every runtime, the shc fabric, shared storage. | The only platform with published shc / shcd / shc-x9s artifacts. Verified. |
| macOS (arm64, amd64) | Single node, or a mesh0 member of a cluster. The shc fabric on the apple runtime only. | Joins as a raft non-voter with a mesh0 address. On the apple runtime it holds shc0 chunks once its pf policy loads. Build from source. |
| Windows / other | No cluster membership. | Join refuses with X501392CLJPLT because no mesh0 device is available. |
An empty --runtime detects a live docker socket as docker and a live
podman socket as podman, and otherwise records docker
(modules/cluster/local_init.go detectRuntimeFrom). An empty --fabric
records shc where that runtime can attach the fabric: on Linux, and on a
Mac running apple. Elsewhere init forms the cluster without the shc
fabric and warns. --fabric none is refused where the runtime can attach
it (X400389FABOFF).
--runtime podman is a runtime executor.New answers. RunsOn does not
bind it to Linux. Init warns that a podman cluster is single-node only
(modules/cluster/service.go CheckInit).
Host capabilities
Section titled “Host capabilities”| Host | mesh | fabric | voter |
|---|---|---|---|
| Linux | Yes | Yes | Yes |
| macOS | Yes | No | No |
| Windows / other | No | No | No |
mesh needs a WireGuard device for mesh0: kernel WireGuard over netlink,
or the daemon’s userspace device on a utun. fabric needs kernel WireGuard
over netlink and nftables for shc0. voter needs a mesh0 device that stays
up while the daemon restarts. A utun owned by shcd cannot provide that.
A Mac join receives a mesh0 address and a non-voter raft seat. It receives
no shc0 subnet or fabric address, and its container engine is not checked
for fabric support. It takes no derived control-plane membership, even
at the control plane’s home location. A join with --control-plane on a host without voter refuses with
X501395ROLCAP, naming the missing capability. A row with no capabilities has none.
Built (SHC-1481). An apple node holds its containers off the node plane
with the pf child anchor com.apple/shc/node-plane, compiled from the same
HostInput as the Linux nft table inet shc_node_plane, and loaded by shcd
while the Mac is a member. The design is in
Security, mesh networking.
Capability and facility refusals
Section titled “Capability and facility refusals”The guards run before the requested role is granted. Joiners check their own capabilities before sending the single-use token; leaders check the declared list before writing a node row.
Swarm is not a runtime and not a host facility. shc init --runtime swarm and a join runtime of swarm are refused (X400422CLSRUN). --fabric swarm is refused (X400371FABSWM). SHC does not run docker swarm init. See New-line runtime.
| Subsystem | Refused operations | Code | Missing facility |
|---|---|---|---|
| Cluster fabric | shc init --fabric shc without fabric | X501391CLSPLT | Kernel WireGuard over netlink and nftables |
| Cluster join | shc node join without mesh | X501392CLJPLT | A WireGuard device for mesh0, either kernel WireGuard over netlink or a userspace device on a utun |
| Node role | Enrol without mesh, or control-plane membership without voter | X501395ROLCAP | The facility named by the missing capability |
| WireGuard fabric device | Applier.Apply on a non-Linux build | X500354FABDEV | Kernel WireGuard over netlink |
| Node-local NFS | enable-server, enable-client, disable | X501393NFSPLT | nfs-kernel-server, exportfs, /etc/exports.d, /etc/nfs.conf.d, and a systemd unit to run them |
| Ceph | cephfs enable, add osd | X501394CEPPLT | cephadm places mon/mgr/osd/mds as systemd units; clients mount via the kernel rbd/cephfs drivers |
The 39x sequence is reserved across modules for host-OS scope
refusals. Every message in the block names the facility, never a bare
“unsupported”: an operator who reads “kernel WireGuard over netlink”
knows it is not coming, one who reads “unsupported on darwin” files a
feature request.
What deliberately does not refuse off Linux
Section titled “What deliberately does not refuse off Linux”These are as important as the refusals. Getting them wrong turns a laptop into a wall of errors, which teaches operators to ignore the error that matters on a node.
| Surface | Behaviour off Linux |
|---|---|
Fabric device status (shc cluster fabric status) | Reports shc0 absent. That is the true and complete answer. |
| Cluster mesh (mesh0) on darwin | Runs in this process on a utun (userspace WireGuard, SHC-1287). Linux keeps kernel WireGuard over netlink. A host that is neither has no mesh0 applier; its Apply is the fabric-device refusal already listed above. |
| NFS node status | Reports is_server=false, is_installed=false, mount_active=false. |
| Cluster mesh status / diagnose | Answers normally; peer state is still reported honestly. |
Cluster mesh disable | Stays reachable. It is the way out of a half-applied mesh. |
| Single-node docker init | Not refused. An empty runtime detects docker or podman and otherwise records docker. An empty fabric records shc only where that runtime attaches it. |
Note the asymmetry between cluster mesh disable and the NFS
disable, which is refused: NFS teardown rewrites /etc/fstab, a
host file that does not belong to SHC. Nothing off Linux could ever have
been enabled, so refusing it denies the operator nothing, which is why
the asymmetry is cheap even though the premise behind it (that macOS
presents an /etc/fstab worth protecting) is
unverified, and stock macOS ships none.
macOS caveats
Section titled “macOS caveats”Three things are true on macOS regardless of what SHC does, and all three are stated here rather than hidden:
- Docker on macOS is a Linux VM (Docker Desktop, colima, Rancher
Desktop, podman machine). Anything a container observes about “the
host” is really the VM. The metrics collector’s
hostmetricsreceiver runs inside that VM and faithfully reports the VM’s CPU, memory and disk as if they were the Mac’s, which is undetectable downstream, because VM metrics and host metrics carry the same names and the same units. So the render STAMPS the answer onto the data: every node-metrics series carriesshc.host_metrics.subject(node|container-runtime-vm) andshc.node.os, and the daemon logsX503122COLVMSon transition. Container metrics are deliberately not stamped: a container’s own CPU is its own on every platform. Details, plus the node facts macOS cannot measure at all, are in macOS. - The macOS artifact is an archive, not a package. Every release
publishes
shc_<ver>_darwin_<arch>.tar.gzforamd64andarm64, a prefix overlay for/usr/local; see macOS. - The daemon runs under launchd, and activation is what installs
it. No archive ships a plist, so
/Library/LaunchDaemons/org.selfhostedcloud.shcd.plistand its watchdog’s exist only after a rootshc initorshc node join. An unprivileged run cannot start the daemon and says so.
Where the boundary lives in code
Section titled “Where the boundary lives in code”ce core/hostplat: the host-OS seam (GOOS(),IsLinux(),Override()for tests) and the package doc that states this scope boundary once, authoritatively.ce modules/fabric/applier_other.go: the original pattern: a//go:build !linuxstub whoseApplyrefuses with a code and whoseStatustruthfully reports absence.
Build tags are used only where the link would otherwise break. Everything else is a runtime check, because logic that compiles on one GOOS can only be tested on that GOOS, and the refusals need tests that prove both halves: that they fire off Linux and that Linux is untouched.