ansible.builtin.shell 模块 - 在目标上执行 shell 命令
注意
此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使没有指定 collections 关键字，也可以使用简短的模块名称 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 |
可以对其进行操作的目标操作系统/系列 |
|
支持：全部 |
指示操作是否采用“raw”或“自由格式”字符串作为选项，以及它是否具有自己的特殊解析方式 |
注释
注意
如果您想安全可靠地执行命令，最好改用 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 表示成功)。 已返回：始终 示例： |
|
命令执行开始时间。 已返回：始终 示例： |
|
命令标准错误。 已返回：始终 示例： |
|
按行拆分的命令标准错误。 已返回：始终 示例： |
|
命令标准输出。 已返回：始终 示例： |
|
命令标准输出按行拆分。 已返回：始终 示例： |