Defined Type: systemd::timer::job

Defined in:
modules/systemd/manifests/timer/job.pp

Overview

Define: systemd::timer::job

Generic wrapper around the basic timer definition that adds log handling and monitoring for defining recurring jobs, much like crons in non-systemd world

description

Description to place in the systemd unit.

command

Command to be executed periodically.

interval

Systemd interval to use. See Systemd::Timer::Schedule for the format. Several intervals can be provided as Array[See Systemd::Timer::Schedule]

user

User that runs the Systemd unit.

environment

Hash containing 'Environment=' related values to insert in the Systemd unit.

monitoring_enabled

Periodically check the last execution of the unit and alarm if it ended up in a failed state. Default: true

monitoring_contact_groups

The monitoring's contact group to send the alarm to. Default: admins

logging_enabled

If true, log directories are created, rsyslog/logrotate rules are created. Default: true

logfile_basedir

Base directory for log files, to which /$title will be appended. Logs will be saved at $logfile_basedir/$title/$logfile_name Default: “/var/log”

logfile_name

The filename of the file storing the syslog output of the running unit. Default: syslog.log

logfile_owner

The user that owns the logfile. If undef, the value of $user will be used. Default: undef

logfile_group

The group that owns the logfile. Default: root''

logfile_perms

The UNIX file permissions to set on the log file. Check systemd::syslog for more info about the available options. Default: 'all'

syslog_force_stop

Force logs to be written into the logfile but not in syslog/daemon.log. This is particularly useful for units that need to log a lot of information, since it prevents a duplication of space consumed on disk. Default: true

syslog_match_startswith

If true, all syslog programnames that start with the service_name will be logged to the output log file. Else, only service_names that match exactly will be logged. Default: true

syslog_identifier

Adds the SyslogIdentifier parameter to the systemd unit to override the default behavior, namely using the program name. This is particularly useful when multiple timers are scheduled using the same program but with different parameters. Without an explicit SyslogIdentifier in fact they would end up sharing the same identifier and rsyslog rules wouldn't work anymore. Default: undef

max_runtime_seconds

Add a RuntimeMaxSec=… stanza to the systemd unit triggered by the timer. This can be useful when setting a timer to run some code every N minutes and the process run by the unit has a potential for deadlocking rather than exiting under some internal error condition. See <www.freedesktop.org/software/systemd/man/systemd.service.html#RuntimeMaxSec=> for more details. Default: undef (do not add stanza)

slice

Run the systemd timer's service unit under a specific slice. By default the service unit will run under the system.slice. Default: undef (do not add any Slice setting to the unit)

environment_file

String containing a file path to be used as 'EnvironmentFile=' in the Systemd unit.

Parameters:

  • description (String)
  • command (String)
  • interval (Any)
  • user (String)
  • environment (Hash[String, String]) (defaults to: {})
  • monitoring_enabled (Boolean) (defaults to: true)
  • monitoring_contact_groups (String) (defaults to: 'admins')
  • logging_enabled (Boolean) (defaults to: true)
  • logfile_basedir (String) (defaults to: '/var/log')
  • logfile_name (String) (defaults to: 'syslog.log')
  • logfile_owner (Optional[String]) (defaults to: undef)
  • logfile_group (String) (defaults to: 'root')
  • logfile_perms (Enum['user', 'group', 'all']) (defaults to: 'all')
  • syslog_force_stop (Boolean) (defaults to: true)
  • syslog_match_startswith (Boolean) (defaults to: true)
  • syslog_identifier (Optional[String]) (defaults to: undef)
  • ensure (Wmflib::Ensure) (defaults to: 'present')
  • max_runtime_seconds (Optional[Integer]) (defaults to: undef)
  • slice (Optional[Pattern[/\w+\.slice/]]) (defaults to: undef)
  • environment_file (Optional[Stdlib::Unixpath]) (defaults to: undef) 


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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'modules/systemd/manifests/timer/job.pp', line 99

