ceph-authtool

ceph-authtool is a utility used to manage Ceph authentication keys and credentials. This tool helps create, view, and modify Ceph authentication keys, which are essential for managing access control in a Ceph cluster. Ceph uses a Public Key Infrastructure (PKI)-like system to authenticate various entities such as monitors, OSDs, and clients.

Common ceph-authtool Commands and Subcommands

1. Create a New Keyring

Creates a new Ceph keyring file.

ceph-authtool --create-keyring <keyring-file>

• Example:

  ceph-authtool --create-keyring /etc/ceph/ceph.client.admin.keyring

This command creates a new keyring file called ceph.client.admin.keyring that will be used for storing the admin key for Ceph.

2. Generate a New Key

Generates a new key and adds it to a keyring.

ceph-authtool <keyring-file> --gen-key --name <entity>

• Example:

  ceph-authtool /etc/ceph/ceph.client.admin.keyring --gen-key --name client.admin

This command generates a new authentication key for the entity client.admin and stores it in the specified keyring file.

3. Import Keys

Imports a key from one keyring to another keyring.

ceph-authtool <keyring-file> --import-keyring <source-keyring>

• Example:

  ceph-authtool /etc/ceph/ceph.client.admin.keyring --import-keyring /tmp/temp-keyring

This command imports the keys from temp-keyring into the admin keyring.

4. View a Keyring

Prints the details of a keyring, including the entities and their keys.

ceph-authtool <keyring-file> --print-key

• Example:

  ceph-authtool /etc/ceph/ceph.client.admin.keyring --print-key

This command prints out the content of the keyring, including the key for the client.admin.

5. Add a New Key to Keyring

Adds an existing key for a specific entity to the keyring.

ceph-authtool <keyring-file> --add-key <key> --name <entity>

• Example:

  ceph-authtool /etc/ceph/ceph.client.admin.keyring --add-key AQABCF....== --name client.admin

This adds the provided authentication key (AQABCF...==) for client.admin into the specified keyring.

6. Remove a Key from a Keyring

Removes a specific entity's key from a keyring.

ceph-authtool <keyring-file> --delete <entity>

• Example:

  ceph-authtool /etc/ceph/ceph.client.admin.keyring --delete client.admin

This removes the client.admin entity from the specified keyring.

7. Change the Permissions of a Key

Sets or modifies the capabilities of an entity in the keyring.

ceph-authtool <keyring-file> --cap <entity> <caps>

• Example:

  ceph-authtool /etc/ceph/ceph.client.admin.keyring --cap client.admin mon 'allow *' osd 'allow *'

This command sets the capabilities of client.admin to have full access to both monitors and OSDs.

8. Extract a Key to a File

Extracts the key for a specific entity and saves it to a file.

ceph-authtool <keyring-file> --print-key --name <entity> --out-file <output-file>

• Example:

  ceph-authtool /etc/ceph/ceph.client.admin.keyring --print-key --name client.admin --out-file /tmp/client.admin.key

This extracts the key for client.admin and saves it to the file /tmp/client.admin.key.

9. Convert Keyring Format

Converts a keyring from one format to another.

ceph-authtool <keyring-file> --convert-keyring <new-format>

• Example:

  ceph-authtool /etc/ceph/ceph.client.admin.keyring --convert-keyring base64

This converts the keyring to a base64-encoded format.

Typical Use Cases:

• Creating and Managing Client Authentication: To manage client authentication in a Ceph cluster, ceph-authtool is used to create, add, and modify the keys stored in keyrings, ensuring secure access to cluster resources.

• Cluster Authentication: Ceph components (e.g., monitors, OSDs) require keyrings to authenticate with each other. Using ceph-authtool, you can generate and manage these keys effectively.

• Backup of Keyrings: Administrators can use ceph-authtool to print keys and store them in separate files for backup or migration purposes.

Conclusion

ceph-authtool is an essential command-line tool for managing Ceph authentication keys. It allows administrators to create, modify, and manage keyrings for various entities like clients, OSDs, and monitors, ensuring secure and proper access control within the Ceph cluster.