ansible / ansible.builtin / v2.5.15 / module / user Manage user accounts | "added in version" 0.2 of ansible.builtin" Authors: Stephen Fromm (@sfromm) stableinterface | supported by coreansible.builtin.user (v2.5.15) — module
pip
Install with pip install ansible==2.5.15
Manage user accounts and user attributes.
For Windows targets, use the M(win_user) module instead.
- name: Add the user 'johnd' with a specific uid and a primary group of 'admin' user: name: johnd comment: John Doe uid: 1040 group: admin
- name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups user: name: james shell: /bin/bash groups: admins,developers append: yes
- name: Remove the user 'johnd' user: name: johnd state: absent remove: yes
- name: Create a 2048-bit SSH key for user jsmith in ~jsmith/.ssh/id_rsa 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 user: name: james18 shell: /bin/zsh groups: developers expires: 1422403387
uid: description: - Optionally sets the I(UID) of the user. home: description: - Optionally set the user's home directory. name: aliases: - user description: - Name of the user to create, remove or modify. required: true force: default: 'no' description: - When used with C(state=absent), behavior is as with C(userdel --force). type: bool group: description: - Optionally sets the user's primary group (takes a group name). local: default: 'no' description: - Forces the use of "local" command alternatives on platforms that implement it. This is useful in environments that use centralized authentification when you want to manipulate the local users. I.E. it uses `luseradd` instead of `useradd`. - This requires that these commands exist on the targeted host, otherwise it will be a fatal error. type: bool version_added: '2.4' version_added_collection: ansible.builtin shell: description: - Optionally set the user's shell. - On Mac OS X, before version 2.5, the default shell for non-system users was /usr/bin/false. Since 2.5, the default shell for non-system users on Mac OS X is /bin/bash. state: choices: - absent - present default: present description: - Whether the account should exist or not, taking action if the state is different from what is stated. append: default: 'no' description: - If C(yes), add the user to the groups specified in C(groups). - If C(no), user will only be added to the groups specified in C(groups), removing them from all other groups. type: bool groups: description: - List of groups user will be added to. When set to an empty string C(''), C(null), or C(~), the user is removed from all groups except the primary group. (C(~) means C(null) in YAML) - Before version 2.3, the only input format allowed was a comma separated string. Now this parameter accepts a list as well as a comma separated string. remove: default: 'no' description: - When used with C(state=absent), behavior is as with C(userdel --remove). type: bool seuser: description: - Optionally sets the seuser type (user_u) on selinux enabled systems. version_added: '2.1' version_added_collection: ansible.builtin system: default: 'no' description: - When creating an account, setting this to C(yes) makes the user a system account. This setting cannot be changed on existing users. type: bool comment: description: - Optionally sets the description (aka I(GECOS)) of user account. expires: description: - An expiry time for the user in epoch, it will be ignored on platforms that do not support this. Currently supported on Linux, FreeBSD, and DragonFlyBSD. version_added: '1.9' version_added_collection: ansible.builtin password: description: - Optionally set the user's password to this crypted value. - On Darwin/OS X systems, this value has to be cleartext. Beware of security issues. - See U(http://docs.ansible.com/ansible/faq.html#how-do-i-generate-crypted-passwords-for-the-user-module) for details on various ways to generate these password values. skeleton: description: - Optionally set a home skeleton directory. Requires create_home option! version_added: '2.0' version_added_collection: ansible.builtin move_home: default: 'no' description: - If set to C(yes) when used with C(home=), attempt to move the user's home directory to the specified directory if it isn't there already. type: bool non_unique: default: 'no' description: - Optionally when used with the -u option, this option allows to change the user ID to a non-unique value. type: bool version_added: '1.1' version_added_collection: ansible.builtin create_home: aliases: - createhome default: 'yes' description: - Unless set to C(no), a home directory will be made for the user when the account is created or if the home directory does not exist. - Changed from C(createhome) to C(create_home) in version 2.5. type: bool login_class: description: - Optionally sets the user's login class for FreeBSD, DragonFlyBSD, OpenBSD and NetBSD systems. ssh_key_bits: default: default set by ssh-keygen description: - Optionally specify number of bits in SSH key to create. version_added: '0.9' version_added_collection: ansible.builtin ssh_key_file: default: .ssh/id_rsa description: - Optionally specify the SSH key filename. If this is a relative filename then it will be relative to the user's home directory. version_added: '0.9' version_added_collection: ansible.builtin ssh_key_type: default: rsa description: - Optionally specify the type of SSH key to generate. Available SSH key types will depend on implementation present on target host. version_added: '0.9' version_added_collection: ansible.builtin ssh_key_comment: default: ansible-generated on $HOSTNAME description: - Optionally define the comment for the SSH key. version_added: '0.9' version_added_collection: ansible.builtin update_password: choices: - always - on_create default: always description: - C(always) will update passwords if they differ. C(on_create) will only set the password for newly created users. version_added: '1.3' version_added_collection: ansible.builtin generate_ssh_key: default: 'no' description: - Whether to generate a SSH key for the user in question. This will B(not) overwrite an existing SSH key. type: bool version_added: '0.9' version_added_collection: ansible.builtin ssh_key_passphrase: description: - Set a passphrase for the SSH key. If no passphrase is provided, the SSH key will default to having no passphrase. version_added: '0.9' version_added_collection: ansible.builtin
append: description: Whether or not to append the user to groups returned: When state is 'present' and the user exists sample: true type: bool comment: description: Comment section from passwd file, usually the user name returned: When user exists sample: Agent Smith type: string create_home: description: Whether or not to create the home directory returned: When user does not exist and not check mode sample: true type: bool force: description: Whether or not a user account was forcibly deleted returned: When state is 'absent' and user exists sample: false type: bool group: description: Primary user group ID returned: When user exists sample: 1001 type: int groups: description: List of groups of which the user is a member returned: When C(groups) is not empty and C(state) is 'present' sample: chrony,apache type: string home: description: Path to user's home directory returned: When C(state) is 'present' sample: /home/asmith type: string move_home: description: Whether or not to move an existing home directory returned: When C(state) is 'present' and user exists sample: false type: bool name: description: User account name returned: always sample: asmith type: string password: description: Masked value of the password returned: When C(state) is 'present' and C(password) is not empty sample: NOT_LOGGING_PASSWORD type: string remove: description: Whether or not to remove the user account returned: When C(state) is 'absent' and user exists sample: true type: bool shell: description: User login shell returned: When C(state) is 'present' sample: /bin/bash type: string ssh_fingerprint: description: Fingerprint of generated SSH key returned: When C(generate_ssh_key) is C(True) sample: 2048 SHA256:aYNHYcyVm87Igh0IMEDMbvW0QDlRQfE0aJugp684ko8 ansible-generated on host (RSA) type: string ssh_key_file: description: Path to generated SSH public key file returned: When C(generate_ssh_key) is C(True) sample: /home/asmith/.ssh/id_rsa type: string ssh_public_key: description: Generated SSH public key file returned: When C(generate_ssh_key) is C(True) sample: '''ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC95opt4SPEC06tOYsJQJIuN23BbLMGmYo8ysVZQc4h2DZE9ugbjWWGS1/pweUGjVstgzMkBEeBCByaEf/RJKNecKRPeGd2Bw9DCj/bn5Z6rGfNENKBmo 618mUJBvdlEgea96QGjOwSB7/gmonduC7gsWDMNcOdSE3wJMTim4lddiBx4RgC9yXsJ6Tkz9BHD73MXPpT5ETnse+A3fw3IGVSjaueVnlUyUmOBf7fzmZbhlFVXf2Zi2rFTXqvbdGHKkzpw1U8eB8xFPP7y d5u1u0e6Acju/8aZ/l17IDFiLke5IzlqIMRTEbDwLNeO84YQKWTm9fODHzhYe0yvxqLiK07 ansible-generated on host'' ' type: string stderr: description: Standard error from running commands returned: When stderr is returned by a command that is run sample: Group wheels does not exist type: string stdout: description: Standard output from running commands returned: When standard output is returned by the command that is run sample: null type: string system: description: Whether or not the account is a system account returned: When C(system) is passed to the module and the account does not exist sample: true type: bool uid: description: User ID of the user account returned: When C(UID) is passed to the module sample: 1044 type: int