community.general.archive 模块 – 创建一个或多个文件或树的压缩存档

注意

此模块是 community.general 集合（版本 10.1.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。您需要其他要求才能使用此模块，有关详细信息，请参见 要求。

要在 playbook 中使用它，请指定：community.general.archive。

概要

• 创建或扩展存档。

• 源文件和存档位于远程主机上，并且存档不会复制到本地主机。

• 可以通过指定 remove=True 在存档后删除源文件。

要求

以下要求需要在执行此模块的主机上满足。

• 如果使用 xz 格式，则需要 lzma（Python 3 的标准库）或 backports.lzma (Python 2)。

参数

参数	注释
attributes 别名: attr 字符串	生成的的文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上的 chattr 的手册页。 此字符串应包含与 lsattr 显示的顺序相同的属性。 默认情况下假定使用 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
dest 路径	目标存档的文件名。父目录必须存在于远程主机上。 当 path 通过指定 glob、目录或列表中多个路径来引用多个文件时，这是必需的。 如果目标存档已存在，它将被截断并覆盖。
exclude_path 列表 / 元素=路径	要从 path 列表和 glob 扩展中排除的远程绝对路径、glob 或路径或 glob 的列表。 使用 exclusion_patterns 来代替排除 path 列表中的任何路径下的文件或子目录。 默认值： []
exclusion_patterns 列表 / 元素=路径 在 community.general 3.2.0 中添加	从结果存档中排除文件或目录的 glob 样式模式。 这与 exclude_path 不同，后者仅适用于 path 中的源路径。
force_archive 布尔值	允许您强制模块将其视为存档，即使仅指定了一个文件。 默认情况下，当指定单个文件时，它仅被压缩（而不是存档）。 如果要在此模块创建的单个文件的存档上使用 ansible.builtin.unarchive，请启用此选项。 选择 false ←（默认） true
格式 字符串	要使用的压缩类型。 选择 “bz2” "gz" ← (默认) “tar” “xz” “zip”
组 字符串	应该拥有文件系统对象的组的名称，如同传递给chown命令一样。 如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下它可以保留之前的属主关系。
模式 任意	生成的文件系统对象应具有的权限。 对于那些习惯使用 /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。
所有者 字符串	应该拥有文件系统对象的用户的名称，如同传递给 chown 命令一样。 如果未指定，它将使用当前用户，除非您是 root 用户，在这种情况下它可以保留之前的属主关系。 指定数字用户名将被视为用户 ID，而不是用户名。为避免混淆，请避免使用数字用户名。
路径 列表 / 元素=路径 / 必需	要压缩或归档的文件或文件组的远程绝对路径、glob 模式或路径或 glob 模式列表。
移除 布尔值	在添加到归档文件后，移除所有添加的源文件和目录树。 选择 false ←（默认） true
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 range。 当设置为 _default 时，如果可用，它将使用策略的 level 部分。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 当设置为 _default 时，如果可用，它将使用策略的 role 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 当设置为 _default 时，如果可用，它将使用策略的 type 部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 system 策略（如果适用）。 当设置为 _default 时，如果可用，它将使用策略的 user 部分。
unsafe_writes 布尔值	影响何时使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统的配置方式或只是损坏的方式会阻止这种情况。一个例子是 Docker 挂载的文件系统对象，它无法从容器内部原子地更新，并且只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时退回到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要提示！不安全的写入会受到竞争条件的影响，并可能导致数据损坏。 选择 false ←（默认） true

属性

属性	支持	描述
check_mode	支持: 完全	可以在 check_mode 中运行，并返回更改状态预测，而无需修改目标。
diff_mode	支持: 无	在 diff 模式下，将返回有关已更改的内容（或可能需要在 check_mode 中更改的内容）的详细信息。

注释

注意

• 可以生成 gzip、bzip2、lzma 和 zip 压缩文件或归档文件。

• 此模块在目标主机上使用 tarfile、zipfile、gzip 和 bz2 包来创建归档文件。这些是 Python 2 和 3 的 Python 标准库的一部分。

参见

另请参阅

ansible.builtin.unarchive

（可选）从本地计算机复制归档文件后将其解压缩。

示例

- name: Compress directory /path/to/foo/ into /path/to/foo.tgz
  community.general.archive:
    path: /path/to/foo
    dest: /path/to/foo.tgz

- name: Compress regular file /path/to/foo into /path/to/foo.gz and remove it
  community.general.archive:
    path: /path/to/foo
    remove: true

- name: Create a zip archive of /path/to/foo
  community.general.archive:
    path: /path/to/foo
    format: zip

- name: Create a bz2 archive of multiple files, rooted at /path
  community.general.archive:
    path:
    - /path/to/foo
    - /path/wong/foo
    dest: /path/file.tar.bz2
    format: bz2

- name: Create a bz2 archive of a globbed path, while excluding specific dirnames
  community.general.archive:
    path:
    - /path/to/foo/*
    dest: /path/file.tar.bz2
    exclude_path:
    - /path/to/foo/bar
    - /path/to/foo/baz
    format: bz2

- name: Create a bz2 archive of a globbed path, while excluding a glob of dirnames
  community.general.archive:
    path:
    - /path/to/foo/*
    dest: /path/file.tar.bz2
    exclude_path:
    - /path/to/foo/ba*
    format: bz2

- name: Use gzip to compress a single archive (i.e don't archive it first with tar)
  community.general.archive:
    path: /path/to/foo/single.file
    dest: /path/file.gz
    format: gz

- name: Create a tar.gz archive of a single file.
  community.general.archive:
    path: /path/to/foo/single.file
    dest: /path/file.tar.gz
    format: gz
    force_archive: true

返回值

常见的返回值记录在此处，以下是此模块特有的字段

键	描述
archived 列表 / 元素=字符串	任何已压缩或添加到归档文件的文件。 返回: 成功
arcroot 字符串	归档根目录。 返回: 始终
dest_state 字符串 在 community.general 3.4.0 中添加	dest 文件的状态。 文件不存在时为 absent。 文件是归档文件时为 archive。 文件被压缩但不是归档文件时为 compress。 文件是归档文件，但未找到 path 下的某些文件时为 incomplete。 返回: 成功
expanded_exclude_paths 列表 / 元素=字符串	来自 exclude_path 参数的匹配排除路径列表。 返回: 始终
expanded_paths 列表 / 元素=字符串	来自 paths 参数的匹配路径列表。 返回: 始终
missing 列表 / 元素=字符串	源中缺失的任何文件。 返回: 成功
状态 字符串	输入 path 的状态。 返回: 始终

作者

• Ben Doherty (@bendoh)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 请求帮助
• 提交错误报告
• 请求功能
• 沟通