NFS Configuration

QuantaStor provides NFS access to Network Shares via two server implementations depending on the underlying storage architecture:

• Scale-up (Kernel NFS) — Used with ZFS-based storage pools. Managed by the Linux kernel NFS server (nfs-kernel-server). Best for single-node and HA-paired deployments.
• Scale-out (NFS-Ganesha) — Used with CephFS-based storage pools. Managed by the NFS-Ganesha userspace NFS server. Enables distributed NFS access across a Ceph cluster.

Both modes are configured and managed through the same QuantaStor web interface (WUI) and CLI.

Client-Side Prerequisites

Install the NFS client utilities on each host that will mount QuantaStor shares.

RHEL / CentOS / Rocky Linux (8, 9)

sudo dnf install -y nfs-utils
sudo systemctl enable --now nfs-client.target

Ubuntu / Debian

sudo apt-get install -y nfs-common

SUSE / openSUSE

sudo zypper install -y nfs-client
sudo systemctl enable --now nfs-client.target

NFS Protocol Version Settings

QuantaStor supports NFSv3, NFSv4, or both simultaneously (default). This setting is system-wide and applies to all shares on the appliance.

Navigation: System Management → Storage System → (right-click) → Modify Network Share Service Settings

CLI — view current NFS service configuration:

# View system info including "Network Share Service Config" section
qs system-get

Note: Changing the NFS protocol mode (v3v4, v4, v3) is performed via the WUI — there is no CLI command for this setting.

Mode	Description
v3v4 (default)	Both NFSv3 and NFSv4 clients are accepted. Recommended for mixed environments.
v4	NFSv4 clients only. Required for Kerberos security modes.
v3	NFSv3 clients only. Use when clients do not support NFSv4.

Controlling NFS Client Access

Each network share has an independent access control list. By default, shares are accessible from any IP address (*). For production environments, restrict access to specific hosts or subnets.

Adding an NFS Client Entry

Navigation: Storage Management → Network Shares → (right-click share) → Add NFS Client

Field	Description	Example
Client Filter	IP address, CIDR subnet, domain name, netgroup, or * for public access	192.168.10.0/24
Access	Read-write (default) or read-only	rw
Root Squash	Map root (UID 0) to the anonymous user. Enable for untrusted clients.	Disabled (no_root_squash) by default
Secure Port	Require NFS requests to originate from ports < 1024	Disabled (insecure) by default
Async Writes	Allow asynchronous write caching. Improves throughput; slight data-loss risk on unclean shutdown.	Disabled (sync) by default
Subtree Check	Verify that a requested file is within the exported subtree. Adds overhead; rarely needed.	Disabled (no_subtree_check) by default
Priority	When multiple rules match a client IP, the lowest-numbered rule wins (1 = highest priority, range 1–10)	1
Custom Options	Additional raw NFS export options, comma-delimited	wdelay,nohide

CLI:

# Add read-write access from a subnet (root squash is NFS default)
qs share-client-add --share=share1 --filter=192.168.10.0/24

# Add read-only access from a second subnet
qs share-client-add --share=share1 --filter=10.0.0.0/8 --rdonly=true

# Add a specific host; disable root squash explicitly
qs share-client-add --share=share1 --filter=192.168.10.50 --options=no_root_squash

# List current NFS client rules for a share
qs share-client-list --share=share1

# Modify an existing rule (enable async writes)
qs share-client-modify --share=share1 --filter=192.168.10.0/24 --async=true

# Remove a rule
qs share-client-remove --share=share1 --filter=192.168.10.0/24

Access Priority

When multiple client filter rules match a client's IP address, Linux NFS applies the most-specific (longest-prefix) match. Add a more specific rule for a single host to override a broader subnet rule:

# Specific host gets read-write + no_root_squash (more specific, matched first)
qs share-client-add --share=share1 --filter=192.168.10.100 --options=no_root_squash

# Broader subnet gets read-only
qs share-client-add --share=share1 --filter=192.168.10.0/24 --rdonly=true

