> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockops.network/llms.txt > Use this file to discover all available pages before exploring further. # Configuration reference > Every citadel-core configuration key, environment override, command-line flag and CLI command. citadel-core reads a YAML configuration file, accepts environment-variable overrides for connection details, and takes a small set of command-line flags at start-up. Secrets (the share-store password and identity password) are supplied through files or prompts, never through the configuration file in production. ## `config.yaml` ### Cluster | Key | Required | Description | | :-------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mpc_threshold` | yes | Signing threshold `t`. Must satisfy `t ≥ ⌊n/2⌋ + 1` for `n` nodes; `2` for a three-node cluster. | | `environment` | yes | `development` or `production`. In `production`, NATS connections require TLS client certificates and credentials. | | `chain_code` | yes | 32 bytes as 64 hexadecimal characters, generated once with `openssl rand -hex 32`. Used for hierarchical key derivation; **must be identical on every node**. The node refuses to start without it. | | `event_initiator_pubkey` | yes | Hex public key of the event initiator (citadel-api). Requests not signed by this key are rejected. | | `event_initiator_algorithm` | no | `ed25519` (default) or `p256`. | | `session_warm_up_delay_ms` | no | Delay before a signing session starts, to let peers settle. Production template sets `100`. | | `max_concurrent_keygen` | no | Key-generation sessions the node runs at once. Default `2`. | | `max_concurrent_signing` | no | Signing sessions the node runs at once. Default `10`. | ### Storage and backups | Key | Required | Description | | :---------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | `badger_password` | yes | Encryption password for the share store (AES-256). **Do not set this in the file in production**, use `--password-file` or `--prompt-credentials`. | | `db_path` | no | Directory holding the share store; the node's name is appended. Default `./db`. | | `backup_enabled` | no | Periodic encrypted backups of the share store. Default `true`. | | `backup_period_seconds` | no | Interval between backups. Default `300`. | | `backup_dir` | no | Where backups are written. Default `./backups`. Backups are encrypted with the share-store password. | ### Messaging and discovery | Key | Required | Description | | :---------------------------------------------------------------- | :--------- | :-------------------------------------------------------------------------------------------------- | | `nats.url` | yes | NATS server URL, `tls://…` in production. May be left empty and supplied as `NATS_URL`. | | `nats.username`, `nats.password` | production | NATS credentials. | | `nats.tls.client_cert`, `nats.tls.client_key`, `nats.tls.ca_cert` | production | Paths to the client certificate, key and CA. If omitted in production the node looks in `./certs/`. | | `consul.address` | yes | Consul address. May be left empty and supplied as `CONSUL_ADDRESS`. | | `consul.username`, `consul.password`, `consul.token` | no | Consul credentials or ACL token. | ### Health and authorisation | Key | Required | Description | | :---------------------------------------------------------------------- | :----------------- | :---------------------------------------------------------------------------------------------------------------------- | | `healthcheck.enabled` | no | Serve `GET /health`. Default `false`; enable for container platforms. | | `healthcheck.address` | no | Listen address. Default `0.0.0.0:8080`; use `0.0.0.0` (not `localhost`) inside containers. | | `authorization.enabled` | no | Require additional named authorizers to co-sign every keygen, signing and reshare request. | | `authorization.required_authorizers` | with authorization | Names of the authorizers whose signatures must be present. | | `authorization.authorizer_public_keys..public_key` / `.algorithm` | with authorization | Each authorizer's public key and algorithm (`ed25519` or `p256`). Generate with `citadel-core-cli generate-authorizer`. | ## Environment variables | Variable | Effect | | :----------------------- | :----------------------------------------------------------- | | `NATS_URL` | Overrides `nats.url`. | | `CONSUL_ADDRESS` | Overrides `consul.address`. | | `ENVIRONMENT` | Default for `citadel-core-cli register-peers --environment`. | | `CITADEL_CORE_NODE_NAME` | Used by the systemd unit to pass `--name`. | ## `citadel-core start` ```bash theme={null} citadel-core start --name [flags] ``` | Flag | Description | | :------------------------------- | :--------------------------------------------------------------------------- | | `--name`, `-n` | **Required.** The node's name as it appears in `peers.json`. | | `--config`, `-c` | Path to `config.yaml`. | | `--peers` | Path to `peers.json`; new entries are synced into Consul at start-up. | | `--password-file`, `-f` | File containing the share-store password. | | `--identity-password-file`, `-k` | File containing the password for the node's `age`-encrypted private key. | | `--decrypt-private-key`, `-d` | The node's private key is encrypted; decrypt it at start-up. | | `--prompt-credentials`, `-p` | Prompt for the share-store password interactively instead of reading a file. | | `--debug` | Debug logging. | `citadel-core version` prints the version. ## `citadel-core-cli` | Command | Purpose | | :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ | | `generate-peers -n [-o peers.json]` | Create the peer registry. | | `register-peers [-p peers.json] [-e ] --config ` | Write the registry into Consul. | | `generate-identity --node [-p peers.json] [-o identity] [--encrypt] [--overwrite]` | Create a node's Ed25519 identity, optionally with the private key encrypted by `age`. | | `generate-initiator [-n event_initiator] [-o .] [--encrypt] [-a ed25519\|p256]` | Create the event initiator's key pair. | | `generate-authorizer --name [-o .] [--encrypt] [-a ed25519\|p256]` | Create an authorizer key pair for the optional authorization layer. | | `recover --backup-dir --recovery-path [--force]` | Rebuild a share store from encrypted backups. | | `version` | Print the CLI version. | ## Files a node uses | File | Content | Sensitivity | | :------------------------------------------ | :-------------------------------------------- | :---------------------------- | | `peers.json` | Every node's name and ID. | Shared with all nodes. | | `identity/_identity.json` | A node's public key and metadata. | Shared with all nodes. | | `identity/_private.key` or `.key.age` | This node's private key (plain or encrypted). | **Secret: this node only.** | | `event_initiator.identity.json` | The initiator's public key. | Shared. | | `event_initiator.key.age` | The initiator's private key. | **Secret: citadel-api only.** | | `db//` | Encrypted share store. | **Secret.** | | `backups/*.enc` | Encrypted share-store backups. | **Secret.** |