.. _user-management: ================= User Management ================= This document describes :term:`Ceph Client` users, and describes the process by which they perform authentication and authorization so that they can access the :term:`Ceph Storage Cluster`. Users are either individuals or system actors (for example, applications) that use Ceph clients to interact with the Ceph Storage Cluster daemons. .. ditaa:: +-----+ | {o} | | | +--+--+ /---------\ /---------\ | | Ceph | | Ceph | ---+---*----->| |<------------->| | | uses | Clients | | Servers | | \---------/ \---------/ /--+--\ | | | | actor When Ceph runs with authentication and authorization enabled (both are enabled by default), you must specify a user name and a keyring that contains the secret key of the specified user (usually these are specified via the command line). If you do not specify a user name, Ceph will use ``client.admin`` as the default user name. If you do not specify a keyring, Ceph will look for a keyring via the ``keyring`` setting in the Ceph configuration. For example, if you execute the ``ceph health`` command without specifying a user or a keyring, Ceph will assume that the keyring is in ``/etc/ceph/ceph.client.admin.keyring`` and will attempt to use that keyring. The following illustrates this behavior: .. prompt:: bash $ ceph health Ceph will interpret the command like this: .. prompt:: bash $ ceph -n client.admin --keyring=/etc/ceph/ceph.client.admin.keyring health Alternatively, you may use the ``CEPH_ARGS`` environment variable to avoid re-entry of the user name and secret. For details on configuring the Ceph Storage Cluster to use authentication, see `Cephx Config Reference`_. For details on the architecture of Cephx, see `Architecture - High Availability Authentication`_. Background ========== No matter what type of Ceph client is used (for example: Block Device, Object Storage, Filesystem, native API), Ceph stores all data as RADOS objects within `pools`_. Ceph users must have access to a given pool in order to read and write data, and Ceph users must have execute permissions in order to use Ceph's administrative commands. The following concepts will help you understand Ceph['s] user management. .. _rados-ops-user: User ---- A user is either an individual or a system actor (for example, an application). Creating users allows you to control who (or what) can access your Ceph Storage Cluster, its pools, and the data within those pools. Ceph has the concept of a ``type`` of user. For purposes of user management, the type will always be ``client``. Ceph identifies users in a "period- delimited form" that consists of the user type and the user ID: for example, ``TYPE.ID``, ``client.admin``, or ``client.user1``. The reason for user typing is that the Cephx protocol is used not only by clients but also non-clients, such as Ceph Monitors, OSDs, and Metadata Servers. Distinguishing the user type helps to distinguish between client users and other users. This distinction streamlines access control, user monitoring, and traceability. Sometimes Ceph's user type might seem confusing, because the Ceph command line allows you to specify a user with or without the type, depending upon your command line usage. If you specify ``--user`` or ``--id``, you can omit the type. For example, ``client.user1`` can be entered simply as ``user1``. On the other hand, if you specify ``--name`` or ``-n``, you must supply the type and name: for example, ``client.user1``. We recommend using the type and name as a best practice wherever possible. .. note:: A Ceph Storage Cluster user is not the same as a Ceph Object Storage user or a Ceph File System user. The Ceph Object Gateway uses a Ceph Storage Cluster user to communicate between the gateway daemon and the storage cluster, but the Ceph Object Gateway has its own user-management functionality for end users. The Ceph File System uses POSIX semantics, and the user space associated with the Ceph File System is not the same as the user space associated with a Ceph Storage Cluster user. Authorization (Capabilities) ---------------------------- Ceph uses the term "capabilities" (caps) to describe the permissions granted to an authenticated user to exercise the functionality of the monitors, OSDs, and metadata servers. Capabilities can also restrict access to data within a pool, a namespace within a pool, or a set of pools based on their application tags. A Ceph administrative user specifies the capabilities of a user when creating or updating that user. Capability syntax follows this form:: {daemon-type} '{cap-spec}[, {cap-spec} ...]' - **Monitor Caps:** Monitor capabilities include ``r``, ``w``, ``x`` access settings, and can be applied in aggregate from pre-defined profiles with ``profile {name}``. For example:: mon 'allow {access-spec} [network {network/prefix}]' mon 'profile {name}' The ``{access-spec}`` syntax is as follows: :: * | all | [r][w][x] The optional ``{network/prefix}`` is a standard network name and prefix length in CIDR notation (for example, ``10.3.0.0/16``). If ``{network/prefix}`` is present, the monitor capability can be used only by clients that connect from the specified network. - **OSD Caps:** OSD capabilities include ``r``, ``w``, ``x``, and ``class-read`` and ``class-write`` access settings. OSD capabilities can be applied in aggregate from pre-defined profiles with ``profile {name}``. In addition, OSD capabilities allow for pool and namespace settings. :: osd 'allow {access-spec} [{match-spec}] [network {network/prefix}]' osd 'profile {name} [pool={pool-name} [namespace={namespace-name}]] [network {network/prefix}]' There are two alternative forms of the ``{access-spec}`` syntax: :: * | all | [r][w][x] [class-read] [class-write] class {class name} [{method name}] There are two alternative forms of the optional ``{match-spec}`` syntax:: pool={pool-name} [namespace={namespace-name}] [object_prefix {prefix}] [namespace={namespace-name}] tag {application} {key}={value} The optional ``{network/prefix}`` is a standard network name and prefix length in CIDR notation (for example, ``10.3.0.0/16``). If ``{network/prefix}`` is present, the OSD capability can be used only by clients that connect from the specified network. - **Manager Caps:** Manager (``ceph-mgr``) capabilities include ``r``, ``w``, ``x`` access settings, and can be applied in aggregate from pre-defined profiles with ``profile {name}``. For example:: mgr 'allow {access-spec} [network {network/prefix}]' mgr 'profile {name} [{key1} {match-type} {value1} ...] [network {network/prefix}]' Manager capabilities can also be specified for specific commands, for all commands exported by a built-in manager service, or for all commands exported by a specific add-on module. For example:: mgr 'allow command "{command-prefix}" [with {key1} {match-type} {value1} ...] [network {network/prefix}]' mgr 'allow service {service-name} {access-spec} [network {network/prefix}]' mgr 'allow module {module-name} [with {key1} {match-type} {value1} ...] {access-spec} [network {network/prefix}]' The ``{access-spec}`` syntax is as follows: :: * | all | [r][w][x] The ``{service-name}`` is one of the following: :: mgr | osd | pg | py The ``{match-type}`` is one of the following: :: = | prefix | regex - **Metadata Server Caps:** For administrators, use ``allow *``. For all other users (for example, CephFS clients), consult :doc:`/cephfs/client-auth` .. note:: The Ceph Object Gateway daemon (``radosgw``) is a client of the Ceph Storage Cluster. For this reason, it is not represented as a Ceph Storage Cluster daemon type. The following entries describe access capabilities. ``allow`` :Description: Precedes access settings for a daemon. Implies ``rw`` for MDS only. ``r`` :Description: Gives the user read access. Required with monitors to retrieve the CRUSH map. ``w`` :Description: Gives the user write access to objects. ``x`` :Description: Gives the user the capability to call class methods (that is, both read and write) and to conduct ``auth`` operations on monitors. ``class-read`` :Descriptions: Gives the user the capability to call class read methods. Subset of ``x``. ``class-write`` :Description: Gives the user the capability to call class write methods. Subset of ``x``. ``*``, ``all`` :Description: Gives the user read, write, and execute permissions for a particular daemon/pool, as well as the ability to execute admin commands. The following entries describe valid capability profiles: ``profile osd`` (Monitor only) :Description: Gives a user permissions to connect as an OSD to other OSDs or monitors. Conferred on OSDs in order to enable OSDs to handle replication heartbeat traffic and status reporting. ``profile mds`` (Monitor only) :Description: Gives a user permissions to connect as an MDS to other MDSs or monitors. ``profile bootstrap-osd`` (Monitor only) :Description: Gives a user permissions to bootstrap an OSD. Conferred on deployment tools such as ``ceph-volume`` and ``cephadm`` so that they have permissions to add keys when bootstrapping an OSD. ``profile bootstrap-mds`` (Monitor only) :Description: Gives a user permissions to bootstrap a metadata server. Conferred on deployment tools such as ``cephadm`` so that they have permissions to add keys when bootstrapping a metadata server. ``profile bootstrap-rbd`` (Monitor only) :Description: Gives a user permissions to bootstrap an RBD user. Conferred on deployment tools such as ``cephadm`` so that they have permissions to add keys when bootstrapping an RBD user. ``profile bootstrap-rbd-mirror`` (Monitor only) :Description: Gives a user permissions to bootstrap an ``rbd-mirror`` daemon user. Conferred on deployment tools such as ``cephadm`` so that they have permissions to add keys when bootstrapping an ``rbd-mirror`` daemon. ``profile rbd`` (Manager, Monitor, and OSD) :Description: Gives a user permissions to manipulate RBD images. When used as a Monitor cap, it provides the user with the minimal privileges required by an RBD client application; such privileges include the ability to blocklist other client users. When used as an OSD cap, it provides an RBD client application with read-write access to the specified pool. The Manager cap supports optional ``pool`` and ``namespace`` keyword arguments. ``profile rbd-mirror`` (Monitor only) :Description: Gives a user permissions to manipulate RBD images and retrieve RBD mirroring config-key secrets. It provides the minimal privileges required for the user to manipulate the ``rbd-mirror`` daemon. ``profile rbd-read-only`` (Manager and OSD) :Description: Gives a user read-only permissions to RBD images. The Manager cap supports optional ``pool`` and ``namespace`` keyword arguments. ``profile simple-rados-client`` (Monitor only) :Description: Gives a user read-only permissions for monitor, OSD, and PG data. Intended for use by direct librados client applications. ``profile simple-rados-client-with-blocklist`` (Monitor only) :Description: Gives a user read-only permissions for monitor, OSD, and PG data. Intended for use by direct librados client applications. Also includes permissions to add blocklist entries to build high-availability (HA) applications. ``profile fs-client`` (Monitor only) :Description: Gives a user read-only permissions for monitor, OSD, PG, and MDS data. Intended for CephFS clients. ``profile role-definer`` (Monitor and Auth) :Description: Gives a user **all** permissions for the auth subsystem, read-only access to monitors, and nothing else. Useful for automation tools. Do not assign this unless you really, **really** know what you're doing, as the security ramifications are substantial and pervasive. ``profile crash`` (Monitor and MGR) :Description: Gives a user read-only access to monitors. Used in conjunction with the manager ``crash`` module to upload daemon crash dumps into monitor storage for later analysis. Pool ---- A pool is a logical partition where users store data. In Ceph deployments, it is common to create a pool as a logical partition for similar types of data. For example, when deploying Ceph as a back end for OpenStack, a typical deployment would have pools for volumes, images, backups and virtual machines, and such users as ``client.glance`` and ``client.cinder``. Application Tags ---------------- Access may be restricted to specific pools as defined by their application metadata. The ``*`` wildcard may be used for the ``key`` argument, the ``value`` argument, or both. The ``all`` tag is a synonym for ``*``. Namespace --------- Objects within a pool can be associated to a namespace: that is, to a logical group of objects within the pool. A user's access to a pool can be associated with a namespace so that reads and writes by the user can take place only within the namespace. Objects written to a namespace within the pool can be accessed only by users who have access to the namespace. .. note:: Namespaces are primarily useful for applications written on top of ``librados``. In such situations, the logical grouping provided by namespaces can obviate the need to create different pools. In Luminous and later releases, Ceph Object Gateway uses namespaces for various metadata objects. The rationale for namespaces is this: namespaces are relatively less computationally expensive than pools, which (pools) can be a computationally expensive method of segregating data sets between different authorized users. For example, a pool ought to host approximately 100 placement-group replicas per OSD. This means that a cluster with 1000 OSDs and three 3R replicated pools would have (in a single pool) 100,000 placement-group replicas, and that means that it has 33,333 Placement Groups. By contrast, writing an object to a namespace simply associates the namespace to the object name without incurring the computational overhead of a separate pool. Instead of creating a separate pool for a user or set of users, you can use a namespace. .. note:: Namespaces are available only when using ``librados``. Access may be restricted to specific RADOS namespaces by use of the ``namespace`` capability. Limited globbing of namespaces (that is, use of wildcards (``*``)) is supported: if the last character of the specified namespace is ``*``, then access is granted to any namespace starting with the provided argument. Managing Users ============== User management functionality provides Ceph Storage Cluster administrators with the ability to create, update, and delete users directly in the Ceph Storage Cluster. When you create or delete users in the Ceph Storage Cluster, you might need to distribute keys to clients so that they can be added to keyrings. For details, see `Keyring Management`_. Listing Users ------------- To list the users in your cluster, run the following command: .. prompt:: bash $ ceph auth ls Ceph will list all users in your cluster. For example, in a two-node cluster, ``ceph auth ls`` will provide an output that resembles the following:: installed auth entries: osd.0 key: AQCvCbtToC6MDhAATtuT70Sl+DymPCfDSsyV4w== caps: [mon] allow profile osd caps: [osd] allow * osd.1 key: AQC4CbtTCFJBChAAVq5spj0ff4eHZICxIOVZeA== caps: [mon] allow profile osd caps: [osd] allow * client.admin key: AQBHCbtT6APDHhAA5W00cBchwkQjh3dkKsyPjw== caps: [mds] allow caps: [mon] allow * caps: [osd] allow * client.bootstrap-mds key: AQBICbtTOK9uGBAAdbe5zcIGHZL3T/u2g6EBww== caps: [mon] allow profile bootstrap-mds client.bootstrap-osd key: AQBHCbtT4GxqORAADE5u7RkpCN/oo4e5W0uBtw== caps: [mon] allow profile bootstrap-osd Note that, according to the ``TYPE.ID`` notation for users, ``osd.0`` is a user of type ``osd`` and an ID of ``0``, and ``client.admin`` is a user of type ``client`` and an ID of ``admin`` (that is, the default ``client.admin`` user). Note too that each entry has a ``key: `` entry, and also has one or more ``caps:`` entries. To save the output of ``ceph auth ls`` to a file, use the ``-o {filename}`` option. Getting a User -------------- To retrieve a specific user, key, and capabilities, run the following command: .. prompt:: bash $ ceph auth get {TYPE.ID} For example: .. prompt:: bash $ ceph auth get client.admin To save the output of ``ceph auth get`` to a file, use the ``-o {filename}`` option. Developers may also run the following command: .. prompt:: bash $ ceph auth export {TYPE.ID} The ``auth export`` command is identical to ``auth get``. .. _rados_ops_adding_a_user: Adding a User ------------- Adding a user creates a user name (that is, ``TYPE.ID``), a secret key, and any capabilities specified in the command that creates the user. A user's key allows the user to authenticate with the Ceph Storage Cluster. The user's capabilities authorize the user to read, write, or execute on Ceph monitors (``mon``), Ceph OSDs (``osd``) or Ceph Metadata Servers (``mds``). There are a few ways to add a user: - ``ceph auth add``: This command is the canonical way to add a user. It will create the user, generate a key, and add any specified capabilities. - ``ceph auth get-or-create``: This command is often the most convenient way to create a user, because it returns a keyfile format with the user name (in brackets) and the key. If the user already exists, this command simply returns the user name and key in the keyfile format. To save the output to a file, use the ``-o {filename}`` option. - ``ceph auth get-or-create-key``: This command is a convenient way to create a user and return the user's key and nothing else. This is useful for clients that need only the key (for example, libvirt). If the user already exists, this command simply returns the key. To save the output to a file, use the ``-o {filename}`` option. It is possible, when creating client users, to create a user with no capabilities. A user with no capabilities is useless beyond mere authentication, because the client cannot retrieve the cluster map from the monitor. However, you might want to create a user with no capabilities and wait until later to add capabilities to the user by using the ``ceph auth caps`` comand. A typical user has at least read capabilities on the Ceph monitor and read and write capabilities on Ceph OSDs. A user's OSD permissions are often restricted so that the user can access only one particular pool. In the following example, the commands (1) add a client named ``john`` that has read capabilities on the Ceph monitor and read and write capabilities on the pool named ``liverpool``, (2) authorize a client named ``paul`` to have read capabilities on the Ceph monitor and read and write capabilities on the pool named ``liverpool``, (3) authorize a client named ``george`` to have read capabilities on the Ceph monitor and read and write capabilities on the pool named ``liverpool`` and use the keyring named ``george.keyring`` to make this authorization, and (4) authorize a client named ``ringo`` to have read capabilities on the Ceph monitor and read and write capabilities on the pool named ``liverpool`` and use the key named ``ringo.key`` to make this authorization: .. prompt:: bash $ ceph auth add client.john mon 'allow r' osd 'allow rw pool=liverpool' ceph auth get-or-create client.paul mon 'allow r' osd 'allow rw pool=liverpool' ceph auth get-or-create client.george mon 'allow r' osd 'allow rw pool=liverpool' -o george.keyring ceph auth get-or-create-key client.ringo mon 'allow r' osd 'allow rw pool=liverpool' -o ringo.key .. important:: Any user that has capabilities on OSDs will have access to ALL pools in the cluster unless that user's access has been restricted to a proper subset of the pools in the cluster. .. _modify-user-capabilities: Modifying User Capabilities --------------------------- The ``ceph auth caps`` command allows you to specify a user and change that user's capabilities. Setting new capabilities will overwrite current capabilities. To view current capabilities, run ``ceph auth get USERTYPE.USERID``. To add capabilities, run a command of the following form (and be sure to specify the existing capabilities): .. prompt:: bash $ 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}]'] For example: .. prompt:: bash $ ceph auth get client.john ceph auth caps client.john mon 'allow r' osd 'allow rw pool=liverpool' ceph auth caps client.paul mon 'allow rw' osd 'allow rwx pool=liverpool' ceph auth caps client.brian-manager mon 'allow *' osd 'allow *' For additional details on capabilities, see `Authorization (Capabilities)`_. Deleting a User --------------- To delete a user, use ``ceph auth del``: .. prompt:: bash $ ceph auth del {TYPE}.{ID} Here ``{TYPE}`` is either ``client``, ``osd``, ``mon``, or ``mds``, and ``{ID}`` is the user name or the ID of the daemon. Printing a User's Key --------------------- To print a user's authentication key to standard output, run the following command: .. prompt:: bash $ ceph auth print-key {TYPE}.{ID} Here ``{TYPE}`` is either ``client``, ``osd``, ``mon``, or ``mds``, and ``{ID}`` is the user name or the ID of the daemon. When it is necessary to populate client software with a user's key (as in the case of libvirt), you can print the user's key by running the following command: .. prompt:: bash $ mount -t ceph serverhost:/ mountpoint -o name=client.user,secret=`ceph auth print-key client.user` Importing a User ---------------- To import one or more users, use ``ceph auth import`` and specify a keyring as follows: .. prompt:: bash $ ceph auth import -i /path/to/keyring For example: .. prompt:: bash $ sudo ceph auth import -i /etc/ceph/ceph.keyring .. note:: The Ceph storage cluster will add new users, their keys, and their capabilities and will update existing users, their keys, and their capabilities. Keyring Management ================== When you access Ceph via a Ceph client, the Ceph client will look for a local keyring. Ceph presets the ``keyring`` setting with four keyring names by default. For this reason, you do not have to set the keyring names in your Ceph configuration file unless you want to override these defaults (which is not recommended). The four default keyring names are as follows: - ``/etc/ceph/$cluster.$name.keyring`` - ``/etc/ceph/$cluster.keyring`` - ``/etc/ceph/keyring`` - ``/etc/ceph/keyring.bin`` The ``$cluster`` metavariable found in the first two default keyring names above is your Ceph cluster name as defined by the name of the Ceph configuration file: for example, if the Ceph configuration file is named ``ceph.conf``, then your Ceph cluster name is ``ceph`` and the second name above would be ``ceph.keyring``. The ``$name`` metavariable is the user type and user ID: for example, given the user ``client.admin``, the first name above would be ``ceph.client.admin.keyring``. .. note:: When running commands that read or write to ``/etc/ceph``, you might need to use ``sudo`` to run the command as ``root``. After you create a user (for example, ``client.ringo``), you must get the key and add it to a keyring on a Ceph client so that the user can access the Ceph Storage Cluster. The `User Management`_ section details how to list, get, add, modify, and delete users directly in the Ceph Storage Cluster. In addition, Ceph provides the ``ceph-authtool`` utility to allow you to manage keyrings from a Ceph client. Creating a Keyring ------------------ When you use the procedures in the `Managing Users`_ section to create users, you must provide user keys to the Ceph client(s). This is required so that the Ceph client(s) can retrieve the key for the specified user and authenticate that user against the Ceph Storage Cluster. Ceph clients access keyrings in order to look up a user name and retrieve the user's key. The ``ceph-authtool`` utility allows you to create a keyring. To create an empty keyring, use ``--create-keyring`` or ``-C``. For example: .. prompt:: bash $ ceph-authtool --create-keyring /path/to/keyring When creating a keyring with multiple users, we recommend using the cluster name (of the form ``$cluster.keyring``) for the keyring filename and saving the keyring in the ``/etc/ceph`` directory. By doing this, you ensure that the ``keyring`` configuration default setting will pick up the filename without requiring you to specify the filename in the local copy of your Ceph configuration file. For example, you can create ``ceph.keyring`` by running the following command: .. prompt:: bash $ sudo ceph-authtool -C /etc/ceph/ceph.keyring When creating a keyring with a single user, we recommend using the cluster name, the user type, and the user name, and saving the keyring in the ``/etc/ceph`` directory. For example, we recommend that the ``client.admin`` user use ``ceph.client.admin.keyring``. To create a keyring in ``/etc/ceph``, you must do so as ``root``. This means that the file will have ``rw`` permissions for the ``root`` user only, which is appropriate when the keyring contains administrator keys. However, if you intend to use the keyring for a particular user or group of users, be sure to use ``chown`` or ``chmod`` to establish appropriate keyring ownership and access. Adding a User to a Keyring -------------------------- When you :ref:`Add a user` to the Ceph Storage Cluster, you can use the `Getting a User`_ procedure to retrieve a user, key, and capabilities and then save the user to a keyring. If you want to use only one user per keyring, the `Getting a User`_ procedure with the ``-o`` option will save the output in the keyring file format. For example, to create a keyring for the ``client.admin`` user, run the following command: .. prompt:: bash $ sudo ceph auth get client.admin -o /etc/ceph/ceph.client.admin.keyring Notice that the file format in this command is the file format conventionally used when manipulating the keyrings of individual users. If you want to import users to a keyring, you can use ``ceph-authtool`` to specify the destination keyring and the source keyring. For example: .. prompt:: bash $ sudo ceph-authtool /etc/ceph/ceph.keyring --import-keyring /etc/ceph/ceph.client.admin.keyring Creating a User --------------- Ceph provides the `Adding a User`_ function to create a user directly in the Ceph Storage Cluster. However, you can also create a user, keys, and capabilities directly on a Ceph client keyring, and then import the user to the Ceph Storage Cluster. For example: .. prompt:: bash $ sudo ceph-authtool -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' /etc/ceph/ceph.keyring For additional details on capabilities, see `Authorization (Capabilities)`_. You can also create a keyring and add a new user to the keyring simultaneously. For example: .. prompt:: bash $ sudo ceph-authtool -C /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' --gen-key In the above examples, the new user ``client.ringo`` has been added only to the keyring. The new user has not been added to the Ceph Storage Cluster. To add the new user ``client.ringo`` to the Ceph Storage Cluster, run the following command: .. prompt:: bash $ sudo ceph auth add client.ringo -i /etc/ceph/ceph.keyring Modifying a User ---------------- To modify the capabilities of a user record in a keyring, specify the keyring and the user, followed by the capabilities. For example: .. prompt:: bash $ sudo ceph-authtool /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' To update the user in the Ceph Storage Cluster, you must update the user in the keyring to the user entry in the Ceph Storage Cluster. To do so, run the following command: .. prompt:: bash $ sudo ceph auth import -i /etc/ceph/ceph.keyring For details on updating a Ceph Storage Cluster user from a keyring, see `Importing a User`_ You may also :ref:`Modify user capabilities` directly in the cluster, store the results to a keyring file, and then import the keyring into your main ``ceph.keyring`` file. Command Line Usage ================== Ceph supports the following usage for user name and secret: ``--id`` | ``--user`` :Description: Ceph identifies users with a type and an ID: the form of this user identification is ``TYPE.ID``, and examples of the type and ID are ``client.admin`` and ``client.user1``. The ``id``, ``name`` and ``-n`` options allow you to specify the ID portion of the user name (for example, ``admin``, ``user1``, ``foo``). You can specify the user with the ``--id`` and omit the type. For example, to specify user ``client.foo``, run the following commands: .. prompt:: bash $ ceph --id foo --keyring /path/to/keyring health ceph --user foo --keyring /path/to/keyring health ``--name`` | ``-n`` :Description: Ceph identifies users with a type and an ID: the form of this user identification is ``TYPE.ID``, and examples of the type and ID are ``client.admin`` and ``client.user1``. The ``--name`` and ``-n`` options allow you to specify the fully qualified user name. You are required to specify the user type (typically ``client``) with the user ID. For example: .. prompt:: bash $ ceph --name client.foo --keyring /path/to/keyring health ceph -n client.foo --keyring /path/to/keyring health ``--keyring`` :Description: The path to the keyring that contains one or more user names and secrets. The ``--secret`` option provides the same functionality, but it does not work with Ceph RADOS Gateway, which uses ``--secret`` for another purpose. You may retrieve a keyring with ``ceph auth get-or-create`` and store it locally. This is a preferred approach, because you can switch user names without switching the keyring path. For example: .. prompt:: bash $ sudo rbd map --id foo --keyring /path/to/keyring mypool/myimage .. _pools: ../pools 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 that are run on their behalf. If your access control needs require that kind of authentication, you will need to have some other mechanism, which is likely to be specific to the front end that is used to access the Ceph object store. This other mechanism would ensure that only acceptable users and programs are able to run on the machine that Ceph permits to access its object store. The keys used to authenticate Ceph clients and servers are typically stored in a plain text file on a trusted host. Appropriate permissions must be set on the plain text file. .. 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. Anyone setting up Ceph systems should be aware of these shortcomings. In particular, 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 access to it could obtain a key that allows them to authenticate their own machines to Ceph. Instead of permitting potentially insecure machines to access a Ceph object store directly, you should require users 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 might address these particular authentication issues more fully. At present, none of the Ceph authentication protocols provide secrecy for messages in transit. As a result, an eavesdropper on the wire can hear and understand all data sent between clients and servers in Ceph, even if the eavesdropper cannot create or alter the data. Similarly, Ceph does not include options to encrypt user data in the object store. Users can, of course, hand-encrypt and store their own data in the Ceph object store, but Ceph itself provides no features to perform object encryption. Anyone storing sensitive data in Ceph should consider encrypting their data before providing it to the Ceph system. .. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication .. _Cephx Config Reference: ../../configuration/auth-config-ref