Configuration reference

Prerequisites · Production deployment

Decentralization Manager has no configuration file. It reads every setting from an environment variable or from a command-line flag. This page lists every DECPM_* variable that the code reads, and the other variables that change its behavior.

How the node loads settings

The binary has one subcommand, serve. The -d or --dir flag goes before serve. All other flags go after it:

dec-party-manager -d ./node-1 serve --port 8081 --noise-port 9001

• A command-line flag overrides the environment variable with the same meaning.
• A variable in the process environment overrides the same variable in the .env file.
• The code default applies when no source sets a value.

The node loads <dir>/.env before it parses the flags. It takes <dir> from -d or --dir. Without that flag, it loads .env from the current working directory. DECPM_DIR does not change where the node looks for .env.

Boolean values are true or false. The node refuses to start when a flag value does not parse. This rule also applies to the variable of a flag. Variables marked env only have no flag. For those variables, the node uses the default when the value does not parse.

The Sensitive column marks a value that grants access or decrypts data. Keep a sensitive value in a secret store, not in an image, a repository or a shared .env file.

HTTP and authentication

Variable (flag)	Required or default	What it does	Sensitive
DECPM_HOST (--host)	Default 0.0.0.0	Sets the address that the HTTP listener and the metrics listener bind to.	No
DECPM_PORT (--port)	Default 8080	Sets the port of the HTTP listener. This listener serves the operator UI, the operator API, the tenant API and /healthz.	No
DECPM_ALLOWED_ORIGIN (--allowed-origin)	Default: same origin only	Adds one origin that CORS accepts, with credentials. Set it only when the UI loads from another host than the API.	No
DECPM_KEYCLOAK_URL (--keycloak-url)	Required for Keycloak	Sets the Keycloak URL that the browser logs in against. The node accepts tokens whose issuer is <URL>/realms/<realm>.	No
DECPM_KEYCLOAK_REALM (--keycloak-realm)	Required for Keycloak	Sets the Keycloak realm of the operator UI.	No
DECPM_KEYCLOAK_CLIENT_ID (--keycloak-client-id)	Required for Keycloak	Sets the public Keycloak client that the operator UI uses.	No
DECPM_KEYCLOAK_INTERNAL_URL (--keycloak-internal-url)	Default: the value of DECPM_KEYCLOAK_URL	Sets the Keycloak URL that the server uses for OIDC discovery, JWKS and introspection. Use it when the server cannot reach the browser-facing URL. The node ignores it, with a warning, when no other Keycloak variable is set.	No
DECPM_AUTH0_DOMAIN (--auth0-domain)	Required for Auth0	Sets the Auth0 tenant domain, without a scheme.	No
DECPM_AUTH0_CLIENT_ID (--auth0-client-id)	Required for Auth0	Sets the Auth0 single-page application client ID. The node creates the Auth0 configuration only when the domain and the client ID are both set.	No
DECPM_AUTH0_AUDIENCE (--auth0-audience)	Required for Auth0	Sets the Auth0 API identifier that the UI requests access tokens for. Without it, Auth0 issues tokens that the server cannot validate.	No
DECPM_AUTH0_SCOPE (--auth0-scope)	Optional	Adds space-separated scopes to the default openid profile email request. Use it when the admin role arrives as an Auth0 RBAC scope. The node ignores it, with a warning, without the Auth0 domain and client ID.	No
DECPM_JWT_ROLE_CLAIM (--jwt-role-claim)	Optional	Names a JWT claim that holds an array of role names. Use it for a namespaced custom claim. The node always reads roles, realm_access.roles and scope too. In Auth0 tokens, it also reads permissions.	No
DECPM_ADMIN_ROLE (--admin-role)	Recommended. Default: unset	Sets the role that admin-only endpoints require. When it is unset, every authenticated caller is an admin.	No
DECPM_TENANT_API_KEYS (--tenant-api-keys)	Required for the tenant API	Sets comma-separated bearer keys that wallet providers present to /v0/tenant/*. When it is unset, the tenant API rejects every call, except in insecure mode.	Yes

Set the variables of one identity provider only. When you set both providers, the operator UI uses Auth0. The --auth0-* flags exist. --help does not show them.

Insecure development mode

Variable (flag)	Required or default	What it does	Sensitive
DECPM_INSECURE (--insecure)	Default false	Turns off authentication. The API accepts any token, and the node signs an unsafe HS256 token for Canton. The node refuses to start in this mode unless DECPM_CANTON_NETWORK is devnet.	No
DECPM_CANTON_HMAC_SECRET (--canton-hmac-secret)	Default unsafe	Sets the secret of the HS256 token. It must match the unsafe auth secret of the Canton participant.	Yes
DECPM_CANTON_HMAC_AUDIENCE (--canton-hmac-audience)	Default https://canton.network.global	Sets the aud claim of the HS256 token. It must match the target audience of the participant.	No
DECPM_CANTON_HMAC_SUBJECT (--canton-hmac-subject)	Default ledger-api-user	Sets the sub claim of the HS256 token. This value is also the Ledger API user.	No

The node starts in insecure mode only on DevNet. When DECPM_CANTON_NETWORK is unset, the network defaults to devnet. The node reads the three DECPM_CANTON_HMAC_* values only in insecure mode. In insecure mode, the node also accepts tenant API calls without a key and serves Swagger UI at /swagger-ui/.

Storage

Variable (flag)	Required or default	What it does	Sensitive
DECPM_DIR (-d, --dir)	Default .	Sets the root directory of the node. The node writes its state to <dir>/data/. The flag goes before serve.	No
DECPM_DB_PATH (--db)	Default <dir>/data/decpm.db	Sets the path of the SQLite database. The Noise key stays under <dir>/data/.	No
DECPM_DB_ENCRYPTION_KEY (--db-encryption-key)	Recommended. Default: unset	Sets a passphrase for the stored party credentials. The node derives an AES-256-GCM key from it with SHA-256. When it is unset, the node stores client IDs, client secrets, user names and passwords in plaintext. A different passphrase makes the stored credentials unusable.	Yes

Noise and peers

Variable (flag)	Required or default	What it does	Sensitive
DECPM_LISTEN_ADDRESS (--listen-address)	Default 0.0.0.0	Sets the address that the Noise listener binds to.	No
DECPM_NOISE_PORT (--noise-port)	Default 9000	Sets the port of the Noise listener. Peers connect to it over raw TCP.	No
DECPM_PUBLIC_ADDRESS (--public-address)	Required when peers run on other hosts. Default: the listen address	Sets the host name or IP address that this node gives to peers.	No
DECPM_NOISE_RETRY_TIMEOUT_SEC (--noise-retry-timeout-sec)	Default 5	Sets the timeout of one attempt, in seconds, for the bounded retry around peer Noise calls.	No
DECPM_NOISE_RETRY_MAX_ATTEMPTS (--noise-retry-max-attempts)	Default 2	Sets the total number of attempts, including the first attempt. The value must be 1 or more.	No
DECPM_NOISE_RETRY_BACKOFF_MS (--noise-retry-backoff-ms)	Default 250	Sets the wait between two attempts, in milliseconds.	No
DECPM_PEER_WAIT_POLL_DELAY_MS (env only)	Default 2000	Sets how long a peer waits, in milliseconds, before it asks the coordinator again for the next command.	No
DECPM_ACS_BLOCK_BYTES (env only)	Default 4194304 (4 MiB)	Sets the size of each ACS block that this node serves as a coordinator. The node clamps the value to the range from 64 KiB to 8 MiB.	No
DECPM_ACS_BLOCK_FETCH_ATTEMPTS (env only)	Default 12	Sets the total number of attempts that a joining member makes to fetch one ACS block. After the last attempt, the transfer counts as broken. The value must be 1 or more.	No
DECPM_ACS_IMPORT_ATTEMPTS (env only)	Default 2	Sets the total number of ACS transfer attempts while the participant of a joining member is disconnected. Each new attempt restarts from the first block. The value must be 1 or more.	No

Legacy timeout variables

The node still parses these four variables. No code reads the parsed values. Setting them changes nothing.

Variable (flag)	Required or default	What it does	Sensitive
DECPM_TIMEOUT_HANDSHAKE (--timeout-handshake)	Default 30	No effect.	No
DECPM_TIMEOUT_MESSAGE (--timeout-message)	Default 120	No effect.	No
DECPM_TIMEOUT_RETRY_ATTEMPTS (--timeout-retry-attempts)	Default 3	No effect.	No
DECPM_TIMEOUT_RETRY_DELAY (--timeout-retry-delay)	Default 5	No effect.	No

Canton Admin API and Ledger API

Variable (flag)	Required or default	What it does	Sensitive
DECPM_CANTON_ADMIN_HOST (--canton-admin-host)	Default 127.0.0.1	Sets the host of the Canton Admin API.	No
DECPM_CANTON_ADMIN_PORT (--canton-admin-port)	Default 5002	Sets the port of the Canton Admin API.	No
DECPM_CANTON_LEDGER_HOST (--canton-ledger-host)	Default 127.0.0.1	Sets the host of the Canton Ledger API.	No
DECPM_CANTON_LEDGER_PORT (--canton-ledger-port)	Default 5001	Sets the port of the Canton Ledger API.	No
DECPM_CANTON_SYNCHRONIZER (--canton-synchronizer)	Default global	Sets the name of the Canton synchronizer.	No
DECPM_CANTON_NETWORK (--canton-network)	Set it explicitly. Default devnet	Selects devnet, testnet or mainnet. The value selects the public service URLs of that network. It also decides whether insecure mode can start.	No
DECPM_TOPOLOGY_RETRY_MAX_ATTEMPTS (env only)	Default 30	Sets how many times the node checks whether a topology change is effective.	No
DECPM_TOPOLOGY_RETRY_DELAY_SECS (env only)	Default 2	Sets the wait between two topology checks, in seconds.	No
DECPM_TOPOLOGY_PROPAGATION_DELAY_SECS (env only)	Default 30	Sets an extra wait, in seconds, after a topology change becomes effective. The wait lets the synchronizer propagate the change.	No

TLS and mTLS to Canton

Each Canton API has its own TLS settings. Both APIs default to plaintext. Plaintext suits a participant on a trusted private network.

Variable (flag)	Required or default	What it does	Sensitive
DECPM_CANTON_ADMIN_TLS (--canton-admin-tls)	Default false	Turns on TLS for the Admin API.	No
DECPM_CANTON_ADMIN_TLS_CA_CERT (--canton-admin-tls-ca-cert)	Default: the platform trust store	Sets the path to a PEM file with the CA that issued the Admin API certificate. Set it for a private CA.	No
DECPM_CANTON_ADMIN_TLS_CLIENT_CERT (--canton-admin-tls-client-cert)	Optional	Sets the path to a PEM client certificate for Admin API mTLS. Set it together with the client key.	No
DECPM_CANTON_ADMIN_TLS_CLIENT_KEY (--canton-admin-tls-client-key)	Optional	Sets the path to the PEM private key of the Admin API client certificate.	Yes, the file
DECPM_CANTON_ADMIN_TLS_DOMAIN (--canton-admin-tls-domain)	Default: the configured host	Sets the name to check the Admin API certificate against, when it differs from the host.	No
DECPM_CANTON_LEDGER_TLS (--canton-ledger-tls)	Default false	Turns on TLS for the Ledger API.	No
DECPM_CANTON_LEDGER_TLS_CA_CERT (--canton-ledger-tls-ca-cert)	Default: the platform trust store	Sets the path to a PEM file with the CA that issued the Ledger API certificate.	No
DECPM_CANTON_LEDGER_TLS_CLIENT_CERT (--canton-ledger-tls-client-cert)	Optional	Sets the path to a PEM client certificate for Ledger API mTLS. Set it together with the client key.	No
DECPM_CANTON_LEDGER_TLS_CLIENT_KEY (--canton-ledger-tls-client-key)	Optional	Sets the path to the PEM private key of the Ledger API client certificate.	Yes, the file
DECPM_CANTON_LEDGER_TLS_DOMAIN (--canton-ledger-tls-domain)	Default: the configured host	Sets the name to check the Ledger API certificate against, when it differs from the host.	No

A client certificate without its key, or a key without its certificate, fails the connection with a half-configured error. A plaintext client against a TLS endpoint fails every call with transport error or BrokenPipe. The connect error names the variable to change.

Signing and AWS KMS

The node reads no DECPM_* variable for signing. It selects the signing backend from the key metadata on the participant. For a key in AWS KMS, it uses the default credential chain and region chain of the AWS SDK.

Variable	Required or default	What it does	Sensitive
AWS_REGION	Required when the chain resolves no region	Sets the AWS region of the KMS keys.	No
Other AWS SDK variables, for example AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE	One credential source is required on an AWS KMS participant	Supply the credentials for the KMS Sign call. On Amazon EKS, an IAM role for the service account sets the web identity variables.	Yes

Sign with AWS KMS gives the IAM setup.

Rewards

Variable (flag)	Required or default	What it does	Sensitive
DECPM_REWARD_AUTOMATION_INTERVAL_SECS (--reward-automation-interval-secs)	Default 300	Sets the seconds between two reward-assignment sweeps for each Decentralized Party. A delegation contract on the ledger turns the automation on. This value sets only the cadence. The node uses 1 second for 0.	No
DECPM_REWARD_EXPIRY_READ_INTERVAL_SECS (--reward-expiry-read-interval-secs)	Default 3600	Sets the seconds between extra reads of the coupon backlog when no sweep is due. These reads refresh the decman_reward_oldest_unassigned_expires_in_seconds gauge.	No
DECPM_REWARD_MAX_CREATES (--reward-max-creates)	Default 100	Sets the maximum number of output contracts in one Delegation_Assign transaction. The node divides it by the number of beneficiaries to get the coupons for each transaction. Lower it when assignments start to fail.	No
DECPM_REWARD_MIN_EXPIRY_MARGIN_SECS (--reward-min-expiry-margin-secs)	Default 120	Sets the minimum time, in seconds, that a coupon must have left before its expiry. The node does not assign a coupon with less time.	No

Reward automation explains the delegation.

Metrics and logging

Variable (flag)	Required or default	What it does	Sensitive
DECPM_METRICS_PORT (--metrics-port)	Default 9464	Sets the port of the Prometheus metrics listener at /metrics. 0 turns off the listener. The listener has no authentication.	No
DECPM_LOG_FORMAT (env only)	Default: JSON	text selects the console format. Any other value selects one JSON object per line.	No
RUST_LOG (env only)	Default dec_party_manager=info,tokio_noise=error,hyper_noise=error	Sets the log filter, in tracing EnvFilter syntax.	No

The metrics listener has no authentication and binds to DECPM_HOST. The metrics listener must use a port that differs from DECPM_PORT and DECPM_NOISE_PORT. When the port is in use, the node logs an error and runs without metrics. Monitoring and logging lists the metrics.

Other

Variable (flag)	Required or default	What it does	Sensitive
DECPM_EXTERNAL_PARTIES_TTL_SECS (--external-parties-ttl-secs)	Default 300	Sets how long, in seconds, the External Parties list serves one topology snapshot. After that time, the next request starts a new topology scan. A scan reads the whole topology store, so keep the value in minutes.	No
DECPM_BUILD_VERSION (env only)	Set by the release image	Sets the build version that the UI shows. Without it, the UI shows <crate version>-dev.	No
DECPM_BUILD_TIME (env only)	Set by the release image	Sets the build time that the UI shows.	No

Test builds with the test-mode feature also read DECPM_TEST_REWARD_ASSIGN_FAILURE_FILE. The release binary does not contain that code. The integration tests read DECPM_IT_* variables, DECPM_KEYCLOAK_USERNAME and DECPM_KEYCLOAK_PASSWORD. The node does not read them.

Technical sources

• Command-line flags
• Startup, .env loading and logging
• Configuration defaults and Canton TLS
• Topology, ACS and polling settings
• ACS block size
• Database encryption
• Server startup and listeners
• Authentication middleware
• AWS KMS signer
• Build information
• Repository README
• Deployment guide

Related pages

• Prerequisites
• Production deployment
• Authentication and operator roles
• Monitoring and logging