download
download installs a file from an HTTPS web address on nodes, such as a
public release artifact. The controller machine fetches the file and checks
it against the SHA-256 the task gives, then sends it to the nodes, where MMX
installs it like a file with source. Use
unpack_archive to unpack a pinned archive, and
git or a shell task for a source that needs credentials.
Inputs
url(string; required): HTTPS URL without credentials or fragment; may read vars, role inputs, loop items, and .node.name, as may sha256sha256(string; optional): the file's SHA-256 in hex; exactly one of sha256 or dangerously_skip_checksumdangerously_skip_checksum(boolean; defaultfalse): true in place of sha256: the file is installed as it arrives, with no check that it is the file you expectdecompress(gzip,bzip2,xz, orzstd; optional): for a tool published as one compressed file: sha256 is the digest of the file as published; the controller machine checks it, decompresses, and installs the decompressed filepath(string; required): absolute; the parent directory must existowner(account name or integer; optional): an account name, or a numeric ID written without quotesgroup(group name or integer; optional): a group name, or a numeric ID written without quotespermissions_mode(string; required): quoted octal, as chmod writes it, such as "0755"; may read a referencesecret_readable_by_group(boolean; defaultfalse): allow the file's group to read content that holds a secretdangerously_let_every_account_read_secret(boolean; defaultfalse): allow every account to read content that holds a secretif_file_exists(replace_existing_contentorkeep_existing_content; defaultreplace_existing_content): as for filecheck_new_file(mapping; optional): as for file
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.
statuschange
What a dryrun reports
Supported; fetches and verifies the file, decompresses it when told, then previews it like file.
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
Install a release artifact
Supply the URL and the expected SHA-256 digest:
- download:
url: https://downloads.example.com/app-1.2.3-linux-arm64
# Replace with the SHA-256 of the release artifact you have verified.
sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
path: /usr/local/bin/app
permissions_mode: "0755"
The controller process fetches each URL/digest once per run and verifies the bytes. A file 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. A node keeps the bytes of each file from a web address that a run sent it, by their SHA-256, until no run has used them for 30 days, so a later run or dryrun sends a node only the files it does not have yet. Matching installed bytes stay unchanged. The download example installs an executable and restarts its service when the bytes change.
A version from the project's variables
The URL and the SHA-256 may read values the controller machine knows before it
connects, such as a version number in the project's vars, under the
same rule as a source path:
# roles/app/main.yml
# app_version and app_sha256 are variables you define in the project's or the
# inventory's vars, such as app_version: 1.2.3 and its 64-digit SHA-256.
node_tasks:
- download:
url: "https://downloads.example.com/app-{{ .vars.app_version }}-linux-amd64"
sha256: "{{ .vars.app_sha256 }}"
path: /usr/local/bin/app
permissions_mode: "0755"
The controller machine fills in url and sha256 for each node before
connecting, then fetches and checks the file as in the first example.
One file for each processor architecture
A release that publishes one file for each processor architecture needs one
task for each file, each with a when on .node.arch. Both tasks may
install the same path:
- task_block:
id: app_binary
changes:
- when: {equals: ["{{ .node.arch }}", amd64]}
download:
url: https://downloads.example.com/app-1.2.3-linux-amd64
# Replace with the SHA-256 of the amd64 file.
sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
path: /usr/local/bin/app
permissions_mode: "0755"
- when: {equals: ["{{ .node.arch }}", arm64]}
download:
url: https://downloads.example.com/app-1.2.3-linux-arm64
# Replace with the SHA-256 of the arm64 file.
sha256: "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
path: /usr/local/bin/app
permissions_mode: "0755"
activate:
- systemd_service:
name: app
state: running
The controller machine fetches and checks both files before the run starts.
On each node, only the task whose when matches the node's architecture
installs /usr/local/bin/app, and the node restarts app when the bytes of
that file change. Two tasks in one node task block that would both run on a
node and write the same path are an error, as
tracked inputs
explains.
A file without a published checksum
Every field that fetches from a web address needs a checksum beside it. Where a vendor publishes no checksum and the file changes under the same address, say so on the page instead:
- download:
url: https://downloads.example.com/app-latest-linux-amd64
dangerously_skip_checksum: true
path: /usr/local/bin/app
permissions_mode: "0755"
MMX then installs the file as it arrives. Nobody notices when the server at
that address starts to serve something else, which is why the setting has
"dangerously" in its name: a reviewer sees it. A task gives exactly one of the
checksum or dangerously_skip_checksum: true.
A file from a web address is checked against its SHA-256
defines the checksum requirement for every module that fetches from a web
address.
A tool published as one compressed file
Some tools are published as one compressed file, such as
restic_0.17.3_linux_amd64.bz2. Name the compression with decompress:
gzip, bzip2, xz, or zstd:
- download:
url: https://github.com/restic/restic/releases/download/v0.17.3/restic_0.17.3_linux_amd64.bz2
# The SHA-256 of the .bz2 file as the project publishes it.
sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
decompress: bzip2
path: /usr/local/bin/restic
permissions_mode: "0755"
sha256 is the digest the project publishes next to the compressed file.
The controller machine checks the downloaded compressed file against the
expected SHA-256 digest, then decompresses the verified file.
The controller machine sends the decompressed file to the nodes for
installation. The next run is unchanged as long as the installed bytes
match. The nodes and the controller machine need no decompression tool
because MMX decompresses with MMX's own code.
How it works
url is an HTTPS URL without credentials or a fragment. Normal TLS checks
apply, redirects stay HTTPS, and transfers stop after 30 seconds without
bytes. Invalid, incomplete, or mismatched downloads fail before any node job
starts.
validate and explain do not fetch downloads. dryrun fetches and verifies
inputs on the controller machine, then previews changes on nodes, and changes
no managed files. Resume uses the saved bytes and needs no source access. A
new dryrun or run reuses a file with a sha256 that an earlier dryrun
or run saved and that the history on the controller machine still holds,
after it checks the SHA-256 again. It fetches the source only when no saved
run holds the file. A
download with dangerously_skip_checksum: true or decompress is fetched
on every new dryrun or run.
Downloads use the same streamed assets and file installer as local sources.
They accept the file fields path, owner, group, permissions_mode,
if_file_exists, secret_readable_by_group,
dangerously_let_every_account_read_secret, and check_new_file, and otherwise behave exactly like
file.source, including unchanged detection, validation, previews, and
service configuration hashes. Results still name the node task download.
Ordinary references are allowed in the path, owner, group, permissions mode, and validator
inputs. if_file_exists works as for
file, and the
check of a new file, shared with file, line, and edit_file, is
described in
Check a new file before replacing the live one
and its design.
owner and group take an account name or a number, as
the rule for owner and group
says.
With decompress, the controller machine keeps only the decompressed file
with the run, so resume needs neither the web address nor a second
decompression. A new run fetches such a file again, because only the
compressed file's SHA-256 is known before the fetch. A small compressed file can hold a huge one, so MMX refuses a
decompressed file that would leave less than 5 % of the controller machine's
filesystem free, as the Avail column of df counts it, and the run fails
before any node job starts.
This form does not support authentication, a URL that depends on a node's
facts or on a task result. The same pinned fetch
supplies unpack_archive, package files, and repository
keys.
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 (dns_tls_and_account_lookups.py) and runs on every tested distribution.
Why it works this way
- Every download requires
permissions_mode. MMX cannot guess which accounts should read or run the downloaded file. See required settings. - Known secret content follows the file permission rule. The file page owns that rule and its acknowledgements, under the shared protective choices.
This page is docs/reference/modules/download.md in the MMX repository.