Skip to content

Latest commit

 

History

History
579 lines (543 loc) · 24.5 KB

ansible.windows.win_user_module.rst

File metadata and controls

579 lines (543 loc) · 24.5 KB
Raw

ansible.windows.win_user

Manages local Windows user accounts

Synopsis

Parameters

Parameter Choices/Defaults Comments
account_disabled
boolean
    Choices:
  • no
  • yes
yes will disable the user account.
no will clear the disabled flag.
account_locked
boolean
    Choices:
  • no
  • yes
Only no can be set and it will unlock the user account if locked.
description
string
Description of the user.
fullname
string
Full name of the user.
groups
list / elements=string
Adds or removes the user from this comma-separated list of groups, depending on the value of groups_action.
When groups_action is replace and groups is set to the empty string ('groups='), the user is removed from all groups.
Since ansible.windows v1.5.0 it is possible to specify a group using it's security identifier.
groups_action
string
    Choices:
  • add
  • replace ←
  • remove
If add, the user is added to each group in groups where not already a member.
If replace, the user is added as a member of each group in groups and removed from any other groups.
If remove, the user is removed from each group in groups.
home_directory
string
added in 1.0.0
The designated home directory of the user.
login_script
string
added in 1.0.0
The login script of the user.
name
string / required
Name of the user to create, remove or modify.
password
string
Optionally set the user's password to this (plain text) value.
password_expired
boolean
    Choices:
  • no
  • yes
yes will require the user to change their password at next login.
no will clear the expired password flag.
password_never_expires
boolean
    Choices:
  • no
  • yes
yes will set the password to never expire.
no will allow the password to expire.
profile
string
added in 1.0.0
The profile path of the user.
state
string
    Choices:
  • absent
  • present ←
  • query
When absent, removes the user account if it exists.
When present, creates or updates the user account.
When query, retrieves the user account details without making any changes.
update_password
string
    Choices:
  • always ←
  • on_create
always will update passwords if they differ.
on_create will only set the password for newly created users.
user_cannot_change_password
boolean
    Choices:
  • no
  • yes
yes will prevent the user from changing their password.
no will allow the user to change their password.

Notes

Note

  • The return values are based on the user object after the module options have been set. When running in check mode the values will still reflect the existing user settings and not what they would have been changed to.

See Also

.. seealso::

   :ref:`ansible.builtin.user_module`
      The official documentation on the **ansible.builtin.user** module.
   :ref:`ansible.windows.win_domain_membership_module`
      The official documentation on the **ansible.windows.win_domain_membership** module.
   :ref:`community.windows.win_domain_user_module`
      The official documentation on the **community.windows.win_domain_user** module.
   :ref:`ansible.windows.win_group_module`
      The official documentation on the **ansible.windows.win_group** module.
   :ref:`ansible.windows.win_group_membership_module`
      The official documentation on the **ansible.windows.win_group_membership** module.
   :ref:`community.windows.win_user_profile_module`
      The official documentation on the **community.windows.win_user_profile** module.

Examples

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

- name: Ensure user bob is absent
  ansible.windows.win_user:
    name: bob
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
account_disabled
boolean
user exists
Whether the user is disabled.
account_locked
boolean
user exists
Whether the user is locked.
description
string
user exists
The description set for the user.

Sample:
Username for test
fullname
string
user exists
The full name set for the user.

Sample:
Test Username
groups
list
user exists
A list of groups and their ADSI path the user is a member of.

Sample:
[{'name': 'Administrators', 'path': 'WinNT://WORKGROUP/USER-PC/Administrators'}]
name
string
always
The name of the user

Sample:
username
password_expired
boolean
user exists
Whether the password is expired.
password_never_expires
boolean
user exists
Whether the password is set to never expire.

Sample:
True
path
string
user exists
The ADSI path for the user.

Sample:
WinNT://WORKGROUP/USER-PC/username
sid
string
user exists
The SID for the user.

Sample:
S-1-5-21-3322259488-2828151810-3939402796-1001
user_cannot_change_password
boolean
user exists
Whether the user can change their own password.


Status

Authors

  • Paul Durivage (@angstwad)
  • Chris Church (@cchurch)