win_user – Manages local Windows user accounts
Synopsis
- Manages local Windows user accounts.
- For non-Windows targets, use the user module instead.
Parameters
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| account_disabled
boolean
|
|
yes will disable the user account.
no will clear the disabled flag.
|
| account_locked
-
|
|
no will unlock the user account if locked.
|
| description
string
|
Description of the user.
|
|
| fullname
string
|
Full name of the user.
|
|
| groups
-
|
Adds or removes the user from this comma-separated lis 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.
|
|
| groups_action
string
|
|
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.
|
| 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
|
|
yes will require the user to change their password at next login.
no will clear the expired password flag.
|
| password_never_expires
boolean
|
|
yes will set the password to never expire.
no will allow the password to expire.
|
| state
string
|
|
When
absent, removes the user account if it exists.
When
present, creates or updates the user account.
When query (new in 1.9), retrieves the user account details without making any changes.
|
| update_password
string
|
|
always will update passwords if they differ. on_create will only set the password for newly created users.
|
| user_cannot_change_password
boolean
|
|
yes will prevent the user from changing their password.
no will allow the user to change their password.
|
See Also
See also
- user – Manage user accounts
- The official documentation on the user module.
- win_domain_membership – Manage domain/workgroup membership for a Windows host
- The official documentation on the win_domain_membership module.
- win_domain_user – Manages Windows Active Directory user accounts
- The official documentation on the win_domain_user module.
- win_group – Add and remove local groups
- The official documentation on the win_group module.
- win_group_membership – Manage Windows local group membership
- The official documentation on the win_group_membership module.
- win_user_profile – Manages the Windows user profiles
- The official documentation on the win_user_profile module.
Examples
- name: Ensure user bob is present
win_user:
name: bob
password: B0bP4ssw0rd
state: present
groups:
- Users
- name: Ensure user bob is absent
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
- This module is guaranteed to have no backward incompatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Paul Durivage (@angstwad)
- Chris Church (@cchurch)
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/win_user_module.html