From 3d0acf9372a35ef48be47efe68192ec389c17ccb Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Thu, 6 Apr 2023 10:21:01 +1000 Subject: [PATCH] doc/rados/config: edit auth-config-ref Line edit doc/rados/config/auth-config-ref.rst. https://tracker.ceph.com/issues/58485 Co-authored-by: Anthony D'Atri Signed-off-by: Zac Dover --- doc/rados/configuration/auth-config-ref.rst | 344 ++++++++++++++------ 1 file changed, 252 insertions(+), 92 deletions(-) diff --git a/doc/rados/configuration/auth-config-ref.rst b/doc/rados/configuration/auth-config-ref.rst index 001f1776526b3..fc14f4ee6eff3 100644 --- a/doc/rados/configuration/auth-config-ref.rst +++ b/doc/rados/configuration/auth-config-ref.rst @@ -1,109 +1,110 @@ .. _rados-cephx-config-ref: ======================== - Cephx Config Reference + CephX Config Reference ======================== -The ``cephx`` protocol is enabled by default. Cryptographic authentication 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 turn it off. **This is not generally -recommended**. +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 are at risk of a man-in-the-middle - attack altering your client/server messages, which could lead to disastrous - security effects. +.. 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 creating users, see `User Management`_. For details on the architecture -of Cephx, see `Architecture - High Availability Authentication`_. +For information about creating users, see `User Management`_. For details on +the architecture of CephX, see `Architecture - High Availability +Authentication`_. Deployment Scenarios ==================== -There are two main scenarios for deploying a Ceph cluster, which impact -how you initially configure Cephx. Most first time Ceph users use -``cephadm`` to create a cluster (easiest). For clusters using -other deployment tools (e.g., Chef, Juju, Puppet, etc.), you will need -to use the manual procedures or configure your deployment tool to +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, you have to bootstrap the monitor manually -and create the ``client.admin`` user and keyring. To bootstrap monitors, follow -the steps in `Monitor Bootstrapping`_. The steps for monitor bootstrapping are -the logical steps you must perform when using third party deployment tools like -Chef, Puppet, Juju, etc. +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/Disabling CephX ======================== -Enabling Cephx requires that you have deployed keys for your monitors, -OSDs and metadata servers. If you are simply toggling Cephx on / off, -you do not have to repeat the bootstrapping procedures. +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 +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 -your `Ceph configuration`_ file, but this is not recommended. +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. -Execute the following procedures to enable ``cephx`` on a cluster with -authentication disabled. If you (or your deployment utility) have already +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 + 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 will clobber any existing + **Warning:** This step will clobber any existing ``/etc/ceph/client.admin.keyring`` file. Do not perform this step if a - deployment tool has already done it for you. Be careful! + deployment tool has already generated a keyring file for you. Be careful! -#. Create a keyring for your monitor cluster and generate a monitor - secret key. +#. 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 *' -#. Copy the monitor keyring into a ``ceph.mon.keyring`` file in every monitor's - ``mon data`` directory. For example, to copy it to ``mon.a`` in cluster ``ceph``, - use the following +#. 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 +#. 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 +#. 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 +#. 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 +#. Enable CephX authentication by setting the following options in the + ``[global]`` section of your `Ceph configuration`_ file: .. code-block:: ini @@ -111,23 +112,23 @@ generated the keys, you may skip the steps related to generating keys. auth_service_required = cephx auth_client_required = cephx - -#. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details. +#. Start or restart the Ceph cluster. For details, see `Operating a Cluster`_. For details on bootstrapping a monitor manually, see `Manual Deployment`_. -Disabling Cephx +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. **We do not recommend it.** However, it may be easier -during setup and/or troubleshooting to temporarily disable authentication. +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 +#. Disable CephX authentication by setting the following options in the + ``[global]`` section of your `Ceph configuration`_ file: .. code-block:: ini @@ -135,8 +136,7 @@ during setup and/or troubleshooting to temporarily disable authentication. auth_service_required = none auth_client_required = none - -#. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details. +#. Start or restart the Ceph cluster. For details, see `Operating a Cluster`_. Configuration Settings @@ -146,70 +146,230 @@ Enablement ---------- -.. confval:: auth_cluster_required -.. confval:: auth_service_required -.. confval:: auth_client_required +``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 you run Ceph with authentication enabled, ``ceph`` administrative commands -and Ceph Clients require authentication keys to access the Ceph Storage Cluster. +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 provide these keys to the ``ceph`` administrative -commands and clients is to include a Ceph keyring under the ``/etc/ceph`` -directory. For Octopus and later releases using ``cephadm``, the filename -is usually ``ceph.client.admin.keyring`` (or ``$cluster.client.admin.keyring``). -If you include the keyring under the ``/etc/ceph`` directory, you don't need to -specify a ``keyring`` entry in your Ceph configuration file. +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. -We recommend copying the Ceph Storage Cluster's keyring file to nodes where you -will run administrative commands, because it contains the ``client.admin`` key. +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, execute the following: +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:: Ensure the ``ceph.keyring`` file has appropriate permissions set - (e.g., ``chmod 644``) on your client machine. +.. 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`` -You may specify the key itself in the Ceph configuration file using the ``key`` -setting (not recommended), or a path to a keyfile using the ``keyfile`` setting. +: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. -.. confval:: keyring - :default: /etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin -.. confval:: keyfile -.. confval:: key .. index:: signatures Signatures ---------- -Ceph performs a signature check that provides some limited protection -against messages being tampered with in flight (e.g., by a "man in the -middle" attack). +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:** -Like other parts of Ceph authentication, Ceph provides fine-grained control so -you can enable/disable signatures for service messages between clients and -Ceph, and so you can enable/disable signatures for messages between Ceph daemons. + 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. -Note that even with signatures enabled data is not encrypted in -flight. -.. confval:: cephx_require_signatures -.. confval:: cephx_cluster_require_signatures -.. confval:: cephx_service_require_signatures -.. confval:: cephx_sign_messages +: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 ------------ -.. confval:: auth_service_ticket_ttl +``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 -- 2.39.5