NFS Media Storage

NFS is a common way to hand Sovereign a media library that lives on a NAS rather than on the server itself. The mount options you choose decide whether a slow or unreachable share degrades gracefully or leaves playback and scans stuck until it comes back. Here’s a starting set, and what each option buys you.

---

Recommended Mount Options

Every deployment method below mounts the share with the same option string. Substitute your own server address, and mount the library read-only, since Sovereign never writes to your media.

addr=<nfs-server-ip>,nfsvers=4.1,ro,soft,timeo=100,retrans=2,rsize=1048576,wsize=1048576,nconnect=4,actimeo=60

These are safe defaults, not tuned values

Nobody can predict your hardware or your network. A 10 GbE link to an all-flash array, a Wi-Fi bridge to a two-bay NAS, and a virtualised filer shared with a dozen other workloads all want different numbers, and the right value for rsize, nconnect, and actimeo on one of them will be wrong on another. Treat the string above as a conservative baseline that works on ordinary gigabit wired networks: start here, confirm playback and library scans are healthy, then change one option at a time and measure. If a value below is described as a trade-off, that trade-off is yours to make.

---

What Each Option Does

Option	Value	Why
addr	<nfs-server-ip>	The NFS server. Prefer an IP over a hostname so a DNS outage can’t stall the mount.
nfsvers	4.1	NFSv4.1 brings sessions, exactly-once semantics, and integrated locking. Use 4.2 if both your server and client support it; drop to 3 only for an appliance that offers nothing newer.
ro	(flag)	Read-only. Sovereign only reads your library, and a read-only mount means no scan, probe, or transcode can ever modify a source file.
soft	(flag)	A request that can’t be served eventually fails with an I/O error instead of retrying forever. See Why soft Matters.
timeo	100	Request timeout in tenths of a second, so 10 seconds here, against a default of 60.
retrans	2	Retries before a request gives up. Over TCP each retry waits 10 seconds longer than the last, so with timeo=100 a request against a dead server errors out after about a minute instead of never.
rsize / wsize	1048576	1 MiB transfer size. Media reads are large and sequential, and bigger transfers mean fewer round trips. The client negotiates downwards automatically if the server caps it lower.
nconnect	4	Opens four TCP connections to the server instead of one, so a large transcode read can’t monopolise the single connection a library scan also needs. Requires a Linux 5.3 or newer kernel on the host.
actimeo	60	How long file and directory attributes stay cached. Higher values cut metadata chatter during a scan; the cost is that newly added files can take up to that long to become visible.

A few options from older guides, and what they actually do:

• nolock - an NFSv3 option that disables the separate lock manager. Under NFSv4 locking is part of the protocol, so the option is a harmless no-op. Keep it only if you’re pinned to nfsvers=3.
• intr - has done nothing since Linux 2.6.25. Interruptible mounts are the default behaviour now.
• noatime - pointless alongside ro, since a read-only mount can’t write access times anyway. It matters only if you deliberately mount a share read-write.
• _netdev and bg - for /etc/fstab entries, so the system doesn’t try to mount the share before the network is up and doesn’t block boot if the NAS is down.

---

Why soft Matters

A hard mount, which is the kernel default, retries a failed request indefinitely. When the NAS goes away, a process reading from the share doesn’t get an error; it blocks in uninterruptible sleep until the share comes back. Every media probe, library scan and transcode reading from that share stops with it, so what you see looks like a hung server, not a storage outage.

This has happened in production: a wedged media mount left playback starts waiting on files that never answered. Sovereign now gives up on a start when it can’t read the file within 20 seconds. The player reports that the storage holding the file didn’t respond, and the server log names the file. That stops a viewer waiting indefinitely, but on a hard mount the stuck reads are still there underneath, and so is every scan that touches the share.

With soft, timeo, and retrans set as above, an unreachable share surfaces as I/O errors in the logs within about a minute, playback for that title fails with an error, and the rest of the server keeps serving.

Note

soft carries a real risk on read-write mounts, where a timed-out write can be lost without an error. Sovereign mounts your library ro, so that risk doesn’t apply here, but think twice before copying these options onto a read-write share.

