Chapter 14

Automated Jobs

Red Hat Certificate System (CS) provides a customizable Job Scheduler component that supports various mechanisms for scheduling cron jobs. This chapter explains how to configure CS to use specific job plug-in modules for accomplishing jobs.

This chapter contains the following sections:

About Automated Jobs

Red Hat Certificate System (CS) includes a component called Job Scheduler that can execute specific jobs at specified times. The job scheduler functions similar to a traditional Unix cron daemon in that it takes registered cron jobs and executes them at a preconfigured date and time. If configured, the scheduler checks at specified intervals for jobs waiting to be executed; if the specified execution time has arrived, the scheduler initiates the job automatically.

Jobs are implemented as Java classes, which are then registered with CS as plug-in modules. You can use a given implementation of a job module and configure multiple instances of it. Each instance must have a unique name (an alphanumeric string with no spaces) and can contain different input parameter values to apply to different jobs. You can also create custom job modules using the CS SDK.

Setting Up Automated Jobs

The automated jobs feature is set up by performing the following tasks:

Enabling and configuring the Job Scheduler; see "Setting Up the Job Scheduler" on page 555 for complete details.
Enabling and configuring one or more of the job modules and setting preferences for those job module; see "Setting Up Specific Jobs" on page 558 for complete details.
Customizing the email notification messages that are sent with these jobs. You do this by changing the template associated with a type of notification. You can change the contents of the message of both plain text messages and HTML messages, and the appearance of HTML messages. See "Customizing Notification Messages" on page 565 for more information

Types of Automated Jobs

The types of automated jobs are RenewalNotification, RequestInQueue, and UnpublishExpired.

RenewalNotificationJob

The RenewalNotification job checks for certificates that are about to expire in the internal database. When it finds one, it automatically emails the certificate's owner and continues sending email reminders for a configured period of time, or until the certificate is renewed. The job also collects a summary of all such renewal notifications and mails the summary to one or more agents or administrators.

The job determines the email address to send the notification using an email resolver, which you can customize using the CS SDK. By default, the email address is found in the certificate itself or in the certificate's associated enrollment request.

RequestInQueueJob

The RequestInQueue module checks the status of the request queue at preconfigured time intervals. If any deferred enrollment requests are waiting in the queue, the job constructs an email message summarizing its findings and sends it to the specified agents.

UnpublishExpiredJob

Expired certificates are not automatically removed from the publishing directory. If you configure a Certificate Manager or Registration Manager to publish certificates to an LDAP directory, over time the directory will contain expired certificates.

The UnpublishExpiredJob job checks for certificates that have expired and are still marked as published in the internal database at the configured time interval. The job connects to the publishing directory and deletes those certificates; it then marks those certificates as unpublished in the internal database. The job also collects a summary of expired certificates that it deleted and mails the summary to one or more agents or administrators as specified by the configuration.

Note that the job automates removal of expired certificates from the directory. You can also remove expired certificates manually following the instructions outlined in section "Updating Certificates and CRLs in a Directory," on page 635.

You can create additional automated jobs using the CS SDK.

Setting Up the Job Scheduler

The Certificate Manager and Registration Manager can execute a job only if the Job Scheduler is turned on (or enabled). As a part of turning the Job Scheduler on, you also specify the frequency at which the Job Scheduler daemon should check if any of the configured jobs need to be executed.

Frequency Settings for Automated Jobs

The Job Scheduler uses a variation of the Unix crontab entry format to specify dates and times for checking the job queue and executing jobs. As shown in Table 14-1, the time entry format consists of five fields (the sixth field specified for the Unix crontab is not used by the Job Scheduler). Values are separated by spaces or tabs.

Each field can contain either a single integer or a pair of integers separated by a hyphen (-) to indicate an inclusive range. To specify all legal values, a field can contain an asterisk rather than an integer. Day fields can contain a comma-separated list of values. The syntax of this expression is:

(Minute) (Hour) (Day of Month) (Month of Year) (Day of Week)

Table 14-1 Time Format for Scheduling Jobs
Field	Value
Minute	0-59
Hour	0-23
Day of month	1-31
Month of year	1-12
Day of week	0-6 (where 0=Sunday)

For example, the following time entry specifies every hour at 15 minutes (1:15, 2:15, 3:15 and so on):

15 * * * *

The following example specifies a job execution time of noon on April 12:

0 12 12 4 *

The day-of-month and day-of-week fields can contain a comma-separated list of values to specify more than one day. If both day fields are specified, the specification is inclusive; that is, the day of the month is not required to fall on the day of the week to be valid. For example, the following entry specifies a job execution time of midnight on the first and fifteenth of every month, and on every Monday:

