community.windows.win_pssession_configuration 模块 – 管理 PSSession 配置

注意

此模块是 community.windows 集合（版本 2.3.0）的一部分。

如果您使用的是 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.windows。

要在 playbook 中使用它，请指定：community.windows.win_pssession_configuration。

概要

  • 注册、取消注册和修改 PowerShell 远程处理的 PSSession 配置。

注意

此模块具有相应的 action 插件。

参数

参数

注释

access_mode

字符串

控制会话配置是否允许仅从 本地 计算机连接、本地和 远程 连接，或不允许连接（disabled）。

选项

  • "disabled"

  • "local"

  • "remote"

alias_definitions

字典

一个字典，定义每个会话的别名。

assemblies_to_load

列表 / elements=string

应加载到每个会话中的程序集。

async_poll

整数

设置异步执行状态每次检查之间的延迟秒数。

复制 poll 关键字的功能。

在检查模式下无效。

不支持 async_poll=0。

默认值： 1

async_timeout

整数

设置等待异步模块执行和等待连接恢复的超时秒数。

复制 async 关键字的功能。

在检查模式下无效。

默认值： 300

author

字符串

会话配置的作者。

此值是元数据，不影响会话配置的功能。

如果未设置，则可以自动生成值。

另请参阅 lenient_config_fields。

company_name

字符串

编写会话配置的公司。

此值是元数据，不影响会话配置的功能。

如果未设置，则可以自动生成值。

另请参阅 lenient_config_fields。

字符串

会话配置的版权声明。

此值是元数据，不影响会话配置的功能。

如果未设置，则可以自动生成值。

另请参阅 lenient_config_fields。

description

字符串

会话配置的描述。

此值是元数据，不影响会话配置的功能。

另请参阅 lenient_config_fields。

environment_variables

字典

一个字典，定义每个会话的环境变量。

execution_policy

字符串

控制 PowerShell 会话中脚本执行的执行策略。

选项

  • "default"

  • "remote_signed"

  • "restricted"

  • "undefined"

  • "unrestricted"

formats_to_process

列表 / elements=path

要为每个会话处理的格式定义文件的路径。

function_definitions

字典

一个字典，定义每个会话的函数。

group_managed_service_account

字符串

如果会话将作为组托管服务帐户 (gMSA) 运行，则这是名称。

请勿使用 run_as_credential_username 和 run_as_credential_password 指定 gMSA。

guid

任何

会话配置文件的 GUID (UUID)。

此值是元数据，因此仅当您在外部使用它时才重要。

如果未设置，将自动生成一个值。

可接受的 GUID 格式很灵活。将接受任何 32 位十六进制数字的字符串，其中所有连字符 - 和开/闭 {} 都将被忽略。

另请参阅 lenient_config_fields。

language_mode

字符串

确定 PowerShell 会话的语言模式。

选项

  • "no_language"

  • "restricted_language"

  • "constrained_language"

  • "full_language"

lenient_config_fields

列表 / elements=string

会话配置中使用的某些字段不会影响其功能，有时在未指定时会自动生成。

为了避免在每次运行时不必要地更改配置，这些选项的值仅在明确指定时才会强制执行。

默认值: ["guid", "author", "company_name", "copyright", "description"]

maximum_received_data_size_per_command_mb

任何

设置每个命令接收的最大数据大小（单位：MB）。

必须适合双精度浮点数值。

maximum_received_object_size_mb

任何

设置最大对象大小（单位：MB）。

必须适合双精度浮点数值。

modules_to_import

列表 / 元素=任意类型

一个应导入会话的模块列表。

这里可以使用任何有效的 PowerShell 模块规范，例如简单的字符串名称或字典。

如果使用字典，则不进行 snake_case 转换，因此必须使用原始的 PowerShell 名称。

mount_user_drive

布尔值

如果为 yes，则会话将创建并挂载一个特定于用户的 PSDrive，用于文件传输。

选项

  • false

  • true

name

字符串 / 必需

要管理的会话配置的名称。

powershell_version

任何

此会话所需的最低 PowerShell 版本。

必须是有效的 .Net System.Version 字符串。

processor_architecure

字符串

会话的处理器架构（32 位或 64 位）。

选项

  • "amd64"

  • "x86"

required_groups

字典

对于 JEA 会话，定义有关连接用户必须属于哪些组的条件访问规则。

有关详细信息，请参阅 https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/session-configurations#conditional-access-rules。

