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`. <br>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](../../../linux/Linux.md), [FreeBSD](../../../bsd/FreeBSD.md), and DragonFlyBSD. Since Ansible 2.6 you can remove the expiry time by specifying a negative value. Currently supported on GNU/[Linux](../../../linux/Linux.md) and [FreeBSD](../../../bsd/FreeBSD.md)                                      |
| **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](../../../applications/network/SSH.md) key for the user in question. This will **not** overwrite an existing [SSH](../../../applications/network/SSH.md) 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](../../../linux/Linux.md)) or plain text password ([macOS](../../../macos/macOS.md)). 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](../../../applications/cli/Shell.md).                                                                                                                                                                                                                                                                                                |
| **ssh_key_bits**       | integer                 | -                                | Optionally specify number of bits in [SSH](../../../applications/network/SSH.md) 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](../../../applications/network/SSH.md) key.                                                                                                                                                                                                                                                                                  |
| **ssh_key_file**       | path                    | .ssh/id_rsa                      | Optionally specify the [SSH](../../../applications/network/SSH.md) 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](../../../applications/network/SSH.md) key.  If no passphrase is provided, the [SSH](../../../applications/network/SSH.md) key will default to having no passphrase.                                                                                                                                                                                                              |
| **ssh_key_type**       | string                  | "rsa"                            | Optionally specify the type of [SSH](../../../applications/network/SSH.md) key to generate.                                                                                                                                                                                                                                                                             |
| **state**              | "present"<br>"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"<br>"on_create" | "always"                         | `always` will update passwords if they differ. <br>`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](../../../applications/cli/Shell.md).                                        |
| **ssh_fingerprint** | string  | When _generate_ssh_key_ is `True`                           | Fingerprint of generated [SSH](../../../applications/network/SSH.md) key.                        |
| **ssh_key_file**    | string  | When _generate_ssh_key_ is `True`                           | Path to generated [SSH](../../../applications/network/SSH.md) private key file.                  |
| **ssh_public_key**  | string  | When _generate_ssh_key_ is `True`                           | Generated [SSH](../../../applications/network/SSH.md) 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
```yaml
- 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
```