path: root/doc/rados/configuration/auth-config-ref.rst

.. _rados-cephx-config-ref:

========================
 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:

   .. 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 `Ceph configuration`_ 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`_.



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:

   .. 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`_.


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``.


.. index:: keys; keyring

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:

.. 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


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.


.. index:: signatures

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


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


.. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping
.. _Operating a Cluster: ../../operations/operating
.. _Manual Deployment: ../../../install/manual-deployment
.. _Ceph configuration: ../ceph-conf
.. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication
.. _User Management: ../../operations/user-management