Skip to content

feat: allow device registration by provisioning key - #91

Draft
otavio wants to merge 4 commits into
masterfrom
provisioning-key
Draft

otavio wants to merge 4 commits into
masterfrom
provisioning-key

Conversation

@otavio

@otavio otavio commented Nov 16, 2026

Copy link
Copy Markdown
Member

Supersedes #89. That PR emits INSTALL_KEY, which shellhub renamed to PROVISIONING_KEY before the feature first shipped in v0.27.0 (shellhub 247164fa4). No release reads INSTALL_KEY: an agent given only that variable ignores it and boots into pairing mode. This branch carries #89's three commits with the rename applied and bumps the agent from v0.26.0, which has no key support, to v0.30.4.

Summary

 recipes-core/shellhub/
-├── shellhub-agent_0.26.0.bb          SRCREV 34c91084 (v0.26.0)
+├── shellhub-agent_0.30.4.bb          SRCREV 8e2fb5ee (v0.30.4)
 ├── shellhub-agent-config_1.0.bb
+│     SHELLHUB_PROVISIONING_KEY       mutually exclusive with SHELLHUB_TENANT_ID
 └── shellhub-agent/shellhub-agent.initd
+      export PROVISIONING_KEY         sysvinit otherwise drops it
 classes/shellhub-rootfs-postcommand.bbclass
-  shellhub_override_tenant_id         rewrites TENANT_ID only
+  shellhub_override_registration     rewrites either line, from
+                                      SHELLHUB_ROOTFS_PROVISIONING_KEY or _TENANT_ID

/etc/default/shellhub-agent carries exactly one credential line:

SERVER_ADDRESS="…"
PRIVATE_KEY="…"
PROVISIONING_KEY="…"     or     TENANT_ID="…"

Evidence

  • Agent v0.30.4, built with Go 1.26.10 and GOTOOLCHAIN=local, started with an unprefixed variable:
    Before: INSTALL_KEY=k starts with no credential and no warning.
    After: PROVISIONING_KEY=k is read as the namespace credential.
    The same tree under Go 1.25 fails with go.mod requires go >= 1.26.10.

  • oelint-adv (contrib/oelint/run-oelint.sh): clean.

  • Rootfs override: I extracted the function from the class and ran it under sh -e against sample config files:

    Provisioning key Tenant Config line Result
    k&%1 sentinel TENANT_ID PROVISIONING_KEY="k&%1", mode 0644, temp file removed
    k2 empty PROVISIONING_KEY PROVISIONING_KEY="k2"
    sentinel tenant PROVISIONING_KEY TENANT_ID="tenant"
    k t TENANT_ID fails: mutually exclusive
    sentinel or empty sentinel or empty TENANT_ID fails: set one
    k sentinel none fails: no credential line
  • Not re-run since the rename: bitbake builds for qemuarm. The commit messages describe nine shellhub-agent-config configurations and seven class combinations, but those were built against Allow device registration by install key #89's INSTALL_KEY version. Re-run them before this leaves draft.

Open questions for the next owner

  • Keep the agent bump in this PR, or land it first as its own PR, as shellhub-agent: Update version 0.25.1 -> 0.26.0 #84 and shellhub-agent: Update version 0.25.1 -> 0.26.0 #85 did?
  • v0.30.4 needs Go 1.26.10. wrynose ships exactly that and oe-core master ships 1.27.3, but whinlatter (1.25.9) and styhead (1.22.12) cannot build it. Should they be dropped from LAYERSERIES_COMPAT_shellhub?
  • The agent now accepts a tenant and a key together. Keep failing the build when both are set, as team#228 decided?
  • With neither credential set, the recipe is still skipped, while the agent now pairs in that case. Should credential-less pairing images be allowed?
  • The Yocto and Buildroot docs pages still say INSTALL_KEY and need the same rename before they are published.

Merge Danger

Door: two-way

Nothing on-disk or on-wire changes beyond the config file the image ships.

Blast Radius: images

Every image built from this layer gets agent v0.30.4, a larger jump than the usual one-release bump. Layers on whinlatter or styhead stop building the agent. The rootfs function was renamed from shellhub_override_tenant_id to shellhub_override_registration, which breaks any downstream recipe that references the old name.

Refs: shellhub-io/team#228

Bump the ShellHub agent to the v0.30.4 upstream release, updating
SRCREV to the commit tagged v0.30.4. The AgentVersion ldflag tracks
${PV} automatically and the LICENSE.md checksum is unchanged.

Since v0.27.0 the agent can enroll with a namespace provisioning key
(PROVISIONING_KEY) instead of a tenant ID, and TENANT_ID is no longer
required: an agent started with neither boots into pairing mode. Both
are read unprefixed, so /etc/default/shellhub-agent can carry them.

