From fa4f9c1f8184ff9041d23300cbe53d7f244698a3 Mon Sep 17 00:00:00 2001 From: John Mulligan Date: Fri, 28 Mar 2025 11:56:12 -0400 Subject: [PATCH] doc/mgr/smb: document the new set of smb mgr module options Document the new --results and --password-filter{,-out} options. These options are added for show and apply but also for cluster {create,rm} as these take and emit these values too. Signed-off-by: John Mulligan --- doc/mgr/smb.rst | 87 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 5 deletions(-) diff --git a/doc/mgr/smb.rst b/doc/mgr/smb.rst index 3252c485a9a..68f6306d776 100644 --- a/doc/mgr/smb.rst +++ b/doc/mgr/smb.rst @@ -55,7 +55,7 @@ Create Cluster .. code:: bash - $ ceph smb cluster create {user|active-directory} [--domain-realm=] [--domain-join-user-pass=] [--define-user-pass=] [--custom-dns=] [--placement=] [--clustering=] + $ ceph smb cluster create {user|active-directory} [--domain-realm=] [--domain-join-user-pass=] [--define-user-pass=] [--custom-dns=] [--placement=] [--clustering=] [--password-filter=] [--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 @@ -101,16 +101,40 @@ public_addrs Supported only when using Samba's clustering. Assign "virtual" IP addresses that will be managed by the clustering subsystem and may automatically move between nodes running Samba containers. +password_filter + One of ``none`` or ``base64``. If the filter is ``none`` the password + values on the command line are assumed to be plain text. If the filter is + ``base64`` the password values are assumed to be obscured with + base64 encoding the string. If ``--password-filter-out`` is not specified + this filter will also be applied to the output. +password_filter_out + One of ``none``, ``base64``, or ``hidden``. If the filter is ``none`` the + password fields in the output are emitted as plain text. If the filter is + ``base64`` password fields will be obscured by base64 encoding the + string. If the filter is ``hidden`` the password values will be replaced + by a invalid generic replacement string containing only asterisks. Remove Cluster ++++++++++++++ .. code:: bash - $ ceph smb cluster rm + $ ceph smb cluster rm [--password-filter=] Remove a logical SMB cluster from the Ceph cluster. +Options: + +cluster_id + A ``cluster_id`` value identifying a cluster resource. +password_filter + One of ``none``, ``base64``, or ``hidden``. If the filter is ``none`` the + password fields in the output are emitted as plain text. If the filter is + ``base64`` password fields will be obscured by base64 encoding the + string. If the filter is ``hidden`` the password values will be replaced + by a invalid generic replacement string containing only asterisks. + + List Clusters ++++++++++++++ @@ -190,15 +214,68 @@ command, for example: $ ceph smb apply -i /path/to/resources.yaml +In addition to the resource specification the ``apply`` sub-command accepts +options that control how the input and output of the command behave: + +.. code:: bash + + $ ceph smb apply [--format=] [--password-filter=] [--password-filter-out=] -i + +Options: + +format + One of ``json`` (the default) or ``yaml``. Output format can be + selected independent of the input format. +password_filter + One of ``none`` or ``base64``. If the filter is ``none`` the password + fields in the input are assumed to be plain text. If the filter is + ``base64`` the password fields are assumed to be obscured with + base64 encoding the string. If ``--password-filter-out`` is not specified + this filter will also be applied to the output. +password_filter_out + One of ``none``, ``base64``, or ``hidden``. If the filter is ``none`` the + password fields in the output are emitted as plain text. If the filter is + ``base64`` password fields will be obscured by base64 encoding the + string. If the filter is ``hidden`` the password values will be replaced + by a invalid generic replacement string containing only asterisks. +input + A file name or ``-`` to use stdin. + + Resources that have already been applied to the Ceph cluster configuration can be viewed using the ``ceph smb show`` command. For example: .. code:: bash - $ ceph smb show [...] + $ ceph smb show ceph.smb.cluster.cluster1 + +The ``show`` command can show all resources, resources of a given type, or specific +resource items. Options can be provided that control the output of the command. + +.. code:: bash + + $ ceph smb show [resource_name...] [--format=] [--results=] [--password-filter=] + +Options: -The ``show`` command can show all resources of a given type or specific -resources by id. ``resource_name`` arguments can take the following forms: +resource_name + One or more strings specifying a resource or resource type. See description below. +format + One of ``json`` (the default) or ``yaml``. +results + One of ``collapsed`` (the default) or ``full``. When set to ``collapsed`` + the output of the command will show only the resource JSON/YAML of + a single item if a single item is found. When set to ``full`` even if a + single item is found the output will always include a wrapper object like + (in pseudo-JSON): ``{"resources": [...Resource objects...]}``. +password_filter + One of ``none``, ``base64``, or ``hidden``. If the filter is ``none`` the + password fields in the output are emitted as plain text. If the filter is + ``base64`` password fields will be obscured by base64 encoding the + string. If the filter is ``hidden`` the password values will be replaced + by a invalid generic replacement string containing only asterisks. + +``resource_name`` arguments can take the following forms: - ``ceph.smb.cluster``: show all cluster resources - ``ceph.smb.cluster.``: show specific cluster with given cluster id -- 2.39.5