Notice

This document is for a development version of Ceph.

CephX Config Reference

The CephX protocol is enabled by default. The cryptographic authentication that CephX provides has some computational costs, though they should generally be quite low. If the network environment connecting your client and server hosts is very safe and you cannot afford authentication, you can disable it.

Warning

Disabling authentication is usually a very bad choice. If you disable authentication, any access to the cluster will be permitted no matter the origin or identity of the client.

For information about creating users, see User Management. For details on the architecture of CephX, see High Availability Authentication.

Deployment Scenarios

How you initially configure CephX depends on your scenario. There are two common strategies for deploying a Ceph cluster. If you are a first-time Ceph user, you should probably take the easiest approach: using cephadm to deploy a cluster. But if your cluster uses other deployment tools (for example, Ansible, Chef, Juju, or Puppet), you will need either to use the manual deployment procedures or to configure your deployment tool so that it will bootstrap your monitor(s).

Manual Deployment

When you deploy a cluster manually, it is necessary to bootstrap the Monitors manually and to create the client.admin user and keyring. To bootstrap Monitors, follow the steps in Monitor Bootstrapping. Follow these steps when using third-party deployment tools (for example, Chef, Puppet, and Juju).

Enabling/Disabling CephX

Enabling CephX is possible only if the keys for your Monitors, OSD, and MDS have already been deployed. If you are simply toggling CephX on or off, it is not necessary to repeat the bootstrapping procedures.

Authentication is explicitly enabled or disabled for all entities via the global section of Ceph configuration. The following configurations affect this.

auth_cluster_required

If enabled, Ceph cluster daemons (i.e., ceph-mon, ceph-osd, ceph-mds and ceph-mgr) must authenticate with each other. Valid settings are cephx or none.

type:

str

runtime updatable:

true

default:

cephx

auth_service_required

If enabled, Ceph cluster daemons require clients to authenticate with the cluster in order to access Ceph services. Valid settings are cephx or none.

type:

str

runtime updatable:

true

default:

cephx

auth_client_required

If enabled, Ceph clients require the Ceph cluster to authenticate with Ceph clients. Valid settings are cephx or none.

type:

str

runtime updatable:

true

default:

cephx, none

Enabling CephX

When CephX is enabled, Ceph will look for the keyring in the default search path: this path includes /etc/ceph/$cluster.$name.keyring. It is possible to override this search path location by adding a keyring option in the [global] section of your Ceph configuration file, but this is not recommended.

To enable CephX on a cluster for which authentication has been disabled, carry out the following procedure. If you (or your deployment utility) have already generated the keys, you may skip the steps related to generating keys.

Create a client.admin key, and save a copy of the key for your client host:

ceph auth get-or-create client.admin mon 'allow *' mds 'allow *' mgr 'allow *' osd 'allow *' -o /etc/ceph/ceph.client.admin.keyring

Warning

This step will clobber any existing /etc/ceph/client.admin.keyring file. Do not perform this step if a deployment tool has already generated a keyring file for you. Be careful!

Create a monitor keyring and generate a monitor secret key:

ceph-authtool --create-keyring /tmp/ceph.mon.keyring --gen-key -n mon. --cap mon 'allow *'

For each monitor, copy the monitor keyring into a ceph.mon.keyring file in the monitor’s mon data directory. For example, to copy the monitor keyring to mon.a in a cluster called ceph, run the following command:
```
cp /tmp/ceph.mon.keyring /var/lib/ceph/mon/ceph-a/keyring
```

Generate a secret key for every MGR, where {$id} is the MGR letter:

ceph auth get-or-create mgr.{$id} mon 'allow profile mgr' mds 'allow *' osd 'allow *' -o /var/lib/ceph/mgr/ceph-{$id}/keyring

Generate a secret key for every OSD, where {$id} is the OSD number:

ceph auth get-or-create osd.{$id} mon 'allow rwx' osd 'allow *' -o /var/lib/ceph/osd/ceph-{$id}/keyring

