Chapter 4. Ceph authentication configuration

As a storage administrator, authenticating users and services is important to the security of the Red Hat Ceph Storage cluster. Red Hat Ceph Storage includes the Cephx protocol, as the default, for cryptographic authentication, and the tools to manage authentication in the storage cluster.

4.1. Prerequisites

  • Installation of the Red Hat Ceph Storage software.

4.2. Cephx authentication

The cephx protocol is enabled by default. Cryptographic authentication has some computational costs, though they are generally quite low. If the network environment connecting clients and hosts is considered safe and you cannot afford authentication computational costs, you can disable it. When deploying a Ceph storage cluster, the deployment tool will create the client.admin user and keyring.


Red Hat recommends using authentication.


If you disable authentication, you are at risk of a man-in-the-middle attack altering client and server messages, which could lead to significant security issues.

Enabling and disabling Cephx

Enabling Cephx requires that you have deployed keys for the Ceph Monitors and OSDs. When toggling Cephx authentication on or off, you do not have to repeat the deployment procedures.

4.3. Enabling Cephx

When cephx is enabled, Ceph will look for the keyring in the default search path, which includes /etc/ceph/$cluster.$name.keyring. You can override this location by adding a keyring option in the [global] section of the Ceph configuration file, but this is not recommended.

Execute the following procedures to enable cephx on a cluster with authentication disabled. If you or your deployment utility have already generated the keys, you may skip the steps related to generating keys.


  • A running Red Hat Ceph Storage cluster.
  • Root-level access to the Ceph Monitor node.


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

    [root@mon ~]# ceph auth get-or-create client.admin mon 'allow *' osd 'allow *' -o /etc/ceph/ceph.client.admin.keyring

    This will erase the contents of any existing /etc/ceph/client.admin.keyring file. Do not perform this step if a deployment tool has already done it for you.

  2. Create a keyring for the monitor cluster and generate a monitor secret key:

    [root@mon ~]# ceph-authtool --create-keyring /tmp/ceph.mon.keyring --gen-key -n mon. --cap mon 'allow *'
  3. Copy the monitor keyring into a ceph.mon.keyring file in every monitor mon data directory. For example, to copy it to mon.a in cluster ceph, use the following:

    [root@mon ~]# cp /tmp/ceph.mon.keyring /var/lib/ceph/mon/ceph-a/keyring
  4. 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
  5. By default the cephx authentication protocol is enabled.


    If the cephx authentication protocol was disabled previously by setting the authentication options to none, then by removing the following lines under the [global] section in the Ceph configuration file (/etc/ceph/ceph.conf) will reenable the cephx authentication protocol:

    auth_cluster_required = none
    auth_service_required = none
    auth_client_required = none
  6. Start or restart the Ceph storage cluster.


    Enabling cephx requires downtime because the cluster needs to be completely restarted, or it needs to be shut down and then started while client I/O is disabled.

    These flags need to be set before restarting or shutting down the storage cluster:

    [root@mon ~]# ceph osd set noout
    [root@mon ~]# ceph osd set norecover
    [root@mon ~]# ceph osd set norebalance
    [root@mon ~]# ceph osd set nobackfill
    [root@mon ~]# ceph osd set nodown
    [root@mon ~]# ceph osd set pause

    Once cephx is enabled and all PGs are active and clean, unset the flags:

    [root@mon ~]# ceph osd unset noout
    [root@mon ~]# ceph osd unset norecover
    [root@mon ~]# ceph osd unset norebalance
    [root@mon ~]# ceph osd unset nobackfill
    [root@mon ~]# ceph osd unset nodown
    [root@mon ~]# ceph osd unset pause

4.4. Disabling Cephx

The following procedure describes how to disable Cephx. If your cluster environment is relatively safe, you can offset the computation expense of running authentication.


Red Hat recommends enabling authentication.

However, it may be easier during setup or troubleshooting to temporarily disable authentication.


  • A running Red Hat Ceph Storage cluster.
  • Root-level access to the Ceph Monitor node.


  1. Disable cephx authentication by setting the following options in the [global] section of the Ceph configuration file:


    auth_cluster_required = none
    auth_service_required = none
    auth_client_required = none

  2. Start or restart the Ceph storage cluster.

4.5. Cephx user keyrings

When you run Ceph with authentication enabled, the ceph administrative commands and Ceph clients require authentication keys to access the Ceph storage cluster.

The most common way to provide these keys to the ceph administrative commands and clients is to include a Ceph keyring under the /etc/ceph/ directory. The file name is usually ceph.client.admin.keyring or $cluster.client.admin.keyring. If you include the keyring under the /etc/ceph/ directory, you do not need to specify a keyring entry in the Ceph configuration file.


Red Hat recommends copying the Red Hat Ceph Storage cluster keyring file to nodes where you will run administrative commands, because it contains the client.admin key.

To do so, execute the following command:

# scp USER@HOSTNAME:/etc/ceph/ceph.client.admin.keyring /etc/ceph/ceph.client.admin.keyring

Replace USER with the user name used on the host with the client.admin key and HOSTNAME with the host name of that host.


Ensure the ceph.keyring file has appropriate permissions set on the client machine.

You can specify the key itself in the Ceph configuration file using the key setting, which is not recommended, or a path to a key file using the keyfile setting.

4.6. Cephx daemon keyrings

Administrative users or deployment tools might generate daemon keyrings in the same way as generating user keyrings. By default, Ceph stores daemons keyrings inside their data directory. The default keyring locations, and the capabilities necessary for the daemon to function.


The monitor keyring contains a key but no capabilities, and is not part of the Ceph storage cluster auth database.

The daemon data directory locations default to directories of the form:




You can override these locations, but it is not recommended.

4.7. Cephx message signatures

Ceph provides fine-grained control so you can enable or disable signatures for service messages between the client and Ceph. You can enable or disable signatures for messages between Ceph daemons.


Red Hat recommends that Ceph authenticate all ongoing messages between the entities using the session key set up for that initial authentication.


Ceph kernel modules do not support signatures yet.

4.8. Additional Resources

  • See all the Red Hat Ceph Storage Cephx configuration options in Appendix D for specific option descriptions and usage.