community.windows.win_pssession_configuration – Manage PSSession Configurations¶
Note
This plugin is part of the community.windows collection (version 1.3.0).
To install it use: ansible-galaxy collection install community.windows
.
To use it in a playbook, specify: community.windows.win_pssession_configuration
.
Synopsis¶
Register, unregister, and modify PSSession Configurations for PowerShell remoting.
Note
This module has a corresponding action plugin.
Parameters¶
Parameter | Choices/Defaults | Comments |
---|---|---|
access_mode
string
|
|
Controls whether the session configuration allows connection from the
local machine only, both local and remote , or none (disabled ). |
alias_definitions
dictionary
|
A dict that defines aliases for each session.
|
|
assemblies_to_load
list
/ elements=string
|
The assemblies that should be loaded into each session.
|
|
async_poll
integer
|
Default: 1
|
Sets a delay in seconds between each check of the asynchronous execution status.
Replicates the functionality of the
poll keyword.Has no effect in check mode.
|
async_timeout
integer
|
Default: 300
|
Sets a timeout for how long in seconds to wait for asynchronous module execution and waiting for the connection to recover.
Replicates the functionality of the
async keyword.Has no effect in check mode.
|
author
string
|
The author of the session configuration.
This value is metadata and does not affect the functionality of the session configuration.
If not set, a value may be generated automatically.
See also lenient_config_fields.
|
|
company_name
string
|
The company that authored the session configuration.
This value is metadata and does not affect the functionality of the session configuration.
If not set, a value may be generated automatically.
See also lenient_config_fields.
|
|
copyright
string
|
The copyright statement of the session configuration.
This value is metadata and does not affect the functionality of the session configuration.
If not set, a value may be generated automatically.
See also lenient_config_fields.
|
|
description
string
|
The description of the session configuration.
This value is metadata and does not affect the functionality of the session configuration.
See also lenient_config_fields.
|
|
environment_variables
dictionary
|
A dict that defines environment variables for each session.
|
|
execution_policy
string
|
|
The execution policy controlling script execution in the PowerShell session.
|
formats_to_process
list
/ elements=path
|
Paths to format definition files to process for each session.
|
|
function_definitions
dictionary
|
A dict that defines functions for each session.
|
|
group_managed_service_account
string
|
If the session will run as a group managed service account (gMSA) then this is the name.
Do not use run_as_credential_username and run_as_credential_password to specify a gMSA.
|
|
guid
raw
|
The GUID (UUID) of the session configuration file.
This value is metadata, so it only matters if you use it externally.
If not set, a value will be generated automatically.
Acceptable GUID formats are flexible. Any string of 32 hexadecimal digits will be accepted, with all hyphens
- and opening/closing {} ignored.See also lenient_config_fields.
|
|
language_mode
string
|
|
Determines the language mode of the PowerShell session.
|
lenient_config_fields
list
/ elements=string
|
Default: ["guid", "author", "company_name", "copyright", "description"]
|
Some fields used in the session configuration do not affect its function, and are sometimes auto-generated when not specified.
To avoid unnecessarily changing the configuration on each run, the values of these options will only be enforced when they are explicitly specified.
|
maximum_received_data_size_per_command_mb
raw
|
Sets the maximum received data size per command in MB.
Must fit into a double precision floating point value.
|
|
maximum_received_object_size_mb
raw
|
Sets the maximum object size in MB.
Must fit into a double precision floating point value.
|
|
modules_to_import
list
/ elements=raw
|
A list of modules that should be imported into the session.
Any valid PowerShell module spec can be used here, so simple str names or dicts can be used.
If a dict is used, no snake_case conversion is done, so the original PowerShell names must be used.
|
|
mount_user_drive
boolean
|
|
If
yes the session creates and mounts a user-specific PSDrive for use with file transfers. |
name
string
/ required
|
The name of the session configuration to manage.
|
|
powershell_version
raw
|
The minimum required PowerShell version for this session.
Must be a valid .Net System.Version string.
|
|
processor_architecure
string
|
|
The processor architecture of the session (32 bit vs. 64 bit).
|
required_groups
dictionary
|
For JEA sessions, defines conditional access rules about which groups a connecting user must belong to.
|
|
role_definitions
dictionary
|
A dict defining the roles for JEA sessions.
|
|
run_as_credential_password
string
|
The password for run_as_credential_username.
|
|
run_as_credential_username
string
|
Used to set a RunAs account for the session. All commands executed in the session will be run as this user.
To use a gMSA, see group_managed_service_account.
To use a virtual account, see run_as_virtual_account and run_as_virtual_account_groups.
Status will always be
changed when a RunAs credential is set because the password cannot be retrieved for comparison. |
|
run_as_virtual_account
boolean
|
|
If
yes the session runs as a virtual account.Do not use run_as_credential_username and run_as_credential_password to specify a virtual account.
|
run_as_virtual_account_groups
list
/ elements=string
|
If run_as_virtual_account=yes this is a list of groups to add the virtual account to.
|
|
schema_version
raw
|
The schema version of the session configuration file.
If not set, a value will be generated automatically.
Must be a valid .Net System.Version string.
|
|
scripts_to_process
list
/ elements=string
|
A list of paths to script files ending in
.ps1 that should be applied to the session. |
|
security_descriptor_sddl
string
|
An SDDL string that controls which users and groups can connect to the session.
If role_definitions is specified the security descriptor will be set based on that.
If this option is not specified the default security descriptor will be applied.
|
|
session_type
string
|
|
Controls what type of session this is.
|
startup_script
path
|
A script that gets run on session startup.
|
|
state
string
|
|
The desired state of the configuration.
|
thread_apartment_state
string
|
|
The apartment state for the PowerShell session.
|
thread_options
string
|
|
Sets thread options for the session.
|
transcript_directory
path
|
Automatic session transcripts will be written to this directory.
|
|
types_to_process
list
/ elements=path
|
Paths to type definition files to process for each session.
|
|
use_shared_process
boolean
|
|
If
yes then the session shares a process for each session. |
user_drive_maximum_size
raw
|
The maximum size of the user drive in bytes.
Must fit into an Int64.
|
|
variable_definitions
list
/ elements=dictionary
|
A list of dicts where each elements defines a variable for each session.
|
|
visible_aliases
list
/ elements=string
|
The aliases that can be used in the session.
For more information see https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities.
|
|
visible_cmdlets
list
/ elements=raw
|
The cmdlets that can be used in the session.
The elements can be simple names or complex command specifications.
For more information see https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities.
|
|
visible_external_commands
list
/ elements=string
|
The external commands and scripts that can be used in the session.
For more information see https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities.
|
|
visible_functions
list
/ elements=raw
|
The functions that can be used in the session.
The elements can be simple names or complex command specifications.
For more information see https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities.
|
Notes¶
Note
This module will restart the WinRM service on any change. This will terminate all WinRM connections including those by other Ansible runs.
Internally this module uses
async
when not in check mode to ensure things goes smoothly when restarting the WinRM service.The standard
async
andpoll
keywords cannot be used; instead use the async_timeout and async_poll options to control asynchronous execution.Setting async_poll=0 will return a result that can be used with
async_status
.Options that don’t list a default value here will use the defaults of
New-PSSessionConfigurationFile
andRegister-PSSessionConfiguration
.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.
See Also¶
See also
- C(New-PSSessionConfigurationFile) Reference
Details and defaults for options that end up in the session configuration file.
- C(Register-PSSessionConfiguration) Reference
Details and defaults for options that are not specified in the session config file.
- PowerShell Just Enough Administration (JEA)
Refer to the JEA documentation for advanced usage of some options
- About Session Configurations
General information about session configurations.
- About Session Configuration Files
General information about session configuration files.
Examples¶
- name: Register a session configuration that loads modules automatically
community.windows.win_pssession_configuration:
name: WebAdmin
modules_to_import:
- WebAdministration
- IISAdministration
description: This endpoint has IIS modules pre-loaded
- name: Set up an admin endpoint with a restricted execution policy
community.windows.win_pssession_configuration:
name: GloboCorp.Admin
company_name: Globo Corp
description: Admin Endpoint
execution_policy: restricted
- name: Create a complex JEA endpoint
community.windows.win_pssession_configuration:
name: RBAC.Endpoint
session_type: restricted_remote_server
run_as_virtual_account: True
transcript_directory: '\\server\share\Transcripts'
language_mode: no_language
execution_policy: restricted
role_definitions:
'CORP\IT Support':
RoleCapabilities:
- PasswordResetter
- EmployeeOffboarder
'CORP\Webhosts':
RoleCapabilities: IISAdmin
visible_functions:
- tabexpansion2
- help
visible_cmdlets:
- Get-Help
- Name: Get-Service
Parameters:
- Name: DependentServices
- Name: RequiredServices
- Name: Name
ValidateSet:
- WinRM
- W3SVC
- WAS
visible_aliases:
- gsv
state: present
- name: Remove a session configuration
community.windows.win_pssession_configuration:
name: UnusedEndpoint
state: absent
- name: Set a sessions configuration with tweaked async values
community.windows.win_pssession_configuration:
name: MySession
description: A sample session
async_timeout: 500
async_poll: 5
Authors¶
Brian Scholer (@briantist)