Generate a secret key for every MDS, where {$id} is the MDS letter:

ceph auth get-or-create mds.{$id} mon 'allow rwx' osd 'allow *' mds 'allow *' mgr 'allow profile mds' -o /var/lib/ceph/mds/ceph-{$id}/keyring

Enable CephX authentication by setting the following options in the [global] section of your Ceph configuration file:
```
[global]
auth_cluster_required = cephx
auth_service_required = cephx
auth_client_required = cephx
```
Start or restart the Ceph cluster. For details, see Operating a Cluster.

For details on bootstrapping a monitor manually, see Manual Deployment.

Disabling CephX

The following procedure describes how to disable CephX. If your cluster environment is safe, you might want to disable CephX in order to offset the computational expense of running authentication. We do not recommend doing so. However, setup and troubleshooting might be easier if authentication is temporarily disabled and subsequently re-enabled.

Disable CephX authentication by setting the following options in the [global] section of your Ceph configuration file:
```
[global]
auth_cluster_required = none
auth_service_required = none
auth_client_required = none
```
Start or restart the Ceph cluster. For details, see Operating a Cluster.

Configuration Settings

Keys

When Ceph is run with authentication enabled, ceph administrative commands and Ceph clients can access the Ceph Storage Cluster only if they use authentication keys.

The most common way to make these keys available to ceph administrative commands and Ceph clients is to include a Ceph keyring under the /etc/ceph directory. For Octopus and later releases that use cephadm, the filename is usually ceph.client.admin.keyring. If the keyring is included in the /etc/ceph directory, then it is unnecessary to specify a keyring entry in the Ceph configuration file.

Because the Ceph Storage Cluster’s keyring file contains the client.admin key, we recommend copying the keyring file to nodes from which you run administrative commands.

To perform this step manually, run the following command:

sudo scp {user}@{ceph-cluster-host}:/etc/ceph/ceph.client.admin.keyring /etc/ceph/ceph.client.admin.keyring

Tip

Make sure that the ceph.keyring file has appropriate permissions (for example, chmod 644) set on your client machine.

You can specify the key itself by using the key setting in the Ceph configuration file (this approach is not recommended), or instead specify a path to a keyfile by using the keyfile setting in the Ceph configuration file.

keyring

A keyring file is an INI-style formatted file where the section names are client or daemon names (e.g., ‘osd.0’) and each section contains a ‘key’ property with CephX authentication key as the value.

type:

str

runtime updatable:

false

see also:

key, keyfile

keyfile

The path to a key file (i.e,. a file containing only the key).

type:

str

runtime updatable:

false

see also:

key

key

The key (i.e., the text string of the key itself). Not recommended.

type:

str

runtime updatable:

false

see also:

keyfile, keyring

Daemon Keyrings

Administrative users or deployment tools (for example, cephadm) generate daemon keyrings in the same way that they generate user keyrings. By default, Ceph stores the keyring of a daemon inside that daemon’s data directory. Consult each components documentation for capabilities expected for the service.

To bootstrap a cluster, consult the Manual Deployment documentation.

Each daemon’s data-directory locations defaults to a path of the form:

/var/lib/ceph/$type/$cluster-$id

For example, osd.12 would have the following data directory:

/var/lib/ceph/osd/ceph-12

It is possible to override these locations, but it is not recommended.

Signatures

Ceph performs a signature check that provides some limited protection against messages being tampered with in flight (for example, by a “man in the middle” attack).

As with other parts of Ceph authentication, signatures admit of fine-grained control. You can enable or disable signatures for service messages between clients and Ceph, and for messages between Ceph daemons.

Note that even when signatures are enabled, data is not encrypted in flight.

cephx_require_signatures

If set to true, Ceph requires signatures on all message traffic between the Ceph Client and the Ceph Storage Cluster, and between daemons comprising the Ceph Storage Cluster. Ceph Argonaut and Linux kernel versions prior to 3.19 do not support signatures; if such clients are in use this option can be turned off to allow them to connect.

