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 插件。

参数

参数	注释
argv 列表 / 元素=字符串	将命令作为列表而不是字符串传递。 使用 argv 可以避免对会被错误解释的值（例如“用户名”）进行引用。 只能提供字符串（自由格式）或列表（argv）形式，不能同时提供两种形式。必须提供其中一种。
chdir 路径	在运行命令之前更改到此目录。
cmd 字符串	要运行的命令。
creates 路径	文件名或（自 2.0 起）glob 模式。如果匹配的文件已存在，则不会运行此步骤。 在检查 removes 之前检查此项。
expand_argument_vars 布尔值 在 ansible-core 2.16 中添加	扩展作为变量的参数，例如 $HOME 将在传递到要运行的命令之前进行扩展。 如果变量不匹配，则保持不变，这与 shell 替换（会将其删除）不同。 设置为 false 以禁用扩展并将值视为文字参数。 选项 false true ← (默认)
free_form 字符串	command 模块将自由格式字符串作为要运行的命令。 没有名为 free_form 的实际参数。
removes 路径	文件名或（自 2.0 起）glob 模式。如果匹配的文件存在，则会运行此步骤。 在检查 creates 之后检查此项。
stdin 字符串	将命令的 stdin 直接设置为指定的值。
stdin_add_newline 布尔值 在 Ansible 2.8 中添加	如果设置为 true，则在 stdin 数据末尾附加换行符。 选项 false true ← (默认)
strip_empty_ends 布尔值 在 Ansible 2.8 中添加	从结果中 stdout/stderr 的末尾去除空行。 选项 false true ← (默认)

属性

属性	支持	描述
check_mode	支持：部分 虽然命令本身是任意的，并且不能符合检查模式语义，但它添加了 creates/removes 选项作为解决方法	可以在 check_mode 下运行并返回更改状态预测，而无需修改目标，如果不支持，则会跳过该操作。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在 check_mode 下更改的内容）的详细信息
platform	平台： 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

关于 **ansible.windows.win_command** 模块的官方文档。

示例

- 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

返回值

常见的返回值已在 此处 记录，以下是此模块特有的字段

Key	描述
cmd 列表 / 元素=字符串	任务执行的命令。 返回值： 始终 示例： ["echo", "hello"]
delta 字符串	命令执行时间差。 返回值： 始终 示例： "0:00:00.001529"
end 字符串	命令执行结束时间。 返回值： 始终 示例： "2017-09-29 22:03:48.084657"
msg 布尔值	changed 返回值： 始终 示例： true
rc 整数	命令返回码 (0 表示成功)。 返回值： 始终 示例： 0
start 字符串	命令执行开始时间。 返回值： 始终 示例： "2017-09-29 22:03:48.083128"
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

资源链接

• 问题追踪器
• 代码仓库
• 通信