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

注意

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

概述

  • 通过 WinRM 在目标上运行命令或放置/获取

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

要求

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

  • pywinrm（python 库）

参数

参数

注释

connection_timeout

整数

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

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

读取超时属于底层的 python Request 调用（http 层）并在 Ansible 控制器上运行。

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

读取超时设置客户端 HTTP-请求超时，并指定客户端（Ansible 控制器）将在 HTTP-连接上等待来自服务器的数据的时间（等待服务器之间消息的超时）。当此计时器到期时，将抛出异常，并且 Ansible 连接将终止并显示错误消息“读取超时”。

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

将操作和读取超时之间的差异设置为 10 秒使其与 winrm-模块和 PSRP-模块中使用的默认值一致，这两个模块也使用 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 使用模式。

托管选项意味着 Ansible 将获取 Kerberos 票证。

而手动选项意味着用户必须已经获得了票证。

如果在尝试获取 Kerberos 票证时 Ansible 冻结，则可以将此设置为 manual 并在 Ansible 外部获取票证，或者通过 pip 安装 pexpect 并重试。

选项

  • "managed"

  • "manual"

配置

  • 变量：ansible_winrm_kinit_mode

kinit_args

字符串

在 ansible-core 2.11 中添加

要传递给 kinit 的额外参数，用于获取 Kerberos 身份验证票证。

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

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

配置

  • 变量：ansible_winrm_kinit_args

kinit_env_vars

列表 / 元素=字符串

在 ansible-core 2.12 中添加

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

默认情况下，不会传递任何环境变量，并且 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 Core 团队

提示

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