cron – Manage cron.d and crontab entries

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

Parameters

Parameter Choices/Defaults Comments
backup
boolean
    Choices:
  • no ←
  • yes
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.
cron_file
-
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
-
Default:
"*"
Day of the month the job should run ( 1-31, *, */2, etc )

aliases: dom
disabled
boolean
added in 2.0
    Choices:
  • no ←
  • yes
If the job should be disabled (commented out) in the crontab.
Only has effect if state=present.
env
boolean
added in 2.1
    Choices:
  • no ←
  • yes
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.
hour
-
Default:
"*"
Hour when the job should run ( 0-23, *, */2, etc )
insertafter
-
added in 2.1
Used with state=present and env. If specified, the environment variable will be inserted after the declaration of specified environment variable.
insertbefore
-
added in 2.1
Used with state=present and env. If specified, the environment variable will be inserted before the declaration of specified environment variable.
job
-
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.

aliases: value
minute
-
Default:
"*"
Minute when the job should run ( 0-59, *, */2, etc )
month
-
Default:
"*"
Month of the year the job should run ( 1-12, *, */2, etc )
name
-
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.
reboot
boolean
    Choices:
  • no ←
  • yes
If the job should be run at reboot. This option is deprecated. Users should use special_time.
special_time
-
added in 1.3
    Choices:
  • reboot
  • yearly
  • annually
  • monthly
  • weekly
  • daily
  • hourly
Special time specification nickname.
state
-
    Choices:
  • absent
  • present ←
Whether to ensure the job or environment variable is present or absent.
user
-
Default:
"root"
The specific user whose crontab should be modified.
weekday
-
Default:
"*"
Day of the week that the job should run ( 0-6 for Sunday-Saturday, *, etc )

aliases: dow

Examples

- name: Ensure a job that runs at 2 and 5 exists. Creates an entry like "0 5,2 * * ls -alh > /dev/null"
  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'
  cron:
    name: "an old job"
    state: absent

- name: Creates an entry like "@reboot /some/job.sh"
  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
  cron:
    name: PATH
    env: yes
    value: /opt/bin

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

- name: Creates a cron file under /etc/cron.d
  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
  cron:
    name: "yum autoupdate"
    cron_file: ansible_yum-autoupdate
    state: absent

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

Status

Authors

  • Dane Summers (@dsummersl)
  • Mike Grozak
  • Patrick Callahan
  • Evan Kaufman (@EvanK)
  • Luca Berruti (@lberruti)

Hint

If you notice any issues in this documentation you can edit this document to improve it.