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: [email protected]
    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: [email protected]
    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)