mirror of
https://github.com/ceph/ceph
synced 2025-01-23 19:46:56 +00:00
3d0acf9372
Line edit doc/rados/config/auth-config-ref.rst. https://tracker.ceph.com/issues/58485 Co-authored-by: Anthony D'Atri <anthony.datri@gmail.com> Signed-off-by: Zac Dover <zac.dover@proton.me>
380 lines
12 KiB
ReStructuredText
380 lines
12 KiB
ReStructuredText
.. _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
|