External configuration management¶

In cluster installations Sapsan streams are managed by an external system (e.g. Flussonic Central): the server periodically fetches the stream list from an external URL and applies it.

Configuration¶

config_external:
  url: http://central.example.com/central/api/v3/streamers/streamer1.example.com
  bearer: <access token>
  client_host: streamer1.example.com
  interval_secs: 5
  timeout_ms: 30000

Parameter	Description
`url`	where to fetch the configuration from
`bearer`	authorization token for the external server
`client_host`	the name this server identifies itself with to the management system
`interval_secs`	polling period (5 s by default)
`timeout_ms`	request timeout (30 s by default)
`fetch_runtime_config`	whether to also fetch the runtime configuration (`true` by default)

Important

When config_external is enabled, the local streams section in sapsan.yaml is ignored — the external server becomes the source of truth. The other sections (listeners, dvr, auth, api_auth) stay local unless the external server supplies its own.

How polling works¶

Sapsan requests GET <url>/streams every interval_secs; the list is fetched page by page via the next cursor. Every request carries Authorization: Bearer, an x-originator: sapsan header, and the client_host.
The runtime configuration (GET <url>/config — listeners, DVR, auth) is fetched only when the server announces it has one.
If the configuration has not changed, the re-apply is skipped.

Failure tolerance¶

A partially invalid list: broken streams are dropped (reporting which field failed), valid ones are applied — status Partial.
A fully invalid configuration (e.g. a port conflict): nothing is applied, the previous configuration keeps running — status Error.
External server unavailability, broken JSON, and HTTP errors are distinguished in the status (network / malformed_json / http<code>).

Next steps¶

Admin API