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

注意

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

概要 

ansible.builtin.shell 模块接受命令名称，后跟一个空格分隔的参数列表。
必须提供自由形式的命令或 cmd 参数，请参阅示例。
它几乎与 ansible.builtin.command 模块完全相同，但通过远程节点上的 shell (/bin/sh) 运行命令。
对于 Windows 目标，请改用 ansible.windows.win_shell 模块。

注意

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

参数 

参数	注释
chdir 路径	在运行命令之前更改到此目录。
cmd 字符串	要运行的命令，后跟可选参数。
creates 路径	文件名，当它已经存在时，此步骤将不会运行。
executable 路径	更改用于执行命令的 shell。此处应使用可执行文件的绝对路径。
free_form 字符串	shell 模块接受要运行的自由形式命令，作为字符串。没有名为 “free form” 的实际参数。请参阅有关如何使用此模块的示例。
removes 路径	文件名，当它不存在时，此步骤将不会运行。
stdin 字符串	直接将命令的 stdin 设置为指定值。
stdin_add_newline 布尔值在 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 模块。编写 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 字符串	任务执行的命令。返回：始终示例： `"rabbitmqctl join_cluster rabbit@master"`
delta 字符串	命令执行增量时间。返回：始终示例： `"0:00:00.325771"`
end 字符串	命令执行结束时间。返回：始终示例： `"2016-02-25 09:18:26.755339"`
msg 布尔值	已更改返回：始终示例: `true`
rc 整数	命令返回代码 (0 表示成功)。返回：始终示例: `0`
start 字符串	命令执行的开始时间。返回：始终示例: `"2016-02-25 09:18:26.429568"`
stderr 字符串	命令的标准错误。返回：始终示例: `"ls: cannot access foo: No such file or directory"`
stderr_lines 列表 / 元素=字符串	命令的标准错误，按行分割。返回：始终示例: `[{"u'ls cannot access foo": "No such file or directory'"}, "u'ls \u2026'"]`
stdout 字符串	命令的标准输出。返回：始终示例: `"Clustering node rabbit@slave1 with rabbit@master \u2026"`
stdout_lines 列表 / 元素=字符串	命令的标准输出，按行分割。返回：始终示例: `["u'Clustering node rabbit@slave1 with rabbit@master \u2026'"]`

作者

Ansible 核心团队
Michael DeHaan