NFS Export Options Reference

Option	Default	Description
rw / ro	rw	Read-write or read-only access.
no_root_squash / root_squash	no_root_squash	root_squash maps UID 0 on the client to the anonymous UID on the server. Enable for untrusted clients.
sync / async	sync	sync commits writes to disk before replying to the client. async improves write throughput but risks data loss if the server crashes before flushing.
insecure / secure	insecure	secure requires NFS requests to originate from privileged ports (< 1024). Most modern NFS clients use unprivileged ports, so insecure is the default.
no_subtree_check / subtree_check	no_subtree_check	Subtree checking verifies a requested file is within the exported directory. Adds overhead and can cause issues during renames. Disabled by default.
crossmnt / nocrossmnt	off	Allow NFS clients to follow mount points within the export. Required if the share contains nested mount points.
fsid=<uuid>	auto	Filesystem identifier used by NFSv4. QuantaStor assigns a UUID-based fsid automatically for stable exports. Do not set manually unless specifically required.
nohide	off	Makes sub-mounts visible to NFS clients without requiring a separate mount command.
wdelay / no_wdelay	wdelay	Delays write commits slightly to allow batching when sync is set. Has no effect with async.

NFSv4 Specific Configuration

Mount Paths

NFSv4 uses a pseudo-filesystem root. QuantaStor exports all shares under /export/. When mounting with NFSv4, specify only the share name — do not include the /export prefix:

Protocol	Mount Path Format	Example
NFSv3	/export/<sharename>	192.168.1.100:/export/share1
NFSv4	/<sharename>	192.168.1.100:/share1

NFSv4 ID Mapping

NFSv4 identifies file owners by string-based user/group names rather than UID/GID numbers. For correct ownership display, the NFS ID mapping domain on each client must match the server's domain.

Edit /etc/idmapd.conf on the client:

[General]
Domain = localdomain

Then restart the ID mapping daemon:

sudo systemctl restart nfs-idmapd

Kerberos / Security Mode

QuantaStor supports Kerberos-based NFS security for environments that require strong authentication, data integrity checking, or wire encryption. Kerberos requires NFSv4.

Prerequisites

• Active Directory or MIT Kerberos KDC must be reachable from the QuantaStor appliance.
• DNS and NTP must be correctly configured on the appliance.
• A valid keytab for the NFS service principal (nfs/<hostname>@REALM) must be installed. Contact OSNEXUS support for keytab deployment procedures.

Kerberos Security Modes

Mode	sec= option	Description
Kerberos (auth only)	sec=krb5	Authenticates the user identity via Kerberos. Data is transmitted in plaintext.
Kerberos + Integrity	sec=krb5i	Adds per-packet integrity signing. Protects against man-in-the-middle tampering. Recommended minimum for secure environments.
Kerberos + Privacy	sec=krb5p	Adds full encryption of all NFS traffic. Highest security; some performance overhead.

Enabling Kerberos System-Wide

Navigation: System Management → Storage System → (right-click) → Modify Network Share Service Settings → Enable Kerberos

Note: Enabling NFS Kerberos system-wide is a WUI-only operation — navigate to System Management → Storage System → (right-click) → Modify Network Share Service Settings → Enable Kerberos. Select the Kerberos mode (krb5, krb5i, or krb5p) from the NFS Security Policy dropdown.

Per-Share Security Policy

The system-level Kerberos policy can be overridden per share:

Navigation: Storage Management → Network Shares → (right-click share) → Modify → NFS Security Policy

Policy	Behavior
Inherit (default)	Uses the system-level default security policy
Kerberos	Requires Kerberos authentication for this share regardless of system default
System (AUTH_SYS)	Uses standard Unix UID/GID authentication for this share regardless of system default

CLI:

# Force Kerberos on a specific share
qs share-modify --share=share1 --nfs-security-policy=kerberos

# Override to AUTH_SYS for a share even if system default is Kerberos
qs share-modify --share=share1 --nfs-security-policy=system

Snapshot Access via NFS

