From e3575bb72f307a27d49fedf3692ca661e3d613a5 Mon Sep 17 00:00:00 2001
From: Zac Dover <zac.dover@proton.me>
Date: Tue, 18 Apr 2023 22:59:09 +0200
Subject: [PATCH] doc/rados: edit user-management (2 of x)
Line-edit doc/rados/user-management.rst (2 of x). Some internal
references had to be removed, but these will be repaired when the next
part of this file is updated in a future PR.
Co-authored-by: Anthony D'Atri <anthony.datri@gmail.com>
Signed-off-by: Zac Dover <zac.dover@proton.me>
---
doc/rados/operations/user-management.rst | 239 ++++++++++++-----------
1 file changed, 122 insertions(+), 117 deletions(-)
diff --git a/doc/rados/operations/user-management.rst b/doc/rados/operations/user-management.rst
index d03c33376cd..4220ff11ba2 100644
--- a/doc/rados/operations/user-management.rst
+++ b/doc/rados/operations/user-management.rst
@@ -337,45 +337,53 @@ 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 backend 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 users such as ``client.glance``, ``client.cinder``,
-etc.
+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. ``all`` is a synonym for ``*``.
+``value`` argument, or both. The ``all`` tag is a synonym for ``*``.
Namespace
---------
-Objects within a pool can be associated to a namespace--a logical group of
+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 such that reads and writes by the user take place only within the
-namespace. Objects written to a namespace within the pool can only be accessed
+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`` where the logical grouping can alleviate the need to create
- different pools. Ceph Object Gateway (in releases beginning with
- Luminous) uses namespaces for various
- metadata objects.
+ ``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 that pools can be a computationally expensive
-method of segregating data sets for the purposes of authorizing separate sets
-of users. For example, a pool should have ~100 placement groups per OSD. So an
-exemplary cluster with 1000 OSDs would have 100,000 placement groups for one
-pool. Each pool would create another 100,000 placement groups in the exemplary
-cluster. By contrast, writing an object to a namespace simply associates the
-namespace to the object name with out the computational overhead of a separate
-pool. Rather than creating a separate pool for a user or set of users, you may
-use a namespace. **Note:** Only available using ``librados`` at this time.
+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.
-Access may be restricted to specific RADOS namespaces using the ``namespace``
-capability. Limited globbing of namespaces is supported; if the last character
+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.
@@ -383,64 +391,60 @@ Managing Users
==============
User management functionality provides Ceph Storage Cluster administrators with
-the ability to create, update and delete users directly in the Ceph Storage
+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 may need to
-distribute keys to clients so that they can be added to keyrings. See `Keyring
-Management`_ for details.
+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`_.
-List Users
-----------
+Listing Users
+-------------
-To list the users in your cluster, execute the following:
+To list the users in your cluster, run the following command:
.. prompt:: bash $
- ceph auth ls
+ ceph auth ls
-Ceph will list out all users in your cluster. For example, in a two-node
-exemplary cluster, ``ceph auth ls`` will output something that looks like
-this::
+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:
+ 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
+ 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 the ``TYPE.ID`` notation for users applies such that ``osd.0`` is a
-user of type ``osd`` and its ID is ``0``, ``client.admin`` is a user of type
-``client`` and its ID is ``admin`` (i.e., the default ``client.admin`` user).
-Note also that each entry has a ``key: <value>`` entry, and one or more
+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: <value>`` entry, and also has one or more
``caps:`` entries.
-You may use the ``-o {filename}`` option with ``ceph auth ls`` to
-save the output to a file.
+To save the output of ``ceph auth ls`` to a file, use the ``-o {filename}`` option.
-Get a User
-----------
+Getting a User
+--------------
-To retrieve a specific user, key and capabilities, execute the
-following:
+To retrieve a specific user, key, and capabilities, run the following command:
.. prompt:: bash $
@@ -452,8 +456,7 @@ For example:
ceph auth get client.admin
-You may also use the ``-o {filename}`` option with ``ceph auth get`` to
-save the output to a file. Developers may also execute the following:
+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 $
@@ -461,42 +464,47 @@ save the output to a file. Developers may also execute the following:
The ``auth export`` command is identical to ``auth get``.
-Add a User
-----------
+Adding a User
+-------------
-Adding a user creates a username (i.e., ``TYPE.ID``), a secret key and
-any capabilities included in the command you use to create the 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 enables the user to authenticate with the Ceph Storage Cluster.
+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``).
+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.
+ 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. You may use the
- ``-o {filename}`` option to save the output to a file.
+ 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 (only). This is useful for clients that
- need the key only (e.g., libvirt). If the user already exists, this command
- simply returns the key. You may use the ``-o {filename}`` option to save the
- output to a file.
+ 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.
-When creating client users, you may create a user with no capabilities. A user
+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 can create a
-user with no capabilities if you wish to defer adding capabilities later using
-the ``ceph auth caps`` command.
+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 capability on Ceph OSDs. Additionally, a user's OSD permissions
-are often restricted to accessing a particular pool:
+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 $
@@ -505,21 +513,19 @@ are often restricted to accessing a particular pool:
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:: If you provide a user with capabilities to OSDs, but you DO NOT
- restrict access to particular pools, the user will have access to ALL
- pools in the cluster!
+.. 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:
-Modify User Capabilities
-------------------------
+Modifying User Capabilities
+---------------------------
-The ``ceph auth caps`` command allows you to specify a user and change the
+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, you should also specify the existing capabilities when using the form:
+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 $
@@ -534,10 +540,10 @@ For example:
ceph auth caps client.paul mon 'allow rw' osd 'allow rwx pool=liverpool'
ceph auth caps client.brian-manager mon 'allow *' osd 'allow *'
-See `Authorization (Capabilities)`_ for additional details on capabilities.
+For additional details on capabilities, see `Authorization (Capabilities)`_.
-Delete a User
--------------
+Deleting a User
+---------------
To delete a user, use ``ceph auth del``:
@@ -545,34 +551,34 @@ To delete a user, use ``ceph auth del``:
ceph auth del {TYPE}.{ID}
-Where ``{TYPE}`` is one of ``client``, ``osd``, ``mon``, or ``mds``,
-and ``{ID}`` is the user name or ID of the daemon.
+Here ``{TYPE}`` is either ``client``, ``osd``, ``mon``, or ``mds``,
+and ``{ID}`` is the user name or the ID of the daemon.
-Print a User's Key
-------------------
+Printing a User's Key
+---------------------
-To print a user's authentication key to standard output, execute the following:
+To print a user's authentication key to standard output, run the following command:
.. prompt:: bash $
ceph auth print-key {TYPE}.{ID}
-Where ``{TYPE}`` is one of ``client``, ``osd``, ``mon``, or ``mds``,
-and ``{ID}`` is the user name or ID of the daemon.
+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 is useful when you need to populate client
-software with a user's key (e.g., libvirt):
+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`
-Import a User(s)
+Importing a User
----------------
To import one or more users, use ``ceph auth import`` and
-specify a keyring:
+specify a keyring as follows:
.. prompt:: bash $
@@ -584,9 +590,8 @@ For example:
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
+.. 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
@@ -659,11 +664,11 @@ ownership and access.
Add 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
+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 only want to use one user per keyring, the `Get a User`_ procedure with
+When you only want to use one user per keyring, the Get 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:
@@ -684,7 +689,7 @@ For example:
Create a User
-------------
-Ceph provides the `Add a User`_ function to create a user directly in the Ceph
+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
Storage Cluster. For example:
@@ -727,10 +732,10 @@ in the keyring to the user entry in the Ceph Storage Cluster:
sudo ceph auth import -i /etc/ceph/ceph.keyring
-See `Import a User(s)`_ for details on updating a Ceph Storage Cluster user
+See Import a User(s) for details on updating a Ceph Storage Cluster user
from a keyring.
-You may also `Modify User Capabilities`_ directly in the cluster, store the
+You may also Modify User Capabilities directly in the cluster, store the
results to a keyring file; then, import the keyring into your main
``ceph.keyring`` file.