# cron – Manage cron.d and crontab entries

- Synopsis

- Requirements

- Parameters

- Examples

- Status

## 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
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 string | Default: "*" | Day of the month the job should run ( 1-31, *, */2, etc ) aliases: dom

disabled
boolean

Choices:
- no ←
- yes

If the job should be disabled (commented out) in the crontab.
Only has effect if `state=present`.

env
boolean

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 string | Default: "*" | Hour when the job should run ( 0-23, *, */2, etc )
insertafter string |  | Used with `state=present` and `env`. If specified, the environment variable will be inserted after the declaration of specified environment variable.
insertbefore string |  | Used with `state=present` and `env`. If specified, the environment variable will be inserted before the declaration of specified environment variable.
job 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`. aliases: value
minute string | Default: "*" | Minute when the job should run ( 0-59, *, */2, etc )
month string | Default: "*" | Month of the year the job should run ( 1-12, *, */2, etc )
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

Choices:
- no ←
- yes

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

special_time
string

Choices:
- annually
- daily
- hourly
- monthly
- reboot
- weekly
- yearly

Special time specification nickname.

state
string

Choices:
- absent
- present ←

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

user string |  | The specific user whose crontab should be modified. When unset, this parameter defaults to using `root`.
weekday string | 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
        job: /opt/bin

    - name: Creates an entry like "APP_HOME=/srv/app" and insert it after PATH declaration
      cron:
        name: APP_HOME
        env: yes
        job: /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

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Dane Summers (@dsummersl)

- Mike Grozak (@rhaido)

- Patrick Callahan (@dirtyharrycallahan)

- Evan Kaufman (@EvanK)

- Luca Berruti (@lberruti)

Hint

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