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

注意

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

摘要

注意

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

参数

参数

注释

chdir

路径

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

cmd

字符串

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

creates

路径

文件名，当它已存在时，此步骤将 **不会** 运行。

executable

路径

更改用于执行命令的 shell。

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

free_form

字符串

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

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

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

removes

路径

文件名，当它不存在时，此步骤将 **不会** 运行。

stdin

字符串

将命令的 stdin 直接设置为指定的值。

stdin_add_newline

布尔值

在 Ansible 2.8 中添加

是否将换行符附加到 stdin 数据。

选项

  • false

  • true ← (默认)

属性

属性

支持

描述

check_mode

支持：部分

虽然命令本身是任意的，并且不能受检查模式语义的影响，但它添加了 creates/removes 选项作为解决方法

可以在检查模式下运行并返回更改状态预测而无需修改目标，如果不受支持，则将跳过该操作。

diff_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

字符串

任务执行的命令。

返回：始终

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