Guides
Configuration
Complete reference for ca.config.yml and environment variables.
Configuration
uPKI CA is configured via a ca.config.yml file that is created automatically on init. All values can be overridden via environment variables (useful for Docker / systemd deployments).
ca.config.yml
Default location: $UPKI_DATA_DIR/ca.config.yml (or ~/.upki/ca/ca.config.yml).
company: "Company Name"
domain: "example.com"
host: "127.0.0.1"
port: 5000
clients: "register"
password: null
seed: null
key_type: "rsa"
key_length: 4096
digest: "sha256"
crl_validity: 7
Reference
| Key | Type | Default | Description |
|---|---|---|---|
company | string | "Company Name" | Organisation name embedded in the CA certificate |
domain | string | "example.com" | Default domain fragment appended to CN if not fully qualified |
host | string | "127.0.0.1" | Bind address for ZMQ sockets |
port | integer | 5000 | CA operations socket. Registration socket uses port + 1 (5001) |
clients | string | "register" | Who can request certificates: all, register (registered nodes only), manual |
password | string/null | null | Password to encrypt the CA private key at rest (null = no encryption) |
seed | string/null | null | RA registration seed (auto-generated on first init if absent) |
key_type | string | "rsa" | Key algorithm: rsa or dsa |
key_length | integer | 4096 | Key size in bits |
digest | string | "sha256" | Signature hash algorithm: md5, sha1, sha256, sha512 |
crl_validity | integer | 7 | CRL validity period in days |
Environment variables
Environment variables take precedence over ca.config.yml. They are the recommended approach for Docker and systemd deployments.
| Variable | Equivalent config key | Description |
|---|---|---|
UPKI_DATA_DIR | --path CLI flag | Override the data directory path |
UPKI_CA_SEED | seed | RA registration seed |
UPKI_CA_HOST | host | Bind address for both ZMQ sockets |
UPKI_CA_KEY_FILE | — | Path to an existing CA private key to import on init |
UPKI_CA_CERT_FILE | — | Path to an existing CA certificate to import on init |
Importing an existing CA
If you have an existing CA key/certificate, pass them at init time:
upki-ca init \
--ca-key /path/to/existing-ca.key \
--ca-cert /path/to/existing-ca.crt
For a password-protected key:
upki-ca init \
--ca-key /path/to/existing-ca.key \
--ca-cert /path/to/existing-ca.crt \
--ca-password-file /run/secrets/ca_pass
Equivalently via environment variables:
UPKI_DATA_DIR=/opt/upki/ca \
UPKI_CA_KEY_FILE=/path/to/existing-ca.key \
UPKI_CA_CERT_FILE=/path/to/existing-ca.crt \
upki-ca start
Securing the seed
The seed is a shared secret. On Docker, use a secret or an encrypted .env file:
# Generate a strong seed
openssl rand -base64 48
# Pass it via Docker secret
docker secret create upki_ca_seed - <<< "your-generated-seed"
In Docker Compose:
services:
upki-ca:
environment:
UPKI_CA_SEED_FILE: /run/secrets/upki_ca_seed
secrets:
- upki_ca_seed
secrets:
upki_ca_seed:
external: true