NFS (Network File System) is the protocol Stack Harbor PaaS uses for sharing files between containers and between accounts. It is a client-server design: the server runs on the host that holds the data and exports it; the client mounts the export and works with the remote files as if they were local.
This page documents what NFS support looks like on the platform — which versions, which roles each container type can play, the default mount options, and the limitations to be aware of.
Protocol versions
| Container | NFSv3 client | NFSv3 server | NFSv4 client | NFSv4 server |
|---|---|---|---|---|
| All containers (except alpine-based) | yes | yes | yes | no |
| Shared Storage Container | yes | yes | yes | yes |
In short: every certified container can be an NFSv3 client and server, every container can be an NFSv4 client, and only the dedicated Shared Storage Container can be an NFSv4 server. Alpine-based containers do not ship with NFS server support.
Default mount options
When the platform sets up an NFS client mount, it uses these options:
- For NFSv3:
nfsvers=3,nolock,udp,soft,timeo=120,retrans=20,_netdev - For NFSv4:
nolock,soft,timeo=30,retrans=2,_netdev
The soft option is deliberate — a hard mount that blocks on a missing server can wedge an application indefinitely. The platform’s defaults trade some throughput for the ability to recover when the server is unreachable.
You can override these in custom mount configurations if your workload needs different behaviour, but the defaults are sensible for typical web application data.
Limitations
A few things to know up front, because they will bite at the wrong time otherwise:
- Files are not exportable — only directories. Wrap the file in a folder and export the folder.
- The exported path cannot be a critical system directory. The platform blocks exports starting with
/proc,/dev,/sys,/run, or paths equal to/,/bin,/lib,/lib64,/lib32,/usr,/usr/bin,/usr/sbin,/usr/lib,/usr/lib64. The exact list can vary by region. - NFS does not work with sleeping environments. A client mount on a sleeping target waits until the target wakes. A server with all client mounts asleep is also effectively idle.
- NFS does not work during live migration. A short read or write blip during a migration is expected; long mounts that span a migration window may need a retry.
NFS versus GlusterFS Native
When the storage container is a GlusterFS cluster, you can choose between NFS and GlusterFS Native as the client protocol.
- NFS — recommended for performance. Lower overhead, mature client, well-understood failure modes.
- GlusterFS Native — recommended when data safety dominates. Native replication, consistent failover behaviour.
This choice surfaces in the mount points dialog when the server is a GlusterFS cluster. For non-clustered storage, NFS is the only option.
Troubleshooting
When something is off with NFS, the dashboard’s Tasks Panel is the first place to look — most failures land there with a usable error. Beyond that:
/var/log/messageson the NFS server has the server-side errors.journalctlon the Shared Storage Container, custom Docker containers, or VPS containers has the systemd-level NFS logs.
The most common real-world failure mode is permissions: the share is exported correctly, the network is fine, but the UID inside the client container does not have write access to the folder on the server side. chown on the server, or running the client process as the right user, is usually the fix.
Where to go from here
- Mount points — adding an NFS mount from the client side.
- Storage exports — declaring an NFS export from the server side.
- Dedicated storage container — the Shared Storage Container, including its NFSv4-server role.