Skip to content

cron

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin
Added in version 0.9.

You need further requirements to be able to use this module, see the Requirements section for details.

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 C("#Ansible: ") corresponding to the O(name) passed to the module, which is used by future ansible/module calls to find/check the state. The O(name) parameter should be unique, and changing the O(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 O(name) parameter to find the environment variable definition line.
  • When using symbols such as C(%), they must be properly escaped.

Requirements

The following Python packages are needed on the host that executes this module:

Parameters

Parameter Defaults / Choices Comments
backup
bool		 If set, create a backup of the crontab before it is modified. The location of the backup is returned in the RV(ignore:backup_file) variable by this module.
cron_file
path		 If specified, uses this file instead of an individual user's crontab. The assumption is that this file is exclusively managed by the module, do not use if the file contains multiple entries, NEVER use for /etc/crontab.
If this is a relative path, it is interpreted with respect to C(/etc/cron.d).
Many Linux distros expect (and some require) the filename portion to consist solely of upper- and lower-case letters, digits, underscores, and hyphens.
Using this parameter requires you to specify the O(user) as well, unless O(state=absent).
Either this parameter or O(name) is required.
day
str		 Default: *
 Day of the month the job should run (V(1-31), V(*), V(*/2), and so on).
disabled
bool		 If the job should be disabled (commented out) in the crontab.
Only has effect if O(state=present).
Version Added: 2.0
env
bool		 If set, manages a crontab's environment variable.
New variables are added on top of crontab.
O(name) and O(value) parameters are the name and the value of environment variable.
Version Added: 2.1
hour
str		 Default: *
 Hour when the job should run (V(0-23), V(*), V(*/2), and so on).
insertafter
str		 Used with O(state=present) and O(env).
If specified, the environment variable will be inserted after the declaration of specified environment variable.
Version Added: 2.1
insertbefore
str		 Used with O(state=present) and O(env).
If specified, the environment variable will be inserted before the declaration of specified environment variable.
Version Added: 2.1
job
str		 The command to execute or, if O(env) is set, the value of environment variable.
The command should not contain line breaks.
Required if O(state=present).
minute
str		 Default: *
 Minute when the job should run (V(0-59), V(*), V(*/2), and so on).
month
str		 Default: *
 Month of the year the job should run (V(1-12), V(*), V(*/2), and so on).
name
str
required		 Description of a crontab entry or, if O(env) is set, the name of environment variable.
This parameter is always required as of ansible-core 2.12.
special_time
str		 Choices: annually, daily, hourly, monthly, reboot, weekly, yearly Special time specification nickname.
Version Added: 1.3
state
str		 Default: present
Choices: absent, present		 Whether to ensure the job or environment variable is present or absent.
user
str		 The specific user whose crontab should be modified.
When unset, this parameter defaults to the current user.
weekday
str		 Default: *
 Day of the week that the job should run (V(0-6) for Sunday-Saturday, V(*), and so on).

Notes

Note

  • If you are experiencing permissions issues with cron and MacOS, you should see the official MacOS documentation for further information.

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)