1 ========================
3 ========================
5 The ``cephx`` protocol is enabled by default. Cryptographic authentication has
6 some computational costs, though they should generally be quite low. If the
7 network environment connecting your client and server hosts is very safe and
8 you cannot afford authentication, you can turn it off. **This is not generally
11 .. note:: If you disable authentication, you are at risk of a man-in-the-middle
12 attack altering your client/server messages, which could lead to disastrous
15 For creating users, see `User Management`_. For details on the architecture
16 of Cephx, see `Architecture - High Availability Authentication`_.
22 There are two main scenarios for deploying a Ceph cluster, which impact
23 how you initially configure Cephx. Most first time Ceph users use
24 ``ceph-deploy`` to create a cluster (easiest). For clusters using
25 other deployment tools (e.g., Chef, Juju, Puppet, etc.), you will need
26 to use the manual procedures or configure your deployment tool to
27 bootstrap your monitor(s).
32 When you deploy a cluster with ``ceph-deploy``, you do not have to bootstrap the
33 monitor manually or create the ``client.admin`` user or keyring. The steps you
34 execute in the `Storage Cluster Quick Start`_ will invoke ``ceph-deploy`` to do
37 When you execute ``ceph-deploy new {initial-monitor(s)}``, Ceph will create a
38 monitor keyring for you (only used to bootstrap monitors), and it will generate
39 an initial Ceph configuration file for you, which contains the following
40 authentication settings, indicating that Ceph enables authentication by
43 auth_cluster_required = cephx
44 auth_service_required = cephx
45 auth_client_required = cephx
47 When you execute ``ceph-deploy mon create-initial``, Ceph will bootstrap the
48 initial monitor(s), retrieve a ``ceph.client.admin.keyring`` file containing the
49 key for the ``client.admin`` user. Additionally, it will also retrieve keyrings
50 that give ``ceph-deploy`` and ``ceph-disk`` utilities the ability to prepare and
51 activate OSDs and metadata servers.
53 When you execute ``ceph-deploy admin {node-name}`` (**note:** Ceph must be
54 installed first), you are pushing a Ceph configuration file and the
55 ``ceph.client.admin.keyring`` to the ``/etc/ceph`` directory of the node. You
56 will be able to execute Ceph administrative functions as ``root`` on the command
63 When you deploy a cluster manually, you have to bootstrap the monitor manually
64 and create the ``client.admin`` user and keyring. To bootstrap monitors, follow
65 the steps in `Monitor Bootstrapping`_. The steps for monitor bootstrapping are
66 the logical steps you must perform when using third party deployment tools like
67 Chef, Puppet, Juju, etc.
70 Enabling/Disabling Cephx
71 ========================
73 Enabling Cephx requires that you have deployed keys for your monitors,
74 OSDs and metadata servers. If you are simply toggling Cephx on / off,
75 you do not have to repeat the bootstrapping procedures.
81 When ``cephx`` is enabled, Ceph will look for the keyring in the default search
82 path, which includes ``/etc/ceph/$cluster.$name.keyring``. You can override
83 this location by adding a ``keyring`` option in the ``[global]`` section of
84 your `Ceph configuration`_ file, but this is not recommended.
86 Execute the following procedures to enable ``cephx`` on a cluster with
87 authentication disabled. If you (or your deployment utility) have already
88 generated the keys, you may skip the steps related to generating keys.
90 #. Create a ``client.admin`` key, and save a copy of the key for your client
93 ceph auth get-or-create client.admin mon 'allow *' mds 'allow *' osd 'allow *' -o /etc/ceph/ceph.client.admin.keyring
95 **Warning:** This will clobber any existing
96 ``/etc/ceph/client.admin.keyring`` file. Do not perform this step if a
97 deployment tool has already done it for you. Be careful!
99 #. Create a keyring for your monitor cluster and generate a monitor
102 ceph-authtool --create-keyring /tmp/ceph.mon.keyring --gen-key -n mon. --cap mon 'allow *'
104 #. Copy the monitor keyring into a ``ceph.mon.keyring`` file in every monitor's
105 ``mon data`` directory. For example, to copy it to ``mon.a`` in cluster ``ceph``,
108 cp /tmp/ceph.mon.keyring /var/lib/ceph/mon/ceph-a/keyring
110 #. Generate a secret key for every OSD, where ``{$id}`` is the OSD number::
112 ceph auth get-or-create osd.{$id} mon 'allow rwx' osd 'allow *' -o /var/lib/ceph/osd/ceph-{$id}/keyring
114 #. Generate a secret key for every MDS, where ``{$id}`` is the MDS letter::
116 ceph auth get-or-create mds.{$id} mon 'allow rwx' osd 'allow *' mds 'allow *' -o /var/lib/ceph/mds/ceph-{$id}/keyring
118 #. Enable ``cephx`` authentication by setting the following options in the
119 ``[global]`` section of your `Ceph configuration`_ file::
121 auth cluster required = cephx
122 auth service required = cephx
123 auth client required = cephx
126 #. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details.
128 For details on bootstrapping a monitor manually, see `Manual Deployment`_.
135 The following procedure describes how to disable Cephx. If your cluster
136 environment is relatively safe, you can offset the computation expense of
137 running authentication. **We do not recommend it.** However, it may be easier
138 during setup and/or troubleshooting to temporarily disable authentication.
140 #. Disable ``cephx`` authentication by setting the following options in the
141 ``[global]`` section of your `Ceph configuration`_ file::
143 auth cluster required = none
144 auth service required = none
145 auth client required = none
148 #. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details.
151 Configuration Settings
152 ======================
158 ``auth cluster required``
160 :Description: If enabled, the Ceph Storage Cluster daemons (i.e., ``ceph-mon``,
161 ``ceph-osd``, and ``ceph-mds``) must authenticate with
162 each other. Valid settings are ``cephx`` or ``none``.
169 ``auth service required``
171 :Description: If enabled, the Ceph Storage Cluster daemons require Ceph Clients
172 to authenticate with the Ceph Storage Cluster in order to access
173 Ceph services. Valid settings are ``cephx`` or ``none``.
180 ``auth client required``
182 :Description: If enabled, the Ceph Client requires the Ceph Storage Cluster to
183 authenticate with the Ceph Client. Valid settings are ``cephx``
191 .. index:: keys; keyring
196 When you run Ceph with authentication enabled, ``ceph`` administrative commands
197 and Ceph Clients require authentication keys to access the Ceph Storage Cluster.
199 The most common way to provide these keys to the ``ceph`` administrative
200 commands and clients is to include a Ceph keyring under the ``/etc/ceph``
201 directory. For Cuttlefish and later releases using ``ceph-deploy``, the filename
202 is usually ``ceph.client.admin.keyring`` (or ``$cluster.client.admin.keyring``).
203 If you include the keyring under the ``/etc/ceph`` directory, you don't need to
204 specify a ``keyring`` entry in your Ceph configuration file.
206 We recommend copying the Ceph Storage Cluster's keyring file to nodes where you
207 will run administrative commands, because it contains the ``client.admin`` key.
209 You may use ``ceph-deploy admin`` to perform this task. See `Create an Admin
210 Host`_ for details. To perform this step manually, execute the following::
212 sudo scp {user}@{ceph-cluster-host}:/etc/ceph/ceph.client.admin.keyring /etc/ceph/ceph.client.admin.keyring
214 .. tip:: Ensure the ``ceph.keyring`` file has appropriate permissions set
215 (e.g., ``chmod 644``) on your client machine.
217 You may specify the key itself in the Ceph configuration file using the ``key``
218 setting (not recommended), or a path to a keyfile using the ``keyfile`` setting.
223 :Description: The path to the keyring file.
226 :Default: ``/etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin``
231 :Description: The path to a key file (i.e,. a file containing only the key).
239 :Description: The key (i.e., the text string of the key itself). Not recommended.
248 Administrative users or deployment tools (e.g., ``ceph-deploy``) may generate
249 daemon keyrings in the same way as generating user keyrings. By default, Ceph
250 stores daemons keyrings inside their data directory. The default keyring
251 locations, and the capabilities necessary for the daemon to function, are shown
256 :Location: ``$mon_data/keyring``
257 :Capabilities: ``mon 'allow *'``
261 :Location: ``$osd_data/keyring``
262 :Capabilities: ``mon 'allow profile osd' osd 'allow *'``
266 :Location: ``$mds_data/keyring``
267 :Capabilities: ``mds 'allow' mon 'allow profile mds' osd 'allow rwx'``
271 :Location: ``$rgw_data/keyring``
272 :Capabilities: ``mon 'allow rwx' osd 'allow rwx'``
275 .. note:: The monitor keyring (i.e., ``mon.``) contains a key but no
276 capabilities, and is not part of the cluster ``auth`` database.
278 The daemon data directory locations default to directories of the form::
280 /var/lib/ceph/$type/$cluster-$id
282 For example, ``osd.12`` would be::
284 /var/lib/ceph/osd/ceph-12
286 You can override these locations, but it is not recommended.
289 .. index:: signatures
294 In Ceph Bobtail and subsequent versions, we prefer that Ceph authenticate all
295 ongoing messages between the entities using the session key set up for that
296 initial authentication. However, Argonaut and earlier Ceph daemons do not know
297 how to perform ongoing message authentication. To maintain backward
298 compatibility (e.g., running both Botbail and Argonaut daemons in the same
299 cluster), message signing is **off** by default. If you are running Bobtail or
300 later daemons exclusively, configure Ceph to require signatures.
302 Like other parts of Ceph authentication, Ceph provides fine-grained control so
303 you can enable/disable signatures for service messages between the client and
304 Ceph, and you can enable/disable signatures for messages between Ceph daemons.
307 ``cephx require signatures``
309 :Description: If set to ``true``, Ceph requires signatures on all message
310 traffic between the Ceph Client and the Ceph Storage Cluster, and
311 between daemons comprising the Ceph Storage Cluster.
318 ``cephx cluster require signatures``
320 :Description: If set to ``true``, Ceph requires signatures on all message
321 traffic between Ceph daemons comprising the Ceph Storage Cluster.
328 ``cephx service require signatures``
330 :Description: If set to ``true``, Ceph requires signatures on all message
331 traffic between Ceph Clients and the Ceph Storage Cluster.
338 ``cephx sign messages``
340 :Description: If the Ceph version supports message signing, Ceph will sign
341 all messages so they cannot be spoofed.
350 ``auth service ticket ttl``
352 :Description: When the Ceph Storage Cluster sends a Ceph Client a ticket for
353 authentication, the Ceph Storage Cluster assigns the ticket a
360 Backward Compatibility
361 ======================
363 For Cuttlefish and earlier releases, see `Cephx`_.
365 In Ceph Argonaut v0.48 and earlier versions, if you enable ``cephx``
366 authentication, Ceph only authenticates the initial communication between the
367 client and daemon; Ceph does not authenticate the subsequent messages they send
368 to each other, which has security implications. In Ceph Bobtail and subsequent
369 versions, Ceph authenticates all ongoing messages between the entities using the
370 session key set up for that initial authentication.
372 We identified a backward compatibility issue between Argonaut v0.48 (and prior
373 versions) and Bobtail (and subsequent versions). During testing, if you
374 attempted to use Argonaut (and earlier) daemons with Bobtail (and later)
375 daemons, the Argonaut daemons did not know how to perform ongoing message
376 authentication, while the Bobtail versions of the daemons insist on
377 authenticating message traffic subsequent to the initial
378 request/response--making it impossible for Argonaut (and prior) daemons to
379 interoperate with Bobtail (and subsequent) daemons.
381 We have addressed this potential problem by providing a means for Argonaut (and
382 prior) systems to interact with Bobtail (and subsequent) systems. Here's how it
383 works: by default, the newer systems will not insist on seeing signatures from
384 older systems that do not know how to perform them, but will simply accept such
385 messages without authenticating them. This new default behavior provides the
386 advantage of allowing two different releases to interact. **We do not recommend
387 this as a long term solution**. Allowing newer daemons to forgo ongoing
388 authentication has the unfortunate security effect that an attacker with control
389 of some of your machines or some access to your network can disable session
390 security simply by claiming to be unable to sign messages.
392 .. note:: Even if you don't actually run any old versions of Ceph,
393 the attacker may be able to force some messages to be accepted unsigned in the
394 default scenario. While running Cephx with the default scenario, Ceph still
395 authenticates the initial communication, but you lose desirable session security.
397 If you know that you are not running older versions of Ceph, or you are willing
398 to accept that old servers and new servers will not be able to interoperate, you
399 can eliminate this security risk. If you do so, any Ceph system that is new
400 enough to support session authentication and that has Cephx enabled will reject
401 unsigned messages. To preclude new servers from interacting with old servers,
402 include the following in the ``[global]`` section of your `Ceph
403 configuration`_ file directly below the line that specifies the use of Cephx
406 cephx require signatures = true ; everywhere possible
408 You can also selectively require signatures for cluster internal
409 communications only, separate from client-facing service::
411 cephx cluster require signatures = true ; for cluster-internal communication
412 cephx service require signatures = true ; for client-facing service
414 An option to make a client require signatures from the cluster is not
417 **We recommend migrating all daemons to the newer versions and enabling the
418 foregoing flag** at the nearest practical time so that you may avail yourself
419 of the enhanced authentication.
421 .. note:: Ceph kernel modules do not support signatures yet.
424 .. _Storage Cluster Quick Start: ../../../start/quick-ceph-deploy/
425 .. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping
426 .. _Operating a Cluster: ../../operations/operating
427 .. _Manual Deployment: ../../../install/manual-deployment
428 .. _Cephx: http://docs.ceph.com/docs/cuttlefish/rados/configuration/auth-config-ref/
429 .. _Ceph configuration: ../ceph-conf
430 .. _Create an Admin Host: ../../deployment/ceph-deploy-admin
431 .. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication
432 .. _User Management: ../../operations/user-management