ansible.builtin.cron – Manage cron.d and crontab entries

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name cron even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in version 0.9: of ansible.builtin

Synopsis

  • Use this module to manage crontab and environment variables entries. This module allows you to create environment variables and named crontab entries, update, or delete them.

  • When crontab jobs are managed: the module includes one line with the description of the crontab entry "#Ansible: <name>" corresponding to the “name” passed to the module, which is used by future ansible/module calls to find/check the state. The “name” parameter should be unique, and changing the “name” value will result in a new cron task being created (or a different one being removed).

  • When environment variables are managed, no comment line is added, but, when the module needs to find/check the state, it uses the “name” parameter to find the environment variable definition line.

  • When using symbols such as %, they must be properly escaped.

Requirements

The below requirements are needed on the host that executes this module.

  • cron (or cronie on CentOS)

Parameters

Parameter

Comments

backup

boolean

If set, create a backup of the crontab before it is modified. The location of the backup is returned in the backup_file variable by this module.

Choices:

  • no ← (default)

  • yes

cron_file

string

If specified, uses this file instead of an individual user’s crontab.

If this is a relative path, it is interpreted with respect to /etc/cron.d.

If it is absolute, it will typically be /etc/crontab.

Many linux distros expect (and some require) the filename portion to consist solely of upper- and lower-case letters, digits, underscores, and hyphens.

To use the cron_file parameter you must specify the user as well.

day

aliases: dom

string

Day of the month the job should run (1-31, *, */2, and so on).

Default: “*”

disabled

boolean

added in 2.0 of ansible.builtin

If the job should be disabled (commented out) in the crontab.

Only has effect if state=present.

Choices:

  • no ← (default)

  • yes

env

boolean

added in 2.1 of ansible.builtin

If set, manages a crontab’s environment variable.

New variables are added on top of crontab.

name and value parameters are the name and the value of environment variable.

Choices:

  • no ← (default)

  • yes

hour

string

Hour when the job should run (0-23, *, */2, and so on).

Default: “*”

insertafter

string

added in 2.1 of ansible.builtin

Used with state=present and env.

If specified, the environment variable will be inserted after the declaration of specified environment variable.

insertbefore

string

added in 2.1 of ansible.builtin

Used with state=present and env.

If specified, the environment variable will be inserted before the declaration of specified environment variable.

job

aliases: value

string

The command to execute or, if env is set, the value of environment variable.

The command should not contain line breaks.

Required if state=present.

minute

string

Minute when the job should run (0-59, *, */2, and so on).

Default: “*”

month

string

Month of the year the job should run (1-12, *, */2, and so on).

Default: “*”

name

string

Description of a crontab entry or, if env is set, the name of environment variable.

Required if state=absent.

Note that if name is not set and state=present, then a new crontab entry will always be created, regardless of existing ones.

This parameter will always be required in future releases.

reboot

boolean

added in 1.0 of ansible.builtin

If the job should be run at reboot. This option is deprecated. Users should use special_time.

Choices:

  • no ← (default)

  • yes

special_time

string

added in 1.3 of ansible.builtin

Special time specification nickname.

Choices:

  • annually

  • daily

  • hourly

  • monthly

  • reboot

  • weekly

  • yearly

state

string

Whether to ensure the job or environment variable is present or absent.

Choices:

  • absent

  • present ← (default)

user

string

The specific user whose crontab should be modified.

When unset, this parameter defaults to the current user.

weekday

aliases: dow

string

Day of the week that the job should run (0-6 for Sunday-Saturday, *, and so on).

Default: “*”

Notes

Note

  • Supports check_mode.

Examples

- name: Ensure a job that runs at 2 and 5 exists. Creates an entry like "0 5,2 * * ls -alh > /dev/null"
  ansible.builtin.cron:
    name: "check dirs"
    minute: "0"
    hour: "5,2"
    job: "ls -alh > /dev/null"

- name: 'Ensure an old job is no longer present. Removes any job that is prefixed by "#Ansible: an old job" from the crontab'
  ansible.builtin.cron:
    name: "an old job"
    state: absent

- name: Creates an entry like "@reboot /some/job.sh"
  ansible.builtin.cron:
    name: "a job for reboot"
    special_time: reboot
    job: "/some/job.sh"

- name: Creates an entry like "PATH=/opt/bin" on top of crontab
  ansible.builtin.cron:
    name: PATH
    env: yes
    job: /opt/bin

- name: Creates an entry like "APP_HOME=/srv/app" and insert it after PATH declaration
  ansible.builtin.cron:
    name: APP_HOME
    env: yes
    job: /srv/app
    insertafter: PATH

- name: Creates a cron file under /etc/cron.d
  ansible.builtin.cron:
    name: yum autoupdate
    weekday: "2"
    minute: "0"
    hour: "12"
    user: root
    job: "YUMINTERACTIVE=0 /usr/sbin/yum-autoupdate"
    cron_file: ansible_yum-autoupdate

- name: Removes a cron file from under /etc/cron.d
  ansible.builtin.cron:
    name: "yum autoupdate"
    cron_file: ansible_yum-autoupdate
    state: absent

- name: Removes "APP_HOME" environment variable from crontab
  ansible.builtin.cron:
    name: APP_HOME
    env: yes
    state: absent

Authors

  • Dane Summers (@dsummersl)

  • Mike Grozak (@rhaido)

  • Patrick Callahan (@dirtyharrycallahan)

  • Evan Kaufman (@EvanK)

  • Luca Berruti (@lberruti)