Ansible User Module: Manage User Accounts on Remote Hosts

Ansible's user module allows you to create, modify, and manage user accounts on remote hosts. With the user module, you can automate tasks like adding new users, setting passwords, managing groups, and even removing users when necessary.

In this article, we will explore how to use the Ansible user module with practical examples.

Basic Syntax of the Ansible User Module

The basic syntax of the user module is as follows:

- name: Manage user accounts
  ansible.builtin.user:
    name: <username>
    state: <state>
    password: <hashed_password>
    groups: <group_list>
    ...

Now, let’s explore different use cases.

1. Create a new user account

The user module can be used to create a new user and set up default configurations like groups, home directories, and shell types.

Below is a playbook that creates a new user named testuser:

---
- name: Create a new user account
  hosts: all
  become: yes
  tasks:
    - name: Create user 'testuser'
      ansible.builtin.user:
        name: testuser
        state: present
        groups: sudo
        comment: "Test User"
        shell: /bin/bash

Here is a brief explanation of each parameters:

• name: The name of the user account to create. Here, we are creating a user named testuser.
• state: present: Ensures that the user exists. If the user does not exist, it will be created.
• groups: sudo: Adds the user to the sudo group, granting administrative privileges.
• comment: "Test User": Adds a description to the user account, often used to store the full name of the user.
• shell: /bin/bash: Sets the default shell for the user to /bin/bash.

The playbook can be applied to multiple target hosts simultaneously, allowing for uniform user creation across an entire infrastructure.

2. Set a password for the user

When creating user accounts, it's important to set passwords to control access. The user module allows you to set a password, but it must be provided in a hashed format for security reasons. To generate a hashed password, you can use the mkpasswd utility:

mkpasswd --method=SHA-512

Once you have the hashed password, you can use it in your playbook as follows:

---
- name: Set password for the user
  hosts: all
  become: yes
  tasks:
    - name: Create user 'testuser' with a password
      ansible.builtin.user:
        name: testuser
        state: present
        password: "$6$rounds=656000$...$..."  # Replace with your hashed password

Here is the explanation:

• password: Sets the password for the user in a hashed format. Using a hashed password ensures that sensitive data is not exposed in plain text.

3. Create a user with a specific UID and home directory

In some cases, you might need to create a user with a specific user ID (UID) or set a custom home directory. This is particularly useful when migrating users from one system to another or when ensuring compatibility with specific applications.

---
- name: Create user with specific UID and home directory
  hosts: all
  become: yes
  tasks:
    - name: Create user 'developer' with UID 1050
      ansible.builtin.user:
        name: developer
        uid: 1050
        home: /opt/developer_home
        state: present

Explanation:

• uid: 1050: Sets a specific UID for the user, which is useful for maintaining consistency across systems or when assigning specific permissions.
• home: /opt/developer_home: Defines a custom home directory for the user. This can be helpful if the default /home directory is not suitable for your use case.

4. Delete a user account

User management also involves removing accounts that are no longer needed, either for security reasons or for managing resource usage. You can delete a user account using the user module by setting the state to absent:

---
- name: Delete a user account
  hosts: all
  become: yes
  tasks:
    - name: Delete user 'testuser'
      ansible.builtin.user:
        name: testuser
        state: absent

Explanation:

• state: absent: Specifies that the user should be removed from the system.

This action will remove the user, but it does not delete their home directory or other associated files by default.

5. Add user to multiple groups

Assigning users to multiple groups is a common requirement in environments where access control is critical. You can use the user module to assign a user to multiple groups, and the append parameter ensures that existing group memberships are not overwritten.

---
- name: Add user to multiple groups
  hosts: all
  become: yes
  tasks:
    - name: Create user 'devops' and add to groups
      ansible.builtin.user:
        name: devops
        groups: "sudo,docker"
        append: yes
        state: present

Explanation:

• groups: "sudo,docker": Specifies the groups that the user should be a part of. In this case, the user will be added to both sudo and docker groups.
• append: yes: Ensures that the user is added to the specified groups without removing them from any other groups they may already be part of.

This is particularly useful for users who need access to multiple roles or administrative privileges across different services.

6. Lock a user account

There might be scenarios where you need to temporarily prevent a user from logging in without deleting their account. In such cases, you can use the password_lock parameter to lock the account:

---
- name: Lock a user account
  hosts: all
  become: yes
  tasks:
    - name: Lock user 'testuser'
      ansible.builtin.user:
        name: testuser
        password_lock: yes

Explanation:

• password_lock: yes: Locks the user's password, effectively preventing them from logging in. This is useful in scenarios where you need to disable access temporarily, such as during a security audit or if the user is on leave.

Locking a user account without deleting it allows you to retain their data and configurations while preventing unauthorized access.

7. Remove user with its home directory

When removing a user account, it is often necessary to delete their home directory and other related files to free up disk space and ensure data privacy. You can achieve this by setting the remove parameter to yes:

---
- name: Remove user and their home directory
  hosts: all
  become: yes
  tasks:
    - name: Remove user 'developer' and delete home directory
      ansible.builtin.user:
        name: developer
        state: absent
        remove: yes

Explanation:

• remove: yes: Deletes the user's home directory and associated mail spool. This ensures that no residual data remains on the system after the user is deleted.

Conclusion

The Ansible user module provides a powerful and flexible way to manage user accounts across multiple servers. Whether you are creating new users, setting passwords, locking accounts, or deleting users and their associated data, the user module helps you automate these tasks efficiently.