---

Keep the Data Directory Off NFS

The recommendations on this page apply to your media library only. The Sovereign data directory (/sovereign-data) holds the SQLite database.

Danger

Never place /sovereign-data on an NFS share. SQLite depends on file locking semantics that NFS doesn’t reliably provide, so the database can be corrupted without any clean error. Keep the data directory on local disk or on block storage.

---

Applying the Options

The same mount options go in a different place on each platform.

Docker

Docker’s --mount flag splits on commas, which collides with a comma-separated NFS option string. Create the volume first, then reference it by name:

docker volume create --driver local \
  --opt type=nfs \
  --opt device=:/MEDIA/movies \
  --opt "o=addr=192.168.1.10,nfsvers=4.1,ro,soft,timeo=100,retrans=2,rsize=1048576,wsize=1048576,nconnect=4,actimeo=60" \
  sovereign_media

The full docker run invocation is on the Docker page.

Docker Compose

Declare the share as a named volume with the same driver options:

volumes:
  sovereign-data:
  nfs_movies:
    driver: local
    driver_opts:
      type: nfs
      device: ':/MEDIA/movies'
      o: 'addr=192.168.1.10,nfsvers=4.1,ro,soft,timeo=100,retrans=2,rsize=1048576,wsize=1048576,nconnect=4,actimeo=60'

Mount it into the server as nfs_movies:/media/movies:ro, as shown on the Docker Compose page.

Kubernetes

With the NFS CSI driver, the options belong in mountOptions on the StorageClass. addr and the share path move into parameters, so they aren’t repeated in the option list:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs-media
provisioner: nfs.csi.k8s.io
parameters:
  server: <nfs-server-ip>
  share: /path/to/media
reclaimPolicy: Retain
volumeBindingMode: Immediate
mountOptions:
  - nfsvers=4.1
  - ro
  - soft
  - timeo=100
  - retrans=2
  - rsize=1048576
  - wsize=1048576
  - nconnect=4
  - actimeo=60

The driver installation and the matching PersistentVolumeClaim are covered on the Kubernetes page.

Tip

nconnect is negotiated per server, per client node: the first mount of a given server wins, and later mounts of the same server reuse its connection count. On a node that mounts several shares from one NAS, set it consistently or leave it off entirely.

---

Verifying the Mount

Confirm the options the kernel applied. They aren’t always the ones you asked for, because the server negotiates transfer sizes and may refuse a version:

nfsstat -m

Then measure sequential read throughput from inside the container, which is the access pattern that matters for playback:

docker exec sovereign dd if=/media/movies/<some-large-file> of=/dev/null bs=1M count=2000

A share that can’t sustain more than the bitrate of your largest file will stutter on direct play no matter how Sovereign is configured. If that number disappoints, the network is usually the constraint before the NFS options are. Check for a duplex mismatch, a saturated uplink, or a Wi-Fi hop in the path before tuning rsize.

---

Troubleshooting

Symptom	Likely Cause
The server appears to hang until the share comes back	A hard mount against an unreachable share. Add soft, timeo, and retrans.
Playback fails but the files are clearly present	Permission denied on the export. Check root_squash or all_squash on the server, and the NFSv4 idmapping domain on both ends.
Newly added titles take a while to appear	The attribute cache. Lower actimeo, or wait for the next library sync.
Throughput is far below the link speed	rsize negotiated down, a single connection saturating one core, or the network path. Confirm with nfsstat -m, then try nconnect.
The mount fails outright at boot	The share was mounted before the network came up. Add _netdev and bg in /etc/fstab.
Titles that used to direct play now transcode	Reads are too slow. On a TV, Sovereign reads part of a file before streaming it unchanged, and transcodes when that read runs out of time. Look at the mount first.
Playback fails saying the storage didn’t respond	The share stopped answering. Sovereign gives up on a start after 20 seconds; check the NAS and the network path to it.

---

Next Steps

• Docker - plain docker run with a pre-created NFS volume
• Docker Compose - named NFS volumes and secrets in an env file
• Kubernetes - the NFS CSI driver and PersistentVolumeClaims
• Configuration Overview - full environment variable reference