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 模块。
注意
此模块具有相应的 操作插件。
参数
参数 |
注释 |
|---|---|
在运行命令之前更改到此目录。 |
|
要运行的命令，后跟可选参数。 |
|
文件名，如果该文件已存在，则不会运行此步骤。 |
|
更改用于执行命令的 shell。 这需要可执行文件的绝对路径。 |
|
shell 模块将一个自由格式的命令作为字符串运行。 没有名为“自由格式”的实际参数。 请参阅关于如何使用此模块的示例。 |
|
文件名，如果该文件不存在，则不会运行此步骤。 |
|
将命令的 stdin 直接设置为指定的值。 |
|
是否在 stdin 数据后面追加换行符。 选项
|
属性
属性 |
支持 |
描述 |
|---|---|---|
可以在 check_mode 下运行并返回更改状态预测，而无需修改目标，如果不受支持，则操作将被跳过。 |
||
支持：无 |
在 diff 模式下，将返回有关更改内容（或可能需要在 check_mode 下更改的内容）的详细信息 |
|
平台： posix |
可以针对其进行操作的目标操作系统/系列 |
|
支持：完整 |
指示操作是否采用“原始”或“自由格式”字符串作为选项，并具有自己的特殊解析方式 |
注释
注意
如果您想以安全和可预测的方式执行命令，最好使用 ansible.builtin.command 模块。编写剧本时的最佳实践将遵循使用 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
返回值
常见返回值在 此处 文档中介绍，以下为此模块独有的字段
键 |
描述 |
|---|---|
任务执行的命令。 已返回：始终 示例： |
|
命令执行的增量时间。 已返回：始终 示例： |
|
命令执行结束时间。 已返回：始终 示例： |
|
已更改 已返回：始终 示例： |
|
命令返回值（0 表示成功）。 已返回：始终 示例： |
|
命令执行开始时间。 已返回：始终 示例： |
|
命令标准错误。 已返回：始终 示例： |
|
命令的标准错误输出，按行分割。 已返回：始终 示例： |
|
命令的标准输出。 已返回：始终 示例： |
|
命令的标准输出，按行分割。 已返回：始终 示例： |