unpack_archive
unpack_archive extracts an archive into a directory of its own on a node,
such as one release of an application. It takes the archive from a pinned
url or a local source on the controller machine. MMX recognizes the
format from the file's contents, not its name: a tar, plain (.tar) or
compressed with gzip (.tar.gz, .tgz), xz (.tar.xz), bzip2 (.tar.bz2),
or zstd (.tar.zst), or a zip. Anything else fails.
For a single file from a web address, use download. For a
release that lives in a Git repository, use git.
Inputs
source(string; optional): local archive file, relative to the project root, or to the role's directory inside a role; one of source or urlurl(string; optional): HTTPS URL, fetched and verified on the controller like download; one of source or url; may read vars, role inputs, loop items, and .node.namesha256(string; optional): the archive's SHA-256 in hex; with url, exactly one of sha256 or dangerously_skip_checksumdangerously_skip_checksum(boolean; defaultfalse): true in place of sha256: the archive is unpacked as it arrives, with no check that it is the file you expectpath(string; required): absolute; the parent must exist; extract each version to its own pathowner(account name or integer; defaultroot): owns every extracted entry; the archive's IDs are ignored; a numeric ID is written without quotesgroup(group name or integer; defaultroot): a numeric ID is written without quotesunpack_without_wrapping_folder(boolean; defaultfalse): true leaves out the one top-level folder many release archives have, so its contents land directly in path; fails if anything lies outside that folderalso_delete_everything_inside(boolean; defaultfalse): required with state: absent, because removal deletes the whole extracted treestate(presentorabsent; defaultpresent): absent removes a directory an unpack_archive task extracted, with its whole tree; requires also_delete_everything_inside: true
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangevalue.entries
What a dryrun reports
Supported; fetches and verifies a url, then checks every entry, and that the files fit while 5% of the filesystem stays free, and counts them without extracting; not_checked while the parent directory is missing, unless an earlier node task of the dryrun would create it.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Unpack a release and switch a symlink
Deploy each release into its own directory on the node. Point a tracked
symlink at the chosen release. The switch restarts the
service, including after an interrupted run:
- task_block:
id: app # a node task block ID you choose
changes:
- unpack_archive:
url: https://releases.example.com/app-1.4.2-linux-amd64.tar.gz
# Replace with the SHA-256 of the release archive you have verified.
sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
path: /srv/app/releases/1.4.2
owner: app
group: app
unpack_without_wrapping_folder: true
- symlink:
path: /srv/app/current
target: releases/1.4.2
activate:
- systemd_service:
name: app
state: running
- unpack_archive:
also_delete_everything_inside: true
path: /srv/app/releases/1.4.1
state: absent
The controller process fetches the URL once per run and checks it against the
SHA-256, as for download. An archive that an earlier run of the project
saved is reused after its SHA-256 is checked again, so an unchanged run does
not fetch it again. On the node, MMX extracts into a staging
directory beside path, then renames it into place.
unpack_without_wrapping_folder: true leaves out the one top-level folder
that many release archives have, such as app-1.4.2/, so its contents land
directly in path. The symlink task then points /srv/app/current at the
new release, and the switch restarts the service app.
Old releases stay until a task deletes them. The example's last
unpack_archive task, with state: absent, deletes one release it
extracted; to keep only the releases you name, use
delete_everything_inside_except
on the releases directory.
How it works
The archive
unpack_archive takes exactly one of source, a local file resolved like
file.source, or url with
sha256, fetched and verified like download under the same
checksum rule.
Dryrun fetches and verifies a URL on the controller machine like download.
A node keeps an archive from a URL as download keeps its file, so a later
run or dryrun does not send it again; an archive from source is sent each
time. Resume reuses the saved bytes.
Extraction on the node
When path is missing, the node extracts into a private staging directory
beside it (.mmx-staging-<name>), then renames the staging directory into
place. The parent of path must exist. Archives are untrusted input, so
every entry is checked before it is created. Extraction fails, in both dryrun
and run, discarding the staging directory and leaving nothing at path, on:
- an entry with an absolute path or a
..component; - a symlink whose target is absolute or leaves the directory:
..may appear only as leading components, no more of them than the link's depth; - an entry at or below a symlink, or a name that appears twice (a directory listed again is fine);
- a hard link that does not name an earlier regular file of the archive;
- a device, FIFO, or other special entry, or a top-level
.mmx-archive.
With unpack_without_wrapping_folder: true, the archive must have exactly
one top-level folder. Any file or other entry outside the archive's single
top-level folder fails the node task before extraction. Leave the setting
out to preserve the archive's whole layout.
Archive entries use the declared owner and group (default root), never
the archive's numeric IDs; owner and group take an account name or a
number, as
the rule for owner and group
says. Entries keep the archive's permission bits except setuid, setgid, and
sticky bits. Zip entries without Unix modes get 0644 or 0755, as do
directories the archive does not list. The directory itself gets owner,
group, and 0755. An interrupted extraction leaves only its staging
directory, which the next attempt replaces.
A small compressed archive can hold huge files. Before it writes a file, MMX
adds up the sizes the archive's files declare, and the node task fails, in
dryrun too, when they would leave less than 5 % of the node's filesystem free,
as the Avail column of df counts it. The staging directory is then deleted,
and nothing is left at path.
Dryrun reads the archive on the node and reports the entry count and any
rejected entry, creating nothing. The result value's entries is the number
of extracted entries.
The record of what was extracted
A root-owned .mmx-archive file in the extracted directory records the
archive's SHA-256, unpack_without_wrapping_folder, owner, and group. If
the record matches the requested archive's SHA-256, wrapping-folder setting,
owner, and group, MMX reports unchanged without rescanning the extracted
directory's contents. Any other directory or file at path, including one
extracted from a different archive or with different settings, fails the
node task: give each version its own path.
state: absent requires also_delete_everything_inside: true and accepts
only those two settings and path. It removes a directory holding a readable
.mmx-archive record, with its whole tree, without following links: it
renames the directory to its staging name, then deletes that. A directory
without a readable record fails. When the path is missing, a staging
directory that an earlier removal or extraction left behind is deleted, and
the removal is changed; with neither, it is unchanged.
In a node task block
unpack_archive adds nothing to service hashes; the files of the tree are
not hashed. With release directories, the tracked symlink records the
release switch, so the switch feeds the
service configuration hash
and an interrupted deployment still restarts.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.
The base suite covers this module (release_directories.py: it unpacks archives into release directories and switches them by a tracked symlink) and runs on every tested distribution.
Why it works this way
-
Each release goes to its own path, and a tracked
symlinkswitches to it. The switch feeds the service hash, so an interrupted deployment still restarts. -
Every entry is checked before it is created. Archives are untrusted input.
-
The declared sizes must leave 5 % of the node's filesystem free. A small compressed archive cannot fill the disk.
-
Unwrapping never silently drops archive entries. A release can depend on any entry; an unexpected layout fails instead of producing an incomplete deployment.
-
Removal explicitly names the whole tree.
also_delete_everything_insidemakes deletion visible when reviewing a task, under protective choices.
This page is docs/reference/modules/unpack_archive.md in the MMX repository.