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 <[email protected]>

Author: phlogistonjohn

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<tls-source-fields>`
+    key
+        Optional object. The fields are described in :ref:`tls source
+        fields<tls-source-fields>`
+    ca_cert
+        Optional object. The fields are described in :ref:`tls source
+        fields<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.
@@ -804,6 +840,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
 -----------------------------------