ansible.builtin.user module – Manage user accounts
Note
This module is part of ansible-core
and included in all Ansible
installations. In most cases, you can use the short
module name
user
even without specifying the collections keyword.
However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.user
for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
Synopsis
Manage user accounts and user attributes.
For Windows targets, use the ansible.windows.win_user module instead.
Parameters
Parameter |
Comments |
---|---|
Sets the authorization of the user. Can set multiple authorizations using comma separation. To delete all authorizations, use Currently supported on Illumos/Solaris. Does nothing when used with other platforms. |
|
Optionally sets the description (aka GECOS) of user account. On macOS, this defaults to the |
|
Unless set to Changed from Choices:
|
|
An expiry time for the user in epoch, it will be ignored on platforms that do not support this. Currently supported on GNU/Linux, FreeBSD, and DragonFlyBSD. Since Ansible 2.6 you can remove the expiry time by specifying a negative value. Currently supported on GNU/Linux and FreeBSD. |
|
This only affects The behavior is the same as When used with Choices:
|
|
Whether to generate a SSH key for the user in question. This will not overwrite an existing SSH key unless used with Choices:
|
|
Optionally sets the user’s primary group (takes a group name). On macOS, this defaults to |
|
A list of supplementary groups which the user is also a member of. By default, the user is removed from all other groups. Configure When set to an empty string Before Ansible 2.3, the only input format allowed was a comma separated string. |
|
macOS only, optionally hide the user from the login window and system preferences. The default will be Choices:
|
|
Optionally set the user’s home directory. |
|
Forces the use of “local” command alternatives on platforms that implement it. This is useful in environments that use centralized authentication when you want to manipulate the local users (in other words, it uses This will check This requires that the above commands as well as Choices:
|
|
Optionally sets the user’s login class, a feature of most BSD OSs. |
|
If set to Choices:
|
|
Name of the user to create, remove or modify. |
|
Optionally when used with the -u option, this option allows to change the user ID to a non-unique value. Choices:
|
|
If provided, set the user’s password to the provided encrypted hash (Linux) or plain text password (macOS). Linux/Unix/POSIX: Enter the hashed password as the value. See FAQ entry for details on various ways to generate the hash of a password. To create an account with a locked/disabled password on Linux systems, set this to To create an account with a locked/disabled password on OpenBSD, set this to OS X/macOS: Enter the cleartext password as the value. Be sure to take relevant security precautions. On macOS, the password specified in the When the password is passed as an argument, the |
|
Maximum number of days between password change. Supported on Linux only. |
|
Minimum number of days between password change. Supported on Linux only. |
|
Number of days of warning before password expires. Supported on Linux only. |
|
Lock the password ( Implementation differs by platform. This option does not always mean the user cannot login using other methods. This option does not disable the user, only lock the password. This must be set to Currently supported on Linux, FreeBSD, DragonFlyBSD, NetBSD, OpenBSD. Choices:
|
|
Sets the profile of the user. Can set multiple profiles using comma separation. To delete all the profiles, use Currently supported on Illumos/Solaris. Does nothing when used with other platforms. |
|
This only affects The behavior is the same as Choices:
|
|
Sets the role of the user. Can set multiple roles using comma separation. To delete all roles, use Currently supported on Illumos/Solaris. Does nothing when used with other platforms. |
|
Optionally sets the seuser type (user_u) on selinux enabled systems. |
|
Optionally set the user’s shell. On macOS, before Ansible 2.5, the default shell for non-system users was On other operating systems, the default shell is determined by the underlying tool invoked by this module. See Notes for a per platform list of invoked tools. |
|
Optionally set a home skeleton directory. Requires |
|
Optionally specify number of bits in SSH key to create. The default value depends on ssh-keygen. |
|
Optionally define the comment for the SSH key. Default: |
|
Optionally specify the SSH key filename. If this is a relative filename then it will be relative to the user’s home directory. This parameter defaults to |
|
Set a passphrase for the SSH key. If no passphrase is provided, the SSH key will default to having no passphrase. |
|
Optionally specify the type of SSH key to generate. Available SSH key types will depend on implementation present on target host. Default: |
|
Whether the account should exist or not, taking action if the state is different from what is stated. See this FAQ entry for additional requirements when removing users on macOS systems. Choices:
|
|
When creating an account This setting cannot be changed on existing users. Choices:
|
|
Optionally sets the UID of the user. |
|
Sets the umask of the user. Currently supported on Linux. Does nothing when used with other platforms. Requires |
|
Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
Support: none |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platform: posix |
Target OS/families that can be operated against |
Notes
Note
There are specific requirements per platform on user management utilities. However they generally come pre-installed with the system and Ansible will require they are present at runtime. If they are not, a descriptive error message will be shown.
On SunOS platforms, the shadow file is backed up automatically since this module edits it directly. On other platforms, the shadow file is backed up by the underlying tools used by this module.
On macOS, this module uses
dscl
to create, modify, and delete accounts.dseditgroup
is used to modify group membership. Accounts are hidden from the login window by modifying/Library/Preferences/com.apple.loginwindow.plist
.On FreeBSD, this module uses
pw useradd
andchpass
to create,pw usermod
andchpass
to modify,pw userdel
remove,pw lock
to lock, andpw unlock
to unlock accounts.On all other platforms, this module uses
useradd
to create,usermod
to modify, anduserdel
to remove accounts.
See Also
See also
- ansible.posix.authorized_key
Adds or removes an SSH authorized key.
- ansible.builtin.group
Add or remove groups.
- ansible.windows.win_user
Manages local Windows user accounts.
Examples
- name: Add the user 'johnd' with a specific uid and a primary group of 'admin'
ansible.builtin.user:
name: johnd
comment: John Doe
uid: 1040
group: admin
- name: Create a user 'johnd' with a home directory
ansible.builtin.user:
name: johnd
create_home: yes
- name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups
ansible.builtin.user:
name: james
shell: /bin/bash
groups: admins,developers
append: yes
- name: Remove the user 'johnd'
ansible.builtin.user:
name: johnd
state: absent
remove: yes
- name: Create a 2048-bit SSH key for user jsmith in ~jsmith/.ssh/id_rsa
ansible.builtin.user:
name: jsmith
generate_ssh_key: yes
ssh_key_bits: 2048
ssh_key_file: .ssh/id_rsa
- name: Added a consultant whose account you want to expire
ansible.builtin.user:
name: james18
shell: /bin/zsh
groups: developers
expires: 1422403387
- name: Starting at Ansible 2.6, modify user, remove expiry time
ansible.builtin.user:
name: james18
expires: -1
- name: Set maximum expiration date for password
ansible.builtin.user:
name: ram19
password_expire_max: 10
- name: Set minimum expiration date for password
ansible.builtin.user:
name: pushkar15
password_expire_min: 5
- name: Set number of warning days for password expiration
ansible.builtin.user:
name: jane157
password_expire_warn: 30
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
Whether or not to append the user to groups. Returned: When Sample: |
|
Comment section from passwd file, usually the user name. Returned: When user exists Sample: |
|
Whether or not to create the home directory. Returned: When user does not exist and not check mode Sample: |
|
Whether or not a user account was forcibly deleted. Returned: When Sample: |
|
Primary user group ID Returned: When user exists Sample: |
|
Whether or not to move an existing home directory. Returned: When Sample: |
|
User account name. Returned: always Sample: |
|
Whether or not to remove the user account. Returned: When Sample: |
|
Fingerprint of generated SSH key. Returned: When Sample: |
|
Path to generated SSH private key file. Returned: When Sample: |
|
Generated SSH public key file. Returned: When Sample: |
|
Standard error from running commands. Returned: When stderr is returned by a command that is run Sample: |
|
Standard output from running commands. Returned: When standard output is returned by the command that is run |
|
Whether or not the account is a system account. Returned: When Sample: |
|