role_definitions

字典

一个定义 JEA 会话角色的字典。

有关详细信息，请参阅 https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/session-configurations#role-definitions。

run_as_credential_password

字符串

run_as_credential_username 的密码。

run_as_credential_username

字符串

用于为会话设置 RunAs 帐户。会话中执行的所有命令都将以此用户身份运行。

要使用 gMSA，请参阅 group_managed_service_account。

要使用虚拟帐户，请参阅 run_as_virtual_account 和 run_as_virtual_account_groups。

设置 RunAs 凭据后，状态始终为 changed，因为无法检索密码进行比较。

run_as_virtual_account

布尔值

如果为 yes，则会话以虚拟帐户运行。

请勿使用 run_as_credential_username 和 run_as_credential_password 来指定虚拟帐户。

选项

  • false

  • true

run_as_virtual_account_groups

列表 / elements=string

如果 run_as_virtual_account=yes，则这是将虚拟帐户添加到的组列表。

schema_version

任何

会话配置文件架构版本。

如果未设置，将自动生成一个值。

必须是有效的 .Net System.Version 字符串。

scripts_to_process

列表 / elements=string

一个脚本文件路径列表，以 .ps1 结尾，应将其应用于会话。

security_descriptor_sddl

字符串

一个 SDDL 字符串，用于控制哪些用户和组可以连接到会话。

如果指定了 role_definitions，则将基于此设置安全描述符。

如果未指定此选项，则将应用默认安全描述符。

session_type

字符串

控制会话的类型。

选项

  • "default"

  • "empty"

  • "restricted_remote_server"

startup_script

路径

在会话启动时运行的脚本。

state

字符串

配置的所需状态。

选项

  • "present" ← (默认)

  • "absent"

thread_apartment_state

字符串

PowerShell 会话的单元状态。

选项

  • "mta"

  • "sta"

thread_options

字符串

设置会话的线程选项。

选项

  • "default"

  • "reuse_thread"

  • "use_current_thread"

  • "use_new_thread"

transcript_directory

路径

自动会话记录将写入此目录。

types_to_process

列表 / elements=path

要为每个会话处理的类型定义文件的路径。

use_shared_process

布尔值

如果为 yes，则每个会话共享一个进程。

选项

  • false

  • true

user_drive_maximum_size

任何

用户驱动器的最大大小（单位：字节）。

必须适合 Int64。

variable_definitions

列表 / 元素=字典

一个字典列表，其中每个元素定义每个会话的变量。

visible_aliases

列表 / elements=string

可以在会话中使用的别名。

有关详细信息，请参阅 https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities。

visible_cmdlets

列表 / 元素=任意类型

可以在会话中使用的 cmdlet。

元素可以是简单的名称或复杂的命令规范。

有关详细信息，请参阅 https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities。

visible_external_commands

列表 / elements=string

可以在会话中使用的外部命令和脚本。

有关详细信息，请参阅 https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities。

visible_functions

列表 / 元素=任意类型

可以在会话中使用的函数。

元素可以是简单的名称或复杂的命令规范。

有关详细信息，请参阅 https://docs.microsoft.com/en-us/powershell/scripting/learn/remoting/jea/role-capabilities。

备注

注意

  • 此模块将在任何更改时重新启动 WinRM 服务。这将终止所有 WinRM 连接，包括其他 Ansible 运行的连接。

  • 在内部，此模块在非检查模式下使用 async，以确保在重新启动 WinRM 服务时顺利进行。

  • 不能使用标准的 async 和 poll 关键字；请改为使用 async_timeout 和 async_poll 选项来控制异步执行。

  • 此处未列出默认值的选项将使用 New-PSSessionConfigurationFile 和 Register-PSSessionConfiguration 的默认值。

  • 如果可以在会话配置文件和会话选项中直接指定一个值，则此模块将优先选择在配置文件中进行设置。

另请参阅

另请参阅

C(New-PSSessionConfigurationFile) 参考

最终出现在会话配置文件中的选项的详细信息和默认值。

C(Register-PSSessionConfiguration) 参考

未在会话配置文件中指定的选项的详细信息和默认值。

PowerShell Just Enough Administration (JEA)

有关某些选项的高级用法，请参阅 JEA 文档

关于会话配置

有关会话配置的常规信息。

关于会话配置文件

有关会话配置文件的常规信息。

示例

- 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

作者

  • Brian Scholer (@briantist)