Report a Documentation Bug

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. Disabling authentication is not generally recommended.

Note

If you disable authentication, you will be at risk of a man-in-the-middle attack that alters your client/server messages, which could have disastrous security effects.

For information about creating users, see User Management. For details on the architecture of CephX, see Architecture - 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, OSDs, and metadata servers have already been deployed. If you are simply toggling CephX on or off, it is not necessary to repeat the bootstrapping procedures.

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:
```
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:
```
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¶

Enablement¶

auth_cluster_required

Description: If this configuration setting is enabled, the Ceph Storage Cluster daemons (that is, ceph-mon, ceph-osd, ceph-mds, and ceph-mgr) are required to authenticate with each other. Valid settings are cephx or none.
Type: String
Required: No
Default: cephx.

auth_service_required

Description: If this configuration setting is enabled, then Ceph clients can access Ceph services only if those clients authenticate with the Ceph Storage Cluster. Valid settings are cephx or none.
Type: String
Required: No
Default: cephx.

auth_client_required

Description: If this configuration setting is enabled, then communication between the Ceph client and Ceph Storage Cluster can be established only if the Ceph Storage Cluster authenticates against the Ceph client. Valid settings are cephx or none.
Type: String
Required: No
Default: cephx.

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

Description: The path to the keyring file.
Type: String
Required: No
Default: /etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin

keyfile

Description: The path to a keyfile (that is, a file containing only the key).
Type: String
Required: No
Default: None

key

Description: The key (that is, the text string of the key itself). We do not recommend that you use this setting unless you know what you’re doing.
Type: String
Required: No
Default: None

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. The default keyring locations and the capabilities that are necessary for the daemon to function are shown below.

ceph-mon

Location: $mon_data/keyring
Capabilities: mon 'allow *'

ceph-osd

Location: $osd_data/keyring
Capabilities: mgr 'allow profile osd' mon 'allow profile osd' osd 'allow *'

ceph-mds

Location: $mds_data/keyring
Capabilities: mds 'allow' mgr 'allow profile mds' mon 'allow profile mds' osd 'allow rwx'

ceph-mgr

Location: $mgr_data/keyring
Capabilities: mon 'allow profile mgr' mds 'allow *' osd 'allow *'

radosgw

Location: $rgw_data/keyring
Capabilities: mon 'allow rwx' osd 'allow rwx'

Note

The monitor keyring (that is, mon.) contains a key but no capabilities, and this keyring is not part of the cluster auth database.

The daemon’s data-directory locations default to directories 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.

keyring

Description: The path to the keyring file.
Type: String
Required: No
Default: /etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin

keyfile

Description: The path to a key file (i.e,. a file containing only the key).
Type: String
Required: No
Default: None

key

Description: The key (i.e., the text string of the key itself). Not recommended.
Type: String
Required: No
Default: None

Daemon Keyrings¶

Administrative users or deployment tools (e.g., cephadm) may 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, are shown below.

ceph-mon

Location: $mon_data/keyring
Capabilities: mon 'allow *'

ceph-osd

Location: $osd_data/keyring
Capabilities: mgr 'allow profile osd' mon 'allow profile osd' osd 'allow *'

ceph-mds

Location: $mds_data/keyring
Capabilities: mds 'allow' mgr 'allow profile mds' mon 'allow profile mds' osd 'allow rwx'

ceph-mgr

Location: $mgr_data/keyring
Capabilities: mon 'allow profile mgr' mds 'allow *' osd 'allow *'

radosgw

Location: $rgw_data/keyring
Capabilities: mon 'allow rwx' osd 'allow rwx'

Note

The monitor keyring (i.e., mon.) contains a key but no capabilities, and is not part of the cluster auth database.

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

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

For example, osd.12 would be:

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

You can 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

Description: If this configuration setting is set to true, Ceph requires signatures on all message traffic between the Ceph client and the Ceph Storage Cluster, and between daemons within the Ceph Storage Cluster.

Note

ANTIQUATED NOTE:

Neither Ceph Argonaut nor Linux kernel versions prior to 3.19 support signatures; if one of these clients is in use, cephx_require_signatures can be disabled in order to allow the client to connect.

Type: Boolean
Required: No
Default: false

cephx_cluster_require_signatures

Description: If this configuration setting is set to true, Ceph requires signatures on all message traffic between Ceph daemons within the Ceph Storage Cluster.
Type: Boolean
Required: No
Default: false

cephx_service_require_signatures

Description: If this configuration setting is set to true, Ceph requires signatures on all message traffic between Ceph clients and the Ceph Storage Cluster.
Type: Boolean
Required: No
Default: false

cephx_sign_messages

Description: If this configuration setting is set to true, and if the Ceph version supports message signing, then Ceph will sign all messages so that they are more difficult to spoof.
Type: Boolean
Default: true

cephx_require_signatures

Description

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

Boolean

Required

No

Default

false

cephx_cluster_require_signatures

Description: If set to true, Ceph requires signatures on all message traffic between Ceph daemons comprising the Ceph Storage Cluster.
Type: Boolean
Required: No
Default: false

cephx_service_require_signatures

Description: If set to true, Ceph requires signatures on all message traffic between Ceph Clients and the Ceph Storage Cluster.
Type: Boolean
Required: No
Default: false

cephx_sign_messages

Description: If the Ceph version supports message signing, Ceph will sign all messages so they are more difficult to spoof.
Type: Boolean
Default: true

Time to Live¶

auth_service_ticket_ttl

Description: When the Ceph Storage Cluster sends a ticket for authentication to a Ceph client, the Ceph Storage Cluster assigns that ticket a Time To Live (TTL).
Type: Double
Default: 60*60