ansible / ansible.builtin / v2.15.10 / module / user Manage user accounts | "added in version" 0.2 of ansible.builtin" Authors: Stephen Fromm (@sfromm)ansible.builtin.user (v2.15.10) — module
pip
Install with pip install ansible-core==2.15.10
Manage user accounts and user attributes.
For Windows targets, use the M(ansible.windows.win_user) module instead.
- 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: 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
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 authentication when you want to manipulate the local users (in other words, 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. 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). - See notes for details on how other operating systems determine the default shell by the underlying tool. 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. - See this L(FAQ entry,https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#running-on-macos-as-a-target) for additional requirements when removing users on macOS systems. type: str umask: description: - Sets the umask of the user. - Does nothing when used with other platforms. - Currently supported on Linux. - Requires C(local) is omitted or False. type: str version_added: '2.12' version_added_collection: ansible.builtin append: default: false description: - If C(true), add the user to the groups specified in C(groups). - If C(false), 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. - By default, the user is removed from all other groups. Configure C(append) to modify this. - 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. elements: str type: list hidden: description: - macOS only, optionally hide the user from the login window and system preferences. - The default will be C(true) 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(true) 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 by specifying 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: - If provided, set the user's password to the provided encrypted hash (Linux) or plain text password (macOS). - B(Linux/Unix/POSIX:) Enter the hashed password as the value. - See L(FAQ entry,https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module) 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 C('!') or C('*'). - To create an account with a locked/disabled password on OpenBSD, set this to C('*************'). - B(OS X/macOS:) Enter the cleartext password as the value. Be sure to take relevant security precautions. 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(true) 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(false), 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: description: - Optionally specify number of bits in SSH key to create. - The default value depends on ssh-keygen. 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 (C(usermod -L), C(usermod -U), C(pw lock)). - 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 C(False) in order to unlock a currently locked password. The absence of this parameter will not unlock a password. - 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 password_expire_max: description: - Maximum number of days between password change. - Supported on Linux only. type: int version_added: '2.11' version_added_collection: ansible.builtin password_expire_min: description: - Minimum number of days between password change. - Supported on Linux only. type: int version_added: '2.11' version_added_collection: ansible.builtin
append: description: Whether or not to append the user to groups. returned: When state is C(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 I(state) is C(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 I(groups) is not empty and I(state) is C(present) sample: chrony,apache type: str home: description: Path to user's home directory. returned: When I(state) is C(present) sample: /home/asmith type: str move_home: description: Whether or not to move an existing home directory. returned: When I(state) is C(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 I(state) is C(present) and I(password) is not empty sample: NOT_LOGGING_PASSWORD type: str remove: description: Whether or not to remove the user account. returned: When I(state) is C(absent) and user exists sample: true type: bool shell: description: User login shell. returned: When I(state) is C(present) sample: /bin/bash type: str ssh_fingerprint: description: Fingerprint of generated SSH key. returned: When I(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 private key file. returned: When I(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 I(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 I(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 I(uid) is passed to the module sample: 1044 type: int