community.general.archive module – Creates a compressed archive of one or more files or trees
Note
This module is part of the community.general collection (version 9.4.0).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.archive
.
Synopsis
Creates or extends an archive.
The source and archive are on the remote host, and the archive is not copied to the local host.
Source files can be deleted after archival by specifying
remove=True
.
Requirements
The below requirements are needed on the host that executes this module.
Requires
lzma
(standard library of Python 3) or backports.lzma (Python 2) if usingxz
format.
Parameters
Parameter |
Comments |
---|---|
The attributes the resulting filesystem object should have. To get supported flags look at the man page for chattr on the target system. This string should contain the attributes in the same order as the one displayed by lsattr. The |
|
The file name of the destination archive. The parent directory must exists on the remote host. This is required when If the destination archive already exists, it will be truncated and overwritten. |
|
Remote absolute path, glob, or list of paths or globs for the file or files to exclude from Use Default: |
|
Glob style patterns to exclude files or directories from the resulting archive. This differs from |
|
Allows you to force the module to treat this as an archive even if only a single file is specified. By default when a single file is specified it is compressed only (not archived). Enable this if you want to use ansible.builtin.unarchive on an archive of a single file created with this module. Choices:
|
|
The type of compression to use. Choices:
|
|
Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
The permissions the resulting filesystem object should have. For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
|
Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
Remote absolute path, glob, or list of paths or globs for the file or files to compress or archive. |
|
Remove any added source files and trees after adding to archive. Choices:
|
|
The level part of the SELinux filesystem object context. This is the MLS/MCS attribute, sometimes known as the When set to |
|
The role part of the SELinux filesystem object context. When set to |
|
The type part of the SELinux filesystem object context. When set to |
|
The user part of the SELinux filesystem object context. By default it uses the When set to |
|
Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
Can produce
gzip
,bzip2
,lzma
, andzip
compressed files or archives.This module uses
tarfile
,zipfile
,gzip
, andbz2
packages on the target host to create archives. These are part of the Python standard library for Python 2 and 3.
See Also
See also
- ansible.builtin.unarchive
Unpacks an archive after (optionally) copying it from the local machine.
Examples
- 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
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
Any files that were compressed or added to the archive. Returned: success |
|
The archive root. Returned: always |
|
The list of matching exclude paths from the exclude_path argument. Returned: always |
|
The list of matching paths from paths argument. Returned: always |
|
Any files that were missing from the source. Returned: success |
|
The state of the input Returned: always |