ansible.builtin.unarchive 模块 – 解压归档文件，可选择先从本地机器复制

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，也可以使用短模块名称 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 模块。

注意

此模块具有相应的 action 插件。

参数

参数	注释
attributes 别名: attr 字符串	生成的 文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上 chattr 的手册页。 此字符串应包含与 lsattr 显示的顺序相同的属性。 默认情况下假定使用 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
copy 布尔值	如果为 true，则文件将从本地控制器复制到受管（远程）节点，否则，插件将在受管机器上查找 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 文件系统对象上下文的 level 部分。 这是 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 下载文件。(版本新增 2.0)。这仅适用于简单情况，对于完整的下载支持，请使用 ansible.builtin.get_url 模块。
unsafe_writes 布尔值	影响何时使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的内容。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的内容，但有时系统的配置方式或只是以阻止这种情况的方式损坏。一个例子是 Docker 挂载的文件系统对象，这些对象无法从容器内部原子地更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的方法来更新文件系统对象（但是，它不会强制 Ansible 执行不安全的写入）。 重要提示！不安全的写入容易受到竞争条件的影响，并可能导致数据损坏。 选择 false ← (默认) true
validate_certs 布尔值	仅当使用 https URL 作为文件来源时才适用。 仅当在个人控制的使用自签名证书的站点上使用时，才应将其设置为 false。 在 2.2 之前的版本中，代码的行为就像将其设置为 true。 选择 false true ← (默认)

属性

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

备注

注意

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

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

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

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

• 目标中不在存档中的现有文件/目录不会被触及。这与正常存档提取的行为相同。

• 目标中不在存档中的现有文件/目录在决定是否应解压缩存档时会被忽略。

另请参阅

另请参阅

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/

返回值

通用返回值记录在此处，以下是此模块独有的字段

键	描述
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"
uid 整数	拥有目标目录的用户的数字 ID。 返回: 始终 示例: 1000

作者

• Michael DeHaan

集合链接

• 问题跟踪器
• 存储库（源代码）
• 通信