Skip to content

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, as image-prod and image-test-prod do. Any other image can inherit tolomeo_users directly.
  • mkpasswd on the build host — provided by the devcontainer, or the whois package 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:

mkpasswd -m sha256crypt

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:

env:
  SYS_USER_PASSWORD_SERVICE: null

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:

export SYS_USER_PASSWORD_SERVICE='$5$<salt>$<hash>'

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:

TLM_USER_PASSWORD[service] = "$5$<salt>$<hash>"

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:

DISABLE_ROOT = "1"

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:

hash="$(mkpasswd -m sha256crypt)"
printf '@b64@%s\n' "$(printf '%s' "$hash" | base64 -w0)"

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 development or production-test request, as ... is not available for this combination;
  • a production request 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 every devel job;
  • the kas env: entry for SYS_USER_PASSWORD_<ACCOUNT>;
  • for production images, a SYS_USER_PASSWORD_<ACCOUNT> variable scoped to production-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