Every node runs the same compose stack and owns its own consoles. Nothing is
installed on the host: the toolchain lives in Dockerfile and the compose
files, and cm is the only entry point you need.
| Service | Job |
|---|---|
discoveryd |
Watches /dev/serial/by-id, decides what is a console, generates the ser2net config |
ser2net |
Stock upstream ser2net, fans each tty out over TCP so several consumers can attach at once |
minerd |
Captures every console, frames and mines it, republishes the raw stream to the broker |
mcpd |
The agent surface (MCP), leases, actuation, queries |
dashd |
The human surface: device list, web console, reports |
peerd |
Announces this node to the fleet and answers peers |
./cm sync user@host # push the source tree, excluding node-owned files
./cm up # build and start, on the node
./cm build-id prints the fingerprint of the source tree. It is baked into
every binary at image build time, so a node can always say which code it is
running. Two nodes reporting the same Cargo version can still be running
different builds; the fingerprint is the thing to compare.
Keep every node on the same build. A fleet where one node is behind produces answers that disagree for reasons that have nothing to do with the boards.
conminer.toml is bind-mounted from the checkout, and the config rejects keys
it does not know. A newer file under an older image stops every service at its
next restart, so sync and ./cm up in one pass, and do not leave a node with
the new file and the old image.
cm sync never overwrites these, and they must not be copied between nodes:
.env: the node name, the address peers should dial, and bind addresses. Overwriting it renames this host in every peer's table, and device rows key on that name. Node policy that must not live in the sharedconminer.tomlgoes here too:CONMINER_RUNNER_ALLOW_RAW_SEND=trueenables the rawsendpassthrough on this node only.instance.json: this node's identity.site.d/: the node's own config (below)./data: the per-device stores.
conminer.toml documents the compiled defaults and is the same on every node
(the config suite holds it to that). What belongs to one node goes in
site.d/*.toml beside it instead: a console's [devices."<selector>"]
section and hooks, a [credentials] file, anything that names this node's
hardware or paths. Every service loads conminer.toml and then each site file
in name order. Tables merge key by key, so a site file names only what it
changes; any other value, an array such as [[controllers]] included,
replaces the one before it. A typo in a site file stops the service like one
in conminer.toml, and the error names the file. conminer check-config
checks the layered result.
# site.d/node.toml
[credentials]
file = "/var/lib/conminer/credentials.toml"
[devices."/dev/serial/by-id/usb-FTDI_Example-if00-port0".hooks]
flash = "/usr/local/libexec/conminer/hooks/qdl-flash --board /etc/conminer/site.d/flash/example.board {image}"
A flash hook's board file lives beside the site files, in site.d/flash/
(docs/flash-hooks.md).
Compose mounts the directory at /etc/conminer/site.d (CONMINER_SITE_DIR
names another one). Only its README is tracked, a deploy never overwrites it,
and ./cm build-id does not hash it, so nodes with different site files still
report the same build for the same source. A change to a site file takes
effect when the services restart (./cm up).
A copy of every node's site directory is tracked in sites/<node>/
(sites/README.md), so the hooks and board files each node runs are on record;
refresh it whenever a node's site.d changes.
curl -s localhost:8080/healthz # dashd
curl -s localhost:8080/api/reports # build fingerprint and the report queue
docker ps --format '{{.Names}} {{.Status}}'
Every service except peerd carries a healthcheck. A node that answers
/api/reports with the expected build is serving the code you think it is.
A powered board with a silent console that returns to EDL after every power
cycle is usually not broken firmware. Look for a lit boot-mode button and the
Held across boots row (in the controller panel, or under the open console),
or call boot_overrides: a latching controller keeps a boot-mode line asserted
until it is released, and power cycle releases nothing. Normal boot (or normal_boot over MCP) releases every line, proves
it by readback, and only then cycles. See boot-overrides.md.
run_command at a login prompt returns LOGIN_REQUIRED until a login for that
console is in the file named by credentials.file. The file must be mode 0600
and owned by the user conminer runs as; it is read at each gate, so adding an
entry needs no restart. Format, placement and what is refused:
credentials.md.
A board's consoles and controller are grouped into a target by the USB hub
they share (2.2, 3.1), unless conminer.toml or name_target names one.
Only consoles that are plugged in, or are keyed by position, take their target
from the hub: a by-id console that is gone keeps its last by_path, and the
hub may hold another board's harness by now. Name a target to keep an
unplugged board's consoles together.
After a power or boot-mode action, devices that enumerate within two minutes
are learned as that board's gadgets (usb_identity, usb_ports tags) and
scope its EDL and zombie checks. A device that carries a console or controller
this node knows (its serial is in a by-id name, or a present console sits on
its port) is a debug adapter and is never learned, resolved or kept as a
gadget; discovery removes such entries from tags on every pass. Two boards'
harnesses on one hub cannot be told apart by topology: the controller binding
refuses rather than guess, so give each its own hub or its own power hook.
Stores grow with use. stats reports db_bytes, line and template counts, and
what the retention policy would collect. Pruning happens only when prune is
called; a configured policy alone does not reclaim anything.