ansible.builtin.win_user (v2.9.27) — module

Install Ansible via pip

Install with pip install ansible==2.9.27

Description

Manages local Windows user accounts.

For non-Windows targets, use the M(user) module instead.

Usage examples

Scanned by Steampunk Spotter

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

- name: Ensure user bob is present
  win_user:
    name: bob
    password: B0bP4ssw0rd
    state: present
    groups:
      - Users

Scanned by Steampunk Spotter

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

- name: Ensure user bob is absent
  win_user:
    name: bob
    state: absent

Inputs

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

state:
    choices:
    - absent
    - present
    - query
    default: present
    description:
    - When C(absent), removes the user account if it exists.
    - When C(present), creates or updates the user account.
    - When C(query) (new in 1.9), retrieves the user account details without making any
      changes.
    type: str

groups:
    description:
    - Adds or removes the user from this comma-separated list of groups, depending on
      the value of I(groups_action).
    - When I(groups_action) is C(replace) and I(groups) is set to the empty string ('groups='),
      the user is removed from all groups.
    version_added: '1.9'
    version_added_collection: ansible.builtin

fullname:
    description:
    - Full name of the user.
    type: str
    version_added: '1.9'
    version_added_collection: ansible.builtin

password:
    description:
    - Optionally set the user's password to this (plain text) value.
    type: str

description:
    description:
    - Description of the user.
    type: str
    version_added: '1.9'
    version_added_collection: ansible.builtin

groups_action:
    choices:
    - add
    - replace
    - remove
    default: replace
    description:
    - If C(add), the user is added to each group in I(groups) where not already a member.
    - If C(replace), the user is added as a member of each group in I(groups) and removed
      from any other groups.
    - If C(remove), the user is removed from each group in I(groups).
    type: str
    version_added: '1.9'
    version_added_collection: ansible.builtin

account_locked:
    choices:
    - 'no'
    description:
    - C(no) will unlock the user account if locked.
    version_added: '1.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.9'
    version_added_collection: ansible.builtin

account_disabled:
    description:
    - C(yes) will disable the user account.
    - C(no) will clear the disabled flag.
    type: bool
    version_added: '1.9'
    version_added_collection: ansible.builtin

password_expired:
    description:
    - C(yes) will require the user to change their password at next login.
    - C(no) will clear the expired password flag.
    type: bool
    version_added: '1.9'
    version_added_collection: ansible.builtin

password_never_expires:
    description:
    - C(yes) will set the password to never expire.
    - C(no) will allow the password to expire.
    type: bool
    version_added: '1.9'
    version_added_collection: ansible.builtin

user_cannot_change_password:
    description:
    - C(yes) will prevent the user from changing their password.
    - C(no) will allow the user to change their password.
    type: bool
    version_added: '1.9'
    version_added_collection: ansible.builtin

Outputs

account_disabled:
  description: Whether the user is disabled.
  returned: user exists
  sample: false
  type: bool
account_locked:
  description: Whether the user is locked.
  returned: user exists
  sample: false
  type: bool
description:
  description: The description set for the user.
  returned: user exists
  sample: Username for test
  type: str
fullname:
  description: The full name set for the user.
  returned: user exists
  sample: Test Username
  type: str
groups:
  description: A list of groups and their ADSI path the user is a member of.
  returned: user exists
  sample:
  - name: Administrators
    path: WinNT://WORKGROUP/USER-PC/Administrators
  type: list
name:
  description: The name of the user
  returned: always
  sample: username
  type: str
password_expired:
  description: Whether the password is expired.
  returned: user exists
  sample: false
  type: bool
password_never_expires:
  description: Whether the password is set to never expire.
  returned: user exists
  sample: true
  type: bool
path:
  description: The ADSI path for the user.
  returned: user exists
  sample: WinNT://WORKGROUP/USER-PC/username
  type: str
sid:
  description: The SID for the user.
  returned: user exists
  sample: S-1-5-21-3322259488-2828151810-3939402796-1001
  type: str
user_cannot_change_password:
  description: Whether the user can change their own password.
  returned: user exists
  sample: false
  type: bool

See also

• user
• win_domain_membership
• win_domain_user
• win_group
• win_group_membership
• win_user_profile