1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2020, Brian Scholer <@briantist>
5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7DOCUMENTATION = r'''
8---
9module: win_pssession_configuration
10short_description: Manage PSSession Configurations
11description:
12  - Register, unregister, and modify PSSession Configurations for PowerShell remoting.
13options:
14  name:
15    description:
16      - The name of the session configuration to manage.
17    type: str
18    required: yes
19  state:
20    description:
21      - The desired state of the configuration.
22    type: str
23    choices:
24      - present
25      - absent
26    default: present
27  guid:
28    description:
29      - The GUID (UUID) of the session configuration file.
30      - This value is metadata, so it only matters if you use it externally.
31      - If not set, a value will be generated automatically.
32      - Acceptable GUID formats are flexible. Any string of 32 hexadecimal digits will be accepted, with all hyphens C(-) and opening/closing C({}) ignored.
33      - See also I(lenient_config_fields).
34    type: raw
35  schema_version:
36    description:
37      - The schema version of the session configuration file.
38      - If not set, a value will be generated automatically.
39      - Must be a valid .Net System.Version string.
40    type: raw
41  author:
42    description:
43      - The author of the session configuration.
44      - This value is metadata and does not affect the functionality of the session configuration.
45      - If not set, a value may be generated automatically.
46      - See also I(lenient_config_fields).
47    type: str
48  description:
49    description:
50      - The description of the session configuration.
51      - This value is metadata and does not affect the functionality of the session configuration.
52      - See also I(lenient_config_fields).
53    type: str
54  company_name:
55    description:
56      - The company that authored the session configuration.
57      - This value is metadata and does not affect the functionality of the session configuration.
58      - If not set, a value may be generated automatically.
59      - See also I(lenient_config_fields).
60    type: str
61  copyright:
62    description:
63      - The copyright statement of the session configuration.
64      - This value is metadata and does not affect the functionality of the session configuration.
65      - If not set, a value may be generated automatically.
66      - See also I(lenient_config_fields).
67    type: str
68  session_type:
69    description:
70      - Controls what type of session this is.
71    type: str
72    choices:
73      - default
74      - empty
75      - restricted_remote_server
76  transcript_directory:
77    description:
78      - Automatic session transcripts will be written to this directory.
79    type: path
80  run_as_virtual_account:
81    description:
82      - If C(yes) the session runs as a virtual account.
83      - Do not use I(run_as_credential_username) and I(run_as_credential_password) to specify a virtual account.
84    type: bool
85  run_as_virtual_account_groups:
86    description:
87      - If I(run_as_virtual_account=yes) this is a list of groups to add the virtual account to.
88    type: list
89    elements: str
90  mount_user_drive:
91      description:
92        - If C(yes) the session creates and mounts a user-specific PSDrive for use with file transfers.
93      type: bool
94  user_drive_maximum_size:
95    description:
96      - The maximum size of the user drive in bytes.
97      - Must fit into an Int64.
98    type: raw
99  group_managed_service_account:
100    description:
101      - If the session will run as a group managed service account (gMSA) then this is the name.
102      - Do not use I(run_as_credential_username) and I(run_as_credential_password) to specify a gMSA.
103    type: str
104  scripts_to_process:
105    description:
106      - A list of paths to script files ending in C(.ps1) that should be applied to the session.
107    type: list
108    elements: str
109  role_definitions:
110    description:
111      - A dict defining the roles for JEA sessions.
112      - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/session-configurations#role-definitions).
113    type: dict
114  required_groups:
115    description:
116      - For JEA sessions, defines conditional access rules about which groups a connecting user must belong to.
117      - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/session-configurations#conditional-access-rules).
118    type: dict
119  language_mode:
120    description:
121      - Determines the language mode of the PowerShell session.
122    type: str
123    choices:
124      - no_language
125      - restricted_language
126      - constrained_language
127      - full_language
128  execution_policy:
129    description:
130      - The execution policy controlling script execution in the PowerShell session.
131    type: str
132    choices:
133      - default
134      - remote_signed
135      - restricted
136      - undefined
137      - unrestricted
138  powershell_version:
139    description:
140      - The minimum required PowerShell version for this session.
141      - Must be a valid .Net System.Version string.
142    type: raw
143  modules_to_import:
144    description:
145      - A list of modules that should be imported into the session.
146      - Any valid PowerShell module spec can be used here, so simple str names or dicts can be used.
147      - If a dict is used, no snake_case conversion is done, so the original PowerShell names must be used.
148    type: list
149    elements: raw
150  visible_aliases:
151    description:
152      - The aliases that can be used in the session.
153      - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities).
154    type: list
155    elements: str
156  visible_cmdlets:
157    description:
158      - The cmdlets that can be used in the session.
159      - The elements can be simple names or complex command specifications.
160      - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities).
161    type: list
162    elements: raw
163  visible_functions:
164    description:
165      - The functions that can be used in the session.
166      - The elements can be simple names or complex command specifications.
167      - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities).
168    type: list
169    elements: raw
170  visible_external_commands:
171    description:
172      - The external commands and scripts that can be used in the session.
173      - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities).
174    type: list
175    elements: str
176  alias_definitions:
177    description:
178      - A dict that defines aliases for each session.
179    type: dict
180  function_definitions:
181    description:
182      - A dict that defines functions for each session.
183    type: dict
184  variable_definitions:
185    description:
186      - A list of dicts where each elements defines a variable for each session.
187    type: list
188    elements: dict
189  environment_variables:
190    description:
191      - A dict that defines environment variables for each session.
192    type: dict
193  types_to_process:
194    description:
195      - Paths to type definition files to process for each session.
196    type: list
197    elements: path
198  formats_to_process:
199    description:
200      - Paths to format definition files to process for each session.
201    type: list
202    elements: path
203  assemblies_to_load:
204    description:
205      - The assemblies that should be loaded into each session.
206    type: list
207    elements: str
208  processor_architecure:
209    description:
210      - The processor architecture of the session (32 bit vs. 64 bit).
211    type: str
212    choices:
213      - amd64
214      - x86
215  access_mode:
216    description:
217      - Controls whether the session configuration allows connection from the C(local) machine only, both local and C(remote), or none (C(disabled)).
218    type: str
219    choices:
220      - disabled
221      - local
222      - remote
223  use_shared_process:
224    description:
225      - If C(yes) then the session shares a process for each session.
226    type: bool
227  thread_apartment_state:
228    description:
229      - The apartment state for the PowerShell session.
230    type: str
231    choices:
232      - mta
233      - sta
234  thread_options:
235    description:
236      - Sets thread options for the session.
237    type: str
238    choices:
239      - default
240      - reuse_thread
241      - use_current_thread
242      - use_new_thread
243  startup_script:
244    description:
245      - A script that gets run on session startup.
246    type: path
247  maximum_received_data_size_per_command_mb:
248    description:
249      - Sets the maximum received data size per command in MB.
250      - Must fit into a double precision floating point value.
251    type: raw
252  maximum_received_object_size_mb:
253    description:
254      - Sets the maximum object size in MB.
255      - Must fit into a double precision floating point value.
256    type: raw
257  security_descriptor_sddl:
258    description:
259      - An SDDL string that controls which users and groups can connect to the session.
260      - If I(role_definitions) is specified the security descriptor will be set based on that.
261      - If this option is not specified the default security descriptor will be applied.
262    type: str
263  run_as_credential_username:
264    description:
265      - Used to set a RunAs account for the session. All commands executed in the session will be run as this user.
266      - To use a gMSA, see I(group_managed_service_account).
267      - To use a virtual account, see I(run_as_virtual_account) and I(run_as_virtual_account_groups).
268      - Status will always be C(changed) when a RunAs credential is set because the password cannot be retrieved for comparison.
269    type: str
270  run_as_credential_password:
271    description:
272      - The password for I(run_as_credential_username).
273    type: str
274  lenient_config_fields:
275    description:
276      - Some fields used in the session configuration do not affect its function, and are sometimes auto-generated when not specified.
277      - To avoid unnecessarily changing the configuration on each run, the values of these options will only be enforced when they are explicitly specified.
278    type: list
279    elements: str
280    default:
281      - guid
282      - author
283      - company_name
284      - copyright
285      - description
286  async_timeout:
287    description:
288      - Sets a timeout for how long in seconds to wait for asynchronous module execution and waiting for the connection to recover.
289      - Replicates the functionality of the C(async) keyword.
290      - Has no effect in check mode.
291    type: int
292    default: 300
293  async_poll:
294    description:
295      - Sets a delay in seconds between each check of the asynchronous execution status.
296      - Replicates the functionality of the C(poll) keyword.
297      - Has no effect in check mode.
298      - I(async_poll=0) is not supported.
299    type: int
300    default: 1
301notes:
302  - This module will restart the WinRM service on any change. This will terminate all WinRM connections including those by other Ansible runs.
303  - Internally this module uses C(async) when not in check mode to ensure things go smoothly when restarting the WinRM service.
304  - The standard C(async) and C(poll) keywords cannot be used; instead use the I(async_timeout) and I(async_poll) options to control asynchronous execution.
305  - Options that don't list a default value here will use the defaults of C(New-PSSessionConfigurationFile) and C(Register-PSSessionConfiguration).
306  - If a value can be specified in both a session config file and directly in the session options, this module will prefer the setting be in the config file.
307seealso:
308  - name: C(New-PSSessionConfigurationFile) Reference
309    description: Details and defaults for options that end up in the session configuration file.
310    link: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/new-pssessionconfigurationfile
311  - name: C(Register-PSSessionConfiguration) Reference
312    description: Details and defaults for options that are not specified in the session config file.
313    link: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/register-pssessionconfiguration
314  - name: PowerShell Just Enough Administration (JEA)
315    description: Refer to the JEA documentation for advanced usage of some options
316    link: https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/overview
317  - name: About Session Configurations
318    description: General information about session configurations.
319    link: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_session_configurations
320  - name: About Session Configuration Files
321    description: General information about session configuration files.
322    link: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_session_configuration_files
323author:
324  - Brian Scholer (@briantist)
325'''
326
327EXAMPLES = r'''
328- name: Register a session configuration that loads modules automatically
329  community.windows.win_pssession_configuration:
330    name: WebAdmin
331    modules_to_import:
332      - WebAdministration
333      - IISAdministration
334    description: This endpoint has IIS modules pre-loaded
335
336- name: Set up an admin endpoint with a restricted execution policy
337  community.windows.win_pssession_configuration:
338    name: GloboCorp.Admin
339    company_name: Globo Corp
340    description: Admin Endpoint
341    execution_policy: restricted
342
343- name: Create a complex JEA endpoint
344  community.windows.win_pssession_configuration:
345    name: RBAC.Endpoint
346    session_type: restricted_remote_server
347    run_as_virtual_account: True
348    transcript_directory: '\\server\share\Transcripts'
349    language_mode: no_language
350    execution_policy: restricted
351    role_definitions:
352      'CORP\IT Support':
353        RoleCapabilities:
354          - PasswordResetter
355          - EmployeeOffboarder
356      'CORP\Webhosts':
357        RoleCapabilities: IISAdmin
358    visible_functions:
359      - tabexpansion2
360      - help
361    visible_cmdlets:
362      - Get-Help
363      - Name: Get-Service
364        Parameters:
365          - Name: DependentServices
366          - Name: RequiredServices
367          - Name: Name
368            ValidateSet:
369              - WinRM
370              - W3SVC
371              - WAS
372    visible_aliases:
373      - gsv
374    state: present
375
376- name: Remove a session configuration
377  community.windows.win_pssession_configuration:
378    name: UnusedEndpoint
379    state: absent
380
381- name: Set a sessions configuration with tweaked async values
382  community.windows.win_pssession_configuration:
383    name: MySession
384    description: A sample session
385    async_timeout: 500
386    async_poll: 5
387'''
388
389RETURN = r'''
390'''
391