Skip to content

TrueNAS Services

Service Protocol Used for
TFTP tftpd-hpa (community app) PXE boot — bootloaders + iPXE menu; see DHCP & PXE Boot
NFS NFS 4.1 Unix/Linux clients, and the truenas-nfs VMware datastore mounted across the ESXi cluster
SMB SMB Windows clients
FTP FTP Camera/NVR recording file transfer
AFP Apple Filing Protocol Apple clients
iSCSI iSCSI (software initiator on ESXi) VMFS datastores backing VMware VMs (vsphere-k8s-gold, truenas-iscsi)
rsync rsync Sync between truenas and truenas-dr
UPS NUT Power-loss monitoring / graceful shutdown
Docker/Apps — truenas-dr only: Vault unsealer container, self-hosted ADO agent, a Ubuntu-based UniFi controller VM

Notes worth keeping

  • iSCSI portal binding matters. The portal should listen on the storage VLAN address specifically (e.g. 10.10.20.3), not 0.0.0.0 — a portal on 0.0.0.0 advertises every address the box has, and ESXi will happily open a second session across the wrong VLAN, reintroducing the exact asymmetric-routing failure the PBR fix exists to prevent.
  • ATS heartbeat. TrueNAS iSCSI targets mishandle ATS-based VMFS heartbeats; VMFS3.UseATSForHBOnVMFS5 = 0 is set on ESXi hosts as a standard TrueNAS+ESXi pairing practice.
  • Docker/Apps containers are subject to the same PBR gap as native services when they try to reach a service on their own host — see Networking Gotchas.
  • SMB execute permission after a TrueNAS SCALE upgrade. An upgrade can reset smb_options, causing .exe launches from an SMB share to fail with a permissions error (read/copy still work) because Samba maps NT-execute from the Unix execute bit. Fix: midclt call smb.update '{"smb_options": "acl allow execute always = True"}' then restart the cifs service.
  • NFS export ACLs must match the current subnet, not a historical one. An export's allowed-network list is scoped to whatever subnet existed when it was configured — if a client's subnet changes (e.g. across a network redesign, or a VM landing on a different VLAN than expected), the mount fails with what looks like a client-side script bug but is actually the server denying that source network entirely. Check showmount -e <truenas-host> from the actual client subnet before debugging the mount command itself.
  • NFSv4 root-mapping (maproot) has a client-side caching trap. A Kubernetes StatefulSet's chown/initdb-style init container can fail with EINVAL if a share's maproot_user/maproot_group are unset (root-squashed) — but NFSv4 also ignores per-share maproot entirely unless the global NFS service flag "Map Root User to root" (v4_v3owner) is enabled. Even after fixing both settings server-side, an already-mounted Linux NFS client won't pick up the change: it caches "server doesn't accept raw uid/gids" in a struct shared across every mount to that server (visible in dmesg as NFS: v4 server ... does not accept raw uid/gids), so it only gets rechecked once every mount to that server drops — a full node reboot (or unmounting everything to that server), not just deleting the affected pod.