user – Keystone Core

user

Manages a Linux user account — its UID/GID, primary group, home directory, login shell, GECOS comment, and supplementary groups. Idempotent: re-applying an unchanged declaration reports no change.

Category: System & core

States

State	Meaning
`present`	The user exists with the declared scalar fields and supplementary groups.
`absent`	The user does not exist; an existing account is removed (and its home directory too when `remove_home` is set).

Parameters

Parameter	Type	Description
`uid`	int	Numeric UID (state `present`).
`gid`	int	Numeric primary GID (state `present`). Mutually exclusive with `group`.
`group`	string	Primary group name (state `present`). Mutually exclusive with `gid`.
`home`	string	Home directory; must be an absolute path (state `present`).
`shell`	string	Login shell; must be an absolute path (state `present`).
`comment`	string	GECOS comment field (state `present`).
`groups`	list	Supplementary group names; the declared set replaces the live set (state `present`).
`system`	bool	Create the account as a system user (state `present`). Default: `false`.
`create_home`	bool	Create the home directory on account creation (state `present`). Default: `false`.
`remove_home`	bool	Delete the home directory when removing the account (state `absent` only). Default: `false`.

Examples

Create a user with a shell and supplementary groups

user:
  alice:
    state: present
    uid: 1500
    home: /home/alice
    shell: /bin/bash
    comment: Alice
    groups:
      - wheel
      - docker
    create_home: true

System user with an explicit primary group

Use group or gid for the primary group, never both.

user:
  svc-myapp:
    state: present
    system: true
    group: myapp
    home: /var/lib/myapp
    shell: /usr/sbin/nologin

Remove a user and its home directory

user:
  alice:
    state: absent
    remove_home: true

Notes

Linux only for the full Check/Apply pipeline; mutating Apply on other operating systems returns ErrUnsupportedOS.
On Linux the backend is auto-detected: shadow-utils (useradd/usermod/userdel) by default, BusyBox (adduser/deluser) on Alpine.
BusyBox ships no usermod, so changing an existing account’s scalar fields is unsupported there; creation and removal work.
gid and group are mutually exclusive on a present user.
state: absent may carry only remove_home (plus severity); attribute params are rejected.
Out of scope for v0.1: macOS via dscl, password / SSH-key management, account expiration (chage), sudoers, and skeleton-dir overrides.

system at