Configure and manage cron jobs with focus on tidiness

Table of Contents

1. Description
2. Setup - The basics of getting started with cron
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

This module is an interface for cron jobs with the main idea to be tidy. That means that any jobs that are not managed should not exist. Once you switch all cron jobs to this module, simply removing the definition is sufficient without worrying about setting ensure => disable and waiting for changes to propagate.

Setup

Beginning with cron

To start out with cron:

include cron

This will start purging all unmanaged cron resources and also make sure the 'cron' package is installed and the service is running.

WARNING: All existing unmanaged cron jobs will be purged!

Usage

Also manage /etc/cron.d directory

class { 'cron':
  purge_crond => true,
}

Same result through Hiera:

cron::purge_crond: true

Wipe it all out

class { 'cron':
  ensure => absent,
}

Same result through Hiera:

cron::ensure: absent

cron::job example

cron::job { 'backup':
  user     => 'backup', # default: 'root'
  minute   => '3-59/5',
  hour     => '9-17',
  monthday => '*/2',
  month    => [ 4, 8, 12 ],
  weekday  => '0-4',
}

cron::whitelist example

cron::whitelist { 'pkg_backup': }

This will make /etc/cron.d/pkg_backup immune, and keep the file's contents untouched.

Reference

Type Aliases

• Cron::Command - Used for cron::job::command parameter. Does not allow newline characters (which breaks crontab).
• Cron::User - Match username to fail early if invalid username is provided.
• Cron::Minute - Stricter cron::job::minute.
• Cron::Hour - Stricter cron::job::hour.
• Cron::Monthday - Stricter cron::job::monthday.
• Cron::Month - Stricter cron::job::month.
• Cron::Weekday - Stricter cron::job::weekday.

Full reference

Check out REFERENCE for up-to-date details.

Limitations

• Made for and tested only on the following Ubuntu distributions:
  • 18.04
  • 20.04
  • 22.04
• Custom Cron::* time types are a lot stricter than builtin cron ones. Careful - this may break existing cron jobs you are converting.
• All cron jobs managed by built-in cron type are fair play. They won't be purged as long as they're in the catalog. But using this module's cron::job type does have its advantages.

Development

I'll be happy to know you're using this for one reason or the other. And if you want to contribute - even better. Feel free to submit an issue / fire up a PR / whatever.

Reference

Table of Contents

Classes

Public Classes

• cron: Main entry point into all cron-related resources on the host. It purges by default. You've been warned!

Private Classes

• cron::config: Various cron configuration files
• cron::install: This class handles cron packages.
• cron::purge: This is where all the purging magic happens. Purge unmanaged cron jobs and also, optionally, purge /etc/cron.d directory.
• cron::remove: This class handles removal of all cron-related resources.
• cron::service: This class handles cron service.

Defined types

• cron::job: Cron job defined type with a bit of magic dust sprinkled all over.
• cron::job::daily: Manage daily cron jobs.
• cron::job::hourly: Manage hourly cron jobs.
• cron::job::monthly: Manage weekly cron jobs.
• cron::job::weekly: Manage weekly cron jobs.
• cron::whitelist: Use this to whitelist any system cron jobs you don't want this module to touch. This will make sure /etc/cron.d/${title} won't get deleted

Data types

• Cron::Command: Used for cron::job::command parameter. Does not allow newline characters (which breaks crontab).
• Cron::Ensure: A simple ensure enum
• Cron::Hour: Stricter cron::job::hour.
• Cron::Minute: Stricter cron::job::minute.
• Cron::Month: Stricter cron::job::month.
• Cron::Monthday: Sricter cron::job::monthday.
• Cron::User: Cron user.
• Cron::Weekday: Stricter cron::job::weekday.

Classes

cron

Main entry point into all cron-related resources on the host. It purges by default. You've been warned!

• See also
  • manpages
    • crontab(1), crontab(5), cron(8)

Examples

Declaring the cron class

include cron

Also purge unmanaged files in /etc/cron.d directory

