ksmbd: implement Continuously Available (CA) share support
Subsystems (2)
cover ksmbd: implement Continuously Available (CA) share support
Enable the Continuously Available (CA) share infrastructure in ksmbd, allowing SMB clients to request and use persistent handles on configured shares.
Background
==========
KSMBD already has a complete in-memory durable handle v1/v2 implementation including the persistent handle data model (fp->is_persistent), protocol parsing (DH2Q with SMB2_DHANDLE_FLAG_PERSISTENT), and reconnect validation (DH2C). However, the server never advertises SMB2_GLOBAL_CAP_PERSISTENT_HANDLES or sets SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY, making this code path unreachable by clients.
Per MS-SMB2, a client can only request a persistent handle on a share that advertises SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY. This creates a
chicken-and-egg: we cannot test persistent handles without first advertising the CA capability.
Implementation Approach
=======================
I chose a top-down approach: enable the CA share capability first, validate with real clients using Samba smbtorture, and then layer on-disk state persistence in a follow-up series. This allows us to:
1. Get end-to-end protocol validation immediately with smbtorture
2. Discover client behavioral expectations before building persistence
3. Deliver incremental value (fencing + write-through + disconnect resilience) before the harder persistence work
Note: at this stage, handles survive connection/session loss but NOT full server crash. On-disk state persistence and startup recovery will be addressed in a follow-up series.
Patches
=======
Patch 1: Advertise SMB2_GLOBAL_CAP_PERSISTENT_HANDLES in negotiate
response when durable handles are enabled globally.
Patch 2: Set SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY in tree connect
response for shares with 'continuous availability = yes'.
Patch 3: Add STATUS_FILE_NOT_AVAILABLE fencing: block conflicting
opens from other clients while a persistent handle is in disconnected state (MS-SMB2 3.3.5.9).
Patch 4: Enforce FILE_WRITE_THROUGH on all opens to CA shares to
ensure data commits to stable storage (MS-SMB2 3.3.5.9).
The corresponding ksmbd-tools patch that adds the 'continuous availability' share configuration parameter is submitted:
https://github.com/namjaejeon/ksmbd-tools/pull/205
Testing
=======
Build the kernel with debug sanitizers enabled:
$ vng --build --force \
--configitem CONFIG_SMB_SERVER=y \
--configitem CONFIG_SMB_SERVER_CHECK_CAP_NET_ADMIN=y \
--configitem CONFIG_SMB_SERVER_KERBEROS5=y \
--configitem CONFIG_CIFS=y \
--configitem CONFIG_CIFS_XATTR=y \
--configitem CONFIG_CIFS_POSIX=y \
--configitem CONFIG_CIFS_ALLOW_INSECURE_LEGACY=y \
--configitem CONFIG_CIFS_DEBUG=y \
--configitem CONFIG_DEBUG_KERNEL=y \
--configitem CONFIG_KASAN=y \
--configitem CONFIG_KASAN_GENERIC=y \
--configitem CONFIG_KASAN_INLINE=y \
--configitem CONFIG_UBSAN=y \
--configitem CONFIG_LOCKDEP=y \
--configitem CONFIG_LOCK_DEBUGGING_SUPPORT=y \
--configitem CONFIG_PROVE_LOCKING=y \
--configitem CONFIG_DEBUG_SPINLOCK=yRun the CA-specific smbtorture tests inside virtme-ng:
$ vng --memory 4G --exec '
mkdir -p /tmp/ksmbd_share /tmp/ksmbd_ca /tmp/ksmbd_conf
chmod 777 /tmp/ksmbd_share /tmp/ksmbd_ca
useradd -u 4242 -M fuzz 2>/dev/null || true
ksmbd.adduser -C ksmbd-sandbox.config \
-P /tmp/ksmbd_conf/ksmbdpwd.db -a fuzz -p fuzz
ksmbd.mountd -C ksmbd-sandbox.config \
-P /tmp/ksmbd_conf/ksmbdpwd.db -n &
sleep 3
T=/path/to/samba/bin/smbtorture
$T //127.0.0.1/ca_share -U fuzz%fuzz \
smb2.durable-v2-open.persistent-open-oplock
$T //127.0.0.1/ca_share -U fuzz%fuzz \
smb2.durable-v2-open.persistent-open-lease
$T //127.0.0.1/ca_share -U fuzz%fuzz \
smb2.durable-v2-open.reopen1
dmesg | grep -E "BUG:|KASAN:|UBSAN:|WARNING:.*ksmbd"
'Key smbtorture tests for CA validation:
smb2.durable-v2-open.persistent-open-oplock
- Connects to CA share, verifies SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY
- Opens file with DH2Q + SMB2_DHANDLE_FLAG_PERSISTENT + batch oplock
- Verifies server grants persistent handle (response has flag 0x02)
- Tests various oplock level combinations with persistent flag
smb2.durable-v2-open.persistent-open-lease
- Same as above but with lease (RWH) instead of oplock
- Disconnects TCP, reconnects with DH2C, verifies handle survives
- Tests lease level combinations with persistent flag
smb2.durable-v2-open.reopen1
- Basic durable v2 disconnect/reconnect lifecycle
- Opens file with batch oplock + DH2Q
- Disconnects session, establishes new session
- Reconnects via DH2C with CreateGuid matching
- Verifies file access resumes after reconnect
smb2.durable-v2-open.purge-disconnected-rwh-with-rwh-open
- Tests conflict resolution: a new RWH open from a different client should purge (close) a disconnected durable handle with RWH lease
- Verifies the server correctly resolves lease conflicts
Results on KASAN/UBSAN/LOCKDEP kernel:
smb2.durable-v2-open.persistent-open-oplock: PASS smb2.durable-v2-open.persistent-open-lease: PASS
smb2.durable-v2-open.reopen1: PASS
smb2.durable-v2-open.purge-disconnected-rwh-with-rwh-open: PASS
Zero KASAN/UBSAN/lockdep findings
---
Yunseong Kim (4):
ksmbd: advertise SMB2_GLOBAL_CAP_PERSISTENT_HANDLES
ksmbd: set SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY in tree connect
ksmbd: add fencing for disconnected persistent handles
ksmbd: enforce write-through on CA share opens
fs/smb/server/smb2ops.c | 10 +++++----- fs/smb/server/smb2pdu.c | 33 +++++++++++++++++++++++++++++---- fs/smb/server/vfs_cache.c | 45 +++++++++++++++++++++++++++++++++++++++++++++ fs/smb/server/vfs_cache.h | 2 ++ 4 files changed, 81 insertions(+), 9 deletions(-)
---
base-commit: 4c6320e0ad400d4ee41cfde614c05a0d87f54e1b
change-id: 20260824-b4-ca-ace9405ce4b0
Best regards,
Signature · 1 line
Yunseong Kim <[email protected]>
PATCH 1/4 ksmbd: advertise SMB2_GLOBAL_CAP_PERSISTENT_HANDLES
Advertise SMB2_GLOBAL_CAP_PERSISTENT_HANDLES in the SMB2 negotiate response when durable handles are enabled globally. This tells clients that the server supports persistent handles, which is a prerequisite for Continuously Available (CA) share functionality.
The capability is gated by KSMBD_GLOBAL_FLAG_DURABLE_HANDLE (controlled by 'durable handles = yes' in ksmbd.conf) so administrators must explicitly enable it.
--- fs/smb/server/smb2ops.c | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
fs/smb/server/smb2ops.c +5 -5
@@ -270,10 +270,8 @@ void init_smb3_02_server(struct ksmbd_conn *conn)if (server_conf.flags &KSMBD_GLOBAL_FLAG_SMB3_MULTICHANNEL ) conn->vals->req_capabilities |=SMB2_GLOBAL_CAP_MULTI_CHANNEL ; -/* -* Durable handles are in-memory only. Do not advertise persistent -* handles until CA recovery and fencing are implemented. -*/ +if (server_conf.flags &KSMBD_GLOBAL_FLAG_DURABLE_HANDLE ) + conn->vals->req_capabilities |=SMB2_GLOBAL_CAP_PERSISTENT_HANDLES ; }/**
@@ -296,7 +294,9 @@ int init_smb3_11_server(struct ksmbd_conn *conn)if (server_conf.flags &KSMBD_GLOBAL_FLAG_SMB3_MULTICHANNEL ) conn->vals->req_capabilities |=SMB2_GLOBAL_CAP_MULTI_CHANNEL ; -/* See init_smb3_02_server(): persistent handles require CA recovery. */ +if (server_conf.flags &KSMBD_GLOBAL_FLAG_DURABLE_HANDLE ) + conn->vals->req_capabilities |=SMB2_GLOBAL_CAP_PERSISTENT_HANDLES ; +return 0 ; }
Signature · 1 line
2.47.3
PATCH 2/4 ksmbd: set SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY in tree connect
In reply to Yunseong KimSet the SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY capability in the tree connect response for shares configured with the 'continuous availability' option (KSMBD_SHARE_FLAG_CONTINUOUS_AVAILABILITY).
This capability is only advertised when persistent handles are also enabled globally (SMB2_GLOBAL_CAP_PERSISTENT_HANDLES). It informs clients that the share supports persistent handles, allowing them to request SMB2_DHANDLE_FLAG_PERSISTENT in DH2Q create contexts.
--- fs/smb/server/smb2pdu.c | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-)
fs/smb/server/smb2pdu.c +8 -3
@@ -2858,10 +2858,15 @@ int smb2_tree_connect(struct ksmbd_work *work) rsp->StructureSize =cpu_to_le16 (16 ); out_err1:/* -* A configured CA share is not continuously available until persistent -* open recovery, ownership fencing, and failover are implemented. +* Advertise Continuous Availability on shares configured with +* the CA flag, when persistent handles are enabled globally. */ - rsp->Capabilities =0 ; +if (share &&test_share_config_flag (share, +KSMBD_SHARE_FLAG_CONTINUOUS_AVAILABILITY ) && + conn->vals->req_capabilities &SMB2_GLOBAL_CAP_PERSISTENT_HANDLES ) + rsp->Capabilities =cpu_to_le32 (SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY ); +else + rsp->Capabilities =0 ; rsp->Reserved =0 ;/* default manual caching */ rsp->ShareFlags =SMB2_SHAREFLAG_MANUAL_CACHING ;
Signature · 1 line
2.47.3
PATCH 3/4 ksmbd: add fencing for disconnected persistent handles
In reply to Yunseong KimPer MS-SMB2 3.3.5.9, when a non-reconnect CREATE request arrives for a file that has a disconnected persistent handle from a different client, the server SHOULD fail the request with STATUS_FILE_NOT_AVAILABLE.
Add ksmbd_has_disconnected_persistent_handle() which checks the inode's open list for any persistent handle that is disconnected (fp->conn is NULL) and belongs to a different client (different ClientGUID). The same client is allowed through so it can reconnect its own handle via DH2C.
This fencing prevents data corruption by blocking conflicting opens while the original client's persistent handle is preserved for reconnection.
--- fs/smb/server/smb2pdu.c | 13 +++++++++++++ fs/smb/server/vfs_cache.c | 45 +++++++++++++++++++++++++++++++++++++++++++++ fs/smb/server/vfs_cache.h | 2 ++ 3 files changed, 60 insertions(+)
fs/smb/server/smb2pdu.c +13 -0
@@ -4427,6 +4427,19 @@ int smb2_open(struct ksmbd_work *work)if (!rc) { file_present = true; +/* +* MS-SMB2 3.3.5.9: If a non-reconnect CREATE arrives for a +* file with a disconnected persistent handle from a different +* client, fail with STATUS_FILE_NOT_AVAILABLE. +*/ +if (!dh_info.reconnected && !dh_info.replay && +ksmbd_has_disconnected_persistent_handle (path.dentry, + conn->ClientGUID)) { + rsp->hdr.Status =STATUS_FILE_NOT_AVAILABLE ; + rc = -EAGAIN ; + goto err_out; + } +if (req->CreateOptions &FILE_DELETE_ON_CLOSE_LE ) {struct xattr_dos_attrib da;
fs/smb/server/vfs_cache.c +45 -0
51 lines not on this page · raw message
fs/smb/server/vfs_cache.h +2 -0
@@ -207,6 +207,8 @@ void ksmbd_fd_put(struct ksmbd_work *work, struct ksmbd_file *fp);struct ksmbd_inode *ksmbd_inode_lookup_lock (struct dentry *d);void ksmbd_inode_put (struct ksmbd_inode *ci);bool ksmbd_close_disconnected_durable_delete_on_close (struct dentry *dentry); +bool ksmbd_has_disconnected_persistent_handle (struct dentry *dentry, +const char *client_guid);struct ksmbd_file *ksmbd_lookup_global_fd (unsigned long long id);struct ksmbd_file *ksmbd_lookup_durable_fd (unsigned long long id);void ksmbd_put_durable_fd (struct ksmbd_file *fp);
Signature · 1 line
2.47.3
PATCH 4/4 ksmbd: enforce write-through on CA share opens
In reply to Yunseong KimPer MS-SMB2 3.3.5.9, opens on Continuously Available shares MUST have FILE_WRITE_THROUGH semantics to ensure data is committed to stable storage before the operation completes. This is required because persistent handles may need to be recovered after a server failure, and any data not flushed to disk would be lost.
Force FILE_WRITE_THROUGH_LE in the CreateOptions passed to ksmbd_vfs_set_fadvise() for files opened on CA shares, which sets O_SYNC on the underlying file descriptor.
--- fs/smb/server/smb2pdu.c | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-)
fs/smb/server/smb2pdu.c +8 -1
@@ -4681,7 +4681,14 @@ int smb2_open(struct ksmbd_work *work) file_info =FILE_CREATED ; } -ksmbd_vfs_set_fadvise (filp, req->CreateOptions); +/* +* MS-SMB2 3.3.5.9: Opens on CA shares MUST have FILE_WRITE_THROUGH +* semantics to ensure data is committed to stable storage. +*/ +if (test_share_config_flag (share,KSMBD_SHARE_FLAG_CONTINUOUS_AVAILABILITY )) +ksmbd_vfs_set_fadvise (filp, req->CreateOptions |FILE_WRITE_THROUGH_LE ); +else +ksmbd_vfs_set_fadvise (filp, req->CreateOptions);/* Obtain Volatile-ID */ fp =ksmbd_open_fd (work, filp);
Signature · 1 line
2.47.3
Namjae Jeon
maintainerQuoted 15 lines · Yunseong Kim
Enable the Continuously Available (CA) share infrastructure in ksmbd, allowing SMB clients to request and use persistent handles on configured shares.
Background
==========KSMBD already has a complete in-memory durable handle v1/v2 implementation including the persistent handle data model (
fp->is_persistent), protocol parsing (DH2Q withSMB2_DHANDLE_FLAG_PERSISTENT), and reconnect validation (DH2C). However, the server never advertisesSMB2_GLOBAL_CAP_PERSISTENT_HANDLESor setsSMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY, making this code path unreachable by clients.
Quoted 4 lines
Per MS-SMB2, a client can only request a persistent handle on a share that advertises
SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY. This creates a
chicken-and-egg: we cannot test persistent handles without first advertising the CA capability.
This looks like a useful first step, but I don't think it provides CA support yet.
The handle state is still kept only in memory. The existing code can reconnect a durable handle after a connection or session loss while the server is still running, but that state is lost when ksmbd or the kernel is restarted. The server therefore can not reconstruct the open from the persistent-id or CreateGuid.
I think this should be implemented in two stages:
1. Standalone CA: add a local crash-safe journal/state store and recover the open state after a server restart, including persistent-handle, lease/oplock, ownership, and replay state.
2. Cluster CA: make the persistent open state available to the node that takes over the share, then add cluster ownership management, stale-node fencing, and cross-node failover support.
Standalone CA should be implemented and validated first. Cluster CA, including cross-node failover, should then be built on top of it. Until standalone recovery is available, advertising the persistent-handle and CA capabilities seems premature. It seems that many updates will be needed to ksmbd-tools when implementing Cluster CA.
Thanks.
Hi Namjae,
Quoted 16 lines · On Thu, 27 Aug 2026 16:54:30 +0900 Namjae Jeon <[email protected]> wrote:
Quoted 15 lines · Yunseong Kim
Enable the Continuously Available (CA) share infrastructure in ksmbd, allowing SMB clients to request and use persistent handles on configured shares.
Background
=====KSMBD already has a complete in-memory durable handle v1/v2 implementation including the persistent handle data model (
fp->is_persistent), protocol parsing (DH2Q withSMB2_DHANDLE_FLAG_PERSISTENT), and reconnect validation (DH2C). However, the server never advertisesSMB2_GLOBAL_CAP_PERSISTENT_HANDLESor setsSMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY, making this code path unreachable by clients.
Quoted 6 lines
Quoted 4 lines
Per MS-SMB2, a client can only request a persistent handle on a share that advertises
SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY. This creates a
chicken-and-egg: we cannot test persistent handles without first advertising the CA capability.This looks like a useful first step, but I don't think it provides CA support yet.
I agree, I was considering the validation aspects when I wrote this v1 draft patch series.
Quoted 5 lines
The handle state is still kept only in memory. The existing code can reconnect a durable handle after a connection or session loss while the server is still running, but that state is lost when ksmbd or the kernel is restarted. The server therefore can not reconstruct the open from the persistent-id or CreateGuid.
Thank you for summarizing this information.
Quoted 5 lines
I think this should be implemented in two stages:
1. Standalone CA: add a local crash-safe journal/state store and recover the open state after a server restart, including persistent-handle, lease/oplock, ownership, and replay state.
Okay, I've been starting "Standalone CA" supports for the next v2 patch series.
Quoted 3 lines
2. Cluster CA: make the persistent open state available to the node that takes over the share, then add cluster ownership management, stale-node fencing, and cross-node failover support.
After the standalone version has been verified and merged, I will work on it.
Quoted 6 lines
Standalone CA should be implemented and validated first. Cluster CA, including cross-node failover, should then be built on top of it. Until standalone recovery is available, advertising the persistent-handle and CA capabilities seems premature. It seems that many updates will be needed to ksmbd-tools when implementing Cluster CA.
Understood, making a solid foundation first.
Quoted 2 lines
Thanks.
Thank you!
Best regards,
Yunseong