0 0 1,15 * 1

To specify one day type without the other, use an asterisk in the other day field. For example, the following entry specifies a job execution time of 3:15 a.m. on every weekday morning:

15 3 * * 1-5

Enabling and Configuring the Job Scheduler

To schedule the interval for executing the job:

In the navigation tree, click Job Scheduler.

The General Settings tab appears. It shows whether the Job Scheduler component is currently enabled or disabled.

Enter information as appropriate:

Enable Jobs Scheduler. Select this option to enable the Job Scheduler; deselect to disable the Job Scheduler. Disabling turns off all the jobs.

Check Frequency. Type the frequency at which the Job Scheduler daemon thread should wake up and call the configured jobs that meet the cron specification. By default, it is set to one minute. See "Frequency Settings for Automated Jobs," on page 555. (The window for entering this information may appear too small. Drag the corners of the CS console window to enlarge the entire CS console window and this field will increase to a usable size.)

To save your changes, click Save.

Setting Up Specific Jobs

You can configure automated jobs using the CS console user interface, or by editing the configuration file directory. We recommend that you make these changes using the CS console.

Enabling and Configuring Specific Jobs Using the CS Console

To enable and configure an automated job using the CS console:

Ensure that the Jobs Scheduler is enabled and configured; see "Setting Up the Job Scheduler," on page 555 for more information.
Log in to the CS console (see "Logging Into the CS Console" on page 239).
Select the Configuration tab.
In the navigation tree, select Job Scheduler, then select Jobs.

The Job Instance tab appears showing the default jobs.

If you want to delete a job instance, select that instance and click delete.

If you want to add a job instance, click Add, then select the module you want to add.

To enable and configure an existing job instance, or modify the configuration of a job, go to the next step.

In the Instance Name list, select a job that you want to enable and configure.
Click Edit/View.

The Job Instance Editor window appears, showing how this job is currently configured.

Select Enable and set each of the configuration settings by specifying them in the fields for this dialog.

For RenewalNotifier see "Configuration Parameters of RenewalNotificationJob," on page 561 for details about these parameters.

For RequestInQueueJob see "Configuration Parameters of RequestInQueueJob," on page 562 for details about these parameters.

For UnpublishExpiredJob see "Configuration Parameters of UnpublishExpiredJob," on page 563 for details about these parameters.

Click Ok
Click Refresh
If you set up a job that sends automated messages, check that your have correctly set up a mail server. See "Mail Server," on page 250.
If you set up a job that sends automated messages, you can customize those messages. See "Customizing Notification Messages," on page 565 for details.

Enabling Configuring Specific Jobs By Editing the Configuration File

Ensure that the Jobs Scheduler is enabled and configured; see "Setting Up the Job Scheduler," on page 555 for more information.
Stop the server instance whose configuration file you will be editing.
Open the CS.cfg file for that server instance in a text editor.
Edit all of the configuration parameters for the job module you are enabling and configuring.

To configure RenewalNotifier, edit all parameters that begin with jobsScheduler.job.certRenewalNotifier; see "Configuration Parameters of RenewalNotificationJob," on page 561 for details about these parameters.

To configure RequestInQueueJob, edit all parameters that begin with jobsScheduler.job.requestInQueueNotifier; see "Configuration Parameters of RequestInQueueJob," on page 562 for details about these parameters.

To configure UnpublishExpiredJob, edit all parameters that begin with jobsScheduler.job.unpublishExpiredCerts; see "Configuration Parameters of UnpublishExpiredJob," on page 563 for details about these parameters.

Save the file.
Restart the server instance.
If you set up a job that sends automated messages, check that your have correctly set up a mail server. See "Mail Server," on page 250.
If you set up a job that sends automated messages, you can customize those messages. See "Customizing Notification Messages," on page 565 for details.

Configuration Parameters of RenewalNotificationJob

Table 14-2 gives details for each of these parameters that you configure either in the CS.cfg file or in the CS console.

