Global Configuration · Stellar Control

Every service of the core, the CLI, the language server and the editor read one global YAML file at start. It describes the deployment (where NATS is, which port the API listens on, how long a leadership lease lasts), not the mission: catalogues, topology and procedures live in the configuration repository.

Every key has a default. An empty file, or no file at all, gives the defaults; a file lists only what it changes. config/stellar.example.yaml in the repository of Stellar Control lists every key with its default and a comment.

Finding the file#

Source	Used by
`--config <path>`	Every service binary, `stellar-mcs`, and the `stellar check`, `lock`, `compile` and `run --dry` commands
`STELLAR_CONFIG`	The same, when `--config` is not given; also `stellar-lsp` and the VS Code extension (`stellar.config`)
Nothing	Built-in defaults

A service logs its effective configuration (after overrides) as YAML at start, in the effective configuration log line.

Environment overrides#

Any value can be overridden by an environment variable named STELLAR__<SECTION>__<KEY>: two underscores between levels, upper or lower case. The value is parsed as YAML, so numbers, booleans, lists and maps work:

Shell

STELLAR__NATS__URL=tls://nats.lab:4222
STELLAR__RECONCILER__LEADER_TTL=10s
STELLAR__OBSERVABILITY__METRICS_ADDR=0.0.0.0:9101
STELLAR__EXECUTOR__DEFAULT_RETRY='{times: 2, every: 5s}'
STELLAR__PASSES__FEEDERS='{fds-feeder: fds}'
STELLAR__EDITOR__FORGE__KIND=gitlab

Overrides apply on top of the file, then the whole configuration is validated. A typical use is giving each instance on a host its own metrics port.

Value syntax#

Kind	Syntax	Examples
Duration	A number followed by `d`, `h`, `min`, `s`, `ms`, `us` or `ns`, with or without a space	`5s`, `3 min`, `30d`, `250ms`
Size	A number followed by `B`, `KB`, `MB`, `GB`, `TB` (powers of 1000) or `KiB`, `MiB`, `GiB`, `TiB` (powers of 1024), or a plain number of bytes	`2TB`, `500 MB`, `1 GiB`
Address	`host:port`	`0.0.0.0:8080`, `127.0.0.1:9100`

Sections#

`time`#

Key	Type	Default	Meaning
`scale`	`utc`, `tai` or `gps`	`utc`	Time scale of the whole chain. Drivers convert on-board time into it. See Time and Freshness.

`nats`#

Key	Type	Default	Meaning
`url`	URL	`nats://localhost:4222`	NATS server: `nats://`, `tls://`, `ws://` or `wss://`
`credentials`	path	unset	Credentials file (JWT and NKey seed) of the component; unset, no authentication
`tls.ca`	path	unset	CA certificates (PEM): TLS required and the server checked against them
`tls.cert`	path	unset	Client certificate (PEM), for mTLS; goes with `tls.key`
`tls.key`	path	unset	Private key of the client certificate; goes with `tls.cert`
`partitions`	integer ≥ 1	`64`	Number of partitions of the future partitioning of the compute stage and value table by target; must exceed the maximum number of instances of a component. Reserved: no service partitions its subjects yet (see Running the Services).

A tls:// URL without tls.ca checks the server against the system roots. See TLS, Encryption and Secrets.

`reconciler`#

Key	Type	Default	Meaning
`leader_ttl`	duration	`5s`	Lifetime of a leadership lease: a standby instance takes over at most this long after the leader dies. Also used by the compute stage, alarm service and transfer manager for their own leases.
`leader_renew`	duration	`1s`	Renewal period of the lease; greater than zero and shorter than `leader_ttl`
`jwt_ttl`	duration	`10min`	Lifetime of the JWTs issued to bound drivers, transports, gateways and connectors, renewed at half-life
`signing_key_file`	path	unset	Seed of the account signing key (readable by its owner only). Without it and `account`, no JWT is issued.
`account`	string	unset	Public key of the NATS account the signing key belongs to

