ansible.builtin.unarchive 模块 - 在（可选）从本地机器复制后解压缩存档

注意

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

概要

• ansible.builtin.unarchive 模块解压缩存档。它不会解压缩不包含存档的压缩文件。

• 默认情况下，它会在解压缩之前将源文件从本地系统复制到目标。

• 设置 remote_src=yes 以解压缩已存在于目标上的存档。

• 如果需要校验和验证，请使用 ansible.builtin.get_url 或 ansible.builtin.uri 来获取文件并设置 remote_src=yes。

• 对于 Windows 目标，请改用 community.windows.win_unzip 模块。

注意

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

参数

参数	注释
attributes 别名：attr 字符串	结果文件系统对象应具有的属性。 要获得支持的标志，请查看目标系统上 chattr 的手册页。 此字符串应包含与 lsattr 显示的属性相同的顺序。 默认情况下，假定使用 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
copy 布尔值	如果为真，则将文件从本地控制器复制到托管（远程）节点，否则，插件将在托管机器上查找 src 存档。 此选项已弃用，建议使用 remote_src。 此选项与 remote_src 互斥。 选项 false true ← (默认)
creates 路径	如果指定绝对路径（文件或目录）已存在，则不会运行此步骤。 指定绝对路径（文件或目录）必须位于使用 dest 给出的基本路径之下。
decrypt 布尔值	此选项控制使用 vault 自动解密源文件。 选项 false true ← (默认)
dest 路径 / 必需	应该解压缩存档的远程绝对路径。 给定的路径必须存在。此模块不会创建基本目录。
exclude 列表 / 元素=字符串	列出要从解压缩操作中排除的目录和文件条目。 与 include 互斥。 默认： []
extra_opts 列表 / 元素=字符串	通过传递一个数组来指定其他选项。 每个用空格分隔的命令行选项都应该是数组中的一个新元素。请参见示例。 具有多个元素的命令行选项必须在数组中使用多行，每行一个元素。 默认： []
group 字符串	应该拥有文件系统对象的组的名称，就像传递给 chown 一样。 未指定时，它使用当前用户的当前组，除非您是 root 用户，在这种情况下它可以保留以前的拥有权。
include 列表 / 元素=字符串 在 ansible-core 2.11 中添加	要从存档中提取的目录和文件条目的列表。如果 include 不为空，则只会提取此处列出的文件。 与 exclude 互斥。 默认： []
io_buffer_size 整数 在 ansible-core 2.12 中添加	用于从存档中以字节为单位提取文件的易失内存缓冲区的大小。 默认： 65536
keep_newer 布尔值	不要替换比存档中的文件更新的现有文件。 选项 false ← (默认) true
list_files 布尔值	如果设置为 True，则返回包含在 tarball 中的文件列表。 选项 false ← (默认) true
mode 任何	结果文件系统对象应具有的权限。 对于习惯使用 /usr/bin/chmod 的人，请记住模式实际上是八进制数。您必须提供足够的 Ansible 信息以正确解析它们。为了获得一致的结果，请引用八进制数（例如，'644' 或 '1777'），以便 Ansible 接收一个字符串并可以将其从字符串转换为数字。添加前导零（例如，0755）有时有效，但在循环和其他情况下可能会失败。 如果在不遵循上述任何规则的情况下向 Ansible 提供一个数字，最终将得到一个十进制数，这将产生意外的结果。 从 Ansible 1.8 开始，模式可以指定为符号模式（例如，u+rwx 或 u=rw,g=r,o=r）。 如果未指定 mode 且目标文件系统对象不存在，则在为新创建的文件系统对象设置模式时，将使用系统上的默认 umask。 如果未指定 mode 且目标文件系统对象 **存在**，则将使用现有文件系统对象的模式。 指定 mode 是确保以正确权限创建文件系统对象的最佳方式。有关详细信息，请参阅 CVE-2020-1736。
owner 字符串	应拥有文件系统对象的用户的名称，如提供给 chown 一样。 如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下它可以保留先前的所有权。 指定数字用户名将被假定为用户 ID 而不是用户名。避免使用数字用户名以避免此混淆。
remote_src 布尔值	设置为 true 以指示存档文件已存在于远程系统上，而不是 Ansible 控制器本地。 此选项与 copy 互斥。 选项 false ← (默认) true
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时被称为 range。 当设置为 _default 时，它将使用策略中的 level 部分（如果可用）。
serole 字符串	SELinux 文件系统对象上下文的 role 部分。 当设置为 _default 时，它将使用策略中的 role 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的 type 部分。 当设置为 _default 时，它将使用策略中的 type 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的 user 部分。 默认情况下，它使用 system 策略（如果适用）。 当设置为 _default 时，它将使用策略中的 user 部分（如果可用）。
src 路径 / 必需	如果 remote_src=no（默认值），则为要复制到目标服务器的存档文件的本地路径；可以是绝对路径或相对路径。如果 remote_src=yes，则为目标服务器上现有存档文件的路径，用于解压缩。 如果 remote_src=yes 且 src 包含 ://，则远程机器将首先从 URL 下载该文件。（version_added 2.0）。这仅适用于简单情况，对于完整的下载支持，请使用 ansible.builtin.get_url 模块。
unsafe_writes 布尔值	影响何时使用原子操作来防止数据损坏或目标文件系统对象的不一致读取。 默认情况下，此模块使用原子操作来防止数据损坏或目标文件系统对象的不一致读取，但有时系统会以阻止此操作的方式进行配置或出现故障。一个示例是 docker 挂载的文件系统对象，它们不能从容器内部以原子方式更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要！不安全的写入容易出现竞争条件，并可能导致数据损坏。 选项 false ← (默认) true
validate_certs 布尔值	这仅适用于使用 https URL 作为文件来源的情况。 这应该只设置为 false，用于使用自签名证书的个人控制的站点。 在 2.2 之前，代码的工作方式就像它设置为 true 一样。 选项 false true ← (默认)

