Directory entry name normalization and case folding

Learn how to configure CephFS to handle directory entry names using normalization, case folding, and encoding settings.

This is particularly important when exporting CephFS through gateways like SMB, which require case-insensitive file system behavior. CephFS clients normalize names, then apply case folding. The Ceph Metadata Server (MDS) stores and matches names using the normalized and case-folded form. CephFS applies Unicode normalization before case folding.

CephFS supports the following virtual extended attributes:


Attribute	Description
ceph.dir.casesensitive	Boolean. Set to false to enable case folding.
ceph.dir.normalization	String. Defines the Unicode normalization form. Accepts nfd, nfc, nfkd, or nfkc.
ceph.dir.encoding	String. Defines the character encoding. Only utf8 is supported.
ceph.dir.charmap	JSON object summarizing case sensitivity, normalization, and encoding. Can also be used to reset to default behavior.

Note: The ceph.dir.charmap attribute stores the complete configuration in JSON format. Use it to view the complete settings or restore default behavior.

When you set a charmap on a directory:

Configuration affects name handling in that directory.
Sub-directories , at the time of creation, inherit the parent directory’s charmap settings.
Configuration applies only to directory entries—not to the directory name itself.
Snapshot names remain case-sensitive and are not normalized. The charmap settings do not apply to them.

Restrictions on modifying directory charmap settings

Before modifying charmap settings, ensure the following:

Directory must be empty.
Directory must not be part of a snapshot.

Permissions for setting directory entry name configuration

CephFS restricts the ability to set the ceph.dir.charmap attribute to clients with appropriate authorization.

To set this attribute, the client must have the MDS p (path) authorization capability on the target directory.
Viewing the attribute does not require special permissions.