/lib/ansible/modules/windows/win_user.py

  1#!/usr/bin/python
  2# -*- coding: utf-8 -*-
  3
  4# Copyright: (c) 2014, Matt Martz <matt@sivel.net>, and others
  5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
  6
  7# this is a windows documentation stub.  actual code lives in the .ps1
  8# file of the same name
  9
 10ANSIBLE_METADATA = {'metadata_version': '1.1',
 11                    'status': ['stableinterface'],
 12                    'supported_by': 'core'}
 13
 14DOCUMENTATION = r'''
 15---
 16module: win_user
 17version_added: "1.7"
 18short_description: Manages local Windows user accounts
 19description:
 20     - Manages local Windows user accounts.
 21     - For non-Windows targets, use the M(user) module instead.
 22options:
 23  name:
 24    description:
 25      - Name of the user to create, remove or modify.
 26    type: str
 27    required: yes
 28  fullname:
 29    description:
 30      - Full name of the user.
 31    type: str
 32    version_added: "1.9"
 33  description:
 34    description:
 35      - Description of the user.
 36    type: str
 37    version_added: "1.9"
 38  password:
 39    description:
 40      - Optionally set the user's password to this (plain text) value.
 41    type: str
 42  update_password:
 43    description:
 44      - C(always) will update passwords if they differ.  C(on_create) will
 45        only set the password for newly created users.
 46    type: str
 47    choices: [ always, on_create ]
 48    default: always
 49    version_added: "1.9"
 50  password_expired:
 51    description:
 52      - C(yes) will require the user to change their password at next login.
 53      - C(no) will clear the expired password flag.
 54    type: bool
 55    version_added: "1.9"
 56  password_never_expires:
 57    description:
 58      - C(yes) will set the password to never expire.
 59      - C(no) will allow the password to expire.
 60    type: bool
 61    version_added: "1.9"
 62  user_cannot_change_password:
 63    description:
 64      - C(yes) will prevent the user from changing their password.
 65      - C(no) will allow the user to change their password.
 66    type: bool
 67    version_added: "1.9"
 68  account_disabled:
 69    description:
 70      - C(yes) will disable the user account.
 71      - C(no) will clear the disabled flag.
 72    type: bool
 73    version_added: "1.9"
 74  account_locked:
 75    description:
 76      - C(no) will unlock the user account if locked.
 77    choices: [ 'no' ]
 78    version_added: "1.9"
 79  groups:
 80    description:
 81      - Adds or removes the user from this comma-separated lis of groups,
 82        depending on the value of I(groups_action).
 83      - When I(groups_action) is C(replace) and I(groups) is set to the empty
 84        string ('groups='), the user is removed from all groups.
 85    version_added: "1.9"
 86  groups_action:
 87    description:
 88      - If C(add), the user is added to each group in I(groups) where not
 89        already a member.
 90      - If C(replace), the user is added as a member of each group in
 91        I(groups) and removed from any other groups.
 92      - If C(remove), the user is removed from each group in I(groups).
 93    type: str
 94    choices: [ add, replace, remove ]
 95    default: replace
 96    version_added: "1.9"
 97  state:
 98    description:
 99      - When C(absent), removes the user account if it exists.
100      - When C(present), creates or updates the user account.
101      - When C(query) (new in 1.9), retrieves the user account details
102        without making any changes.
103    type: str
104    choices: [ absent, present, query ]
105    default: present
106seealso:
107- module: user
108- module: win_domain_membership
109- module: win_domain_user
110- module: win_group
111- module: win_group_membership
112- module: win_user_profile
113author:
114    - Paul Durivage (@angstwad)
115    - Chris Church (@cchurch)
116'''
117
118EXAMPLES = r'''
119- name: Ensure user bob is present
120  win_user:
121    name: bob
122    password: B0bP4ssw0rd
123    state: present
124    groups:
125      - Users
126
127- name: Ensure user bob is absent
128  win_user:
129    name: bob
130    state: absent
131'''
132
133RETURN = r'''
134account_disabled:
135  description: Whether the user is disabled.
136  returned: user exists
137  type: bool
138  sample: false
139account_locked:
140  description: Whether the user is locked.
141  returned: user exists
142  type: bool
143  sample: false
144description:
145  description: The description set for the user.
146  returned: user exists
147  type: str
148  sample: Username for test
149fullname:
150  description: The full name set for the user.
151  returned: user exists
152  type: str
153  sample: Test Username
154groups:
155  description: A list of groups and their ADSI path the user is a member of.
156  returned: user exists
157  type: list
158  sample: [
159    {
160      "name": "Administrators",
161      "path": "WinNT://WORKGROUP/USER-PC/Administrators"
162    }
163  ]
164name:
165  description: The name of the user
166  returned: always
167  type: str
168  sample: username
169password_expired:
170  description: Whether the password is expired.
171  returned: user exists
172  type: bool
173  sample: false
174password_never_expires:
175  description: Whether the password is set to never expire.
176  returned: user exists
177  type: bool
178  sample: true
179path:
180  description: The ADSI path for the user.
181  returned: user exists
182  type: str
183  sample: "WinNT://WORKGROUP/USER-PC/username"
184sid:
185  description: The SID for the user.
186  returned: user exists
187  type: str
188  sample: S-1-5-21-3322259488-2828151810-3939402796-1001
189user_cannot_change_password:
190  description: Whether the user can change their own password.
191  returned: user exists
192  type: bool
193  sample: false
194'''