/lib/ansible/modules/windows/win_user_profile.py

  1#!/usr/bin/python
  2# -*- coding: utf-8 -*-
  3
  4# Copyright: (c) 2019, Ansible Project
  5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
  6
  7ANSIBLE_METADATA = {'metadata_version': '1.1',
  8                    'status': ['preview'],
  9                    'supported_by': 'community'}
 10
 11DOCUMENTATION = r'''
 12---
 13module: win_user_profile
 14version_added: '2.8'
 15short_description: Manages the Windows user profiles.
 16description:
 17- Used to create or remove user profiles on a Windows host.
 18- This can be used to create a profile before a user logs on or delete a
 19  profile when removing a user account.
 20- A profile can be created for both a local or domain account.
 21options:
 22  name:
 23    description:
 24    - Specifies the base name for the profile path.
 25    - When I(state) is C(present) this is used to create the profile for
 26      I(username) at a specific path within the profile directory.
 27    - This cannot be used to specify a path outside of the profile directory
 28      but rather it specifies a folder(s) within this directory.
 29    - If a profile for another user already exists at the same path, then a 3
 30      digit incremental number is appended by Windows automatically.
 31    - When I(state) is C(absent) and I(username) is not set, then the module
 32      will remove all profiles that point to the profile path derived by this
 33      value.
 34    - This is useful if the account no longer exists but the profile still
 35      remains.
 36    type: str
 37  remove_multiple:
 38    description:
 39    - When I(state) is C(absent) and the value for I(name) matches multiple
 40      profiles the module will fail.
 41    - Set this value to C(yes) to force the module to delete all the profiles
 42      found.
 43    default: no
 44    type: bool
 45  state:
 46    description:
 47    - Will ensure the profile exists when set to C(present).
 48    - When creating a profile the I(username) option must be set to a valid
 49      account.
 50    - Will remove the profile(s) when set to C(absent).
 51    - When removing a profile either I(username) must be set to a valid
 52      account, or I(name) is set to the profile's base name.
 53    default: present
 54    choices:
 55    - absent
 56    - present
 57    type: str
 58  username:
 59    description:
 60    - The account name of security identifier (SID) for the profile.
 61    - This must be set when I(state) is C(present) and must be a valid account
 62      or the SID of a valid account.
 63    - When I(state) is C(absent) then this must still be a valid account number
 64      but the SID can be a deleted user's SID.
 65seealso:
 66- module: win_user
 67- module: win_domain_user
 68author:
 69- Jordan Borean (@jborean93)
 70'''
 71
 72EXAMPLES = r'''
 73- name: Create a profile for an account
 74  win_user_profile:
 75    username: ansible-account
 76    state: present
 77
 78- name: Create a profile for an account at C:\Users\ansible
 79  win_user_profile:
 80    username: ansible-account
 81    name: ansible
 82    state: present
 83
 84- name: Remove a profile for a still valid account
 85  win_user_profile:
 86    username: ansible-account
 87    state: absent
 88
 89- name: Remove a profile for a deleted account
 90  win_user_profile:
 91    name: ansible
 92    state: absent
 93
 94- name: Remove a profile for a deleted account based on the SID
 95  win_user_profile:
 96    username: S-1-5-21-3233007181-2234767541-1895602582-1305
 97    state: absent
 98
 99- name: Remove multiple profiles that exist at the basename path
100  win_user_profile:
101    name: ansible
102    state: absent
103    remove_multiple: yes
104'''
105
106RETURN = r'''
107path:
108  description: The full path to the profile for the account. This will be null
109    if C(state=absent) and no profile was deleted.
110  returned: always
111  type: str
112  sample: C:\Users\ansible
113'''