Skip to content

Setting up Couriers

This page covers configuring a registered Courier to download secrets and scheduling it to run automatically.

Prerequisites

  • A Courier registered in the platform (see CLM Couriers — Setting Up)
  • The Courier granted read access to the target Locker (see Courier Access)
  • The Locker UUID (visible on the Locker detail page in the portal)
  • The Zaita Courier binary installed on the target system

Configuration

Secrets download is configured in the Courier's YAML configuration file under a secrets block. Multiple secrets blocks can be defined to download multiple Lockers in a single run.

secrets:
  locker_uuid: "550e8400-e29b-41d4-a716-446655440000"
  output_file: /etc/myapp/secrets.env
  output_format: env_file
  on_success: "systemctl reload myapp"
  on_failure: "systemctl stop myapp"

Configuration Reference

Field Required Description
locker_uuid Yes The UUID of the Locker to download. Found on the Locker detail page
output_file Yes Absolute path where the secrets file will be written
output_format Yes Format of the output file: env_file or json
on_success No Shell command to run after a successful write
on_failure No Shell command to run if the download or write fails

Running the Courier

To download secrets, run the download-secrets command:

zaita-courier download-secrets -c /etc/zaita/courier.yaml

Exit codes:

Code Meaning
0 Success — secrets written to the output file
1 Failure — authentication error, API error, decryption error, or file write error

Stdout on success:

{
  "success": true,
  "locker_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "locker_name": "production-api-keys",
  "secret_count": 3,
  "output_file": "/etc/myapp/secrets.env"
}

Hooks

The optional on_success and on_failure fields accept any shell command. Common uses:

  • Reload a service after secrets are updated — systemctl reload myapp
  • Stop a service if secrets delivery fails — systemctl stop myapp
  • Send an alert on failure — curl -s -X POST https://alerting.example.com/...
  • Trigger a deployment after secret rotation

The hook exit code is logged but does not affect the Courier's own exit code.

Scheduling with Cron

Couriers are not persistent agents — they are designed to be scheduled. To refresh secrets automatically, add the Courier to a crontab:

# Download secrets every 15 minutes
*/15 * * * * /usr/local/bin/zaita-courier download-secrets -c /etc/zaita/courier.yaml

Adjust the schedule to match your secret rotation frequency. If secrets are rotated infrequently, a daily run is typically sufficient. For security-sensitive environments or secrets that may rotate at any time, every 15 minutes is a reasonable default.

Audit Events

Every download attempt is recorded in the platform's audit log:

Event Description
courier.download_locker.success Courier successfully downloaded and received the Locker
courier.download_locker.failed The BCP call failed (decryption or key error)
courier.download_locker.unauthorised The Courier does not have access to the requested Locker

Audit logs are viewable under Admin → Audit Log.

Next Steps