Skip to content

pkix command group

The pkix command group manages the global administrator PKIX validation profile in {{ product_name }}. It controls how administrator-facing X.509 certificates are validated: the trust source (trust anchors or a keystore), the revocation mode (OCSP/CRL), and the timing and freshness tolerances applied during path validation.

The pkix commands are remote gRPC calls. Before running any of them you must:

  1. Create a host profile with profile hosts create.
  2. Authenticate with profile authn login.

Use the global -p/--profile option (default default-admin) before the command path to pick a host profile for a single invocation. Shared flags are documented in Global options.

Replace self-signed certificates before enabling strict PKIX

Enable a strict trust source and revocation checking only when administrator certificates are issued by a CA whose CRL and/or OCSP endpoints are reachable from the runtime environment. Validate connectivity and freshness windows before tightening --pkix-revocation-mode or disabling --pkix-soft-fail.

Commands in this group

Command Purpose Anchor
pkix view Display the current administrator PKIX configuration #pkix-view
pkix update Partially update the administrator PKIX configuration #pkix-update
pkix backup Back up the configuration to a binary .pb file #pkix-backup
pkix restore Restore the configuration from a binary .pb backup #pkix-restore

Typical workflow

  1. Inspect the active profile with pkix view.
  2. Adjust trust material and revocation policy with pkix update (a read-modify-write partial merge).
  3. Capture the result with pkix backup for archival or promotion to another environment.
  4. Re-apply a saved configuration with pkix restore.

Group help

bin/admin.sh pkix --help

pkix view

Displays the global administrator PKIX configuration. The trust-store password is never returned; the reply reports only whether one is configured.

Syntax

bin/admin.sh pkix view [options]

Required options

This command has no command-specific required options.

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh pkix view -f json

pkix update

Updates the global administrator PKIX configuration. The command performs a partial merge: it first fetches the current configuration, applies only the options you supply on top of it, and sends the merged result back. Options you omit are left unchanged. Supplying --pkix-trust-anchor file(s) replaces the entire anchor set; supplying --pkix-trust-store-password replaces the stored password, while omitting it preserves the stored value.

Syntax

bin/admin.sh pkix update [options]

Required options

This command has no required options. Every PKIX field is optional so any subset can be updated in a single call.

Conditionally required options

Condition Required options
--pkix-trust-mode TRUST_MODE_ANCHORS At least one --pkix-trust-anchor (unless a usable anchor set already exists)
--pkix-trust-mode TRUST_MODE_KEYSTORE --pkix-trust-store-blob (or an existing --pkix-trust-store-path), --pkix-trust-store-type, and --pkix-trust-store-password

Optional options

Show optional options
Option Default Description
--pkix-name unchanged PKIX validation profile name
--pkix-trust-mode unchanged Trust source: TRUST_MODE_ANCHORS or TRUST_MODE_KEYSTORE
--pkix-trust-store-type unchanged Trust-store type: TRUST_STORE_TYPE_JKS or TRUST_STORE_TYPE_PKCS12
--pkix-revocation-mode unchanged Revocation mode: REVOCATION_MODE_NONE, REVOCATION_MODE_OCSP_ONLY, REVOCATION_MODE_CRL_ONLY, REVOCATION_MODE_PREFER_OCSP, or REVOCATION_MODE_PREFER_CRL
--[no-]pkix-soft-fail unchanged Treat revocation lookup failures as non-fatal
--[no-]pkix-only-end-entity unchanged Check revocation only for the end-entity certificate
--[no-]pkix-require-ocsp-nonce unchanged Require the OCSP nonce extension
--pkix-http-request-timeout-ms unchanged HTTP request timeout for CRL/OCSP fetches (ms)
--pkix-max-clock-skew-ms unchanged Maximum tolerated validation clock skew (ms)
--pkix-max-ocsp-age-ms unchanged Maximum OCSP response age (ms)
--pkix-max-crl-age-ms unchanged Maximum CRL age (ms)
--pkix-trust-store-path unchanged Trust-store filesystem path
--pkix-trust-store-password preserved when omitted Trust-store password (plaintext)
--pkix-trust-anchor unchanged Trust-anchor X.509 certificate file(s); repeatable, replaces the current anchor set
--pkix-trust-store-blob unchanged Trust-store keystore file
-f, --out-format YAML Output format: JSON or YAML

