Working with Ansible User Module

Ansible user module helps us to manage user accounts in Linux systems including creating user accounts, deleting them, setting passwords, adding groups to each user, etc.

How to create users in Ansible

Let us first see how to write a basic task for creating a Linux user using the Ansible user module.

There is only one mandatory parameter which is the name parameter. This is the name of the user account which you want to create. But if you are not providing the password, the account will be in a locked state, which means you cannot login using the password option. For example, I created a new user without setting the password parameter. When I am trying to log in, it will be asking for the password. But since I have not set the password  I cannot log in. Also, as you can see in the following /etc/shadow, the account is locked.

test1:!:17441:0:99999:7:::

So it is better to set a password also while creating a new user.

While giving the password, you have to give it as a hash value and not cleartext(Except on Darwin system). Click here to know more about generating the hash value.

The home directory for the user will also be created at /home/test2 by default. You have the option to choose your home directory by setting the home parameter. The password given in the below task is a hash of string ‘test1’.

The password provided in the below task is a hash of string ‘test1’.

- hosts: all
  tasks:
  - name: Ansible create user example.
    user:
      name: test2
      password: $6$53uLlaE42OzJi8k1$nah2F17o2XYc1rMg1bZwlIY2XRdgnYrqwVGUJC
bsnpwtqCAGxyn9eN/RRdZNugHbcOLjz/.y4Slou4ut7yl3P0

mdtutorials2@system01:~$ sudo vim /etc/shadow
...
test2:$6$53uLlaE42OzJi8k1$nah2F17o2XYc1rMg1bZwlIY2XRdgnYrqwVGUJCbsnpwtqCAGxyn9eN/RRdZNugHbcOLjz/.y4Slou4ut7yl3P0:17441:0:99999:7:::

1.2 Adding a User to Group in Ansible

There are other options which will be helpful while creating a new user. For the full set of parameters refer the Ansible docs.

In order to add a user to certain groups, you can use the ‘groups’ parameter. In the following example, I am setting the groups of the user test2, which was already created, to root and ubuntu.

- hosts: all
  tasks:
  - name: ansible add user to group example
    user:
      name: test3
      groups: root, ubuntu

output
======
mdtutorials2@system01:~$ groups test3
test3: test3 root ubuntu

Note: This will overwrite the existing set of users. For example, if I give another task below with only ‘root’ against the ‘groups’ parameter, then the user is removed from ubuntu group.

mdtutorials2@system01:~$ groups test3
test3 : test3 root

Note: If the group mentioned is not already present in the System, Ansible will throw an error like below.

fatal: [localhost]: FAILED! => {“changed”: false, “failed”: true, “msg”: “Group admins does not exist”}

1.3 Appending new groups to an existing user

If you do not want to overwrite the existing set of groups, then you can use the ‘append’ parameter. Just set the value of append parameter to ‘yes’. By default, the value is ‘yes’.

For example, if I need to add the test3 user to two more groups ‘googlecloud’ and ‘admin’, I can do the following.

- hosts: all
  tasks:
  - name: Ansible append user to group example.
    user:
      name: test3
      groups: admin, googlecloud
      append: yes

output
======
mdtutorials2@system01:~$ groups test3
test3 : test3 root admin googlecloud

1.4 Setting the primary group for a user

You can also set the primary group for a user. By default, the name of the user itself is taken as the primary group, which you can see from the ‘groups’ output of test3 user. You can use the ‘group’ parameter for setting the primary group for a user. Note that there is no ‘s’.

If the user is already existing, then the previous value of primary group will be overwritten.

For example, I am creating a new user test4 with the primary group set as ‘admin’

- hosts: all
  tasks:
  - name: ansible add the primary group for a user example
    user:
      name: test4
      group: admin

output
======
mdtutorials2@system01:~$ groups test4
test4 : admin

Note: To remove a particular user from all the secondary groups you can execute the task with ‘groups’ parameter set to empty string. This will not remove the primary group.

How to remove a User in Ansible

Removing an existing user is easy. You just have to set the ‘state’ parameter to ‘absent’. It executes the ‘userdel’ command in the background.

The below task will delete the user test4 from the system.

- hosts: all
  tasks:
  - name: ansible remove user example
    user:
      name: test4
      state: absent

output
======
mdtutorials2@system01:~$ groups test4
groups: ‘test4’: no such user

mdtutorials2@system01:~$ cd /home/test4
mdtutorials2@system01:/home/test4$

You can see the user test4 does not exist anymore. But the home directory still exists. If you want to remove the home directory also, you can set the remove parameter to ‘yes’. By default, the value is ‘no’. Also, set the force parameter to ‘yes’ for the forced removal of files.

The following task does the equivalent of ‘userdel test4 –remove –force’.

- hosts: all
  tasks:
  - name: ansible delete user to group example
    user:
      name: test4
      state: absent
      remove: yes 
      force: yes

output
======

mdtutorials2@system01:~$ groups test4
groups: ‘test4’: no such user

mdtutorials2@system01:~$ cd /home/test4
-bash: cd: /home/test4: No such file or directory

As you can see from the output, the user and the home directory is deleted for user ‘test4.’