ansible.builtin.user (v2.4.0.0-1) — module

Install Ansible via pip

Install with pip install ansible==2.4.0.0.post1

Description

Manage user accounts and user attributes.

For Windows targets, use the M(win_user) module instead.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Add the user 'johnd' with a specific uid and a primary group of 'admin'
- user:
    name: johnd
    comment: "John Doe"
    uid: 1040
    group: admin

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# Remove the user 'johnd'
- user:
    name: johnd
    state: absent
    remove: yes

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# added a consultant whose account you want to expire
- user:
    name: james18
    shell: /bin/zsh
    groups: developers
    expires: 1422403387

Inputs

    
uid:
    description:
    - Optionally sets the I(UID) of the user.
    required: false

home:
    description:
    - Optionally set the user's home directory.
    required: false

name:
    aliases:
    - user
    description:
    - Name of the user to create, remove or modify.
    required: true

force:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - When used with C(state=absent), behavior is as with C(userdel --force).
    required: false

group:
    description:
    - Optionally sets the user's primary group (takes a group name).
    required: false

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 `luseradd` instead of `useradd`.
    - This requires that these commands exist on the targeted host, otherwise it will
      be a fatal error.
    required: false
    version_added: '2.4'
    version_added_collection: ansible.builtin

shell:
    description:
    - Optionally set the user's shell.
    required: false

state:
    choices:
    - present
    - absent
    default: present
    description:
    - Whether the account should exist or not, taking action if the state is different
      from what is stated.
    required: false

append:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - If C(yes), will only add groups, not set them to just the list in I(groups).
    required: false

groups:
    description:
    - Puts the user in  list of groups. When set to the empty string ('groups='), the
      user is removed from all groups except the primary group.
    - Before version 2.3, the only input format allowed was a 'comma separated string',
      now it should be able to accept YAML lists also.
    required: false

remove:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - When used with C(state=absent), behavior is as with C(userdel --remove).
    required: false

seuser:
    description:
    - Optionally sets the seuser type (user_u) on selinux enabled systems.
    required: false
    version_added: '2.1'
    version_added_collection: ansible.builtin

system:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - When creating an account, setting this to C(yes) makes the user a system account.  This
      setting cannot be changed on existing users.
    required: false

comment:
    description:
    - Optionally sets the description (aka I(GECOS)) of user account.
    required: false

expires:
    default: None
    description:
    - An expiry time for the user in epoch, it will be ignored on platforms that do not
      support this. Currently supported on Linux and FreeBSD.
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

password:
    description:
    - Optionally set the user's password to this crypted value.  See the user example
      in the github examples directory for what this looks like in a playbook. See U(http://docs.ansible.com/ansible/faq.html#how-do-i-generate-crypted-passwords-for-the-user-module)
      for details on various ways to generate these password values. Note on Darwin system,
      this value has to be cleartext. Beware of security issues.
    required: false

skeleton:
    description:
    - Optionally set a home skeleton directory. Requires createhome option!
    required: false
    version_added: '2.0'
    version_added_collection: ansible.builtin

move_home:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - If set to C(yes) when used with C(home=), attempt to move the user's home directory
      to the specified directory if it isn't there already.
    required: false

createhome:
    choices:
    - 'yes'
    - 'no'
    default: 'yes'
    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.
    required: false

non_unique:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - Optionally when used with the -u option, this option allows to change the user ID
      to a non-unique value.
    required: false
    version_added: '1.1'
    version_added_collection: ansible.builtin

login_class:
    description:
    - Optionally sets the user's login class for FreeBSD, OpenBSD and NetBSD systems.
    required: false

ssh_key_bits:
    default: default set by ssh-keygen
    description:
    - Optionally specify number of bits in SSH key to create.
    required: false
    version_added: '0.9'
    version_added_collection: ansible.builtin

ssh_key_file:
    default: .ssh/id_rsa
    description:
    - Optionally specify the SSH key filename. If this is a relative filename then it
      will be relative to the user's home directory.
    required: false
    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.
    required: false
    version_added: '0.9'
    version_added_collection: ansible.builtin

ssh_key_comment:
    default: ansible-generated on $HOSTNAME
    description:
    - Optionally define the comment for the SSH key.
    required: false
    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.
    required: false
    version_added: '1.3'
    version_added_collection: ansible.builtin

generate_ssh_key:
    choices:
    - 'yes'
    - 'no'
    default: 'no'
    description:
    - Whether to generate a SSH key for the user in question. This will B(not) overwrite
      an existing SSH key.
    required: false
    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.
    required: false
    version_added: '0.9'
    version_added_collection: ansible.builtin