NFS Configuration: Difference between revisions

From OSNEXUS Online Documentation Site
Jump to navigation Jump to search
← Older edit
VisualWikitext
m QSTOR-11826: Fix CLI command bugs (live-tested against 10.0.8.110): --filter replaces --client-filter, --rdonly replaces --read-only, share-client-list/share-session-list replace enum, --disable-nfs-snap-dir fixes typo, --disable-nfs-hidden-dir-browsing replaces nonexistent --enable-nfs-snap-browsing, --share-session replaces --session, note NFS mode/Kerberos are WUI-only settings
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:user_guide]]
QuantaStor provides NFS access to [[Network_Shares|Network Shares]] via two server implementations depending on the underlying storage architecture:
This section outlines how to setup your servers/hosts to access QuantaStor Network Shares via the NFS protocol.


=== Access Control / Permissions Configuration ===
* '''Scale-up (Kernel NFS)''' — Used with ZFS-based storage pools. Managed by the Linux kernel NFS server (<code>nfs-kernel-server</code>). Best for single-node and HA-paired deployments.
Unlike CIFS, access control via NFS is managed by providing access to a specific set of IP addresses. The default permissions for new Network Shares is to provide public access from all IP addresses which is shown in the QuantaStor web UI as a [public] network share client entry.  The default access control configuration is also to "squash" rights from remote "root" user accounts to the "nobody" user ID as a security precaution.  This may cause problems with some applications, and in those cases you can apply the 'no_root_squash' custom option to your network share.  Also, if you've changed it to NFS v4 then the 'no_root_squash' option may also be required unless you've manually configured the system to use Kerberos user authentication.  
* '''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.
==== no_root_squash Configuration ====
To configure the 'no_root_squash' option first go the the QuantaStor web management interface and expand the tree where you see ''Network Shares''. In this example, 'share1' and under there you'll see a host access entry called \[public\].  Right-click on that and choose 'Modify NFS Client Access...'.  In this screen input no_root_squash into the Custom NFS Export Options section.  This will allow you to modify files in the share.  Second you'll probably want to enable 'Async Writes' which will boost performance a bit.  Once you're done click 'OK'.


[[File:Modify NFS Client Access Web.jpg]]
Both modes are configured and managed through the same QuantaStor web interface (WUI) and CLI.


==== NFSv4 Mount Procedure ====
__TOC__


Continuing the above example, if you've switched from NFSv3 mode to NFSv4 you'll need to unmount the share if you already have it mounted then re-mount the share:
== Client-Side Prerequisites ==


<code>umount /media001</code>
Install the NFS client utilities on each host that will mount QuantaStor shares.


Now to mount the share with nfs4 mode, mount it like so:
=== RHEL / CentOS / Rocky Linux (8, 9) ===


<code>mount -t nfs4 192.168.0.103:/media001 /media001</code>
<pre>
sudo dnf install -y nfs-utils
sudo systemctl enable --now nfs-client.target
</pre>
 
=== Ubuntu / Debian ===
 
<pre>
sudo apt-get install -y nfs-common
</pre>
 
=== SUSE / openSUSE ===
 
<pre>
sudo zypper install -y nfs-client
sudo systemctl enable --now nfs-client.target
</pre>
 
== 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:'''
<pre>
# View system info including "Network Share Service Config" section
qs system-get
</pre>
 
'''Note:''' Changing the NFS protocol mode (v3v4, v4, v3) is performed via the WUI — there is no CLI command for this setting.
 
