Ansible Role: Users

This role manages users and their groups on your system.

Requirements

Access to a repository containing packages, likely on the internet.
A recent Ansible version (tested last 2 stable major versions).

The following roles can be installed to ensure all requirements are met, using ansible-galaxy install -r requirements.yml:

---
- rembik.bootstrap

Role Variables

These defaults are set in defaults/main.yml:

---
# defaults file for users

# The default value, whether to create a group for every user
# and make that their primary group
users_group_per_user: yes
# If no group per user is created, then this is the default primary
# group all users belong to
users_group: users
# The default value, whether to create home directory for the user
# when the account is created or if the home directory does not exist
users_create_home: yes
# The default sudo options for the user when sudo is set to yes,
# but none are specified
users_sudo_options: "ALL=(ALL) NOPASSWD: ALL"
# The default shell for the user when none is specified
users_shell: /bin/bash
# The local directory to find/store generated ssh keys
users_ssh_key_dir: ssh_keys

# Lists of users to create, remove or modify
users: []

# List of user groups to create or delete
users_groups: []

A good place to put replacements for these variables is in group_vars/all or group_vars/group_name, if you only want defined users and groups to be on certain machines.

The users variable containing the list of users to create, remove or modify. Each user in this list is defined as an dictionary. The following parameters are available for each user dictionary:

User Parameter	Choices / Defaults	Comments
`name` required		Name of the user to create, remove or modify.
`state`	Choices: present absent	Whether the account should exist or not, taking action if the state is different from what is stated.
`comment`		Optionally sets the description (aka GECOS) of user account.
`uid`		Optionally sets the UID of the user.
`group`	Default: `user.name`	Optionally overrides the user's primary group taken from `users_group_per_user=yes` or `users_group` (takes a group name).
`gid`		This only affects `users_group_per_user=yes`. Optionally sets different GID of user's primary group. Otherwise the UID will be used.
`groups`		List of groups user will be added to. When set to an empty string the user is removed from all groups except the primary group.
`append`	Choices: no yes	If yes, add the user to the groups specified in `groups`. If no, user will only be added to the groups specified in `groups`, removing them from all other groups.
`password`	Default: !	Optionally set the user's password to this crypted value. Otherwise the user account will be locked.
`update_password`	Choices: always on_create	always will update passwords if they differ. on_create will only set the password for newly created users.
`create_home`	Choices: yes no	Optionally overrides this value taken from `users_create_home`. Unless set to no, a home directory will be made for the user when the account is created or if the home directory does not exist.
`home`	Default: /home/`user.name`	Optionally set the user's home directory.
`shell`	Default: /bin/bash	Optionally overrides the user's shell taken from `users_shell`.
`profile`		Optionally sets custom block into user's profile. Requires `user.create_home=yes`!
`cron`	Choices: no yes	If yes, allow the user to create, edit, display, or remove crontab files. Otherwise, disallow to modify crontab files.
`sudo`	Choices: no yes	If yes, set the user's sudo options taken from `user.sudo_options`. Otherwise, remove the user's sudo options.
`sudo_options`	Default: ALL=(ALL) NOPASSWD: ALL	Optionally overrides the user's sudo options taken from `users_sudo_options`.
`ssh_key`		List of the users's authorized SSH keys (takes public SSH keys; included directly and without newlines). When set to an empty list or string all the users's authorized SSH keys are removed. Requires `user.create_home=yes`!
`generate_ssh_key`	Choices: no yes	Unless set to no, generate the user's SSH key pair, if the SSH key does not exists in the local directory `users_ssh_key_dir`. After that, add it to the users's authorized SSH keys and deploy the SSH key pair to the user. Requires `user.create_home=yes`!
`remove`	Choices: no yes	This only affects `user.state=absent`, it attempts to remove directories associated with the user. The behavior is the same as userdel --remove, check the man page for details and support.
`force`	Choices: no yes	This only affects `user.state=absent`, it forces removal of the user and associated directories on supported platforms. The behavior is the same as userdel --force, check the man page for details and support.

The users_groups variable containing the list of user groups to create or delete. Each group in this list is defined as an dictionary. The following parameters are available for each group dictionary:

Group Parameter	Choices / Defaults	Comments
`name` required		Name of the group to manage.
`state`	Choices: present absent	Whether the group should be present or not on the remote host.
`gid`		Optional GID to set for the group.

Dependencies

In general this role has no dependencies. In combination with the recommended role rembik.bootstrap, this role uses the defined bootstrap_user (if necessary) to connect to the remote host and executing this role tasks.

Example Playbook

This example is taken from molecule/playbook.yml:

---
- name: Converge
  hosts: all
  gather_facts: no
  become: yes

  roles:
    - role: rembik.bootstrap
    - role: rembik.users
      vars:
        users_ssh_key_dir: "{{ lookup('env', 'MOLECULE_EPHEMERAL_DIRECTORY') }}/ssh_key"
        users_groups:
          - name: users
          - name: bin
        users:
          - name: nouser
            comment: No User
            create_home: no
          - name: molecule
            comment: Ansible Test User
            uid: 2001
            home: /home/test
            cron: yes
            sudo: yes
            generate_ssh_key: yes
          - name: administrator
            comment: Administrator
            uid: 2002
            groups: [users]
            cron: yes
            sudo: yes
            profile: |
              alias ll='ls -lah'
              alias cp='cp -iv'
            ssh_key:
              - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABWBILQeRSYYmGea/WIf6kd... admin@example.com"
          - name: user
            comment: User
            uid: 2003
            groups: [users]
            shell: /bin/sh
            generate_ssh_key: yes