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 层），并在 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 中添加

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

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

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

配置

  • 变量：ansible_winrm_kinit_args

kinit_env_vars

list / elements=string

在 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 ← (default)

  • 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

list / elements=string

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

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

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

配置

  • 变量：ansible_winrm_transport

作者

  • Ansible 核心团队

提示

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