Skip to content

Commit

Permalink
Merge pull request ceph#51154 from zdover23/wip-doc-2023-04-20-rados-…
Browse files Browse the repository at this point in the history 
…operations-3-of-x

doc/rados/ops: edit user-management.rst (3 of x)

Reviewed-by: Cole Mitchell <cole.mitchell@gmail.com>
  • Loading branch information
@zdover23 @yuvalif
zdover23 authored and yuvalif committed Apr 30, 2023
2 parents cd3c861 + b297870 commit 42dc543
Showing 1 changed file with 95 additions and 91 deletions.
186 changes: 95 additions & 91 deletions doc/rados/operations/user-management.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -464,6 +464,8 @@ To save the output of ``ceph auth get`` to a file, use the ``-o {filename}`` opt

The ``auth export`` command is identical to ``auth get``.

.. _rados_ops_adding_a_user:

Adding a User
-------------

Expand Down Expand Up @@ -598,38 +600,41 @@ 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 the following four keyring
names by default so you don't have to set them in your Ceph configuration file
unless you want to override the defaults (not recommended):
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 is your Ceph cluster name as defined by the
name of the Ceph configuration file (i.e., ``ceph.conf`` means the cluster name
is ``ceph``; thus, ``ceph.keyring``). The ``$name`` metavariable is the user
type and user ID (e.g., ``client.admin``; thus, ``ceph.client.admin.keyring``).
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 executing commands that read or write to ``/etc/ceph``, you may
need to use ``sudo`` to execute the command as ``root``.
.. 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 (e.g., ``client.ringo``), you must get the key and add
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. However, Ceph also provides the
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.

Create a Keyring
----------------
Creating a Keyring
------------------

When you use the procedures in the `Managing Users`_ section to create users,
you need to provide user keys to the Ceph client(s) so that the Ceph client
can retrieve the key for the specified user and authenticate with the Ceph
Storage Cluster. Ceph Clients access keyrings to lookup a user name and
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
Expand All @@ -640,65 +645,64 @@ empty keyring, use ``--create-keyring`` or ``-C``. For example:
ceph-authtool --create-keyring /path/to/keyring

When creating a keyring with multiple users, we recommend using the cluster name
(e.g., ``$cluster.keyring``) for the keyring filename and saving it in the
``/etc/ceph`` directory so that the ``keyring`` configuration default setting
will pick up the filename without requiring you to specify it in the local copy
of your Ceph configuration file. For example, create ``ceph.keyring`` by
executing the following:
(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 it in the ``/etc/ceph`` directory.
For example, ``ceph.client.admin.keyring`` for the ``client.admin`` user.
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
the file will have ``rw`` permissions for the ``root`` user only, which is
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, ensure
that you execute ``chown`` or ``chmod`` to establish appropriate keyring
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.

Add a User to a Keyring
-----------------------
Adding a User to a Keyring
--------------------------

When you add a user to the Ceph Storage Cluster, you can use the Get a
User procedure to retrieve a user, key and capabilities and save the user to a
keyring.
When you :ref:`Add a user<rados_ops_adding_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.

When you only want to use one user per keyring, the Get a User procedure with
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, execute the following:
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 we use the recommended file format for an individual user.
Notice that the file format in this command is the file format conventionally used when manipulating the keyrings of individual users.

When you want to import users to a keyring, you can use ``ceph-authtool``
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

Create a User
-------------
Creating a User
---------------

Ceph provides the Add 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. Then, you can import the user to the Ceph
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

See `Authorization (Capabilities)`_ for additional details on capabilities.
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:
Expand All @@ -707,36 +711,37 @@ For example:

sudo ceph-authtool -C /etc/ceph/ceph.keyring -n client.ringo --cap osd 'allow rwx' --cap mon 'allow rwx' --gen-key

In the foregoing scenarios, the new user ``client.ringo`` is only in the
keyring. To add the new user to the Ceph Storage Cluster, you must still add
the new user to the Ceph Storage Cluster:
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

Modify a User
-------------
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:
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 to the Ceph Storage Cluster, you must update the user
in the keyring to the user entry in the Ceph Storage Cluster:
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

See Import a User(s) for details on updating a Ceph Storage Cluster user
from a keyring.
For details on updating a Ceph Storage Cluster user from a
keyring, see `Importing a User`_

You may also Modify User Capabilities directly in the cluster, store the
results to a keyring file; then, import the keyring into your main
You may also :ref:`Modify user capabilities<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
Expand All @@ -746,12 +751,12 @@ Ceph supports the following usage for user name and secret:

``--id`` | ``--user``

:Description: Ceph identifies users with a type and an ID (e.g., ``TYPE.ID`` or
``client.admin``, ``client.user1``). The ``id``, ``name`` and
``-n`` options enable you to specify the ID portion of the user
name (e.g., ``admin``, ``user1``, ``foo``, etc.). You can specify
: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`` enter the following:
to specify user ``client.foo``, run the following commands:

.. prompt:: bash $

Expand All @@ -761,10 +766,10 @@ Ceph supports the following usage for user name and secret:

``--name`` | ``-n``

:Description: Ceph identifies users with a type and an ID (e.g., ``TYPE.ID`` or
``client.admin``, ``client.user1``). The ``--name`` and ``-n``
options enables you to specify the fully qualified user name.
You must specify the user type (typically ``client``) with the
: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 $
Expand All @@ -775,8 +780,8 @@ Ceph supports the following usage for user name and secret:

``--keyring``

:Description: The path to the keyring containing one or more user name and
secret. The ``--secret`` option provides the same functionality,
: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
Expand All @@ -793,43 +798,42 @@ Ceph supports the following usage for user name and secret:
Limitations
===========

The ``cephx`` protocol authenticates Ceph clients and servers to each other. It
The ``cephx`` protocol authenticates Ceph clients and servers to each other. It
is not intended to handle authentication of human users or application programs
run on their behalf. If that effect is required to handle your access control
needs, you must have another mechanism, which is likely to be specific to the
front end used to access the Ceph object store. This other mechanism has the
role of ensuring that only acceptable users and programs are able to run on the
machine that Ceph will permit to access its object store.
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 with appropriate permissions in a trusted host.
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. Those setting up Ceph systems should be aware of
uses in the background. Anyone setting up Ceph systems should be aware of
these shortcomings.

In particular, arbitrary user machines, especially portable machines, should not
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 surreptitious access to it could
obtain the key that will allow them to authenticate their own machines to Ceph.

Rather than permitting potentially insecure machines to access a Ceph object
store directly, users should be required to sign in to a trusted machine in
your environment using a method that provides sufficient security for your
purposes. That trusted machine will store the plaintext Ceph keys for the
human users. A future version of Ceph may address these particular
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 the moment, none of the Ceph authentication protocols provide secrecy for
messages in transit. Thus, an eavesdropper on the wire can hear and understand
all data sent between clients and servers in Ceph, even if it cannot create or
alter them. Further, Ceph does not include options to encrypt user data in the
object store. Users can hand-encrypt and store their own data in the Ceph
object store, of course, but Ceph provides no features to perform object
encryption itself. Those storing sensitive data in Ceph should consider
encrypting their data before providing it to the Ceph system.
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
Expand Down

0 comments on commit 42dc543

Please sign in to comment.