Qadmin: New page: NFS+SMB cross-protocol lock coherence, Disable Oplocks recommendation, verified results, limits and HA failover behaviour

2026-09-24T03:11:56Z

New page: NFS+SMB cross-protocol lock coherence, Disable Oplocks recommendation, verified results, limits and HA failover behaviour

New page

[[Category:admin_guide]]

This page covers file locking on a [[Network Shares|Network Share]] that NFS and SMB clients use at the same time: what each protocol provides, why the default share configuration does not keep NFS and SMB locks coherent with each other, the one setting that does, the limits measured on a scale-up pool, and what happens to locks during an HA failover.

{| class="wikitable"
! Section !! Purpose
|-
| [[#Summary|Summary]] || What is coherent in each configuration, at a glance
|-
| [[#How each protocol locks|How each protocol locks]] || NFS and SMB locking, and where each one keeps its state
|-
| [[#Why the default configuration is not coherent across protocols|Why the default configuration is not coherent across protocols]] || SMB leases, client-side lock caching, and what goes wrong
|-
| [[#Configuring a share for NFS and SMB access|Configuring a share for NFS and SMB access]] || The Disable Oplocks setting, from the WUI and the CLI
|-
| [[#Verified behaviour|Verified behaviour]] || The lock conflict matrix and the concurrent-writer results
|-
| [[#Limits|Limits]] || Lock rates and lock counts measured on a scale-up pool
|-
| [[#Locks and HA failover|Locks and HA failover]] || Why held locks do not survive a pool failover
|-
| [[#Checking lock state on the appliance|Checking lock state on the appliance]] || Seeing which locks and leases the server actually holds
|}

== Summary ==

Byte-range locking works within each protocol on every share: an NFS client's lock blocks other NFS clients, and an SMB client's lock blocks other SMB clients. Locking '''across''' the two protocols -- an NFS client and an SMB client locking the same file -- is only coherent when oplocks are disabled on the share.

{| class="wikitable"
! Share configuration !! NFS vs NFS !! SMB vs SMB !! NFS vs SMB !! SMB reads see NFS writes !! Locks survive HA failover
|-
| Default (oplocks on) || Yes || Yes || '''No''' || '''No''' -- an SMB client can keep serving cached data || No
|-
| '''Disable Oplocks''' ticked || Yes || Yes || Yes || Yes || No
|}

'''If a share is accessed over both NFS and SMB, and any application relies on locking or on seeing the other protocol's writes promptly, tick Disable Oplocks on that share.''' Shares used by one protocol only do not need it and are faster without it.

== How each protocol locks ==

{| class="wikitable"
! Protocol !! Locking mechanism !! Where the server keeps it
|-
| NFSv3 || Byte-range locks through the separate NLM protocol (<code>lockd</code>/<code>statd</code>) || Kernel POSIX locks on the pool's file system
|-
| NFSv4.x || Byte-range locks as part of the protocol, plus delegations that let a client cache a file || Kernel POSIX locks, with client state tracked by <code>nfsdcld</code>
|-
| SMB2/SMB3 || Byte-range locks, share modes, and oplocks/leases that let a client cache a file || Samba's lock database, mirrored to kernel locks on the file system (<code>posix locking = yes</code>)
|}

All of these are advisory to a POSIX application: they protect data only when every writer takes a lock. SMB byte-range locks are enforced against other SMB clients' reads and writes by Samba, but not against NFS I/O.

Because Samba mirrors each SMB byte-range lock into a kernel lock, and the kernel NFS server takes kernel locks too, the two protocols see each other's locks -- '''provided the SMB lock actually reaches the server.''' That condition is what the default configuration breaks.

== Why the default configuration is not coherent across protocols ==

By default a share has oplocks on and Samba grants SMB2/SMB3 '''leases'''. A client holding a write-caching lease is allowed to process byte-range locks locally, without sending them to the server, because it believes no one else has the file open. Samba grants that lease when it sees no other SMB opens, and Samba cannot see NFS opens: its <code>kernel oplocks</code> setting is off by default, so an NFS client opening or locking the file does not break the lease.

The result, measured on a scale-up pool with Linux NFSv4.2 and SMB 3.1.1 clients:

* '''An SMB lock is invisible to NFS.''' While an SMB client held a write lock on a range, the server recorded no lock at all -- neither in Samba's lock table nor in the kernel -- and an NFS client locked the same range successfully.
* '''An NFS lock is invisible to SMB.''' The NFS lock was a real kernel lock on the server, but the SMB client granted its own conflicting lock locally and never asked.
* '''Updates are lost silently.''' One NFS writer and one SMB writer each incremented a shared counter 500 times, both taking a proper lock around every update. The file ended at 926 instead of 1000, and neither application saw an error.
* '''Reads go stale.''' An SMB client that had read a file kept returning the old contents after an NFS client rewrote it, even on a fresh open.
* '''Clients fail when the lease finally breaks.''' With several writers on each protocol, the SMB client tried to push its locally held locks to the server when a lease was broken, and the server refused them because an NFS client held the same range. Applications then saw <code>EIO</code> on unlock, or hung waiting on a lock.

The SMB protocol allows any client holding a write-caching lease to handle byte-range locks locally, Windows clients included. Only Linux clients were tested, but nothing in this behaviour is specific to them.

== Configuring a share for NFS and SMB access ==

With oplocks disabled, Samba grants no oplock or lease, so every SMB lock goes to the server, Samba mirrors it into a kernel lock, and NFS and SMB clients block each other correctly. SMB clients also stop caching file data, so they read what an NFS client wrote.

=== From the web interface ===

{{Navigation|Storage Management → Network Shares → ''select a Network Share'' → Network Share → Modify ''(toolbar)'' → CIFS/SMB Settings ''(tab)''}}

Under '''CIFS/SMB Advanced Options''', tick '''Disable Oplocks''' and click '''OK'''. The same checkbox is on the CIFS/SMB Settings tab of the Create Network Share dialog. See [[Network Shares#CIFS/SMB Settings tab|Network Shares]] for the other options on that tab.

A lease granted before the change is not revoked by it. In testing, SMB clients were reconnected after changing the setting; do the same -- or make the change in a quiet period -- before relying on it.

=== From the CLI ===

<code>[[QuantaStor CLI Command Reference#share-modify|qs share-modify]] --share=<share> --cifs-options=oplocks=no</code>

To return the share to the default, remove the option with a leading tilde: <code>--cifs-options=~oplocks</code>.

Disabling oplocks also stops Samba granting SMB2/SMB3 leases, so no separate lease setting is needed.

=== The cost ===

Disabling oplocks removes SMB client-side caching, so SMB I/O on the share makes more round trips to the server. In the concurrent-writer test above, 500 locked updates from the SMB client took 4.7 seconds with oplocks disabled against 3.4 seconds with the default -- the default being faster precisely because it was not sending its locks to the server. The effect on large sequential transfers is smaller than on small, lock-heavy or metadata-heavy workloads. NFS performance is unaffected.

This is why the setting is per share rather than system-wide: keep oplocks on for shares that only SMB clients use.

== Verified behaviour ==

The results below were measured on an HA pair of scale-up nodes with a ZFS pool on a shared JBOD, using two Linux clients, each mounting the share over NFSv4.2 and SMB 3.1.1. One client held a lock on bytes 100-149 of a file while the other attempted a conflicting lock.

=== Lock conflict matrix, with Disable Oplocks ticked ===

{| class="wikitable"
! Held by !! Attempted by !! Overlapping write lock !! Read lock vs read lock !! Write lock vs held read lock !! Last held byte (149) !! Adjacent byte (150)
|-
| NFS || NFS || Refused || Granted || Refused || Refused || Granted
|-
| NFS || SMB || Refused || Granted || Refused || Refused || Granted
|-
| SMB || NFS || Refused || Granted || Refused || Refused || Granted
|-
| SMB || SMB || Refused || Granted || Refused || Refused || Granted
|}

Every result is the correct one. With the default configuration, the NFS/NFS and SMB/SMB rows are identical, but both cross-protocol rows grant every conflicting lock.

=== Concurrent writers ===

Each writer repeatedly locks an 8-byte counter at the start of a shared file, reads it, writes back the value plus one, flushes, and unlocks. Any lost update means two writers held the lock at once.

{| class="wikitable"
! Share configuration !! Writers !! Updates expected !! Final value !! Lost
|-
| Default || 1 NFS + 1 SMB || 1,000 || 926 || '''74'''
|-
| Disable Oplocks || 1 NFS + 1 SMB || 1,000 || 1,000 || 0
|-
| Disable Oplocks || 4 NFS + 4 SMB, across two client hosts || 2,400 || 2,400 || 0
|-
| ''Control: no locking at all'' || 4 NFS + 4 SMB || 2,400 || 1,569 || 831
|}

The control row shows that the test does detect concurrent updates when locking is absent.

=== Share modes are not enforced against NFS ===

SMB share modes -- a Windows application opening a file with deny-write or deny-read -- are enforced by Samba among SMB clients only. The share's <code>kernel share modes</code> setting is off, so Samba does not pass share modes to the kernel, and an NFS client is not blocked by an SMB client's deny mode. This follows from the setting and was not separately tested. Applications that coordinate through share modes rather than byte-range locks should not rely on them across protocols.

== Limits ==

These figures come from the lab system above -- six-vCPU virtual machines on a single network segment -- and show scaling behaviour rather than a ceiling for production hardware. All were measured with Disable Oplocks ticked, so every lock went to the server.

{| class="wikitable"
! Measurement !! NFS !! SMB !! Notes
|-
| Lock + unlock pairs per second, one process || about 790 || about 850 || Bound by the network round trip, not the server
|-
| Lock + unlock pairs per second, 16 processes on two hosts sharing one file || colspan="2" | about 2,660 combined || The server was not saturated; throughput scales with the number of clients
|-
| Time for one process to take N locks on one file, all held at once || 10,000 in 13 s; 50,000 in 322 s || 10,000 in 36 s; 50,000 did not complete in 10 minutes || See below
|}

'''Keep the number of locks held on a single file to around 10,000 or fewer.''' On both protocols the cost of adding a lock grows with the number already held on that file, so acquisition slows sharply beyond that point. SMB is affected more: Samba processes a file's lock list on one CPU core, which was fully busy during the 50,000-lock run. The limit applies per file, not per share, so spreading locks across files avoids it.

An NFS client that holds a file open with no other client using it may be given a delegation and process its locks locally at a far higher rate. That is safe, because the server recalls the delegation when another client opens the file. It does mean single-client lock benchmarks over NFS overstate the rate that contended access achieves.

== Locks and HA failover ==

'''Byte-range locks, NFS and SMB alike, do not survive an HA pool failover.''' After the pool moves to the other node, another client can immediately take a lock that the previous holder still believes it owns, and the previous holder is not told.

* '''NFS.''' The node taking over the pool does not start an NFSv4 grace period for it, and has no record of the clients that held locks on the other node, so a client's attempt to reclaim its locks is refused. A Linux client logs <code>NFS: <server>: lost N locks</code> in its kernel log; the application itself is not told. [[NFS Configuration#NFS over an HA storage pool|NFS over an HA storage pool]] describes the NFS side of a failover in full.
* '''SMB.''' SMB sessions and open files are re-established after the failover, but byte-range locks are not carried over, and the client's attempt to re-take them can fail. The application is not notified.

Client I/O resumes on its own after the move: in testing, both NFS and SMB writers stalled for about 53 seconds during a manual failover and then continued without errors. Applications that use locks for correctness -- databases on file shares, shared project files, lock-file schemes -- need to handle a failover by reopening files and re-acquiring their locks, or be stopped before a planned failover. See [[HA Cluster Setup (JBODs)]] for configuring and triggering failover.

== Checking lock state on the appliance ==

To see what the server actually holds -- the quickest way to tell whether SMB locks are reaching it -- run these on the node that currently owns the pool:

<pre style="font-size: smaller">
smbstatus -L # SMB open files, with their oplock or lease level
smbstatus -B # SMB byte-range locks
stat -c %i <file> # the file's inode number
grep ":<inode> " /proc/locks # kernel locks on that file, from NFS and from Samba
</pre>

With Disable Oplocks ticked, <code>smbstatus -L</code> shows <code>NONE</code> in the Oplock column and an SMB client's lock appears in <code>/proc/locks</code> as an <code>OFDLCK</code> entry beside any NFS <code>POSIX</code> locks. With the default configuration an SMB client shows <code>LEASE(RWH)</code> and its locks appear nowhere on the server.

To confirm the setting Samba is using for a share:

<pre style="font-size: smaller">
testparm -s --section-name=<share>
</pre>

A share with Disable Oplocks ticked lists <code>oplocks = No</code>.

== Related pages ==

* [[Network Shares]] -- creating shares and every option on the CIFS/SMB Settings tab
* [[NFS Configuration]] -- the NFS server, protocol versions, and NFS over an HA storage pool
* [[HA Cluster Setup (JBODs)]] -- HA storage pools and failover
* [[Scale-up HA Storage Pool Troubleshooting]] -- diagnosing failover problems
* [[QuantaStor CLI Command Reference#share-modify|QuantaStor CLI Command Reference]] -- <code>share-modify</code> and its <code>--cifs-options</code> argument

----
<small>''Verified against QuantaStor 6.9.0.''</small>

Multi-protocol File Locking - Revision history

Qadmin: New page: NFS+SMB cross-protocol lock coherence, Disable Oplocks recommendation, verified results, limits and HA failover behaviour