Configure NFS mount options

NFS mount options control how the NFS client behaves when accessing your File Store. This guide explains the available options and helps you optimize mount settings for your specific workload.

Default mount options

The basic mount command for File Store is:

sudo mount -t nfs4 -o nfsvers=4.1,_netdev <endpoint>:/ /mnt/filestore

Required options:

nfsvers=4.1 - Use NFSv4.1 protocol (required for File Store)
_netdev - Tell the system this is a network filesystem

Note: File Store requires NFSv4.1 minimum. Some clients may negotiate NFSv4.2, which is compatible and will work correctly. Always specify nfsvers=4.1 in your mount commands for compatibility.

Recommended mount configuration

We recommend the following mount options for Linux:

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,nconnect=16,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2 \
  <endpoint>:/ /mnt/filestore

Recommended mount options:

nfsvers=4.1 – Use the NFSv4.1 protocol (required for File Store)
_netdev – Prevents the system from attempting to mount the file system until the network is available
nconnect=16 – Uses 16 parallel TCP connections for improved throughput.
rsize=1048576 – Sets the maximum number of bytes of data that the NFS client can receive for each READ request. Use the largest size possible to avoid diminished performance.
wsize=1048576 – Sets the maximum number of bytes of data that the NFS client can send for each WRITE request. Use the largest size possible to avoid diminished performance.
hard – Sets the recovery behavior of the NFS client after an NFS request times out, so that NFS requests are retried indefinitely until the server replies. This helps ensure data integrity.
timeo=600 – Sets the timeout value that the NFS client uses to wait for a response before retrying to 600 deciseconds (60 seconds).
retrans=2 – Sets the number of times the NFS client retries a request before attempting further recovery action.

Note: nconnect enables parallel TCP connections which can significantly improve throughput for sequential and large file workloads. However, latency-sensitive workloads with many small random I/O operations may not benefit.

Performance optimization options

Read performance

For read-heavy workloads, add these options:

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,noatime,nodiratime \
  <endpoint>:/ /mnt/filestore

Options explained:

Option	Value	Description
`rsize`	1048576	Read buffer size (1 MB)
`wsize`	1048576	Write buffer size (1 MB)
`noatime`	-	Don't update access times (reduces writes)
`nodiratime`	-	Don't update directory access times

Write performance

For write-heavy workloads:

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,async \
  <endpoint>:/ /mnt/filestore

Warning: The async option improves write performance but may result in data loss if the client crashes before writes are committed. Use with caution.

General purpose workloads

For mixed read/write workloads:

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard \
  <endpoint>:/ /mnt/filestore

Option	Description
`hard`	Retry indefinitely on server failure (prevents data corruption)

Reliability options

Preventing data loss

For maximum data safety:

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard,sync \
  <endpoint>:/ /mnt/filestore

Key options:

hard - Never give up on a request (prevents silent data loss)
sync - Synchronous writes (data is committed before returning)

Note: The sync option significantly impacts write performance. Use only when data safety is critical.

Handling server recovery

When the File Store recovers from a failure, you may see "stale file handle" errors. These options help:

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard,retry=5 \
  <endpoint>:/ /mnt/filestore

retry=5 - Retry mount attempts 5 times before failing

If you encounter stale file handles, unmount and remount:

sudo umount /mnt/filestore
sudo mount -t nfs4 -o nfsvers=4.1,_netdev <endpoint>:/ /mnt/filestore

Caching options

Client-side caching

NFSv4.1 supports client-side caching through delegations. To control caching:

# Enable aggressive caching (may see stale data)
sudo mount -t nfs4 -o nfsvers=4.1,_netdev,acdirmax=60,acregmax=60 \
  <endpoint>:/ /mnt/filestore

# Minimize caching (more consistent, less performance)
sudo mount -t nfs4 -o nfsvers=4.1,_netdev,acdirmax=3,acregmax=3,noac \
  <endpoint>:/ /mnt/filestore

Caching options:

Option	Description	Default
`acregmax`	Attribute cache timeout for files (seconds)	60
`acdirmax`	Attribute cache timeout for directories (seconds)	60
`noac`	Disable attribute caching entirely	-

Warning: Disabling caching (noac) significantly impacts performance. Use only when strong consistency is required.

Cache coherence

When multiple clients access the same files, you may need to manage cache coherence:

# For applications requiring strong consistency
sudo mount -t nfs4 -o nfsvers=4.1,_netdev,noac \
  <endpoint>:/ /mnt/filestore

Mount options for specific workloads

Web server content

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,noatime,nodiratime \
  <endpoint>:/ /mnt/filestore

Optimized for read-heavy access
No access time updates reduce writes

Database files (not recommended)

While File Store can be used for database storage, it's not recommended for high-performance databases. If you must:

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard,sync \
  <endpoint>:/ /mnt/filestore

Synchronous writes ensure data consistency
Consider using block storage instead for better performance

Media streaming

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,noatime \
  <endpoint>:/ /mnt/filestore

Large buffer sizes for streaming
No access time updates

Development and CI/CD

sudo mount -t nfs4 -o nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard,noserverino \
  <endpoint>:/ /mnt/filestore

noserversino - Use client-generated inode numbers (better for some build tools)

Persistent mount configuration

To make mount options persistent across reboots, add them to /etc/fstab:

# Edit /etc/fstab with your preferred options
sudo tee -a /etc/fstab <<EOF
<endpoint>:/ /mnt/filestore nfs4 \
  nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,noatime,nodiratime,hard 0 0
EOF

Test the fstab entry:

sudo mount -a

Verifying mount options

To see the current mount options:

mount | grep filestore

Or for more detail:

cat /proc/mounts | grep filestore

Troubleshooting

Mount fails with "invalid argument"

If you see this error:

mount.nfs4: invalid argument

Check that:

You're using nfsvers=4.1 (NFSv4.0 is not supported)
The endpoint IP is correct
The export path is / (root)

Slow performance

If performance is slow:

Check current mount options:
```
mount | grep filestore
```
Verify rsize/wsize are set to 1048576 (1 MB)
Check if sync is enabled (removes for better performance)
Monitor network latency:
```
ping <endpoint>
```

Stale file handles

If you see "stale file handle" errors after a File Store recovery:

Close all open files

Unmount and remount:

sudo umount /mnt/filestore
sudo mount -t nfs4 -o nfsvers=4.1,_netdev <endpoint>:/ /mnt/filestore

Summary of recommended options

Workload Type	Recommended Options
General purpose	`nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard`
Read-heavy	`nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,noatime,nodiratime`
Write-heavy	`nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard`
Maximum safety	`nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard,sync`
Multiple clients	`nfsvers=4.1,_netdev,rsize=1048576,wsize=1048576,hard,noac`

evroc User Documentation