{| class="wikitable"
! Mode !! Description
|-
| <code>v3v4</code> (default) || Both NFSv3 and NFSv4 clients are accepted. Recommended for mixed environments.
|-
| <code>v4</code> || NFSv4 clients only. Required for Kerberos security modes.
|-
| <code>v3</code> || 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 (<code>*</code>). 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
 
{| class="wikitable"
! Field !! Description !! Example
|-
| '''Client Filter''' || IP address, CIDR subnet, domain name, netgroup, or <code>*</code> for public access || <code>192.168.10.0/24</code>
|-
| '''Access''' || Read-write (default) or read-only || <code>rw</code>
|-
| '''Root Squash''' || Map root (UID 0) to the anonymous user. Enable for untrusted clients. || Disabled (<code>no_root_squash</code>) by default
|-
| '''Secure Port''' || Require NFS requests to originate from ports < 1024 || Disabled (<code>insecure</code>) by default
|-
| '''Async Writes''' || Allow asynchronous write caching. Improves throughput; slight data-loss risk on unclean shutdown. || Disabled (<code>sync</code>) by default
|-
| '''Subtree Check''' || Verify that a requested file is within the exported subtree. Adds overhead; rarely needed. || Disabled (<code>no_subtree_check</code>) 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 || <code>wdelay,nohide</code>
|}
 
'''CLI:'''
<pre>
# 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
</pre>
 
=== 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:
 
<pre>
# 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
</pre>
 
== NFS Export Options Reference ==
 
{| class="wikitable"
! Option !! Default !! Description
|-
| <code>rw</code> / <code>ro</code> || <code>rw</code> || Read-write or read-only access.
|-
| <code>no_root_squash</code> / <code>root_squash</code> || <code>no_root_squash</code> || <code>root_squash</code> maps UID 0 on the client to the anonymous UID on the server. Enable for untrusted clients.
|-
| <code>sync</code> / <code>async</code> || <code>sync</code> || <code>sync</code> commits writes to disk before replying to the client. <code>async</code> improves write throughput but risks data loss if the server crashes before flushing.
|-
| <code>insecure</code> / <code>secure</code> || <code>insecure</code> || <code>secure</code> requires NFS requests to originate from privileged ports (< 1024). Most modern NFS clients use unprivileged ports, so <code>insecure</code> is the default.
|-
| <code>no_subtree_check</code> / <code>subtree_check</code> || <code>no_subtree_check</code> || Subtree checking verifies a requested file is within the exported directory. Adds overhead and can cause issues during renames. Disabled by default.
|-
| <code>crossmnt</code> / <code>nocrossmnt</code> || off || Allow NFS clients to follow mount points within the export. Required if the share contains nested mount points.
|-
| <code>fsid=<uuid></code> || auto || Filesystem identifier used by NFSv4. QuantaStor assigns a UUID-based fsid automatically for stable exports. Do not set manually unless specifically required.
|-
| <code>nohide</code> || off || Makes sub-mounts visible to NFS clients without requiring a separate mount command.
|-
| <code>wdelay</code> / <code>no_wdelay</code> || <code>wdelay</code> || Delays write commits slightly to allow batching when <code>sync</code> is set. Has no effect with <code>async</code>.
|}
 
== NFSv4 Specific Configuration ==
 
=== Mount Paths ===
 
NFSv4 uses a pseudo-filesystem root. QuantaStor exports all shares under <code>/export/</code>. When mounting with NFSv4, specify only the share name — do not include the <code>/export</code> prefix:


Note that we've added the ''-t nfs4'' option, and second we have excluded the ''/export'' prefix to the mount path. That's important, do not try mounting a nfs4 network share with the ''/export'' prefix. It may work for awhile but you will inevitably have problems with this.
{| class="wikitable"
! Protocol !! Mount Path Format !! Example
|-
| NFSv3 || <code>/export/<sharename></code> || <code>192.168.1.100:/export/share1</code>
|-
| NFSv4 || <code>/<sharename></code> || <code>192.168.1.100:/share1</code>
|}


=== Resolving ''Stale File Handle'' issue on older RedHat / CentOS 5.x systems ===
=== NFSv4 ID Mapping ===


We've seen some problems with the NFS client that comes with Centos 5.5 which leads to the NFS connection dropping.  After which you'll see 'Stale File Handle' errors when you try to mount the share. The quick fix for this is to login to your QuantaStor system then run this command:
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.


<code>sudo /opt/osnexus/quantastor/bin/nfskeepalive --cron</code>
Edit <code>/etc/idmapd.conf</code> on the client:
 
<pre>
[General]
Domain = localdomain
</pre>


This generates a small amount of periodic activity on the active shares so that the connections do not get dropped and you don't get stale file handles.  CentOS 5.5 has the 2.6.18 kernel which is several years old now and we don't see this problem with the newer kernels used in CentOS 6.x.
Then restart the ID mapping daemon:
<pre>
sudo systemctl restart nfs-idmapd
</pre>


=== RedHat / CentOS 6.x NFS Configuration ===
== Kerberos / Security Mode ==
To setup your system to communicate with QuantaStor over NFS you'll first need to login as root and install a couple of packages like so:


<code>yum install nfs-utils nfs-utils-lib</code>
QuantaStor supports Kerberos-based NFS security for environments that require strong authentication, data integrity checking, or wire encryption. Kerberos requires NFSv4.


Once NFS is installed you can now mount the Network Shares that you've created in your QuantaStor system.  To do this first create a directory to mount the share to.  In this example our share name is 'media001'.
=== Prerequisites ===


<code>mkdir /media001</code>
* 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 (<code>nfs/<hostname>@REALM</code>) must be installed. Contact OSNEXUS support for keytab deployment procedures.


Now we can mount the share to that directory by providing the IP address of the Quantastor system (192.168.0.103 in this example) and the name of the share with the /export prefix like so:
=== Kerberos Security Modes ===


<code>mount 192.168.0.103:/export/media001 /media001</code>
{| class="wikitable"
! Mode !! sec= option !! Description
|-
| Kerberos (auth only) || <code>sec=krb5</code> || Authenticates the user identity via Kerberos. Data is transmitted in plaintext.
|-
| Kerberos + Integrity || <code>sec=krb5i</code> || Adds per-packet integrity signing. Protects against man-in-the-middle tampering. Recommended minimum for secure environments.
|-
| Kerberos + Privacy || <code>sec=krb5p</code> || Adds full encryption of all NFS traffic. Highest security; some performance overhead.
|}


=== Ubuntu / Debian NFS Configuration ===
=== Enabling Kerberos System-Wide ===


The process for configuring NFS with Ubuntu and Debian is the same as above only the package installation is different.  To install the NFS client packages issue these commands at the console to get started then follow the same instructions given above for mounting shares for CentOS:
'''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
{| class="wikitable"
! 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:'''
<pre>
<pre>
sudo -i
# Force Kerberos on a specific share
apt-get update
qs share-modify --share=share1 --nfs-security-policy=kerberos
apt-get install nfs-common
 
# Override to AUTH_SYS for a share even if system default is Kerberos
qs share-modify --share=share1 --nfs-security-policy=system
</pre>
 
== 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 <code>.zfs/snapshot/</code> 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:'''
<pre>
# 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
</pre>
</pre>
Client access:
<pre>
ls /mnt/data/.zfs/snapshot/
# 2024-06-17-08:00:00
# 2024-06-16-08:00:00
</pre>
=== _snaps Folder (GMT Snapshot Folder) ===
Activated snapshots also appear in a <code>_snaps/</code> directory at the root of the export using GMT-formatted names, compatible with Windows Previous Versions:
<pre>
ls /mnt/data/_snaps/
# @GMT-2024.06.17-08.00.00
# @GMT-2024.06.16-08.00.00
</pre>
To disable <code>_snaps</code> visibility for a share:
<pre>
qs share-modify --share=share1 --disable-nfs-snap-dir=true
</pre>
To re-enable:
<pre>
qs share-modify --share=share1 --disable-nfs-snap-dir=false
</pre>
== Mounting on Linux Clients ==
=== NFSv3 ===
<pre>
# 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
</pre>
=== NFSv4 (Recommended) ===
<pre>
# 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
</pre>
=== Performance Mount Options ===
{| class="wikitable"
! Option !! Recommended Value !! Description
|-
| <code>rsize</code> || <code>1048576</code> || Read block size in bytes. Increase to 1 MB for sequential workloads.
|-
| <code>wsize</code> || <code>1048576</code> || Write block size in bytes. Increase to 1 MB for sequential workloads.
|-
| <code>timeo</code> || <code>300</code> || Timeout in tenths of a second before retrying an NFS request.
|-
| <code>retrans</code> || <code>3</code> || Number of retransmissions before a soft-mount returns an error.
|-
| <code>hard</code> / <code>soft</code> || <code>soft</code> || <code>hard</code> retries indefinitely (processes hang if server is unavailable). <code>soft</code> returns an error after <code>retrans</code> failures.
|-
| <code>proto=tcp</code> || recommended || Force TCP transport. More reliable than UDP for large or sustained transfers.
|-
| <code>noresvport</code> || optional || Do not require a privileged source port. Use when the server export uses the <code>insecure</code> option (the default).
|}
Example high-throughput NFSv4 mount:
<pre>
sudo mount -t nfs4 \
  -o rw,soft,timeo=300,retrans=3,rsize=1048576,wsize=1048576,proto=tcp \
  192.168.1.100:/share1 /mnt/data
</pre>
=== Kerberos Mount ===
<pre>
# 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
</pre>
Ensure a valid Kerberos ticket is present on the client before mounting:
<pre>
kinit username@REALM
klist
</pre>
== 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):'''
<pre>
Install-WindowsFeature NFS-Client
</pre>
'''Windows 10/11 Pro:'''
Control Panel → Programs → Turn Windows features on or off → Services for NFS → Client for NFS
=== Mount via Command Prompt ===
<pre>
# 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:
</pre>
'''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:'''
<pre>
# 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>
</pre>
For detailed NFSv4 state analysis (open files, client IPs, ZFS dataset mappings):
<pre>
# 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
</pre>
== Troubleshooting ==
=== Share Not Visible to Clients ===
# Verify the share has at least one NFS client rule: <code>qs share-client-list --share=share1</code>
# Confirm the NFS service is running: <code>systemctl status nfs-server</code> (scale-up) or <code>systemctl status nfs-ganesha</code> (scale-out)
# Test connectivity on port 2049: <code>nc -zv 192.168.1.100 2049</code>
# List exports visible from the server: <code>showmount -e 192.168.1.100</code>
=== Permission Denied on Mount ===
# Verify the client's IP address matches an NFS client rule on the share.
# If a CIDR rule is used, confirm the client IP is within that range.
# Check priority ordering — the highest-priority (lowest-numbered) matching rule wins.
# 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:
<pre>
sudo umount -l /mnt/data
sudo mount -t nfs4 192.168.1.100:/share1 /mnt/data
</pre>
If the error persists, verify the current fsid on the server:
<pre>
sudo exportfs -v | grep share1
</pre>
=== NFSv4 Ownership Shows as "nobody" ===
This is an ID mapping domain mismatch between client and server. Edit <code>/etc/idmapd.conf</code> on the client:
<pre>
[General]
Domain = localdomain
</pre>
Then flush the ID map cache:
<pre>
sudo systemctl restart nfs-idmapd
# Or on some systems:
sudo nfsidmap -c
</pre>
=== Poor NFS Performance ===
# Increase <code>rsize</code> and <code>wsize</code> to 1 MB (<code>-o rsize=1048576,wsize=1048576</code>).
# Use TCP transport (<code>proto=tcp</code>) instead of UDP.
# For write-heavy workloads on ZFS pools, verify the SLOG (ZIL) device is configured on the storage pool.
# If <code>sync</code> write latency is high, consider enabling <code>async</code> on the NFS client rule (trade-off: slight data-loss risk on unclean shutdown).
# Check raw network throughput between client and appliance with <code>iperf3</code>.
=== NFSv3 Portmapper Issues ===
NFSv3 requires the portmapper service (rpcbind) in addition to the NFS daemon. If NFSv3 mounts fail with "RPC: Port mapper failure":
<pre>
sudo systemctl status rpcbind
sudo systemctl enable --now rpcbind
</pre>
== 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 <code>/etc/ganesha/ganesha.conf</code>.
* 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:
<pre>
systemctl status nfs-ganesha
</pre>
For full CephFS setup, see [[Scale-out File Setup (ceph)]].
== See Also ==
* [[Network_Shares|Network Shares]] — Creating and managing NFS/SMB shares
* [[Security_Configuration|Security Configuration]] — LDAP, Kerberos, RBAC
* [[Remote-replication_(DR)|Remote Replication (DR)]] — Replicating NFS share data to a DR site
* [[Snapshot_Schedules|Snapshot Schedules]] — Automated snapshot creation for data protection
* [[Scale-out_File_Setup_(ceph)|Scale-out File Setup (ceph)]] — CephFS-backed NFS with NFS-Ganesha
[[Category:admin_guide]]

Latest revision as of 16:06, 17 June 2026

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

Retrieved from "https://wiki.osnexus.com/index.php?title=NFS_Configuration&oldid=27168"