101 lines
No EOL
14 KiB
Markdown
101 lines
No EOL
14 KiB
Markdown
# 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
|
||
``` |