属性

属性	支持	描述
action	支持：完全支持	表示它具有相应的 action 插件，因此一些选项的部分可以在控制器上执行
async	支持：不支持	支持与 async 关键字一起使用
bypass_host_loop	支持：不支持	强制执行不按主机执行的“全局”任务，这会绕过按主机模板和串行、节流和其他循环考虑因素 条件将按使用 run_once 那样工作，使用的变量将来自第一个可用的主机 此操作在锁步策略之外无法正常工作
check_mode	支持：部分支持 不支持压缩的 tar 文件。	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标，如果不受支持，则该操作将被跳过。
diff_mode	支持：部分支持 使用 gtar 的 --diff 参数来计算是否已更改。如果此 arg 不受支持，它将始终解压缩存档。	将在 diff 模式下返回关于更改内容（或可能需要更改的内容在 check_mode 中）的详细信息。
platform	平台： posix	可以对其进行操作的目标操作系统/系列
safe_file_operations	支持：不支持	使用 Ansible 的严格文件操作功能来确保适当的权限并避免数据损坏
vault	支持：完全支持	可以自动解密 Ansible 拱顶文件

备注

注意

• 需要目标主机上的 zipinfo 和 gtar/unzip 命令。

• 需要目标主机上的 zstd 命令来扩展 .tar.zst 文件。

• 可以使用 unzip 处理 .zip 文件，以及使用 gtar 处理 .tar、.tar.gz、.tar.bz2、.tar.xz 和 .tar.zst 文件。

• 不处理 .gz 文件、.bz2 文件、.xz 或 .zst 文件，这些文件不包含 .tar 存档。

• 不修改目标中的现有文件/目录，这些文件/目录不在存档中。这与正常的存档提取行为相同。

• 目标中的现有文件/目录，这些文件/目录不在存档中，将被忽略，用于决定是否应该解压缩存档。

另请参阅

另请参阅

community.general.archive

community.general.archive 模块的官方文档。

community.general.iso_extract

community.general.iso_extract 模块的官方文档。

community.windows.win_unzip

community.windows.win_unzip 模块的官方文档。

示例

- name: Extract foo.tgz into /var/lib/foo
  ansible.builtin.unarchive:
    src: foo.tgz
    dest: /var/lib/foo

- name: Unarchive a file that is already on the remote machine
  ansible.builtin.unarchive:
    src: /tmp/foo.zip
    dest: /usr/local/bin
    remote_src: yes

- name: Unarchive a file that needs to be downloaded (added in 2.0)
  ansible.builtin.unarchive:
    src: https://example.com/example.zip
    dest: /usr/local/bin
    remote_src: yes

- name: Unarchive a file with extra options
  ansible.builtin.unarchive:
    src: /tmp/foo.zip
    dest: /usr/local/bin
    extra_opts:
    - --transform
    - s/^xxx/yyy/

返回值

常见的返回值已在 此处 文档中说明，以下字段是此模块独有的

Key	描述
dest 字符串	目标目录的路径。 返回：始终 示例： "/opt/software"
files 列表 / 元素=字符串	存档中所有文件的列表。 返回：当 list_files 为 True 时 示例： ["[\"file1\"", " \"file2\"]"]
gid 整数	拥有目标目录的组的数字 ID。 返回：始终 示例： 1000
group 字符串	拥有目标目录的组的名称。 返回：始终 示例： "librarians"
handler 字符串	用于提取和解压缩存档的存档软件处理程序。 返回：始终 示例： "TgzArchive"
mode 字符串	表示目标目录的八进制权限的字符串。 返回：始终 示例： "0755"
owner 字符串	拥有目标目录的用户的名称。 返回：始终 示例： "paul"
size 整数	目标目录的大小（以字节为单位）。不包括其中包含的文件或子目录的大小。 返回：始终 示例： 36
src 字符串	源存档的路径。 如果 src 是远程 web URL 或来自本地 ansible 控制器，则这将显示下载存储的临时位置。 返回：始终 示例： "/home/paul/test.tar.gz"
state 字符串	目标的状态。实际上始终为“directory”。 返回：始终 示例： "directory"
uid 整数	拥有目标目录的用户数字 ID。 返回：始终 示例： 1000

作者

• Michael DeHaan

收藏链接

• 问题追踪器
• 仓库（来源）
• 通信