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。

概要 

在未设置 WinRM 的情况下，从 Linux 主机到 Windows 主机运行远程命令。
可以在 Ansible 控制器上运行，以引导 Windows 主机使其准备好使用 WinRM。

需求 

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

pypsexec
可选 Kerberos 身份验证的 smbprotocol[kerberos]

参数 

参数	注释
arguments 字符串	运行可执行文件时使用的任何参数，作为一个字符串。
asynchronous 布尔值	将命令作为分离进程运行，模块在启动进程后立即返回，而进程继续在后台运行。当此设置为 `yes` 时，stdout 和 stderr 返回值将为 null。此类型的进程不支持 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 返回值将为 null。此类型的进程不支持 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 主机本地管理员组的成员。对于未加入域的主机，应将 LocalAccountTokenFilterPolicy 设置为 1 以确保其正常工作，请参见 https://support.microsoft.com/en-us/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 字符串	尝试运行进程时出现的任何异常详细信息返回值：模块失败示例： `"Received exception from remote PAExec service: Failed to start \"invalid.exe\". The system cannot find the file specified. [Err=0x2, 2]"`
pid 整数	已创建的异步进程的进程 ID 返回值：成功且 asynchronous 为 ‘yes’ 示例： `719`
rc 整数	远程进程的返回码返回值：成功且 asynchronous 为 ‘no’ 示例： `0`
stderr 字符串	远程进程的 stderr 返回值：成功且 interactive 或 asynchronous 为 ‘no’ 示例： `"Error [10] running process"`
stdout 字符串	远程进程的 stdout 返回值：成功且 interactive 或 asynchronous 为 ‘no’ 示例： `"Hello World"`

作者

Jordan Borean (@jborean93)