class { 'cron':
  purge_crond => true,
}

Removing all cron-related resources from the system

class { 'cron':
  ensure => absent,
}

Deny crontab(1) usage to all users except 'luke' (and 'root' - he can always do that).

class { 'cron':
  allowed_users => [ 'luke' ],
}

Parameters

The following parameters are available in the cron class:

• ensure
• package_version
• allow_all_users
• allowed_users
• denied_users
• service_manage
• service_ensure
• service_enable
• purge_cron
• purge_crond
• purge_noop

ensure

Data type: Enum[present, absent]

Whether to enable or disable cron on the system.

Default value: present

package_version

Data type: Pattern[/\A[^\n]+\z/]

Custom cron package version.

Default value: installed

allow_all_users

Data type: Boolean

Allow all users to manage crontab.

Default value: false

allowed_users

Data type: Array[Cron::User]

List of users allowed to use crontab(1). By default, only root can.

Default value: []

denied_users

Data type: Array[Cron::User]

List of users specifically denied to use crontab(1). Note: When this is not empty, all users except ones specified here will be able to use crontab.

Default value: []

service_manage

Data type: Boolean

Whether to manage cron service at all.

Default value: true

service_ensure

Data type: Enum[running, stopped]

Cron service's ensure parameter.

Default value: running

service_enable

Data type: Boolean

Cron service's enable parameter.

Default value: true

purge_cron

Data type: Boolean

Whether to purge crontab entries.

Default value: true

purge_crond

Data type: Boolean

Also purge unmanaged files in /etc/cron.d directory.

Default value: false

purge_noop

Data type: Boolean

Run purging in noop mode.

Default value: false

Defined types

cron::job

Cron job defined type with a bit of magic dust sprinkled all over.

Examples

Consider cron job declaration using built-in type

cron { 'my_job':
  minute => 0,
  hour   => 3,
}

This differs in that it manages all time values by default

cron::job { 'my_job':
  minute => 0,
  hour   => 3,
}

Simple cron job that runs every minute

cron::job { 'ping-host':
  command => '/usr/local/bin/my-host-pinger',
}

More advanced declaration

cron::job { 'my-backup':
  command => '/usr/local/bin/my-backup',
  hour    => [ 0, 12 ],
  minute  => '*/10';
}

Parameters

The following parameters are available in the cron::job defined type:

• command
• ensure
• user
• minute
• hour
• monthday
• month
• weekday

command

Data type: Cron::Command

Command path to be executed

ensure

Data type: Cron::Ensure

Cron job state

Default value: present

user

Data type: Cron::User

The user who owns the cron job

Default value: 'root'

minute

Data type: Cron::Minute

Cron minute

Default value: '*'

hour

Data type: Cron::Hour

Cron hour

Default value: '*'

monthday

Data type: Cron::Monthday

Cron monthday

Default value: '*'

month

Data type: Cron::Month

Cron month

Default value: '*'

weekday

Data type: Cron::Weekday

Cron weekday

Default value: '*'

cron::job::daily

Manage daily cron jobs.

Parameters

The following parameters are available in the cron::job::daily defined type:

• command
• ensure
• minute
• hour
• user

command

Data type: Cron::Command

Command path to be executed

ensure

Data type: Cron::Ensure

Cron job state

Default value: present

minute

Data type: Cron::Minute

Cron minute

Default value: 0

hour

Data type: Cron::Hour

Cron hour

Default value: 0

user

Data type: Cron::User

The user who owns the cron job

Default value: 'root'

cron::job::hourly

Manage hourly cron jobs.

Parameters

The following parameters are available in the cron::job::hourly defined type:

• command
• ensure
• minute
• user

command

Data type: Cron::Command

Command path to be executed

ensure

Data type: Cron::Ensure

Cron job state

Default value: present

minute

Data type: Cron::Minute

Cron minute

Default value: 0

user

Data type: Cron::User

The user who owns the cron job

Default value: 'root'

cron::job::monthly