type:

bool

runtime updatable:

true

default:

false

cephx_cluster_require_signatures

If set to true, Ceph requires signatures on all message traffic between Ceph daemons comprising the Ceph Storage Cluster.

type:

bool

runtime updatable:

true

default:

false

cephx_service_require_signatures

If set to true, Ceph requires signatures on all message traffic between Ceph Clients and the Ceph Storage Cluster.

type:

bool

runtime updatable:

true

default:

false

cephx_sign_messages

If the Ceph version supports message signing, Ceph will sign all messages so they are more difficult to spoof.

type:

bool

runtime updatable:

true

default:

true

Time to Live

auth_mon_ticket_ttl

The time-to-live for tickets with the auth subsystem of the Monitors. These tickets are used to reclaim the global ID associated with the running client.

type:

float

runtime updatable:

true

default:

72 hours

auth_service_ticket_ttl

The time-to-live for non-auth service tickets issued by the Monitors. These tickets would include services like the OSD or MDS. This allows the client to authenticate independently with the service for the given timeframe before having to refresh its tickets with the Monitors again.

type:

float

runtime updatable:

true

default:

1 hour

Upgrading and Rotating CephX Keys

In 2026, it became necessary to upgrade the cipher key type for all CephX keys due to the potential vulnerabilities in the older encryption schemes. To effect this upgrade, it’s necessary to do the upgrade in several steps.

Note

cephadm and Rook automate this process for you. cephadm however does not handle the client key changes.

Allow the newer key types for authentication. For upgraded clusters, this should be done automatically by the Monitors.

Confirm the upgrade:
```
ceph --format=json mon dump | jq -r '.auth_allowed_ciphers | map(.name) | join (",")'
```
should output something like:
```
aes,aes256k
```
where aes256k is the new more secure cipher type.

If not included, you can explicitly enable it:
```
ceph mon set auth_allowed_ciphers aes,aes256k
```
Then confirm the change:
```
ceph --format=json mon dump | jq -r '.auth_allowed_ciphers | map(.name) | join (",")'
```
Set the preferred default cipher type for new keys. You may choose not to do this if you want new keys, by default, to use the older cipher type until your client applications can be upgraded.

Check the current value:
```
ceph --format=json mon dump | jq -r '.auth_preferred_cipher.name'
```
might output:
```
aes
```
To upgrade to aes256k as the new default cipher type, execute:
```
ceph mon set auth_preferred_cipher aes256k
```
Confirm the change:
```
ceph --format=json mon dump | jq -r '.auth_preferred_cipher.name'
```
should output:
```
aes256k
```
Rotate the keys for all service daemon credentials. These include mon, mgr, osd, and mds.

Warning

Changing the key will make the existing daemon unable to reauthenticate.

Note

The mon. historically has not been managed by the Monitor auth database; it exists soley in each Monitor’s keyring inside its data directory. This suggested rotation procedure now puts the authoritative copy in the auth database alongside other keys. The Monitor keyring persists as a fallback or emergency key.

Begin with the mon. key:
```
ceph auth rotate --key-type=aes256k mon. | tee mon.keyring
```
Save the mon.keyring file in a safe place. It should not be necessary to update the keyring files for each Monitor.

Restart each Monitor:
```
systemctl restart ceph-mon@$ID
```
Warning

If a Monitor was out-of-quorum during the Monitor key rotation, it will not have the new key. You must put the saved mon.keyring in its keyring file so it can authenticate.

Now, for each other service daemon type (mgr, osd, and mds):

Stop the daemon:
```
systemctl stop ceph-$TYPE@$ID
```
If it is an OSD:
```
ceph osd down $ID
```
Rotate the entity’s key:
```
ceph auth rotate --key-type=aes256k $TYPE.$ID | tee keyring
```
Note

If you have updated auth_preferred_cipher then you can omit --key-type.

