ansible / ansible.builtin / v2.8.13 / module / user Manage user accounts | "added in version" 0.2 of ansible.builtin" Authors: Stephen Fromm (@sfromm) stableinterface | supported by coreansible.builtin.user (v2.8.13) — module
pip
Install with pip install ansible==2.8.13
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
- name: Starting at Ansible 2.6, modify user, remove expiry time user: name: james18 expires: -1
uid: description: - Optionally sets the I(UID) of the user. type: int home: description: - Optionally set the user's home directory. type: path name: aliases: - user description: - Name of the user to create, remove or modify. required: true type: str role: description: - Sets the role of the user. - Does nothing when used with other platforms. - Can set multiple roles using comma separation. - To delete all roles, use C(role=''). - Currently supported on Illumos/Solaris. type: str version_added: '2.8' version_added_collection: ansible.builtin force: default: false description: - This only affects C(state=absent), it forces removal of the user and associated directories on supported platforms. - The behavior is the same as C(userdel --force), check the man page for C(userdel) on your system for details and support. - When used with C(generate_ssh_key=yes) this forces an existing key to be overwritten. type: bool group: description: - Optionally sets the user's primary group (takes a group name). type: str local: default: false 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 C(luseradd) instead of C(useradd)). - This will check C(/etc/passwd) for an existing account before invoking commands. If the local account database exists somewhere other than C(/etc/passwd), this setting will not work properly. - This requires that the above commands as well as C(/etc/passwd) must exist on the target host, otherwise it will be a fatal error. - Mutually exclusive with C(groups) and C(append) type: bool version_added: '2.4' version_added_collection: ansible.builtin shell: description: - Optionally set the user's shell. - On macOS, before Ansible 2.5, the default shell for non-system users was C(/usr/bin/false). Since Ansible 2.5, the default shell for non-system users on macOS is C(/bin/bash). - On other operating systems, the default shell is determined by the underlying tool being used. See Notes for details. type: str 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. type: str append: default: false 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. - Mutually exclusive with C(local) type: bool groups: description: - List of groups user will be added to. When set to an empty string C(''), the user is removed from all groups except the primary group. - Before Ansible 2.3, the only input format allowed was a comma separated string. - Mutually exclusive with C(local) type: list hidden: description: - macOS only, optionally hide the user from the login window and system preferences. - The default will be C(yes) if the I(system) option is used. type: bool version_added: '2.6' version_added_collection: ansible.builtin remove: default: false description: - This only affects C(state=absent), it attempts to remove directories associated with the user. - The behavior is the same as C(userdel --remove), check the man page for details and support. type: bool seuser: description: - Optionally sets the seuser type (user_u) on selinux enabled systems. type: str version_added: '2.1' version_added_collection: ansible.builtin system: default: false description: - When creating an account C(state=present), 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. type: str expires: description: - 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 specify a negative value. Currently supported on GNU/Linux and FreeBSD. type: float version_added: '1.9' version_added_collection: ansible.builtin profile: description: - Sets the profile of the user. - Does nothing when used with other platforms. - Can set multiple profiles using comma separation. - To delete all the profiles, use C(profile=''). - Currently supported on Illumos/Solaris. type: str version_added: '2.8' version_added_collection: ansible.builtin password: description: - Optionally set the user's password to this crypted value. - On macOS systems, this value has to be cleartext. Beware of security issues. - To create a disabled account on Linux systems, set this to C('!') or C('*'). - To create a disabled account on OpenBSD, set this to C('*************'). - See U(https://docs.ansible.com/ansible/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module) for details on various ways to generate these password values. type: str skeleton: description: - Optionally set a home skeleton directory. - Requires C(create_home) option! type: str version_added: '2.0' version_added_collection: ansible.builtin move_home: default: false description: - 'If set to C(yes) when used with C(home: ), attempt to move the user''s old home directory to the specified directory if it isn''t there already and the old home exists.' type: bool non_unique: default: false 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: true 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 Ansible 2.5. type: bool login_class: description: - Optionally sets the user's login class, a feature of most BSD OSs. type: str ssh_key_bits: default: default set by ssh-keygen description: - Optionally specify number of bits in SSH key to create. type: int version_added: '0.9' version_added_collection: ansible.builtin ssh_key_file: description: - 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 I(.ssh/id_rsa). type: path 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. type: str version_added: '0.9' version_added_collection: ansible.builtin authorization: description: - Sets the authorization of the user. - Does nothing when used with other platforms. - Can set multiple authorizations using comma separation. - To delete all authorizations, use C(authorization=''). - Currently supported on Illumos/Solaris. type: str version_added: '2.8' version_added_collection: ansible.builtin password_lock: description: - Lock the password (usermod -L, pw lock, usermod -C). - BUT implementation differs on different platforms, this option does not always mean the user cannot login via other methods. - This option does not disable the user, only lock the password. Do not change the password in the same task. - Currently supported on Linux, FreeBSD, DragonFlyBSD, NetBSD, OpenBSD. type: bool version_added: '2.6' version_added_collection: ansible.builtin ssh_key_comment: default: ansible-generated on $HOSTNAME description: - Optionally define the comment for the SSH key. type: str 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. type: str version_added: '1.3' version_added_collection: ansible.builtin generate_ssh_key: default: false description: - Whether to generate a SSH key for the user in question. - This will B(not) overwrite an existing SSH key unless used with C(force=yes). 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. type: str 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: str 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: str home: description: Path to user's home directory returned: When C(state) is 'present' sample: /home/asmith type: str 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: str password: description: Masked value of the password returned: When C(state) is 'present' and C(password) is not empty sample: NOT_LOGGING_PASSWORD type: str 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: str 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: str 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: str 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: str 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: str stdout: description: Standard output from running commands returned: When standard output is returned by the command that is run sample: null type: str 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