Try SpotterManage user accounts
| "added in version" 0.2 of ansible.builtin"
Authors: Stephen Fromm (@sfromm)
stableinterface | supported by core
pipInstall with pip install ansible==2.9.27
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 (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
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 private 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