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
    Choices:
  • disabled
  • local
  • remote
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
    Choices:
  • default
  • remote_signed
  • restricted
  • undefined
  • unrestricted
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
    Choices:
  • no_language
  • restricted_language
  • constrained_language
  • full_language
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
    Choices:
  • no
  • yes
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
    Choices:
  • amd64
  • x86
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
    Choices:
  • no
  • yes
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
    Choices:
  • default
  • empty
  • restricted_remote_server
Controls what type of session this is.
startup_script
path
A script that gets run on session startup.
state
string
    Choices:
  • present ←
  • absent
The desired state of the configuration.
thread_apartment_state
string
    Choices:
  • mta
  • sta
The apartment state for the PowerShell session.
thread_options
string
    Choices:
  • default
  • reuse_thread
  • use_current_thread
  • use_new_thread
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
    Choices:
  • no
  • yes
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.
visible_cmdlets
list / elements=raw
The cmdlets that can be used in the session.
The elements can be simple names or complex command specifications.
visible_external_commands
list / elements=string
The external commands and scripts that can be used in the session.
visible_functions
list / elements=raw
The functions that can be used in the session.
The elements can be simple names or complex command specifications.

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 and poll 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 and Register-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)