From 4e897de3225aa8624c3e0188236f85f523088ea2 Mon Sep 17 00:00:00 2001 From: John Mulligan Date: Sat, 10 Feb 2024 09:06:53 -0500 Subject: [PATCH] doc/cephadm: add a file documenting the smb service Signed-off-by: John Mulligan --- doc/cephadm/services/index.rst | 1 + doc/cephadm/services/smb.rst | 205 +++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+) create mode 100644 doc/cephadm/services/smb.rst diff --git a/doc/cephadm/services/index.rst b/doc/cephadm/services/index.rst index c1da5d15f89..df8b3b42169 100644 --- a/doc/cephadm/services/index.rst +++ b/doc/cephadm/services/index.rst @@ -19,6 +19,7 @@ for details on individual services: monitoring snmp-gateway tracing + smb Service Status ============== diff --git a/doc/cephadm/services/smb.rst b/doc/cephadm/services/smb.rst new file mode 100644 index 00000000000..8ca70c5baf2 --- /dev/null +++ b/doc/cephadm/services/smb.rst @@ -0,0 +1,205 @@ +.. _deploy-cephadm-smb-samba: + +=========== +SMB Service +=========== + +.. note:: Only the SMB3 protocol is supported. + +.. warning:: + + SMB support is under active development and many features may be + missing or immature. Additionally, a Manager module to automate + SMB clusters and SMB shares is in development. Once that feature + is developed it will be the preferred method for managing + SMB on ceph. + + +Deploying Samba Containers +========================== + +Cephadm deploys `Samba `_ servers using container images +built by the `samba-container project `_. + +In order to host SMB Shares with access to CephFS file systems, deploy +Samba Containers with the following command: + +.. prompt:: bash # + + orch apply smb [--features ...] [--placement ...] ... + +There are a number of additional parameters that the command accepts. See +the Service Specification for a description of these options. + +Service Specification +===================== + +An SMB Service can be applied using a specification. An example in YAML follows: + +.. code-block:: yaml + + service_type: smb + service_id: tango + placement: + hosts: + - ceph0 + spec: + cluster_id: tango + features: + - domain + config_uri: rados://.smb/tango/scc.toml + custom_dns: + - "192.168.76.204" + join_sources: + - "rados:mon-config-key:smb/config/tango/join1.json" + include_ceph_users: + - client.smb.fs.cluster.tango + +The specification can then be applied by running the following command: + +.. prompt:: bash # + + ceph orch apply -i smb.yaml + + +Service Spec Options +-------------------- + +Fields specific to the ``spec`` section of the SMB Service are described below. + +cluster_id + A short name identifying the SMB "cluster". In this case a cluster is + simply a management unit of one or more Samba services sharing a common + configuration, and may not provide actual clustering or availability + mechanisms. + +features + A list of pre-defined terms enabling specific deployment characteristics. + An empty list is valid. Supported terms: + + * ``domain``: Enable domain member mode + +config_uri + A string containing a (standard or de-facto) URI that identifies a + configuration source that should be loaded by the samba-container as the + primary configuration file. + Supported URI schemes include ``http:``, ``https:``, ``rados:``, and + ``rados:mon-config-key:``. + +join_sources + A list of strings with (standard or de-facto) URI values that will + be used to identify where authentication data that will be used to + perform domain joins are located. Each join source is tried in sequence + until one succeeds. + See ``config_uri`` for the supported list of URI schemes. + +custom_dns + A list of IP addresses that will be used as the DNS servers for a Samba + container. This features allows Samba Containers to integrate with + Active Directory even if the Ceph host nodes are not tied into the Active + Directory DNS domain(s). + +include_ceph_users: + A list of cephx user (aka entity) names that the Samba Containers may use. + The cephx keys for each user in the list will automatically be added to + the keyring in the container. + + +Configuring an SMB Service +-------------------------- + +.. warning:: + + A Manager module for SMB is under active development. Once that module + is available it will be the preferred method for managing Samba on Ceph + in an end-to-end manner. The following discussion is provided for the sake + of completeness and to explain how the software layers interact. + +Creating an SMB Service spec is not sufficient for complete operation of a +Samba Container on Ceph. It is important to create valid configurations and +place them in locations that the container can read. The complete specification +of these configurations is out of scope for this document. You can refer to the +`documentation for Samba `_ as +well as the `samba server container +`_ +and the `configuation file +`_ +it accepts. + +When one has composed a configuration it should be stored in a location +that the Samba Container can access. The recommended approach for running +Samba Containers within Ceph orchestration is to store the configuration +in the Ceph cluster. There are two ways to store the configuration +in ceph: + +RADOS +~~~~~ + +A configuration file can be stored as a RADOS object in a pool +named ``.smb``. Within the pool there should be a namespace named after the +``cluster_id`` value. The URI used to identify this resource should be +constructed like ``rados://.smb//``. Example: +``rados://.smb/tango/config.json``. + +The containers are automatically deployed with cephx keys allowing access to +resources in these pools and namespaces. As long as this scheme is used +no additional configuration to read the object is needed. + +To copy a configuration file to a RADOS pool, use the ``rados`` command line +tool. For example: + +.. prompt:: bash # + + # assuming your config file is /tmp/config.json + rados --pool=.smb --namespace=tango put config.json /tmp/config.json + +MON Key/Value Store +~~~~~~~~~~~~~~~~~~~ + +A configuration file can be stored as a value in the Ceph Monitor Key/Value +store. The key must be named after the cluster like so: +``smb/config//``. This results in a URI that can be used to +identify this configuration constructed like +``rados:mon-config-key:smb/config//``. +Example: ``rados:mon-config-key:smb/config/tango/config.json``. + +The containers are automatically deployed with cephx keys allowing access to +resources with the key-prefix ``smb/config//``. As long as this +scheme is used no additional configuration to read the value is needed. + +To copy a configuration file into the Key/Value store use the ``ceph config-key +put ...`` tool. For example: + +.. prompt:: bash # + + # assuming your config file is /tmp/config.json + ceph config-key set smb/config/tango/config.json -i /tmp/config.json + + +HTTP/HTTPS +~~~~~~~~~~ + +A configuration file can be stored on an HTTP(S) server and automatically read +by the Samba Container. Managing a configuration file on HTTP(S) is left as an +exercise for the reader. + +.. note:: All URI schemes are supported by parameters that accept URIs. Each + scheme has different performance and security characteristics. + + +Limitations +=========== + +A non-exhaustive list of important limitations for the SMB service follows: + +* DNS is a critical component of Active Directory. If one is configuring the + SMB service for domain membership, either the Ceph host node must be + configured so that it can resolve the Active Directory (AD) domain or the + ``custom_dns`` option may be used. In both cases DNS hosts for the AD domain + must still be reachable from whatever network segment the ceph cluster is on. +* Proper clustering/high-availability/"transparent state migration" is not yet + supported. If a placement causes more than service to be created these + services will act independently and may lead to unexpected behavior if clients + access the same files at once. +* Services must bind to TCP port 445. Running multiple SMB services on the same + node is not yet supported and will trigger a port-in-use conflict. -- 2.39.5