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 字符串	生成的filesystem对象应具有的属性。 要获取支持的标志，请查看目标系统上 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 任意	生成的filesystem对象应具有的权限。 对于习惯于 /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	支持：不支持	强制执行不会按主机执行的“全局”任务，这会绕过按主机进行的模板化以及串行、节流和其他循环考虑因素 条件将按使用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

相关链接

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