Copy the keyring file to the machine running the daemon, then execute:
```
ceph-authtool --import-keyring $COPIED_KEYRING /var/lib/ceph/$TYPE/ceph-$ID/keyring
```
Adjust the above script based on where the data directory for your daemons are located.

If the daemon is an OSD created using ceph-volume the osd_key bluestore label may also need to be updated. To find the device that must be passed to the bluestore tool:
```
ceph-volume lvm list $OSD_ID --format json
```
and find the lv_path field. Or, for a raw OSD:
```
ceph-volume raw list --format json
```
and find the device field for the OSD who’s key you wish to rotate.

Once the device path is acquired the bluestore label can be rotated by executing:
```
ceph-bluestore-tool --dev $DEV_PATH set-label-key --key osd_key -v $COPIED_KEYRING
```
Finally, restart the daemon:
```
systemctl restart ceph-$TYPE@$ID
```
Confirm the AUTH_INSECURE_SERVICE_KEY_TYPE is cleared.
```
ceph --format=json health detail | jq '.checks | has("AUTH_INSECURE_SERVICE_KEY_TYPE")'
```
output gives false.

If it outputs true, there is another daemon that needs to be upgraded. Check the output of ceph health detail.

Upgrade the cipher for rotating service keys.

ceph mon set auth_service_cipher aes256k

Confirm the change:

ceph --format=json mon dump | jq -r '.auth_service_cipher.name'

should output

aes256k

Verify the AUTH_INSECURE_SERVICE_TICKETS is resolved:

ceph --format=json health detail | jq '.checks | has("AUTH_INSECURE_SERVICE_TICKETS") | not'

Wipe the rotating service keys.

Warning

This is not recommended for most deployments. It is best to let your rotating service keys expire after a few hours (using default TTL).

Warning

Only perform this step if all service daemons have upgraded binaries that understand the new cipher type.

If you want to immediately clear the AUTH_INSECURE_ROTATING_SERVICE_KEY_TYPE warning, you can wipe the existing rotating service key database on the Monitors:
```
ceph auth wipe-rotating-service-keys
```
should output:
```
wiped rotating service keys!
```
This will cause all service daemons to refresh the rotating service keys. Upgraded clients will similarly refresh their tickets with the Monitors.

Note

This operation has no effect on the existing sessions the Clients have established with service daemons.
Prevent creation of new insecure keys.

When the Monitor setting auth_allowed_ciphers setting includes an insecure key type, the default value of the Monitor config mon_auth_allow_insecure_key will be altered at runtime to true. For an upgraded cluster, you should therefore expect see the AUTH_INSECURE_KEYS_CREATABLE health warning.

You can disable this configuration manually to prevent new insecure keys from being created. Alternatively, once the auth_allowed_ciphers omits insecure key types (in a future step of this process), this configuration will have its default value changed and that should also clear AUTH_INSECURE_KEYS_CREATABLE.

To manually disable the creation of insecure keys:
```
ceph config set mon 'mon auth allow insecure key' false
```
Verify the AUTH_INSECURE_KEYS_CREATABLE is resolved:
```
ceph --format=json health detail | jq '.checks | has("AUTH_INSECURE_KEYS_CREATABLE") | not'
```
output gives false.

For more information, see Allow Creation of Insecure Keys.
Rotate the admin key.

Warning

Rotating the admin key requires special care as recovering from a mistake is complicated. Be careful.

Note

It is common for the client.admin credential’s key to be copied to several nodes that may need to execute administrative commands. The new key will need to be copied to each node.

Create a backup emergency admin key in case of mistakes:
```
ceph auth get-or-create client.admin-backup mon "allow *" | tee ./client.admin-backup.keyring
```
Confirm the backup key works:
```
ceph -n client.admin-backup -k ./client.admin-backup.keyring auth ls
```
Now, rotate the client.admin key:
```
ceph auth rotate --key-type=aes256k client.admin | tee ./client.admin.keyring
```
Note

If you have updated auth_preferred_cipher then you can omit --key-type.

Warning

