Image-local users

User records live in os.users. They create accounts inside the image; they are unrelated to OpenFactory website accounts or organization roles.

Canonical shape

{
  "os": {
    "users": [
      {
        "username": "deploy",
        "full_name": "Deployment Operator",
        "groups": ["sudo"],
        "shell": "/bin/bash"
      }
    ]
  }
}

Supported fields include username, optional password, full_name, groups, shell, and a target-specific level used by Elster/Vyatta images. Older examples containing home or comment do not match the canonical model and may be ignored.

User and group names are restricted to safe Linux account characters and length. The shell must be an absolute path without whitespace or shell metacharacters.

Password behavior

Leaving password unset creates a password-locked account. That is the preferred recipe state for key-only SSH, first-boot enrollment, or deployment-time identity integration.

If a plaintext password is included, it becomes sensitive build input and may be exposed through saved recipes, logs, or exports. Do not use a real production credential in a recipe. Phone recipes must collect credentials on the device rather than baking them into the image.

Before disabling SSH password authentication, confirm an approved public key or another access method is present and tested. Otherwise a correctly hardened image can be inaccessible.

Groups and privilege

• sudo and wheel can grant administrative authority depending on the distribution.
• docker commonly grants root-equivalent control through the daemon socket.
• kvm grants access to virtualization devices where present.
• adm can expose sensitive logs.

Treat these as privileged groups and grant only what the account needs. Distribution-specific group names are not portable.

Service accounts

For a noninteractive service account, select a no-login shell available on the target and omit administrative groups. Confirm the generator and service unit preserve the intended identity; a recipe default may add sudo if groups is omitted, so provide an explicit empty group list where appropriate.

Verification

Test the exact properties that matter:

• account exists with the expected UID range;
• primary and supplementary groups are correct;
• login shell and password-lock state are correct;
• home and file ownership, if generated elsewhere, are correct;
• unauthorized sudo and service access are denied; and
• the approved login or enrollment path succeeds.

Do not infer least privilege from account creation alone.