Notice

This document is for a development version of Ceph.

Report a Documentation Bug

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:

orch apply smb <cluster_id> <config_uri> [--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:

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:

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/<cluster_id>/<object_name>. 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:

# 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/<cluster_id>/<name>. This results in a URI that can be used to identify this configuration constructed like rados:mon-config-key:smb/config/<cluster_id>/<name>. 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/<cluster_id>/. 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:

# 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.

Brought to you by the Ceph Foundation

The Ceph Documentation is a community resource funded and hosted by the non-profit Ceph Foundation. If you would like to support this and our other efforts, please consider joining now.