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 模块。

注意

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

参数

参数	注释
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 文件系统对象上下文的级别部分。 这是 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	支持：不支持	强制执行不按主机执行的“全局”任务，这会绕过按主机模板化以及 serial、throttle 和其他循环考虑因素 条件将按使用run_once的方式工作，使用的变量将来自第一个可用的主机 此操作在非锁步策略之外通常无法正常工作
check_mode	支持：部分支持 不支持 gzip 压缩的 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文件。

• 不处理不包含.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”。 返回值：始终 示例： "directory"
uid 整数	目标目录所属用户的数字 ID。 返回值：始终 示例：1000

作者

• Michael DeHaan

集合链接

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