VFS_CEPH_NEW(8)

💖 VFS_CEPH_NEW — bestie edition 💖

okay so real talk, this is vfs_ceph_new from the samba(8) suite (manual section 8, system administration tools, iykyk) and it's literally the module that lets Samba flex all the fancy features that come out of libcephfs' low-level APIs. she's a VFS module. she's iconic. let's get into it 🦋

✨ SYNOPSIS ✨

vfs objects = ceph_new

that's it. that's the whole vibe. one line. slay 💅

---

🌸 DESCRIPTION 🌸

so first things first: this VFS module is part of the samba(8) suite. family reunion, she's there 💖

vfs_ceph_new exposes CephFS-specific features for Samba to use. think of it as the module that lets your Samba share speak fluent Ceph.

now, for the besties who don't know: Ceph is a distributed network file system designed to provide excellent performance, reliability, and scalability. it's a shared library that lets applications access a Ceph distributed file system through a POSIX-like interface. she's giving distributed. she's giving POSIX-ish. no cap 🌈

here's the important bit though — you can combine this module with other modules, BUT it should be the last module in the vfs objects list. like, last last. final girl energy. any modules you add to the right of the ceph entry may not have any effect at all, and that's just how it is 😭

vfs_ceph_new performs mapping between Windows and POSIX Access Control Lists (ACLs). and to make sure POSIX ACLs get processed and enforced correctly, these Ceph configuration parameters are automatically applied for you, no work required:

client acl type = posix_acl
fuse default permissions = false

NOTE: this is a second implementation of a ceph module — it 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. so yes she's the newer sister and she's lowkey more efficient and highkey more precise 🔥

---

🎀 CONFIGURATION 🎀

vfs_ceph_new requires that the underlying share path is a Ceph filesystem. that's the rule. non-negotiable. periodt.

[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 gets treated differently: it's interpreted as an absolute path within the Ceph filesystem on the attached Ceph cluster. yes bestie, different rules, different lane 💫

and if you're in a ctdb cluster environment where ctdb manages Samba, you must configure CTDB_SAMBA_SKIP_SHARE_CHECK=yes to disable local share path checks — otherwise ctdb will not reach a healthy state. she will simply not be okay 🙈

also note: currently kernel share modes have to be disabled in a share running with the CephFS vfs module for file serving to work properly. not a suggestion, it's a whole thing 💀

---

👑 OPTIONS 👑

💜 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. read the prerequisites bestie, don't skip them 🫶

• 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. no backup plan, she's committed 🔥
• auto — Attempt to use the proxy library but fall back to the regular cephfs connection if prerequisites are unmet. flexible queen 🌸

💜 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. lock it in, throw away the key (but actually keep the key) 🔐

• disabled (default) — FSCrypt support is disabled.
• none — An alias for disabled. same thing, different font 💅
• 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.

---

⭐ VERSION ⭐

This man page is part of version 4.24.7-Ubuntu-4.24.7+dfsg-1ubuntu1 of the Samba suite. 💖

---

🌟 AUTHOR 🌟

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. legends only, honestly 👑

---

okay bye bestie, go mount something 💅✨

Samba 4.24.7-Ubuntu-4.24.7+dfsg-1ubuntu1 — dated 09/13/2026 — and that's the whole VFS_CEPH_NEW(8) page, no cap, fr fr 🦋💖