Samba 4.25 adds SMB3 persistent handles so shares survive a server restart
Samba 4.25.0, released on 24 September 2026, ships experimental SMB3 persistent handles — the building block for transparent failover. The reward, files that stay open through an outage, comes at the cost of synchronous persistence and a share that only speaks SMB.
24 September 2026. Samba publishes 4.25.0, the first stable release of its new series. 2012. Microsoft had already shipped “continuous availability” in Windows Server 2012 using SMB3 persistent handles. 25 September 2026. Phoronix reports that Samba is catching up by bundling the same mechanism, experimentally. Why it matters: an SMB share can now survive a server restart without clients having to reopen their files — if you are willing to pay a significant storage cost.
What persistent handles actually do
A handle is the identifier an SMB client receives when it opens a file. Normally that handle is only meaningful for the lifetime of the connection: if the server restarts, the session drops and the client must reopen every file, losing locks and unfinished writes along the way.
SMB3 persistent handles change that rule. Samba persists the state of each handle — every open, update, lease and close — to durable on-disk storage, so open files can be reconstructed when clients reconnect after an outage. In practice, a virtual machine whose disk is served over SMB, or a clustered database, can tolerate a momentary node failure without having to reopen its files.
The capability is advertised to clients through the SMB2_CAP_PERSISTENT_HANDLES protocol flag. Turning it on for a share requires two settings together: the global persistent handles option and the per-share continuous availability option. One without the other does nothing.
What the client experiences is the point of the feature. During a failover, the client keeps its connection and its open files instead of hitting a network error and being forced to reopen everything. That is the difference between a workload that briefly stalls and one that has to rebuild its state from scratch — the distinction that matters for clustered filesystems and virtual machine images, where a dropped handle can corrupt an in-flight write or force a guest to remount its disk.
[global]
persistent handles = yes
persistent handles durability = full_outage
[cluster_share]
path = /srv/cluster_share
continuous availability = yes
kernel oplocks = no
kernel share modes = no
posix locking = noThe price: synchronous persistence and SMB-only access
The feature is not free, and Samba says so plainly in its release notes. Every open, update, lease and close operation must be synchronously persisted to durable storage. The result is higher latency than a conventional file server — high enough that the project recommends reserving the feature for workloads that genuinely need continuous availability, and steering clear of it on general-purpose file servers.
The second cost is less visible but just as structural. Because Samba must maintain the SMB state itself, persistent handles force a share into SMB-exclusive access. Three settings become mandatory: kernel oplocks = no, kernel share modes = no and posix locking = no. In plain terms, the share stops being interoperable with local POSIX access or NFS clients. That is an architectural decision, not a configuration detail — you give up the dual access path to gain handle survival.
That trade-off is visible in the option itself. Enabling the feature on a share means accepting that every metadata change must now land on durable storage before the operation is acknowledged — exactly the cost a general-purpose file server avoids by keeping handle state in memory. The release notes are explicit that the feature is not meant for those servers: it exists for the subset of deployments where a dropped handle is worse than a slower one, such as a hypervisor cluster or a database that cannot tolerate a lost lock.
Cluster durability, a two-speed trade-off
In a cluster, handle state lives in a volatile ctdb database replicated to every node, with a backup copy held in a persistent ctdb database. Only that backup copy lets handles survive a simultaneous failure of every node — for example a maintenance window that powers the whole cluster down, which wipes the volatile databases.
Maintaining that backup is expensive: every change to a persistent handle triggers an additional cluster-wide transaction, written to stable storage on each node. That is where the new persistent handles durability option comes in, letting the administrator pick a side between performance and durability.
full_outage is the default. The backup copy is maintained and handles survive a full-cluster outage. partial_outage drops the backup: handles survive any outage that leaves at least one node running — a node crash, a rolling restart, losing all but one node — but are lost if every node goes down at once. In exchange, every open, update, lease and close operation becomes noticeably cheaper.
The trade-off is clean and easy to reason about: if your failover leans on node redundancy rather than surviving a total shutdown, partial_outage is enough and buys back latency. If you must survive a planned full shutdown, stay on full_outage. The choice is not cosmetic — on a busy cluster, the extra cluster-wide transaction per handle change is a real, measurable write cost that lands on every node’s stable storage.
What else 4.25 ships
The branch is more than persistent handles. The vfs_aio_ratelimit VFS module gains cluster-wide coordination: per-share rate limits are now enforced as a global ceiling across the whole cluster rather than per node. A new daemon, ratelimitd, aggregates activity from each node’s smbd processes and broadcasts node-level summaries over Samba’s messaging layer — the build must be made with --with-ratelimitd.
A new VFS module, vfs_ceph_rgw, uses the librgw API to export Ceph Object Gateway buckets as SMB shares, presenting objects as a hierarchy of files and folders. JSON audit logging is tidied up — the two leading spaces before the opening brace are gone, and embedded newlines are converted to spaces. Finally, domain encryption types now default to AES for domains at functional level 2008 or higher, retiring weaker legacy cipher suites that still show up in mixed-version domains.
Verdict
If you serve virtual machine disks or clustered databases over SMB, try persistent handles in staging: this is the missing piece for genuinely transparent failover, but measure the added latency on your own workload first, because synchronous persistence is not free. If you run a general-purpose file server, leave it off: the storage overhead and the loss of POSIX/NFS access are not justified. If your cluster must survive a full shutdown, stay on persistent handles durability = full_outage; otherwise partial_outage will give back the lost latency without sacrificing the redundancy you actually rely on. In every case, remember the feature is experimental — it maps out a direction, not a stable destination, and both the durability knobs and the performance profile may still shift before it stabilises.