ansible.builtin.shell 模块 – 在目标上执行 shell 命令

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，您也可以使用简短的模块名称 shell。但是，我们建议您使用 完全限定的集合名称 (FQCN) ansible.builtin.shell，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合冲突。

概要

注意

此模块具有相应的 action 插件。

参数

参数

注释

chdir

path

运行命令之前更改到此目录。

cmd

string

要运行的命令，后跟可选参数。

creates

path

文件名，如果文件已存在，则不会运行此步骤。

executable

path

更改用于执行命令的 shell。

这需要可执行文件的绝对路径。

free_form

string

shell 模块采用自由格式命令作为字符串运行。

没有名为“自由格式”的实际参数。

请参阅有关如何使用此模块的示例。

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

支持：完全支持

指示操作是否采用“原始”或“自由格式”字符串作为选项，并对其进行自己的特殊解析

备注

注意

  • 如果您想安全且可预测地执行命令，最好改用 ansible.builtin.command 模块。编写 playbook 时的最佳实践将遵循使用 ansible.builtin.command 的趋势，除非明确需要 ansible.builtin.shell 模块。运行临时命令时，请根据您的最佳判断。

  • 要清理传递给 shell 模块的任何变量，您应该使用 {{ var | quote }} 而不是 {{ var }}，以确保它们不包含分号等恶意内容。

  • 此模块使用内联 shell 脚本的替代方法是使用 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

关于 **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

changed

返回：始终

示例： 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

命令标准输出。

返回：始终

示例： "集群节点 rabbit@slave1 与 rabbit@master \u2026"

stdout_lines

list / elements=string

命令标准输出按行分割。

返回：始终

示例： ["u'集群节点 rabbit@slave1 与 rabbit@master \u2026'"]

作者

  • Ansible核心团队

  • Michael DeHaan