Updated April 15, 2023
Introduction to Ansible User Module
Ansible provides a lot of useful modules which can help to ease our jobs in IT. For almost every operation, we have one or more modules in Ansible which can do similar execution, that would have been done by commands or scripting.
One such module is the user module, which is used to create, remove, update a user on remotes hosts. This is for Linux/Unix based OS on remotes hosts. For target machines based on Microsoft Windows, there is another similar module named win_user. In this article, we will learn about the user module and its parameters with acceptable options.
What is the Ansible User Module?
Ansible user module is a way to use Ansible to do user management on target remote machines. In any operating system like Linux or Microsoft Windows; user, group, and role management are an important part. Which makes users segregated based on their assigned privileges, requirement, and scope of work.
While using the Ansible user module we are basically doing the same operations which we would be doing using user management related commands in Linux/Unix environment.
So we need to remember below points while using this module: –
- There are some basic requirements which are needed by this module on remote systems, if those requirements are not present, then running this module will fail. These requirements vary from system to system as it varies from Linux to Sun Solaris
- When making the changes in the shadow file of remote systems, the file is backed up either by the system’s OS or the underlying tools used by This behavior is dependent on the operating system on target machines.
- For macOS, this module uses dscl based commands to create, remove, and modify accounts and group membership.
- For the FreeBSD platform, this module uses pw useradd and chpass command to do the creation of the user.
Similarly other commands to do other tasks.
- On all other Linux/Unix based operating systems, this module will invoke useradd, userdel, usermod command.
How does it work?
In Ansible, for user module, we have a set of parameters with related default and acceptable options. We can use these in a suitable combination to perform a required task related to user management on a remote target machine.
- name: Name of the user account to create/modify/remove.
- password: This is to set the password of a user.
- comment: To set the GECOS/comment of a user
- append: To assign a user to a list of groups. Default is no, which means the new group’s list will overwrite the current group lists, which are assigned to the user.
- expires Expiry time in epoch format. This will be ignored in the unsupported platform.
- force: This is to force the deletion of the user, when used with state=absent.
- home: To set the user’s home directory
- group: The primary group of a user can be set by this.
- groups: Secondary groups can be set by this. If empty string like (‘ ‘) is mentioned then all secondary groups will be removed,
- remove: To remove user associated directories when used with state=absent.
- shell: To set the user’s working default shell.
- state: To specify whether the user should be present or absent.
- system: When setting to yes and state=present. This makes the user a system user.
- uid: To set the UID of the user.
Examples of Ansible User Module
Now by using examples, we will try to learn about the Ansible USER module, which you might have to use in day to day operations. First, let me introduce you to our lab environment. We have an Ansible controller node named ansible-controller. Also, as target remote machines we have two Linux based nodes named host-one and host-two. We will run Ansible command and playbooks on the Ansible control node ansible- controller and try to do changes on the target remote machines.
Example #1
In this example, we create a user on remote machines, for this, we have a playbook like below.
Code:
hosts: all tasks:
name: create test_user on remote machines user:
name: test_user state: present uid: 2001
shell: /bin/bash
comment: This is a test user group: testgroup
name: Now we check whether the user is present on remote machines and with what parameter
shell: "getent passwd test_user;passwd -S test_user" register: var_user
debug:
var: var_user.stdout_lines
Now running this playbook like below, we are creating the user on remote hosts and checking this user’s availability and creation date.
Code:
ansible-playbook ansible_user.yaml
Output:
Example #2
In this example, we will first check the user’s secondary group and then add a secondary group to the user and then check again. For this, we will user Ansible modules debug, shell and
Code:
hosts: all gather_facts: no tasks:
name: Here we check the secondary group list of user "test_user" shell: id test_user
register: var_user_group
debug:
var: var_user_group.stdout_lines
name: Here we will add user "test_user" to secondary group "testgroup" user:
name: test_user groups: testgroup append: yes
name: Here we check again the secondary group list of user "test_user" shell: id test_user
register: var_user_group1
debug:
var: var_user_group1.stdout_lines
Now execute this playbook using ansible-playbook command like below.
Code:
ansible-playbook ansible_user_group.yaml
Output:
The output will be like below where you can see that the user “test_user” was not assigned to any secondary group. Then we assigned a group “test group” as a secondary group to it. Now on checking again we can see this group is listed as a secondary group.
Example #3
For removing a user from remote machines, create a playbook like below: –
Code:
hosts: all tasks:
name: To remove test_user from remote machines user:
name: test_user state: absent remove: yes force: yes
Now running this playbook will give output like below where you can see that the user is removed.
Code:
ansible-playbook ansible_user_remove.yaml -v
Output:
Conclusion
As we saw in this article that this module is potent enough to make you enable to do user management remotely. This way we can do user provisioning easily especially when we have many machines to touch upon. So learn it first and then use it.
Recommended Articles
This is a guide to Ansible User Module. Here we discuss an introduction to Ansible User Module, how does it work with examples to implement. You can also go through our other related articles to learn more –
