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

https://github.com/debfx/ansible · Python · 113 lines · 104 code · 5 blank · 4 comment · 0 complexity · 293ee9d9e968d34b8005bfa953379dbc MD5 · raw file

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