модуль community.windows.psexec — выполняет команды на удалённом узле Windows на основе модели PsExec

Примечание

Этот модуль входит в коллекцию community.windows (версия 3.1.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.windows. Для использования этого модуля могут потребоваться дополнительные компоненты; подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: community.windows.psexec.

Краткое описание
Требования
Параметры
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Выполняет удалённую команду на узле Windows с узла Linux без настройки WinRM.
Можно запустить на контроллере Ansible для начальной настройки узлов Windows и подготовки их к работе с WinRM.

Требования

На узле, выполняющем этот модуль, необходимы следующие компоненты.

pypsexec
smbprotocol[kerberos] для дополнительной аутентификации Kerberos

Параметры

Параметр	Комментарии
arguments строка	Аргументы, передаваемые исполняемому файлу одной строкой.
asynchronous логический	Запускает команду как отсоединённый процесс. Модуль возвращает управление сразу после запуска процесса, который продолжает работать в фоновом режиме. Если этому параметру задано значение `yes`, возвращаемые значения stdout и stderr будут иметь значение null. Параметр stdin не работает с процессами этого типа. Если этому параметру задано значение `yes`, возвращаемое значение rc не устанавливается. Варианты: `false` ← (по умолчанию) `true`
connection_password строка	Пароль для connection_user. Обязателен, если не установлены компоненты Kerberos или имя пользователя относится к локальной учётной записи узла Windows. Можно не указывать, чтобы использовать билет участника Kerberos для участника, заданного параметром connection_user, если установлена библиотека Kerberos и билет уже был получен с помощью команды `kinit`.
connection_timeout целое число	Время ожидания в секундах при получении первоначального ответа сервера на согласование SMB. По умолчанию: `60`
connection_username строка	Имя пользователя для подключения к удалённому узлу Windows. Этот пользователь должен входить в группу `Administrators` на узле Windows. Обязательно, если не установлены компоненты 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 логический	Запускает процесс в интерактивном режиме и отображает его окно в сеансе Windows, указанном параметром interactive_session. Если этому параметру задано значение `yes`, возвращаемые значения stdout и stderr будут иметь значение null. Параметр stdin не работает с процессами этого типа. Варианты: `false` ← (по умолчанию) `true`
interactive_session целое число	Идентификатор сеанса Windows для отображения интерактивного процесса на удалённом узле Windows. Допустимо только, если для параметра 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 логический	Отображает интерфейс процесса на защищённом рабочем столе Winlogon, если параметр process_username равен `System`. Варианты: `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: Выполняет команды оболочки на целевых узлах.

Примеры

- 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 строка	Подробности исключения, возникшего при попытке запуска процесса Возвращается: выполнение модуля завершилось ошибкой Пример: `"Received exception from remote PAExec service: Failed to start \"invalid.exe\". The system cannot find the file specified. [Err=0x2, 2]"`
pid целое число	Идентификатор созданного асинхронного процесса Возвращается: при успешном выполнении, если 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)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/windows/psexec_module.html