diff --git a/docs-xml/smbdotconf/protocol/smb3sharecaps.xml b/docs-xml/smbdotconf/protocol/smb3sharecaps.xml
new file mode 100644
index 000000000000..add89f1644a9
--- /dev/null
+++ b/docs-xml/smbdotconf/protocol/smb3sharecaps.xml
@@ -0,0 +1,202 @@
+
+
+
+ The SMB3 protocol introduced the SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY
+ flag. It means clients can have different expectations from the
+ server (or cluster of servers).
+
+
+
+ Note: this option only applies to disk shares.
+
+
+ In a ctdb cluster shares are continuously available,
+ but windows clients mix this with the global persistent
+ handles support.
+
+
+ Persistent handles are requested if
+ SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY is present
+ even without SMB2_CAP_PERSISTENT_HANDLES.
+
+
+ And SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY is
+ required for SMB2_SHARE_CAP_CLUSTER to have
+ an effect.
+
+
+ So we better don't announce this by default
+ until we support persistent handles.
+
+
+ The option
+ can be used to force the announcement of SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY.
+
+
+
+ Warning: only use this if you know what you are doing!
+
+
+
+ smb3 share cap:CONTINUOUS AVAILABILITY = yes
+
+
+smb3 share cap:CLUSTER
+
+
+
+
+
+ The SMB3 protocol introduced the SMB2_SHARE_CAP_SCALEOUT
+ flag. It means clients can have different expectations from
+ cluster of multiple servers and alters the retry/reconnect
+ behavior.
+
+
+
+ Note: this option only applies to disk shares.
+
+
+ In a ctdb cluster we have multiple active nodes,
+ so we announce SMB2_SHARE_CAP_SCALEOUT in a cluster.
+
+
+ The option
+ can be used to disable the announcement of SMB2_SHARE_CAP_SCALEOUT,
+ even if is yes.
+
+
+
+ clustering = yes
+ smb3 share cap: SCALE OUT = no
+
+
+clustering
+
+
+
+
+
+ The SMB3 protocol introduced the SMB2_SHARE_CAP_CLUSTER
+ flag. It means clients can expect that all cluster nodes
+ provide a witness service in order to use the [MS-SWN]
+ protocol to monitor the server cluster.
+
+
+
+ Note: this option only applies to disk shares.
+
+
+ rpcd_witness is only active if
+ samba-dcerpcd8
+ is not started as on demand helper and only in a ctdb cluster.
+
+
+ So we announce SMB2_SHARE_CAP_CLUSTER only if
+ is yes and
+ is no.
+
+
+ The option
+ can be used to control the announcement of SMB2_SHARE_CAP_CLUSTER
+ independent of
+ and
+ .
+
+
+ Example to disable the announcement of SMB2_SHARE_CAP_CLUSTER:
+
+
+ clustering = yes
+ rpc start on demand helpers = no
+ smb3 share cap: CLUSTER = no
+
+
+ Example to force the announcement of SMB2_SHARE_CAP_CLUSTER:
+
+
+ smb3 share cap: CLUSTER = yes
+
+
+ Example to let Windows clients use the witness service,
+ see option
+ and USE AT YOUR OWN RISK!:
+
+
+
+ clustering = yes
+ rpc start on demand helpers = no
+ # This is the default with the above:
+ # smb3 share cap: CLUSTER = yes
+ #
+ # Use at you own risk!
+ smb3 share cap: CONTINUOUS AVAILABILITY = yes
+
+
+clustering
+rpc start on demand helpers
+smb3 share cap:CONTINUOUS AVAILABILITY
+smb3 share cap:ASYMMETRIC
+
+
+
+
+
+ The SMB3_02 protocol introduced the SMB2_SHARE_CAP_ASYMMETRIC
+ flag. It means clients alters its behavior and uses
+ isolated transport connections and witness registrations for
+ the share. It means a client may connect to different
+ cluster nodes for individual shares and
+ net witness share-move can be used
+ to control the node usage.
+
+
+
+ Note: this option only applies to disk shares.
+
+
+ Shares in a ctdb cluster are symmetric by design,
+ so we don't announce SMB2_SHARE_CAP_ASYMMETRIC by default.
+
+
+ The option
+ can be used to force the announcement of SMB2_SHARE_CAP_ASYMMETRIC.
+
+
+ Example to force the announcement of SMB2_SHARE_CAP_ASYMMETRIC:
+
+
+
+ smb3 share cap: ASYMMETRIC = yes
+
+
+ Example to let Windows clients use the witness service,
+ see option
+ and USE AT YOUR OWN RISK!:
+
+
+
+ clustering = yes
+ rpc start on demand helpers = no
+ # This is the default with the above:
+ # smb3 share cap: CLUSTER = yes
+ #
+ # Use at you own risk!
+ smb3 share cap: CONTINUOUS AVAILABILITY = yes
+ smb3 share cap: ASYMMETRIC = yes
+
+
+smb3 share cap:CLUSTER
+