Table 14-2 RenewalNotificationJob Parameters
Parameter	Description
enabled	Specifies whether the job is enabled or disabled. Specify the value of this parameter as true to enable; specify the value of this parameter as false to disable.
cron	Specifies the cron string specifying the schedule of when this job should be run. In other words, it specifies the time at which the Job Scheduler daemon thread should check the certificates for sending renewal notifications. Permissible values: Must follow the convention specified in "Frequency Settings for Automated Jobs" on page 555. Example: 03**1-5 In this example, the job will be executed from Monday through Friday at 3:00 pm.
notifyTriggerOffset	Specifies how long (in days) before certificate expiration the first notification will be sent.
notifyEndOffset	Specifies how long (in days) after the certificate expire notifications will continue to be sent, if the certificate is not renewed.
senderEmail	Specifies the sender of the notification messages (who will be notified of any delivery problems).
emailSubject	Specifies the text of the subject line of the notification message.
emailTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for formulating the message content.
summary.enabled	Specifies whether a summary report of renewal notifications should be compiled and sent. Specify the value of this parameter as true to enable; specify the value of this parameter as false to disable. If you enabled, be sure to set the remaining parameters; these are required by the server to send the summary report.
summary. recipientEmail	Specifies the recipients of the summary message. These can be, for example, agents who need to know the status of user certificates. You can specify more than one recipient by separating each email address with a comma.
summary.senderEmail	Specifies the email address of the sender of the summary message.
summary. emailSubject	Specifies the subject line of the summary message.
summary. itemTemplate	Specifies the path, including the filename, to the directory that contains the template to be used to create the content and format of each item to be collected for the summary report (see the summary.emailTemplate parameter below). For details, see "Customizing Notification Messages" on page 565.
summary. emailTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for formulating the summary report email notification. For details, see "Customizing Notification Messages" on page 565.

Configuration Parameters of RequestInQueueJob

Table 14-3 gives details for each of these parameters that you configure either in the CS.cfg file or in the CS console.

Table 14-3 RequestInQueueJob Parameters
Parameter	Description
enabled	Specify the value of this parameter as true to enable; specify the value of this parameter as false to disable.
cron	Specifies the cron specification for when this job should be run. This is the time at which the Job Scheduler daemon thread checks the queue for pending requests. Permissible values: Must follow the convention specified in "Frequency Settings for Automated Jobs" on page 555. Example: 00**0
subsystemid	Specifies the subsystem that this job is for. Permissible values: ca or ra. ca specifies that the job is for the Certificate Manager. ra specifies that the job is for the Registration Manager.
summary.enabled	Specifies whether a summary of the job accomplished should be compiled and sent. Specify the value of this parameter as true to enable; specify the value of this parameter as false to disable. If you enabled, be sure to set the remaining parameters; these are required by the server to send the summary report.
summary. emailSubject	Specifies the subject line of the summary message.
summary. emailTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for creating the summary report. For details, see "Customizing Notification Messages" on page 565.
summary.senderEmail	Specifies the sender of the notification message (who should be notified of any delivery problems).
summary. recipientEmail	Specifies the recipients of the summary message. These should be, for example, agents who need to process pending requests.You can specify more than one recipient by separating each email address with a comma.

Configuration Parameters of UnpublishExpiredJob

Table 14-4 gives details for each of these parameters that you configure either in the CS.cfg file or in the CS console.

Table 14-4 UnpublishExpiredJob Parameters
Parameter	Description
enabled	Specify the value of this parameter as true to enable; specify the value of this parameter as false to disable.
cron	Specifies the cron specification for when this job should be run. This is the time at which the Job Scheduler daemon thread checks the certificates for removing expired certificates from the publishing directory. Permissible values: Must follow the convention specified in "Frequency Settings for Automated Jobs" on page 555. Example: 00**6
summary.enabled	Specifies whether a summary of the certificates removed by the job should be compiled and sent. Specify the value of this parameter as true to enable; specify the value of this parameter as false to disable. If you enabled, be sure to set the remaining parameters; these are required by the server to send the summary report.
summary. emailSubject	Specifies the subject line of the summary message.
summary. emailTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for formulating the summary report.
summary. itemTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for formulating the content and format of each item to be collected for the summary report (see the summary.emailTemplate parameter above).
summary.senderEmail	Specifies the sender of the summary message (who should be notified of any delivery problems).
summary. recipientEmail	Specifies the recipients of the summary message. These can be, for example, agents who need to know the status of user certificates. You can specify more than one recipient by separating each email address with a comma.

Customizing Notification Messages

The email notifications that are sent are constructed using a template for each type of message that is sent. Each type of message has an HTML template and a plain text template associated with it. Messages are constructed from text and tokens, and HTML markup in the case of HTML templates. Tokens are variables, identified with the dollar sign ($) character, in the message that are replaced by the current value when the message is constructed. See "Token Definitions," on page 566 for a list of available tokens.

You can modify the contents of any message type by making changes to the text and tokens contained in the template for that message type. You can modify the appearance of HTML messages by modifying the HTML commands included in the HTML template for that message type.

