7 This document describes :term:`Ceph Client` users, and their authentication and
8 authorization with the :term:`Ceph Storage Cluster`. Users are either
9 individuals or system actors such as applications, which use Ceph clients to
10 interact with the Ceph Storage Cluster daemons.
16 +--+--+ /---------\ /---------\
18 ---+---*----->| |<------------->| |
19 | uses | Clients | | Servers |
20 | \---------/ \---------/
27 When Ceph runs with authentication and authorization enabled (enabled by
28 default), you must specify a user name and a keyring containing the secret key
29 of the specified user (usually via the command line). If you do not specify a
30 user name, Ceph will use ``client.admin`` as the default user name. If you do
31 not specify a keyring, Ceph will look for a keyring via the ``keyring`` setting
32 in the Ceph configuration. For example, if you execute the ``ceph health``
33 command without specifying a user or keyring::
37 Ceph interprets the command like this::
39 ceph -n client.admin --keyring=/etc/ceph/ceph.client.admin.keyring health
41 Alternatively, you may use the ``CEPH_ARGS`` environment variable to avoid
42 re-entry of the user name and secret.
44 For details on configuring the Ceph Storage Cluster to use authentication,
45 see `Cephx Config Reference`_. For details on the architecture of Cephx, see
46 `Architecture - High Availability Authentication`_.
51 Irrespective of the type of Ceph client (e.g., Block Device, Object Storage,
52 Filesystem, native API, etc.), Ceph stores all data as objects within `pools`_.
53 Ceph users must have access to pools in order to read and write data.
54 Additionally, Ceph users must have execute permissions to use Ceph's
55 administrative commands. The following concepts will help you understand Ceph
61 A user is either an individual or a system actor such as an application.
62 Creating users allows you to control who (or what) can access your Ceph Storage
63 Cluster, its pools, and the data within pools.
65 Ceph has the notion of a ``type`` of user. For the purposes of user management,
66 the type will always be ``client``. Ceph identifies users in period (.)
67 delimited form consisting of the user type and the user ID: for example,
68 ``TYPE.ID``, ``client.admin``, or ``client.user1``. The reason for user typing
69 is that Ceph Monitors, OSDs, and Metadata Servers also use the Cephx protocol,
70 but they are not clients. Distinguishing the user type helps to distinguish
71 between client users and other users--streamlining access control, user
72 monitoring and traceability.
74 Sometimes Ceph's user type may seem confusing, because the Ceph command line
75 allows you to specify a user with or without the type, depending upon your
76 command line usage. If you specify ``--user`` or ``--id``, you can omit the
77 type. So ``client.user1`` can be entered simply as ``user1``. If you specify
78 ``--name`` or ``-n``, you must specify the type and name, such as
79 ``client.user1``. We recommend using the type and name as a best practice
82 .. note:: A Ceph Storage Cluster user is not the same as a Ceph Object Storage
83 user or a Ceph File System user. The Ceph Object Gateway uses a Ceph Storage
84 Cluster user to communicate between the gateway daemon and the storage
85 cluster, but the gateway has its own user management functionality for end
86 users. The Ceph File System uses POSIX semantics. The user space associated
87 with the Ceph File System is not the same as a Ceph Storage Cluster user.
91 Authorization (Capabilities)
92 ----------------------------
94 Ceph uses the term "capabilities" (caps) to describe authorizing an
95 authenticated user to exercise the functionality of the monitors, OSDs and
96 metadata servers. Capabilities can also restrict access to data within a pool,
97 a namespace within a pool, or a set of pools based on their application tags.
98 A Ceph administrative user sets a user's capabilities when creating or updating
101 Capability syntax follows the form::
103 {daemon-type} '{cap-spec}[, {cap-spec} ...]'
105 - **Monitor Caps:** Monitor capabilities include ``r``, ``w``, ``x`` access
106 settings or ``profile {name}``. For example::
108 mon 'allow {access-spec} [network {network/prefix}]'
112 The ``{access-spec}`` syntax is as follows: ::
116 The optional ``{network/prefix}`` is a standard network name and
117 prefix length in CIDR notation (e.g., ``10.3.0.0/16``). If present,
118 the use of this capability is restricted to clients connecting from
121 - **OSD Caps:** OSD capabilities include ``r``, ``w``, ``x``, ``class-read``,
122 ``class-write`` access settings or ``profile {name}``. Additionally, OSD
123 capabilities also allow for pool and namespace settings. ::
125 osd 'allow {access-spec} [{match-spec}] [network {network/prefix}]'
127 osd 'profile {name} [pool={pool-name} [namespace={namespace-name}]] [network {network/prefix}]'
129 The ``{access-spec}`` syntax is either of the following: ::
131 * | all | [r][w][x] [class-read] [class-write]
133 class {class name} [{method name}]
135 The optional ``{match-spec}`` syntax is either of the following: ::
137 pool={pool-name} [namespace={namespace-name}] [object_prefix {prefix}]
139 [namespace={namespace-name}] tag {application} {key}={value}
141 The optional ``{network/prefix}`` is a standard network name and
142 prefix length in CIDR notation (e.g., ``10.3.0.0/16``). If present,
143 the use of this capability is restricted to clients connecting from
146 - **Manager Caps:** Manager (``ceph-mgr``) capabilities include
147 ``r``, ``w``, ``x`` access settings or ``profile {name}``. For example: ::
149 mgr 'allow {access-spec} [network {network/prefix}]'
151 mgr 'profile {name} [{key1} {match-type} {value1} ...] [network {network/prefix}]'
153 Manager capabilities can also be specified for specific commands,
154 all commands exported by a built-in manager service, or all commands
155 exported by a specific add-on module. For example: ::
157 mgr 'allow command "{command-prefix}" [with {key1} {match-type} {value1} ...] [network {network/prefix}]'
159 mgr 'allow service {service-name} {access-spec} [network {network/prefix}]'
161 mgr 'allow module {module-name} [with {key1} {match-type} {value1} ...] {access-spec} [network {network/prefix}]'
163 The ``{access-spec}`` syntax is as follows: ::
167 The ``{service-name}`` is one of the following: ::
171 The ``{match-type}`` is one of the following: ::
175 - **Metadata Server Caps:** For administrators, use ``allow *``. For all
176 other users, such as CephFS clients, consult :doc:`/cephfs/client-auth`
179 .. note:: The Ceph Object Gateway daemon (``radosgw``) is a client of the
180 Ceph Storage Cluster, so it is not represented as a Ceph Storage
183 The following entries describe each access capability.
187 :Description: Precedes access settings for a daemon. Implies ``rw``
193 :Description: Gives the user read access. Required with monitors to retrieve
199 :Description: Gives the user write access to objects.
204 :Description: Gives the user the capability to call class methods
205 (i.e., both read and write) and to conduct ``auth``
206 operations on monitors.
211 :Descriptions: Gives the user the capability to call class read methods.
217 :Description: Gives the user the capability to call class write methods.
223 :Description: Gives the user read, write and execute permissions for a
224 particular daemon/pool, and the ability to execute
227 The following entries describe valid capability profiles:
229 ``profile osd`` (Monitor only)
231 :Description: Gives a user permissions to connect as an OSD to other OSDs or
232 monitors. Conferred on OSDs to enable OSDs to handle replication
233 heartbeat traffic and status reporting.
236 ``profile mds`` (Monitor only)
238 :Description: Gives a user permissions to connect as a MDS to other MDSs or
242 ``profile bootstrap-osd`` (Monitor only)
244 :Description: Gives a user permissions to bootstrap an OSD. Conferred on
245 deployment tools such as ``ceph-volume``, ``cephadm``, etc.
246 so that they have permissions to add keys, etc. when
247 bootstrapping an OSD.
250 ``profile bootstrap-mds`` (Monitor only)
252 :Description: Gives a user permissions to bootstrap a metadata server.
253 Conferred on deployment tools such as ``cephadm``, etc.
254 so they have permissions to add keys, etc. when bootstrapping
257 ``profile bootstrap-rbd`` (Monitor only)
259 :Description: Gives a user permissions to bootstrap an RBD user.
260 Conferred on deployment tools such as ``cephadm``, etc.
261 so they have permissions to add keys, etc. when bootstrapping
264 ``profile bootstrap-rbd-mirror`` (Monitor only)
266 :Description: Gives a user permissions to bootstrap an ``rbd-mirror`` daemon
267 user. Conferred on deployment tools such as ``cephadm``, etc.
268 so they have permissions to add keys, etc. when bootstrapping
269 an ``rbd-mirror`` daemon.
271 ``profile rbd`` (Manager, Monitor, and OSD)
273 :Description: Gives a user permissions to manipulate RBD images. When used
274 as a Monitor cap, it provides the minimal privileges required
275 by an RBD client application; this includes the ability
276 to blocklist other client users. When used as an OSD cap, it
277 provides read-write access to the specified pool to an
278 RBD client application. The Manager cap supports optional
279 ``pool`` and ``namespace`` keyword arguments.
281 ``profile rbd-mirror`` (Monitor only)
283 :Description: Gives a user permissions to manipulate RBD images and retrieve
284 RBD mirroring config-key secrets. It provides the minimal
285 privileges required for the ``rbd-mirror`` daemon.
287 ``profile rbd-read-only`` (Manager and OSD)
289 :Description: Gives a user read-only permissions to RBD images. The Manager
290 cap supports optional ``pool`` and ``namespace`` keyword
293 ``profile simple-rados-client`` (Monitor only)
295 :Description: Gives a user read-only permissions for monitor, OSD, and PG data.
296 Intended for use by direct librados client applications.
298 ``profile simple-rados-client-with-blocklist`` (Monitor only)
300 :Description: Gives a user read-only permissions for monitor, OSD, and PG data.
301 Intended for use by direct librados client applications. Also
302 includes permission to add blocklist entries to build HA
305 ``profile fs-client`` (Monitor only)
307 :Description: Gives a user read-only permissions for monitor, OSD, PG, and MDS
308 data. Intended for CephFS clients.
310 ``profile role-definer`` (Monitor and Auth)
312 :Description: Gives a user **all** permissions for the auth subsystem, read-only
313 access to monitors, and nothing else. Useful for automation
314 tools. Do not assign this unless you really, **really** know what
315 you're doing as the security ramifications are substantial and
318 ``profile crash`` (Monitor and MGR)
320 :Description: Gives a user read-only access to monitors, used in conjunction
321 with the manager ``crash`` module to upload daemon crash
322 dumps into monitor storage for later analysis.
327 A pool is a logical partition where users store data.
328 In Ceph deployments, it is common to create a pool as a logical partition for
329 similar types of data. For example, when deploying Ceph as a backend for
330 OpenStack, a typical deployment would have pools for volumes, images, backups
331 and virtual machines, and users such as ``client.glance``, ``client.cinder``,
337 Access may be restricted to specific pools as defined by their application
338 metadata. The ``*`` wildcard may be used for the ``key`` argument, the
339 ``value`` argument, or both. ``all`` is a synony for ``*``.
344 Objects within a pool can be associated to a namespace--a logical group of
345 objects within the pool. A user's access to a pool can be associated with a
346 namespace such that reads and writes by the user take place only within the
347 namespace. Objects written to a namespace within the pool can only be accessed
348 by users who have access to the namespace.
350 .. note:: Namespaces are primarily useful for applications written on top of
351 ``librados`` where the logical grouping can alleviate the need to create
352 different pools. Ceph Object Gateway (from ``luminous``) uses namespaces for various
355 The rationale for namespaces is that pools can be a computationally expensive
356 method of segregating data sets for the purposes of authorizing separate sets
357 of users. For example, a pool should have ~100 placement groups per OSD. So an
358 exemplary cluster with 1000 OSDs would have 100,000 placement groups for one
359 pool. Each pool would create another 100,000 placement groups in the exemplary
360 cluster. By contrast, writing an object to a namespace simply associates the
361 namespace to the object name with out the computational overhead of a separate
362 pool. Rather than creating a separate pool for a user or set of users, you may
363 use a namespace. **Note:** Only available using ``librados`` at this time.
365 Access may be restricted to specific RADOS namespaces using the ``namespace``
366 capability. Limited globbing of namespaces is supported; if the last character
367 of the specified namespace is ``*``, then access is granted to any namespace
368 starting with the provided argument.
373 User management functionality provides Ceph Storage Cluster administrators with
374 the ability to create, update and delete users directly in the Ceph Storage
377 When you create or delete users in the Ceph Storage Cluster, you may need to
378 distribute keys to clients so that they can be added to keyrings. See `Keyring
379 Management`_ for details.
384 To list the users in your cluster, execute the following::
388 Ceph will list out all users in your cluster. For example, in a two-node
389 exemplary cluster, ``ceph auth ls`` will output something that looks like
392 installed auth entries:
395 key: AQCvCbtToC6MDhAATtuT70Sl+DymPCfDSsyV4w==
396 caps: [mon] allow profile osd
399 key: AQC4CbtTCFJBChAAVq5spj0ff4eHZICxIOVZeA==
400 caps: [mon] allow profile osd
403 key: AQBHCbtT6APDHhAA5W00cBchwkQjh3dkKsyPjw==
408 key: AQBICbtTOK9uGBAAdbe5zcIGHZL3T/u2g6EBww==
409 caps: [mon] allow profile bootstrap-mds
411 key: AQBHCbtT4GxqORAADE5u7RkpCN/oo4e5W0uBtw==
412 caps: [mon] allow profile bootstrap-osd
415 Note that the ``TYPE.ID`` notation for users applies such that ``osd.0`` is a
416 user of type ``osd`` and its ID is ``0``, ``client.admin`` is a user of type
417 ``client`` and its ID is ``admin`` (i.e., the default ``client.admin`` user).
418 Note also that each entry has a ``key: <value>`` entry, and one or more
421 You may use the ``-o {filename}`` option with ``ceph auth ls`` to
422 save the output to a file.
428 To retrieve a specific user, key and capabilities, execute the
431 ceph auth get {TYPE.ID}
435 ceph auth get client.admin
437 You may also use the ``-o {filename}`` option with ``ceph auth get`` to
438 save the output to a file. Developers may also execute the following::
440 ceph auth export {TYPE.ID}
442 The ``auth export`` command is identical to ``auth get``.
447 Adding a user creates a username (i.e., ``TYPE.ID``), a secret key and
448 any capabilities included in the command you use to create the user.
450 A user's key enables the user to authenticate with the Ceph Storage Cluster.
451 The user's capabilities authorize the user to read, write, or execute on Ceph
452 monitors (``mon``), Ceph OSDs (``osd``) or Ceph Metadata Servers (``mds``).
454 There are a few ways to add a user:
456 - ``ceph auth add``: This command is the canonical way to add a user. It
457 will create the user, generate a key and add any specified capabilities.
459 - ``ceph auth get-or-create``: This command is often the most convenient way
460 to create a user, because it returns a keyfile format with the user name
461 (in brackets) and the key. If the user already exists, this command
462 simply returns the user name and key in the keyfile format. You may use the
463 ``-o {filename}`` option to save the output to a file.
465 - ``ceph auth get-or-create-key``: This command is a convenient way to create
466 a user and return the user's key (only). This is useful for clients that
467 need the key only (e.g., libvirt). If the user already exists, this command
468 simply returns the key. You may use the ``-o {filename}`` option to save the
471 When creating client users, you may create a user with no capabilities. A user
472 with no capabilities is useless beyond mere authentication, because the client
473 cannot retrieve the cluster map from the monitor. However, you can create a
474 user with no capabilities if you wish to defer adding capabilities later using
475 the ``ceph auth caps`` command.
477 A typical user has at least read capabilities on the Ceph monitor and
478 read and write capability on Ceph OSDs. Additionally, a user's OSD permissions
479 are often restricted to accessing a particular pool. ::
481 ceph auth add client.john mon 'allow r' osd 'allow rw pool=liverpool'
482 ceph auth get-or-create client.paul mon 'allow r' osd 'allow rw pool=liverpool'
483 ceph auth get-or-create client.george mon 'allow r' osd 'allow rw pool=liverpool' -o george.keyring
484 ceph auth get-or-create-key client.ringo mon 'allow r' osd 'allow rw pool=liverpool' -o ringo.key
487 .. important:: If you provide a user with capabilities to OSDs, but you DO NOT
488 restrict access to particular pools, the user will have access to ALL
489 pools in the cluster!
492 .. _modify-user-capabilities:
494 Modify User Capabilities
495 ------------------------
497 The ``ceph auth caps`` command allows you to specify a user and change the
498 user's capabilities. Setting new capabilities will overwrite current capabilities.
499 To view current capabilities run ``ceph auth get USERTYPE.USERID``. To add
500 capabilities, you should also specify the existing capabilities when using the form::
502 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}]']
506 ceph auth get client.john
507 ceph auth caps client.john mon 'allow r' osd 'allow rw pool=liverpool'
508 ceph auth caps client.paul mon 'allow rw' osd 'allow rwx pool=liverpool'
509 ceph auth caps client.brian-manager mon 'allow *' osd 'allow *'
511 See `Authorization (Capabilities)`_ for additional details on capabilities.
516 To delete a user, use ``ceph auth del``::
518 ceph auth del {TYPE}.{ID}
520 Where ``{TYPE}`` is one of ``client``, ``osd``, ``mon``, or ``mds``,
521 and ``{ID}`` is the user name or ID of the daemon.
527 To print a user's authentication key to standard output, execute the following::
529 ceph auth print-key {TYPE}.{ID}
531 Where ``{TYPE}`` is one of ``client``, ``osd``, ``mon``, or ``mds``,
532 and ``{ID}`` is the user name or ID of the daemon.
534 Printing a user's key is useful when you need to populate client
535 software with a user's key (e.g., libvirt). ::
537 mount -t ceph serverhost:/ mountpoint -o name=client.user,secret=`ceph auth print-key client.user`
542 To import one or more users, use ``ceph auth import`` and
545 ceph auth import -i /path/to/keyring
549 sudo ceph auth import -i /etc/ceph/ceph.keyring
552 .. note:: The Ceph storage cluster will add new users, their keys and their
553 capabilities and will update existing users, their keys and their
559 When you access Ceph via a Ceph client, the Ceph client will look for a local
560 keyring. Ceph presets the ``keyring`` setting with the following four keyring
561 names by default so you don't have to set them in your Ceph configuration file
562 unless you want to override the defaults (not recommended):
564 - ``/etc/ceph/$cluster.$name.keyring``
565 - ``/etc/ceph/$cluster.keyring``
566 - ``/etc/ceph/keyring``
567 - ``/etc/ceph/keyring.bin``
569 The ``$cluster`` metavariable is your Ceph cluster name as defined by the
570 name of the Ceph configuration file (i.e., ``ceph.conf`` means the cluster name
571 is ``ceph``; thus, ``ceph.keyring``). The ``$name`` metavariable is the user
572 type and user ID (e.g., ``client.admin``; thus, ``ceph.client.admin.keyring``).
574 .. note:: When executing commands that read or write to ``/etc/ceph``, you may
575 need to use ``sudo`` to execute the command as ``root``.
577 After you create a user (e.g., ``client.ringo``), you must get the key and add
578 it to a keyring on a Ceph client so that the user can access the Ceph Storage
581 The `User Management`_ section details how to list, get, add, modify and delete
582 users directly in the Ceph Storage Cluster. However, Ceph also provides the
583 ``ceph-authtool`` utility to allow you to manage keyrings from a Ceph client.
588 When you use the procedures in the `Managing Users`_ section to create users,
589 you need to provide user keys to the Ceph client(s) so that the Ceph client
590 can retrieve the key for the specified user and authenticate with the Ceph
591 Storage Cluster. Ceph Clients access keyrings to lookup a user name and
592 retrieve the user's key.
594 The ``ceph-authtool`` utility allows you to create a keyring. To create an
595 empty keyring, use ``--create-keyring`` or ``-C``. For example::
597 ceph-authtool --create-keyring /path/to/keyring
599 When creating a keyring with multiple users, we recommend using the cluster name
600 (e.g., ``$cluster.keyring``) for the keyring filename and saving it in the
601 ``/etc/ceph`` directory so that the ``keyring`` configuration default setting
602 will pick up the filename without requiring you to specify it in the local copy
603 of your Ceph configuration file. For example, create ``ceph.keyring`` by
604 executing the following::
606 sudo ceph-authtool -C /etc/ceph/ceph.keyring
608 When creating a keyring with a single user, we recommend using the cluster name,
609 the user type and the user name and saving it in the ``/etc/ceph`` directory.
610 For example, ``ceph.client.admin.keyring`` for the ``client.admin`` user.
612 To create a keyring in ``/etc/ceph``, you must do so as ``root``. This means
613 the file will have ``rw`` permissions for the ``root`` user only, which is
614 appropriate when the keyring contains administrator keys. However, if you
615 intend to use the keyring for a particular user or group of users, ensure
616 that you execute ``chown`` or ``chmod`` to establish appropriate keyring
617 ownership and access.
619 Add a User to a Keyring
620 -----------------------
622 When you `Add a User`_ to the Ceph Storage Cluster, you can use the `Get a
623 User`_ procedure to retrieve a user, key and capabilities and save the user to a
626 When you only want to use one user per keyring, the `Get a User`_ procedure with
627 the ``-o`` option will save the output in the keyring file format. For example,
628 to create a keyring for the ``client.admin`` user, execute the following::
630 sudo ceph auth get client.admin -o /etc/ceph/ceph.client.admin.keyring
632 Notice that we use the recommended file format for an individual user.
634 When you want to import users to a keyring, you can use ``ceph-authtool``
635 to specify the destination keyring and the source keyring.
638 sudo ceph-authtool /etc/ceph/ceph.keyring --import-keyring /etc/ceph/ceph.client.admin.keyring
643 Ceph provides the `Add a User`_ function to create a user directly in the Ceph
644 Storage Cluster. However, you can also create a user, keys and capabilities
645 directly on a Ceph client keyring. Then, you can import the user to the Ceph
646 Storage Cluster. For example::
648 sudo ceph-authtool -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' /etc/ceph/ceph.keyring
650 See `Authorization (Capabilities)`_ for additional details on capabilities.
652 You can also create a keyring and add a new user to the keyring simultaneously.
655 sudo ceph-authtool -C /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' --gen-key
657 In the foregoing scenarios, the new user ``client.ringo`` is only in the
658 keyring. To add the new user to the Ceph Storage Cluster, you must still add
659 the new user to the Ceph Storage Cluster. ::
661 sudo ceph auth add client.ringo -i /etc/ceph/ceph.keyring
666 To modify the capabilities of a user record in a keyring, specify the keyring,
667 and the user followed by the capabilities. For example::
669 sudo ceph-authtool /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx'
671 To update the user to the Ceph Storage Cluster, you must update the user
672 in the keyring to the user entry in the Ceph Storage Cluster. ::
674 sudo ceph auth import -i /etc/ceph/ceph.keyring
676 See `Import a User(s)`_ for details on updating a Ceph Storage Cluster user
679 You may also `Modify User Capabilities`_ directly in the cluster, store the
680 results to a keyring file; then, import the keyring into your main
681 ``ceph.keyring`` file.
686 Ceph supports the following usage for user name and secret:
688 ``--id`` | ``--user``
690 :Description: Ceph identifies users with a type and an ID (e.g., ``TYPE.ID`` or
691 ``client.admin``, ``client.user1``). The ``id``, ``name`` and
692 ``-n`` options enable you to specify the ID portion of the user
693 name (e.g., ``admin``, ``user1``, ``foo``, etc.). You can specify
694 the user with the ``--id`` and omit the type. For example,
695 to specify user ``client.foo`` enter the following::
697 ceph --id foo --keyring /path/to/keyring health
698 ceph --user foo --keyring /path/to/keyring health
703 :Description: Ceph identifies users with a type and an ID (e.g., ``TYPE.ID`` or
704 ``client.admin``, ``client.user1``). The ``--name`` and ``-n``
705 options enables you to specify the fully qualified user name.
706 You must specify the user type (typically ``client``) with the
707 user ID. For example::
709 ceph --name client.foo --keyring /path/to/keyring health
710 ceph -n client.foo --keyring /path/to/keyring health
715 :Description: The path to the keyring containing one or more user name and
716 secret. The ``--secret`` option provides the same functionality,
717 but it does not work with Ceph RADOS Gateway, which uses
718 ``--secret`` for another purpose. You may retrieve a keyring with
719 ``ceph auth get-or-create`` and store it locally. This is a
720 preferred approach, because you can switch user names without
721 switching the keyring path. For example::
723 sudo rbd map --id foo --keyring /path/to/keyring mypool/myimage
731 The ``cephx`` protocol authenticates Ceph clients and servers to each other. It
732 is not intended to handle authentication of human users or application programs
733 run on their behalf. If that effect is required to handle your access control
734 needs, you must have another mechanism, which is likely to be specific to the
735 front end used to access the Ceph object store. This other mechanism has the
736 role of ensuring that only acceptable users and programs are able to run on the
737 machine that Ceph will permit to access its object store.
739 The keys used to authenticate Ceph clients and servers are typically stored in
740 a plain text file with appropriate permissions in a trusted host.
742 .. important:: Storing keys in plaintext files has security shortcomings, but
743 they are difficult to avoid, given the basic authentication methods Ceph
744 uses in the background. Those setting up Ceph systems should be aware of
747 In particular, arbitrary user machines, especially portable machines, should not
748 be configured to interact directly with Ceph, since that mode of use would
749 require the storage of a plaintext authentication key on an insecure machine.
750 Anyone who stole that machine or obtained surreptitious access to it could
751 obtain the key that will allow them to authenticate their own machines to Ceph.
753 Rather than permitting potentially insecure machines to access a Ceph object
754 store directly, users should be required to sign in to a trusted machine in
755 your environment using a method that provides sufficient security for your
756 purposes. That trusted machine will store the plaintext Ceph keys for the
757 human users. A future version of Ceph may address these particular
758 authentication issues more fully.
760 At the moment, none of the Ceph authentication protocols provide secrecy for
761 messages in transit. Thus, an eavesdropper on the wire can hear and understand
762 all data sent between clients and servers in Ceph, even if it cannot create or
763 alter them. Further, Ceph does not include options to encrypt user data in the
764 object store. Users can hand-encrypt and store their own data in the Ceph
765 object store, of course, but Ceph provides no features to perform object
766 encryption itself. Those storing sensitive data in Ceph should consider
767 encrypting their data before providing it to the Ceph system.
770 .. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication
771 .. _Cephx Config Reference: ../../configuration/auth-config-ref