community.windows.psexec 模块 – 基于 PsExec 模型在远程 Windows 主机上运行命令

注意

此模块是 community.windows 集合（版本 2.3.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.windows。您需要进一步的要求才能使用此模块，请参阅 要求 了解详细信息。

要在 playbook 中使用它，请指定：community.windows.psexec。

概要

• 从 Linux 主机向 Windows 主机运行远程命令，而无需设置 WinRM。

• 可以在 Ansible 控制器上运行以引导 Windows 主机，使其为 WinRM 做好准备。

要求

执行此模块的主机需要以下要求。

• pypsexec

• smbprotocol[kerberos] 用于可选的 Kerberos 身份验证

参数

参数	注释
arguments 字符串	在运行可执行文件时使用的任何参数，以单个字符串形式。
asynchronous 布尔值	将命令作为分离的进程运行，并且该模块在启动进程后立即返回，而进程继续在后台运行。 当设置为 yes 时，stdout 和 stderr 返回值将为空。 stdin 选项不适用于此类型的进程。 当此值为 yes 时，不会设置 rc 返回值 选择 false ← (默认) true
connection_password 字符串	connection_user 的密码。 如果未安装 Kerberos 要求或用户名是 Windows 主机的本地帐户，则为必需项。 如果安装了 Kerberos 库，并且在之前使用 kinit 命令检索了票据，则可以省略此项，以便使用由 connection_user 设置的主体的 Kerberos 主体票据。
connection_timeout 整数	在接收来自服务器的初始 SMB 协商响应时等待的超时时间（以秒为单位）。 默认值： 60
connection_username 字符串	连接到远程 Windows 主机时使用的用户名。 此用户必须是 Windows 主机的 Administrators 组的成员。 如果未安装 Kerberos 要求或用户名是 Windows 主机的本地帐户，则为必需项。 如果安装了 Kerberos 库，则可以省略此项，以便使用本地凭据缓存中的默认 Kerberos 主体票据。 如果未指定 process_username，则远程进程将在此帐户下以网络登录身份运行。
encrypt 布尔值	将使用 SMB 加密来加密发送到主机和从主机发送的 SMB 消息。 这需要 SMB 3 协议，该协议仅在 Windows Server 2012 或 Windows 8 中受支持，旧版本（如 Windows 7 或 Windows Server 2008 (R2)）必须将其设置为 no 并且不使用加密。 当设置为 no 时，数据包将以纯文本形式显示，并且任何嗅探网络的人都可以看到，任何进程选项都包含在此中。 选择 false true ← (默认)
executable 字符串 / 必需	要在 Windows 主机上运行的可执行文件。
hostname 字符串 / 必需	要连接的远程 Windows 主机，可以是 IP 地址或主机名。
integrity_level 字符串	当定义了 process_username 且不等于 System 时，进程的完整性级别。 当 default 时，基于系统设置的默认完整性级别。 当 elevated 时，将使用管理权限运行命令。 当 limited 时，将强制命令以非管理权限运行。 选择 "limited" "default" ← (默认) "elevated"
interactive 布尔值	将进程作为交互式进程运行，该进程显示由 interactive_session 指定的 Windows 会话的进程窗口。 当设置为 yes 时，stdout 和 stderr 返回值将为空。 stdin 选项不适用于此类型的进程。 选择 false ← (默认) true
interactive_session 整数	在远程 Windows 主机上显示交互式进程时使用的 Windows 会话 ID。 这仅在 interactive 为 yes 时有效。 默认值为 0，它是 Windows 主机的控制台会话。 默认值： 0
load_profile 布尔值	在加载用户配置文件的情况下运行远程命令。 选择 false true ← (默认)
port 整数	远程 SMB 服务正在侦听的端口。 默认值： 445
priority 字符串	在 Windows 主机上设置命令的优先级。 有关更多详细信息，请参阅 https://msdn.microsoft.com/en-us/library/windows/desktop/ms683211.aspx。 选择 "above_normal" "below_normal" "high" "idle" "normal" ← (默认) "realtime"
process_password 字符串	process_username 的密码。 如果定义了 process_username 且不是 System，则为必需项。
process_timeout 整数	进程运行的超时时间，以秒为单位。 值 0 表示没有超时。 默认值： 0
process_username 字符串	运行进程的用户。 可以设置为以指定帐户的交互式登录方式运行进程，这样可以绕过未指定时使用的网络登录的限制。 如果省略，则该进程将以与connection_username相同的帐户通过网络登录运行。 设置为 System 以内置 SYSTEM 帐户运行，此帐户不需要密码。 如果encrypt 为 no，则用户名和密码将作为简单的 XOR 加密的字节字符串发送，该字符串未加密。 不需要特殊的工具即可获取用户名和密码，只需要了解协议即可。
show_ui_on_logon_screen 布尔值	当 process_username 为 System 时，在 Winlogon 安全桌面上显示进程 UI。 选择 false ← (默认) true
stdin 字符串	进程启动后，在 stdin 管道上发送的数据。 当 interactive 或 asynchronous 为 yes 时，此选项无效。
working_directory 字符串	更改启动进程时设置的工作目录。 默认值： "C:\\Windows\\System32"

