user

manage a user account

A step that creates a user also creates its home directory. Without group, it also creates a group with the name of the user. The defaults and system count only when the step creates the user.

Keys

Key	Type	Default	Meaning
`name`	string	required
`uid`	ID	-
`group`	name or ID	<name>	primary group
`system`	boolean	false	system user, at creation only
`home`	string	/home/<name>	created when missing; never moved
`shell`	string	/bin/sh	login shell
`groups`	list of strings	-	exact supplementary groups
`add_groups`	list of strings	-	groups to join, keeping the others
`password`	string	-	crypt hash, usually a !secret
`comment`	string	-	full name or description
`authorized_keys`	list of strings	-	exact SSH keys of the user
`absent`	boolean	false	remove the user; the home stays

`user.name`

string, required

A new user's name has lowercase letters, digits, _, and -, and does not start with a digit or -. It has at most 32 characters.

`user.uid`

A whole number. A uid that another user has fails the check.

`user.group`

name or ID, default <name>

Primary group. Without group, a step that creates the user also creates a group with the name of the user.

`user.system`

boolean, default false

System user, at creation only. Its home is /nonexistent and its shell is /usr/sbin/nologin. It counts only when the step creates the user.

`user.home`

string, default /home/<name>

Created when missing; never moved. The step creates a missing home directory, except /nonexistent. The default counts only when the step creates the user. A system user gets /nonexistent. A changed home is not moved.

`user.shell`

string, default /bin/sh

`user.groups`

list of strings

Exact supplementary groups. A step has groups or add_groups.

`user.add_groups`

list of strings

Groups to join, keeping the others. A step with only name and add_groups does not create the user: apply fails when the user does not exist.

`user.password`

string

Crypt hash, usually a !secret, such as one from mkpasswd -m yescrypt or openssl passwd -6. ! or * alone locks the password. Without password, the password of a new user is locked.

`user.comment`

string

Full name or description.

`user.authorized_keys`

list of strings

Exact SSH keys of the user, in ~/.ssh/authorized_keys.

`user.absent`

boolean, default false

Remove the user; the home stays.

Example

- user:
    name: deploy
    groups: [www-data]
    shell: /bin/bash
    authorized_keys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGlrZDl2Q3h5c3d6bW9ja2tleWZvcmRvY3MxMjM0 deploy@laptop