Samba 4.25 Adds Experimental Persistent Handles on SMB-Only Shares

Samba 4.25.0 Makes SMB3 Persistent Handles Available on Linux, Behind Two Switches​

Phoronix reported the release on September 25 and called persistent handles its most exciting addition. Samba's own 4.25.0 release notes describe the feature as experimental and as "a fundamental building block for Transparent Failover." Linuxiac put it this way: persistent handles let clients reconnect after a server restart or outage while keeping access to files they already had open.

Here is how it works. Samba writes all the handle state it needs to durable on-disk storage. When a client reconnects, Samba rebuilds the open files from that saved state, so applications can ride out a temporary server failure without reopening anything. The server advertises support through the SMB3 capability flag SMB2_CAP_PERSISTENT_HANDLES.

Nothing changes after an upgrade until an administrator turns it on. The release notes list three new smb.conf parameters. The global persistent handles option defaults to no, the per-share continuous availability option defaults to no, and the global persistent handles durability option defaults to full_outage. A share only uses persistent handles when both persistent handles and continuous availability are enabled.

Phoronix summed up the feature as "uninterrupted file access." Samba's claim is narrower. It promises reconnection and handle reconstruction after temporary failures, it calls the feature experimental, and it documents limits on what can survive, which are covered below.

Why Windows Clients Needed Persistent Handles From Samba 4.20 Onward​

This release fills a gap that Samba's own documentation pointed out two years earlier. The Samba 4.20.0 release notes added a witness service for clustered setups, with a warning that current windows client requires SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY in addition to SMB2_SHARE_CAP_CLUSTER in order to make use of the witness service. The same notes said that SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY implies the windows clients always ask for persistent handle (which are not implemented in samba yet), so that every open generates a warning on the Windows side.

That was the old situation. A Samba share could claim continuous availability to satisfy Windows' witness requirements, but it could not grant the persistent handles Windows then asked for. In Samba 4.25, the continuous availability share option is tied to real persistent-handle support. It sits behind an explicit opt-in and is marked experimental.

LinuxCompatible describes what this changes: Traditional SMB loses a client's file handles on a server restart, forcing a reopen of everything. For a file clerk opening spreadsheets, a reopen barely matters. A hypervisor keeping VM disk images open on an SMB share, or a clustered database holding its files open, has far less tolerance for that. Those are the workloads Samba names.

The Cost of Persistent Handles: SMB-Exclusive Shares and Synchronous Writes​

The first restriction is about access. Samba has to keep full SMB state for these handles, so they are only available on shares configured for SMB-exclusive access. Each affected share needs three settings:

kernel oplocks = no
kernel share modes = no
posix locking = no

According to the release notes, these settings disable interoperability with local POSIX file access and NFS clients on the affected share. That rules out a common Linux file-server layout, where the same directory tree is exported over both SMB and NFS or is used by local processes on the server. If Linux services or NFS clients also touch a share, that share is not a candidate for persistent handles. The data would need to move to a dedicated SMB-only share first.

The second restriction is performance. Samba says bluntly that Persistent Handles incur a significant performance cost. The reason is that file handle metadata is synchronously persisted to durable storage for every open, update, lease, and close operation, increasing latency compared to traditional SMB file serving. The project concludes that the feature is intended only for workloads needing continuous-availability semantics and is not recommended for general-purpose file servers. Linuxiac and LinuxCompatible report the same guidance.

Samba gives no benchmark figures for the overhead. The size of the penalty will depend on how metadata-heavy a workload is and on how fast the underlying storage can make writes durable. A VM image that is opened once and then read and written for hours sees far fewer handle-state changes than a share full of small files being opened and closed constantly. That is an inference from the documented design, not a measured result, but it explains why Samba points to long-lived-handle workloads.

Choosing full_outage or partial_outage on a CTDB Cluster​

On a clustered Samba deployment built on CTDB, Samba's clustered database layer, handle state is stored in two places. The first is a volatile CTDB database replicated to every node. The second is a backup copy in a persistent CTDB database. Samba explains that only the backup copy lets handles survive an outage of every node at once, such as a maintenance window in which the whole cluster is shut down and restarted, because that kind of outage wipes the volatile databases.

The backup copy is expensive. Each change to a persistent handle's state adds a cluster-wide transaction, and that transaction is written to stable storage on every node. The new persistent handles durability option lets administrators choose which way to lean:

The choice comes down to how the cluster is actually run. If maintenance is always done as rolling restarts and a full-cluster power-down is rare or planned for, partial_outage covers the failures that happen in practice and removes the most expensive part of the design. If the risk is a whole site losing power, only full_outage keeps handles across that event. Samba made the safer option the default.

AES-Only Kerberos Defaults Arrive for Samba AD Domains, Citing CVE-2026-20833​

The change most likely to affect Windows-heavy shops is not persistent handles. It is a Kerberos default for Samba acting as an Active Directory domain controller. The default value of kdc default domain supported enctypes now corresponds to aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96, meaning AES only, when the domain functional level is 2008 or higher. Samba says the change addresses CVE-2026-20833, and the smb.conf changes table lists it as a new default of AES encryption types "if supported by domain."

This change has been flagged since the release-candidate stage. LinuxCompatible reported that 4.25.0rc2 hardens the Kerberos KDC to AES-only encryption by default for domains at functional level 2008 or higher to close CVE-2026-20833. The release notes give the CVE identifier but do not describe the vulnerability, so its severity and root cause should be looked up in its primary record rather than assumed.

