aboutsummaryrefslogtreecommitdiff
path: root/REFERENCE.md
blob: 79c1e42c060e475fd0d38011d6a3fc4cb23028d6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
# Reference
<!-- DO NOT EDIT: This document was generated by Puppet Strings -->

## Table of Contents

**Resource types**

* [`cron`](#cron): Installs and manages cron jobs. Every cron resource created by Puppet requires a command and at least one periodic attribute (hour, minute, m

## Resource types

### cron

Installs and manages cron jobs. Every cron resource created by Puppet
requires a command and at least one periodic attribute (hour, minute,
month, monthday, weekday, or special). While the name of the cron job is
not part of the actual job, the name is stored in a comment beginning with
`# Puppet Name: `. These comments are used to match crontab entries created
by Puppet with cron resources.

If an existing crontab entry happens to match the scheduling and command of a
cron resource that has never been synced, Puppet defers to the existing
crontab entry and does not create a new entry tagged with the `# Puppet Name: `
comment.

Example:

    cron { 'logrotate':
      command => '/usr/sbin/logrotate',
      user    => 'root',
      hour    => 2,
      minute  => 0,
    }

Note that all periodic attributes can be specified as an array of values:

    cron { 'logrotate':
      command => '/usr/sbin/logrotate',
      user    => 'root',
      hour    => [2, 4],
    }

...or using ranges or the step syntax `*/2` (although there's no guarantee
that your `cron` daemon supports these):

    cron { 'logrotate':
      command => '/usr/sbin/logrotate',
      user    => 'root',
      hour    => ['2-4'],
      minute  => '*/10',
    }

**Important:** _The Cron type will not reset parameters that are
removed from a manifest_. For example, removing a `minute => 10` parameter
will not reset the minute component of the associated cronjob to `*`.
These changes must be expressed by setting the parameter to
`minute => absent` because Puppet only manages parameters that are out of
sync with manifest entries.

**Autorequires:** If Puppet is managing the user account specified by the
`user` property of a cron resource, then the cron resource will autorequire
that user.

#### Properties

The following properties are available in the `cron` type.

##### `ensure`

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

##### `command`

The command to execute in the cron job.  The environment
provided to the command varies by local system rules, and it is
best to always provide a fully qualified command.  The user's
profile is not sourced when the command is run, so if the
user's environment is desired it should be sourced manually.

All cron parameters support `absent` as a value; this will
remove any existing values for that field.

##### `special`

A special value such as 'reboot' or 'annually'.
Only available on supported systems such as Vixie Cron.
Overrides more specific time of day/week settings.
Set to 'absent' to make puppet revert to a plain numeric schedule.

##### `minute`

The minute at which to run the cron job.
Optional; if specified, must be between 0 and 59, inclusive.

##### `hour`

The hour at which to run the cron job. Optional;
if specified, must be between 0 and 23, inclusive.

##### `weekday`

The weekday on which to run the command. Optional; if specified,
must be either:

-   A number between 0 and 7, inclusive, with 0 or 7 being Sunday
-   The name of the day, such as 'Tuesday'.

##### `month`

The month of the year. Optional; if specified,
must be either:

-   A number between 1 and 12, inclusive, with 1 being January
-   The name of the month, such as 'December'.

##### `monthday`

The day of the month on which to run the
command.  Optional; if specified, must be between 1 and 31.

##### `environment`

Any environment settings associated with this cron job.  They
will be stored between the header and the job in the crontab.  There
can be no guarantees that other, earlier settings will not also
affect a given cron job.


Also, Puppet cannot automatically determine whether an existing,
unmanaged environment setting is associated with a given cron
job.  If you already have cron jobs with environment settings,
then Puppet will keep those settings in the same place in the file,
but will not associate them with a specific job.

Settings should be specified exactly as they should appear in
the crontab, like `PATH=/bin:/usr/bin:/usr/sbin`.

##### `user`

The user who owns the cron job.  This user must
be allowed to run cron jobs, which is not currently checked by
Puppet.

This property defaults to the user running Puppet or `root`.

The default crontab provider executes the system `crontab` using
the user account specified by this property.

##### `target`

The name of the crontab file in which the cron job should be stored.

This property defaults to the value of the `user` property if set, the
user running Puppet or `root`.

For the default crontab provider, this property is functionally
equivalent to the `user` property and should be avoided. In particular,
setting both `user` and `target` to different values will result in
undefined behavior.

#### Parameters

The following parameters are available in the `cron` type.

##### `name`

namevar

The symbolic name of the cron job.  This name
is used for human reference only and is generated automatically
for cron jobs found on the system.  This generally won't
matter, as Puppet will do its best to match existing cron jobs
against specified jobs (and Puppet adds a comment to cron jobs it adds),
but it is at least possible that converting from unmanaged jobs to
managed jobs might require manual intervention.