A Longhorn NFS backup target needs NFSv4, and nfsOptions cannot change that

Longhorn always mounts an NFS backup target as nfs4, including in its fallback chain, so a NAS that only serves NFSv3 cannot be a backup target. How to check the server, and what enabling v4 on an older QNAP involves.

My Longhorn install had no working backup target. Every snapshot lived on the same disk as the volumes it was supposed to protect, which is fine until the disk goes. The obvious place for backups was the NAS I already had, and the question was how to connect it: NFS or iSCSI.

iSCSI is not an option

Longhorn backup targets are object storage (S3), NFS, SMB/CIFS or Azure Blob. Longhorn writes backups as files and objects into a store, so it needs a filesystem or a bucket. An iSCSI LUN is a raw block device, and Longhorn has no backup target type for it. My NAS is an old ARM QNAP that can’t run MinIO or QNAP’s own object storage either, so S3 was out as well. That left NFS.

The NAS spoke NFS, just not the right version

The share was already exported. What I hadn’t checked was which protocol versions the server actually speaks. On a Linux-based NAS the kernel tells you directly:

cat /proc/fs/nfsd/versions
# +2 +3 -4 -4.1

Versions 2 and 3 on, 4 off. That matters because Longhorn only mounts backup targets as nfs4. The mount type is hard-coded in Longhorn’s backupstore code, both when you pass custom ?nfsOptions= in the target URL and in its automatic fallback, which tries 4.2, then 4.1, then 4.0 and gives up. Nothing in the chain tries v3. Setting nfsvers=3 in the options doesn’t help, because the mount type is still nfs4.

So if your NAS only serves NFSv3, it isn’t a Longhorn backup target, however the export is configured. Check /proc/fs/nfsd/versions (or your NAS’s NFS settings page) before you spend time on anything else.

Turning on NFSv4 on an older QNAP

QTS 4.3 has NFSv4 support installed but switched off. The web UI checkbox is a config flag, which you can also set from a shell:

setcfg NFS Enable_V4 TRUE      # writes /etc/config/uLinux.conf
/etc/init.d/nfs restart

With the flag set, the init script builds an NFSv4 pseudo-root, regenerates the exports and starts the ID mapper. v3 stays available alongside, so existing v3 clients keep working. To roll back, set the flag to FALSE and restart again.

The catch is the restart. The QTS init script stops NFS with kill -9 on nfsd, so every client with a mount open loses it mid-write. Before running it, find everything that mounts from the NAS (VM disks, container hosts, NFS volumes in the cluster) and stop it cleanly. I use the same quiesce-everything playbook as for a NAS reboot. I haven’t done that restart yet. It’s waiting for a maintenance window, which is why this note ends at the plan rather than at a running backup.

One thing to tighten while you’re there

Longhorn needs the export with no_root_squash, because it writes as root. My NAS exported every share to * with no_root_squash, so any machine on the network could write to it as root. When you set up the backup export, restrict it to the nodes that actually need it.