# 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`](#user.name) | string | required |  |
| [`uid`](#user.uid) | ID | - |  |
| [`group`](#user.group) | name or ID | \<name\> | primary group |
| [`system`](#user.system) | boolean | false | system user, at creation only |
| [`home`](#user.home) | string | /home/\<name\> | created when missing; never moved |
| [`shell`](#user.shell) | string | /bin/sh | login shell |
| [`groups`](#user.groups) | list of strings | - | exact supplementary groups |
| [`add_groups`](#user.add_groups) | list of strings | - | groups to join, keeping the others |
| [`password`](#user.password) | string | - | crypt hash, usually a !secret |
| [`comment`](#user.comment) | string | - | full name or description |
| [`authorized_keys`](#user.authorized_keys) | list of strings | - | exact SSH keys of the user |
| [`absent`](#user.absent) | boolean | false | remove the user; the home stays |

### `user.name` {#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` {#user.uid}

ID

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

### `user.group` {#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` {#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` {#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` {#user.shell}

string, default /bin/sh

Login shell. The default counts only when the step creates the user. A system user gets /usr/sbin/nologin.

### `user.groups` {#user.groups}

list of strings

Exact supplementary groups. A step has groups or add\_groups.

### `user.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` {#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` {#user.comment}

string

Full name or description.

### `user.authorized_keys` {#user.authorized_keys}

list of strings

Exact SSH keys of the user, in \~/.ssh/authorized\_keys.

### `user.absent` {#user.absent}

boolean, default false

Remove the user; the home stays.

## Example

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