5 This document describes :term:`Ceph Client` users, and their authentication and
6 authorization with the :term:`Ceph Storage Cluster`. Users are either
7 individuals or system actors such as applications, which use Ceph clients to
8 interact with the Ceph Storage Cluster daemons.
13 +--+--+ /---------\ /---------\
15 ---+---*----->| |<------------->| |
16 | uses | Clients | | Servers |
17 | \---------/ \---------/
24 When Ceph runs with authentication and authorization enabled (enabled by
25 default), you must specify a user name and a keyring containing the secret key
26 of the specified user (usually via the command line). If you do not specify a
27 user name, Ceph will use ``client.admin`` as the default user name. If you do
28 not specify a keyring, Ceph will look for a keyring via the ``keyring`` setting
29 in the Ceph configuration. For example, if you execute the ``ceph health``
30 command without specifying a user or keyring::
34 Ceph interprets the command like this::
36 ceph -n client.admin --keyring=/etc/ceph/ceph.client.admin.keyring health
38 Alternatively, you may use the ``CEPH_ARGS`` environment variable to avoid
39 re-entry of the user name and secret.
41 For details on configuring the Ceph Storage Cluster to use authentication,
42 see `Cephx Config Reference`_. For details on the architecture of Cephx, see
43 `Architecture - High Availability Authentication`_.
49 Irrespective of the type of Ceph client (e.g., Block Device, Object Storage,
50 Filesystem, native API, etc.), Ceph stores all data as objects within `pools`_.
51 Ceph users must have access to pools in order to read and write data.
52 Additionally, Ceph users must have execute permissions to use Ceph's
53 administrative commands. The following concepts will help you understand Ceph
60 A user is either an individual or a system actor such as an application.
61 Creating users allows you to control who (or what) can access your Ceph Storage
62 Cluster, its pools, and the data within pools.
64 Ceph has the notion of a ``type`` of user. For the purposes of user management,
65 the type will always be ``client``. Ceph identifies users in period (.)
66 delimited form consisting of the user type and the user ID: for example,
67 ``TYPE.ID``, ``client.admin``, or ``client.user1``. The reason for user typing
68 is that Ceph Monitors, OSDs, and Metadata Servers also use the Cephx protocol,
69 but they are not clients. Distinguishing the user type helps to distinguish
70 between client users and other users--streamlining access control, user
71 monitoring and traceability.
73 Sometimes Ceph's user type may seem confusing, because the Ceph command line
74 allows you to specify a user with or without the type, depending upon your
75 command line usage. If you specify ``--user`` or ``--id``, you can omit the
76 type. So ``client.user1`` can be entered simply as ``user1``. If you specify
77 ``--name`` or ``-n``, you must specify the type and name, such as
78 ``client.user1``. We recommend using the type and name as a best practice
81 .. note:: A Ceph Storage Cluster user is not the same as a Ceph Object Storage
82 user or a Ceph Filesystem user. The Ceph Object Gateway uses a Ceph Storage
83 Cluster user to communicate between the gateway daemon and the storage
84 cluster, but the gateway has its own user management functionality for end
85 users. The Ceph Filesystem uses POSIX semantics. The user space associated
86 with the Ceph Filesystem is not the same as a Ceph Storage Cluster user.
90 Authorization (Capabilities)
91 ----------------------------
93 Ceph uses the term "capabilities" (caps) to describe authorizing an
94 authenticated user to exercise the functionality of the monitors, OSDs and
95 metadata servers. Capabilities can also restrict access to data within a pool or
96 a namespace within a pool. A Ceph administrative user sets a user's
97 capabilities when creating or updating a user.
99 Capability syntax follows the form::
101 {daemon-type} '{capspec}[, {capspec} ...]'
103 - **Monitor Caps:** Monitor capabilities include ``r``, ``w``, ``x`` access
104 settings or ``profile {name}``. For example::
109 - **OSD Caps:** OSD capabilities include ``r``, ``w``, ``x``, ``class-read``,
110 ``class-write`` access settings or ``profile {name}``. Additionally, OSD
111 capabilities also allow for pool and namespace settings. ::
113 osd 'allow {access} [pool={pool-name} [namespace={namespace-name}]]'
114 osd 'profile {name} [pool={pool-name} [namespace={namespace-name}]]'
116 - **Metadata Server Caps:** For administrators, use ``allow *``. For all
117 other users, such as CephFS clients, consult :doc:`/cephfs/client-auth`
120 .. note:: The Ceph Object Gateway daemon (``radosgw``) is a client of the
121 Ceph Storage Cluster, so it is not represented as a Ceph Storage
124 The following entries describe each capability.
128 :Description: Precedes access settings for a daemon. Implies ``rw``
134 :Description: Gives the user read access. Required with monitors to retrieve
140 :Description: Gives the user write access to objects.
145 :Description: Gives the user the capability to call class methods
146 (i.e., both read and write) and to conduct ``auth``
147 operations on monitors.
152 :Descriptions: Gives the user the capability to call class read methods.
158 :Description: Gives the user the capability to call class write methods.
164 :Description: Gives the user read, write and execute permissions for a
165 particular daemon/pool, and the ability to execute
169 ``profile osd`` (Monitor only)
171 :Description: Gives a user permissions to connect as an OSD to other OSDs or
172 monitors. Conferred on OSDs to enable OSDs to handle replication
173 heartbeat traffic and status reporting.
176 ``profile mds`` (Monitor only)
178 :Description: Gives a user permissions to connect as a MDS to other MDSs or
182 ``profile bootstrap-osd`` (Monitor only)
184 :Description: Gives a user permissions to bootstrap an OSD. Conferred on
185 deployment tools such as ``ceph-disk``, ``ceph-deploy``, etc.
186 so that they have permissions to add keys, etc. when
187 bootstrapping an OSD.
190 ``profile bootstrap-mds`` (Monitor only)
192 :Description: Gives a user permissions to bootstrap a metadata server.
193 Conferred on deployment tools such as ``ceph-deploy``, etc.
194 so they have permissions to add keys, etc. when bootstrapping
197 ``profile rbd`` (Monitor and OSD)
199 :Description: Gives a user permissions to manipulate RBD images. When used
200 as a Monitor cap, it provides the minimal privileges required
201 by an RBD client application. When used as an OSD cap, it
202 provides read-write access to an RBD client application.
204 ``profile rbd-read-only`` (OSD only)
206 :Description: Gives a user read-only permissions to an RBD image.
212 A pool is a logical partition where users store data.
213 In Ceph deployments, it is common to create a pool as a logical partition for
214 similar types of data. For example, when deploying Ceph as a backend for
215 OpenStack, a typical deployment would have pools for volumes, images, backups
216 and virtual machines, and users such as ``client.glance``, ``client.cinder``,
223 Objects within a pool can be associated to a namespace--a logical group of
224 objects within the pool. A user's access to a pool can be associated with a
225 namespace such that reads and writes by the user take place only within the
226 namespace. Objects written to a namespace within the pool can only be accessed
227 by users who have access to the namespace.
229 .. note:: Namespaces are primarily useful for applications written on top of
230 ``librados`` where the logical grouping can alleviate the need to create
231 different pools. Ceph Object Gateway (from ``luminous``) uses namespaces for various
234 The rationale for namespaces is that pools can be a computationally expensive
235 method of segregating data sets for the purposes of authorizing separate sets
236 of users. For example, a pool should have ~100 placement groups per OSD. So an
237 exemplary cluster with 1000 OSDs would have 100,000 placement groups for one
238 pool. Each pool would create another 100,000 placement groups in the exemplary
239 cluster. By contrast, writing an object to a namespace simply associates the
240 namespace to the object name with out the computational overhead of a separate
241 pool. Rather than creating a separate pool for a user or set of users, you may
242 use a namespace. **Note:** Only available using ``librados`` at this time.
248 User management functionality provides Ceph Storage Cluster administrators with
249 the ability to create, update and delete users directly in the Ceph Storage
252 When you create or delete users in the Ceph Storage Cluster, you may need to
253 distribute keys to clients so that they can be added to keyrings. See `Keyring
254 Management`_ for details.
260 To list the users in your cluster, execute the following::
264 Ceph will list out all users in your cluster. For example, in a two-node
265 exemplary cluster, ``ceph auth ls`` will output something that looks like
268 installed auth entries:
271 key: AQCvCbtToC6MDhAATtuT70Sl+DymPCfDSsyV4w==
272 caps: [mon] allow profile osd
275 key: AQC4CbtTCFJBChAAVq5spj0ff4eHZICxIOVZeA==
276 caps: [mon] allow profile osd
279 key: AQBHCbtT6APDHhAA5W00cBchwkQjh3dkKsyPjw==
284 key: AQBICbtTOK9uGBAAdbe5zcIGHZL3T/u2g6EBww==
285 caps: [mon] allow profile bootstrap-mds
287 key: AQBHCbtT4GxqORAADE5u7RkpCN/oo4e5W0uBtw==
288 caps: [mon] allow profile bootstrap-osd
291 Note that the ``TYPE.ID`` notation for users applies such that ``osd.0`` is a
292 user of type ``osd`` and its ID is ``0``, ``client.admin`` is a user of type
293 ``client`` and its ID is ``admin`` (i.e., the default ``client.admin`` user).
294 Note also that each entry has a ``key: <value>`` entry, and one or more
297 You may use the ``-o {filename}`` option with ``ceph auth ls`` to
298 save the output to a file.
304 To retrieve a specific user, key and capabilities, execute the
307 ceph auth get {TYPE.ID}
311 ceph auth get client.admin
313 You may also use the ``-o {filename}`` option with ``ceph auth get`` to
314 save the output to a file. Developers may also execute the following::
316 ceph auth export {TYPE.ID}
318 The ``auth export`` command is identical to ``auth get``, but also prints
319 out the internal ``auid``, which is not relevant to end users.
326 Adding a user creates a username (i.e., ``TYPE.ID``), a secret key and
327 any capabilities included in the command you use to create the user.
329 A user's key enables the user to authenticate with the Ceph Storage Cluster.
330 The user's capabilities authorize the user to read, write, or execute on Ceph
331 monitors (``mon``), Ceph OSDs (``osd``) or Ceph Metadata Servers (``mds``).
333 There are a few ways to add a user:
335 - ``ceph auth add``: This command is the canonical way to add a user. It
336 will create the user, generate a key and add any specified capabilities.
338 - ``ceph auth get-or-create``: This command is often the most convenient way
339 to create a user, because it returns a keyfile format with the user name
340 (in brackets) and the key. If the user already exists, this command
341 simply returns the user name and key in the keyfile format. You may use the
342 ``-o {filename}`` option to save the output to a file.
344 - ``ceph auth get-or-create-key``: This command is a convenient way to create
345 a user and return the user's key (only). This is useful for clients that
346 need the key only (e.g., libvirt). If the user already exists, this command
347 simply returns the key. You may use the ``-o {filename}`` option to save the
350 When creating client users, you may create a user with no capabilities. A user
351 with no capabilities is useless beyond mere authentication, because the client
352 cannot retrieve the cluster map from the monitor. However, you can create a
353 user with no capabilities if you wish to defer adding capabilities later using
354 the ``ceph auth caps`` command.
356 A typical user has at least read capabilities on the Ceph monitor and
357 read and write capability on Ceph OSDs. Additionally, a user's OSD permissions
358 are often restricted to accessing a particular pool. ::
360 ceph auth add client.john mon 'allow r' osd 'allow rw pool=liverpool'
361 ceph auth get-or-create client.paul mon 'allow r' osd 'allow rw pool=liverpool'
362 ceph auth get-or-create client.george mon 'allow r' osd 'allow rw pool=liverpool' -o george.keyring
363 ceph auth get-or-create-key client.ringo mon 'allow r' osd 'allow rw pool=liverpool' -o ringo.key
366 .. important:: If you provide a user with capabilities to OSDs, but you DO NOT
367 restrict access to particular pools, the user will have access to ALL
368 pools in the cluster!
371 .. _modify-user-capabilities:
373 Modify User Capabilities
374 ------------------------
376 The ``ceph auth caps`` command allows you to specify a user and change the
377 user's capabilities. Setting new capabilities will overwrite current capabilities.
378 To view current capabilities run ``ceph auth get USERTYPE.USERID``. To add
379 capabilities, you should also specify the existing capabilities when using the form::
381 ceph auth caps USERTYPE.USERID {daemon} 'allow [r|w|x|*|...] [pool={pool-name}] [namespace={namespace-name}]' [{daemon} 'allow [r|w|x|*|...] [pool={pool-name}] [namespace={namespace-name}]']
385 ceph auth get client.john
386 ceph auth caps client.john mon 'allow r' osd 'allow rw pool=liverpool'
387 ceph auth caps client.paul mon 'allow rw' osd 'allow rwx pool=liverpool'
388 ceph auth caps client.brian-manager mon 'allow *' osd 'allow *'
390 To remove a capability, you may reset the capability. If you want the user
391 to have no access to a particular daemon that was previously set, specify
392 an empty string. For example::
394 ceph auth caps client.ringo mon ' ' osd ' '
396 See `Authorization (Capabilities)`_ for additional details on capabilities.
402 To delete a user, use ``ceph auth del``::
404 ceph auth del {TYPE}.{ID}
406 Where ``{TYPE}`` is one of ``client``, ``osd``, ``mon``, or ``mds``,
407 and ``{ID}`` is the user name or ID of the daemon.
413 To print a user's authentication key to standard output, execute the following::
415 ceph auth print-key {TYPE}.{ID}
417 Where ``{TYPE}`` is one of ``client``, ``osd``, ``mon``, or ``mds``,
418 and ``{ID}`` is the user name or ID of the daemon.
420 Printing a user's key is useful when you need to populate client
421 software with a user's key (e.g., libvirt). ::
423 mount -t ceph serverhost:/ mountpoint -o name=client.user,secret=`ceph auth print-key client.user`
429 To import one or more users, use ``ceph auth import`` and
432 ceph auth import -i /path/to/keyring
436 sudo ceph auth import -i /etc/ceph/ceph.keyring
439 .. note:: The ceph storage cluster will add new users, their keys and their
440 capabilities and will update existing users, their keys and their
447 When you access Ceph via a Ceph client, the Ceph client will look for a local
448 keyring. Ceph presets the ``keyring`` setting with the following four keyring
449 names by default so you don't have to set them in your Ceph configuration file
450 unless you want to override the defaults (not recommended):
452 - ``/etc/ceph/$cluster.$name.keyring``
453 - ``/etc/ceph/$cluster.keyring``
454 - ``/etc/ceph/keyring``
455 - ``/etc/ceph/keyring.bin``
457 The ``$cluster`` metavariable is your Ceph cluster name as defined by the
458 name of the Ceph configuration file (i.e., ``ceph.conf`` means the cluster name
459 is ``ceph``; thus, ``ceph.keyring``). The ``$name`` metavariable is the user
460 type and user ID (e.g., ``client.admin``; thus, ``ceph.client.admin.keyring``).
462 .. note:: When executing commands that read or write to ``/etc/ceph``, you may
463 need to use ``sudo`` to execute the command as ``root``.
465 After you create a user (e.g., ``client.ringo``), you must get the key and add
466 it to a keyring on a Ceph client so that the user can access the Ceph Storage
469 The `User Management`_ section details how to list, get, add, modify and delete
470 users directly in the Ceph Storage Cluster. However, Ceph also provides the
471 ``ceph-authtool`` utility to allow you to manage keyrings from a Ceph client.
477 When you use the procedures in the `Managing Users`_ section to create users,
478 you need to provide user keys to the Ceph client(s) so that the Ceph client
479 can retrieve the key for the specified user and authenticate with the Ceph
480 Storage Cluster. Ceph Clients access keyrings to lookup a user name and
481 retrieve the user's key.
483 The ``ceph-authtool`` utility allows you to create a keyring. To create an
484 empty keyring, use ``--create-keyring`` or ``-C``. For example::
486 ceph-authtool --create-keyring /path/to/keyring
488 When creating a keyring with multiple users, we recommend using the cluster name
489 (e.g., ``$cluster.keyring``) for the keyring filename and saving it in the
490 ``/etc/ceph`` directory so that the ``keyring`` configuration default setting
491 will pick up the filename without requiring you to specify it in the local copy
492 of your Ceph configuration file. For example, create ``ceph.keyring`` by
493 executing the following::
495 sudo ceph-authtool -C /etc/ceph/ceph.keyring
497 When creating a keyring with a single user, we recommend using the cluster name,
498 the user type and the user name and saving it in the ``/etc/ceph`` directory.
499 For example, ``ceph.client.admin.keyring`` for the ``client.admin`` user.
501 To create a keyring in ``/etc/ceph``, you must do so as ``root``. This means
502 the file will have ``rw`` permissions for the ``root`` user only, which is
503 appropriate when the keyring contains administrator keys. However, if you
504 intend to use the keyring for a particular user or group of users, ensure
505 that you execute ``chown`` or ``chmod`` to establish appropriate keyring
506 ownership and access.
509 Add a User to a Keyring
510 -----------------------
512 When you `Add a User`_ to the Ceph Storage Cluster, you can use the `Get a
513 User`_ procedure to retrieve a user, key and capabilities and save the user to a
516 When you only want to use one user per keyring, the `Get a User`_ procedure with
517 the ``-o`` option will save the output in the keyring file format. For example,
518 to create a keyring for the ``client.admin`` user, execute the following::
520 sudo ceph auth get client.admin -o /etc/ceph/ceph.client.admin.keyring
522 Notice that we use the recommended file format for an individual user.
524 When you want to import users to a keyring, you can use ``ceph-authtool``
525 to specify the destination keyring and the source keyring.
528 sudo ceph-authtool /etc/ceph/ceph.keyring --import-keyring /etc/ceph/ceph.client.admin.keyring
534 Ceph provides the `Add a User`_ function to create a user directly in the Ceph
535 Storage Cluster. However, you can also create a user, keys and capabilities
536 directly on a Ceph client keyring. Then, you can import the user to the Ceph
537 Storage Cluster. For example::
539 sudo ceph-authtool -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' /etc/ceph/ceph.keyring
541 See `Authorization (Capabilities)`_ for additional details on capabilities.
543 You can also create a keyring and add a new user to the keyring simultaneously.
546 sudo ceph-authtool -C /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' --gen-key
548 In the foregoing scenarios, the new user ``client.ringo`` is only in the
549 keyring. To add the new user to the Ceph Storage Cluster, you must still add
550 the new user to the Ceph Storage Cluster. ::
552 sudo ceph auth add client.ringo -i /etc/ceph/ceph.keyring
558 To modify the capabilities of a user record in a keyring, specify the keyring,
559 and the user followed by the capabilities. For example::
561 sudo ceph-authtool /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx'
563 To update the user to the Ceph Storage Cluster, you must update the user
564 in the keyring to the user entry in the the Ceph Storage Cluster. ::
566 sudo ceph auth import -i /etc/ceph/ceph.keyring
568 See `Import a User(s)`_ for details on updating a Ceph Storage Cluster user
571 You may also `Modify User Capabilities`_ directly in the cluster, store the
572 results to a keyring file; then, import the keyring into your main
573 ``ceph.keyring`` file.
579 Ceph supports the following usage for user name and secret:
581 ``--id`` | ``--user``
583 :Description: Ceph identifies users with a type and an ID (e.g., ``TYPE.ID`` or
584 ``client.admin``, ``client.user1``). The ``id``, ``name`` and
585 ``-n`` options enable you to specify the ID portion of the user
586 name (e.g., ``admin``, ``user1``, ``foo``, etc.). You can specify
587 the user with the ``--id`` and omit the type. For example,
588 to specify user ``client.foo`` enter the following::
590 ceph --id foo --keyring /path/to/keyring health
591 ceph --user foo --keyring /path/to/keyring health
596 :Description: Ceph identifies users with a type and an ID (e.g., ``TYPE.ID`` or
597 ``client.admin``, ``client.user1``). The ``--name`` and ``-n``
598 options enables you to specify the fully qualified user name.
599 You must specify the user type (typically ``client``) with the
600 user ID. For example::
602 ceph --name client.foo --keyring /path/to/keyring health
603 ceph -n client.foo --keyring /path/to/keyring health
608 :Description: The path to the keyring containing one or more user name and
609 secret. The ``--secret`` option provides the same functionality,
610 but it does not work with Ceph RADOS Gateway, which uses
611 ``--secret`` for another purpose. You may retrieve a keyring with
612 ``ceph auth get-or-create`` and store it locally. This is a
613 preferred approach, because you can switch user names without
614 switching the keyring path. For example::
616 sudo rbd map --id foo --keyring /path/to/keyring mypool/myimage
625 The ``cephx`` protocol authenticates Ceph clients and servers to each other. It
626 is not intended to handle authentication of human users or application programs
627 run on their behalf. If that effect is required to handle your access control
628 needs, you must have another mechanism, which is likely to be specific to the
629 front end used to access the Ceph object store. This other mechanism has the
630 role of ensuring that only acceptable users and programs are able to run on the
631 machine that Ceph will permit to access its object store.
633 The keys used to authenticate Ceph clients and servers are typically stored in
634 a plain text file with appropriate permissions in a trusted host.
636 .. important:: Storing keys in plaintext files has security shortcomings, but
637 they are difficult to avoid, given the basic authentication methods Ceph
638 uses in the background. Those setting up Ceph systems should be aware of
641 In particular, arbitrary user machines, especially portable machines, should not
642 be configured to interact directly with Ceph, since that mode of use would
643 require the storage of a plaintext authentication key on an insecure machine.
644 Anyone who stole that machine or obtained surreptitious access to it could
645 obtain the key that will allow them to authenticate their own machines to Ceph.
647 Rather than permitting potentially insecure machines to access a Ceph object
648 store directly, users should be required to sign in to a trusted machine in
649 your environment using a method that provides sufficient security for your
650 purposes. That trusted machine will store the plaintext Ceph keys for the
651 human users. A future version of Ceph may address these particular
652 authentication issues more fully.
654 At the moment, none of the Ceph authentication protocols provide secrecy for
655 messages in transit. Thus, an eavesdropper on the wire can hear and understand
656 all data sent between clients and servers in Ceph, even if it cannot create or
657 alter them. Further, Ceph does not include options to encrypt user data in the
658 object store. Users can hand-encrypt and store their own data in the Ceph
659 object store, of course, but Ceph provides no features to perform object
660 encryption itself. Those storing sensitive data in Ceph should consider
661 encrypting their data before providing it to the Ceph system.
664 .. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication
665 .. _Cephx Config Reference: ../../configuration/auth-config-ref