doc/mgr/smb: document client compatibility mode

Add documentation for --client-compat parameter in 'cluster create'
command and new 'cluster update client-compat' command. This feature
enables macOS-specific SMB optimizations (fruit VFS, streams_xattr)
and can be set during cluster creation or updated for existing clusters.

Signed-off-by: Shweta Sodani <shsodani@redhat.com>

diff --git a/doc/mgr/smb.rst b/doc/mgr/smb.rst
index ad70c13948a7caa10c9f69097640cd6ecdf5ddc9..6cf26482a5832ced4bb7704053f145f969ac6238 100644 (file)
--- a/doc/mgr/smb.rst
+++ b/doc/mgr/smb.rst
@@ -55,7 +55,7 @@ Create Cluster
 
 .. prompt:: bash #
 
-   ceph smb cluster create <cluster_id> {user|active-directory} [--domain-realm=<domain_realm>] [--domain-join-user-pass=<domain_join_user_pass>] [--define-user-pass=<define_user_pass>] [--custom-dns=<custom_dns>] [--placement=<placement>] [--clustering=<clustering>] [--password-filter=<password_filter>] [--password-filter-out=<password_filter_out>]
+   ceph smb cluster create <cluster_id> {user|active-directory} [--domain-realm=<domain_realm>] [--domain-join-user-pass=<domain_join_user_pass>] [--define-user-pass=<define_user_pass>] [--custom-dns=<custom_dns>] [--placement=<placement>] [--clustering=<clustering>] [--client-compat={default|macos}] [--password-filter=<password_filter>] [--password-filter-out=<password_filter_out>]
 
 Create a new logical cluster, identified by the cluster ID value. The cluster
 create command must specify the authentication mode the cluster will use. This
@@ -100,6 +100,11 @@ clustering
     enables clustering regardless of the placement count. A value of ``never``
     disables clustering regardless of the placement count. If unspecified,
     ``default`` is assumed.
+client_compat
+    Optional. One of ``default`` or ``macos``. Controls client-specific SMB
+    features and optimizations. The ``default`` mode provides standard SMB
+    behavior with broad compatibility. The ``macos`` mode enables macOS-specific
+    optimized settings for macOS clients. If unspecified, ``default`` is assumed.
 public_addrs
     Optional. A string in the form of <ipaddress/prefixlength>[%<destination address>].
     Supported only when using Samba's clustering. Assign "virtual" IP addresses
@@ -165,6 +170,15 @@ previous example. Set three CTDB public address values and a custom placement:
         --public-address=192.168.76.112/24 \
         --placement="3 label:smb"
 
+Create a cluster for macOS clients with user authentication:
+
+.. prompt:: bash #
+
+    ceph smb cluster create mac_cluster user \
+        --define-user-pass=macuser%Passw0rd1 \
+        --client-compat=macos \
+        --placement="label:smb"
+
 
 Update Cluster QoS
 ++++++++++++++++++
@@ -216,6 +230,53 @@ Disable QoS for all shares in a cluster:
      --write-bw-limit=0
 
 
+
+Update Cluster Client Compatibility
+++++++++++++++++++++++++++++++++++++
+
+.. prompt:: bash #
+
+   ceph smb cluster update client-compat {default|macos} <cluster_id>
+
+Update the client compatibility mode for an SMB cluster. This setting controls whether client-specific SMB features and optimizations are enabled.
+
+The client compatibility mode determines how the Samba server is configured to optimize for specific client types:
+
+- ``default``: Standard SMB behavior without client-specific optimizations. This is the default mode and provides broad compatibility with all SMB clients.
+- ``macos``: Enable macOS-specific features including the Samba's fruit VFS module for proper handling of macOS metadata and optimized settings for macOS clients.
+
+When ``macos`` mode is enabled, the following features are automatically configured:
+
+- Fruit VFS module for proper handling of macOS-specific file attributes
+- Streams_xattr VFS module for extended attribute support
+
+Options:
+
+client_compat
+    One of ``default`` or ``macos``
+cluster_id
+    A short string uniquely identifying the cluster
+
+Examples
+~~~~~~~~
+
+Enable macOS compatibility mode for a cluster:
+
+.. prompt:: bash #
+
+   ceph smb cluster update client-compat macos mycluster
+
+Revert to default (standard) compatibility mode:
+
+.. prompt:: bash #
+
+   ceph smb cluster update client-compat default mycluster
+
+.. note::
+   The ``macos`` compatibility mode is recommended when the primary clients accessing the SMB shares are macOS systems. Otherwise default mode is recommended.
+
+
+
 Remove Cluster
 ++++++++++++++
 
@@ -879,6 +940,12 @@ custom_smb_global_options
     indicator that the user is aware that using this option can easily break
     things in ways that the Ceph team can not help with. This special key will
     automatically be removed from the list of options passed to Samba.
+client_compat
+    Optional. One of ``default`` or ``macos``. Controls client-specific SMB
+    features and optimizations. The ``default`` mode provides standard SMB
+    behavior with broad compatibility. The ``macos`` mode enables macOS-specific
+    features including Samba's fruit VFS module for proper handling of macOS and
+    optimized settings for macOS clients. If unspecified, ``default`` is assumed.
 
 .. warning::
    Setting the ``clustering`` option allows an administrator to choose exactly
@@ -977,6 +1044,20 @@ The following is an example of a cluster configured for standalone operation:
       hosts:
         - node6.mycluster.sink.test
 
+The following is an example of a cluster optimized for macOS clients:
+
+.. code-block:: yaml
+
+    resource_type: ceph.smb.cluster
+    cluster_id: macshare
+    auth_mode: user
+    client_compat: macos
+    user_group_settings:
+      - source_type: resource
+        ref: ug1
+    placement:
+      count: 1
+
 An example cluster resource with intent to remove:
 
 .. code-block:: yaml