备注

注意

• 此模块要求 Windows 主机已配置并启用了 SMB，并且防火墙上打开了 445 端口。

• 除非 asynchronous 为 yes，否则此模块将等待进程完成，请确保该进程作为非交互式命令运行，以避免无限期挂起等待输入。

• connection_username 必须是 Windows 主机本地 Administrator 组的成员。 对于未加入域的主机，应将 LocalAccountTokenFilterPolicy 设置为 1 以确保此功能正常工作，请参阅 https://support.microsoft.com/zh-cn/help/951016/description-of-user-account-control-and-remote-restrictions-in-windows。

• 有关此模块和各种主机要求的更多信息，请参阅 https://github.com/jborean93/pypsexec。

另请参阅

另请参阅

ansible.builtin.raw

执行一个低级的命令。

ansible.windows.win_command

在远程 Windows 节点上执行命令。

community.windows.win_psexec

以另一个（特权）用户身份（远程）运行命令。

ansible.windows.win_shell

在目标主机上执行 shell 命令。

示例

- name: Run a cmd.exe command
  community.windows.psexec:
    hostname: server
    connection_username: username
    connection_password: password
    executable: cmd.exe
    arguments: /c echo Hello World

- name: Run a PowerShell command
  community.windows.psexec:
    hostname: server.domain.local
    connection_username: username@DOMAIN.LOCAL
    connection_password: password
    executable: powershell.exe
    arguments: Write-Host Hello World

- name: Send data through stdin
  community.windows.psexec:
    hostname: 192.168.1.2
    connection_username: username
    connection_password: password
    executable: powershell.exe
    arguments: '-'
    stdin: |
      Write-Host Hello World
      Write-Error Error Message
      exit 0

- name: Run the process as a different user
  community.windows.psexec:
    hostname: server
    connection_user: username
    connection_password: password
    executable: whoami.exe
    arguments: /all
    process_username: anotheruser
    process_password: anotherpassword

- name: Run the process asynchronously
  community.windows.psexec:
    hostname: server
    connection_username: username
    connection_password: password
    executable: cmd.exe
    arguments: /c rmdir C:\temp
    asynchronous: true

- name: Use Kerberos authentication for the connection (requires smbprotocol[kerberos])
  community.windows.psexec:
    hostname: host.domain.local
    connection_username: user@DOMAIN.LOCAL
    executable: C:\some\path\to\executable.exe
    arguments: /s

- name: Disable encryption to work with WIndows 7/Server 2008 (R2)
  community.windows.psexec:
    hostanme: windows-pc
    connection_username: Administrator
    connection_password: Password01
    encrypt: false
    integrity_level: elevated
    process_username: Administrator
    process_password: Password01
    executable: powershell.exe
    arguments: (New-Object -ComObject Microsoft.Update.Session).CreateUpdateInstaller().IsBusy

- name: Download and run ConfigureRemotingForAnsible.ps1 to setup WinRM
  community.windows.psexec:
    hostname: '{{ hostvars[inventory_hostname]["ansible_host"] | default(inventory_hostname) }}'
    connection_username: '{{ ansible_user }}'
    connection_password: '{{ ansible_password }}'
    encrypt: true
    executable: powershell.exe
    arguments: '-'
    stdin: |
      $ErrorActionPreference = "Stop"
      $sec_protocols = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::SystemDefault
      $sec_protocols = $sec_protocols -bor [Net.SecurityProtocolType]::Tls12
      [Net.ServicePointManager]::SecurityProtocol = $sec_protocols
      $url = "https://github.com/ansible/ansible-documentation/raw/devel/examples/scripts/ConfigureRemotingForAnsible.ps1"
      Invoke-Expression ((New-Object Net.WebClient).DownloadString($url))
      exit
  delegate_to: localhost

返回值

通用返回值在此处记录，以下是此模块独有的字段

键	描述
msg 字符串	尝试运行进程时出现的任何异常详细信息 返回： 模块失败 示例： "从远程 PAExec 服务收到异常：无法启动 \"invalid.exe\"。系统找不到指定的文件。[Err=0x2, 2]"
pid 整数	已创建的异步进程的进程 ID 返回： 成功且 asynchronous 为 'yes' 示例： 719
rc 整数	远程进程的返回码 返回： 成功且 asynchronous 为 'no' 示例： 0
stderr 字符串	来自远程进程的 stderr 返回： 成功且 interactive 或 asynchronous 为 'no' 示例： "运行进程时出错 [10]"
stdout 字符串	来自远程进程的 stdout 返回： 成功且 interactive 或 asynchronous 为 'no' 示例： "你好，世界"

作者

• Jordan Borean (@jborean93)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 通信