Previous Contents Index Next |
iPlanet Certificate Management System Plug-ins Guide |
Chapter 2 Job Plug-in Modules
iPlanet Certificate Management Server (CMS) 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 that you might want to schedule include email notifications of timed events (such as the expiration of a certificate) that require action on the part of users, and periodic activities such as updates of related directories.
This chapter describes the job plug-in modules that are provided with Certificate Management System and explains how to schedule times for jobs.
The chapter has the following sections:
Overview of Job Plug-in Modules
RenewalNotificationJob Plug-in Module
Overview of Job Plug-in Modules
Both the Certificate Manager and Registration Manager provide a set of job plug-in modules that can be employed by the server to automate certain activities. The Job Plugin Registration tab of the CMS window (see Figure 2-1) lists all the modules and the corresponding classes that are currently registered with a Certificate Manager.
Figure 2-1    Default job modules for the Certificate Manager
Table 2-1 lists these modules.
Table 2-1    Schedulable job plug-in modules for Certificate Manager and Registration Manager
Plug-in module name
Description
A schedulable job that notifies end entities by email that their certificates are about to expire and must be renewed, and optionally sends a summary of these notices to agents. For more information, see RenewalNotificationJob Plug-in Module.
A schedulable job that notifies agents at regular intervals of the current state of the request queue.
In addition, agents can also be notified by email that a request has been added to the request queue by configuring an event-driven notification. See RequestInQJob Plug-in Module.
A schedulable job that updates the configured publishing directory periodically by removing expired certificates, and sends a summary of removed certificates to agents or administrators. For more information, see UnpublishExpiredJob Plug-in Module.
Jobs are implemented as Java classes, which are then registered with Certificate Management System 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.
Note that the name of the Java class for a job plug-in module is in this format:
com.iplanet.certsrv.jobs.<plugin_name>
where <plugin_name> is the name of a plug-in module. For example, the Java class for the RenewalNotificationJob module would be:
com.iplanet.certsrv.jobs.RenewalNotificationJob
RenewalNotificationJob Plug-in Module
When a certificate is about to expire, the owner of the certificate needs to renew it. Using the Jobs Scheduler, you can configure a Certificate Manager or Registration Manager to automatically send email-based renewal notices to users whose certificates are about to expire or have expired. You can also configure these subsystems to send one or more administrators or issuing agents a summary of users who have received these reminders.
The RenewalNotificationJob plug-in module is a schedulable job. When an instance of the job is enabled, it 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 which to send the notification using an email resolver, which you can customize. By default, the email address is found in the certificate itself or in the certificate's associated enrollment request.
The email notification message, as well as the summary message, are constructed using a template found in the configured directory. This directory has the following default location: <server_root>/cert-<instance_id>/emails
You can configure both the path and filenames of the template files for each job and modify the templates to customize the contents and appearance of the messages. Messages can be sent as HTML or plain text. For customization information, see Customizing Notification Messages.
For each instance of the RenewalNotificationJob class, you can configure the following:
The schedule of times when the job will be run; see Schedule for Executing Jobs.
How long before expiration the first notification will be sent.
How long, after the certificate expires, notifications will continue to be sent if the certificate is not renewed.
The sender of the notification messages (who will be notified of any delivery problems).
The file location of the notification email template.
The subject line of the notification message.
How the email address for the notification is to be resolved. If a summary is to be sent, you can configure the following:
The recipients of the summary message. These can be, for example, agents who need to know the status of user certificates.
The sender of the summary message (who will be notified of any delivery problems).
The file location of the summary message template.
The file location of content and format of each item to be collected for the summary.
Configuration Parameters of RenewalNotificationJob
In the CMS configuration file, the RenewalNotificationJob module is identified as jobsScheduler.impl.RenewalNotificationJob.class=com.iplanet.
certsrv.jobs.RenewalNotificationJob.
In the CMS window, the module is identified as RenewalNotificationJob. Figure 2-2 shows how the configurable parameters pertaining to the plug-in module are displayed in the CMS window.
Figure 2-2    Parameters defined in the RenewalNotificationJob module
Table 2-2 gives details about each of these parameters.
Table 2-2    Description of parameters defined in the RenewalNotificationJob module
Parameter
Description
Specifies whether the job is enabled or disabled. Check the box to enable the job. Uncheck the box to disable the job. If you enable the job and set the remaining parameters correctly, the server runs the job at scheduled intervals.
Specifies the cron specification for 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 Schedule for Executing Jobs
Specifies how long (in days) before certificate expiration the first notification will be sent.
Specifies how long (in days) after the certificate expire notifications will continue to be sent, if the certificate is not renewed.
Specifies the sender of the notification messages (who will be notified of any delivery problems).
Specifies the subject line of the notification message.
Permissible values: An alphanumeric string of up to 255 characters.
Specifies the path, including the filename, to the directory that contains the template to be used for formulating the message content.
Permissible values: Template file path, including the file name.
Specifies whether a summary report of renewal notifications should be compiled and sent. Check the box if you want the server to compose and send a summary report. Uncheck the box if you don't want the server to compose and send a summary report. If you check the box, be sure to set the remaining parameters; these are required by the server to send the summary report.
Specifies the recipients of the summary message. These can be, for example, agents who need to know the status of user certificates.
Permissible values: Full email addresses, separated by commas.
Specifies the sender of the summary message (who will be notified of any delivery problems).
Specifies the subject line of the summary message.
Permissible values: An alphanumeric string of up to 255 characters.
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 below). For details, see Customizing Notification Messages.
Permissible values: The template file path, including the file name.
Example: C:\iplanet\servers\cert-testCA\emails\
renewJobItem.txt
Specifies the path, including the filename, to the directory that contains the template to be used for formulating the summary report. For details, see Customizing Notification Messages.
Permissible values: The template file path, including the file name.
Example: C:\iplanet\servers\cert-testCA\emails\
renewJobSummary.txt
RequestInQJob Plug-in Module
In addition to or instead of notifying agents of new requests, you might want to schedule a job that regularly notifies them of the status of the request queue. Such a job can check at a configured interval whether there are any deferred enrollment requests waiting for review. It can then send an email message to agents informing them of the number of requests waiting in the request queue for which they are responsible.
The RequestInQJob plug-in module is a schedulable job. When an instance of the job is enabled, it gets activated at the configured interval and checks the status of the request queue. 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.
The job constructs the summary message by using a template located in a configured directory. This directory has the following default location: <server_root>/cert-<instance_id>/emails
You can configure the path and filename of the template file for each job and modify the templates to customize the contents and appearance of the messages. Messages can be sent as HTML or plain text.
For each instance of the RequestInQJob class, you can configure the following:
The subsystem, Certificate Manager or Registration Manager, that should use this job.
The schedule of times when the job will be run; see Schedule for Executing Jobs.
The sender of the notification messages (who will be notified of any delivery problems).
The file location of the notification email template.
The subject line of the notification message.
The email addresses of message recipients; these should be subsystem agents whose task it is to review manual enrollment requests.
Configuration Parameters of RequestInQJob
In the CMS configuration file, the RequestInQJob module is identified as
jobsScheduler.impl.RequestInQJob.class=com.iplanet.certsrv.
jobs.RequestInQJob.
In the CMS window, the module is identified as RequestInQJob. Figure 2-3 shows how the configurable parameters for the module are displayed in the CMS window.
Figure 2-3    Parameters defined in the RequestInQJob module
Table 2-3 gives details for each of these parameters.
Table 2-3    Description of parameters defined in the RequestInQJob module
Parameter
Description
Specifies whether the job is enabled or disabled. Check the box to enable the job. Uncheck the box to disable the job. If you enable the job and set the remaining parameters correctly, the server runs the job at scheduled intervals.
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 Schedule for Executing Jobs
Specifies whether a summary of the job accomplished should be compiled and sent. Check the box if you want the server to compose and send a summary report. Uncheck the box if you don't want the server to compose and send a summary report. If you check the box, be sure to set the remaining parameters; these are required by the server to send the summary report.
Specifies the subject line of the summary message.
Permissible values: An alphanumeric string of up to 255 characters.
Specifies the path, including the filename, to the directory that contains the template to be used for formulating the summary report. For details, see Customizing Notification Messages.
Permissible values: The template file path, including the file name.
Example: C:\iplanet\servers\cert-testCA\emails\
reqInQJobSummary.txt
Specifies the sender of the notification message (who should be notified of any delivery problems).
Specifies the recipients of the summary message. These should be, for example, agents who need to process pending requests.
Permissible values: Full email addresses, separated by commas.
UnpublishExpiredJob Plug-in Module
Certificate Management System doesn't automatically remove expired certificates 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. To help you remove expired certificates from the directory, both the Certificate Manager and Registration Manager come with a plug-in module that allows you to create a schedulable job that periodically removes (or unpublishes) certificates that have expired. When the directory has been updated, the job can collect a summary report of the certificates that have been removed and send it to people who need to have this information. Typically, you would want to send this notification to certificate issuing agents or the administrator of the publishing directory.
Th UnpublishExpiredJob plug-in module is a schedulable job. When an instance of the job is enabled, it gets activated at the configured interval and checks for certificates that have expired and are still marked as published in the internal database. The job connects to the publishing directory and deletes these certificates; it then marks these 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.
The job constructs the summary message by using a template located in a configured directory. This directory has the following default location: <server_root>/cert-<instance_id>/emails
You can configure the path and filename of the template file for each job. You can also modify the templates to customize the contents and appearance of the messages; see Customizing Message Templates.
Messages can be sent as HTML or plain text.
For each instance of the UnpublishExpiredJob class, you can configure the following:
The schedule of times when the job will be run; see Schedule for Executing Jobs. If a summary is to be sent, you can configure the following:
The recipients of the summary message. These can be, for example, administrators who are responsible for the publishing directory.
The sender of the summary message (who will be notified of any delivery problems).
The file location a of the summary message template.
The file location of content and format of each item to be collected for the summary. 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 "Manually Updating Certificates and CRLs in a Directory" in Chapter 19, "Setting Up LDAP Publishing" of CMS Installation and Setup Guide.
Configuration Parameters of UnpublishExpiredJob
In the CMS configuration file, the UnpublishExpiredJob module is identified as
jobsScheduler.impl.ExpiredUnpublishJob.class=com.iplanet.
certsrv.jobs.UnpublishExpiredJob.
In the CMS window, the module is identified as UnpublishExpiredJob. Figure 2-4 shows how the configurable parameters for the module are displayed in the CMS window.
Figure 2-4    Parameters defined in the UnpublishExpiredJob module
Table 2-4 gives details for each of these parameters.
Table 2-4    Description of parameters defined in the UnpublishExpiredJob module
Parameter
Description
Specifies whether the job is enabled or disabled. Check the box to enable the job. Uncheck the box to disable the job. If you enable the job and set the remaining parameters correctly, the server runs the job at scheduled intervals.
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 Schedule for Executing Jobs
Specifies whether a summary of the certificates removed by the job should be compiled and sent. Check the box if you want the server to compose and send a summary report. Uncheck the box if you don't want the server to compose and send a summary report. If you check the box, be sure to set the remaining parameters; these are required by the server to send the summary report.
Specifies the subject line of the summary message.
Permissible values: An alphanumeric string of up to 255 characters.
Specifies the path, including the filename, to the directory that contains the template to be used for formulating the summary report. For details, see Customizing Notification Messages.
Permissible values: The template file path, including the file name.
Example: C:\iplanet\servers\cert-testCA\emails\
unpublishCertsJobSummary.html
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).
Permissible values: The template file path, including the file name.
Example: C:\iplanet\servers\cert-testCA\emails\
unpublishCertsJobItem.txt
Specifies the sender of the summary message (who should be notified of any delivery problems).
Specifies the recipients of the summary message. These can be, for example, agents who need to know the status of user certificates.
Permissible values: Complete email addresses, separated by commas.
Schedule for Executing 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 2-5, 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.
Table 2-5    Time format for scheduling jobs
Field
Value
Each field can contain either a single integer or a pair of integers separated by a hyphen or dash (-) 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.
For example, the following time entry specifies every hour at 15 minutes (1:15, 2:15, 3:15 and so on):
The following example specifies a job execution time of noon on April 12:
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:
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:
Customizing Notification Messages
Summary email messages are constructed using templates located in the emails directory of a CMS instance. This directory has the following default location: <server_root>/cert-<instance_id>/emails
Both text an HTML templates are included by default. They are listed in Table 2-6.
Templates for Summary Notifications
Table 2-6 lists the default template files for formulating the notification messages that summarize jobs that were executed by the Job Scheduler component of a Certificate Manager or Registration Manager. You can change the name of these files as applicable; be sure to make the appropriate changes to the configuration.
For summaries, a separate template is used to format the entry for each item in the summary. The item entries are then added to a table in the summary message.
Tokens, which you can use as variables in the body of the message, are defined for each templates enabling you to customize the message; the token is replaced by its current variable value in the constructed message. For details, see Customizing Message Templates.
Note that in the CMS configuration, template files for schedulable jobs are identified as follows:
jobsScheduler.job.<job_name>.summary.emailTemplate=
<template_file_path>
jobsScheduler.job.<job_name>.summary.itemTemplate=
<template_file_path>
Customizing Message Templates
You can modify the templates to customize the contents and appearance of messages. The message body can contain HTML or plain text. In the body of the message, you can use tokens or keywords as variables. A token is indicated by the dollar character ($) and is replaced by its current variable value in the constructed message. Different tokens are available for each job or notification class. These are listed in Tokens Available in Message Templates.
For example, a certificate-issuance-notification message can make use of tokens as follows:
------------------------------------
CERTIFICATE RENEWAL NOTIFICATION
------------------------------------
Your certificate will expire soon:
Serial Number= $SerialNumber
SubjectDN= $SubjectDN
IssuerDN= $IssuerDN
Validity Period= $NotBefore - $NotAfter
To renew your certificate, please follow this URL:
https://$HttpHost:$HttpPort
If you have any questions or problems, please send an email to cert_central@siroe.com.
Thank you.
Tokens Available in Message Templates
This section explains the tokens provided in the templates used by the default job plug-in and event-triggered notification modules to formulate notification messages.
Tokens for Renewal Notification Messages
This section lists the tokens that are available in the message templates for instances of the RenewalNotificationJob class or plug-in module.
Table 2-7 lists the tokens that you can use for formulating this job's summary report. You can customize the content and format of the items in the report by using the tokens defined in Table 2-8.
Table 2-8 lists the tokens for the inner list items.
Table 2-8    Tokens for items in renewal-notification job's summary report
Token
Description
Specifies the type of certificatewhether 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).
Specifies the fully qualified host name of the Certificate Manager or Registration Manager to which end entities should connect to renew their certificates. (The token enables you to construct the URL which end entities use to renew their certificates; see the example in Customizing Message Templates.)
Specifies the port number at which the Certificate Manager or Registration Manager is listening to certificate-renewal requests from end entities. (The token enables you to construct the URL which end entities use to renew their certificates; see the example in Customizing Message Templates.)
Specifies the request typewhether it is a certificate enrollment, certificate renewal, certificate revocation, key archival, or key recovery request.
Specifies the serial number of the certificate; the serial number will be displayed as a hexadecimal value in the resulting message.
Specifies the distinguished name of the certificate subject.
Tokens for Request In Queue Notification Messages
Table 2-9 lists the tokens that you can use for formulating the content of the RequestInQueueJob job's summary report.
Tokens for Directory Update Notification Messages
This section lists the tokens that are available in summary message templates for instances of the UnpublishExpiredJob class or plug-in module.
Table 2-10 lists the tokens that are available for this jobs's summary report. You can customize the content and format of the items in the report by using the tokens defined in Table 2-11.
Table 2-11 lists the tokens for the inner list items.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated October 07, 2002