ansible.builtin.winrm 连接 – 通过 Microsoft 的 WinRM 运行任务

注意

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

概要

  • 通过 WinRM 在目标上运行命令或 put/fetch

  • 此插件允许传递协议支持但此处未明确定义的额外参数。它们应该采用以下模式声明的变量形式 ansible_winrm_<option>。

需求

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

  • pywinrm（python 库）

参数

参数

注释

connection_timeout

整数

尽管名称如此，但它为 WinRM 连接设置“操作”和“读取”超时设置。

操作超时属于 WS-Man 层，并在受管 Windows 主机上的 winRM-service 上运行。

读取超时属于底层的 python 请求调用（http-layer），并在 ansible 控制器上运行。

操作超时设置在受管 Windows 主机上运行的 WS-Man “操作超时”。操作超时指定命令在 winRM-service 上运行多长时间，然后才会将消息 “WinRMOperationTimeoutError” 发送回客户端。客户端（静默地）忽略此消息并启动操作超时的另一个实例，等待命令完成（长时间运行的命令）。

读取超时设置客户端 HTTP-请求超时，指定客户端（ansible 控制器）将等待从服务器返回数据通过 HTTP-连接的时间（等待来自服务器的中继消息的超时）。当此计时器过期时，将抛出异常，并且 ansible 连接将使用错误消息 “读取超时” 终止。

为了避免抛出上述异常，读取超时将设置为比 WS-Man 操作超时高 10 秒，从而使连接在网络延迟较长或服务器和客户端网络之间存在多个跃点的网络上更加稳健。

将操作超时和读取超时之间的差值设置为 10 秒，使其与 winrm-module 和 PSRP-module 中使用的默认值保持一致，这些模块也使用 10 秒（读取超时为 30 秒，操作超时为 20 秒）。

对应于 pywinrm 中的 operation_timeout_sec 和 read_timeout_sec 参数，因此请避免使用此参数设置这些变量。

默认值为已安装的 pywinrm 版本中设置的值。

配置

  • 变量：ansible_winrm_connection_timeout

kerberos_command

字符串

用于请求身份验证票证的 kerberos 命令

默认： "kinit"

配置

  • 变量：ansible_winrm_kinit_cmd

kerberos_mode

字符串

kerberos 使用模式。

managed 选项意味着 Ansible 将获取 kerberos 票证。

而 manual 选项意味着必须由用户先获得票证。

如果在尝试获取 Kerberos 票证时遇到 Ansible 冻结问题，您可以将其设置为 manual，并在 Ansible 之外获取票证，或者通过 pip 安装 pexpect 并重试。

选择

  • "managed"

  • "manual"

配置

  • 变量：ansible_winrm_kinit_mode

kinit_args

字符串

在 ansible-core 2.11 中添加

获取 Kerberos 身份验证票证时传递给 kinit 的额外参数。

默认情况下，不会将额外参数传递给 kinit，除非还设置了 *ansible_winrm_kerberos_delegation*。在这种情况下，-f 将被添加到 kinit 参数中，以便检索可转发票证。

如果设置了此参数，则这些参数将覆盖 kinit 的任何现有默认值，包括用于委托票证的 -f。

配置

  • 变量：ansible_winrm_kinit_args

kinit_env_vars

列表 / 元素=字符串

在 ansible-core 2.12 中添加

用于获取 Kerberos 身份验证票证时传递给 kinit 的环境变量列表。

默认情况下，不会传递任何环境变量，并且 kinit 将使用空白状态运行。

环境变量 KRB5CCNAME 不能在此处指定，因为它用于存储 WinRM 使用的临时 Kerberos 票证。

默认： []

配置

  • INI 条目

    [winrm]
kinit_env_vars =

  • 变量：ansible_winrm_kinit_env_vars

path

字符串

要连接到的 URI 路径

默认： "/wsman"

配置

  • 变量：ansible_winrm_path

pipelining

布尔值

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

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

但是，这可能会与特权升级（become）冲突。例如，使用 sudo 操作时，必须先在目标主机的 sudoers 文件中禁用 requiretty，这就是默认情况下禁用此功能的原因。

选择

  • false ← (默认)

  • true

配置

  • INI 条目

    [defaults]
pipelining = false

    [connection]
pipelining = false

  • 环境变量：ANSIBLE_PIPELINING

  • 变量：ansible_pipelining

port

整数

winrm 在远程目标上连接的端口

默认值为 https (5986) 端口，如果使用 http，则应为 5985

默认： 5986

配置

  • 变量：ansible_port

  • 变量：ansible_winrm_port

  • 关键字：port

remote_addr

字符串

Windows 计算机的地址

默认： "inventory_hostname"

配置

  • 变量：inventory_hostname

  • 变量：ansible_host

  • 变量：ansible_winrm_host

remote_password

别名：password

字符串

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

配置

  • 变量：ansible_password

  • 变量：ansible_winrm_pass

  • 变量：ansible_winrm_password

remote_user

字符串

要登录到 Windows 计算机的用户

配置

  • 变量：ansible_user

  • 变量：ansible_winrm_user

  • 关键字：remote_user

scheme

字符串

要使用的 URI 方案

如果未设置，则默认为 https 或 http（如果 port 为 5985）。

选择

  • "http"

  • "https"

配置

  • 变量：ansible_winrm_scheme

transport

列表 / 元素=字符串

尝试使用的 WinRM 传输列表（ssl、plaintext、kerberos 等）

如果为 None（默认值），插件将尝试自动猜测正确的列表。

可用的选项取决于您的 pywinrm 版本。

配置

  • 变量：ansible_winrm_transport

作者

  • Ansible 核心团队

提示

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