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

字符串

控制会话配置是否只允许来自 local 机器的连接，同时允许本地和 remote 连接，或者两者都不允许 (disabled)。

选项

  • "disabled"

  • "local"

  • "remote"

alias_definitions

字典

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

assemblies_to_load

列表 / 元素=字符串

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

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

列表 / 元素=路径

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

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

列表 / 元素=字符串

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

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

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

maximum_received_data_size_per_command_mb

任意

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

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

maximum_received_object_size_mb

任意

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

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

modules_to_import

列表 / 元素=任意

应导入到会话中的模块列表。

此处可以使用任何有效的 PowerShell 模块规范，因此可以使用简单的 str 名称或字典。

如果使用字典，则不会进行 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

列表 / 元素=字符串

如果 run_as_virtual_account=yes，则这是要向其中添加虚拟帐户的组列表。

schema_version

任意

会话配置文件的模式版本。

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

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

scripts_to_process

列表 / 元素=字符串

应应用于会话的以 .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

列表 / 元素=路径

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

use_shared_process

布尔值

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

选项

  • false

  • true

user_drive_maximum_size

任意

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

必须适合 Int64。

variable_definitions

列表 / 元素=字典

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

visible_aliases

列表 / 元素=字符串

可在会话中使用的别名。

更多信息请参见 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

列表 / 元素=字符串

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

更多信息请参见 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)