Introduction

The SMB colocation feature in Ceph 9.0 significantly enhances the flexibility of Samba deployments by allowing multiple Samba container services to run on a single Ceph node. Traditionally, SMB services were constrained by fixed networking assumptions, which limited how many SMB clusters could coexist on the same host. Colocation removes this limitation by introducing configurable networking parameters at the cluster level.

This feature is particularly useful in containerised and multi-tenant environments where efficient resource utilisation, isolation, and flexibility are critical. With colocation, operators can deploy multiple independent SMB clusters — each with its own authentication mode, ports, and networking configuration—on the same Ceph infrastructure.

Objective

The primary objectives of the SMB colocation feature are:

• Enable multiple Samba containers to coexist on the same Ceph node without port or network conflicts.

• Provide cluster-level control over SMB, CTDB, and metrics ports.

• Allow administrators to explicitly define which IP addresses or networks an SMB cluster may bind to.

• Support both standalone (user-based authentication) and Active Directory–backed SMB clusters.

• Improve scalability and flexibility for SMB deployments in orchestrated environments.

SMB MGR Module Enhancements

To support colocation, the SMB Manager module introduces new cluster-level networking options:

• Custom ports: Administrators can customise the ports used by SMB, CTDB, and SMB metrics.

• Bind address configuration: Define specific IP addresses or networks that SMB containers must exclusively use, ensuring proper isolation between colocated clusters.

These settings make it possible to safely run multiple SMB clusters on the same node without interference.

Example Deployments

Bind Address and Network Configuration

In colocated environments, controlling which IP addresses or networks an SMB cluster can bind to is critical. The bind_addrs option allows explicit isolation by limiting the interfaces used by Samba containers.

This ensures that multiple SMB clusters running on the same Ceph node do not conflict with each other at the networking layer.

Example: Binding to Specific IP Addresses

Use this configuration when you want the SMB cluster to listen only on selected IP addresses:

bind_addrs:

  - address: 192.168.10.11

  - address: 192.168.10.12

  - address: 192.168.10.13

In this example, the SMB services will exclusively bind to the listed IPs. Any other IPs present on the node will be ignored by this cluster.

Example: Binding to a Network Range

Use network-based binding when the cluster should listen on all IPs within a specific subnet:

bind_addrs:

  - network: 192.168.20.0/24

This configuration allows Samba containers to bind to any IP address within the 192.168.20.0/24 network. This is particularly useful in environments with dynamic IP allocation or when using multiple interfaces within the same subnet.

Both address-based and network-based bindings can be combined with custom ports to fully isolate colocated SMB clusters.

Example Deployments

1. Deploying a Standalone SMB Cluster

The following example demonstrates how to deploy a standalone SMB cluster using local user-based authentication, with explicit bind address configuration.

Standalone Cluster with Address-Based Binding

# smb cluster resources

- resource_type: ceph.smb.cluster

  cluster_id: <cluster-name>

  auth_mode: user

  user_group_settings:

    - source_type: resource

      ref: <user-group-name>

  custom_ports:

    smb: <custom-smb-port>

    smbmetrics: <custom-smbmetrics-port>

    ctdb: <custom-ctdb-port>

  bind_addrs:

    - address: <ip-address>

  placement:

    label: smb

In this configuration, the SMB cluster binds only to the specified IP address, ensuring isolation when multiple SMB clusters are colocated on the same node.

Standalone Cluster with Network-Based Binding

# smb cluster resources

- resource_type: ceph.smb.cluster

  cluster_id: <cluster-name>

  auth_mode: user

  user_group_settings:

    - source_type: resource

      ref: <user-group-name>

  custom_ports:

    smb: <custom-smb-port>

    smbmetrics: <custom-smbmetrics-port>

    ctdb: <custom-ctdb-port>

  bind_addrs:

    - network: <ip-address>/<prefix>

  placement:

    label: smb

This setup allows the SMB cluster to bind to any IP address within the specified network range, which is useful in environments with multiple interfaces or dynamic IP assignment.

SMB Share Definition

# cluster share

- resource_type: ceph.smb.share

  cluster_id: <cluster-name>

  share_id: <share-name>

  cephfs:

    volume: <cephfs-volume-name>

    subvolumegroup: <cephfs-subvolumegroup>

    subvolume: <cephfs-subvolume>

    path: /

User and Group Configuration

# usergroup

- resource_type: ceph.smb.usersgroups

  users_groups_id: <user-group-name>

  values:

    users:

      - name: <smb-username>

        password: <smb-userpassword>

    groups: []

2. Deploying an Active Directory–Backed SMB Cluster

This example shows how to deploy an SMB cluster integrated with Active Directory (AD), including bind address isolation.

AD Cluster with Address-Based Binding

# AD cluster resources

- resource_type: ceph.smb.cluster

  cluster_id: <cluster-name>

  auth_mode: active-directory

  domain_settings:

    realm: <domain-name>

    join_sources:

      - source_type: resource

        ref: <auth-join>

  custom_ports:

    smb: <custom-smb-port>

    smbmetrics: <custom-smbmetrics-port>

    ctdb: <custom-ctdb-port>

  bind_addrs:

    - address: <ip-address>

  custom_dns:

    - <domain-ip>

  placement:

    label: smb

This configuration ensures the AD-backed SMB cluster listens only on the specified IP address.

AD Cluster with Network-Based Binding

# AD cluster resources

- resource_type: ceph.smb.cluster

  cluster_id: <cluster-name>

  auth_mode: active-directory

  domain_settings:

    realm: <domain-name>

    join_sources:

      - source_type: resource

        ref: <auth-join>

  custom_ports:

    smb: <custom-smb-port>

    smbmetrics: <custom-smbmetrics-port>

    ctdb: <custom-ctdb-port>

  bind_addrs:

    - network: <ip-address>/<prefix>

  custom_dns:

    - <domain-ip>

  placement:

    label: smb

This setup allows the AD-backed SMB cluster to bind to any IP within the defined subnet, which is useful in enterprise environments with segmented networks.

Active Directory Join Credentials

# Auth join

- resource_type: ceph.smb.join.auth

  auth_id: <auth-join>

  auth:

    username: <AD-username>

    password: <AD-userpassword>

SMB Share Definition

# SMB share

- resource_type: ceph.smb.share

  cluster_id: <cluster-name>

  share_id: <share-name>

  cephfs:

    volume: <cephfs-volume-name>

    subvolumegroup: <cephfs-subvolumegroup-name>

    subvolume: <cephfs-subvolume-name>

Client Access

Once the SMB cluster and share are deployed, clients can connect using the configured custom SMB port:

smbclient -U '<smb-username>%<smb-userpassword>' \

  -p <custom-smb-port> //<Node-IP>/<share-name>

This explicit port specification is key when multiple SMB clusters are colocated on the same node.

Conclusion

The SMB colocation feature in Ceph 9.0 is a major step forward for scalable and flexible SMB deployments. By introducing customizable networking parameters and cluster-level isolation, it enables multiple SMB clusters – standalone or Active Directory–backed—to run safely on the same Ceph node.

This capability is especially valuable in containerised, multi-tenant, and test environments where efficient resource usage and clear separation between services are essential. With colocation, Ceph SMB becomes more adaptable, easier to scale, and better suited for modern infrastructure needs.