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 模块。

注意

此模块具有相应的操作插件。

参数 

参数	注释
chdir 路径	在运行命令之前，先进入此目录。
cmd 字符串	要运行的命令，后跟可选参数。
creates 路径	文件名，当它已存在时，此步骤将不运行。
executable 路径	更改用于执行命令的 shell。这需要可执行文件的绝对路径。
free_form 字符串	shell 模块接受要运行的自由格式命令，作为字符串。没有名为“free form”的实际参数。有关如何使用此模块，请参阅示例。
removes 路径	文件名，当它不存在时，此步骤将不运行。
stdin 字符串	将命令的 stdin 直接设置为指定的值。
stdin_add_newline 布尔值在 Ansible 2.8 中添加	是否在 stdin 数据中附加换行符。选择 `false` `true` ←（默认）

属性 

属性	支持	描述
check_mode	支持: 部分虽然命令本身是任意的，并且不能受制于 check 模式语义，但它添加了 `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: 在目标主机上执行 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 布尔值	changed 返回: 总是示例: `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