-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat Ceph Storage
Chapter 8. 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):
-
/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
).
When executing commands that read or write to /etc/ceph
, you may need to use sudo
to execute the command as root
.
After you create a user (e.g., 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 ceph-authtool
utility to allow you to manage keyrings from a Ceph client.
8.1. Create 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 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:
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:
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.
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 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 ownership and access.
8.2. 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 keyring.
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:
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.
When you want to import users to a keyring, you can use ceph-authtool
to specify the destination keyring and the source keyring. For example:
sudo ceph-authtool /etc/ceph/ceph.keyring --import-keyring /etc/ceph/ceph.client.admin.keyring
8.3. Create 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 Storage Cluster. For example:
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.
You can also create a keyring and add a new user to the keyring simultaneously. 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. :
sudo ceph auth add client.ringo -i /etc/ceph/ceph.keyring
8.4. Modify 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:
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 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 from a keyring.
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.