Introduced in OneFS 9.14, Durable Handles are a feature of the SMB2 and SMB3 protocols in which, when a client opens a file, it receives an opaque file handle that can be marked as durable. A durable handle allows the open file state to survive a temporary client disconnect, such as a brief network glitch, transient cluster interruption, wi‑fi connectivity drop, or client sleep event, enabling the SMB client to reconnect and reclaim the same handle within a server-defined grace period. From the application’s perspective, the file remains open and normal I/O continues without errors or forced reopens. Durable handles are requested by the client at open time using specific CREATE request contexts, such as SMB2_CREATE_DURABLE_HANDLE_REQUEST and the corresponding reconnect variants.
Durable file handle support in OneFS 9.14 and later provides the following attributes and benefits:
| Attribute | Details |
| Availability | Supported with SmartConnect static IP pools in OneFS 9.14. |
| Client | Supports v2 Durable Handles (SMB 3+ dialects). |
| Context | Client can reconnect to the same file without losing its context. |
| Cost | Lightweight, avoiding the performance overhead of full Continuous Availability. |
| Persistence | Allows the cluster to keep the SMB file handle alive briefly. |
Under the hood, OneFS durable handles employ the following fundamental architecture:
At the protocol level, a durable handle is established when the client sends an SMB CREATE request that includes a durable handle create context. If the server and share configuration permit durable handles, the cluster’s SMB server marks the open accordingly and returns a persistent handle identifier along with a reconnect token, such as a create GUID, which can later be used to reclaim the handle. During normal operation, the client performs READ, WRITE, and locking operations using that handle over its SMB session.
If the client disconnects unexpectedly and the underlying TCP connection and SMB session are lost, the cluster retains the durable handle’s state, including open and lock information, for a defined timeout period rather than closing it immediately. When the client reconnects, it reestablishes an SMB session and tree connection and issues a new CREATE request with a durable handle reconnect context that includes the original token:
If the cluster still holds the handle and the reconnect request matches, it rebinds the durable handle to the new session and I/O seamlessly resumes. If the client does not reconnect before the timeout expires, the cluster closes the open, releases any associated locks, and the handle can no longer be reclaimed.
As such, durable handles are intended to protect against short client-side outages and assume that the SMB server instance remains available. They do not survive a full-on SMB server and/or node failure unless additional high-availability mechanisms such are in place.
One such mechanism is SMB Continuous Availability (CA),a related and complimentary feature of the SMB3 protocol, which extends this model to provide high availability for clustered SMB file servers by allowing open file state and I/O to survive planned and unplanned server or node failovers.
| Focus | SMB Durable Handles | SMB Continuous Availability |
| What | Best-effort resilience to transient client connectivity issues while assuming the server remains running. | Explicitly designed to tolerate server or node failures in a clustered environment. |
| How | Stores open state locally for a limited time and is negotiated per file open. | Requires share-level configuration and supporting cluster infrastructure to persist state across nodes. |
| Where | General file access scenarios where brief network disruptions are expected, such as user desktops or laptops. | CA shares are intended for critical workloads that demand uninterrupted access through failover events. |
| Version | OneFS 9.14 onwards. | OneFS 8.0 onwards. |
| Type | Lighter weight, without the write-stability requirements of CA | Uses persistent handles. |
| Performance | Much lower performance impact. | Higher performance cost due to stable write requirement. |
| Realm | Granted only when client connects through a static IP pool in OneFS 9.14. | Works with both dynamic and static IP pools. |
| Status | Enabled by default. | Disabled by default. |
PowerScale has supported Continuous Availability since OneFS 8.0, and it is enabled at the share level by marking a share as continuously available, relying on persistent handle and lease state that is stored or replicated in a highly available, cluster-consistent manner. This allows the SMB server resource to move to another node during a failover while clients transparently reconnect and continue I/O without application disruption. CA combines persistent or durable v2 durable handles with clustering and witness mechanisms to coordinate reconnection and ensure strict data consistency semantics across nodes.
In practice, durable handles and SMB3 continuous availability differ in scope and guarantees. Durable handles provide best-effort resilience to transient client connectivity issues while assuming the server remains running, whereas CA is explicitly designed to tolerate server or node failures in a clustered environment. Durable handles store open state locally for a limited time and are negotiated per file open, while CA requires share-level configuration and supporting cluster infrastructure to persist state across nodes. As a result, durable handles are commonly used for general file access scenarios where brief network disruptions are expected, such as user desktops or laptops, while CA shares are intended for critical workloads like Hyper‑V or SQL Server over SMB that demand uninterrupted access through failover events.
On a PowerScale cluster running OneFS 9.14 or later, durable handles are supported as part of standard SMB2 and SMB3 operation to help clients recover from short connectivity disruptions. SMB3 continuous availability is provided through CA-enabled SMB shares, where OneFS ensures that file, handle, and share state are protected across service or node failovers within the cluster, allowing appropriately capable SMB3 clients to resume I/O transparently. As such, all CA shares make use of durable or persistent handle semantics internally, but durable handles alone do not imply continuous availability; CA represents a share-level, cluster-integrated high-availability capability, whereas durable handles are a file open resiliency mechanism.
Enabled by default in OneFS 9.14, durable file handles are only granted to clients that request them via an SMB session established from a static-IP SmartConnect network pool. Note that durable file handles on dynamic pools will be supported in a future OneFS release.
Durable handles can be configured on a per-share basis from the CLI, WebUI and platform API, as follows:
During creation:
# isi smb shares create --durable-handle-enabled <true | false>
Or from the OneFS WebUI under Protocols > Windows sharing (SMB) > SMB shares > Create a SMB share:
Durable handles support can modified on an existing share:
# isi smb shares modify --durable-handle-enabled <true | false>
A timeout can be configured with the ‘–ca-timeout’ flag, and the default duration is 120 seconds:
# isi smb shares create --durable-handle-enabled true --ca-timeout
As noted previously, SMB durable handles are enabled by default in OneFS 9.14:
# isi smb settings shares view | grep -i dura Durable Handle Enabled: Yes
They can also be easily disabled globally as follows:
# isi smb settings shares modify --durable-handle-enabled 0 # isi smb settings shares view | grep -i dura Durable Handle Enabled: No
Or from the WebUI under Protocols > Windows sharing (SMB) > Default share settings:
Additionally, Continuous Availability can also now be enabled or disabled on an existing share as follows:
# isi smb shares modify --continuously-available <true | false>
When enabling CA on a share, the following confirmation popup is displayed, advising of the potential write performance implications when activating Continuous Availability:
Note that, due to the IP allocation cache and timer of entry, a change in IP allocation method from dynamic to static or vice versa can potentially result in up to a five minute delay before durable handles configuration changes (enable or disable) are enacted.
If and when it comes to investigating and troubleshooting durable handles, the /var/log/lwiod.log is a good place to start. Beyond that, network packet captures can also be extremely helpful at understanding and verifying the SMB sessions at a protocol request level. When examining a pcap of an SMB session with a network sniffing tool (e.g. Wireshark), the presence of the ‘SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2’ request with a ‘Persistent Handle’ flag of value zero (“0”) indicates that this is a Durable Handle request:
Alternatively, if the persistent handle flag contains a value of one (“1”), this indicates that the request is for a persistent handle, with the likelihood that SMB CA is involved.