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 以指示存档文件已存在于远程系统上，而不是本地控制器。 此选项与 copy 相互排斥。 选项 false ← (默认) true
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时被称为 range。 当设置为 _default 时，它将使用策略中的 level 部分（如果可用）。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 当设置为 _default 时，它将使用策略中的 role 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 当设置为 _default 时，它将使用策略中的 type 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 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 加密的 vault 文件

注意事项

注意

• 要求目标主机上具有 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

集合链接

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