config.toml reference

bcd node, bcd site, bcd helper, bcd join, bcd sim, bcd doctor and bcd update read one file, /etc/bcd/config.toml unless --config names another. The install script writes it with mode 0600 (0640 root:bcd on a node installed with --unprivileged); bcd join --server writes it when a machine has none, and a ramdisk writes one into the OS it deploys. This page is the reference for every key daemon/internal/config accepts. The commands page covers the flags, and troubleshooting covers what goes wrong.

Format

The parser accepts a documented subset of TOML 1.0, and refuses everything else with a line number, so a typo fails loudly instead of being ignored:

A file over 64 KiB or not valid UTF-8 is refused. Top-level keys must come before the first [section]: as in TOML, a key after a header belongs to that section. Errors read like this:

config /etc/bcd/config.toml: line 9: unknown key plugins.directory
config /etc/bcd/config.toml: line 4: log.json must be true or false
config /etc/bcd/config.toml: site is required

Every command that loads the file stops with exit 1 on such an error, and bcd doctor fails its config check with the same text. Lists (pins, bridges, CIDRs, clusters, plugin names) are comma-separated strings, since arrays are not accepted.

A complete example

# Written by the better-compute install script. bcd refuses unknown keys.
gateway_url = "https://gw.eu.example.com"
site = "fsn1"
serving_ca_spki_pin = "sha256/..."
join_signing_key_pin = "sha256/..."
join_encryption_key_pin = "sha256/..."
approver_set_sha256 = "<64 lower-case hex digits>"
command_root_sha256 = "<64 hex>,<64 hex>"
# data_dir = "/var/lib/bcd"
# socket_path = "/run/bcd/bcd.sock"

[journal]
max_bytes = 67_108_864
max_events = 10_000

[log]
level = "info"
json = true

[update]
release_pins = "sha256/...,sha256/..."
release_threshold = 2
release_sequence = 12

[helper]
socket = "/run/bcd-helper/helper.sock"
user = "bcd"
instance_bridges = "br0"

[imds]
listen = "169.254.169.254:80"

[kubernetes]
allowed_clusters = "https://10.0.0.10:6443#sha256:<64 hex>"

No node needs every section. The install script writes the top-level keys and only the sections its flags ask for; see generate the script.

Who reads what

bcd ramdisk reads no file: it builds the same structure from its bc.* boot parameters (see the ramdisk). bcd hardware, bcd status and bcd version read none.

Top-level keys

A pin is sha256/ followed by the standard base64 of the 32-byte SHA-256 of a SubjectPublicKeyInfo, the form HPKP and curl --pinnedpubkey use. Anything else is "a pin must be sha256/ followed by the standard base64 of a 32-byte digest". The three pins come from the sealed PKI bundle (bootstrapPins in better-compute/pki, or daemon install-script); they are the node's trust anchors, never taken from the network. A bcd join pin flag that differs from the file is refused ("--serving-ca-pin does not match /etc/bcd/config.toml").

[journal]

See the journal.

[log]

[update]

Self-update (self-update). Without release pins bcd takes no new binary: the control plane alone can never hand a node one.

Without slots_dir and without [helper], upgrade.json and update.json stay in data_dir.

[helper]

Privilege separation: bcd node runs as user and sends its privileged work to bcd helper, as root, on socket. See running bcd node unprivileged.

Security notes:

• The helper reads its own copy of this file as root and refuses to start unless it is a regular file root owns, writable by no one else, in directories only root can write. [host] units, command_root_sha256 and the join pin in it decide what root does for the node, so never hand the file to the bcd account or make it group-writable.
• The socket's directory must be root's and closed to group and other writes; the helper creates the socket there with mode 0660, group the node user's primary group.
• The helper serves a peer only when its uid and gid are user's (or root) and its /proc/<pid>/exe is the entrypoint, a slot binary or the helper's own binary.
• bcd join running as root with this section hands identity.json and node.key to user when it finishes, and keeps root's signed join record that the helper binds host units to.

[plugins]

bcx driver plugins (see driver plugins in bcd and the plugin sandbox). Read by bcd node and bcd site.

A node with [plugins] needs the systemd drop-in that gives bcd CAP_SETUID, CAP_SETGID and its delegated cgroup; see the plugin drop-in. --unprivileged cannot host plugins.

[websocket]

The WebSocket fallback for networks whose TLS-inspecting proxy strips client certificates. Read by bcd node and bcd site; setting url turns it on.

Over the fallback bcd takes only signed commands and specs and opens no tunnels; a node whose trust bundle holds no command-signing roots refuses to dial ("the WebSocket fallback needs command-signing roots (every command and spec signed)"). Renewals go to POST /v1/renew on the same endpoint.

[site]

[boot]

A site agent's boot server, read only by bcd site. See a site agent for an example and sites for its behaviour.

proxy_dhcp and tftp need server_ip (IPv4) and url, or bcd site exits 2. These keys are checked when bcd site starts, not when the file is parsed.

[imds]

[instances]

[kubernetes]

Joining a cluster hands it root on the machine (privileged pods), which is why root, not the control plane, names the clusters. See k8s-join and GPUs for pods. Both keys are validated by the agent at start (bcd node, bcd site) and allowed_clusters also by bcd helper and bcd doctor, not by the parser, so a bad entry does not stop bcd join or bcd update.

[host]

The data directory

data_dir (default /var/lib/bcd, mode 0700) is bcd's own. Under [helper] it belongs to the bcd account, so nothing root trusts lives there.

Outside data_dir:

The install script's own files and units are listed in files on the host.