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 names
  • cron_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, @hourly
  • run_as_user_account (string; required): the account cron runs the command as; cron needs it on every entry in /etc/cron.d
  • command (string; required): one line, run by cron with /bin/sh; write % as it should reach the command, MMX escapes it for cron
  • env (mapping; optional): variable lines written above the entry, such as MAILTO or PATH; a secret is rejected, because every account can read the file
  • state (present or absent; default present): 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.

  • status
  • change

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

  • name is the file's name in /etc/cron.d/: letters, digits, -, and _ only, because cron ignores other file names.
  • cron_schedule is five cron fields, or one of cron's @ words: @reboot, @yearly, @annually, @monthly, @weekly, @daily, @midnight, or @hourly.
  • run_as_user_account is required, because cron needs the account on every entry in /etc/cron.d/.
  • command is one line, and runs as written: MMX fills in no reference there, and validation refuses one to a value MMX knows, such as cd {{ .inputs.sites_dir }}, which cron would run with its braces. Put the value in env, such as env: {SITES_DIR: "{{ .inputs.sites_dir }}"}, and write cd "$SITES_DIR" in the command.
  • env holds variable lines written above the entry, such as MAILTO or PATH.
  • The file is written like a file node 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's changes, the file is a tracked input, like a file from a file node task.
  • state: absent removes 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 another name.

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_job is a core module beside systemd_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.