ansible.builtin.command 模块 – 在目标上执行命令
注意
此模块是 ansible-core
的一部分,包含在所有 Ansible 安装中。在大多数情况下,即使不指定 collections 关键字,您也可以使用简短的模块名称 command
。但是,我们建议您使用 完全限定集合名称 (FQCN) ansible.builtin.command
,以便轻松链接到模块文档并避免与其他可能具有相同模块名称的集合冲突。
概要
ansible.builtin.command 模块接受命令名称,后跟一个以空格分隔的参数列表。
给定的命令将在所有选定的节点上执行。
命令将不会通过 shell 处理,因此诸如
"*"
、"<"
、">"
、"|"
、";"
和"&"
之类的操作将不起作用。此外,环境变量通过 Python 而不是 shell 解析,请参阅expand_argument_vars
,如果未匹配则保持不变。如果需要这些功能,请使用 ansible.builtin.shell 模块。为了创建比使用空格分隔参数更容易阅读的
command
任务,请使用args
任务关键字传递参数,或使用cmd
参数。需要自由格式的命令或
cmd
参数,请参阅示例。对于 Windows 目标,请改用 ansible.windows.win_command 模块。
注意
此模块具有相应的 action 插件。
参数
参数 |
注释 |
---|---|
在运行命令之前更改到此目录。 |
|
要运行的命令。 |
|
文件名或(自 2.0 起)glob 模式。如果匹配的文件已经存在,则不会运行此步骤。 这会在检查 |
|
展开作为变量的参数,例如 如果变量不匹配,则保持不变,这与 shell 替换会将其删除不同。 设置为 选择
|
|
command 模块将自由格式字符串作为要运行的命令。 没有名为“自由格式”的实际参数。 |
|
文件名或(自 2.0 起)glob 模式。如果匹配的文件存在,则会运行此步骤。 这在检查 |
|
将命令的 stdin 直接设置为指定的值。 |
|
如果设置为 选择
|
|
从结果的 stdout/stderr 末尾删除空行。 选择
|
属性
属性 |
支持 |
描述 |
---|---|---|
可以在 check_mode 下运行,并返回更改状态预测,而无需修改目标,如果不支持,则会跳过该操作。 |
||
支持: 不支持 |
在 diff 模式下,将返回已更改的详细信息(或在 check_mode 中可能需要更改的内容) |
|
平台: posix |
可以对其进行操作的目标操作系统/系列 |
|
支持: 完全支持 |
指示操作是否将“raw”或“自由形式”字符串作为选项,并且具有其自己的特殊解析 |
备注
注意
如果要通过 shell 运行命令(例如,使用
<
、>
、|
等),实际上您需要的是 ansible.builtin.shell 模块。 如果未正确进行引号,解析 shell 元字符可能会导致执行意外的命令,因此在可能的情况下,使用 ansible.builtin.command 模块更安全。creates
、removes
和chdir
可以在命令之后指定。 例如,如果您只想在某个文件不存在时运行命令,请使用此选项。当传递
creates
或removes
时,支持检查模式。如果在检查模式下运行并且指定了其中任何一个,则该模块将检查文件是否存在并报告正确的更改状态。 如果未提供这些选项,则将跳过该任务。自 2.4 版本起,
executable
参数已删除。 如果您需要此参数,请改用 ansible.builtin.shell 模块。对于 Windows 目标,请改用 ansible.windows.win_command 模块。
对于重新启动系统,请使用 ansible.builtin.reboot 或 ansible.windows.win_reboot 模块。
如果命令返回非 UTF-8 数据,则必须对其进行编码以避免问题。 这可能需要使用 ansible.builtin.shell,以便可以通过
base64
管道输出。
另请参阅
另请参阅
- ansible.builtin.raw
执行一个底层命令。
- ansible.builtin.script
在传输到远程节点后,在该节点上运行本地脚本。
- ansible.builtin.shell
在目标上执行 shell 命令。
- ansible.windows.win_command
在远程 Windows 节点上执行命令。
示例
- name: Return motd to registered var
ansible.builtin.command: cat /etc/motd
register: mymotd
# free-form (string) arguments, all arguments on one line
- name: Run command if /path/to/database does not exist (without 'args')
ansible.builtin.command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database
# free-form (string) arguments, some arguments on separate lines with the 'args' keyword
# 'args' is a task keyword, passed at the same level as the module
- name: Run command if /path/to/database does not exist (with 'args' keyword)
ansible.builtin.command: /usr/bin/make_database.sh db_user db_name
args:
creates: /path/to/database
# 'cmd' is module parameter
- name: Run command if /path/to/database does not exist (with 'cmd' parameter)
ansible.builtin.command:
cmd: /usr/bin/make_database.sh db_user db_name
creates: /path/to/database
- name: Change the working directory to somedir/ and run the command as db_owner if /path/to/database does not exist
ansible.builtin.command: /usr/bin/make_database.sh db_user db_name
become: yes
become_user: db_owner
args:
chdir: somedir/
creates: /path/to/database
# argv (list) arguments, each argument on a separate line, 'args' keyword not necessary
# 'argv' is a parameter, indented one level from the module
- name: Use 'argv' to send a command as a list - leave 'command' empty
ansible.builtin.command:
argv:
- /usr/bin/make_database.sh
- Username with whitespace
- dbname with whitespace
creates: /path/to/database
- name: Run command using argv with mixed argument formats
ansible.builtin.command:
argv:
- /path/to/binary
- -v
- --debug
- --longopt
- value for longopt
- --other-longopt=value for other longopt
- positional
- name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues
ansible.builtin.command: cat {{ myfile|quote }}
register: myoutput
返回值
常见的返回值记录在 此处,以下是此模块特有的字段
键 |
描述 |
---|---|
任务执行的命令。 返回: 总是 示例: |
|
命令执行的增量时间。 返回: 总是 示例: |
|
命令执行结束时间。 返回: 总是 示例: |
|
changed 返回: 总是 示例: |
|
命令返回代码(0 表示成功)。 返回: 总是 示例: |
|
命令执行开始时间。 返回: 总是 示例: |
|
命令的标准错误。 返回: 总是 示例: |
|
命令的标准错误,按行拆分。 返回: 总是 示例: |
|
命令的标准输出。 返回: 总是 示例: |
|
命令的标准输出,按行拆分。 返回: 总是 示例: |