ansible.builtin.cron module – 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 Fully Qualified Collection Name (FQCN) ansible.builtin.cron for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
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 (any ‘vixie cron’ conformant variant, like cronie)
Parameters
Parameter |
Comments |
|---|---|
If set, create a backup of the crontab before it is modified. The location of the backup is returned in the Choices:
|
|
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 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 Either this parameter or |
|
Day of the month the job should run ( Default: |
|
If the job should be disabled (commented out) in the crontab. Only has effect if Choices:
|
|
Hour when the job should run ( Default: |
|
Used with If specified, the environment variable will be inserted after the declaration of specified environment variable. |
|
Used with If specified, the environment variable will be inserted before the declaration of specified environment variable. |
|
The command to execute or, if env is set, the value of environment variable. The command should not contain line breaks. Required if |
|
Minute when the job should run ( Default: |
|
Month of the year the job should run ( Default: |
|
Description of a crontab entry or, if env is set, the name of environment variable. This parameter is always required as of ansible-core 2.12. |
|
Special time specification nickname. Choices:
|
|
Whether to ensure the job or environment variable is present or absent. Choices:
|
|
The specific user whose crontab should be modified. When unset, this parameter defaults to the current user. |
|
Day of the week that the job should run ( Default: |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: full |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
Support: full |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platform: posix |
Target OS/families that can be operated against |
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