community.windows.win_pssession_configuration (2.2.0) — module

Install collection

Install with ansible-galaxy collection install community.windows:==2.2.0

Add to requirements.yml

  collections:
    - name: community.windows
      version: 2.2.0

Description

Register, unregister, and modify PSSession Configurations for PowerShell remoting.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Remove a session configuration
  community.windows.win_pssession_configuration:
    name: UnusedEndpoint
    state: absent

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Inputs

    
guid:
    description:
    - 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 C(-) and opening/closing C({}) ignored.
    - See also I(lenient_config_fields).
    type: raw

name:
    description:
    - The name of the session configuration to manage.
    required: true
    type: str

state:
    choices:
    - present
    - absent
    default: present
    description:
    - The desired state of the configuration.
    type: str

author:
    description:
    - 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 I(lenient_config_fields).
    type: str

copyright:
    description:
    - 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 I(lenient_config_fields).
    type: str

async_poll:
    default: 1
    description:
    - Sets a delay in seconds between each check of the asynchronous execution status.
    - Replicates the functionality of the C(poll) keyword.
    - Has no effect in check mode.
    - I(async_poll=0) is not supported.
    type: int

access_mode:
    choices:
    - disabled
    - local
    - remote
    description:
    - Controls whether the session configuration allows connection from the C(local) machine
      only, both local and C(remote), or none (C(disabled)).
    type: str

description:
    description:
    - The description of the session configuration.
    - This value is metadata and does not affect the functionality of the session configuration.
    - See also I(lenient_config_fields).
    type: str

company_name:
    description:
    - 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 I(lenient_config_fields).
    type: str

session_type:
    choices:
    - default
    - empty
    - restricted_remote_server
    description:
    - Controls what type of session this is.
    type: str

async_timeout:
    default: 300
    description:
    - 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 C(async) keyword.
    - Has no effect in check mode.
    type: int

language_mode:
    choices:
    - no_language
    - restricted_language
    - constrained_language
    - full_language
    description:
    - Determines the language mode of the PowerShell session.
    type: str

schema_version:
    description:
    - 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.
    type: raw

startup_script:
    description:
    - A script that gets run on session startup.
    type: path

thread_options:
    choices:
    - default
    - reuse_thread
    - use_current_thread
    - use_new_thread
    description:
    - Sets thread options for the session.
    type: str

required_groups:
    description:
    - For JEA sessions, defines conditional access rules about which groups a connecting
      user must belong to.
    - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/session-configurations#conditional-access-rules).
    type: dict

visible_aliases:
    description:
    - The aliases that can be used in the session.
    - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities).
    elements: str
    type: list

visible_cmdlets:
    description:
    - The cmdlets that can be used in the session.
    - The elements can be simple names or complex command specifications.
    - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities).
    elements: raw
    type: list

execution_policy:
    choices:
    - default
    - remote_signed
    - restricted
    - undefined
    - unrestricted
    description:
    - The execution policy controlling script execution in the PowerShell session.
    type: str

mount_user_drive:
    description:
    - If C(yes) the session creates and mounts a user-specific PSDrive for use with file
      transfers.
    type: bool

role_definitions:
    description:
    - A dict defining the roles for JEA sessions.
    - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/session-configurations#role-definitions).
    type: dict

types_to_process:
    description:
    - Paths to type definition files to process for each session.
    elements: path
    type: list

alias_definitions:
    description:
    - A dict that defines aliases for each session.
    type: dict

modules_to_import:
    description:
    - 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.
    elements: raw
    type: list

visible_functions:
    description:
    - The functions that can be used in the session.
    - The elements can be simple names or complex command specifications.
    - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities).
    elements: raw
    type: list

assemblies_to_load:
    description:
    - The assemblies that should be loaded into each session.
    elements: str
    type: list

formats_to_process:
    description:
    - Paths to format definition files to process for each session.
    elements: path
    type: list

powershell_version:
    description:
    - The minimum required PowerShell version for this session.
    - Must be a valid .Net System.Version string.
    type: raw

scripts_to_process:
    description:
    - A list of paths to script files ending in C(.ps1) that should be applied to the
      session.
    elements: str
    type: list

use_shared_process:
    description:
    - If C(yes) then the session shares a process for each session.
    type: bool

function_definitions:
    description:
    - A dict that defines functions for each session.
    type: dict

transcript_directory:
    description:
    - Automatic session transcripts will be written to this directory.
    type: path

variable_definitions:
    description:
    - A list of dicts where each elements defines a variable for each session.
    elements: dict
    type: list

environment_variables:
    description:
    - A dict that defines environment variables for each session.
    type: dict

lenient_config_fields:
    default:
    - guid
    - author
    - company_name
    - copyright
    - description
    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.
    elements: str
    type: list

processor_architecure:
    choices:
    - amd64
    - x86
    description:
    - The processor architecture of the session (32 bit vs. 64 bit).
    type: str

run_as_virtual_account:
    description:
    - If C(yes) the session runs as a virtual account.
    - Do not use I(run_as_credential_username) and I(run_as_credential_password) to specify
      a virtual account.
    type: bool

thread_apartment_state:
    choices:
    - mta
    - sta
    description:
    - The apartment state for the PowerShell session.
    type: str

user_drive_maximum_size:
    description:
    - The maximum size of the user drive in bytes.
    - Must fit into an Int64.
    type: raw

security_descriptor_sddl:
    description:
    - An SDDL string that controls which users and groups can connect to the session.
    - If I(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.
    type: str

visible_external_commands:
    description:
    - The external commands and scripts that can be used in the session.
    - For more information see U(https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities).
    elements: str
    type: list

run_as_credential_password:
    description:
    - The password for I(run_as_credential_username).
    type: str

run_as_credential_username:
    description:
    - 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 I(group_managed_service_account).
    - To use a virtual account, see I(run_as_virtual_account) and I(run_as_virtual_account_groups).
    - Status will always be C(changed) when a RunAs credential is set because the password
      cannot be retrieved for comparison.
    type: str

group_managed_service_account:
    description:
    - If the session will run as a group managed service account (gMSA) then this is the
      name.
    - Do not use I(run_as_credential_username) and I(run_as_credential_password) to specify
      a gMSA.
    type: str

run_as_virtual_account_groups:
    description:
    - If I(run_as_virtual_account=yes) this is a list of groups to add the virtual account
      to.
    elements: str
    type: list

maximum_received_object_size_mb:
    description:
    - Sets the maximum object size in MB.
    - Must fit into a double precision floating point value.
    type: raw

maximum_received_data_size_per_command_mb:
    description:
    - Sets the maximum received data size per command in MB.
    - Must fit into a double precision floating point value.
    type: raw

See also

• C(New-PSSessionConfigurationFile) Reference: Details and defaults for options that end up in the session configuration file. link
• C(Register-PSSessionConfiguration) Reference: Details and defaults for options that are not specified in the session config file. link
• PowerShell Just Enough Administration (JEA): Refer to the JEA documentation for advanced usage of some options link
• About Session Configurations: General information about session configurations. link
• About Session Configuration Files: General information about session configuration files. link