Manage User Accounts¶
This guide covers declaring the login accounts of a production image and supplying their passwords at build time,
using a service account for field-service technicians as the worked example.
Accounts are generated by the tolomeo_users class. Its variables, defaults and checks are listed in
Configuration Classes.
A production image ships two accounts by default:
| Account | Password variable | Without a password |
|---|---|---|
root |
SYS_USER_PASSWORD_ROOT |
Falls back to TLM_DEVEL_PASSWORD — no working login |
admin |
SYS_USER_PASSWORD_ADMIN |
do_rootfs fails |
Prerequisites¶
- A production image that requires
recipes-core/images/include/tolomeo-image-prod.inc, asimage-prodandimage-test-proddo. Any other image caninherit tolomeo_usersdirectly. mkpasswdon the build host — provided by the devcontainer, or thewhoispackage on Debian and Ubuntu.
Generate a Password Hash¶
Accounts take a crypt(3) hash, never a plaintext password. Run mkpasswd without a password argument: it prompts
for the password without echoing it, so the password stays out of the shell history and the process list:
The output has the form $5$<salt>$<hash>. Pass it as printed: the class escapes it for the shell. A hash already
escaped with printf "%q" is accepted too.
Add an Account¶
The steps below add a service account with /bin/sh as its shell, serial-port access through dialout, and read
access to the system journal through systemd-journal.
Declare the Account¶
TLM_USERS lists every account in the image, and TLM_USERS[<account>] defines each one except root. Set both
in your production image recipe, after the require line:
require recipes-core/images/include/tolomeo-image-prod.inc
TLM_USERS = "root admin service"
TLM_USERS[service] = "service,/bin/sh,dialout:systemd-journal"
The definition tuple has three comma-separated fields:
| Field | Example | Description |
|---|---|---|
| Primary group | service |
Group created for the account and set as its primary group |
| Shell | /bin/sh |
Login shell; empty means /bin/sh |
| Extra groups | dialout:systemd-journal |
Supplementary groups, :-separated; may be empty |
Missing groups are created. Pick a primary group name that base-passwd does not already define (such as operator or
staff), or the account joins that system group instead of getting its own.
To extend the reference image-prod without editing it, put the same lines in an image-prod.bbappend in your layer,
with TLM_USERS:append = " service" in place of the assignment.
To ship an image without admin, leave it out of the list: TLM_USERS = "root service".
Pass the Password Through kas¶
kas forwards only the environment variables it lists, one entry per account. Add the service entry to
kas/base.yml, which both kas/common.yml and kas-ci/common.yml include, so that local and CI builds both see it:
The variable name is SYS_USER_PASSWORD_ followed by the account name in upper case, with - replaced by _.
meta-tolomeo already forwards SYS_USER_PASSWORD_ROOT and SYS_USER_PASSWORD_ADMIN from
meta-tolomeo-app/kas/common.yml.
Build the Image¶
Export one hash per account, then build. Each mkpasswd call prompts for the password of the account on its line:
export SYS_USER_PASSWORD_ROOT="$(mkpasswd -m sha256crypt)"
export SYS_USER_PASSWORD_ADMIN="$(mkpasswd -m sha256crypt)"
export SYS_USER_PASSWORD_SERVICE="$(mkpasswd -m sha256crypt)"
kas build kas/<machine>_<distro>_<image>.yml
To reuse a hash generated earlier, export it in single quotes, which stop the shell from expanding its $
characters:
Verify the Account¶
Check the generated rootfs before flashing:
ROOTFS=$(ls -d build/tmp-glibc/work/*/<image>/*/rootfs)
grep '^service:' $ROOTFS/etc/passwd $ROOTFS/etc/shadow
grep 'service' $ROOTFS/etc/group
<rootfs>/etc/passwd:service:x:1001:1001::/home/service:/bin/sh
<rootfs>/etc/shadow:service:$5$<salt>$<hash>:15069:0:99999:7:::
dialout:x:20:service
systemd-journal:x:995:service
service:x:1001:
The hash in /etc/shadow matches the value of SYS_USER_PASSWORD_SERVICE.
Set a Password in Configuration¶
TLM_USER_PASSWORD[<account>] takes precedence over the environment. Use it for a fixed, non-secret credential,
such as on a test image:
Warning
A hash committed to a layer is readable by everyone with access to the layer. Supply production credentials through the environment.
Lock the Root Account¶
Set DISABLE_ROOT in the image recipe or local.conf:
root is locked whether or not it appears in TLM_USERS, and SYS_USER_PASSWORD_ROOT is ignored. Keep at least
one other account with a password, or the device has no login.
Supply Passwords in CI¶
Every CI job has a key set, YOCTO_KEY_SET, that decides where its account passwords come from. The branch flow and
the embedded manager (EM) flow, in which the EM sends a build request as pipeline variables, use the same key sets:
| Key set | Jobs | keys/ |
Password source |
|---|---|---|---|
devel (default) |
Every job except the ones below | A link to devel-keys/, as on a developer machine |
devel-keys/credentials/<account>, hashed by the CI; overrides any preset SYS_USER_PASSWORD_* |
prod |
Branch flow: build:production, build:nightly:production |
Provided by the project (meta-tolomeo: ci/provision-prod-keys.sh) |
SYS_USER_PASSWORD_<ACCOUNT> CI/CD variable, taken as is |
prod |
Branch flow: package-build:production, package-test:swu:production |
Same as above | — (no password variables) |
prod |
EM flow: build:production |
Same as above | SYS_USER_PASSWORD_<ACCOUNT> CI/CD variable, or a request override, taken as is |
prod |
EM flow: package-build:prod, package-test:swu:prod |
Same as above | — (no password variables) |
The CI hashes each plaintext devel password with mkpasswd -m sha256crypt, so the development passwords stay in
plain files and never reach a production image. In the branch flow, only build:production and
build:nightly:production receive the production variables: they build image-prod in the production-build
environment. package-build:production (environment production-signing) and package-test:swu:production use
prod for the keys/ tree only. The pipeline enforces the pairing through production-targets: image-prod:
image-prod must use prod, and no other target may.
In meta-tolomeo, ci/provision-prod-keys.sh fills keys/ for prod jobs with a private copy of devel-keys/
without credentials/.
Set the CI/CD Variables¶
GitLab cannot mask a value that contains $ and expands $… in variable values, so store the hash base64-encoded
behind an @b64@ prefix; the pipeline decodes it:
mkpasswd prompts for the password. Add the output as SYS_USER_PASSWORD_ROOT and SYS_USER_PASSWORD_ADMIN under
Settings → CI/CD → Variables with these attributes:
| Attribute | Value |
|---|---|
| Visibility | Masked and hidden |
| Flags | Protected |
| Environment scope | production-build, exactly |
The CI does not hash these values. Before BitBake starts, an image-prod build fails when a variable is missing or
empty, or when it does not decode to a crypt(3) hash. Production images build on protected refs only.
Production passwords are temporary: users change them at first login.
Build Through the Embedded Manager¶
The development and production-test flavors use the devel key set and need no password variables.
The production flavor builds image-prod in build:production with the prod key set (keys/ from
ci/provision-prod-keys.sh) on the $YOCTO_PROD_RUNNER_TAG runner. The job runs in the production-build
environment and takes SYS_USER_PASSWORD_ROOT and SYS_USER_PASSWORD_ADMIN from the CI/CD settings, set as in
Set the CI/CD Variables. The EM jobs package-build:prod (environment
production-signing) and package-test:swu:prod use prod for the keys/ tree only. The other EM jobs use devel.
A request overrides the settings by sending SYS_USER_PASSWORD_ROOT, SYS_USER_PASSWORD_ADMIN, or both as pipeline
variables in the same form: @b64@ followed by the base64 of the mkpasswd -m sha256crypt output. A value the
request does not send comes from the CI/CD settings. GitLab gives pipeline variables precedence over the CI/CD
settings. The pipeline UI shows request values unmasked, and they reach every job of that pipeline, so prefer the
CI/CD settings and override only when needed.
The request guard runs before anything builds and rejects:
- an empty override, as
SYS_USER_PASSWORD_ROOT (root_password) is set but empty; - password values on a
developmentorproduction-testrequest, as... is not available for this combination; - a
productionrequest on an unprotected ref.
A production request with no value in the settings or the request fails at the start of build:production, as does
a value that is not a crypt(3) hash.
Add an Account in CI¶
Besides the steps in Add an Account, add three things:
- the development password as
devel-keys/credentials/<account>, hashed by the CI for everydeveljob; - the kas
env:entry forSYS_USER_PASSWORD_<ACCOUNT>; - for production images, a
SYS_USER_PASSWORD_<ACCOUNT>variable scoped toproduction-build.
Every file under devel-keys/credentials/ is an account: keep nothing else there.
Troubleshooting¶
no password for enabled account 'service'¶
The account is in TLM_USERS but no hash reached BitBake. Check that SYS_USER_PASSWORD_SERVICE is exported in the
shell that runs kas, and that the kas configuration lists it under env: — kas drops variables it does not list.
has no TLM_USERS[service] definition tuple¶
Add the TLM_USERS[service] tuple next to TLM_USERS. Only root needs none.
password for account 'service' is not a crypt(3) hash¶
The variable holds a plaintext password or a mangled hash. Regenerate it with mkpasswd, or export a stored hash in
single quotes.
SYS_USER_PASSWORD_ROOT must be set for image-prod¶
The pipeline builds image-prod without the CI/CD variable: the ref is not protected, the variable is missing or
empty, or its environment scope is not exactly production-build. The same applies to any
SYS_USER_PASSWORD_<ACCOUNT>. Set it as described in Supply Passwords in CI.
SYS_USER_PASSWORD_ROOT is not a crypt(3) hash¶
The variable does not decode to a mkpasswd hash: it holds a plaintext password, or the hash lacks the @b64@
prefix or the base64 encoding. Regenerate it with the snippet in Set the CI/CD Variables.
image-prod requires YOCTO_KEY_SET=prod¶
A job builds image-prod with the devel key set, or a job for another target uses prod. The second case reads
YOCTO_KEY_SET=prod is reserved for production targets, followed by the production targets and the offending target.
Keep production-targets: image-prod and YOCTO_KEY_SET: prod on the same jobs.
The root password is rejected on a local build¶
No SYS_USER_PASSWORD_ROOT was supplied, so root received the TLM_DEVEL_PASSWORD placeholder, which matches no
password. Export a real hash and rebuild.
See also
- Configuration Classes —
tolomeo_usersvariables, password resolution order and checks - kas Configuration — which fragment forwards which environment variable
- Build Your Own BSP Layer — the integration project and its production image