user¶

user manages a local Linux user account: whether it exists, its UID, home directory, login shell, and the groups it must belong to. It reads the account with getent passwd and id -nG, and changes it with useradd, usermod and userdel only when something differs.

Minimal example¶

examples/resources/user/minimal.rb

user "deploy"

Options¶

Option	Type	Default	Description
`uid`	Integer	unmanaged	Numeric user ID.
`home`	String	unmanaged	Home directory path.
`shell`	String	unmanaged	Login shell, such as `"/bin/bash"` or `"/usr/sbin/nologin"`.
`groups`	Array of Strings	unmanaged	Groups the user must belong to. Other memberships are left alone. The groups must exist.
`system`	`true` or `false`	`false`	Create a system account (`useradd -r`), which gets no home directory. Only used when the user is created.
`state`	`:present` or `:absent`	`:present`	`:absent` deletes the account with `userdel`; the home directory is kept.
`notifies`	`[:action, "type[name]"]`, optionally with `:immediately`, or a list of them	none	Actions to run on other resources when this one changes. See Notifications.
`subscribes`	`[:action, "type[name]"]`, optionally with `:immediately`, or a list of them	none	Actions to run on this resource when another one changes.
`tags`	Symbol, String, or an Array of them	none	Tags for running part of a recipe with `--tags` and `--skip-tags`. See Tags.

New users that are not system users get a home directory (useradd -m). Changing home on an existing user updates the account but does not move files.

Scenarios¶

examples/resources/user/recipe.rb

# A login user who belongs to at least the adm group.
user "deploy", shell: "/bin/bash", groups: ["adm"]

# A system user without a login shell.
user "svc-backup", system: true, home: "/var/lib/svc-backup", shell: "/usr/sbin/nologin"

A deploy user and a service account¶

$ sudo sadame plan examples/resources/user
sadame 0.5.1 plan on local (Debian GNU/Linux 12 (bookworm))

+ user[deploy]
    state: absent -> present
    shell: /bin/bash
    groups: adm

+ user[svc-backup]
    state: absent -> present
    home: /var/lib/svc-backup
    shell: /usr/sbin/nologin

Plan: 2 to create, 0 to update, 0 to remove, 0 to run, 0 unchanged.

$ sudo sadame apply examples/resources/user
sadame 0.5.1 apply on local (Debian GNU/Linux 12 (bookworm))

changed    user[deploy]
           state: absent -> present
           shell: /bin/bash
           groups: adm
changed    user[svc-backup]
           state: absent -> present
           home: /var/lib/svc-backup
           shell: /usr/sbin/nologin

Summary
  changed      2  user[deploy]
                  user[svc-backup]
  unchanged    0
  failed       0
  skipped      0
  notified     0

Finished in 0.20s.

$ id deploy
uid=1000(deploy) gid=1000(deploy) groups=1000(deploy),4(adm)

Adding a user to the docker group¶

groups: only adds. A user already in wheel stays there:

examples/resources/user/docker_group.rb

# groups: only adds memberships; the docker group is created by the package.
package "docker.io"
user "deploy", groups: ["docker"]

$ sudo sadame plan examples/resources/user/docker_group.rb
sadame 0.5.1 plan on local (Debian GNU/Linux 12 (bookworm))

+ package[docker.io]
    state: absent -> installed

+ user[deploy]
    state: absent -> present
    groups: docker

Plan: 2 to create, 0 to update, 0 to remove, 0 to run, 0 unchanged.

Removing an account¶

examples/resources/user/remove.rb

# userdel removes the account; the home directory is kept.
user "olduser", state: :absent

Common mistakes¶

Groups that do not exist yet. useradd -G docker fails if the docker group has not been created. Declare the package that creates it first.
Alpine without shadow. Alpine's BusyBox has no useradd. Declare package "shadow" before any user resource; without it the resource fails with a message saying so.
Expecting a group list to be exact. Removing a group from groups: does not remove the user from that group.
Clashing with existing accounts. Many distributions ship system users such as backup or www-data. Declaring one of those with a different home or shell changes the existing account.