Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Box profile

A box profile is one JSON file in shared/edge-boxes/, named after the box (i69-mu1.json). It is the only place an edge node’s identity is written down. shared/render-edge-config.py turns it into everything else the box needs:

./shared/render-edge-config.py \
  --config shared/edge-boxes/i69-mu1.json \
  --output-dir target/edge-config/i69-mu1
Generated fileInstalled asRead by
nats-leaf.conf/etc/containers/systemd/nats-leaf.confthe NATS server
alloy.container/etc/containers/systemd/alloy.containersystemd (Quadlet)
streamer.env.json/etc/avena-rs/streamer.env.jsonthe streamer
archiver.env.json/etc/avena-rs/archiver.env.jsonthe archiver
exporter.env.json/etc/avena-rs/exporter.env.jsonthe exporter
labjack-kv.generated.jsonthe key-value bucket, by hand (setup step 9)streamer and archiver

Without --output-dir, the renderer writes into the repository instead (shared/ and rust-ljm/), overwriting whichever box was rendered last. Always pass --output-dir. The installer does.

The renderer stops with an error naming the field if a required field is missing or empty.

Top level

FieldRequiredMeaning
site_idyesSite name, e.g. i69. First token of subjects and keys.
box_idyesThis box, e.g. i69-mu1. Also its hostname.
source.typeyeslabjack.
source.idyesThis box’s LabJack in subjects and keys, e.g. i69-lj2.

nats

FieldRequiredMeaning
root_subjectyesSubject root, avenars.
local_serversyesHow the services reach the local server: nats://127.0.0.1:4222.
config_serversnoCentral servers to mirror configuration from, comma-separated: nats://nats1.oats:4222,nats://nats2.oats:4222. Empty turns mirroring off.
config_jetstream_domainnoJetStream domain of the central bucket. Empty for the default.
leaf_server_nameyesName of the local server, <box_id>-leaf. Shows up in /varz and on central.
leaf_listenyesClient listen address of the local server, 127.0.0.1:4222.
monitor_listenyesMonitoring listen address, 127.0.0.1:8222.
jetstream_domainyesThis box’s JetStream domain, edge-<box_id>. Must be unique.
jetstream_store_diryesStore directory inside the container, /var/lib/nats/jetstream. On the host it is under /home/user/nats.
leaf_credentials_pathyesLeaf credentials inside the container, /etc/nats/creds/leaf.creds. On the host, /etc/containers/systemd/creds/leaf.creds.
leaf_remotesyes, at least oneCentral leaf endpoints: nats://nats1.oats:7422, nats://nats2.oats:7422.
stream_max_bytesnoSize limit of the local stream in bytes, a positive integer. The oldest messages are dropped when it is reached.
kv_bucketyesConfiguration bucket, avenabox.
kv_keyyesThis box’s configuration key, <site_id>.<box_id>.<source_id>.config.
stream_nameyesJetStream stream for live samples, labjacks.

paths

FieldRequiredMeaning
rust_creds_fileyesCredentials the services use: /etc/avena-rs/apt.creds.
parquet_diryesRoot of the archive.
output_diryesWritten to the streamer’s environment; the streamer does not currently use it.
exporter_http_urlyesWritten to the streamer’s environment; not used by the current services.

labjack

FieldRequiredMeaning
nameyesName of the LabJack. Usually the same as source.id.
asset_numberyesUnique integer shown in the webapp and used in archive paths.
max_channelsyesAnalog inputs the webapp offers, 14 for a T7.
ipyesThe LabJack’s reserved IPv4 address.
serialyesThe LabJack’s serial number. The streamer refuses a different device.
rotate_secsyesArchive file window in seconds, normally 300.
sensor_settingsyesInitial recording settings. scans_per_read and scan_rate_hz are required and channels_enabled must not be empty. The whole object is copied into the LabJack configuration.
max_failuresnoBecomes STREAMER_MAX_LABJACK_FAILURES. Default 5.
retry_delay_secsnoBecomes STREAMER_LABJACK_RETRY_DELAY_SECS. Default 5.
identifier, usb_id, open_ordernoWritten to the environment but effectively unused: the streamer opens the LabJack by ip, and falls back to identifier only when no IP is set, which the renderer does not allow.

sensor_settings in the profile only seeds the configuration. Once the box is running, the copy in the key-value bucket is what counts, and edits belong there.