community.windows.win_pssession_configuration – Manage PSSession Configurations

From Get docs
Ansible/docs/2.11/collections/community/windows/win pssession configuration module


community.windows.win_pssession_configuration – Manage PSSession Configurations

Note

This plugin is part of the community.windows collection (version 1.2.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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • present

  • absent

The desired state of the configuration.

thread_apartment_state

string

  • mta
  • sta

The apartment state for the PowerShell session.

thread_options

string

  • 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

  • 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)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/community/windows/win_pssession_configuration_module.html