Configuring the agent
Before you begin
You must conform to the following rules while specifying the parameters in the configuration data set:
- Only one parameter is allowed on each line and can start in any position on that line.
- Parameters must be specified in full and are not case-sensitive except for hierarchical file system (HFS) path names.
- A line with an asterisk * in the first position is treated as a comment.
- RSS parameters support standard z/OS ampersand-prefixed (&) variables (for example, &SYSNAME).
- (SPE2507) You can include static and dynamic system symbols in the parameters. For more information, see Using static and dynamic system symbols in parameters.
Using static and dynamic system symbols in parameters
System symbols act as placeholders and are replaced by substitution text (a character string) to maintain unique values in your shared parameter library definitions (accessible to multiple systems). There are two types of system symbols:
- Static system symbol—The substitution text for these symbols are either system-defined or defined in the IEASYMxx member via the SYMDEF subcommand processing. Static system symbols are set during IPL (Initial Program Load) and do not normally change.
- Dynamic system symbol—The substitution text for these symbols can change in real time at any point in an IPL and it is available via the IBM ASASYMBM or ASASYMBF service. You can use dynamic system symbols to build dynamic paths and file names.
Static or dynamic system symbols that you use must be defined in the "z/OS MVS Initialization and Tuning Reference" manual.
The following table lists commonly used dynamic system symbols:
| Dynamic system symbol | Description |
|---|---|
| &MON | Month of the year |
| &DAY | Day of the month |
| &JDAY | Julian day of the year |
| &YR2 | Year in two digits |
| &YR4 | Year in four digits |
| &WDAY | Name of the day of the week |
| &HR | Hour |
| &MIN | Minute |
| &SEC | Second |
| &JOBNAME | Job name of task |
| &HHMMSS | Time of day. Use &LHHMMSS for local time. |
| &YYMMDD | Date. Use &LYYMMDD for local date. |
For more information about system symbols, see the "z/OS MVS Initialization and Tuning Reference" manual.
To set up your agents, you must configure the following statements. You can find a sample configuration member, ECVAPARM, in the hlq.RSSSAMP library.
Global statement
The following global parameters define general functionality:
Parameter | Description |
|---|---|
Activate appName | Name of the application to be loaded The value of this parameter must be Venafi. |
MessageLevel level level | Message level written to RSSPRINT You can define multiple message levels. We recommend that you include message level Info Error. |
RACFAdminUser userID | User ID for issuing commands to the external security manager (ESM) If you omit this parameter, the user ID of the agent task is used. |
ECAgent statement
The following ECAgent parameters define the REST API server for the agent instance. Only one ECAgent statement is required per instance.
Parameter | Description |
|---|---|
ECAgent | Begins the ECAgent statement |
HostName hostName | IPaddress | (Required) Location of the agent instance Enter the host name or IP address for the server on which the agent is located. |
Port portNumber | Port number used by the agent instance (Required) Enter the port number to be used by the REST API for the agent. |
DatasetHLQ hlq | High-level qualifier for temporary data sets EC for Venafipasses the specified hlq to the REXX procedures that generate the full data set name. Specify up to 17 characters. The high-level qualifier cannot end with a period and it must conform to z/OS data set naming standards for data set qualifiers. For example:
The default value is blank; no qualifier is used. |
CheckpointDataset vsamDataSetName | Name of the VSAM KSDS data set for checkpointing This parameter has no default. |
CheckpointShared Yes | No | Specifies whether the checkpoint data set should be shared across multiple agent instances in the same sysplex The default value is No. |
TLSAware Yes | No | Verifies whether incoming transactions have been secured by a valid AT-TLS policy Transactions that are flagged as insecure or not having an AT-TLS policy are rejected. The default value is No. |
VerifyGateway Yes | No | Verifies whether incoming transactions have been sent by a genuine EC for Venafi gateway Transactions that are flagged as not coming from a genuine gateway are rejected. The default value is No. |
VipaGroup dvipaName | Specifies the name of the DVIPA target Use this parameter if you are using Dynamic Virtual IP Addressing (DVIPA) from your Venafi Trust Protection Platform (TPP), instead of an LPAR, to process agent requests. System symbolics, such as &SYSNAME, are supported. The DVIPA name can be up to 16 characters in length. |
ExpirySearchTime hh:mm | Time of day that EC for Venafi searches for expired certificates Enter the hour and minutes to perform the search. The default value is 00:00. |
DeleteAfter days | Number of days after which an expired certificate is deleted Accepted values for this parameter are:
The default value is 0. |
EndECAgent | Ends the ECAgent statement |
Sample eC Agent statements
EmailProfile statement
The following EmailProfile parameters define the type of email that the agent sends to the JES destination:
Parameter | Description |
|---|---|
EmailProfile | Begins the EmailProfile statement |
FromEmail emailAddress | (Required) Email address assigned to the agent that sent the email |
SysoutClass class | (Required) Output print class for printing email data that the IBM Communications Server Simple Mail Transfer Protocol (CSSMTP) application scans for |
SysoutDEST systemName | (Required) JES destination for routing email data, which is the name of the system on which CSSMTP is running |
SysoutWriter writerName | (Required) External writer name used by CSSMTP to scan email data The value of this parameter must be the same as the value of the ExtWrtName statement that is defined in the CSSMTP configuration. |
EndEmailProfile | Ends the EmailProfile statement |
EmailRecipients statement
The following EmailRecipients parameters define the email addresses of individuals and groups who should receive email notifications from the agent:
Parameter | Description |
|---|---|
EmailRecipients | Begins the EmailRecipients statement |
Expired To emailAddress | (Optional) Sends an email to a person or group when EC for Venafi detects an expired certificate You can repeat this parameter for as many recipients as you want. |
Failures To emailAddress | (Optional) Sends an email to a person or group when EC for Venafi fails to process a TPP request You can repeat this parameter for as many recipients as you want. |
Success To emailAddress | (Optional) Sends an email to a person or group when EC for Venafi succeeds in processing a TPP request You can repeat this parameter for as many recipients as you want. |
EndEmailRecipients | Ends the EmailRecipients statement |