The agent's go.mod now requires Go 1.26.10. wrynose ships exactly that
and master ships 1.27.3; whinlatter's 1.25.9 refuses the module under
GOTOOLCHAIN=local, so this version does not build there.

Built the agent at the v0.30.4 tag with Go 1.26.10 and
GOTOOLCHAIN=local, and started it with PROVISIONING_KEY, with
INSTALL_KEY and with neither set; it starts in each case, and only the
first carries a credential the agent reads.

Signed-off-by: Otavio Salvador <otavio@ossystems.com.br>
The recipe could only configure a device by tenant ID, so every unit
built from a Yocto image registered through the namespace's legacy
source. That source is seeded in manual mode, which turns a production
run into a queue of pending devices somebody has to accept by hand.
A provisioning key is what avoids that, and it also carries tags, so an
access policy can cover the batch before anybody opens the console.

Add SHELLHUB_PROVISIONING_KEY and emit PROVISIONING_KEY= into
/etc/default/shellhub-agent. The two variables are mutually exclusive
rather than a precedence pair: setting both fails the build, because an
image registering through a source the integrator did not choose is the
failure this fixes. Exactly one credential line is written, so a
provisioning-key build never ships TENANT_ID="undefined".

Both default to the "undefined" sentinel, so the guard reads the same
way for either credential, and an explicitly emptied value counts as
unset alongside it. Clearing an inherited SHELLHUB_TENANT_ID is then a
way to move to a provisioning key rather than a spurious
mutual-exclusion failure, and an empty tenant with no provisioning key
no longer slips past both guards to ship TENANT_ID="". The resolved
values are stored back so do_compile only tests for emptiness instead
of repeating the sentinel handling in shell.

The parse guard now accepts either variable. Requiring a tenant when a
provisioning key is set would force integrators to invent one to get
past the check. Tenant-only registration stays for existing
integrations, and the guard's message names the provisioning key as the
path for anything new.

Built shellhub-agent-config for qemuarm in nine configurations. Either
credential alone writes its own line, as does one paired with the other
emptied or left at the sentinel; both set fails parsing with the
mutual-exclusion message; neither set, and either or both emptied with
nothing else configured, skip the recipe with a message pointing at
SHELLHUB_PROVISIONING_KEY. oelint-adv is clean.

Implements shellhub-io/team#228

Signed-off-by: Otavio Salvador <otavio@ossystems.com.br>
The init script sources /etc/default/shellhub-agent and then re-exports
only the variables the daemon needs, so PROVISIONING_KEY stayed a plain
shell variable and never reached shellhub-agent.start's exec.
Registering by provisioning key would have worked on systemd images,
which pull the file in through EnvironmentFile=, and silently lost the
credential on sysvinit ones.

Implements shellhub-io/team#228

Signed-off-by: Otavio Salvador <otavio@ossystems.com.br>
The class could only rewrite TENANT_ID, so an image built with
SHELLHUB_PROVISIONING_KEY had no rootfs-time override at all: the sed
matched nothing and the class silently left the credential untouched.

Add SHELLHUB_ROOTFS_PROVISIONING_KEY next to SHELLHUB_ROOTFS_TENANT_ID,
with the same mutual exclusion the recipe applies. The rewrite now
matches either credential line and replaces it wholesale, so a
tenant-built image can be swapped over to a provisioning key. The
function is renamed to shellhub_override_registration since it no
longer only touches the tenant.

Both variables default to the "undefined" sentinel and treat an
explicitly emptied value as unset, matching shellhub-agent-config.
Without a default, bitbake left the literal ${SHELLHUB_ROOTFS_TENANT_ID}
in the generated task script, so the [ -z ] guard never fired and the
unexpanded text was written into the rootfs config. Guard against a
config carrying no credential line too, rather than rewriting nothing
and reporting success.

The substitution uses awk reading the credential from the environment
rather than sed, so a '&' or a '%' in the value is written literally
instead of being taken as sed syntax.

Extracted the expanded function from bitbake -e for seven variable
combinations and ran each under set -e against fixture configs built
either way. Overriding by provisioning key or by tenant rewrites the
line whichever credential the image shipped, including when the other
variable is emptied or left at the sentinel; a key containing '&' and
'%' survives verbatim; the file keeps mode 0644 and the temporary copy
is cleaned up; setting both, setting neither, emptying both, and a
config with no credential line each fail with their own message.
oelint-adv is clean.

Implements shellhub-io/team#228

Signed-off-by: Otavio Salvador <otavio@ossystems.com.br>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant