From 743434c26b4c930a7022358257f0847f990ea8ae Mon Sep 17 00:00:00 2001 From: John Mulligan Date: Fri, 27 Jun 2025 10:00:19 -0400 Subject: [PATCH] doc/mgr: add documentation for bind_addrs option Add some documentation for the bind_addrs option including a warning about how combining public_addrs and bind_addrs gets quirky. Signed-off-by: John Mulligan (cherry picked from commit 5020c79ae13b18003d85bfbbc0a126b8e2d00ab6) --- doc/cephadm/services/smb.rst | 15 +++++++++++++++ doc/mgr/smb.rst | 28 ++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/doc/cephadm/services/smb.rst b/doc/cephadm/services/smb.rst index f0b2f405af3d6..0e39edb63ef6d 100644 --- a/doc/cephadm/services/smb.rst +++ b/doc/cephadm/services/smb.rst @@ -112,6 +112,21 @@ custom_ports ports used by smb for client access and the metrics exporter, but not change the port used by the CTDB clustering daemon. +bind_addrs + A list of objects indicating what IP address or IP network the + SMB and related services may bind to. The fields described for these + objects are mutually exclusive, but at least one field is required. + Fields: + + address + Optional. A single IP address represented as a string. For example, + ``192.168.7.50``. + network + Optional. A single IP network represented as a string. A network + can be used to specify a range of many IP addresses. The network + string always includes a "/" character before a prefix length. + For example, ``192.168.7.0/24``. + 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 diff --git a/doc/mgr/smb.rst b/doc/mgr/smb.rst index 36b6dbaf374f0..66c85296766d6 100644 --- a/doc/mgr/smb.rst +++ b/doc/mgr/smb.rst @@ -456,6 +456,22 @@ custom_ports ports used by smb for client access and the metrics exporter, but not change the port used by the CTDB clustering daemon. Note - not all SMB clients are able to use alternate port numbers. +bind_addrs + Optional. A list of objects indicating what IP address or IP network the + SMB and related services may bind to. The fields described for these + objects are mutually exclusive, but at least one field is required. + (The behavior of this option changes when used with clustering and + ``public_addrs``. See note below.) + Fields: + + address + Optional. A single IP address represented as a string. For example, + ``192.168.7.50``. + network + Optional. A single IP network represented as a string. A network + can be used to specify a range of many IP addresses. The network + string always includes a "/" character before a prefix length. + For example, ``192.168.7.0/24``. placement Optional. A Ceph Orchestration :ref:`placement specifier `. Defaults to one host if not provided @@ -472,6 +488,8 @@ public_addrs Assign "virtual" IP addresses that will be managed by the clustering subsystem and may automatically move between nodes running Samba containers. + (The behavior of this option changes when used with ``bind_addrs``. See + note below.) Fields: address @@ -512,6 +530,16 @@ custom_smb_global_options placement. In particular, be aware that running multiple instances of the same ``smb`` service without clustering enabled can cause unexpected behavior. +.. warning:: + The behavior of the system when combining ``bind_addrs`` and + ``public_addrs`` on a cluster could lead to unexpected results. The ``smbd`` + process can only dynamically add/remove public addresses when assigned to + monitor a network device (e.g. ``eth0``) versus a specific address. If the + network device is assigned multiple addresses and those addreses overlap + with a different smb cluster it is possible the services may fail to start. + Currently, one must manually ensure that the devices used by a IP or network + is exclusvely used for that network to ensure SMB services start properly. + .. _join-source-fields: -- 2.39.5