From: John Wilkins Date: Thu, 14 Aug 2014 03:28:10 +0000 (-0700) Subject: doc: Restructured auth configuration reference. X-Git-Tag: v0.86~154^2~9 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=4c651b7d0aef9cb2a7546bbc4fa5a443f128996e;p=ceph.git doc: Restructured auth configuration reference. Signed-off-by: John Wilkins --- diff --git a/doc/rados/configuration/auth-config-ref.rst b/doc/rados/configuration/auth-config-ref.rst index c17d477b8fec..f6ca9ed78a9f 100644 --- a/doc/rados/configuration/auth-config-ref.rst +++ b/doc/rados/configuration/auth-config-ref.rst @@ -2,65 +2,199 @@ Cephx Config Reference ======================== -.. index:: cephx; authentication; cephx configuration - To identify users and protect against man-in-the-middle attacks, Ceph provides -its ``cephx`` authentication system to authenticate users and daemons. See `Ceph -Authentication & Authorization`_ for an introduction to ``cephx`` -authentication. See the `Cephx Guide`_ for details on enabling/disabling, -creating users and setting user capabilities. +its ``cephx`` authentication system to authenticate users and daemons. +.. note:: The ``cephx`` protocol does not address data encryption in transport + (e.g., SSL/TLS) or encryption at rest. -Enable/Disable Authentication -============================= +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**. -Depending on the version, Ceph either enables or disables authentication by -default. Use the following settings to expressly enable or disable Ceph. -See `Ceph Authentication`_ for additional details. +.. important:: Remember, 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. -.. topic:: Authentication Enablement Defaults +Deployment Scenarios +==================== - Ceph version 0.54 and earlier versions disable authentication by default. - If you want to use Ceph authentication, you must specifically enable it - for version 0.54 and earlier versions. - - Ceph version 0.55 and later version enable authentication by default. If you - do not want to use Ceph authentication, you must specifically disable it - for versions 0.55 and later versions. - +There are two main scenarios for deploying a Ceph cluster, which impact +how you initially configure Cephx. Most first time Ceph users use +``ceph-deploy`` 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 +bootstrap your monitor(s). -.. topic:: Authentication Granularity +ceph-deploy +----------- - Ceph version 0.50 and earlier versions use ``auth supported`` to enable or - disable authentication between the :term:`Ceph Client` and the :term:`Ceph - Storage Cluster`. Ceph authentication in earlier versions only authenticates - users sending message traffic between the client and the cluster, so it does - not have fine-grained control. - - Ceph version 0.51 and later versions use fine-grained control, which allows - you to require authentication of the client by the cluster - (``auth service required``), authentication of the cluster by the client - (``auth client required``), and authentication of a daemon within the - cluster by another daemon within the cluster (``auth cluster required``). +When you deploy a cluster with ``ceph-deploy``, you do not have to bootstrap the +monitor manually or create the ``client.admin`` user or keyring. The steps you +execute in the `Storage Cluster Quick Start`_ will invoke ``ceph-deploy`` to do +that for you. +When you execute ``ceph-deploy new {initial-monitor(s)}``, Ceph will create a +monitor keyring for you (only used to bootstrap monitors), and it will generate +an initial Ceph configuration file for you, which contains the following +authentication settings, indicating that Ceph enables authentication by +default:: + auth_cluster_required = cephx + auth_service_required = cephx + auth_client_required = cephx -``auth supported`` +When you execute ``ceph-deploy mon create-initial``, Ceph will bootstrap the +initial monitor(s), retrieve a ``ceph.client.admin.keyring`` file containing the +key for the ``client.admin`` user. Additionally, it will also retrieve keyrings +that give ``ceph-deploy`` and ``ceph-disk`` utilities the ability to prepare and +activate OSDs and metadata servers. -.. deprecated:: 0.51 +When you execute ``ceph-deploy admin {node-name}`` (note: Ceph must be installed +first), you are pushing a Ceph configuration file and the +``ceph.client.admin.keyring`` to the ``/etc/ceph`` directory of the node. You +will be able to execute Ceph administrative functions on the command line. -:Description: Indicates whether to use authentication. If not specified, - it defaults to ``none``, which means it is disabled. -:Type: String -:Required: No -:Default: ``none`` +Manual Deployment +----------------- - -``auth cluster required`` +When you deploy a cluster with 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`_. + + +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 +-------------- + +When ``cephx`` is enabled, Ceph will look for the keyring in the default search +path, which includes ``/etc/ceph/ceph.$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. + +Execute the following procedures to enable ``cephx`` on a cluster with ``cephx`` +disabled. 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 *' osd 'allow *' -o /etc/ceph/ceph.client.admin.keyring + + **Warning:** This 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! + +#. Create a keyring for your cluster and generate a monitor secret key. :: + + 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:: + + cp /tmp/ceph.mon.keyring /var/lib/ceph/mon/ceph-a/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 *' -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. See `Operating a Cluster`_ for details. + +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 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. + +#. 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 -.. versionadded:: 0.51 + +#. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details. + + +Cephx Limitations +================= + +The ``cephx`` protocol authenticates Ceph clients and servers to each other. It +is not intended to handle authentication of human users or application programs +run on their behalf. If that effect is required to handle your access control +needs, you must have another mechanism, which is likely to be specific to the +front end used to access the Ceph object store. This other mechanism has the +role of ensuring that only acceptable users and programs are able to run on the +machine that Ceph will permit to access its object store. + +The keys used to authenticate Ceph clients and servers are typically stored in +a plain text file with appropriate permissions in a trusted host. + +.. important:: Storing keys in plaintext files has security shortcomings, but + they are difficult to avoid, given the basic authentication methods Ceph + uses in the background. Those setting up Ceph systems should be aware of + these shortcomings. + +In particular, arbitrary user machines, especially portable machines, should not +be configured to interact directly with Ceph, since that mode of use would +require the storage of a plaintext authentication key on an insecure machine. +Anyone who stole that machine or obtained surreptitious access to it could +obtain the key that will allow them to authenticate their own machines to Ceph. + +Rather than permitting potentially insecure machines to access a Ceph object +store directly, users should be required to sign in to a trusted machine in +your environment using a method that provides sufficient security for your +purposes. That trusted machine will store the plaintext Ceph keys for the +human users. A future version of Ceph may address these particular +authentication issues more fully. + +At the moment, none of the Ceph authentication protocols provide secrecy for +messages in transit. Thus, an eavesdropper on the wire can hear and understand +all data sent between clients and servers in Ceph, even if he cannot create or +alter them. Further, Ceph does not include options to encrypt user data in the +object store. Users can hand-encrypt and store their own data in the Ceph +object store, of course, but Ceph provides no features to perform object +encryption itself. Those storing sensitive data in Ceph should consider +encrypting their data before providing it to the Ceph system. + +Configuration Settings +====================== + +Enablement +---------- + + +``auth cluster required`` :Description: If enabled, the Ceph Storage Cluster daemons (i.e., ``ceph-mon``, ``ceph-osd``, and ``ceph-mds``) must authenticate with @@ -68,40 +202,35 @@ See `Ceph Authentication`_ for additional details. :Type: String :Required: No -:Default: Version 0.54 and earlier ``none``. Version 0.55 and later ``cephx``. +:Default: ``cephx``. ``auth service required`` -.. versionadded:: 0.51 - :Description: If enabled, the Ceph Storage Cluster daemons require Ceph Clients to authenticate with the Ceph Storage Cluster in order to access Ceph services. Valid settings are ``cephx`` or ``none``. :Type: String :Required: No -:Default: Version 0.54 and earlier ``none``. Version 0.55 and later ``cephx``. - +:Default: ``cephx``. ``auth client required`` -.. versionadded:: 0.51 - :Description: If enabled, the Ceph Client requires the Ceph Storage Cluster to authenticate with the Ceph Client. Valid settings are ``cephx`` or ``none``. :Type: String :Required: No -:Default: Version 0.54 and earlier ``none``. Version 0.55 and later ``cephx``. +: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. @@ -152,10 +281,53 @@ setting (not recommended), or a path to a keyfile using the ``keyfile`` setting. :Default: None +Daemon Keyrings +--------------- + +With the exception of the monitors, Ceph generates daemon keyrings in the same +way that it generates user keyrings. By default, the daemons store their +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: N/A + +``ceph-osd`` + +:Location: ``$osd_data/keyring`` +:Capabilities: ``mon 'allow rwx' osd 'allow *'`` + +``ceph-mds`` + +:Location: ``$mds_data/keyring`` +:Capabilities: ``mds 'allow rwx' mds 'allow *' osd 'allow *'`` + +``radosgw`` + +:Location: ``$rgw_data/keyring`` +:Capabilities: ``mon 'allow rw' osd 'allow rwx'`` + + +Note that the monitor keyring 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. + + .. index:: signatures Signatures -========== +---------- In Ceph Bobtail and subsequent versions, we prefer that Ceph authenticate all ongoing messages between the entities using the session key set up for that @@ -211,7 +383,7 @@ Ceph, and you can enable/disable signatures for messages between Ceph daemons. Time to Live -============ +------------ ``auth service ticket ttl`` @@ -223,7 +395,72 @@ Time to Live :Default: ``60*60`` -.. _Ceph Authentication & Authorization: ../../operations/auth-intro -.. _Cephx Guide: ../../operations/authentication -.. _Ceph Authentication: ../../operations/auth-intro#ceph-authentication-cephx -.. _Create an Admin Host: ../../deployment/ceph-deploy-admin#create-an-admin-host +Backward Compatibility +====================== + +For Cuttlefish and earlier releases, see `Cephx`_. + +In Ceph Argonaut v0.48 and earlier versions, if you enable ``cephx`` +authentication, Ceph only authenticates the initial communication between the +client and daemon; Ceph does not authenticate the subsequent messages they send +to each other, which has security implications. In Ceph Bobtail and subsequent +versions, Ceph authenticates all ongoing messages between the entities using the +session key set up for that initial authentication. + +We identified a backward compatibility issue between Argonaut v0.48 (and prior +versions) and Bobtail (and subsequent versions). During testing, if you +attempted to use Argonaut (and earlier) daemons with Bobtail (and later) +daemons, the Argonaut daemons did not know how to perform ongoing message +authentication, while the Bobtail versions of the daemons insist on +authenticating message traffic subsequent to the initial +request/response--making it impossible for Argonaut (and prior) daemons to +interoperate with Bobtail (and subsequent) daemons. + +We have addressed this potential problem by providing a means for Argonaut (and +prior) systems to interact with Bobtail (and subsequent) systems. Here's how it +works: by default, the newer systems will not insist on seeing signatures from +older systems that do not know how to perform them, but will simply accept such +messages without authenticating them. This new default behavior provides the +advantage of allowing two different releases to interact. **We do not recommend +this as a long term solution**. Allowing newer daemons to forgo ongoing +authentication has the unfortunate security effect that an attacker with control +of some of your machines or some access to your network can disable session +security simply by claiming to be unable to sign messages. + +.. note:: Even if you don't actually run any old versions of Ceph, + the attacker may be able to force some messages to be accepted unsigned in the + default scenario. While running Cephx with the default scenario, Ceph still + authenticates the initial communication, but you lose desirable session security. + +If you know that you are not running older versions of Ceph, or you are willing +to accept that old servers and new servers will not be able to interoperate, you +can eliminate this security risk. If you do so, any Ceph system that is new +enough to support session authentication and that has Cephx enabled will reject +unsigned messages. To preclude new servers from interacting with old servers, +include the following in the ``[global]`` section of your `Ceph +configuration`_ file directly below the line that specifies the use of Cephx +for authentication:: + + cephx require signatures = true ; everywhere possible + +You can also selectively require signatures for cluster internal +communications only, separate from client-facing service:: + + cephx cluster require signatures = true ; for cluster-internal communication + cephx service require signatures = true ; for client-facing service + +An option to make a client require signatures from the cluster is not +yet implemented. + +**We recommend migrating all daemons to the newer versions and enabling the +foregoing flag** at the nearest practical time so that you may avail yourself +of the enhanced authentication. + + +.. _Storage Cluster Quick Start: ../../../start/quick-ceph-deploy/ +.. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping +.. _Operating a Cluster: ../../operations/operating +.. _Manual Deployment: ../../../install/manual-deployment +.. _Cephx: http://ceph.com/docs/cuttlefish/rados/configuration/auth-config-ref/ +.. _Ceph configuration: ../ceph-conf +.. _Create an Admin Host: ../../deployment/ceph-deploy-admin \ No newline at end of file