QuantaStor exposes point-in-time snapshots to NFS clients through two mechanisms.

.zfs Directory (ZFS Snapshot Browsing)

When enabled, NFS clients can browse the .zfs/snapshot/ directory at the root of each share to access individual snapshots directly without administrator intervention.

Navigation: Storage Management → Network Shares → (right-click share) → Modify → Enable NFS Snapshot Browsing

CLI:

# Enable .zfs snapshot directory browsing for a share
qs share-modify --share=share1 --disable-nfs-hidden-dir-browsing=false

# Disable .zfs snapshot directory browsing
qs share-modify --share=share1 --disable-nfs-hidden-dir-browsing=true

Client access:

ls /mnt/data/.zfs/snapshot/
# 2024-06-17-08:00:00
# 2024-06-16-08:00:00

_snaps Folder (GMT Snapshot Folder)

Activated snapshots also appear in a _snaps/ directory at the root of the export using GMT-formatted names, compatible with Windows Previous Versions:

ls /mnt/data/_snaps/
# @GMT-2024.06.17-08.00.00
# @GMT-2024.06.16-08.00.00

To disable _snaps visibility for a share:

qs share-modify --share=share1 --disable-nfs-snap-dir=true

To re-enable:

qs share-modify --share=share1 --disable-nfs-snap-dir=false

Mounting on Linux Clients

NFSv3

# One-time mount
sudo mount -t nfs -o rw,soft,timeo=300,retrans=3 192.168.1.100:/export/share1 /mnt/data

# Persistent — add to /etc/fstab
192.168.1.100:/export/share1  /mnt/data  nfs  rw,soft,timeo=300,retrans=3,_netdev  0  0

NFSv4 (Recommended)

# One-time mount
sudo mount -t nfs4 -o rw,soft,timeo=300,retrans=3 192.168.1.100:/share1 /mnt/data

# Persistent — add to /etc/fstab
192.168.1.100:/share1  /mnt/data  nfs4  rw,soft,timeo=300,retrans=3,_netdev  0  0

Performance Mount Options

Option	Recommended Value	Description
rsize	1048576	Read block size in bytes. Increase to 1 MB for sequential workloads.
wsize	1048576	Write block size in bytes. Increase to 1 MB for sequential workloads.
timeo	300	Timeout in tenths of a second before retrying an NFS request.
retrans	3	Number of retransmissions before a soft-mount returns an error.
hard / soft	soft	hard retries indefinitely (processes hang if server is unavailable). soft returns an error after retrans failures.
proto=tcp	recommended	Force TCP transport. More reliable than UDP for large or sustained transfers.
noresvport	optional	Do not require a privileged source port. Use when the server export uses the insecure option (the default).

Example high-throughput NFSv4 mount:

sudo mount -t nfs4 \
  -o rw,soft,timeo=300,retrans=3,rsize=1048576,wsize=1048576,proto=tcp \
  192.168.1.100:/share1 /mnt/data

Kerberos Mount

# Mount with Kerberos integrity (krb5i)
sudo mount -t nfs4 -o sec=krb5i,rw 192.168.1.100:/share1 /mnt/data

# Mount with Kerberos encryption (krb5p)
sudo mount -t nfs4 -o sec=krb5p,rw 192.168.1.100:/share1 /mnt/data

Ensure a valid Kerberos ticket is present on the client before mounting:

kinit username@REALM
klist

Mounting on Windows Clients

Windows includes an NFS client (Services for NFS) available on Pro and Server editions.

Enable the NFS Client

Windows Server (PowerShell):

Install-WindowsFeature NFS-Client

Windows 10/11 Pro: Control Panel → Programs → Turn Windows features on or off → Services for NFS → Client for NFS

Mount via Command Prompt

# Mount share1 as drive Z:
mount \\192.168.1.100\export\share1 Z:

# Specify soft mount type
mount -o mtype=soft \\192.168.1.100\export\share1 Z:

Note: The built-in Windows NFS client supports NFSv2/v3. For NFSv4, use a third-party NFS client.

