ansible.builtin.psrp 连接 – 通过 Microsoft PowerShell 远程处理协议运行任务

注意

此连接插件是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，您可以使用简短的插件名称 psrp。但是，我们建议您使用 完全限定的集合名称 (FQCN) ansible.builtin.psrp，以便轻松链接到插件文档并避免与可能具有相同连接插件名称的其他集合发生冲突。

Ansible 2.7 中的新增功能

摘要

  • 通过 PSRP（WinRM 插件）在目标上运行命令或执行 put/fetch 操作

  • 这类似于 ansible.builtin.winrm 连接插件，该插件使用相同的底层传输，但会在 PowerShell 解释器中运行。

要求

以下要求是在执行此连接的本地控制器节点上所需的。

  • pypsrp>=0.4.0, <1.0.0（Python 库）

参数

参数

注释

auth

字符串

在对远程用户进行身份验证时要使用的身份验证协议。

默认值 negotiate 会尝试使用 Kerberos（kerberos）（如果可用）并回退到 NTLM（ntlm）（如果不可用）。

选项

  • "basic"

  • "certificate"

  • "negotiate" ← (默认)

  • "kerberos"

  • "ntlm"

  • "credssp"

配置

  • 变量：ansible_psrp_auth

ca_cert

别名：cert_trust_path

路径

在验证服务器证书时要使用的 PEM 证书链的路径。

如果 cert_validation 设置为 ignore，则忽略此值。

配置

  • 变量：ansible_psrp_cert_trust_path

  • 变量：ansible_psrp_ca_cert

cert_validation

字符串

是否验证远程服务器的证书。

设置为 ignore 以不验证任何证书。

ca_cert 可以设置为 PEM 证书链的路径，以用于验证。

选项

  • "validate" ← (默认)

  • "ignore"

配置

  • 变量：ansible_psrp_cert_validation

certificate_key_pem

路径

与证书身份验证一起使用的 X509 证书密钥的本地路径。

配置

  • 变量：ansible_psrp_certificate_key_pem

certificate_pem

路径

与证书身份验证一起使用的 X509 证书的本地路径。

配置

  • 变量：ansible_psrp_certificate_pem

configuration_name

字符串

要连接到的 PowerShell 配置端点的名称。

默认值： "Microsoft.PowerShell"

配置

  • 变量：ansible_psrp_configuration_name

connection_timeout

整数

向远程主机发出请求的连接超时时间。

以秒为单位。

默认值： 30

配置

  • 变量：ansible_psrp_connection_timeout

credssp_auth_mechanism

字符串

与 CredSSP 身份验证一起使用的子身份验证机制。

当为 auto 时，会尝试使用 Kerberos 和 NTLM，并优先使用 Kerberos。

选项

  • "auto" ← (默认)

  • "kerberos"

  • "ntlm"

配置

  • 变量：ansible_psrp_credssp_auth_mechanism

credssp_disable_tlsv1_2

布尔值

禁用在 CredSSP 身份验证通道上使用 TLSv1.2。

除非处理不支持 TLSv1.2 的主机，否则不应将其设置为 yes。

选项

  • false ← (默认)

  • true

配置

  • 变量：ansible_psrp_credssp_disable_tlsv1_2

credssp_minimum_version

整数

将接受的最低 CredSSP 服务器身份验证版本。

设置为 5 以确保服务器已打补丁并且不受 CVE 2018-0886 的影响。

默认值： 2

配置

  • 变量：ansible_psrp_credssp_minimum_version

ignore_proxy

布尔值

将禁用任何环境代理设置并直接连接到远程主机。

如果设置了 proxy，则忽略此选项。

选项

  • false ← (默认)

  • true

配置

  • 变量：ansible_psrp_ignore_proxy

max_envelope_size

整数

设置发送到远程主机的每个 WSMan 消息的最大大小。

以字节为单位。

默认为 150KiB，以确保与旧版主机兼容。

默认值： 153600

配置

  • 变量：ansible_psrp_max_envelope_size

message_encryption

字符串

控制消息加密设置，当 protocol 为 https 时，这与 TLS 加密不同。

只有身份验证协议 negotiate、kerberos、ntlm 和 credssp 可以执行消息加密。其他身份验证协议仅在 protocol 设置为 https 时才支持加密。

auto 表示仅在不使用 TLS/HTTPS 时才使用消息加密。

always 与 auto 相同，但即使在通过 TLS/HTTPS 运行时也始终使用消息加密。

never 会禁用通过 HTTP 运行时存在的任何加密检查，并禁用任何身份验证加密过程。

选项

  • "auto" ← (默认)

  • "always"

  • "never"

配置

  • 变量：ansible_psrp_message_encryption

negotiate_delegate

布尔值

