Yocto User Creation: Make Package and Image Account Policies Agree

A service account exists in a Yocto image, but its home directory, group or numeric identity differs from what the package expects. Two declarations of the same username do not necessarily converge on one complete policy. Package installation and image-level account customization operate at different points and can make different assumptions.

Diagnose the account as a contract between the package that needs it and the image that integrates it. The behavior discussed here follows Yocto Project 5.0.12 and the examined scarthgap account classes.

Put a package requirement on the correct package

The USERADD_PACKAGES reference identifies which outputs of a recipe require account operations. A recipe inheriting useradd must set that list and provide the corresponding user, group or membership parameters.

For an illustrative sensor-agent output package, use USERADD_PACKAGES = "sensor-agent" and a matching USERADD_PARAM:sensor-agent. Its parameters can request a system account named sensor, a noninteractive shell, and a defined home path. Choose those details according to the daemon's requirements; do not borrow an arbitrary numeric UID from an unrelated example.

Check that the package named here is actually installed. A user declaration attached to an optional subpackage does not become an image-wide account guarantee. Likewise, the recipe name and the package name need not match. Inspect the generated package's pre-install script when the account is unexpectedly absent.

The useradd implementation prepares account information for recipe sysroots and attaches package-specific operations to pre-install scripts. This supports both image construction and package installation on a target. A late image-only account declaration cannot replace all of those earlier requirements.

Distinguish customization from duplicate creation

The extrausers class applies account operations at image level through EXTRA_USERS_PARAMS. Those operations belong to the image rather than following an independently installed service package.

Suppose the package declares sensor with one home path, while the image contains another useradd for sensor with a different home. Do not assume the later declaration updates the existing account. In the examined shared account helpers, account creation checks whether the name already exists and skips recreating an existing name.

That behavior can produce a successful build with the first account attributes still present. Compare the actual account record with both declarations. If the product deliberately needs to modify a package-created account, make that an explicit, reviewed modification rather than hiding it inside another creation command.

Trace the phase that introduced the difference

The extrausers implementation hooks its operations into root-filesystem postprocessing. This provides a useful diagnostic boundary: inspect the package-generated account operation, then the image customization, then the final account database.

For an unexpected primary group, compare the requested group, the final passwd entry's numeric group ID, and the matching group record. For a wrong home path, inspect both the account field and the directory the application actually uses. An account entry alone does not demonstrate that the directory exists with usable ownership and permissions.

If the image changes a UID or GID, inspect numeric ownership of packaged files and any persistent data that the next boot will reuse. A username shown by a host-side file listing is not sufficient to establish the identity encoded for the target. Treat a changed numeric identity as a migration question where persistent files are involved.

Make reuse and upgrade behavior explicit

When multiple packages need one account, choose a single coordinated definition and make their dependencies reflect that arrangement. Test a package installed independently of the original image customizations if the product supports that use case. An account available in one factory image can otherwise be missing when the package is reused elsewhere.

For reproducible numeric identities, Yocto offers static-ID tables through USERADDEXTENSION, USERADD_UID_TABLES and USERADD_GID_TABLES. Review the documented static-ID policy and rebuild state when changing that configuration; merely hardcoding a name does not fix its number.

The final comparison should be specific: the selected account definition, the package carrying its creation logic, any intentional image modifications, and the resulting target records and file ownership. That exposes competing policies without converting the service account into an unrelated interactive-login configuration.