Модуль ansible.builtin.shell — выполнение команд оболочки на целевых узлах

Примечание

Этот модуль входит в состав ansible-core и включен во все установки Ansible. В большинстве случаев можно использовать краткое имя модуля shell, не указывая ключевое слово collections. Тем не менее для удобства перехода к документации модуля и во избежание конфликтов с другими коллекциями, в которых может быть модуль с таким же именем, рекомендуется использовать полное имя коллекции (FQCN) ansible.builtin.shell.

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

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

Модуль ansible.builtin.shell принимает имя команды, за которым следует список аргументов, разделенных пробелами.
Требуется команда в свободной форме или параметр cmd; см. примеры.
Он почти полностью аналогичен модулю ansible.builtin.command, но выполняет команду через оболочку (/bin/sh) на удаленном узле.
Для целевых узлов Windows используйте модуль ansible.windows.win_shell.

Примечание

У этого модуля есть соответствующий модуль действий.

Параметры

Параметр	Комментарии
chdir path	Перейти в этот каталог перед выполнением команды.
cmd string	Команда для выполнения, за которой могут следовать аргументы.
creates path	Имя файла. Если файл уже существует, этот шаг не будет выполнен.
executable path	Изменить оболочку, используемую для выполнения команды. Ожидается абсолютный путь к исполняемому файлу.
free_form string	Модуль shell принимает команду для выполнения в виде строки свободной формы. Параметра с фактическим именем «free form» не существует. Примеры показывают, как использовать этот модуль.
removes path	Имя файла. Если файл не существует, этот шаг не будет выполнен.
stdin string	Задать для stdin команды непосредственно указанное значение.
stdin_add_newline boolean добавлено в Ansible 2.8	Добавлять ли символ новой строки к данным stdin. Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: частичная поскольку сама команда произвольна и не может соответствовать семантике режима проверки, добавляются параметры `creates`/`removes` в качестве обходного решения	Может работать в режиме check_mode и возвращать прогноз статуса изменений, не изменяя целевой узел; если поддержка отсутствует, действие будет пропущено.
diff_mode	Поддержка: отсутствует	В режиме diff будут возвращены сведения об изменениях (или о том, что, возможно, нужно изменить в режиме check_mode).
platform	Платформа: posix	Целевые ОС и семейства ОС, с которыми можно работать
raw	Поддержка: полная	Указывает, принимает ли действие строку «raw» или «free form» в качестве параметра и выполняет ли для нее собственный специальный разбор

Примечания

Примечание

Если вам нужно выполнять команды безопасно и предсказуемо, лучше использовать модуль ansible.builtin.command. При написании сценариев рекомендуется использовать ansible.builtin.command, если только явно не требуется модуль ansible.builtin.shell. При выполнении разовых команд руководствуйтесь здравым смыслом.
Чтобы обезопасить переменные, передаваемые модулю shell, следует использовать {{ var | quote }}, а не просто {{ var }}, чтобы исключить наличие опасных символов, например точки с запятой.
Вместо встроенных сценариев оболочки с этим модулем можно использовать модуль ansible.builtin.script, возможно, вместе с модулем ansible.builtin.template.
Для перезагрузки систем используйте модуль ansible.builtin.reboot или ansible.windows.win_reboot.
Если команда возвращает данные в кодировке, отличной от UTF-8, их необходимо закодировать, чтобы избежать проблем. Один из вариантов — передать вывод через base64.

См. также

ansible.builtin.command: Выполняет команды на целевых узлах.
ansible.builtin.raw: Выполняет низкоуровневую команду без предварительной обработки.
ansible.builtin.script: Передает локальный сценарий на удаленный узел и выполняет его.
ansible.windows.win_shell: Выполняет команды оболочки на целевых узлах.

Примеры

- name: Execute the command in remote shell; stdout goes to the specified file on the remote
  ansible.builtin.shell: somescript.sh >> somelog.txt

- name: Change the working directory to somedir/ before executing the command
  ansible.builtin.shell: somescript.sh >> somelog.txt
  args:
    chdir: somedir/

# You can also use the 'args' form to provide the options.
- name: This command will change the working directory to somedir/ and will only run when somedir/somelog.txt doesn't exist
  ansible.builtin.shell: somescript.sh >> somelog.txt
  args:
    chdir: somedir/
    creates: somelog.txt

# You can also use the 'cmd' parameter instead of free form format.
- name: This command will change the working directory to somedir/
  ansible.builtin.shell:
    cmd: ls -l | grep log
    chdir: somedir/

- name: Run a command that uses non-posix shell-isms (in this example /bin/sh doesn't handle redirection and wildcards together but bash does)
  ansible.builtin.shell: cat < /tmp/*txt
  args:
    executable: /bin/bash

- name: Run a command using a templated variable (always use quote filter to avoid injection)
  ansible.builtin.shell: cat {{ myfile|quote }}

# You can use shell to run other executables to perform actions inline
- name: Run expect to wait for a successful PXE boot via out-of-band CIMC
  ansible.builtin.shell: |
    set timeout 300
    spawn ssh admin@{{ cimc_host }}

    expect "password:"
    send "{{ cimc_password }}\n"

    expect "\n{{ cimc_name }}"
    send "connect host\n"

    expect "pxeboot.n12"
    send "\n"

    exit 0
  args:
    executable: /usr/bin/expect
  delegate_to: localhost

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
cmd string	Команда, выполненная задачей. Возвращается: всегда Пример: `"rabbitmqctl join_cluster rabbit@master"`
delta string	Продолжительность выполнения команды. Возвращается: всегда Пример: `"0:00:00.325771"`
end string	Время завершения выполнения команды. Возвращается: всегда Пример: `"2016-02-25 09:18:26.755339"`
msg boolean	изменено Возвращается: всегда Пример: `true`
rc integer	Код возврата команды (0 означает успешное выполнение). Возвращается: всегда Пример: `0`
start string	Время начала выполнения команды. Возвращается: всегда Пример: `"2016-02-25 09:18:26.429568"`
stderr string	Поток стандартных ошибок команды. Возвращается: всегда Пример: `"ls: cannot access foo: No such file or directory"`
stderr_lines list / elements=string	Поток стандартных ошибок команды, разбитый на строки. Возвращается: всегда Пример: `[{"u'ls cannot access foo": "No such file or directory'"}, "u'ls \u2026'"]`
stdout string	Поток стандартного вывода команды. Возвращается: всегда Пример: `"Clustering node rabbit@slave1 with rabbit@master \u2026"`
stdout_lines list / elements=string	Поток стандартного вывода команды, разбитый на строки. Возвращается: всегда Пример: `["u'Clustering node rabbit@slave1 with rabbit@master \u2026'"]`

Авторы

Команда Ansible Core
Michael DeHaan

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

© 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/ansible/builtin/shell_module.html