The client.admin key is now changed. You cannot execute new Ceph commands as client.admin until you import the new key into your keyring.

Import the new client.admin key into your system’s keyring file:
```
ceph-authtool --import-keyring ./client.admin.keyring /etc/ceph/ceph.client.admin.keyring
```
Warning

Your system’s keyring file may be in a different location! Check /etc/ceph and your local Ceph configuration.

Verify the key works:
```
ceph -n client.admin -k /etc/ceph/ceph.client.admin.keyring ceph auth ls
```
If everything looks good, remove the backup key:
```
ceph auth rm client.admin-backup
```
Rotate other client keys.

The process to rotate other client keys is similar to the admin key.

To view client credentials with insecure keys:
```
ceph health detail
```
should include output with AUTH_INSECURE_CLIENT_KEY_TYPE:
```
[WRN] AUTH_INSECURE_CLIENT_KEY_TYPE: 2 auth client entities with insecure key types
 entity client.fs using insecure key type: aes
 entity client.fs_a using insecure key type: aes
```
which tells you that two keys need to be updated.

If the client’s software (e.g. ceph-fuse or the Linux kernel driver) is up-to-date on all machines using the key, you may rotate the key and distribute it.
```
ceph auth rotate --key-type=aes256k client.$ID | tee ./client.$ID.keyring
```
Note

If you have updated auth_preferred_cipher then you can omit --key-type.

Then copy and import the key to each machine using that client.$ID credential.

Once all client credentials have been upgraded, you should see the AUTH_INSECURE_CLIENT_KEY_TYPE health warning clear.
```
ceph --format=json health detail | jq '.checks | has("AUTH_INSECURE_CLIENT_KEY_TYPE") | not'
```
output gives false.

If you cannot rotate a particular client key yet, you may prefer to mute the health warning until you can complete upgrading all of the client keys. We expect this to be typical situation for some clusters.
```
ceph health mute AUTH_INSECURE_CLIENT_KEY_TYPE 8w
```
to mute the warning for 8 weeks. Alternatively, use --sticky to make it permanent.
Disallow insecure keys for authentication.

Now that all serivce daemon and client keys have been rotated, you can remove the insecure cipher key type from the list of types allowed for authentication.
```
ceph mon set auth_allowed_ciphers aes256k
```
Note

This will now disable the default value for mon_auth_allow_insecure_key and clear the AUTH_INSECURE_KEYS_CREATABLE warning.

Warning

If you remove the key type for the client.admin key or for service daemon keys, you may break authentication in your cluster. That situation will require rescue via Emergency Allowed Ciphers. Ensure that AUTH_INSECURE_CLIENT_KEY_TYPE and AUTH_INSECURE_SERVICE_KEY_TYPE health warnings are clear!

Once changed, you should see the AUTH_INSECURE_KEYS_ALLOWED health warning clear.
```
ceph --format=json health detail | jq '.checks | has("AUTH_INSECURE_KEYS_ALLOWED") | not'
```
output gives false.

At this point, your CephX ciphers and keys should be upgraded.

Rotating CephX Keys

The Monitors provide a mechanism to only update the key for an entity via the auth rotate command.

ceph auth rotate $TYPE.$ID

For example:

ceph auth rotate client.fs | tee ./client.fs.keyring

The output of the command is the new key:

[client.fs]
        key = <redacted>
        caps mds = "allow rwp"
        caps mon = "allow r"
        caps osd = "allow rw tag cephfs data=*"

This can be imported into a new keyring using ceph-authtool:

ceph-authtool --import-keyring ./client.fs.keyring /etc/ceph/client.fs.keyring

Note

The key must be distributed to all locations where the key is in use.

Emergency Allowed Ciphers

The Monitors maintain the set of allowed ciphers for credential keys in the MonMap. This is normally set live on the cluster using:

It’s possible to set a cipher for which no key exists to authenticate during key upgrades. To work around this, the Monitors may be rescued using the local startup configuration:

mon_auth_emergency_allowed_ciphers

