RepoMirrors/ceph
1
0
Fork 0
mirror of https://github.com/ceph/ceph synced 2025-02-24 19:47:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc/rados: edit user-management (2 of x)

Browse Source 
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>
This commit is contained in:
Zac Dover 2023-04-18 22:59:09 +02:00
parent 195262cf6b
commit e3575bb72f
1 changed files with 122 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

239
doc/rados/operations/user-management.rst
View File

@ -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.