Validation rules

  • The update is a read-modify-write merge against the live configuration; omitted options keep their current values.
  • --pkix-trust-mode accepts only TRUST_MODE_ANCHORS or TRUST_MODE_KEYSTORE (case-insensitive).
  • --pkix-trust-store-type accepts only TRUST_STORE_TYPE_JKS or TRUST_STORE_TYPE_PKCS12 (case-insensitive).
  • --pkix-revocation-mode accepts only REVOCATION_MODE_NONE, REVOCATION_MODE_OCSP_ONLY, REVOCATION_MODE_CRL_ONLY, REVOCATION_MODE_PREFER_OCSP, or REVOCATION_MODE_PREFER_CRL (case-insensitive).
  • --pkix-trust-anchor is repeatable (arity = 1..*); when supplied it clears and re-populates the entire anchor set with the DER bytes of the given X.509 certificates.
  • --pkix-trust-store-password sets the plaintext credential when present; the backend preserves the stored password when it is omitted.
  • The boolean toggles --pkix-soft-fail, --pkix-only-end-entity, and --pkix-require-ocsp-nonce are negatable: use the --no- prefix (for example --no-pkix-soft-fail) to disable them.

Example (anchors trust mode, prefer OCSP)

bin/admin.sh pkix update \
  --pkix-name default-admin-pkix \
  --pkix-trust-mode TRUST_MODE_ANCHORS \
  --pkix-trust-anchor ./ca-root.crt ./ca-intermediate.crt \
  --pkix-revocation-mode REVOCATION_MODE_PREFER_OCSP \
  --no-pkix-soft-fail \
  --no-pkix-only-end-entity \
  --pkix-http-request-timeout-ms 5000 \
  --pkix-max-clock-skew-ms 300000 \
  --pkix-max-ocsp-age-ms 21600000 \
  --pkix-max-crl-age-ms 86400000 \
  -f json

Example (keystore trust mode)

bin/admin.sh pkix update \
  --pkix-trust-mode TRUST_MODE_KEYSTORE \
  --pkix-trust-store-blob ./admin-truststore.p12 \
  --pkix-trust-store-type TRUST_STORE_TYPE_PKCS12 \
  --pkix-trust-store-password <password> \
  --pkix-revocation-mode REVOCATION_MODE_CRL_ONLY \
  -f yaml

pkix backup

Backs up the administrator PKIX configuration to a binary protobuf (.pb) file. The backup never contains the trust-store password (it is redacted server-side); trust anchors and the trust-store blob are retained. When printed to screen, the binary payload is Base64-encoded so it can be captured from the console.

Syntax

bin/admin.sh pkix backup [options]

Required output mode options (choose exactly one)

Option Description Example
-o, --output-file Write the .pb backup to a file (creates or truncates) -o ./admin-pkix.pb
-s, --print-to-screen Print the Base64-encoded .pb payload to the console -s true

Validation rules

  • The output destination is an exclusive argument group with multiplicity 1: supply exactly one of -o/--output-file or -s/--print-to-screen.
  • The backup is a binary protobuf payload. File output writes raw bytes; screen output is Base64-encoded.

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format for any error reporting: JSON or YAML

Example

bin/admin.sh pkix backup -o ./admin-pkix.pb

pkix restore

Restores the administrator PKIX configuration from a binary protobuf (.pb) backup produced by pkix backup. The stored trust-store password is preserved unless the backup carries one.

Syntax

bin/admin.sh pkix restore [options]

Required options

Option Description Example
-i, --input-file Binary .pb PKIX backup file to restore -i ./admin-pkix.pb

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh pkix restore -i ./admin-pkix.pb -f json

Standard CLI options are documented in Global options.

FAQ

Do pkix commands need a login?

Yes. Every pkix command is a remote gRPC call. Create a host profile with profile hosts create, then authenticate with profile authn login before running pkix view, pkix update, pkix backup, or pkix restore.

Does pkix update replace the whole configuration?

No. pkix update performs a partial merge: it fetches the current configuration and applies only the options you supply. Omitted options keep their current values. Supplying --pkix-trust-anchor files is the exception — it replaces the entire trust-anchor set.

Is the trust-store password included in a backup?

No. The trust-store password is redacted server-side and never written to a pkix backup file. On pkix restore, the stored password is preserved unless the backup itself carries one.

What format does pkix backup produce?

A binary protobuf (.pb) payload. With -o/--output-file it writes raw bytes; with -s/--print-to-screen it prints the Base64-encoded payload to the console.