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

Install Ansible via pip

Install with pip install ansible==2.5.6

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

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

groups:
    description:
    - Adds or removes the user from this comma-separated lis 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.
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

fullname:
    default: null
    description:
    - Full name of the user
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

password:
    default: null
    description:
    - Optionally set the user's password to this (plain text) value.
    required: false

description:
    default: null
    description:
    - Description of the user
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

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

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

account_disabled:
    choices:
    - 'yes'
    - 'no'
    default: null
    description:
    - C(yes) will disable the user account.  C(no) will clear the disabled flag.
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

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

password_never_expires:
    choices:
    - 'yes'
    - 'no'
    default: null
    description:
    - C(yes) will set the password to never expire.  C(no) will allow the password to
      expire.
    required: false
    version_added: '1.9'
    version_added_collection: ansible.builtin

user_cannot_change_password:
    choices:
    - 'yes'
    - 'no'
    default: null
    description:
    - C(yes) will prevent the user from changing their password.  C(no) will allow the
      user to change their password.
    required: false
    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