Ansible User Module Tutorial

Managing users and user attributes is a typical operation for any system administrator. The Ansible user module is one of the handiest ways to manage users and their attributes when working with remote hosts.

Ansible.builtin.user module is part of ansible-core and is available by default in most ansible installations.

In this guide, we will focus on how to manage user accounts using the ansible user module.

How The Ansible User Module Works

The Ansible user module works using a collection of parameters. Each parameter allows you to customize the action the module performs and how the module performs set actions on the remote host.

The following are some of the important parameters of the Ansible user module.

  • name – The username to create, delete, or modify
  • password – Sets a password for a specified user.
  • uid – Sets the UID of a defined user.
  • shell – Sets the default shell for a user.
  •  expires – Sets the expiry time expressed in epoch time.
  • generate_ssh_key – A Boolean value that sets if an ssh-key pair should be generated for a specified user.
  • create_home – Boolean value. If true, a home directory is created for a user during account creation.
  • force – Force delete a user account
  • group – Defines the primary group for a specified user.
  • state – Determines whether an account should exist or not: absent or present

It is good to understand that there are other parameters not covered in this guide. Check the ansible user module docs to learn more.

The best way to illustrate how to use the Ansible user module is using practical examples.

Ansible User Module Practical Examples

In this guide, we assume you have an Ansible control node with the remote host inventory configured.

Before proceeding further, start by testing if the remote hosts are up:

ansible all -m ping -v

If all hosts are up and all requirements met, you should see an output similar to the one shown below:

Example 1: How to create a user

To create a user on the remote hosts, we can use a simple playbook such as the one shown in the example below:

- hosts: all
  become: true
  - name: create user on remote host
      name: ansible_test
      shell: /bin/bash
      group: wheel

In the example above, we call the user module using its full name. However, you can short name it to “user”

  1. name – Specifies the username of the target user to create
  2. shell – Sets the default shell for the user
  3. group – Defines the primary group for the user

Save the playbook and run with the command:

ansible-playbook createuser.yml

Example 2: How to remove a user

We can remove a remote user by setting the state as absent and remove to true. Below is an example playbook:

- hosts: all
  become: true
  - name: remove user
      name: ansible_test
      state: absent
      remove: true

In this example, we set the state as absent. Setting the remove parameter to true will remove the user’s associated directories.

Run the playbook:

ansible-playbook removeuser.yml

Example 3: How to set a password expiration date

Suppose we want to set an expiry date for a user’s password. We can do this by setting the expiry date as:

- hosts: all
  become: true
  - name: set password expiration
      name: ansible_test
      password_expire_min: 5
      password_expire_max: 15

Example 4: How to create an SSH key for a user

To generate an SSH key pair for a remote user, we can use the generate_ssh_key parameters as shown in the playbook below:

- hosts: all
  - name: generate ssh key
      name: ansible_test
      generate_ssh_key: true
      ssh_key_file: ~/.ssh/id_rsa
      ssh_key_type: rsa
      ssh_key_bits: 4096

Example  5: How to update a user password

To update a user’s password, we will backup the shadow and generate a hash for the password as shown in the playbook below:

- hosts: all
  become: true
  - name: backup shadow file
      src: /etc/shadow
      dest: /etc/shadow.bak
  - name: update user password
      name: ansible_test
      state: present
      update_password: true
      password: "{{ updatedpassword|password_hash('sha512') }}"

In the example above, we start by backing up the shadow file. Next, we specify the new password for the user.

Run the playbook as:

ansible-playbook updatepass.yml updatedpassword=<newpassword>


This guide taught you how to manage users and user attributes using the Ansible user module. I suggest checking the documentation for additional parameters.

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list