In practice, this is a default change in a domain setting, and defaults are what catch unmanaged environments off guard. An inference from the documented change: any account, keytab or legacy device in a Samba AD domain that still depends on non-AES Kerberos encryption could stop authenticating after the upgrade if it relied on the old default. Domains below the 2008 functional level do not get the new AES-only default, according to the release notes.

The final release also includes a signing change for SMB3. Among the fixes added between rc2 and final, LinuxCompatible notes that Stefan Metzmacher added a requirement that SMB3 session setup responses always be signed, and fixed a winbindd crash. The same stretch of development included persistent-handles documentation and database-layer bugs, plus a regression where smbstatus byte-range locks got broken. Persistent-handle bugs were still being fixed days before the stable release, which fits the experimental label.

Ceph RGW Shares, Cluster Rate Limits and a New Cluster Functional Level​

The other additions in Samba 4.25 mostly target storage and cluster operators.

The new vfs_ceph_rgw module uses the librgw APIs to export Ceph Object Gateway buckets as SMB shares. It shows a bucket's objects as a hierarchy of files and folders, supports standard POSIX UIDs and GIDs, and handles most basic file operations. For teams already running Ceph, this gives Windows clients a way to browse object storage as a normal SMB share. Samba's "most basic file operations" wording means applications that need full file-system semantics should be tested first.

Rate limiting in vfs_aio_ratelimit now works across a whole cluster. The vfs_aio_ratelimit module now enforces rate limits as a global ceiling across the cluster. Each share's limits are tracked separately. Coordination comes from a new daemon, ratelimitd, [which] aggregates activity from all smbd processes on its node and broadcasts summaries to other nodes. Samba must be built with --with-ratelimitd to get this feature, so whether it is available depends on how a distribution packages Samba.

Samba also adds a cluster functional level, which the project compares to Active Directory's domain and forest functional levels. New database formats and inter-node messages stay locked until an administrator raises the level, so nodes on different Samba versions can keep working together during a rolling upgrade. Samba 4.25 implements the initial level 1.0, which is currently also the only defined level. On a non-clustered server the highest supported level is always activated automatically, there is nothing to configure or maintain.

On clusters, the level is stored in cluster_level.tdb and is managed with new net clusterlevel subcommands:

1. net clusterlevel features lists the levels the installed binaries support.
2. net clusterlevel show shows the currently active level.
3. net clusterlevel showall shows each node's supported levels, the active level, and the highest level that could be activated.
4. net clusterlevel upgrade --test (the default mode) reports whether an upgrade is possible, and --apply performs it.

Raising the level is a one-way operation with no way back. Samba says it should only be done after every node is upgraded and the new version has proven itself. The current implementation also requires every node to announce exactly the same set of supported levels, which in practice means the same Samba version. A node that does not support the active level refuses to start. Samba also states that this mechanism only prepares for future upgrades and is not designed to help clusters move from pre-4.25 versions to 4.25.

A few smaller changes affect tooling and scripts. JSON audit-log lines no longer start with two spaces before the opening {, and embedded newlines are normalized to spaces. CTDB lock, PID and socket paths now sit in ctdb/ subdirectories under Samba's build-time locations. The ctdb.init script has moved to ctdb/doc/examples, and Samba describes it as essentially unmaintained and untested. The detect_init_style() function and CTDB_INIT_STYLE variable are deprecated in favour of CTDB_PLATFORM_STYLE, which may affect site-local event scripts. The getwd cache parameter has been removed, and allow dcerpc auth level connect is deprecated.

What this means for you​

Most administrators should plan the 4.25 upgrade around the Kerberos, logging and CTDB changes, and leave persistent handles switched off. Persistent handles are only worth evaluating if you run SMB-only shares that host VM images or clustered database files, where a server failover currently forces applications to reopen files, and even then only in a test environment first. Samba's own advice applies to everyone: read the release notes before upgrading.

• Leave persistent handles and continuous availability at their default of no on general-purpose file servers, because Samba says the synchronous metadata writes make the feature unsuitable for them.
• Rule out any share that NFS clients or local Linux processes also access, because the required kernel oplocks, kernel share modes and posix locking settings break that interoperability.
• On CTDB clusters, pick full_outage only if handles must survive a whole-cluster shutdown; otherwise partial_outage covers node crashes and rolling restarts at lower cost.
• Before upgrading a Samba AD domain controller at functional level 2008 or higher, find any accounts or devices that still depend on non-AES Kerberos encryption, since the new default is AES-only.
• Check log parsers and SIEM ingestion rules that depend on the old leading whitespace or multi-line content in Samba's JSON audit logs.
• Do not run net clusterlevel upgrade --apply until every node runs the same 4.25 build and has proven stable, because the level cannot be lowered.

Samba 4.25 finally lets Linux file servers grant the persistent handles that Windows clients have asked for on continuously available shares since Samba 4.20, but the release marks it as an early, costly and narrowly scoped capability. For most shops, the upgrade decision depends on the AES-only Kerberos default and the CTDB housekeeping. Persistent handles will matter for clustered VM and database storage once Samba removes the experimental label. Until then, they belong on dedicated SMB-only test shares, with a deliberate choice between full_outage and partial_outage.