ceph-authtool is a command-line utility for managing Ceph keyring files. It allows you to create, view, and modify authentication credentials for Ceph clients and monitors. This is essential for securing cluster access and configuring services like RADOS gateways or CephFS.

Key Functions

• Create new keyring files with specified keys
• View existing keyring contents
• Modify existing keys or add new ones
• Generate client or monitor keys with specific permissions

Practical Usage Steps

1. Create a new client keyring

Generate a new keyring file for a client (e.g., client.admin):

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

2. Add a key to the keyring

Add a key to the newly created keyring (replace your-secret-key with your actual key):

ceph-authtool --add-key /etc/ceph/ceph.client.admin.keyring --name client.admin --secret your-secret-key

3. Verify the keyring contents

Check the contents of the keyring to confirm the key was added:

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

4. Modify an existing key

Update an existing key in the keyring (replace new-secret-key with your new key):

ceph-authtool --modify-key /etc/ceph/ceph.client.admin.keyring --name client.admin --secret new-secret-key

5. Create a monitor keyring

Generate a keyring specifically for a monitor (e.g., mon.host):

ceph-authtool --create-keyring /etc/ceph/ceph.mon.host.keyring --gen-key

6. Add a monitor key

Add a key to the monitor keyring (replace mon-secret with your monitor key):

ceph-authtool --add-key /etc/ceph/ceph.mon.host.keyring --name mon.host --secret mon-secret

Important Notes

• Always store keyring files securely (typically in /etc/ceph/)
• Use --gen-key to generate random keys automatically
• The --name parameter must match the client/monitor name used in Ceph configuration
• Keyring files must be owned by root and have restrictive permissions (e.g., chmod 600)
• For monitor keys, ensure the key name matches the monitor's hostname in the cluster

Common Use Cases

• Configuring Ceph clients for RADOS Gateway (S3 API)
• Setting up CephFS clients
• Creating monitor authentication for cluster management
• Troubleshooting authentication issues in Ceph clusters

Verification

After modifying keyrings, verify the configuration by checking Ceph status:

ceph -s

ceph-authtool

ceph-authtool is a command‑line utility for managing Ceph keyring files. It lets you create, view, add, modify and delete keys used for authentication with Ceph clients and monitors. The keyring files are typically stored in /etc/ceph/ and must be protected with strict permissions.

Creating a new keyring

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

Creates an empty keyring file and generates a random secret key.

Adding a key to a keyring

ceph-authtool --add-key /etc/ceph/ceph.client.admin.keyring --name client.admin --secret your-secret-key

Adds a key for the client named client.admin. Replace your-secret-key with the actual secret.

Viewing a keyring

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

Displays the contents of the keyring, showing all stored keys and their associated names.

Modifying an existing key

ceph-authtool --modify-key /etc/ceph/ceph.client.admin.keyring --name client.admin --secret new-secret-key

Updates the secret for the specified client name.

Creating a monitor keyring

ceph-authtool --create-keyring /etc/ceph/ceph.mon.host.keyring --gen-key

Generates a dedicated keyring for a monitor; the filename should reflect the monitor’s hostname.

Adding a monitor key

ceph-authtool --add-key /etc/ceph/ceph.mon.host.keyring --name mon.host --secret mon-secret

Adds a key for the monitor named mon.host. Ensure the key name matches the monitor’s hostname in the cluster configuration.

Important considerations

• Store keyring files in a secure location (commonly /etc/ceph/) and set restrictive permissions (chmod 600).
• Use --gen-key to let the tool generate a random secret automatically.
• The --name argument must correspond to the client or monitor identifier used elsewhere in the Ceph configuration.
• After any changes, verify the setup with ceph -s to confirm the cluster recognises the updated authentication.