Skip to content

Linux Users Ansible Role

Manage local users and groups on Debian and Ubuntu systems.

Features

  • Create/update/remove local groups
  • Create/update/remove local users, including primary/group memberships
  • Optionally remove home directories when users are absent
  • Manage authorized_keys for user accounts
  • Optionally enforce password aging/inactivity settings for managed accounts
  • Optionally lock managed non-login accounts using /usr/sbin/nologin, /sbin/nologin, or /bin/false
  • Ensure XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS are set in user ~/.bashrc

Role Variables

Variable Default Description
users_default_shell /bin/bash Default login shell when none is provided per user
users_default_password_expire_max_days null Default maximum password age; null leaves account setting unchanged
users_default_password_expire_min_days null Default minimum password age; null leaves account setting unchanged
users_default_password_warn_days null Default password expiry warning days; null leaves account setting unchanged
users_default_password_inactive_days null Default inactive days after expiry; null leaves account setting unchanged
users_lock_non_login_accounts false Lock managed accounts whose shell is a non-login shell
users_validate_root_gid_zero true Assert that the root account uses primary GID 0
users_validate_shadow_group_empty false Assert that the shadow group has no explicit members. WARNING: Enabling this Breaks VNC (wayvnc), pwhistory, and other services that require shadow group membership for unix_chkpwd PAM authentication.
users_validate_system_accounts_non_login false Assert that system accounts use non-login shells
users_system_accounts_max_uid 1000 UID threshold below which accounts are treated as system accounts for validation
users_system_accounts_exempt ['root', 'sync', 'shutdown', 'halt'] System accounts excluded from non-login shell validation
users_non_login_shells see defaults Allowed non-login shells for system-account validation
users_remove_home_on_absent false Remove home directory when a user is set to absent (overridable per user via remove)
users_groups [] List of groups to manage (name, state, gid, system)
users_accounts [] List of user accounts to manage

users_groups entries

Key Type Description
name string Group name (required)
state string present (default) or absent
gid int Optional GID
system bool Create as system group

users_accounts entries

Key Type Description
name string Username (required)
state string present (default) or absent
uid int Optional UID
primary_group string Primary group name/GID
groups list Supplemental groups
append bool Append to groups (default true)
shell string Login shell (defaults to users_default_shell)
comment string GECOS/comment field
home string Home directory path
create_home bool Create home directory (default true)
system bool Create as system user (default false)
password string Hashed password (password_hash recommended)
password_expire_max_days int Per-user maximum password age override
password_expire_min_days int Per-user minimum password age override
password_warn_days int Per-user password expiry warning days override
password_inactive_days int Per-user inactive days after expiry override
remove bool Remove home directory when state: absent (falls back to users_remove_home_on_absent)
ssh_authorized_keys list SSH keys to place in authorized_keys (each entry may be a string key or dict with key and optional state)

Example Playbook

---
- hosts: servers
  become: true
  roles:
    - role: users
      vars:
        users_groups:
          - name: developers
            gid: 1500
        users_accounts:
          - name: alice
            groups: ["developers", "sudo"]
            comment: "Alice Example"
            ssh_authorized_keys:
              - key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMoleculeTestKey alice@example"
          - name: tempuser
            state: absent
            remove: true