doc/rados/configuration/auth-config-ref.rst
.. _rados-cephx-config-ref:
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 :ref:user-management. For details on
the architecture of CephX, see :ref:arch_high_availability_authentication.
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).
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 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.
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 :ref:Ceph configuration <configuring-ceph>
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:
.. prompt:: bash $
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:
.. prompt:: bash $
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:
.. prompt:: bash $
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:
.. prompt:: bash $
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:
.. prompt:: bash $
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:
.. prompt:: bash $
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 :ref:Ceph configuration <configuring-ceph>
file:
.. code-block:: ini
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_.
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 :ref:Ceph configuration <configuring-ceph>
file:
.. code-block:: ini
auth_cluster_required = none
auth_service_required = none
auth_client_required = none
#. Start or restart the Ceph cluster. For details, see Operating a Cluster_.
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.
.. index:: keys; keyring
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 :ref:Ceph configuration <configuring-ceph> 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:
.. prompt:: bash $
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
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.
.. index:: 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
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
.. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping .. _Operating a Cluster: ../../operations/operating .. _Manual Deployment: ../../../install/manual-deployment