From a65ca9fa79b3c45ddf4351a151e4a0073a1310ee Mon Sep 17 00:00:00 2001 From: John Mulligan Date: Thu, 2 May 2024 17:05:44 -0400 Subject: [PATCH] doc: add subsections on custom share and custom global options Document the options, the risk of using it, and the "magic key-value" pair needed to enable it. Signed-off-by: John Mulligan --- doc/mgr/smb.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/mgr/smb.rst b/doc/mgr/smb.rst index 05de3be1710a5..a19b392ad33ee 100644 --- a/doc/mgr/smb.rst +++ b/doc/mgr/smb.rst @@ -357,6 +357,21 @@ custom_dns placement Optional. A Ceph Orchestration :ref:`placement specifier `. Defaults to one host if not provided +custom_smb_share_options + Optional mapping. Specify key-value pairs that will be directly added to + the global ``smb.conf`` options (or equivalent) of a Samba server. Do + *not* use this option unless you are prepared to debug the Samba instances + yourself. + + This option is meant for developers, feature investigators, and other + advanced users to take more direct control of a share's options without + needing to make changes to the Ceph codebase. Entries in this map should + match parameters in ``smb.conf`` and their values. A special key + ``_allow_customization`` must appear somewhere in the mapping with the + value of ``i-take-responsibility-for-all-samba-configuration-errors`` as an + 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. .. _join-source-fields: @@ -465,6 +480,20 @@ cephfs provider Optional. One of ``samba-vfs`` or ``kcephfs`` (``kcephfs`` is not yet supported) . Selects how CephFS storage should be provided to the share +custom_smb_share_options + Optional mapping. Specify key-value pairs that will be directly added to + the ``smb.conf`` (or equivalent) of a Samba server. Do *not* use this + option unless you are prepared to debug the Samba instances yourself. + + This option is meant for developers, feature investigators, and other + advanced users to take more direct control of a share's options without + needing to make changes to the Ceph codebase. Entries in this map should + match parameters in ``smb.conf`` and their values. A special key + ``_allow_customization`` must appear somewhere in the mapping with the + value of ``i-take-responsibility-for-all-samba-configuration-errors`` as an + 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. The following is an example of a share: -- 2.39.5