News › linux
By The Linux Camp News, September 29, 2026
Samba 4.25.0 can preserve SMB file handles across server outages, but the experimental feature requires SMB-exclusive shares and adds synchronous metadata writes.
Samba 4.25.0, released September 24, 2026, introduces experimental SMB3 Persistent Handles to help clients recover open files after server outages. The release is the first stable version in the 4.25 series; that designation does not make this feature production-stable. Samba describes it as a building block for transparent failover, rather than a complete failover solution. 2
A file handle represents a client's open file. Samba saves the state needed to reconstruct those open files on durable storage, so a reconnecting client can retain valid handles after a restart or outage. Applications therefore need not reopen the files. Samba identifies virtual-machine storage and clustered databases as intended beneficiaries. This is recovery of open-file state, not a promise that applications experience no pause. 2
Installing the release is not sufficient to make a share use persistent handles. Check both configuration scopes: the global "persistent handles" option and the share's "continuous availability" option must be enabled. Samba advertises the feature to clients through the SMB2_CAP_PERSISTENT_HANDLES protocol capability. 2
The access model is a deployment boundary: eligible shares must be SMB-exclusive, with "kernel oplocks = no", "kernel share modes = no" and "posix locking = no". Samba says these settings disable interoperability with local POSIX access and NFS clients on the affected share. The practical inference is to inventory every access path before enabling the feature: a share also used through NFS or local file operations is not a drop-in candidate. 2
Recovery has a latency cost because each open, update, lease and close operation synchronously persists handle metadata to durable storage. In its release notes retrieved September 29, 2026, Samba calls the performance cost significant and recommends the feature only for workloads needing Continuous Availability semantics, not general-purpose file servers. The supplied notes give no benchmark, so they establish the cause of the overhead, not its size for a particular workload. 2
In a cluster, Samba replicates handle state to every node in a volatile CTDB database and also keeps a persistent backup. The distinction matters when all nodes stop: the volatile databases are lost, and only the persistent copy lets handles survive. A whole-cluster maintenance shutdown therefore exercises a different recovery requirement from losing one node. 2
The global "persistent handles durability" policy lets operators choose that failure boundary. Its default, "full_outage", maintains the backup and preserves handles through a whole-cluster outage. "partial_outage" omits the backup and preserves handles only while at least one node remains running, covering individual crashes and rolling restarts. An operational inference follows: select the policy against the maintenance procedure as well as the expected fault scenario, because stopping every node under "partial_outage" loses the handles. 2
The backup is not merely extra capacity consumption. Samba says each persistent-handle state change adds a cluster-wide transaction written to stable storage on every node. That explains why omitting it can reduce the work on the handle-operation path, but also why the cheaper policy cannot provide the same whole-cluster recovery guarantee. 2