Skip to main content

​
Overview

This guide covers platform-level Key Manager issues that require administrator access. For user-facing issues such as 403 errors or expired secrets, see the Key Manager Troubleshooting guide.
Administrator Access Required — This operation requires the admin role. Contact your Xloud administrator if you do not have sufficient permissions.

​
Diagnostic Checklist

Check Key Manager container status
docker ps --filter name=barbican
Verify Key Manager API is responding
openstack secret list --limit 1
Check Key Manager API logs
docker logs barbican-api --tail 100

​
Platform Issues

Secret retrieval returns 500 Internal Server Error

Cause: The secret store backend is unavailable — HSM connectivity lost, KMIP server unreachable, or master key file inaccessible.Diagnosis:
Check Key Manager worker logs for backend errors
docker logs barbican-worker --tail 100 | grep -i "error\|backend\|connect"
Resolution by backend type:
BackendCheckResolution
simple_cryptoMaster key file readablels -la /etc/xavs/key-manager/kek.conf
pkcs11HSM online and partition accessibleVerify HSM dashboard status
kmipNetwork to KMIP server on port 5696nc -zv <kmip-host> 5696
Cause: The CA plugin is unreachable or misconfigured.Diagnosis:
Check order status and error detail
openstack secret order show <order-href>
Review the error_status_code and error_reason fields. Common causes:
  • CA plugin service is not running — check container status via XDeploy
  • Certificate subject DN contains invalid characters or fields rejected by the CA
  • CA connectivity timeout — verify network access from Key Manager to the CA endpoint
Check CA plugin container
docker ps --filter name=barbican
docker logs barbican-worker --tail 50 | grep -i "ca\|order\|cert"
Cause: ACL changes require a short propagation delay, or the caller is authenticated under a different user identity than expected.Diagnosis:
Verify ACL on the secret
openstack acl get <secret-href>
Confirm the user ID in the ACL matches the authenticated user’s actual ID:
Get current user ID
openstack token issue -c user_id -f value
Resolution: If the user ID does not match, ensure the correct user identity is being used in the API call. ACL entries reference user IDs, not usernames — a renamed user retains the same ID.
Cause: Database connectivity failure, missing master key file, or configuration error preventing service initialization.Diagnosis:
Check startup logs
docker logs barbican-api --tail 200 | grep -i "error\|critical\|warn"
Common startup failures:
ErrorCauseResolution
database not reachableDB host unreachableCheck DB container status
No such file: kek.confMaster key file missingRestore from backup or re-generate
PKCS11 library not foundHSM library missingVerify library path in config
KMIP connection refusedKMIP server downCheck KMIP server connectivity
Cause: The secret store backend is under load or the encryption operation is slow (common with PKCS#11 HSM under high request rates).Resolution:
  • Check HSM health and current load from the HSM management interface
  • Consider scaling Key Manager worker replicas via XDeploy to parallelize requests
  • For KMIP backends, verify network latency to the KMIP server
  • Review Key Manager worker logs for timeout or retry events

​
Log Locations

ComponentLog Command
Key Manager APIdocker logs barbican-api
Key Manager Workerdocker logs barbican-worker
Key Manager Keystone Listenerdocker logs barbican-keystone-listener

​
Next Steps

Key Manager Troubleshooting (User)

User-facing Key Manager issues — 403 errors, expired secrets, ACL problems

Backend Configuration

Verify and update secret store backend configuration

Architecture

Understand component roles to narrow down failure scope

Security

Security hardening to prevent recurrence