finalgene.users

Ansible Role `users`

Description

This role is used to manage users and their groups on a system.

Requirements

You need the ansible.posix collection to use this role.

ansible-galaxy collection install ansible.posix

Role Variables

Variable	Type	Default	Comments
users	list of objects	`[]`	List of users to create or delete (see users).
users_authorized_keys_exclusive	boolean	`true`	If true, keeps only defined authorized keys for users.
users_authorized_keys_file	string	`.ssh/authorized_keys`	Path to the `authorized_keys` file in the user's home directory.
users_create_homedirs	boolean	`true`	Create home directories for new users.
users_create_per_user_group	boolean	`true`	If true, creates a group for every user as their primary group.
users_default_shell	string	`/bin/bash`	Default shell for users if not specified.
users_group	string	`users`	Default group name for all users. Required only if `users_create_per_user_group` is `false`.
users_groups	list of objects	`[]`	List of user groups to create or delete (see users_groups).
users_home	string	`/home`	Directory for all user home directories.
users_home_chroot	boolean	`false`	If true, uses chroot for user home directories.
users_home_mode	string	`0750`	Permissions for user home directories.
users_kill_process	boolean	`false`	If true, kills user processes if the user is active.
users_kill_process_allowed_users	list of strings		List of usernames whose processes can be killed, used if `users_kill_process` is `true`.
users_kill_process_forbidden_users	list of strings	`[]`	Usernames whose processes should never be killed (e.g., `root`). Used if `users_kill_process` is `true`.
users_kill_process_timeout	integer	`30`	Time in seconds to wait before force-killing a process, used if `users_kill_process` is `true`.
users_ssh_key_type	string	`rsa`	Default SSH key type for users.

users

Variable	Type	Default	Comments
append	boolean	`false`	If true, keeps existing group relations.
authorized_keys	list of strings		List of public SSH keys for user authorization.
authorized_keys_exclusive	boolean		If true, keeps only the specified authorized keys.
comment	string	`''`	User's regular name as a comment.
expires	integer		Expiry time for user in epoch format.
force	boolean	`false`	If true, forces removal of the user and related directories.
group	string		User's primary group name.
groups	list of strings		List of all groups that the user belongs to.
home	string		Full path to the user's home directory.
home_chroot	boolean		If true, sets home ownership to `root` for chroot feature.
home_create	boolean		If true, creates the user's home directory.
home_files	list of objects		List of files to manage in the user's home directory.
home_mode	string		Permissions for the user's home directory.
local	boolean	`false`	Forces the use of “local” command alternatives on supported platforms.
move_home	boolean	`false`	If true, moves the user's old home directory to a new location if it doesn’t exist.
non_unique	boolean	`false`	Allows changing the user ID to a non-unique value.
password	string	`!`	User's password hash (should be created using `mkpasswd`).
password_expire_max	integer		Maximum days between password changes.
password_expire_min	integer		Minimum days between password changes.
password_lock	boolean		Locks the user's password.
remove	boolean	`false`	If true, tries to remove directories related to the user (when `state=absent`).
seuser	string		Optionally sets the SE user type on SELinux systems.
shell	string		User's login shell.
ssh_key_bits	integer		Size of the generated SSH key.
ssh_key_comment	string		Optionally define comment for the SSH key.
ssh_key_file	string		Optionally specify the SSH key filename.
ssh_key_generate	boolean		If true, generates an SSH key pair.
ssh_key_password	string		Passphrase for the generated SSH key.
ssh_key_type	string		Type of the generated SSH key (e.g., `rsa`, `ed25519`).
ssh_keys	list of objects		List of private SSH keys for the user (see ssh_keys).
state	string	`present`	`present` creates or updates the user, `absent` removes an existing user.
system	boolean		Indicates if the user is a system user (`true`) or not (`false`).
uid	integer		User ID; if not defined, the next available UID is used.
update_password	boolean		`always` updates passwords if they differ; `on_create` sets password only for newly created users.
username	string required		Login name of the user.

home_files

Variable	Type	Default	Comments
content	string		Content of the managed file (used only if `template` is not provided).
dir_mode	string	`0750`	Directory permissions (for created directories).
file_mode	string	`0640`	File permissions.
path	string		File path, relative to the user's home directory.
state	string	`present`	`present` creates or updates the file; `absent` removes it.
template	string		Indicates if the group is a system group (`true`) or not (`false`).

ssh_keys

Variable	Type	Default	Comments
name	string required		Key file name.
key	string		Content of the SSH private key file.
state	string	`present`	`present` stores the key file in the user's home directory; `absent` removes an existing key file.

users_groups

Variable	Type	Default	Comments
gid	integer		The group's GID; the next available GID is used if not defined.
local	boolean	`false`	Forces use of “local” command alternatives on supported platforms.
name	string required		Group name.
state	string	`present`	`present` creates or updates the group; `absent` removes an existing group.
system	boolean		Indicates if the group is a system group (`true`) or not (`false`).

Example Playbook

users:
  - username: foo
    comment: Foo Barrington
    groups:
      - wheel
      - -systemd-journal
    uid: 1001
    home: /local/home/foo
    authorized_keys:
      - "ssh-rsa AAAAA.... foo@machine"
      - "ssh-rsa AAAAB.... foo2@machine"
  - username: bar
    uid: 1002
    state: absent
    remove: yes
    force: yes
users_groups:
  - name: developers
    gid: 10000