Node settings

Hubs and grabbers are configured by environment variables on the machine they run on. Node settings let a server admin override a chosen subset of those from the platform instead, without shell access to the box.

Six methods carry the surface, three per node kind, all under xmb.api.v1 and all requiring the xmb:admin scope:

What may be set

Only keys on an allowlist, which the API serves rather than expecting you to know. Get…Settings returns a settable list describing each key:

{
  "settings": { "GRABBER_WG_MTU": "1280" },
  "settable": [
    {
      "key": "GRABBER_WG_MTU",
      "description": "Tunnel MTU. Lower it when a path fragments — the usual cause of heavy packet loss over WireGuard.",
      "defaultValue": "1380",
      "requiresRestart": true
    }
  ]
}

Read the list rather than hard-coding it. A node and the platform update independently, so a client that assumed the keys would offer settings the running node has never heard of, and hide ones it gained.

settings holds only what is explicitly set. A key that is absent is at the node's own default, which defaultValue reports.

What may never be set

Everything a node needs in order to reach the platform is permanently outside the allowlist — its API URL, its token, its update source, its data directory, and the credentials for its torrent client. This is deliberate and is not a gap to be filled later.

The reason is recovery. Those values are also the only route by which a bad setting could be corrected, so a mistake in one could not be fixed remotely — the correction would have to travel over the thing the mistake broke. Nothing settable is a credential, for the same reason in reverse.

Setting them

Set…Settings replaces the whole map rather than merging into it. The map you send is the map stored, so removing a key means sending it absent:

{
  "serverSlug": "luke",
  "uuid": "eb32c10b-8882-40b5-9479-12145a726547",
  "settings": { "GRABBER_WG_MTU": "1280" }
}

Merging would leave no way to clear a single setting without a second verb, and "unset this" is exactly what an operator reaches for after a value that made things worse.

Values are validated on the way in. A key outside the allowlist, a value the node could not use (GRABBER_WG_MTU of 68, an ANNOUNCE_INTERVAL of 1s), or an empty string all return invalid_argument with a message naming the key. An unknown key is refused rather than silently dropped — a setting that vanished without comment would read as one that had been applied.

When they take effect

The node collects its settings on the announce it already makes, roughly every minute, and writes them to disk. They are applied at its next start, because setting an environment variable only means anything before the configuration is read.

So changing a setting is two steps: set it, then restart the node with RestartHub / RestartGrabber. Every entry in settable reports requiresRestart so a client can say so plainly.

These are deliberately not TriggerHubUpdate / TriggerGrabberUpdate. Those ask a node to converge on what its release channel publishes, and answer UPDATE_OUTCOME_UP_TO_DATE when it already has — which is true, and useless when the reason to restart is a configuration change rather than a version. A restart does not change runningVersion; that is the whole difference between them.

The node drops off the tunnel for a few seconds while it re-execs. A grabber's downloads live in its torrent client rather than in the grabber process, so a restart does not lose them.

A variable already set on the machine itself wins over the platform's value. Someone who set it on the box did so deliberately and can see it there; a value from elsewhere silently overriding it would make the machine misreport its own configuration.

If a setting goes wrong

A new setting is on probation until the node manages a successful announce with it applied. If a node starts three times without ever managing one, it discards the settings, logs that it has done so, and comes back on its own environment.

This matters most for the tunnel. The announce travels to the platform over the ordinary internet rather than through the tunnel, so a setting that breaks the tunnel — a wrong MTU being the obvious one — leaves the node still reachable and still able to be told something different. The probation covers the narrower case of a value that stops the node announcing or starting at all.

The practical consequence: a bad setting costs a few minutes and some restarts. It does not cost a trip to the machine.