允许远程用户将其凭据委托给另一台服务器，即凭据委托。

仅在 Kerberos 是协商的身份验证或被显式设置为身份验证时才有效。

当 NTLM 是协商的身份验证时被忽略。

选项

  • false

  • true

配置

  • 变量：ansible_psrp_negotiate_delegate

negotiate_hostname_override

字符串

在 Kerberos 查找中搜索主机时覆盖远程主机名。

这允许 Ansible 通过 IP 连接，但使用远程服务器的 DNS 名称进行身份验证。

仅在 Kerberos 是协商的身份验证或被显式设置为身份验证时才有效。

当 NTLM 是协商的身份验证时被忽略。

配置

  • 变量：ansible_psrp_negotiate_hostname_override

negotiate_send_cbt

布尔值

在进行身份验证时发送通道绑定令牌 (CBT) 结构。

CBT 用于通过将外部传输通道绑定到身份验证通道来提供针对中间人 (MitM) 攻击的额外保护。

仅在使用 HTTPS 时才使用 CBT，不适用于 HTTP。

选项

  • false

  • true ← (默认)

配置

  • 变量：ansible_psrp_negotiate_send_cbt

negotiate_service

字符串

覆盖 Kerberos 身份验证期间使用的 SPN 的服务部分。

仅在 Kerberos 是协商的身份验证或被显式设置为身份验证时才有效。

当 NTLM 是协商的身份验证时被忽略。

默认值： "WSMAN"

配置

  • 变量：ansible_psrp_negotiate_service

operation_timeout

整数

设置每个操作的 WSMan 超时时间。

以秒为单位。

此值不应超过 connection_timeout 的值。

默认值： 20

配置

  • 变量：ansible_psrp_operation_timeout

路径

字符串

要连接到的 URI 路径。

默认值： "wsman"

配置

  • 变量：ansible_psrp_path

pipelining

布尔值

通过在不进行实际文件传输的情况下执行许多 Ansible 模块，流水线处理可减少在远程服务器上执行模块所需的连接操作数量。

启用此功能可以带来非常显著的性能提升。

但是，这可能与权限提升（become）冲突。例如，在使用 sudo 操作时，您必须首先在目标主机的 sudoers 文件中禁用 requiretty，这就是此功能默认处于禁用状态的原因。

选项

  • false ← (默认)

  • true

配置

  • INI 条目

    [defaults]
pipelining = false

    [connection]
pipelining = false

  • 环境变量：ANSIBLE_PIPELINING

  • 变量：ansible_pipelining

端口

整数

PSRP 在远程目标上连接的端口。

如果 protocol 未定义或为 https，则默认为 5986，否则端口为 5985。

配置

  • 变量：ansible_port

  • 变量：ansible_psrp_port

  • 关键字：port

协议

字符串

设置连接使用的协议。

如果 port 未定义或 port 不为 5985，则默认为 https。

选项

  • "http"

  • "https"

配置

  • 变量：ansible_psrp_protocol

代理

字符串

连接到远程主机时使用的代理 URL。

配置

  • 变量：ansible_psrp_proxy

读取超时

整数

在 Ansible 2.8 中添加

从远程主机接收数据的读取超时时间。

此值必须始终大于 operation_timeout。

此选项需要 pypsrp >= 0.3。

以秒为单位。

默认值： 30

配置

  • 变量：ansible_psrp_read_timeout

重连回退

整数

在 Ansible 2.8 中添加

在重连尝试之间使用的回退时间。（首先休眠 X，然后休眠 2*X，然后休眠 4*X，…）

以秒为单位。

在 Ansible 2.9 中添加了 ansible_psrp_reconnection_backoff 变量。

默认值： 2

配置

  • 变量：ansible_psrp_connection_backoff

  • 变量：ansible_psrp_reconnection_backoff

重连重试次数

整数

在 Ansible 2.8 中添加

连接错误时的重试次数。

默认值： 0

配置

  • 变量：ansible_psrp_reconnection_retries

远程地址

字符串

远程主机的主机名或 IP 地址。

默认值： "inventory_hostname"

配置

  • 变量：inventory_hostname

  • 变量：ansible_host

  • 变量：ansible_psrp_host

远程密码

别名：password

字符串

remote_user 的身份验证密码。可以作为 CLI 选项提供。

配置

  • 变量：ansible_password

  • 变量：ansible_winrm_pass

  • 变量：ansible_winrm_password

远程用户

字符串

要登录的用户。

配置

  • 变量：ansible_user

  • 变量：ansible_psrp_user

  • 关键字：remote_user

作者

  • Ansible 核心团队

提示

每个条目类型的配置项具有从低到高的优先级顺序。例如，列表中较低的变量将覆盖较高的变量。