Templates for Summary Notifications

Notification message templates are located in the following directory:

<server_root>/cert-<instance_id>/emails

Table 14-5 lists the default template provided for creating notification messages. You can change the name of these files as applicable; be sure to make the appropriate changes when configuring the job.

Table 14-5 Notification Templates
Filename	Description
UnpublishExpiredJob
ExpiredUnpublishJob	Template for constructing the summary report or table that summarizes removal of expired certificates from the directory. Uses the ExpiredUnpublishJobItem template to format the items in the table.
ExpiredUnpublishJobItem	Template for formatting the items to be included in the summary table.
RequestInQueueJob
riq1Item.html	Template for formatting the items to be included in the summary table, which is constructed using the riq1Summary.html template.
riq1Summary.html	Template for formulating the summary report or table that summarizes how many requests are pending in the agent queue of a Certificate Manager or Registration Manager.
RenewalNotificationJob
rnJob1.txt	Template for formulating the message content to be sent to end entities to inform them that their certificates are about to expire and that they should renew their certificates before expiration.
rnJob1Summary.txt	Template for constructing the summary report to be sent to agents and administrators. Uses the rnJob1Item.txt template to format items in the message.
rnJob1Item.txt	Template for formatting the items to be included in the summary report.

Token Definitions

Table 14-6 lists and defines the tokens that can be used in the notification message templates.

Table 14-6 Tokens for the renewal-notification job's summary report
Token	Description
$CertType	Specifies the type of certificate-whether SSL client (client), SSL server (server), Registration Manager's signing certificate (ra), Certificate Manager's CA signing certificate (ca), router certificate (Cisco-router), or other (other).
$ExecutionTime	Specifies the time the job (instance) was run.
$HexSerialNumber	Specifies the serial number of the certificate that has been issued in hexidecimal format.
$HttpHost	Specifies the fully qualified DNS host name of the Certificate Manager or Registration Manager to which end entities should connect to renew their certificates.
$HttpPort	Specifies the port number on which the Certificate Manager or Registration Manager is listening to certificate-renewal requests from end entities.
$InstanceID	Specifies the name of the job instance.
$IssuerDN	Specifies the distinguished name of the certificate issuer.
$NotAfter	Specifies the NotAfter attribute of the certificate validity period.
$NotBefore	Specifies the NotBefore attribute of the certificate validity period.
$RecipientEmail	Specifies the email address of the recipient.
$RequestId	Specifies the request ID.
$RequestorEmail	Specifies the requestor's email address.
$RequestType	Specifies the request type-whether it is a certificate enrollment, certificate renewal, certificate revocation, key archival, or key recovery request.
$RevocationDate	Specifies the date the certificate was revoked.
$SenderEmail	Specifies the email address of the sender.
$SerialNumber	Specifies the serial number of the certificate; the serial number will be displayed as a hexadecimal value in the resulting message.
$Status	Specifies whether the operation failed or succeeded.
$SubjectDN	Specifies the distinguished name of the certificate subject.
$SummaryItemList	Specifies the list of items in the summary notification. Each item corresponds to a certificate the job detects for renewal or for removal from the publishing directory.
$SummaryTotalFailure	Specifies the total number of items in the summary report that failed.
$SummaryTotalNum	Specifies the total number of items (certificates that require to be renewed, or certificates to be removed from the directory) in the summary report.
$SummaryTotalSuccess	Specifies how many of the total number of items in the summary report succeeded.

Managing Job Plug-ins

You can register a new job plug-in module or delete a job plug-in module. This section details how to perform these tasks.

Registering or Deleting a Job Module

You can register custom job plug-in modules from the CS window. Registering a new module involves specifying the name of the module and the full name of the Java class that implements the module.

You can also delete job modules, although it is not recommended.

To register or a job module in the CS framework:

Log in to the CS window (see "Logging Into the CS Console" on page 239).
Select the Configuration tab.
In the navigation tree, select Job Scheduler, then select Jobs.

The Job Instance tab appears. It lists any currently configured jobs.

Select the Job Plugin Registration tab.

The Job Plugin Registration tab appears.

To delete a module, select the module you want to delete and click Delete.

When prompted, confirm the delete action.

To register a module, click Register.

The Register Job Scheduler Plugin Implementation window appears.

Specify information as appropriate:

Plugin name. Type a name for the plug-in module.

Class name. Type the full name of the class for this module-that is, the path to the implementing Java class. If this class is part of a package, be sure to include the package name. For example, if you are registering a class named customJob and if this class is in a package named com.customplugins, type com.customplugins.customJob.

Click OK.