knowledge/technology/tools/Ansible/modules/ansible.builtin.user.md

ansible.builtin.user

Manage user accounts and user attributes.

Parameter

Parameter	Type	Default	Description
append	boolean	false	If true, add the user to the groups specified in groups. If false, user will only be added to the groups specified in groups, removing them from all other groups.
create_home	boolean	true	Unless set to false, a home directory will be made for the user when the account is created or if the home directory does not exist.
expires	float	-	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
force	boolean	false	This only affects state=absent, it forces removal of the user and associated directories on supported platforms. The behavior is the same as userdel --force, check the man page for userdel on your system for details and support. When used with generate_ssh_key=yes this forces an existing key to be overwritten.
generate_ssh_key	boolean	false	Whether to generate a SSH key for the user in question. This will not overwrite an existing SSH key unless used with force=yes.
group	string	-	Optionally sets the user’s primary group (takes a group name).
groups	list / elements=string	-	List of groups user will be added to. By default, the user is removed from all other groups. Configure append to modify this. When set to an empty string '', the user is removed from all groups except the primary group.
home	path	-	Optionally set the user’s home directory.
move_home	boolean	false	If set to true when used with 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.
name	string / required	-	Name of the user to create, remove or modify.
password	string	-	If provided, set the user’s password to the provided encrypted hash (Linux) or plain text password (macOS). You can generate the encrypted hash with the mkpasswd command.
remove	boolean	false	This only affects state=absent, it attempts to remove directories associated with the user. The behavior is the same as userdel --remove, check the man page for details and support.
shell	string	-	Optionally set the user’s shell.
ssh_key_bits	integer	-	Optionally specify number of bits in SSH key to create. The default value depends on ssh-keygen.
ssh_key_comment	string	"ansible-generated on $HOSTNAME"	Optionally define the comment for the SSH key.
ssh_key_file	path	.ssh/id_rsa	Optionally specify the SSH key filename. If this is a relative filename then it will be relative to the user’s home directory.
ssh_key_passphrase	string	-	Set a passphrase for the SSH key. If no passphrase is provided, the SSH key will default to having no passphrase.
ssh_key_type	string	"rsa"	Optionally specify the type of SSH key to generate.
state	"present" "absent"	present	Whether the account should exist or not, taking action if the state is different from what is stated.
system	boolean	false	When creating an account state=present, setting this to true makes the user a system account.
uid	integer	-	Optionally sets the UID of the user.
update_password	"always" "on_create"	"always"	always will update passwords if they differ. on_create will only set the password for newly created users.

Return Values

Value	Type	When	Description
append	boolean	When state is present and the user exists	Whether or not to append the user to groups.
comment	string	When user exists	Comment section from passwd file, usually the user name.
create_home	boolean	When user does not exist and not check mode	Whether or not to create the home directory.
force	boolean	When state is absent and user exists	Whether or not a user account was forcibly deleted.
group	integer	When user exists	Primary user group ID
groups	string	When groups is not empty and state is present	List of groups of which the user is a member.
home	string	When state is present	Path to user’s home directory.
move_home	boolean	When state is present and user exists	Whether or not to move an existing home directory.
name	string	always	User account name.
remove	boolean	When state is absent and user exists	Whether or not to remove the user account.
shell	string	When state is present	User login shell.
ssh_fingerprint	string	When generate_ssh_key is True	Fingerprint of generated SSH key.
ssh_key_file	string	When generate_ssh_key is True	Path to generated SSH private key file.
ssh_public_key	string	When generate_ssh_key is True	Generated SSH public key file.
stderr	string	When stderr is returned by a command that is run	Standard error from running commands.
stdout	string	When standard output is returned by the command that is run	Standard output from running commands.
uid	integer	When uid is passed to the module	User ID of the user account.

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: 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