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