vfs_ceph_new - Man Page

vfs objects = ceph_new

This VFS module is part of the samba(8) suite​.

The vfs_ceph_new VFS module exposes CephFS specific features for use by Samba​.

Ceph is a distributed network file system designed to provide excellent performance, reliability, and scalability​. This is a shared library allowing applications to access a Ceph distributed file system via a POSIX-like interface​.

This module can be combined with other modules, but it should be the last module in the vfs objects list​. Modules added to this list to the right of the ceph entry may not have any effect at all​.

vfs_ceph_new performs mapping between Windows and POSIX Access Control Lists (ACLs)​. To ensure correct processing and enforcement of POSIX ACLs, the following Ceph configuration parameters are automatically applied:

		client acl type = posix_acl
		fuse default permissions = false

NOTE: This is a second implementation of a ceph module which uses libcephfs low-level APIs (compared to the original vfs_ceph(8) module which uses path-based APIs)​. Using the low-level API allows more optimized and fine-grained access to the Ceph storage layer​.

vfs_ceph_new requires that the underlying share path is a Ceph filesystem​.

		[share]
		vfs objects = ceph_new
		path = /non-mounted/cephfs/path
		kernel share modes = no

Since vfs_ceph_new does not require a filesystem mount, the share path is treated differently: it is interpreted as an absolute path within the Ceph filesystem on the attached Ceph cluster​. In a ctdb cluster environment where ctdb manages Samba, CTDB_SAMBA_SKIP_SHARE_CHECK=yes must be configured to disable local share path checks, otherwise ctdb will not reach a healthy state​.

Note that currently kernel share modes have to be disabled in a share running with the CephFS vfs module for file serving to work properly​.

ceph_new:config_file = path

Allows one to define a ceph configfile to use​. Empty by default​.

Example: ceph_new:config_file = /etc/ceph/ceph​.conf

ceph_new:user_id = name

Allows one to explicitly set the client ID used for the CephFS mount handle​. Empty by default (use the libcephfs client default)​.

Example: ceph_new:user_id = samba

ceph_new:filesystem = fs_name

Allows one to explicitly select the CephFS file system to use when the Ceph cluster supports more than one file system​. Empty by default (use the default file system of the Ceph cluster)​.

Example: ceph_new:filesystem = myfs2

ceph_new:proxy = [ yes | no | auto ]

Allows one to indicate use of the libcephfs proxy library for optimized resource utilization, allowing more simultaneous client connections​. Prerequisites include the presence of libcephfs_proxy​.so​.X shared library file under loadable locations for dynamic linker and an active(running) libcephfsd daemon​.

• no (default) - Do not use the proxy library but regular connection through libcephfs​.so​.X​.
• yes - Always use the proxy library and fail the client connection request if prerequisites are unmet​.
• auto - Attempt to use the proxy library but fall back to the regular cephfs connection if prerequisites are unmet​.

ceph_new:fscrypt = [ disabled | none | keybridge ]

Configures the CephFS client to enable FSCrypt-style encrypted (sub-)volume support​. If enabled, encryption is applied automatically to empty shares and future connections to said share will require FSCrypt with the same key material​.

• disabled (default) - FSCrypt support is disabled​.
• none - An alias for disabled​.
• keybridge - Enable CephFS FSCrypt support using the keybridge RPC API for fetching key material​. Setting this option requires that the options ceph_new:keybridge socket, ceph_new:keybridge scope, and ceph_new:keybridge name be specified​.

ceph_new:keybridge socket = type:path

Configures the CephFS FSCrypt support to communicate with a KeyBridge server listening to the provided socket​. The KeyBridge server uses the varlink KeyBridge protocol to fetch key material from one or more key distribution services, such as KMIP for example​.

The only permitted type is unix​. The path value is a path to a unix domain socket for a keybridge server​. For example: unix:/run/keybridge/keybridge​.sock

If specified, this option requires the options ceph_new:keybridge scope and ceph_new:keybridge name to be specified​.

ceph_new:keybridge scope = scope

Set the scope value for KeyBridge API requests​. The scope identifies a context for keys, typically mapping to a particular backend​. The available scope values depend on the configuration of the KeyBridge server​. For example: "kmip​.testing"​.

If specified, this option requires the options ceph_new:keybridge socket and ceph_new:keybridge name to be specified​.

ceph_new:keybridge name = name

Set the name value for KeyBridge API requests​. The name or identifier for a key, within a scope, that the KeyBridge server will be use to "unlock" the encryption for this share​. For example: "volume1"​.

If specified, this option requires the options ceph_new:keybridge socket and ceph_new:keybridge scope to be specified​.

ceph_new:keybridge kind = [ B64 | VALUE ]

Set the kind of the data field for KeyBridge API requests​. A KeyBridge server is capable of data exchange using either Base64 encoded strings (B64) or plain text (VALUE)​. Depending on the scope, a server may be able to fetch key material in one form or the other​. Use this option to manually select the data kind​.

If unspecified, B64 will be used​.

This man page is part of version 4​.25​.0 of the Samba suite​.

The original Samba software and related utilities were created by Andrew Tridgell​. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed​.