Session Monitoring

Active NFS client sessions can be viewed in the QuantaStor web interface or CLI.

Navigation: Storage Management → Network Shares → (right-click share) → Show Sessions

CLI:

# List all active NFS and SMB sessions
qs share-session-list

# Get details for a specific session
qs share-session-get --share-session=<session-id>

For detailed NFSv4 state analysis (open files, client IPs, ZFS dataset mappings):

# Summary view
sudo /opt/osnexus/quantastor/scripts/qs_nfsv4_sessions.sh

# Verbose — includes open file details
sudo /opt/osnexus/quantastor/scripts/qs_nfsv4_sessions.sh -v

# Limit output to a specific storage path
sudo /opt/osnexus/quantastor/scripts/qs_nfsv4_sessions.sh --path=/mnt/storage-pools

Troubleshooting

Share Not Visible to Clients

1. Verify the share has at least one NFS client rule: qs share-client-list --share=share1
2. Confirm the NFS service is running: systemctl status nfs-server (scale-up) or systemctl status nfs-ganesha (scale-out)
3. Test connectivity on port 2049: nc -zv 192.168.1.100 2049
4. List exports visible from the server: showmount -e 192.168.1.100

Permission Denied on Mount

1. Verify the client's IP address matches an NFS client rule on the share.
2. If a CIDR rule is used, confirm the client IP is within that range.
3. Check priority ordering — the highest-priority (lowest-numbered) matching rule wins.
4. Confirm that port 2049 (TCP/UDP) and port 111 (portmapper, NFSv3 only) are not blocked by a firewall between client and appliance.

Stale NFS File Handle

A stale file handle error occurs when the share was removed and recreated (acquiring a new UUID/fsid) while a client still held a mount. To resolve:

sudo umount -l /mnt/data
sudo mount -t nfs4 192.168.1.100:/share1 /mnt/data

If the error persists, verify the current fsid on the server:

sudo exportfs -v | grep share1

NFSv4 Ownership Shows as "nobody"

This is an ID mapping domain mismatch between client and server. Edit /etc/idmapd.conf on the client:

[General]
Domain = localdomain

Then flush the ID map cache:

sudo systemctl restart nfs-idmapd
# Or on some systems:
sudo nfsidmap -c

Poor NFS Performance

1. Increase rsize and wsize to 1 MB (-o rsize=1048576,wsize=1048576).
2. Use TCP transport (proto=tcp) instead of UDP.
3. For write-heavy workloads on ZFS pools, verify the SLOG (ZIL) device is configured on the storage pool.
4. If sync write latency is high, consider enabling async on the NFS client rule (trade-off: slight data-loss risk on unclean shutdown).
5. Check raw network throughput between client and appliance with iperf3.

NFSv3 Portmapper Issues

NFSv3 requires the portmapper service (rpcbind) in addition to the NFS daemon. If NFSv3 mounts fail with "RPC: Port mapper failure":

sudo systemctl status rpcbind
sudo systemctl enable --now rpcbind

Scale-out NFS (NFS-Ganesha)

When using CephFS-based scale-out storage pools, QuantaStor uses NFS-Ganesha instead of the kernel NFS server. Key differences from scale-up mode:

• NFS-Ganesha runs as a userspace daemon; its configuration is managed by QuantaStor at /etc/ganesha/ganesha.conf.
• Mount commands and access control entries are identical to scale-up mode.
• Provides distributed NFS access across multiple CephFS nodes for higher aggregate throughput.
• Defaults to port 2049 (same as kernel NFS).

Check the Ganesha service status on the appliance:

systemctl status nfs-ganesha

For full CephFS setup, see Scale-out File Setup (ceph).

See Also

• Network Shares — Creating and managing NFS/SMB shares
• Security Configuration — LDAP, Kerberos, RBAC
• Remote Replication (DR) — Replicating NFS share data to a DR site
• Snapshot Schedules — Automated snapshot creation for data protection
• Scale-out File Setup (ceph) — CephFS-backed NFS with NFS-Ganesha