Install the Provisioning Agent - Pioneer and Reconciliation Agent - Voyager of the CA Top Secret connector on the mainframe. These agents communicate with the LDAP Gateway during connector operations.
These are the software and environmental setting requirements for installing the Provisioning Agent - Pioneer and Reconciliation Agent - Voyager.
Verifying Installation Requirement
Ensure that the mainframe system on which you intend to install Pioneer and Voyager meet the following requirements:
Table 4-1 Installation Requirements for Agents
| Item | Requirement |
|---|---|
| Operating System | IBM z/OS 2.2, 2.3 |
| Message Transport Layer | TCP/IP |
| CA Top Secret Identity Repository | Verify that the current patch for z/OS is installed. |
| Target system user account for the Provisioning Agent - Pioneer and Reconciliation Agent - Voyager | CA Top Secret-authorized user account with System Administrators privileges. |
Note:
Both the Voyager and Pioneer Agents must have CA Top Secret ACIDs defined on the CA Top Secret database. These ACIDs must have at least the permissions of the System Administrators group on the mainframe. These user accounts have permissions above those of ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges. Voyager and Pioneer use Language Environment. The following are the recommended Language Environment runtime options that avoid issues when installing Voyager and Pioneer:Environmental Settings and Other Requirements
Ensure that the following requirements are met on the mainframe:
Maintaining a specific password format is an example of the objective for which you use custom exits.
When the exit is enabled, it will collect TSS events and cache them in a storage subpool. In addition, TSSINSTX calls IDFCACHE, which is the CA Top Secret caching module.
Note:
As the systems programmer, you must do an IPL after a system component is changed or modified.The CA Top Secret connector is shipped with a pair of agents, one for provisioning (Pioneer) and one for real-time reconciliation (Vogayer). If real-time reconciliation is not required, then install and start only the provisioning agent.
After installing Pioneer and Voyager, you must configure the mainframe agents to receive requests from and send responses to the LDAP gateway.
You must configure the provisioning agent to receive requests from the LDAP gateway, which originates from Oracle Identity Manager.
Edit the <HLQ>.PIONEER.CONTROL.FILE file to configure the behavior of the provisioning agent. Here, <HLQ> is the high-level-qualifier that you specified while installing the agents.
Table 4-4 Parameters of the Pioneer Control File
| Parameter | Value | Description |
|---|---|---|
| TCPN | TCPIP |
The name of the TCP/IP STC where the agent is executing. |
| IPAD | 0.0.0.0 |
Do not change. |
| PORT | 9999 |
The TCP/IP port that the agent will listen on. |
| CRLF | Y or N |
If this flag is set to Y, then mainframe sends a response with carriage line feed.
You must set the value of this parameter to Y for version 6+ of the LDAP Gateway. Set to N for version 5. |
| ESIZE | 16 |
This is the only valid value. This parameter is for the AES128 encryption and decryption. |
| POST_PROC_ALIAS | T or F |
If you set the value of this parameter to T, then all LDAP Alias requests are processed. If you set it to F, then all LDAP Alias requests are rejected. |
| RWAIT | 0 or 999 (in seconds) |
Enter the number of seconds the agent must wait before executing the jobs submitted by the batch recon. |
| JWAIT | 0 or 999 (in seconds) |
Enter the number of seconds the agent must wait before executing the IDCAMS jobs. |
| QUEUE_DSN | IDF.SEARCH |
Max 44 character DSN used with RWAIT for recons. This DSN does not need allocated or deleted. |
| EXPORT_MON | NO or YES, REC=X |
Monitor XML imports displaying a message every X ACIDS. |
| IP | V4 or V6 |
IP version to be used for communication between LDAP gateway and PIONEER agent. Value Value Default value is |
| DEBUG | Y or N |
This parameter is deprecated. |
| IDLEMSG | Y or N |
This parameter is deprecated. |
| DEBUGOUT | SYSOUT, CLASS(X) |
This parameter is deprecated. |
| SPIN_CLASS | X |
This parameter is deprecated. |
| AUDIT_LOG | YES or NO |
This parameter is deprecated. |
Postprocessing Procedure for the Provisioning Agent
C=CREATE,M=TESTA,L=TEST.TESTA C=ADDTO,M=TESTB,L=TEST.TESTB C=REMOVE,M=TESTC,L=TEST.TESTC Control file ( //PARMFLE ) explanations:
By default, the post-processing submits member (M=) from PDS library (L=) for every CREATE, ADDTO, REMOVE done on TSS. The post-processing takes place on every command added to the Pioneer control file. This library is dynamically allocated to Pioneer and later freed. If no post-processing is required, then do not code the C= for the TSS command. For example, C=CREATE …… C=ADDTO ….
/* rexx sample clist */ Arg p1 p2
The Library specified with L= parameter and the member with M= parameter should contain batch JCL to execute REXX Clist.
//REXXCLST JOB SYSTEMS,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A,PRTY=8, // NOTIFY=&SYSUID,REGION=0K //STEP0 EXEC PGM=IKJEFT01,DYNAMNBR=50 //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSPROC DD DISP=SHR,DSN=PIONEER.CLIST.LIBRARY //SYSTERM DD DUMMY //SYSTSIN DD * /*
For postprocessing the commands (CREATE/ADDTO/REMOVE etc ) mentioned in the control file, Pioneer adds: %clistname P1 P2
Where clistname is the value specified with M= parameter in the control file for the corresponding command.
Note:
The JCL member name specified with the M= parameter in the control file and the corresponding REXX/Clist member name needs to be the same.You must configure the reconciliation agent to send incremental responses to the LDAP gateway.
Edit the <HLQ>.VOYAGER.CONTROL.FILE file to configure the behavior of the reconciliation agent. <HLQ> is the high-level qualifier that you specified while installing the agents.
Note:
Voyager keeps reading supbool 231 for any reconciliation events and processes them. Therefore, for efficient use of allocated subpool 231, it is recommended to have Voyager up and running, failing which condition of event loss may occur.Table 4-5 Parameters of the Voyager Control File
| Parameter | Value | Description |
|---|---|---|
| TCPN | TCPIP |
The name of the TCP/IP STC where the agent is executing. |
| IPAD | 999.999.999.999 or ldap.example.com |
LDAP destination IP address or hostname (up to 40 characters). |
| PORT | 9999 |
LDAP destination port that is listening to the incoming agent messages. |
| CRLF | Y or N |
If this flag is set to Y, then mainframe sends a response with carriage line feed. You must set the value of this parameter to Y for version 6+ of the LDAP Gateway. Set to N for version 5. |
| ESIZE | 16 |
This is the only valid value. This parameter is for the AES128 encryption and decryption. |
| CACHE_DELAY | 0 to 999 |
This is the number of seconds that Voyager waits before issuing a write socket to the LDAP Gateway. |
| VOYAGER_ID | VOYAGER |
This value will be included in the LDAP logs for diagnostic |
| CONNECT_RETRY | 999 |
The number of times to retry when the LDAP connection is down. |
| CONNECT_INTV | 10 |
The number of seconds between retries when the LDAP connection is down. |
| FAST_SHUTDOWN_NUM | Any 3-digit numeric value |
A 3-digit numeric value representing a batch. Note: If you enter 0 or 1 as the value of this parameter, then this value is automatically defaulted to Voyager uses this 3-digit numeric value to process the records prior to checking operator’s shutdown command. An explicit check for the shutdown command (/F VOYAGER,SHUTDOWN) is made only after processing each batch (of FAST_SHUTDOWN_NUM number of events). Whenever you enter the shutdown command, Voyager saves any remaining events (including events from subpool 231) to the disk (“cache save file”) file for processing them later and shuts the process down. If there is no shutdown command, then Voyager processes the next ‘batch’ of events. Re-polling (reading from subpool 231) will continue to happen after all events are processed (when events are less than 100 or after processing 100 events each). |
| IP | V4 or V6 |
IP version to be used for communication between LDAP gateway and VOYAGER agent. Value Value Default value is |
| PIONEER_DELETE_MSGS |
Not applicable |
The parameter is deprecated. |
| RECOVERY_INTERVAL |
Not applicable |
The parameter is deprecated. |
| DNS_RECOVERY_INTERVAL |
Not applicable |
The parameter is deprecated. |
| DEBUG | Y or N |
This parameter is deprecated. |
| DEBUGOUT | SYSOUT, CLASS (X) |
This parameter is deprecated. |
| CONNECT_MSGS | Y or N |
This parameter is deprecated. |
| MSGID01 | NO or YES,IDMV602E,X |
This parameter is deprecated. |
You can configure logging for both Pioneer and Voyager by editing the <HLQ>.PIONEER.CONTROL.LOG and <HLQ>.VOYAGER.CONTROL.LOG files, respectively, and setting values for various log parameters based on your requirement. For example, you can have complete control over the messages that you want to print or suppress and also the device over which the message must be printed. A separate control file is designed and used to control the functionality of logging through LOGGERX.
Logging Parameters
LOGGERX requires initial parameters setup for operating. This is achieved by using a control file (different from the control file for Pioneer). The parameters of this control file described in the following table.
Table 4-6 Logging Parameters
| Parameter | Accepted Value | Description |
|---|---|---|
| LOGGERX_MSGID01 | NO or YES,IDMV602E,X |
If you want to suppress the IDMV602E recovery message, then set the value of this parameter to NO. If you want to display the IDMV602E recovery message, then set the value of the parameter to YES in the following format: YES,IDMV602E,X In this format, replace X with any number between 0 through 99, which specifies the number of times the recovery message IDMV602E must be displayed. For example, YES,IDMV602E,6. Note: This parameter is applicable only to the <HLQ>.VOYAGER.CONTROL.LOG file. |
| LOGGERX_SYSOUT_CLASS | A through Z |
The value in this parameter determines the class where the SYSOUT messages must be rolled to. For example, if you set the value of this parameter to A, then all SYSOUT messages will be directed to class A. If you do not specify a value for this parameter, then by default, all SYSOUT messages are rolled to class A. |
| LOGGERX_LEVEL_ROUTING |
MSG_TYPE:DEVICE In this format, replace:
|
This parameter controls the message logging based on message type. The value of this parameter must contain the message type and the devices on which it is to be printed. For example, if you set the value of this parameter to INFO:SYSOUT|CONSOLE, then it means that all Informational messages will be written on to SPOOL/SYSOUT and the mainframe operator console. The same is applicable for message types – WARN(Warning), EROR(Error) and DEBG(DEBUGOUT). |
| LOGGERX_XXXX where XXXX can be either INFO, WARN, EROR, DEBG, AUDT, or PARM | SYSOUT | Use this parameter to specify SYSOUT when the value of DEVICE in the LOGGERX_LEVEL_ROUTING parameter is FILE.
When the value is passed as SYSOUT, the file is created in the SPOOL as part of job output. For example, consider that the value of the LOGGERX_LEVEL_ROUTING parameter is set to WARN:FILE. In such a case, the entry LOGFILE_WARN=SYSOUT means that the job output will contain a file by the name WARNOUT that will contain warning messages. |
| LOGGERX_MSG_ROUTING | MSGID:DEVICE
In this format, replace:
|
Use this parameter to redirect messages to a different device or suppress individual message based on message IDs. This parameter overrides the message levels set in the LOGGERX_LEVEL_ROUTING parameter. For example, the entries LOGGERX_MSG_ROUTING=IDFRPI001:NONE and LOGGERX_MSG_ROUTING=IDFRPI002:FILE combined with LOGGERX_LEVEL_ROUTING=INFO:CONSOLE mean that all Informational messages will go out on CONSOLE except, IDFRPI001(suppressed) and IDFRPI002(written on a file). You can provide 999 message IDs for each agent. In other words, you can choose to override, suppress, or redirect any number of messages. For a comprehensive list of message IDs and the corresponding message text, see Pioneer and Voyager Messages. |
| LOGGERX_FILE_MSG | SYSOUT |
This parameter is used when FILE is specified as the Device type in the LOGGERX_MSG_ROUTING parameter to route all message ID- specific messages to MSGOUT in the spool. This parameter accepts a value of SYSOUT. When the value is passed as SYSOUT, the file is (MSGOUT) created in the SPOOL as part of job output. For example, the entry LOGFILE_MSG=SYSOUT means that the job output will contain a file by the name MSGOUT that contains messages corresponding to the message ID provided in the value of the LOGGERX_MSG_ROUTING parameter with the destination device as FILE. |
| LOGGERX_DEBUG | Y or N |
This parameter is deprecated in v6.0.0 and later versions of the Mainframe agents. |
| LOGGERX_SPIN_CLASS | X |
This parameter is deprecated in v6.0.0 and later versions of the Mainframe agents. |
| LOGGERX_AUDIT_LOG | YES or NO |
This parameter is deprecated in v6.0.0 and later versions of the Mainframe agents. |
| LOGGERX_CONNECT_MSGS | Y or N |
This parameter is deprecated in v6.0.0 and later versions of the Mainframe agents. |
Important Use Case of the Log File
LOGGERX_LEVEL_ROUTING=INFO:FILE
The above combination results in all INFO, AUDT, WARN, ERR, and DBG messages written onto INFOOUT, AUDOUT, WARNOUT, ERROROUT and DEBUGOUT, respectively, in spool/Sysout.
The above combination results in all INFO, AUDT, WARN, ERR, DBG messages written onto INFOOUT, AUDOUT, WARNOUT, ERROROUT, and DEBUGOUT, respectively, in spool and all the messages will also be written onto SYSOUT file in job output.
LOGGERX_LEVEL_ROUTING=INFO:FILE|SYSOUT|CONSOLE
The above combination results in all INFO, AUDT, WARN, ERR, and DBG messages written onto INFOOUT, AUDOUT, WARNOUT, ERROROUT and DEBUGOUT, respectively, in spool and all the messages will also be written onto SYSOUT file in job output and on the mainframe operator console.
LOGGERX_LEVEL_ROUTING=INFO:NONE|SYSOUT|CONSOLE
The above combinations results in all INFO, AUDT, WARN, ERR, and DBG messages being suppressed. Since NONE is specified it does not matter if other devices are specified too, the messages will be suppressed. However, as LOGGERX_MSG_ROUTING is also specified, the messages IDs IDMP000I, IDMP010I, IDMP300I, and IDMP001E are not suppressed and are displayed on the CONSOLE. This establishes that at any point of time, the LOGGERX_MSG_ROUTING parameter has a higher priority in deciding the message’s output device, than its corresponding LEVEL ROUTING
Note:
In the sample control log files, for Parm message output, logging is routed based on message IDs IDMP400I, IDMP401E, and IDMV400I. These are set to route to 'SYSOUT' device and needs to maintain to get the PARMOUT dataset created in SPOOL.Learn about working with custom reconciliation exit routines.
Note:
If you have made changes to the standard TSSINSTX exit routine provided by CA Top Secret, then you must perform the procedure described in this topic. Skip this topic if you are using the default TSSINSTX exit.You can customize the default TSSINSTX exit to meet any special requirements in your environment.
The <HLQ>.JCLLIB dataset includes several sample files such as a sample reconciliation exit (TSSINSTX) and a custom exit (CUSTINSX). Use the CUSTINSX file to include your custom logic for the reconciliation exit. Use the sample reconciliation exit (TSSINSTX) to call the CUSTINSX file that includes your custom logic.
The source in the sample reconciliation exit (TSSINSTX) includes a call to IDMWORKS' modified version of TSSINSTX (IDFINSTX) in EXIT0 (before exiting from the TSSINSTX exit).
The following is the sample source as seen under the label 'EXIT0':
* IDMWORKS Modification to call Real-time exit * Starts at Label EXIT0 for 9 lines * EXIT0 DS 0H COMMON EXIT POINT *** CODE BELOW ADDED TO CALL IDFINSTX (IDMWORKS' TSSINSTX) *** SLR R15,R15 LR R1,R9 COPY PARMLIST ADDR TO R1 LR R11,R13 COPY WORKAREA ADDR TO R11 LA R13,WORKAREA L R15,=V(IDFINSTX) LOAD ADDR OF CUSTOMER EXIT BALR R14,R15 CALL IT LR R13,R11 *** CODE ABOVE ADDED TO CALL IDFINSTX (IDMWORKS' TSSINSTX) ***
In addition, the sample reconciliation exit (TSSINSTX) source contains the label CUSTEXIT, which calls the module CUSTINSX (your custom version of TSSINSTX). The call part of the sample code is commented by specifying * in column 1 on each row as shown below:
*** CODE BELOW ADDED TO CALL CUSTOMER'S MODIFIED EXIT *** **** UNCOMMENT BELOW CODE TO CALL CUSTOMIZED EXIT(CUSTINSX) **** *CUSTEXIT DS 0H * LR R1,R9 * LR R11,R13 * LA R13,WORKAREA * L R15,=V(CUSTINSX) * BALR R14,R15 * LR R13,R11 * B EXIT0 **** UNCOMMENT ABOVE CODE TO CALL CUSTOMIZED EXIT(CUSTINSX) **** *** CODE ABOVE ADDED TO CALL CUSTOMER'S MODIFIED EXIT ***
Uncomment the code to update it as per your requirements.
To make use of real-time reconciliation and the reconciliation agent, you must activate system exits for capturing and reacting to changes in the target system.
Real-time reconciliation requires the activation of the TSSINSTX exit. The TSSINSTX exit captures commands passively and then passes them to a caching module.
<HLQ>.LINKLIB dataset into the CA Top Secret loadlib, usually CAI.CAKOLINK, that is available in the installation Linklist.F TSS,EXIT(ON) command and wait for the OKAY response to be displayed.Both provisioning and reconciliation agents have an operator interface, and you can control the agents by passing commands through the interface.
Pass the Pioneer provisioning agent commands through the operator interface to control Pioneer.
Table 4-7 Provisioning Agent Commands
| Command | Description |
|---|---|
T PROG=ID |
APF authorizes <HLQ>.LINKLIB - required to start the agent. |
S PIONEER |
Starts the agent. |
F PIONEER,SHUTDOWN |
Shuts down the agent. |
F PIONEER,STATUS |
Sends a status request to the agent. |
F PIONEER,DEBUG=Y |
Enables debug-level (detailed) log output. |
F PIONEER,DEBUG=N |
Disables debug-level (detailed) log output. |
Note:
This interface through the z/OS modify command is a single-threaded system. Commands are queued and may take a few seconds before the agent acknowledges them.Pass the Voyager reconciliation agent through the operator interface to control Voyager.
Table 4-8 Reconciliation Agent Commands
| Command | Description |
|---|---|
T PROG=ID |
APF authorizes <HLQ>.LINKLIB - required to start the agent. |
S STARTUP |
Allocates the subpool used to store reconciliation events - required for real-time reconciliation. |
F TSS,EXIT(ON) |
Activates system exits - required for real-time reconciliation as described in Activating Reconciliation Exits. |
S VOYAGER |
Starts the agent. |
F VOYAGER,SHUTDOWN |
Shuts down the agent. |
F VOYAGER,STATUS |
Sends a status request to the agent. |
F VOYAGER,DEBUG=Y |
Enables debug-level (detailed) log output. |
F VOYAGER,DEBUG=N |
Disables debug-level (detailed) log output. |
F VOYAGER,IPAD=999.999.999.999,PORT=9999 |
Changes the IP address and port of the target LDAP Gateway. |
Note:
The interface through the z/OS modify command is a single-threaded system. Commands are queued and take a few seconds before the agent acknowledges them.