The API also reads signing_key_file and account, to sign the NATS credentials of follow-up.

`api`#

Key	Type	Default	Meaning
`listen`	address	`0.0.0.0:8080`	Listen address of the HTTP/WebSocket API
`web_dir`	path	unset	Directory of the built web application (`core/frontend/dist`), served besides the API
`editor_url`	URL	unset	The editor service, to which the API relays `/v1/editor/…`; unset, no editor

`executor`#

Key	Type	Default	Meaning
`default_retry`	`{times, for, every}`	`{times: 1, every: 2s}`	Retry policy of eligible steps that declare no `retry`: `times` retries after the first attempt, `for` a total duration, `every` an interval. At least `times` or `for`.
`ack_timeout`	duration	`10s`	Longest wait for ACK 1, ACK 2, an echo and the first samples of a verification without `within`; a telecommand not uplinked within this time after PENDING is refused

default_retry is also a compilation parameter: stellar check, lock and compile, the language server and dry runs read it (see Retries).

`derived`#

Key	Type	Default	Meaning
`max_window`	duration > 0	`1h`	Longest window of the temporal functions (`avg`, `rate`, `stable`…), checked at compile time

`alarms`#

Key	Type	Default	Meaning
`max_shelve`	duration > 0	`8h`	Longest shelving of an alarm; a shelving ends by itself after its duration

`passes`#

Key	Type	Default	Meaning
`feeders`	map identity → `fds` or `provider`	`{}`	Identity of each feeder script pushing passes, and the only source it may write

YAML

passes:
  feeders: {fds-feeder: fds, station-feeder: provider}

See Writing a Pass Feeder.

`scheduler`#

Key	Type	Default	Meaning
`margin`	duration	`30s`	Margin kept before the LOS: the runs of a pass must end before LOS minus this margin

Read by the scheduler, the API (runs bound to a pass) and the executor.

`auth`#

Key	Type	Default	Meaning
`jwks_file`	path	unset	JWK set of the OIDC identity provider (the file its `jwks_uri` serves). Unset with `jwks_url`, tokens are refused and only declared identities work.
`jwks_url`	URL	unset	The `jwks_uri` of the provider, read at start (a failure stops the service) and every hour; takes precedence over `jwks_file`
`issuer`	string	unset	Expected `iss`; unset, not checked
`audience`	string	unset	Expected `aud`; unset, not checked
`roles_claim`	dotted path	`roles`	Claim holding the roles, such as `realm_access.roles`: a list, or a string of roles separated by spaces (`scope`)
`roles_prefix`	string	empty	Prefix of the roles of the MCS in that claim, taken off; the others are ignored. Empty: every role
`required`	bool	`false`	Every request of the API needs a checked token (`401 auth::token-required`), but `GET /v1/auth/config` and `GET /v1/openapi.json`; a WebSocket gives it as its `token` parameter
`client_id`	string	unset	Public client of the web console at the provider; with `issuer`, the console signs its users in
`cli_client_id`	string	unset	Public client of the CLI at the provider (native, device flow); with `issuer` and `client_id`, `stellar login` signs in
`organization`	string	unset	Organization (Logto) whose token the console asks for
`nats_ttl`	duration	`1h`	Validity of the NATS credentials of follow-up exchanged against a token

Read by the API, the executor (it checks again the token sent with an answer) and the editor. See Identity and Roles.

`editor`#

