tritonadm config

tritonadm config reads and changes cluster-wide tritond settings, which are stored in FoundationDB. It needs fleet-operator rights. The settings needed to boot tritond live in its boot config file, not here.

Execution context

Every command is an HTTP call against tritond, from any host with a configured tritonadm.

Synopsis

tritonadm config list
tritonadm config get <KEY>
tritonadm config set <KEY> <VALUE> [--hold]
tritonadm config reset <KEY> [-n] [-y] [--keep-going]
tritonadm config features

tritonadm config list

Lists every key. Alias ls. Columns: key, value, default, restart, env. With -l, also description.

tritonadm config get

Prints <KEY> = <VALUE>, then default:, restart: yes or restart: no, an env override: line when an environment variable shadows the stored value at boot, and the description.

tritonadm config set

Stores one value. The command parses <VALUE> in this order:

1. For a sandbox.feature.<NAME>.tenants key, a value that does not start with [ is a comma-separated list of tenant UUIDs. none or an empty string is an empty list. A part that is not a UUID is refused before the request is sent.
2. For any other key, a value that parses as JSON is JSON: 30, true, null, 0.25, {"pool":"vm"}, ["a","b"].
3. Anything else is a JSON string: sandbox-4g, on.

The command prints <KEY> = <VALUE>, then saved or saved; restart tritond to apply. If an environment variable is set for the key, it also prints a note that the variable shadows the value at boot.

Option	Description
--hold	Only for an image pin key. Adds the key to image_pins.held before the write, so the intent reconciler does not move the pin back to the channel's image. Any other key is refused.

The image pin keys are network.gateway_image, sandbox.rootfs_image, sandbox.code_interpreter_image, sandbox.desktop_image, and sandbox.builder_image. With --hold, the command prints this line before the <KEY> = <VALUE> line:

<KEY> is held: the intent reconciler leaves it alone

To follow the channel's image again, remove the key from image_pins.held.

tritonadm config reset

Resets one key to its built-in default, after a confirmation that shows the old and new values. A reset of api.names makes it unset, which means the zone's boot names. With the tritond front door on and no boot names, that reset is refused. A reset of preview.domains stores an empty list.

tritonadm config features

Lists every sandbox feature gate. Columns: feature, mode, default, tenants. With -l, also description.

Write behavior

config set and config reset write with compare-and-swap. tritond reads the settings, applies the change, checks the result, and writes it only if no other write came in between. After 5 conflicting tries, the write fails with 409 and this message:

the settings kept changing during the write; try again

A name list that fails a check in Public names and preview domains gets 400, and nothing is stored.

Sandbox settings

No sandbox.* key needs a tritond restart. The three *_default node keys are read by each compute node's agent when it starts, so restart the agent after a change.

Key	Default	Range	Description
sandbox.rootfs_image	Unset	<UUID>@<STAMP>	Image of the base template. Unset means no sandbox can be created. Image pin.
sandbox.code_interpreter_image	Unset	<UUID>@<STAMP>	Image of the code-interpreter template. Unset means the template is not offered. Image pin.
sandbox.desktop_image	Unset	<UUID>@<STAMP>	Image of the desktop template. Image pin.
sandbox.builder_image	Unset	<UUID>@<STAMP>	Image of the template builder. Image pin.
sandbox.default_package	sandbox-2g	Package name	Package for a create that names none, and the one the booted pool keeps. Checked for name format only.
sandbox.pool_depth	0	0 to 8	Booted sandboxes of the default package each sandbox node keeps waiting. 0 turns the pool off.
sandbox.max_per_tenant	32	At least 1	Live sandboxes one tenant may hold. Read on every create.
sandbox.creates_per_minute_per_tenant	60	At least 1	Creates per tenant per minute, per control-plane node.
sandbox.default_ttl_secs	3600	Up to sandbox.max_ttl_secs	Lifetime when a create names none.
sandbox.max_ttl_secs	86400	At least 1	Longest lifetime a create may ask for.
sandbox.session_ttl_secs	3600	At least 1	Validity of a sandbox session token.
sandbox.enabled_default	false	Bool	Whether a compute node with no override takes sandbox jobs. Agent reads it at start.
sandbox.max_per_node_default	50	1 to 50	Sandboxes a compute node with no override runs at once. Agent reads it at start.
sandbox.reservoir_percent_default	0.25	0.0 to 1.0	Reservoir share for sandbox guests on a node with no override. Agent reads it at start.
sandbox.feature.<NAME>	Per gate	off, allowlist, on	Feature gate mode.
sandbox.feature.<NAME>.tenants	[]	Up to 1024 tenant UUIDs	Tenants let through while the mode is allowlist. A set replaces the whole list.

Feature gates

A gate in allowlist mode with an empty list is off for every tenant. A tenant that is not let through gets 403 FeatureDisabled. Gates apply within a few seconds.

Gate	Default	Covers
memory	allowlist	Pause, memory snapshots, memory forks, and on_deadline=pause. Resume always works.
desktop	allowlist	The desktop template, RDP, screenshots, and input.
templates_from_dockerfile	allowlist	Template builds from a Dockerfile, and build-context uploads.
templates_from_image	on	Template builds from an OCI image.
templates_from_snapshot	on	Template builds from a sandbox snapshot.
egress_domains	allowlist	Domain rules in a sandbox network policy.
code_interpreter	on	The code-interpreter template and the code routes.
preview_public	allowlist	Public preview ports, which need no token. Off also makes existing public ports private.
fork	on	Sandbox fork.
ports	on	Port tunnels and ssh-config.
preview	on	Port settings, preview URLs, and preview-token rotation. Previews also need a preview domain.

Related settings

Key	Default	Description
channel.upstream_url	Unset	The release channel the cluster follows. channel refresh mirrors from it, and install, update, self-update, versions, and channel revisions use it when no channel flag is given. Genesis from the channel sets it. Unset after an --image-dir genesis.
network.gateway_image	Unset	The triton-gateway image that NAT gateway and SSH relay zones run, as <UUID>@<STAMP>. The intent reconciler derives it from the in-cluster channel. Unset means no gateway zone can be created. Image pin.
placement.default_vm_traits	{}	Traits a VM places by when its package and the operator gave it none, as a JSON object such as {"pool":"vm"}. Empty sends such VMs only to compute nodes with no traits. May not name cpu-class or disk-class. At most 30 traits. Applied live.
image_pins.held	[]	Image pin keys that the intent reconciler leaves at the operator's value.
reservoir.enabled_default	true	General bhyve reservoir management, for nodes with no override.
reservoir.percent_default	0.80	General reservoir floor, as a fraction of RAM.

Public names and preview domains

Two settings hold the public names. Each takes a JSON list, or a comma-separated list on config set. none or an empty string is an empty list. Each list holds at most 16 names. Both apply within 5 seconds, with no restart.

Key	Default	Description
api.names	Unset	The Cloud API names. tritond checks them, and refuses a preview.domains entry that shares a registrable domain with one. With the tritond front door on, the front door serves the Cloud API on them. With it off, tritond does not serve on them. Unset means the zone's boot names.
preview.domains	Unset	Sandbox preview domains, primary first. Unset or empty means previews are off. Leave it unset.

config set refuses a name list with 400, and stores nothing. config reset runs the name checks too. The stored-value check answers first, as invalid value for <KEY>: <MESSAGE>:

Refusal	Message
More than 16 names	lists more than 16 names
An empty entry, or one longer than 253 characters	"<NAME>" is not a DNS name

The name checks answer next, as refused: `<KEY>`: <MESSAGE>, where <KEY> is the key whose value failed. The api.names checks also run on every preview.domains write.

Refusal	Message
api.names is an empty list	lists no names; reset it to serve the zone's boot names
api.names is unset, the zone has no boot names, and the front door is on	is unset and the zone gives no API names; the front door needs at least one
Not a DNS name	`<NAME>` is not a DNS name of at least two labels
An API name listed twice	`<NAME>` is listed twice
An API name that is a forwarded service's name	`<NAME>` is the name of a forwarded service
A preview domain that is an ICANN public suffix. A private-section suffix such as github.io is accepted.	preview domain `<DOMAIN>` is a public suffix, not a domain of its own
A preview domain with no registrable domain	preview domain `<DOMAIN>` has no registrable domain
A preview domain that shares a registrable domain with an API name, a forwarded name, or api_domains	preview domain `<DOMAIN>` shares the registrable domain `<REGISTRABLE>` with `<NAME>`; serve previews from a registrable domain of their own
A preview domain listed twice, or one under another	preview domains `<DOMAIN>` and `<DOMAIN>` overlap; list each once
Preview domains with no API, forwarded, or api_domains names to check against	no API or portal names to check the preview domains against: set `api.names` first

config features shows a preview.domains row with on or off. On Triton Cloud it shows off.

The public edge is triton-adc, not tritond. See Set public names and preview domains.

See also

• Turn sandbox features on with feature gates
• Sandbox capacity
• Set up public names and preview domains
• tritonadm command index