From c6ddd7566c59b9bf795042cc6b74c2dc7bee4352 Mon Sep 17 00:00:00 2001 From: John Mulligan Date: Fri, 4 Jul 2025 09:20:47 -0400 Subject: [PATCH] doc: document remote control in the mgr smb file It covers the remote control configuration object and the tls credential resource and source object created to support it and future tls needs. Signed-off-by: John Mulligan (cherry picked from commit e74227f3beba0d850d6094f26a2e52b51e6466b8) --- doc/mgr/smb.rst | 86 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 2 deletions(-) diff --git a/doc/mgr/smb.rst b/doc/mgr/smb.rst index 66c85296766d6..4f42ec6ee001a 100644 --- a/doc/mgr/smb.rst +++ b/doc/mgr/smb.rst @@ -450,8 +450,8 @@ custom_dns custom_ports Optional. A mapping of service names to port numbers that will override the default ports used for those services. The service names are: - ``smb``, ``smbmetrics``, and ``ctdb``. If a service name is not - present in the mapping the default port will be used. + ``smb``, ``smbmetrics``, ``ctdb``, and ``remote-control``. If a service + name is not present in the mapping the default port will be used. For example, ``{"smb": 4455, "smbmetrics": 9009}`` will change the ports used by smb for client access and the metrics exporter, but not change the port used by the CTDB clustering daemon. @@ -506,6 +506,32 @@ public_addrs host. Run ``cephadm list-networks`` for an example of these mappings. If destination is not supplied the network is automatically determined using the address value supplied and taken as the destination. +remote_control + Optional object. This object configures an SMB cluster to deploy an extra + ``remote control`` service. This service provides a gRPC server that + can be used to enumerate connected clients and disconnect clients from + shares. This service uses mTLS for authentication. By default, this service + uses port 54445. The port can be configured using the ``custom_ports`` + parameter in the cluster resource. If the service is enabled and any of the + ``cert``, ``key``, or ``ca_cert`` fields are not populated mTLS will be + disabled and the service will operate in a read-only mode. Running the + service with mTLS disabled is not recommended. + Fields: + + enabled + Optional boolean. If explicitly set to ``true`` or ``false`` this + field will enable or disable the remote control service. If left + unset the TLS fields will be checked - if the TLS fields are filled + automatically enable the service. + cert + Optional object. The fields are described in :ref:`tls source + fields` + key + Optional object. The fields are described in :ref:`tls source + fields` + ca_cert + Optional object. The fields are described in :ref:`tls source + fields` custom_smb_global_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 @@ -561,6 +587,16 @@ ref String. Required for ``source_type: resource``. Must refer to the ID of a ``ceph.smb.join.auth`` resource +.. _tls-source-fields: + +A TLS source object supports the following fields: + +source_type + Optional. Must be ``resource`` if specified. +ref + String. Required for ``source_type: resource``. Must refer to the ID of a + ``ceph.smb.tls.credential`` resource + .. note:: The ``source_type`` ``empty`` is generally only for debugging and testing the module and should not be needed in production deployments. @@ -792,6 +828,52 @@ Example: groups: [] +TLS Credential Resource +------------------------ + +TLS credential resources store copies of TLS files such as Certificates, Keys, +or CA Certificates. +A TLS credential resource supports the following fields: + +resource_type + A literal string ``ceph.smb.tls.credential`` +tls_credential_id + A short string identifying the TLS credential resource +intent + One of ``present`` or ``removed``. If not provided, ``present`` is assumed. + If ``removed`` all following fields are optional +credential_type + Required string. The value may be one of ``cert``, ``key``, or ``ca-cert``. + This value indicates what type of TLS credential the value field holds. +value: + A string containing the TLS certificate or key value in PEM encoding. +linked_to_cluster: + Optional. A string containing a cluster id. If set, the resource may only + be used with the linked cluster and will automatically be removed when the + linked cluster is removed. + +Example: + +.. code-block:: yaml + + resource_type: ceph.smb.tls.credential + tls_credential_id: mycert1 + credential_type: cert + # NOTE: The value below is truncated to make the documentation more + # consise. A real embedded certificate is expected to be valid and + # will be longer than this example. + value: | + -----BEGIN CERTIFICATE----- + MIIFDjCCA/agAwIBAgISBtFQfoXc4RmyVabbv28RClKdMA0GCSqGSIb3DQEBCwUA + MDMxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQwwCgYDVQQD + EwNSMTAwHhcNMjUwNTE5MTAyNzUyWhcNMjUwODE3MTAyNzUxWjASMRAwDgYDVQQD + EwdjZXBoLmlvMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx6fif6PQ + LOTdnO8d1JHcF7D+oB/mQlplFz4vwq/GB6Y4oWK3uCQ4PPz/qyvE4wyvc5EPhjfg + d8XNc4ajEBcSUoRj3UwWwiA4oht0SyoJIfwVGp/kF5jxHhVCLdoaaqAxv7nAghWM + 6Dg= + -----END CERTIFICATE----- + + A Declarative Configuration Example ----------------------------------- -- 2.39.5