Manage weekly cron jobs.

Parameters

The following parameters are available in the cron::job::monthly defined type:

• command
• ensure
• minute
• hour
• monthday
• user

command

Data type: Cron::Command

Command path to be executed

ensure

Data type: Cron::Ensure

Cron job state

Default value: present

minute

Data type: Cron::Minute

Cron minute

Default value: 0

hour

Data type: Cron::Hour

Cron hour

Default value: 0

monthday

Data type: Cron::Monthday

Cron monthday

Default value: 1

user

Data type: Cron::User

The user who owns the cron job

Default value: 'root'

cron::job::weekly

Manage weekly cron jobs.

Parameters

The following parameters are available in the cron::job::weekly defined type:

• command
• ensure
• minute
• hour
• weekday
• user

command

Data type: Cron::Command

Command path to be executed

ensure

Data type: Cron::Ensure

Cron job state

Default value: present

minute

Data type: Cron::Minute

Cron minute

Default value: 0

hour

Data type: Cron::Hour

Cron hour

Default value: 0

weekday

Data type: Cron::Weekday

Cron weekday

Default value: 0

user

Data type: Cron::User

The user who owns the cron job

Default value: 'root'

cron::whitelist

Use this to whitelist any system cron jobs you don't want this module to touch. This will make sure /etc/cron.d/${title} won't get deleted or modified.

Examples

Using cron::whitelist resource

cron::whitelist { 'sample_name': }

Data types

Cron::Command

Used for cron::job::command parameter. Does not allow newline characters (which breaks crontab).

Alias of Pattern[/\A[^\n]+\z/]

Cron::Ensure

A simple ensure enum

Alias of Enum[present, absent]

Cron::Hour

Stricter cron::job::hour.

Alias of

Variant[Integer[0, 23], Array[Variant[
    Integer[0, 23],
    # Ranges like '0-12', '5-8', etc.
    Pattern[/\A(1?\d|2[0-3])-(1?\d|2[0-3])\z/],
    # Constructs like '*/5', '*/2'
    Pattern[/\A\*\/(1?\d|2[0-3])\z/],
  ], 2], Pattern[/\A(\*|(1?[0-9]|2[0-3])-(1?[0-9]|2[0-3]))(\/([2-9]|1[0-9]|2[0-3]))?\z/]]

Cron::Minute

Stricter cron::job::minute.

Alias of

Variant[Integer[0, 59], Array[Variant[
    Integer[0, 59],
    # Ranges like '0-37', '30-59', etc.
    Pattern[/\A[0-5]?\d-[0-5]?\d\z/],
    # Patterns like '*/2'
    Pattern[/\A\*\/([2-9]|[1-5]\d)\z/],
  ], 2], Pattern[/\A(\*|[0-5]?\d-[0-5]?\d)(\/([2-9]|[1-5]\d))?\z/]]

Cron::Month

Stricter cron::job::month.

Alias of Variant[Integer[1, 12], Array[Integer[1, 12], 2], Pattern[/\A\*(\/([2-9]|1[0-1]))?\z/]]

Cron::Monthday

Sricter cron::job::monthday.

Alias of Variant[Integer[1, 31], Array[Integer[1, 31], 2], Pattern[/\A\*(\/([2-9]|[1-2][0-9]|30))?\z/]]

Cron::User

Cron user.

Alias of Pattern[/\A\w[a-z0-9_-]{0,31}\z/]

Cron::Weekday

Stricter cron::job::weekday.

Alias of Variant[Integer[0, 6], Array[Integer[0, 6], 2], Pattern[/\A(\*|[0-6]-[0-6])(\/[2-6])?\z/]]

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[Unreleased]

[0.11.0] - 2024-08-01

Changed

• Update stdlib requirements in metadata.json.
• Update Puppet version requirements in metadata.json (now only Puppet 7 and 8 are supported).
• Update Ubuntu version support (now only 18.04, 20.04, 22.04 are supported).
• Switch to Litmus acceptance testing.
• Switch to GitHub actions for testing.