set allowed ciphers to override mon map configuration

type:

str

runtime updatable:

false

This will allow your existing client.admin or other administrative key to authenticate as normal.

When this configuration is set, the Monitors will raise the AUTH_EMERGENCY_CIPHERS_SET health warning. It should only be set on a temporary basis to rescue the cluster.

Allow Creation of Insecure Keys

By default, the Monitors will allow creation of keys with a cipher type known to be insecure so long as the Monitors also allow that cipher to authenticate. When that cipher type is removed from the authentication list, the Monitors will also disable the default value of the mon_auth_allow_insecure_key configuration.

mon_auth_allow_insecure_key

By default, the Monitors will allow creation of keys with a cipher type known to be insecure so long as the Monitors also allow that cipher to authenticate. When that cipher type is removed from the authentication list, the Monitors will also disable the default value of this configuration. When disabled, ceph commands can no longer create keys with an insecure cipher type.

type:

bool

runtime updatable:

true

default:

false

When disabled, ceph commands can no longer create keys with an insecure cipher type.

When this configuration is enabled by default or otherwise, the Monitors will raise the AUTH_INSECURE_KEYS_CREATABLE health warning.

Dump Existing Keys

The Monitors provide a command to dump all CephX credentials and key metadata as well as all rotating service key metadata.

ceph --format=json-pretty auth dump-keys

produces truncated output like:

{
    "data": {
        "version": 15,
        "rotating_version": 1,
        "secrets": [
            {
                "entity": {
                    "type": 2,
                    "type_str": "mds",
                    "id": "a"
                },
                "auth": {
                    "key": {
                        "type": 1,
                        "type_str": "aes",
                        "created": "2025-07-29T21:53:30.978646-0400"
                    },
                    "pending_key": {
                        "type": 0,
                        "type_str": "none",
                        "created": "0.000000"
                    },
                    "caps": [
                        {
                            "service_name": "mds",
                            "access_spec": "\u0005\u0000\u0000\u0000allow"
                        },
                        {
                            "service_name": "mgr",
                            "access_spec": "\u0011\u0000\u0000\u0000allow profile mds"
                        },
                        {
                            "service_name": "mon",
                            "access_spec": "\u0011\u0000\u0000\u0000allow profile mds"
                        },
                        {
                            "service_name": "osd",
                            "access_spec": "\u0017\u0000\u0000\u0000allow rw tag cephfs *=*"
                        }
                    ]
                }
            },
            ...
        ],
        "rotating_secrets": [
            {
                "entity": {
                    "type": 1,
                    "type_str": "mon",
                    "id": "*"
                },
                "secrets": {
                    "max_ver": 3,
                    "keys": [
                        {
                            "id": 1,
                            "expiring_key": {
                                "key": {
                                    "type": 1,
                                    "type_str": "aes",
                                    "created": "2025-07-29T21:53:04.632712-0400"
                                },
                                "expiration": "2025-07-29T22:53:04.632703-0400"
                            }
                        },
                        {
                            "id": 2,
                            "expiring_key": {
                                "key": {
                                    "type": 1,
                                    "type_str": "aes",
                                    "created": "2025-07-29T21:53:04.632715-0400"
                                },
                                "expiration": "2025-07-29T23:53:04.632703-0400"
                            }
                        },
                        {
                            "id": 3,
                            "expiring_key": {
                                "key": {
                                    "type": 1,
                                    "type_str": "aes",
                                    "created": "2025-07-29T21:53:04.632718-0400"
                                },
                                "expiration": "2025-07-30T00:53:04.632703-0400"
                            }
                        }
                    ]
                }
            },
        ]
    }
}

This command only works for format types json or json-pretty.

You may use this information to monitor the entities in the Monitor auth database as well as key types. For example, this information lets the operator check if insecure key types are in use. Consider this a low-level API. For example, the caps listed are in a binary format that is unsuitable for analysis.

Note

Generally, the Monitors will warn you if there is a dangerous situation such as insecure key types are in use.

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.