cron_job
A scheduled job is a command that a node runs by itself at set times, such
as a nightly cleanup. cron_job manages one cron entry in its own file,
/etc/cron.d/<name>, on the node. cron_job is for teams that keep
their schedules in cron.
For new jobs, use systemd_scheduled_job
instead. With it, a job has a multi-line script with the same rules as
shell, secrets stay out of world-readable files, two runs never overlap, a
missed run can be made up after downtime, output is in the journal instead
of mail, and systemctl list-timers shows the next run.
Set up
cron must be installed and running on the node. The package
cron provides cron on Debian and Ubuntu and cronie on the Red Hat family. The cron_job module installs no package and
starts no service, so put the package node task and the service node task
first:
- when: {equals: ["{{ .node.package_manager }}", apt]}
apt_package: {packages: [{name: cron, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", apt]}
systemd_service: {name: cron, start_at_boot: true, state: running}
- when: {equals: ["{{ .node.package_manager }}", dnf]}
dnf_package: {packages: [{name: cronie, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", dnf]}
systemd_service: {name: crond, start_at_boot: true, state: running}
The service is cron on Debian and Ubuntu, and crond on the Red Hat
family.
Inputs
name(string; required): the file's name: letters, digits, - and _ only, because cron ignores other file namescron_schedule(string; required): five cron fields (minute, hour, day of month, month, day of week), such as"15 3 * * *", or one of cron's @ words: @reboot, @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourlyrun_as_user_account(string; required): the account cron runs the command as; cron needs it on every entry in /etc/cron.dcommand(string; required): one line, run by cron with /bin/sh; write % as it should reach the command, MMX escapes it for cronenv(mapping; optional): variable lines written above the entry, such as MAILTO or PATH; a secret is rejected, because every account can read the filestate(presentorabsent; defaultpresent): absent accepts only name and state; it removes a file that has MMX's marker line and refuses one that lacks it
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; shows the file's text difference; a node without cron is not checked.
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
Keep a job in cron
- cron_job:
name: rotate-upload-cache
cron_schedule: "15 3 * * *"
run_as_user_account: www-data
command: /usr/local/bin/rotate-upload-cache --keep 14 --suffix $(date +%Y-%m-%d)
env:
MAILTO: ops@example.com
MMX writes the file /etc/cron.d/rotate-upload-cache on the node, owned by
root with mode 0644:
# Managed by MMX: cron_job. Written by the node task for rotate-upload-cache; MMX replaces a change made here on its next run.
MAILTO=ops@example.com
15 3 * * * www-data /usr/local/bin/rotate-upload-cache --keep 14 --suffix $(date +\%Y-\%m-\%d)
At 03:15 every night, cron runs the command with /bin/sh as the account
www-data. cron reads a % in a command as the end of the command, so MMX
writes each % as \%; write the command as it should reach the shell.
How it works
nameis the file's name in/etc/cron.d/: letters, digits,-, and_only, because cron ignores other file names.cron_scheduleis five cron fields, or one of cron's@words:@reboot,@yearly,@annually,@monthly,@weekly,@daily,@midnight, or@hourly.run_as_user_accountis required, because cron needs the account on every entry in/etc/cron.d/.commandis one line, and runs as written: MMX fills in no reference there, and validation refuses one to a value MMX knows, such ascd {{ .inputs.sites_dir }}, which cron would run with its braces. Put the value inenv, such asenv: {SITES_DIR: "{{ .inputs.sites_dir }}"}, and writecd "$SITES_DIR"in the command.envholds variable lines written above the entry, such asMAILTOorPATH.- The file is written like a
filenode task: MMX compares it with what the node task asks for, writes it only when it differs, and shows the text difference in a dryrun. In a node task block'schanges, the file is a tracked input, like a file from afilenode task. state: absentremoves the file when it starts with MMX's marker line, and refuses a file without it, because then MMX did not write it.- A present job also refuses, in a dryrun and in a run, an existing file of
that name without the marker line, such as a package's own
/etc/cron.d/certbot. Choose anothername.
Errors and what they mean
| The reason holds | What the error means, and what to do |
|---|---|
cron is not installed; install the package cron (Debian and Ubuntu) or cronie (Red Hat family) first |
Install cron in an earlier node task; see Set up. A dryrun reports the node task not checked, because an earlier node task may install cron. A missing run_as_user_account account is treated the same way. |
a secret cannot go into a cron file, which every account on the node can read; use systemd_scheduled_job, which keeps a secret in a file only root can read |
Every account on the node can read the file. Use systemd_scheduled_job for a job that needs a secret. |
cron_job.command must not have a backslash directly before %: cron cannot pass that pair to a command. Write the % without the backslash; MMX escapes every % for cron |
cron has no way to pass that pair to a command. |
refusing to write /etc/cron.d/...: the file exists and lacks the MMX marker line ... |
A file of that name that MMX did not write exists, and the job would overwrite it. Choose another name. |
refusing to remove /etc/cron.d/...: the file lacks the MMX marker line ... |
Another tool or a person wrote the file. Remove it by hand, or with a file node task (state: absent). |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/scheduled_jobs.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, in containers on the first four and in virtual machines on the last two. It checks
the cron file and cron running the
entry; on a node without cron, it checks the dryrun and the failure that
names the package. The validation record has the
latest results.
Why it works this way
cron_jobis a core module besidesystemd_scheduled_job. Each is named for its tool, and many teams have cron entries they do not want to convert yet.- No secrets in
env. The file in/etc/cron.d/is readable by every account.
This page is docs/reference/modules/cron_job.md in the MMX repository.