define systemd::timer::job(
    String $description,
    String $command,
    # TODO: add type definition once we move past puppet 4.10, see https://tickets.puppetlabs.com/browse/PUP-7650
    # Variant[Systemd::Timer::Schedule, Array[Systemd::Timer::Schedule, 1]] $interval,
    $interval,
    String $user,
    Hash[String, String] $environment = {},
    Boolean $monitoring_enabled = true,
    String $monitoring_contact_groups = 'admins',
    Boolean $logging_enabled = true,
    String $logfile_basedir = '/var/log',
    String $logfile_name = 'syslog.log',
    Optional[String] $logfile_owner = undef,
    String $logfile_group = 'root',
    Enum['user', 'group', 'all'] $logfile_perms = 'all',
    Boolean $syslog_force_stop = true,
    Boolean $syslog_match_startswith = true,
    Optional[String] $syslog_identifier = undef,
    Wmflib::Ensure $ensure = 'present',
    Optional[Integer] $max_runtime_seconds = undef,
    Optional[Pattern[/\w+\.slice/]] $slice = undef,
    Optional[Stdlib::Unixpath] $environment_file = undef,
) {
    # Sanitize the title for use on the filesystem
    $safe_title = regsubst($title, '[^\w\-]', '_', 'G')


    $input_intervals = $interval ? {
#        Systemd::Timer::Schedule           => [$interval],
#        Array[Systemd::Timer::Schedule, 1] => $interval,
        Hash    => [$interval],
        Array   => $interval,
        # TODO: we can get rid of the default as soon as $interval is properly typed
        default => fail('Illegal value for $interval parameter'),
    }

    # If we were provided with only OnUnitActive/OnUnitInactive intervals, which are times relative
    # to when the service unit was last activated or deactivated, we need to add an additional
    # interval to get systemd to DTRT with this timer: an OnActiveSec that will start the service
    # for the first time after the timer and service are installed (or after a reboot).
    #
    # This activation gives meaning to the OnUnit intervals, as a null value for the timestamp of
    # last service activation/deactivation acts like NaN, making the comparison always false.
    $mangled_intervals = $input_intervals.all |$iv| {$iv['start'] =~ /OnUnit(In)?[Aa]ctive/} ? {
        false => $input_intervals,
        true  => $input_intervals + [{
            'interval' => '1s',
            'start'    => 'OnActiveSec'
        }],
    }

    systemd::unit { "${title}.service":
        ensure  => $ensure,
        content => template('systemd/timer_service.erb'),
    }

    systemd::timer { $title:
        ensure          => $ensure,
        timer_intervals => $mangled_intervals,
        unit_name       => "${title}.service",
    }

    if $logging_enabled {
        # The owner of the log files
        $log_owner = $logfile_owner ? {
            undef   => $user,
            default => $logfile_owner
        }

        # If syslog_match_startswith is false, use equality when matching
        # the programname to output to the log file, else use startswith.
        $syslog_programname_comparison = $syslog_match_startswith ? {
            false => 'isequal',
            true  => 'startswith',
        }

        systemd::syslog { $safe_title:
            ensure                 => $ensure,
            base_dir               => $logfile_basedir,
            log_filename           => $logfile_name,
            owner                  => $log_owner,
            group                  => $logfile_group,
            readable_by            => $logfile_perms,
            force_stop             => $syslog_force_stop,
            programname_comparison => $syslog_programname_comparison
        }
    }


    if $monitoring_enabled {
        # T225268 - always provision NRPE plugin script
        require ::systemd::timer::nrpe_plugin

        nrpe::monitor_service { "check_${title}_status":
            ensure         => $ensure,
            description    => "Check the last execution of ${title}",
            nrpe_command   => "/usr/local/lib/nagios/plugins/check_systemd_unit_status ${title}",
            check_interval => 10,
            retries        => 2,
            contact_group  => $monitoring_contact_groups,
            notes_url      => 'https://wikitech.wikimedia.org/wiki/Analytics/Systems/Managing_systemd_timers',
        }
    }
}