Settings
An administrator can change most of reportd's settings in the studio, under Admin → Settings (/admin/settings), instead of in the config file.
Where a setting comes from
reportd reads its settings in layers, each over the one before:
- the defaults;
- the config file (
config.yaml, or--config, or$REPORTD_CONFIG); - the settings:
dataDir/settings.yaml, which setup and the Settings page write, and withstate.driver: postgres, the schema'ssettingstable over it; REPORTD_*environment variables (docker.md).
The page shows every setting with what it does, its value, its default and where its value came from: Default, Config file, Set here, or the variable's name. reportd config show --origin prints the same. Secrets are masked as config show masks them; a secret: reference is shown, since it holds no secret.
A setting the config file or a variable sets is locked. It is changed there; the page shows it with a Locked badge, and PATCH /v1/settings refuses it with 409 setting-fixed and the origin. A list or a map (limits.rate, auth.oidc.providers) is one setting, locked when the file sets any part of it.
The page
- Sections group the settings (Sign-in, Security, Limits, Rendering, Data, Studio connections, Viewer, Retention, …), with the ones reportd reads at start last. Each row has the setting's name, its path, what it does, its default and its origin, and its field: a switch, a number with its unit, a size in KB, MB or GB, a duration (
30m,8h), a list, a choice of the words it takes, or asecret:reference. - Search (
/) finds a setting by its name, path, description or value; every word must match, and the matches are marked. The chips narrow to the settings that can be changed, that are changed, set here, locked, or read at start. - The inspector: a setting's name opens it in a pane on the right (
?setting=<path>links to it), with all it says, the full field (the rate limits as a table, a list of objects such as the sign-in providers as JSON), its default, where its value comes from, and what applying it restarts. Escape or Close shuts it. - Changes wait until you apply them: each row shows Changed with Undo, Reset to default puts a setting set here back to what the config file or the default gives, and the bar at the bottom counts them. Apply changes (Mod+S) opens a review of each change, now and after, then reportd restarts once for all of them.
What the page can change
Every setting but these, which it shows, read-only:
| Not changed here | Why |
|---|---|
listen, dataDir, state.*, secrets.*, migrations.* | reportd reads them before it can read its settings. |
renderer.command, renderer.listen, renderer.unix, the stores' paths, studio.*, viewer.dir, viewer.path, viewer.signInPath, viewer.spillDir, agents.assistant.file, sync.* | Paths on disk, routes, and what isn't used yet. |
admin.* | The first administrator, made at the first start. |
auth.mfaKey | A new key couldn't open the second factors sealed with the old one. |
licence, connections | They have pages of their own (Licence, Data sources). |
Of the rest, some need a licence feature: auth.oidc.providers, auth.saml.* (sso), renderer.urls, renderer.discover, renderer.discoverName (scale), agents.assistant.* (assistant). Secrets are only secret: references: viewer.linkSecret, renderer.token, auth.saml.key, the assistant's token and API key, client secrets and webhook secrets in their lists.
Studio connections
The Studio connections section is the policy for the data connections people add in the studio: what they may reach, and which secrets they may send there. It doesn't apply to the operator's connections in config.yaml, which are trusted. A connection outside it can't be saved or tested. Adding and changing the connections themselves is in data-connections.md.
| Setting | Default | What |
|---|---|---|
data.connections.allowHosts | none | The hosts a connection may reach: db.corp.example, *.db.corp.example for the names under it (not the domain itself), api.partner.example:443 for one port only, an IP address (203.0.113.7, [2001:db8::5]:5432), or * for any host. Names compare in lower case, with a trailing dot dropped and international names in their xn-- form. Empty, no studio connection can be saved, so set this first. |
data.connections.allowPrivate | off | Private addresses: 10/8, 172.16/12, 192.168/16, fc00::/7 (ULA) and 100.64/10 (carrier-grade NAT). |
data.connections.allowLoopback | off | This machine: 127.0.0.0/8, ::1 and localhost, for a database next to reportd. |
data.connections.sqliteDir | none | The one folder, as a full path, that SQLite files come from, opened read-only. A file is named relative to it; .. and symbolic links can't lead out of it. Empty, studio connections can't use SQLite. |
data.connections.secrets | secret:env:CONN_*, secret:file:conn-* | The secret: references a connection may use, as patterns where * stands for any characters. A secret provider plugin's references need a pattern of their own, such as secret:vault:kv/reporting/*. |
- Never reachable, whatever the settings say: link-local addresses (
169.254/16,fe80::/10), the clouds' metadata services (169.254.169.254,fd00:ec2::254,100.100.100.200, Azure's168.63.129.16,metadata.google.internal), multicast, and the reserved ranges. An IPv6 address that carries an IPv4 one (mapped, NAT64, 6to4) counts as that one. A host listed inallowHostsis checked again on the address dialled, after DNS. - Never usable as a secret, whatever the patterns say: any reference reportd's own config uses (
auth.*,viewer.linkSecret,renderer.token, the assistant's key and token, webhook and sign-in provider secrets, the operator's connections, the licence…), the tokens of the font and template sources, and anyREPORTD_variable. Otherwise someone who may add connections could point one at their own server and have reportd send its own secrets there. reportd collects these from the whole config it runs on, so a secret setting added later is covered too. Environment variables and files compare without regard to case, as Windows reads them. - The patterns are checked when they're saved:
*in a host only at the start (*.corp.example) or on its own; no wildcard over a whole top-level domain (*.com); a port from 1 to 65535; a secret pattern that names its provider and gives the names a prefix (secret:env:*is refused). A refusal names the entry at fault (422invalid, withpathsuch asdata.connections.allowHosts.1). A newsqliteDirmust be a folder that is there. - Testing a connection, and
GET /v1/connections?check=true, count in theproberate class (rate-limits.md).
renderer.workers, renderer.queue and renderer.maxBodyBytes are given to the renderd reportd starts (renderer.command), as --workers, --queue and --max-body; a renderd reportd only connects to takes its own flags.
Applying
- Secrets are references, never values. A secret setting takes only a
secret:reference (secret:env:NAME,secret:file:NAME), so the site never writes a password to a file: a literal is refused 422secret-literal. Sending the mask back (********) is refused 422masked, so a secret can't be replaced by the mask. - Each value is checked. A setting that takes one of a few words (
tests.publishGate,logging.level, …) refuses another (422invalid), rather than reading it as the default as the config file's would; a number can't be negative. - The whole config is checked first. reportd resolves the config with the change, and runs the checks it runs at start. A change that would leave it invalid writes nothing (422
invalid, saying why), and so does one the licence doesn't cover (403licence-required). - Applying restarts reportd, once for all the changes, in-process on the same listener, as after setup: requests wait meanwhile, signed-in sessions stay, a job's render in progress runs again, and the viewer's sessions keep their data while its limits stay the same. The renderd reportd starts restarts with it. Nothing is reloaded live.
- Everyone is told. Before it stops, reportd tells every signed-in browser over
GET /v1/events. The studio and the viewer say it is applying new settings and let people keep working: edits wait and are saved once it is back, and the connection-lost overlay doesn't come up. Back, they check the sign-in, save what waited, read again what the settings change (the branding, the licence, who is signed in, the versions) and say so. Nothing reloads; the studio offers to reload only when reportd came back as another version. - A change reportd can't start on is put back. If reportd fails to start on the new settings (renderd doesn't answer at a new address, say), it puts the settings back as they were and starts on those; the page then says which change was undone, and why. On the shared state, the node that made the change puts it back.
- Reset to default sends
null, which removes the setting from the settings, so the config file or the default applies again. - Each change is audited as
settings.changewith the paths, never the values.
On the shared state
With state.driver: postgres, a change goes to the schema's settings table, not to a node's settings.yaml. Every node polls the table's version with its other reloads, and starts again within a few seconds of a change, as it does for a new licence, telling its own browsers first. The page says that every node restarts. Two changes at once can't overwrite each other: the second is refused 409 settings-changed, and is made again on what the first wrote.
Each node's own settings.yaml (where setup writes) is still read, under the table. Backups take the two together, as the layer reportd reads; reportd state import moves settings.yaml into the table, and state export writes the layer back to dataDir (state.md).
The API
| Route | What |
|---|---|
GET /v1/settings | Every setting: path, value (masked), origin, editable, fixed, secret, the licence feature it needs, and what it is: title, doc, kind, default, unit, options, and renderd when the renderd reportd starts is given it. shared says a change restarts every node; undone names the last change reportd couldn't start on, and why. |
PATCH /v1/settings | {path: value} changes, null putting one back. Answers the paths written and restart: true. |
GET /v1/events | Server-sent events for any signed-in principal: hello with reportd's run and version on connecting, restarting with the reason and the paths changed before it stops, signed-out when the stream's sign-in has ended (checked every 25 s without counting as a use), and library-released when a library's release reaches an environment the principal may read templates in (designer/libraries.md). |
The settings routes need settings.manage, which only the administrator role has and an agent key never does.