mirror of
https://github.com/pollen-robotics/microduck.git
synced 2026-11-22 06:29:20 +08:00
The October brain, brought up to main. Beyond the conflicts: - The pad's handoff (silent until touched, lets go after pad_idle_s) is now pad_map::engage, since main moved padd's mapping into pad-map. A pad nobody was touching going away no longer sits the robot down: the brain was driving, not the pad. - autod walks at the pad's [pad_drive] full stick rather than the removed robotd_params::drive constants. - [map]'s template values are commented out like [laser] and [soccer]: they never shipped live, so they do not belong in EVER_SHIPPED. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1101 lines
53 KiB
Bash
Executable File
1101 lines
53 KiB
Bash
Executable File
#!/bin/sh
|
|
#
|
|
# Install the robot daemon on a fresh board, from nothing.
|
|
#
|
|
# curl -fsSL https://raw.githubusercontent.com/pollen-robotics/microduck/main/scripts/install.sh | sudo sh
|
|
#
|
|
# Target: 64-bit Debian userland on aarch64 — Armbian 26.2.x on the Radxa Zero 3, and
|
|
# whatever else Debian 12/13 arm64 you point it at. Needs `curl` and coreutils and
|
|
# nothing else: tar and zstd are linked into `updaterd`, so there is no package to
|
|
# install first.
|
|
#
|
|
# Idempotent. Re-running it on an installed robot re-checks everything and changes
|
|
# nothing, and it never overwrites /etc/robot/updater.toml.
|
|
#
|
|
# ── how it works ─────────────────────────────────────────────────────────────
|
|
#
|
|
# The circularity — "an update needs the updater, which arrives in an update" — is broken
|
|
# by downloading one bare `updaterd` binary and running its `install` subcommand. That
|
|
# runs the ordinary engine: signature verification, extraction, the atomic swap, the
|
|
# journal entry. There is no bootstrap-specific install logic, so nothing here can drift
|
|
# from how every later update behaves.
|
|
#
|
|
# Notably this script never parses a manifest. It hands `updaterd` the config and lets the
|
|
# configured source resolve `latest`, because a shell script picking the version out of a
|
|
# signed JSON document would be a second, weaker reader of that document.
|
|
#
|
|
# For the same reason only two files come from the repository over raw.githubusercontent:
|
|
# the config and the public keys, both needed *before* anything can be verified. The unit
|
|
# files and the journald drop-in are taken out of the installed release instead — the same
|
|
# bytes a signature was checked against.
|
|
#
|
|
# ── chain of trust ───────────────────────────────────────────────────────────
|
|
#
|
|
# 1. TLS to raw.githubusercontent.com gets this script, the config and the public keys.
|
|
# 2. TLS to github.com gets the bootstrap `updaterd`. It is NOT yet verified.
|
|
# 3. That binary verifies the manifest and artifact against the keys from (1), and
|
|
# refuses to install anything they do not sign.
|
|
# 4. Afterwards this script compares the bootstrap binary's sha256 against
|
|
# `current/bin/updaterd`, which came out of the verified artifact. Equal digests
|
|
# mean the binary from (2) was genuine after all. CI asserts the two are the same
|
|
# bytes, so a mismatch is a real finding, not a packaging quirk.
|
|
#
|
|
# The residual trust is GitHub itself, which is also where this script came from — step
|
|
# (4) narrows it rather than removing it. An install that wants no such window should use
|
|
# `updaterd install --from <dir>` against files carried in by hand.
|
|
|
|
set -eu
|
|
|
|
# ── knobs ────────────────────────────────────────────────────────────────────
|
|
|
|
# The repository releases are published from. Override for a fork or a test repo.
|
|
REPO="${DUCK_REPO:-pollen-robotics/microduck}"
|
|
|
|
# Branch the trusted keys are read from. Pin to a tag for a reproducible provisioning run.
|
|
#
|
|
# Deliberately *not* where the config comes from — see `CONFIG_REF` below. Keys and config age
|
|
# differently: the key set only ever grows, so the newest is the safest, while a config field is
|
|
# only understood by binaries from its own version onwards.
|
|
ENV_REF="${DUCK_REF:-}"
|
|
REF="${ENV_REF:-main}"
|
|
|
|
# Where `updater.toml` and `robotd.toml` come from. Defaults to the tag of the release being
|
|
# installed, and `DUCK_REF` deliberately does *not* change it.
|
|
#
|
|
# That looked wrong at first — surely naming a ref should name it for everything — and it is
|
|
# not. `--ref my-branch` means "run my branch's scripts", which is how the provisioning scripts
|
|
# get tested at all; it does not mean "hand the last stable binary a config from a branch it
|
|
# predates". Making DUCK_REF govern this put the `allow_users` failure straight back, on the
|
|
# very command an operator would use to test the fix for it.
|
|
#
|
|
# Set this only to test a config change together with a build that understands it.
|
|
CONFIG_REF="${DUCK_CONFIG_REF:-}"
|
|
|
|
# Set by `resolve_bootstrap_asset` to the tag of the release actually being installed, and used
|
|
# by `install_config` when the operator did not name a ref. Empty until then.
|
|
RELEASE_TAG=""
|
|
|
|
# For a private repository: a token with read access to contents. Also used for the
|
|
# release download, which needs auth on a private repo.
|
|
TOKEN="${DUCK_TOKEN:-}"
|
|
|
|
# Re-install a release onto a board that already has one, using the release's *own*
|
|
# updaterd rather than the one installed.
|
|
#
|
|
# The escape hatch for a board whose installed updaterd is too old to accept the release you
|
|
# are trying to give it. Not hypothetical: 0.1.4 taught the health gate to commit on a
|
|
# `degraded` robot, and a board on 0.1.2 rolls 0.1.4 back for reporting exactly that — it
|
|
# cannot install the version that fixes it. Every future change to health semantics or
|
|
# manifest format has the same shape.
|
|
#
|
|
# `updaterd install` refuses when a release is live, and it is right to: it forces
|
|
# `on_apply = none` and `health = none`, which on a *running* robot would silently disable
|
|
# auto-rollback. So this stops the daemons first. With nothing running there is no robot to
|
|
# mislead anyone about, which is the same position a bare board is in — and that is a path
|
|
# this script already takes. `install_units` starts them again afterwards.
|
|
#
|
|
# What is genuinely given up is auto-rollback *for this one install*: with no gate, a bad
|
|
# release stays live. `verify_install` reports health at the end and `report` names
|
|
# `robotctl rollback` for that reason. Ordinary updates keep the gate.
|
|
FORCE_REINSTALL="${DUCK_FORCE_REINSTALL:-}"
|
|
|
|
# Which electronic board this is, written to robotd.toml's `[board] version`. Empty leaves the
|
|
# file alone, which is a zero3 unless it already says otherwise. `provision-board.sh --board`.
|
|
BOARD="${DUCK_BOARD:-}"
|
|
|
|
# Trust the team dev key on this board, so `robotctl update apply --ref <branch>` works.
|
|
#
|
|
# sudo DUCK_TOKEN=... DUCK_DEV_KEY=/path/to/team.dev.pub sh install.sh
|
|
#
|
|
# Operator-supplied on purpose, and never fetched. `deploy/trusted_keys/README.md` is
|
|
# explicit that `team.dev.pub` stays out of the repository: a robot that trusts it installs
|
|
# anything anyone on the team builds, unreviewed. Fetching it here would turn that from a
|
|
# per-board decision into the default for every robot we image, which is precisely the
|
|
# property that must not be automatic.
|
|
DEV_KEY="${DUCK_DEV_KEY:-}"
|
|
|
|
# Install everything and start nothing.
|
|
#
|
|
# sudo DUCK_NO_START=1 DUCK_TOKEN=... sh install.sh
|
|
#
|
|
# For separating a board-level fault from the daemons. It puts the release, the units, the users
|
|
# and the groups in place and leaves every unit neither enabled nor started, so the board — and
|
|
# the boot after it — comes back with nothing of ours running. `verify_install` then skips the
|
|
# checks that need a live daemon rather than failing them.
|
|
#
|
|
# Deliberately not `enable` without `--now`: the point is that the *next* boot is clean too, and
|
|
# an enabled unit would start on it. That reboot is what makes the measurement honest, because
|
|
# stopping a daemon does not undo what it pushed to a subsystem — a `btd` that has set `Pairable`
|
|
# and registered a default pairing agent leaves both behind when it dies.
|
|
NO_START="${DUCK_NO_START:-}"
|
|
|
|
RAW="https://raw.githubusercontent.com/${REPO}/${REF}"
|
|
BOOTSTRAP_ASSET="updaterd-bootstrap-aarch64"
|
|
|
|
# Set by `resolve_bootstrap_asset`. A global rather than a `$(...)` result so a failure can
|
|
# `die` in the caller's shell instead of exiting a subshell and returning an empty string.
|
|
BOOTSTRAP_URL=""
|
|
|
|
# Set by `add_operator_to_group` when it added the operator to `robot` on this run, which means
|
|
# their current shell still cannot reach the sockets. Read by `report`, so the closing
|
|
# instructions gate on it rather than listing commands that are going to fail.
|
|
group_pending=0
|
|
|
|
CONFIG_DIR=/etc/robot
|
|
KEYS_DIR="${CONFIG_DIR}/trusted_keys"
|
|
INSTALL_DIR=/opt/robot/daemon
|
|
UNIT_DIR=/etc/systemd/system
|
|
|
|
# Public keys expected in the image. All three, not just the one that signs today: a
|
|
# robot verifies only against the set baked into it, so this is the single chance to make
|
|
# key rotation possible without re-flashing by hand.
|
|
KEYS="release-1.pub release-2.pub release-3.pub"
|
|
|
|
# ── helpers ──────────────────────────────────────────────────────────────────
|
|
|
|
say() { printf '\033[1m==>\033[0m %s\n' "$*"; }
|
|
warn() { printf '\033[33mwarning:\033[0m %s\n' "$*" >&2; }
|
|
die() { printf '\033[31merror:\033[0m %s\n' "$*" >&2; exit 1; }
|
|
|
|
fetch() {
|
|
# $1 url, $2 destination
|
|
if [ -n "$TOKEN" ]; then
|
|
curl -fsSL -H "Authorization: Bearer ${TOKEN}" -o "$2" "$1"
|
|
else
|
|
curl -fsSL -o "$2" "$1"
|
|
fi
|
|
}
|
|
|
|
# As `fetch`, but asking the release API for bytes rather than metadata.
|
|
#
|
|
# Without `Accept: application/octet-stream` that endpoint answers with the asset's JSON
|
|
# description, which downloads perfectly and is not a binary.
|
|
fetch_asset() {
|
|
# $1 url, $2 destination
|
|
if [ -n "$TOKEN" ]; then
|
|
curl -fsSL -H "Authorization: Bearer ${TOKEN}" \
|
|
-H "Accept: application/octet-stream" -o "$2" "$1"
|
|
else
|
|
curl -fsSL -H "Accept: application/octet-stream" -o "$2" "$1"
|
|
fi
|
|
}
|
|
|
|
# ── steps ────────────────────────────────────────────────────────────────────
|
|
|
|
check_environment() {
|
|
if [ "$(id -u)" != 0 ]; then
|
|
die "run as root (pipe to \`sudo sh\`, not \`sh\`)"
|
|
fi
|
|
|
|
arch="$(uname -m)"
|
|
if [ "$arch" != "aarch64" ]; then
|
|
die "this installer publishes aarch64 binaries only, and this box is ${arch}"
|
|
fi
|
|
|
|
for tool in curl systemctl sha256sum install; do
|
|
if ! command -v "$tool" >/dev/null 2>&1; then
|
|
die "${tool} is required"
|
|
fi
|
|
done
|
|
|
|
case "$REPO" in
|
|
ORG/*)
|
|
die "REPO is still the placeholder '${REPO}'.
|
|
Set DUCK_REPO, or substitute the real repository in scripts/install.sh and
|
|
deploy/updater.toml. A robot installed against a repository that does not exist
|
|
installs fine and then never finds another update."
|
|
;;
|
|
esac
|
|
}
|
|
|
|
# The board has no battery-backed RTC. A clock reading 1970 fails TLS certificate-date
|
|
# validation, and the error surfaces as an opaque handshake failure several steps later —
|
|
# `updaterd`'s own preflight checks this for the same reason. Better to say so here.
|
|
wait_for_clock() {
|
|
if [ ! -d /run/systemd/system ]; then
|
|
warn "not running under systemd; skipping the clock check"
|
|
return 0
|
|
fi
|
|
if timedatectl show --property=NTPSynchronized --value 2>/dev/null | grep -q yes; then
|
|
return 0
|
|
fi
|
|
|
|
say "waiting for the clock to sync (no RTC on this board; TLS needs a real date)"
|
|
i=0
|
|
while [ "$i" -lt 60 ]; do
|
|
if timedatectl show --property=NTPSynchronized --value 2>/dev/null | grep -q yes; then
|
|
return 0
|
|
fi
|
|
sleep 2
|
|
i=$((i + 1))
|
|
done
|
|
warn "the clock is still unsynchronised after 2 minutes; downloads may fail with a
|
|
certificate error. Check the network and systemd-timesyncd."
|
|
}
|
|
|
|
# The trust anchor and the one file an operator is expected to edit. Both come from the
|
|
# repository over raw rather than from a release, because nothing can be verified until the keys
|
|
# are here.
|
|
#
|
|
# But from *different refs*, and that distinction cost a board. The keys come from `REF`
|
|
# (`main` by default) because the trusted set only ever grows, so the newest is the safest. The
|
|
# config comes from the tag of the release actually being installed, because a config field is
|
|
# only understood by binaries from its own version onwards — and pairing a config off `main`
|
|
# with the last stable binary means every field added since that release breaks provisioning:
|
|
#
|
|
# ERROR updaterd: invalid config error=TOML parse error at line 70
|
|
# unknown field `allow_users`, expected one of ...
|
|
#
|
|
# on a fresh board, from a clean checkout, with nothing an operator could have done wrong.
|
|
# `deny_unknown_fields` is right — a typo in a robot's config should not be ignored — so the
|
|
# fix belongs here, in what gets paired with what.
|
|
#
|
|
# An explicit `DUCK_REF` still wins for both: someone naming a ref is asking for that ref.
|
|
install_config() {
|
|
say "installing config and trusted keys"
|
|
|
|
# Where the *config* comes from, as opposed to the keys and the scripts.
|
|
if [ -n "$CONFIG_REF" ]; then
|
|
config_raw="https://raw.githubusercontent.com/${REPO}/${CONFIG_REF}"
|
|
warn "config from ${CONFIG_REF} because DUCK_CONFIG_REF asked for it. If that ref has
|
|
fields the release being installed does not know, updaterd will refuse to start."
|
|
elif [ -n "$RELEASE_TAG" ]; then
|
|
config_raw="https://raw.githubusercontent.com/${REPO}/${RELEASE_TAG}"
|
|
say "config from ${RELEASE_TAG}, matching the release being installed"
|
|
else
|
|
config_raw="$RAW"
|
|
fi
|
|
|
|
mkdir -p "$KEYS_DIR"
|
|
chmod 755 "$CONFIG_DIR" "$KEYS_DIR"
|
|
|
|
for key in $KEYS; do
|
|
# Only release-1 signs today; the spares are the rotation path and may not be
|
|
# committed yet. A missing spare is not fatal, a missing release-1 is.
|
|
if fetch "${RAW}/deploy/trusted_keys/${key}" "${KEYS_DIR}/${key}"; then
|
|
chmod 644 "${KEYS_DIR}/${key}"
|
|
else
|
|
rm -f "${KEYS_DIR}/${key}"
|
|
if [ "$key" = "release-1.pub" ]; then
|
|
die "cannot fetch ${key} from ${RAW}/deploy/trusted_keys/
|
|
Without it nothing can be verified, so there is nothing safe to install."
|
|
fi
|
|
warn "no ${key} published yet; skipping"
|
|
fi
|
|
done
|
|
|
|
# Never overwritten. This is the file an operator edits to point a bench robot at a
|
|
# different channel or to allow dev keys, and clobbering that on a re-run is a
|
|
# surprise nobody wants twice.
|
|
if [ -f "${CONFIG_DIR}/updater.toml" ]; then
|
|
warn "keeping the existing ${CONFIG_DIR}/updater.toml"
|
|
else
|
|
fetch "${config_raw}/deploy/updater.toml" "${CONFIG_DIR}/updater.toml"
|
|
sed -i "s|\"ORG/duck-daemon\"|\"${REPO}\"|" "${CONFIG_DIR}/updater.toml"
|
|
chmod 644 "${CONFIG_DIR}/updater.toml"
|
|
fi
|
|
|
|
if grep -q '"ORG/' "${CONFIG_DIR}/updater.toml"; then
|
|
die "${CONFIG_DIR}/updater.toml still names a placeholder repository"
|
|
fi
|
|
|
|
# Same rule: never overwritten, because it is where a bench robot's loop rate and
|
|
# health thresholds get tuned. robotd runs on built-in defaults if it is missing, so
|
|
# this is documentation as much as configuration.
|
|
if [ -f "${CONFIG_DIR}/robotd.toml" ]; then
|
|
warn "keeping the existing ${CONFIG_DIR}/robotd.toml"
|
|
else
|
|
fetch "${config_raw}/deploy/robotd.toml" "${CONFIG_DIR}/robotd.toml"
|
|
chmod 644 "${CONFIG_DIR}/robotd.toml"
|
|
fi
|
|
declare_board
|
|
}
|
|
|
|
# Land the first release through the real engine. `--config` is the config installed
|
|
# above, so there is one statement of where keys live, where state lives and which channel
|
|
# this robot tracks — rather than a copy of those values here that could disagree with the
|
|
# one the daemon reads a minute later.
|
|
# Find the bootstrap asset's API download URL on the latest stable release.
|
|
#
|
|
# **Not** `releases/latest/download/<asset>`. On a private repository that browser URL
|
|
# returns 404 with or without a token — see `docs/design/updater-design.md` §6.1 — which is exactly
|
|
# how this failed the first time it was run against a real board. The engine already
|
|
# re-resolves its own download URLs through the release API (`resolve_download` in
|
|
# `source/github.rs`); this script was the one place that had not caught up, because until a
|
|
# release was promoted there was nothing here to exercise.
|
|
resolve_bootstrap_asset() {
|
|
# Idempotent: `main` resolves early so `install_config` knows the tag, and
|
|
# `bootstrap_first_release` still asks for itself so it stands alone. One API call either
|
|
# way — and, more usefully, one answer, so the config and the binary cannot come from two
|
|
# different "latest" releases if one is published mid-install.
|
|
[ -z "$BOOTSTRAP_URL" ] || return 0
|
|
|
|
api="https://api.github.com/repos/${REPO}/releases/latest"
|
|
json="$(mktemp)"
|
|
|
|
if ! fetch "$api" "$json"; then
|
|
rm -f "$json"
|
|
die "cannot read ${api}
|
|
A stable, non-prerelease release must exist. If only staging releases have been
|
|
published, promote one first: gh workflow run promote --field version=X.Y.Z"
|
|
fi
|
|
|
|
# Parsed with grep rather than jq: this script runs before anything is installed, and
|
|
# requiring a JSON parser on a freshly flashed board, in order to bootstrap the thing
|
|
# that installs software, would be the wrong way round.
|
|
#
|
|
# Whitespace is stripped *first*. The API pretty-prints, so `tr '{'` alone leaves the
|
|
# original newlines in place and grep still matches line by line — the line naming the
|
|
# asset does not carry its id, and the search silently finds nothing. Compacting makes
|
|
# one line per JSON object, and an asset's `id` and `name` both precede its nested
|
|
# `uploader` object, so the line naming the asset carries its id too.
|
|
json_compact="$(mktemp)"
|
|
tr -d ' \n' < "$json" | tr '{' '\n' > "$json_compact"
|
|
rm -f "$json"
|
|
|
|
id="$(
|
|
grep "\"name\":\"${BOOTSTRAP_ASSET}\"" "$json_compact" \
|
|
| grep -o '"id":[0-9][0-9]*' \
|
|
| grep -o '[0-9][0-9]*' \
|
|
| head -1
|
|
)"
|
|
|
|
if [ -z "$id" ]; then
|
|
rm -f "$json_compact"
|
|
die "the latest release has no asset named ${BOOTSTRAP_ASSET}.
|
|
A promoted release must carry it — release.yml attaches it, promote.yml copies it across."
|
|
fi
|
|
|
|
# The tag as well, because the config has to come from the same version as the binary.
|
|
# Same grep-not-jq reasoning as above.
|
|
RELEASE_TAG="$(
|
|
grep -o '"tag_name":"[^"]*"' "$json_compact" \
|
|
| head -1 \
|
|
| sed 's/.*"tag_name":"//; s/"$//'
|
|
)"
|
|
rm -f "$json_compact"
|
|
|
|
BOOTSTRAP_URL="https://api.github.com/repos/${REPO}/releases/assets/${id}"
|
|
}
|
|
|
|
# Stop the daemons so a forced re-install is operating on an inert board.
|
|
#
|
|
# Deliberately not `try-restart`-style politeness: the point is that nothing is live while
|
|
# the swap happens with no health gate behind it. Motors stop; on this robot that is
|
|
# acceptable and is the price of the escape hatch.
|
|
stop_for_reinstall() {
|
|
say "stopping the daemons for a clean re-install"
|
|
# Absent units are not a problem to report: a board running an older release simply has no
|
|
# configd or btd, and warning about them on every forced re-install trains people to ignore
|
|
# the warnings that matter.
|
|
for unit in autod.service mapd.service padd.service netpadd.service tofd.service nfcd.service btd.service configd.service robotd.service updaterd.service; do
|
|
[ -f "${UNIT_DIR}/${unit}" ] || continue
|
|
systemctl stop "$unit" 2>/dev/null || warn "could not stop ${unit}"
|
|
done
|
|
}
|
|
|
|
bootstrap_first_release() {
|
|
if [ -L "${INSTALL_DIR}/current" ] && [ -n "$FORCE_REINSTALL" ]; then
|
|
say "forcing a clean re-install over $(readlink "${INSTALL_DIR}/current")"
|
|
warn "the health gate does not apply to a forced re-install, so this one cannot
|
|
auto-roll-back. If the robot misbehaves afterwards: sudo robotctl rollback daemon"
|
|
stop_for_reinstall
|
|
elif [ -L "${INSTALL_DIR}/current" ]; then
|
|
say "a release is already live ($(readlink "${INSTALL_DIR}/current")); skipping the bootstrap"
|
|
# This script provisions a bare board; it is not how an installed board updates. Say
|
|
# so, because everything after this point still prints reassuring green output and it
|
|
# is entirely reasonable to read that as "now on the latest release".
|
|
cat <<'EOF'
|
|
|
|
This script only bootstraps a board with no release on it, so the daemon version below
|
|
will not change. To update an installed board:
|
|
|
|
sudo robotctl update apply daemon
|
|
|
|
If that rolls back because the installed updaterd is too old to accept the new release,
|
|
re-install through the release's own updaterd. This stops the daemons and runs without a
|
|
health gate, so it cannot auto-roll-back — signatures and hashes are still verified:
|
|
|
|
sudo DUCK_TOKEN="$DUCK_TOKEN" DUCK_FORCE_REINSTALL=1 sh /tmp/install.sh
|
|
|
|
EOF
|
|
return 0
|
|
fi
|
|
|
|
tmp="$(mktemp -d)"
|
|
# shellcheck disable=SC2064 # expand $tmp now, deliberately
|
|
trap "rm -rf '$tmp'" EXIT INT TERM
|
|
|
|
say "fetching the bootstrap updaterd"
|
|
resolve_bootstrap_asset
|
|
if ! fetch_asset "$BOOTSTRAP_URL" "${tmp}/updaterd"; then
|
|
die "cannot fetch ${BOOTSTRAP_URL}"
|
|
fi
|
|
chmod +x "${tmp}/updaterd"
|
|
|
|
say "installing the first release (verifying signatures)"
|
|
# GITHUB_TOKEN, not DUCK_TOKEN: the engine reads that name, and it needs one for the
|
|
# same reason this script does — a private repo's API answers 404 to an unauthenticated
|
|
# caller. Exported only for this command, deliberately: nothing is written to disk, so
|
|
# the installed `updaterd` still has no credential and still cannot fetch a *later*
|
|
# update until someone adds the systemd drop-in by hand. That asymmetry is the point —
|
|
# provisioning is a person at a keyboard, an unattended update is not.
|
|
# `--force` only on the forced path, where the daemons have just been stopped. updaterd
|
|
# verifies that itself — it refuses --force while robotd still answers — so this cannot
|
|
# quietly swap a release under a running robot.
|
|
force_flag=""
|
|
if [ -n "$FORCE_REINSTALL" ]; then
|
|
force_flag="--force"
|
|
fi
|
|
|
|
# shellcheck disable=SC2086 # unquoted so an empty force_flag passes no argument at all
|
|
GITHUB_TOKEN="$TOKEN" "${tmp}/updaterd" install \
|
|
--config "${CONFIG_DIR}/updater.toml" $force_flag
|
|
|
|
if [ ! -L "${INSTALL_DIR}/current" ]; then
|
|
die "the install reported success but nothing is live"
|
|
fi
|
|
|
|
# Close the loop on the one unverified download. The installed binary came out of a
|
|
# signature-verified artifact; if the bootstrap binary matches it byte for byte, the
|
|
# bootstrap binary was genuine too.
|
|
boot_sum="$(sha256sum "${tmp}/updaterd" | cut -d' ' -f1)"
|
|
installed_sum="$(sha256sum "${INSTALL_DIR}/current/bin/updaterd" | cut -d' ' -f1)"
|
|
if [ "$boot_sum" != "$installed_sum" ]; then
|
|
die "the bootstrap binary does not match bin/updaterd in the verified release.
|
|
bootstrap: ${boot_sum}
|
|
installed: ${installed_sum}
|
|
The installed release is signed and safe, but the binary that installed it was not the
|
|
one this release contains. Treat that as a compromised download and investigate."
|
|
fi
|
|
say "bootstrap binary verified against the signed release"
|
|
|
|
rm -rf "$tmp"
|
|
trap - EXIT INT TERM
|
|
}
|
|
|
|
# The `robot` group must exist before either unit starts: both declare `Group=robot`, and
|
|
# that is what makes their 0660 sockets mean "the robot group" rather than "root only".
|
|
# systemd fails the unit outright if the group is missing.
|
|
#
|
|
# Taken from the installed release rather than from the repository, so it is the copy a
|
|
# signature was checked against.
|
|
create_group() {
|
|
say "creating the robot group and the service accounts"
|
|
|
|
# Every sysusers file the release ships, read from the directory rather than named one by
|
|
# one. `hooks/postinstall` already installs them this way on update, and the two lists
|
|
# drifting apart is precisely how a new daemon's account arrives on updated boards and not
|
|
# on freshly provisioned ones — which is the harder failure to find, because the fresh board
|
|
# is the one nobody suspects.
|
|
if [ -d "${INSTALL_DIR}/current/systemd/sysusers.d" ]; then
|
|
mkdir -p /usr/lib/sysusers.d
|
|
for src in "${INSTALL_DIR}"/current/systemd/sysusers.d/*.conf; do
|
|
[ -f "$src" ] || continue
|
|
install -m 644 "$src" "/usr/lib/sysusers.d/$(basename "$src")"
|
|
done
|
|
if command -v systemd-sysusers >/dev/null 2>&1; then
|
|
systemd-sysusers
|
|
fi
|
|
fi
|
|
|
|
# The accounts those units name, for a board where systemd-sysusers is not available. Both
|
|
# daemons run unprivileged for reasons that matter — btd parses bytes from anyone in radio
|
|
# range, padd is meant to have no privileged access to the robot — and a unit naming a
|
|
# missing `User=` fails to start with an error that reads as a broken daemon.
|
|
#
|
|
# Only when the release actually ships the service. Creating a system account for something
|
|
# that does not exist on this board is not harmful, but it is a lie about what is installed,
|
|
# and the next person reading /etc/passwd should not have to work out which.
|
|
for daemon in btd padd netpadd autod; do
|
|
[ -f "${INSTALL_DIR}/current/systemd/${daemon}.service" ] || continue
|
|
if ! getent passwd "$daemon" >/dev/null; then
|
|
useradd --system --no-create-home --shell /usr/sbin/nologin "$daemon" \
|
|
|| warn "could not create the ${daemon} user; ${daemon}.service will not start"
|
|
fi
|
|
done
|
|
|
|
if ! getent group robot >/dev/null; then
|
|
groupadd --system robot
|
|
fi
|
|
if ! getent group robot >/dev/null; then
|
|
die "the robot group could not be created; updaterd.service will not start without it"
|
|
fi
|
|
|
|
add_operator_to_group
|
|
}
|
|
|
|
# Put the person doing the install in the `robot` group.
|
|
#
|
|
# The socket is mode 0660, root:robot, and `Group=robot` in the unit is load-bearing for
|
|
# exactly this reason: group membership is how a non-root client reaches robotd. But the group
|
|
# was only ever created, never populated — so on every board provisioned so far, no
|
|
# unprivileged user could talk to the robot at all:
|
|
#
|
|
# $ robotctl health
|
|
# error: cannot reach robotd at /run/robotd.sock: Permission denied (os error 13)
|
|
#
|
|
# which reads like a crashed daemon rather than a missing group.
|
|
#
|
|
# Read-only access, not a privilege grant: mutations are refused to non-root peers regardless
|
|
# of group, so this permits asking and not commanding.
|
|
add_operator_to_group() {
|
|
# The human who ran sudo, not `whoami` — that is root, which is already able to connect
|
|
# and would make this a silent no-op.
|
|
operator="${SUDO_USER:-}"
|
|
if [ -z "$operator" ] || [ "$operator" = root ]; then
|
|
return 0
|
|
fi
|
|
|
|
if id -nG "$operator" 2>/dev/null | tr ' ' '\n' | grep -qx robot; then
|
|
return 0
|
|
fi
|
|
|
|
if usermod -aG robot "$operator"; then
|
|
say "added ${operator} to the robot group"
|
|
# Deliberately not a `warn`, and it does not say "log out". A process's group set is
|
|
# fixed at exec and there is no API to add to another process's — not even for root —
|
|
# so the shell that launched this install can never be fixed from inside it. What can
|
|
# be fixed is the size of the remaining step: `newgrp` is one command in that same
|
|
# shell instead of dropping an SSH session and coming back. `report` repeats it,
|
|
# because by then this line has scrolled past a release download.
|
|
group_pending=1
|
|
else
|
|
warn "could not add ${operator} to the robot group; robotctl will need sudo"
|
|
fi
|
|
}
|
|
|
|
# Make this a developer board: trust the dev key, and allow dev-signed releases.
|
|
#
|
|
# Both halves are needed and they are independent checks in the updater — a trusted key only
|
|
# counts as a dev key if its filename ends `.dev.pub`, and a dev key is only honoured when
|
|
# `allow_dev_keys` is on. Doing one without the other silently produces a board that still
|
|
# refuses branch builds, with a signature error that reads like a corrupt release.
|
|
install_dev_key() {
|
|
[ -n "$DEV_KEY" ] || return 0
|
|
|
|
[ -f "$DEV_KEY" ] || die "DUCK_DEV_KEY=${DEV_KEY} is not a readable file.
|
|
Pass the *public* half — team.dev.pub. If you only have the secret key:
|
|
minisign -R -s <secret> -p team.dev.pub"
|
|
|
|
# Checked here rather than discovered at verification time, where the error names the
|
|
# release and not the key, and sends you looking at the wrong thing.
|
|
if ! head -1 "$DEV_KEY" | grep -q 'untrusted comment:'; then
|
|
die "${DEV_KEY} does not look like a minisign public key.
|
|
Expected a two-line file beginning 'untrusted comment:'. A secret key or a signature
|
|
will be accepted by this file copy and then fail every verification."
|
|
fi
|
|
|
|
config="${CONFIG_DIR}/updater.toml"
|
|
if ! grep -q '^allow_dev_keys' "$config"; then
|
|
die "${config} has no allow_dev_keys setting to enable.
|
|
It is a top-level key, so it cannot be safely appended — a line added at the end would
|
|
land inside whichever [table] comes last. Add it by hand near trusted_keys_dir."
|
|
fi
|
|
|
|
# The filename is load-bearing, so it is ours to choose rather than the caller's: a key
|
|
# installed under any other name is classified as a *release* key, and branch builds
|
|
# would then be trusted as though they had been reviewed.
|
|
install -m 644 "$DEV_KEY" "${KEYS_DIR}/team.dev.pub"
|
|
sed -i 's/^allow_dev_keys.*/allow_dev_keys = true/' "$config"
|
|
|
|
say "dev mode: trusting team.dev.pub and allowing dev-signed releases"
|
|
warn "this board will now install any branch build anyone on the team pushes, without
|
|
review. Never do this to a robot you ship. To undo:
|
|
sudo rm ${KEYS_DIR}/team.dev.pub
|
|
sudo sed -i 's/^allow_dev_keys.*/allow_dev_keys = false/' ${config}
|
|
sudo systemctl restart updaterd"
|
|
}
|
|
|
|
# The units live inside the release, so this can only run after the release is installed.
|
|
# They are *copied* rather than symlinked through `current`: a unit file read through the
|
|
# symlink would change under systemd's feet on every update, and after a rollback
|
|
# systemd's view of the world would depend on which release happened to be live at the
|
|
# last daemon-reload.
|
|
# What `DUCK_NO_START` does instead of enabling a unit.
|
|
#
|
|
# `disable --now`, not merely "skip the enable". A board being re-installed is already running
|
|
# these from last time, and skipping the enable would leave every one of them up while this script
|
|
# printed that nothing was enabled or running — which is worse than not having the knob, because
|
|
# the measurement it exists for would be taken against a board that looks quiet and is not.
|
|
#
|
|
# Failure is ignored: a unit that was never enabled is exactly the state being asked for.
|
|
stop_instead() {
|
|
say "not enabling ${1}, and stopping it if it was running (DUCK_NO_START)"
|
|
systemctl disable --now "$1" 2>/dev/null || true
|
|
}
|
|
|
|
# Undo what the release's own postinstall hook did, when this install is meant to start nothing.
|
|
#
|
|
# `hooks/postinstall`, inside the release `bootstrap_first_release` installs, does
|
|
# `systemctl enable --now` on every unit the release ships — and that runs *before* `install_units`
|
|
# here. So skipping the enables below is not enough on a fresh board either: all five are already
|
|
# up by the time this script gets a say.
|
|
#
|
|
# They do still run for a few seconds, which no knob in this script can prevent, so `report` tells
|
|
# you to reboot. A daemon does not undo what it pushed to a subsystem when it dies.
|
|
quiet_the_release_units() {
|
|
[ -n "$NO_START" ] || return 0
|
|
say "DUCK_NO_START: undoing the enables hooks/postinstall just did"
|
|
for unit in autod.service mapd.service padd.service netpadd.service tofd.service nfcd.service btd.service configd.service robotd.service updaterd.service; do
|
|
[ -f "${UNIT_DIR}/${unit}" ] || continue
|
|
stop_instead "$unit"
|
|
done
|
|
}
|
|
|
|
# `systemctl enable --now`, unless this install is meant to start nothing.
|
|
#
|
|
# Returns success in that case, so a caller's `|| warn` does not fire about a unit that was never
|
|
# meant to run.
|
|
enable_unit() {
|
|
if [ -n "$NO_START" ]; then
|
|
stop_instead "$1"
|
|
return 0
|
|
fi
|
|
systemctl enable --now "$1"
|
|
}
|
|
|
|
# The same, for a unit enabled without being started — see `robot-boot-check.timer`.
|
|
enable_at_boot() {
|
|
if [ -n "$NO_START" ]; then
|
|
stop_instead "$1"
|
|
return 0
|
|
fi
|
|
systemctl enable "$1"
|
|
}
|
|
|
|
install_units() {
|
|
say "installing systemd units"
|
|
unit_src="${INSTALL_DIR}/current/systemd"
|
|
|
|
# Two are required, because without them the board is neither a robot nor able to become
|
|
# one. Everything else is whatever the release happens to ship.
|
|
for unit in updaterd.service robotd.service; do
|
|
if [ ! -f "${unit_src}/${unit}" ]; then
|
|
die "the installed release has no systemd/${unit}.
|
|
That is the release, not this script: $(readlink "${INSTALL_DIR}/current" 2>/dev/null)
|
|
carries no such unit, and a robot without it has nothing to run."
|
|
fi
|
|
done
|
|
|
|
# Read the directory rather than assert a list. A hardcoded set makes this script fail on
|
|
# any release that is not exactly its contemporary — which is every fresh install, because
|
|
# the scripts come from a branch and the release is the last stable one. `configd.service`
|
|
# was the case that proved it: added on main, absent from 0.2.0, and provisioning died at
|
|
# "the installed release has no systemd/configd.service" on a board that was fine.
|
|
#
|
|
# The release is the authority on what it contains. This script's job is to install it.
|
|
shipped=""
|
|
for src in "${unit_src}"/*.service "${unit_src}"/*.timer; do
|
|
[ -f "$src" ] || continue
|
|
unit="$(basename "$src")"
|
|
install -m 644 "$src" "${UNIT_DIR}/${unit}"
|
|
shipped="${shipped} ${unit}"
|
|
done
|
|
say "units from the release:${shipped}"
|
|
|
|
# journald persistence, so the logs from an incident outlive the reboot that followed
|
|
# it. See docs/deploy.md in the release for the Armbian tmpfs caveat this does not
|
|
# solve on its own.
|
|
src="${INSTALL_DIR}/current/deploy/journald.conf.d/10-robot.conf"
|
|
if [ -f "$src" ]; then
|
|
mkdir -p /etc/systemd/journald.conf.d
|
|
install -m 644 "$src" /etc/systemd/journald.conf.d/10-robot.conf
|
|
systemctl restart systemd-journald || warn "could not restart systemd-journald"
|
|
else
|
|
warn "the release carries no journald drop-in; logs may not survive a reboot"
|
|
fi
|
|
|
|
# `robotctl` on PATH, through `current` so it follows the active release. A symlink on
|
|
# purpose here: it is a tool an operator invokes, not a file systemd caches.
|
|
ln -sfn "${INSTALL_DIR}/current/bin/robotctl" /usr/local/bin/robotctl
|
|
|
|
# The recovery scripts on root's PATH, and *copied* — the opposite decision to `robotctl` above,
|
|
# for the same reason the units are copied. They exist for boards whose release cannot start, so
|
|
# reading them through `current` would route the recovery through the thing being recovered.
|
|
#
|
|
# Absent from releases predating them, which is every release on a first install from a branch.
|
|
for script in robot-rescue robot-boot-check; do
|
|
src="${INSTALL_DIR}/current/scripts/${script}"
|
|
if [ -f "$src" ]; then
|
|
mkdir -p /usr/local/sbin
|
|
install -m 755 "$src" "/usr/local/sbin/${script}"
|
|
else
|
|
warn "the release carries no scripts/${script}; a board whose daemons cannot start
|
|
has less recovery than it should. The next update installs it."
|
|
fi
|
|
done
|
|
|
|
# The login-shell files: the `robotctl` completions, the motd banner, and the robot's name in
|
|
# the prompt.
|
|
#
|
|
# Run from the installed release rather than written here, like the sysusers files above: it is
|
|
# the copy a signature was checked against, and it is the same file `hooks/postinstall` runs on
|
|
# every update. That second caller is the point — a step only this script performs reaches no
|
|
# board that was provisioned before it was written (`docs/design/updater-design.md` §9.1), and
|
|
# anything added here must go in that script rather than in a function beside this call.
|
|
setup_login="${INSTALL_DIR}/current/scripts/setup-login.sh"
|
|
if [ -f "$setup_login" ]; then
|
|
sh "$setup_login" || warn "the login-shell files did not install; the prompt, the banner
|
|
and the completions are all cosmetic and the robot is unaffected."
|
|
else
|
|
warn "the release carries no scripts/setup-login.sh, so the prompt will not name this
|
|
robot. The next update installs it."
|
|
fi
|
|
|
|
# Apt off the boot path: Armbian's `@reboot` update count and the stock apt-daily timers, which
|
|
# together pin a core for seconds while robotd is starting and produce nothing a robot reads.
|
|
# Same shape as setup-login.sh above, for the same §9.1 reason: the hook runs it too.
|
|
setup_quiet_boot="${INSTALL_DIR}/current/scripts/setup-quiet-boot.sh"
|
|
if [ -f "$setup_quiet_boot" ]; then
|
|
sh "$setup_quiet_boot" || warn "could not take apt off the boot path; boot is slower and
|
|
noisier than it needs to be, and the robot is unaffected."
|
|
else
|
|
warn "the release carries no scripts/setup-quiet-boot.sh; Armbian keeps running a simulated
|
|
apt upgrade at every boot. The next update installs it."
|
|
fi
|
|
|
|
systemctl daemon-reload
|
|
enable_unit updaterd.service
|
|
enable_unit robotd.service
|
|
|
|
# configd before btd: btd asks configd for the pairing PIN, and a btd that starts first
|
|
# simply refuses to pair until configd answers. Ordering here saves a confusing first boot
|
|
# rather than being required — btd retries.
|
|
#
|
|
# Both `if`-guarded, because a release older than this script does not carry them and the
|
|
# right response to that is to install what there is, not to refuse.
|
|
if [ -f "${UNIT_DIR}/configd.service" ]; then
|
|
enable_unit configd.service
|
|
fi
|
|
# btd is allowed to fail without failing the install. It needs a Bluetooth adapter, and on
|
|
# this board hci0 does not exist until ~73s after boot; a robot with no working radio is
|
|
# still a robot that updates and walks.
|
|
if [ -f "${UNIT_DIR}/btd.service" ]; then
|
|
enable_unit btd.service || warn "btd did not start; check:
|
|
journalctl -u btd -b
|
|
The robot works without it — only the phone path is unavailable."
|
|
fi
|
|
|
|
# padd waits for a gamepad and drives when one connects, so it is safe to have running with
|
|
# no pad paired: it sends nothing, and robotd's deadman holds the robot. Enabling it here is
|
|
# what makes `robotctl pad pair` the only step between a board and driving it.
|
|
#
|
|
# Allowed to fail like btd. It needs the `padd` user and the `input` group, and a robot that
|
|
# cannot read a gamepad is still a robot that updates and walks.
|
|
if [ -f "${UNIT_DIR}/padd.service" ]; then
|
|
enable_unit padd.service || warn "padd did not start; check:
|
|
journalctl -u padd -b
|
|
The robot works without it — only the gamepad is unavailable."
|
|
fi
|
|
|
|
# mediad last of the daemons, since it forwards calls to three of the ones above and its unit
|
|
# says `After=` them. It is safe to have running with nobody connected — `webrtcsink` listens
|
|
# and the pipeline sits at PLAYING.
|
|
#
|
|
# Allowed to fail like btd and padd, and for a sharper reason than either: it streams the
|
|
# camera by default (`[media] camera` in robotd.toml) and it needs the GStreamer stack
|
|
# `setup-gstreamer.sh` installs. A board missing either has no WebRTC gateway and is still a
|
|
# robot that updates, walks and pairs.
|
|
if [ -f "${UNIT_DIR}/mediad.service" ]; then
|
|
enable_unit mediad.service || warn "mediad did not start; check:
|
|
journalctl -u mediad -b
|
|
A board with no camera, or provisioned before the GStreamer stack existed, is the usual cause:
|
|
sudo /usr/local/sbin/robot-setup-gstreamer # the stack
|
|
sudo robotctl configure # [media] camera off, for no camera
|
|
The robot works without it — only the camera and the WebRTC console are unavailable."
|
|
fi
|
|
|
|
# The boot-time recovery net: three minutes into each boot, ask whether this release brought
|
|
# its daemons up, and fall back to golden if it did not.
|
|
#
|
|
# `enable`, deliberately **without** `--now`. An `OnBootSec=` timer started later than its
|
|
# deadline fires at once, and "at once" here is the middle of provisioning — daemons still being
|
|
# started by the lines above, on a board that has no golden yet anyway. It is a boot check, so
|
|
# the first boot it should apply to is the next one.
|
|
#
|
|
# `robot-boot-check.service` is not enabled and must not be: it carries no `[Install]` section
|
|
# precisely so that nothing enables it, and the timer is what starts it.
|
|
if [ -f "${UNIT_DIR}/robot-boot-check.timer" ]; then
|
|
enable_at_boot robot-boot-check.timer || warn "the boot recovery timer did not enable;
|
|
a release whose daemons cannot start will need robot-rescue by hand."
|
|
fi
|
|
|
|
# Anything the release ships that this script does not know how to start. Reported rather
|
|
# than started blindly: a unit may be a template, or something another unit pulls in, and
|
|
# guessing is how a robot ends up running a service nobody chose. Named, so adding a daemon
|
|
# is one line here and never a silent omission.
|
|
for unit in $shipped; do
|
|
case "$unit" in
|
|
updaterd.service|robotd.service|configd.service|btd.service|padd.service) ;;
|
|
# Enabled by postinstall beside padd; its ExecCondition decides which of the two runs.
|
|
netpadd.service) ;;
|
|
mediad.service) ;;
|
|
duck-gateway.service) ;;
|
|
# No `enable_unit` of its own, unlike the three above: `postinstall` enabled every
|
|
# unit carrying an `[Install]` section a step earlier, and nothing depends on this
|
|
# one — `robotd` does not read depth and `monitor` says "no depth stream" and
|
|
# carries on. Naming it here is what stops that being reported as a daemon this
|
|
# script forgot, which is how it read on every fresh install.
|
|
tofd.service) ;;
|
|
# Likewise: enabled by postinstall, and nothing waits on it — no reader is a log line.
|
|
nfcd.service) ;;
|
|
# Likewise: a client of robotd and tofd that reconnects to both on its own, and
|
|
# nothing waits on the map.
|
|
mapd.service) ;;
|
|
# The same: postinstall enabled it, and it idles unless `[autonomous] enabled`, so
|
|
# there is nothing to start here and nothing that fails without it.
|
|
autod.service) ;;
|
|
robot-boot-check.timer) ;;
|
|
# Started by its timer, never enabled. See above.
|
|
robot-boot-check.service) ;;
|
|
*) warn "${unit} was installed but not enabled — this script does not know where
|
|
it belongs in the start order. Add it to install_units, or start it by hand." ;;
|
|
esac
|
|
done
|
|
}
|
|
|
|
|
|
verify_install() {
|
|
say "verifying"
|
|
|
|
# The same list release.yml asserts on, checked here through the symlink the units
|
|
# actually resolve — an artifact can be complete and still be installed wrong.
|
|
for required in bin/updaterd bin/robotd bin/robotctl version.toml; do
|
|
if [ ! -e "${INSTALL_DIR}/current/${required}" ]; then
|
|
die "the installed release is missing ${required}"
|
|
fi
|
|
done
|
|
|
|
# Nothing was started, so every check below would report a failure that was asked for.
|
|
if [ -n "$NO_START" ]; then
|
|
say "nothing enabled or started (DUCK_NO_START); skipping the daemon checks"
|
|
return 0
|
|
fi
|
|
|
|
failed=0
|
|
for unit in updaterd robotd; do
|
|
if systemctl is-active --quiet "$unit"; then
|
|
printf ' %-10s active\n' "$unit"
|
|
else
|
|
printf ' %-10s NOT active\n' "$unit"
|
|
failed=1
|
|
fi
|
|
done
|
|
|
|
if [ "$failed" != 0 ]; then
|
|
die "a unit did not come up. Look at:
|
|
journalctl -u updaterd -b --no-pager
|
|
journalctl -u robotd -b --no-pager"
|
|
fi
|
|
|
|
# Ask the robot what it is running, which is also the first thing to ask for in any
|
|
# support report. Non-fatal: a daemon that is active but not yet answering is a timing
|
|
# artefact, not a failed install.
|
|
robotctl version || warn "robotctl could not reach the daemons yet"
|
|
|
|
# And ask whether it is actually *working*, which `is-active` cannot tell you.
|
|
#
|
|
# robotd stays active with no motor bus: it logs the failure, keeps serving its socket,
|
|
# and reports unhealthy. Before this, a board with no servos wired produced a completely
|
|
# green install of a daemon that could not see a robot.
|
|
#
|
|
# Non-fatal on purpose. A bench board with no motors attached is a legitimate state — it
|
|
# is the right thing to test the update system against — so this reports rather than
|
|
# refuses. The exit code is swallowed deliberately.
|
|
if robotctl health; then
|
|
:
|
|
else
|
|
warn "robotd is up but not healthy. That is the honest answer, not necessarily a
|
|
failed install — a bench board reports exactly this until its servos are powered, and
|
|
the reason above says which. robotd keeps retrying, so powering the servos brings it up
|
|
without reinstalling or restarting anything. Look at:
|
|
journalctl -u robotd -b --no-pager"
|
|
fi
|
|
}
|
|
|
|
report() {
|
|
version="$(readlink "${INSTALL_DIR}/current" | sed 's|releases/||')"
|
|
say "installed daemon ${version}"
|
|
|
|
if [ -n "$NO_START" ]; then
|
|
warn "DUCK_NO_START was set: the release and its units are installed and NOTHING is
|
|
enabled, now or at the next boot. This board is not a working robot until:
|
|
sudo systemctl enable --now updaterd robotd configd btd padd autod
|
|
|
|
REBOOT BEFORE MEASURING ANYTHING. The release's own hooks/postinstall enabled and started
|
|
every daemon before this script could stop them, so they have run on this boot. A daemon does
|
|
not undo what it pushed to a subsystem when it dies — btd leaves Pairable set, an advertising
|
|
instance, and the IO capability its default pairing agent gave the adapter:
|
|
sudo reboot"
|
|
fi
|
|
|
|
# Before the command list, not after: every command below fails with "Permission denied"
|
|
# in the shell reading this, and that is what a first-time operator reasonably reads as a
|
|
# broken install. Naming the one step between them and a working robot is worth more than
|
|
# keeping the happy path uncluttered.
|
|
if [ "$group_pending" = 1 ]; then
|
|
cat <<'EOF'
|
|
|
|
FIRST, in this same shell:
|
|
|
|
newgrp robot
|
|
|
|
You were just added to the `robot` group, and a process's groups are fixed when it starts —
|
|
so this shell is not in it yet and both sockets will refuse it. `newgrp` starts a shell that
|
|
is, which is one command instead of a logout. Any new login has it already, and
|
|
`sudo robotctl …` works either way.
|
|
EOF
|
|
fi
|
|
|
|
cat <<'EOF'
|
|
|
|
robotctl health the whole robot: hardware and software
|
|
robotctl version what is running, and what is installed
|
|
robotctl update status update state per component
|
|
robotctl update check is a newer release available
|
|
sudo robotctl update apply daemon update now (mutations are root-only by design)
|
|
sudo robotctl pad pair pair a gamepad, then drive it — that is the only step
|
|
|
|
This robot polls for updates on its own and will apply a *mandatory* release without
|
|
waiting to be asked. Ordinary releases wait for a client.
|
|
EOF
|
|
|
|
# Claimed only if there was somewhere to write it — an image without bash-completion
|
|
# gets no completions and must not be told otherwise.
|
|
if [ -f /usr/share/bash-completion/completions/robotctl ]; then
|
|
printf '\nTab-completion is installed; open a new shell to pick it up.\n'
|
|
fi
|
|
|
|
# Only on a board that is actually in dev mode. Printing it everywhere would advertise a
|
|
# capability most boards correctly refuse, and the failure then looks like a broken
|
|
# release rather than a board that was never meant to take one.
|
|
if [ -f "${KEYS_DIR}/team.dev.pub" ]; then
|
|
cat <<'EOF'
|
|
|
|
DEV BOARD: trusts team.dev.pub and accepts dev-signed branch builds.
|
|
|
|
sudo robotctl update apply daemon --ref BRANCH install what a branch last built
|
|
EOF
|
|
fi
|
|
}
|
|
|
|
|
|
# The motor bus, checked but never configured here.
|
|
#
|
|
# Board bring-up is `setup-board.sh`'s job — device-tree overlays need a reboot and belong to
|
|
# the board, not to a daemon release. But installing a robot daemon onto a board with no bus
|
|
# is worth saying out loud: the install will succeed, `robotd` will start, fail to open the
|
|
# bus, and report unhealthy. That is honest behaviour, and an easy thing to stare past.
|
|
MOTOR_PORT="${MOTOR_PORT:-/dev/ttyS2}"
|
|
|
|
check_board() {
|
|
if [ -e "$MOTOR_PORT" ]; then
|
|
# Existing is not the same as usable. Armbian runs a login console on this UART by
|
|
# default, and a getty *reads* the port — so it eats servo replies and every motor
|
|
# looks absent. Identical symptoms to unwired hardware, and far harder to guess.
|
|
tty="$(basename "$MOTOR_PORT")"
|
|
if systemctl is-active --quiet "serial-getty@${tty}.service" 2>/dev/null; then
|
|
warn "a login console (serial-getty@${tty}) is running on ${MOTOR_PORT}.
|
|
It will consume servo replies and robotd will report every motor missing. Run
|
|
scripts/setup-board.sh, which masks it."
|
|
fi
|
|
return 0
|
|
fi
|
|
warn "${MOTOR_PORT} does not exist, so robotd will have no motor bus.
|
|
Run scripts/setup-board.sh (then reboot) to enable it. Installing anyway: the update
|
|
system is worth testing on a board whose bus is not wired yet, and robotd reports itself
|
|
unhealthy rather than pretending."
|
|
}
|
|
|
|
# Let `updaterd` fetch updates on a *developer's* board.
|
|
#
|
|
# Only when a token was supplied, and never on a customer robot: those install from a public
|
|
# artifact repository and pass no token, so they never reach this path. A fleet-wide
|
|
# credential baked into an image is one that leaks and cannot be rotated without reflashing —
|
|
# the failure the tiered signing keys exist to avoid (deploy/README.md).
|
|
#
|
|
# Without this, `updaterd` is installed, running, and unable to fetch a single update — which
|
|
# is most of what it is for.
|
|
install_token_dropin() {
|
|
if [ -z "$TOKEN" ]; then
|
|
say "no token supplied; updaterd will not be able to fetch updates"
|
|
return 0
|
|
fi
|
|
|
|
dir=/etc/systemd/system/updaterd.service.d
|
|
mkdir -p "$dir"
|
|
# Restrictive umask before the write, not chmod after: a drop-in is world-readable by
|
|
# default, and this one holds a credential from the moment it exists.
|
|
(
|
|
umask 077
|
|
printf '[Service]\nEnvironment=GITHUB_TOKEN=%s\n' "$TOKEN" > "${dir}/token.conf"
|
|
)
|
|
systemctl daemon-reload
|
|
# `daemon-reload` re-reads unit files; it does not restart anything. Without this the
|
|
# drop-in exists on disk and the *running* updaterd still has no GITHUB_TOKEN, so every
|
|
# later check 404s against a private repo — silently, on a timer, forever. The units are
|
|
# started before this function runs, so this was not a corner case: it was every board.
|
|
#
|
|
# `try-restart`, not `restart`: if updaterd is not running, starting it is
|
|
# `install_units`' job and doing it here would hide a failure there.
|
|
systemctl try-restart updaterd.service || warn "could not restart updaterd"
|
|
say "wrote ${dir}/token.conf (mode 600) so updaterd can fetch updates"
|
|
warn "that file holds a GitHub token in plaintext. Fine on a developer's board, not on a
|
|
robot you ship. It is why artifact hosting is still open — docs/design/updater-design.md §6.1."
|
|
}
|
|
|
|
# Refuse a board name robotd would refuse, before anything is downloaded: an unknown value in
|
|
# `[board] version` is a type error, and a robotd that will not parse its file does not start.
|
|
# The names are `robotd_params::board::BOARD_LABELS`.
|
|
check_board_name() {
|
|
case "$BOARD" in
|
|
""|zero3|beta|face-board-v1) ;;
|
|
*) die "DUCK_BOARD=${BOARD} is not a board: zero3, beta or face-board-v1" ;;
|
|
esac
|
|
}
|
|
|
|
# Write the board into robotd.toml, whatever state the file is in: just fetched from a release
|
|
# whose template has a commented `[board]`, fetched from one that predates the section, or kept
|
|
# from an earlier install. `version` is the only key of that name in the file, so it is matched
|
|
# on its own, commented or not.
|
|
declare_board() {
|
|
[ -n "$BOARD" ] || return 0
|
|
file="${CONFIG_DIR}/robotd.toml"
|
|
if grep -Eq '^#? *version = "' "$file"; then
|
|
sed -i -E "s|^#? *version = \".*\"|version = \"${BOARD}\"|" "$file"
|
|
elif grep -q '^\[board\]' "$file"; then
|
|
awk -v board="$BOARD" '{ print } /^\[board\]$/ { print "version = \"" board "\"" }' \
|
|
"$file" > "${file}.new"
|
|
mv "${file}.new" "$file"
|
|
else
|
|
printf '\n[board]\nversion = "%s"\n' "$BOARD" >> "$file"
|
|
fi
|
|
say "declared this board a ${BOARD} in ${file}"
|
|
}
|
|
|
|
main() {
|
|
check_board_name
|
|
check_environment
|
|
check_board
|
|
wait_for_clock
|
|
# Before install_config, which needs to know which release it is pairing a config with.
|
|
resolve_bootstrap_asset
|
|
install_config
|
|
install_dev_key
|
|
bootstrap_first_release
|
|
# Straight after, not at install_units: the release's postinstall hook has already enabled and
|
|
# started everything by this point.
|
|
quiet_the_release_units
|
|
create_group
|
|
install_units
|
|
install_token_dropin
|
|
verify_install
|
|
report
|
|
}
|
|
|
|
# Called on the last line so a truncated download — the real failure mode of
|
|
# `curl | sh` — defines functions and then does nothing, rather than running half an
|
|
# install.
|
|
main "$@"
|