[0.10.0] - 2020-01-27

Added

• GH-8 Add $ensure parameter to cron::job and cron::job::* defined types.

[0.9.0] - 2019-08-08

Changed

• Update stdlib version requirements in metadata.json.
• Update REFERENCE.md with data type since Puppet strings started supporting these.
• PDK update.

[0.8.0] - 2018-10-09

Added

• Puppet 6 support (no production code changes).

Changed

• Validation, Unit, and Acceptance stages now all include Puppet 6.
• Run acceptance tests using new puppet and module install helpers.

[0.7.0] - 2018-09-08

Added

• Custom cron job types:
  • cron::job::hourly.
  • cron::job::daily.
  • cron::job::weekly.
  • cron::job::monthly.
• Cron::User type alias.

Changed

• Improve $::cron::package_version validation.

Removed

• cron::prep4cron() function. This was an internal function that uniq'd arrays passed to the cron::job resource. Things like [ 20, 50, 20, 50 ] are now fair play - both according to the crontab definition and this module.

[0.6.2] - 2018-09-01

Changed

• Minor change to README.md purely to test how Travis deployment works.

[0.6.1] - 2018-08-16

Fixed

• REFERENCE.md.

[0.6.0] - 2018-08-16

Added

• $cron::purge_cron parameter to manage crontab purging.
• $cron::allow_all_users parameter to allow all users to manage their crontabs.

Fixed

• puppetlabs_spec_helper's mock_with deprecation warning.
• Acceptance tests with latest beaker.
• RuboCop update.

[0.5.0] - 2018-03-14

Added

• Acceptance tests for /etc/cron.allow.
• Manage package version through $cron::package_version parameter.
• The following parameters are now available to manage cron service:
  • $cron::service_manage
  • $cron::service_ensure
  • $cron::service_enable

Changed

• Create an empty /etc/cron.allow by default.
• cron::job input is stricter:
  • command does not accept newlines
  • user accepts strings of at least 1 character
  • all time values have been updated (\A, \z instead of ^ and $)

[0.4.0] - 2018-03-05

Added

• Acceptance testing on Ubuntu 18.04.
• Acceptance tests for cron::job.
• REFERENCE.md generated using puppet-strings.

Changed

• Travis configuration prettified.
• Documentation cleanups.
• Acceptance tests split up into multiple spec files.

Fixed

• Removal order that led to (through a chain of other events) a non-working ensure => absent on Ubuntu 18.04.
• Proper trailing newline handling for /etc/cron.allow and /etc/cron.deny.

[0.3.0] - 2017-12-21

Added

• The Changelog.
• $::cron::purge_noop parameter that disables crontab purging (but you'll still see noop notices).
• $::cron::allowed_users and $::cron::denied_users parameters that manage users thru cron.allow and cron.deny files.

Changed

• A few more acceptance tests.
• Idempotence tests refactored.
• Adding/removing cron entries does not reload the cron service anymore.
• Cron::Minute and Cron::Hour now accept ranges and patterns like */2 inside an array.
• Because of the previous change, cron::prep4cron function doesn't sort the array anymore, it simply throws away repeated values.
• All Cron:: types accept a minimum of 2 array elements instead of 1.
• Updated tests for Cron:: types as rspec-puppet now supports these natively. w00h00!
• Added require ::cron to the cron::job define. It is now not necessary to include it. Beware though, that this might break if you don't have any cron jobs defined. No purging for you then!

Fixed

• Updated documentation for cron::prep4cron() function.

[0.2.0] - 2017-02-10

Added

• This is the first clean release of the cron module.

Changed

• Removed all incron references (this used to be cron + incron module).

[0.1.0] - 2017-02-08 [YANKED]

Added

• This used to be cron + incron module. After reading lots of suggestions about single-purposeness of modules, I decided to split this module into two and make this a pure cron-only one.
• This is the last point where you can check the previous approach.
• Doesn't seem feasible to release this, hence the [YANKED] tag.