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 服务上运行。

读取超时属于底层 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 使用模式。

managed 选项表示 Ansible 将获取 Kerberos 票据。

而 manual 选项表示用户必须已获取票据。

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

选择

  • "managed"

  • "manual"

配置

  • 变量：ansible_winrm_kinit_mode

kinit_args

字符串

在 ansible-core 2.11 中添加

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

默认情况下，除非还设置了 _ansible_winrm_kerberos_delegation_，否则不会将任何额外的参数传递到 kinit。在这种情况下，将 -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；如果 port 为 5985，则默认使用 http。

选择

  • "http"

  • "https"

配置

  • 变量：ansible_winrm_scheme

transport

列表 / 元素=字符串

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

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

可用选择取决于您的 pywinrm 版本

配置

  • 变量：ansible_winrm_transport

作者

  • Ansible Core 团队

提示

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