Key	Type	Default	Meaning
`listen`	address	`127.0.0.1:8090`	Listen address of `stellar-editor`
`workdir`	path	`/var/lib/stellar/editor`	Its clone of the repository and the working copies of the drafts
`repository`	Git remote	unset	Remote of the configuration repository; unset, nothing to edit (and `stellar-mcs` does not start the editor)
`branch`	string	`main`	Branch the reviews target
`path`	path	`.`	The configuration repository within the Git repository
`forge.kind`	`none`, `gitlab`, `github` or `direct`	`none`	`gitlab` opens merge requests, `github` pull requests, `none` only pushes branches, `direct` merges a proposed draft and publishes it at once (a sandbox)
`forge.api`	URL	`https://gitlab.com/api/v4` or `https://api.github.com`	API of the forge
`forge.project`	string	`''`	`group/repository` (GitLab) or `owner/repository` (GitHub)
`forge.token_env`	string	`STELLAR_FORGE_TOKEN`	Environment variable holding the service token of the MCS, which pushes and opens reviews
`cli`	command	`stellar`	The `stellar` command, for dry runs
`declared_identity`	bool	`true`	Whether identities declared with `X-Stellar-User` are accepted; `false`, OIDC tokens only

See Web Editor.

`archive`#

Key	Type	Default	Meaning
`streams.max_age`	duration > 0	`30d`	Retention of the continuous stream archive (`STREAMS`)
`streams.max_bytes`	size > 0	`2TB`	Its volume bound; the first limit reached applies

The reconciler applies them when it starts. JetStream reserves max_bytes on the disk of the server; when it cannot, the archive is bounded by max_age only, with a warning in the logs.

`observability`#

Key	Type	Default	Meaning
`metrics_addr`	address	`0.0.0.0:9100`	Listen address of `/metrics` and `/healthz`
`log_format`	`json` or `text`	`json`	One JSON object per line, or human-readable text for development
`log_level`	tracing filter	`info`	Such as `info` or `stellar_reconciler=debug,info`; `RUST_LOG` takes precedence when set

See Observability.

Who reads what#

Component	Sections
Every service	`nats`, `observability`
Reconciler	`reconciler`, `archive`
Compute stage, alarm service, transfer manager	`reconciler.leader_ttl`, `reconciler.leader_renew` (their leases)
API	`api`, `auth`, `passes`, `scheduler`, `reconciler.signing_key_file`, `reconciler.account`
Executor	`executor`, `scheduler`, `auth`
Alarm service	`alarms`
Scheduler	`scheduler`
Editor	`editor`, `auth`, compilation parameters
CLI, language server	`executor.default_retry`, `derived.max_window` (compilation); a dry run also `executor.ack_timeout`

Validation#

A configuration is refused, with exit code 2 and the name of the key, when:

nats.url is not a nats://, tls://, ws:// or wss:// URL;
nats.partitions is 0;
reconciler.leader_renew is zero or not shorter than reconciler.leader_ttl;
executor.default_retry sets neither times nor for;
derived.max_window, alarms.max_shelve, archive.streams.max_age or archive.streams.max_bytes is zero;
a feeder of passes.feeders has a source other than fds or provider;
nats.tls.cert is given without nats.tls.key, or the reverse (at connection).

A production example#

YAML

nats:
  url: tls://nats.mcs.example.org:4222
  credentials: /run/secrets/services.creds
  tls:
    ca: /etc/stellar/tls/ca.pem
reconciler:
  signing_key_file: /run/secrets/stellar-account-signing.nk
  account: ACCOUNT_PUBLIC_KEY
api:
  listen: 0.0.0.0:8080
  web_dir: /opt/stellar/frontend
  editor_url: http://127.0.0.1:8090
auth:
  jwks_file: /etc/stellar/jwks.json
  issuer: https://idp.example.org/realms/ops
  audience: stellar-mcs
  roles_claim: realm_access.roles
passes:
  feeders: {fds-feeder: fds, station-feeder: provider}
archive:
  streams: {max_age: 30d, max_bytes: 2TB}
observability:
  log_format: json
  log_level: info

Finding the file#

Environment overrides#

Value syntax#

Sections#

time#

nats#

reconciler#

api#

executor#

derived#

alarms#

passes#

scheduler#

auth#

editor#

archive#

observability#

Who reads what#

Validation#

A production example#

`time`#

`nats`#

`reconciler`#

`api`#

`executor`#

`derived`#

`alarms`#

`passes`#

`scheduler`#

`auth`#

`editor`#

`archive`#

`observability`#