Installing and Configuring the Agents of the IBM RACF Connector on the Mainframe

4 Installing and Configuring the Agents of the IBM RACF Connector on the Mainframe

Install the Provisioning Agent - Pioneer and Reconciliation Agent - Voyager of the IBM RACF connector on the mainframe. These agents communicate with the LDAP Gateway during connector operations.

4.1 Installation Requirements for Agents

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 Requirements

Item	Requirement
Operating System	IBM z/OS 2.5 and 3.1
Message Transport Layer	TCP/IP
IBM RACF Advanced 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.	IBM RACF Advanced-authorized user account with System Administrators privileges.

Note:

Both the Voyager and Pioneer Agents must have IBM RACF ACIDs defined on the IBM RACF 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:

ALL31(ON)
HEAP(32768,32768,ANYWHERE,KEEP,8192,4096)
STACK(131072,131072,ANYWHERE,KEEP,524288,524288)

Environmental Settings and Other Requirements

Ensure that the following requirements are met on the mainframe:

A subpool is created to contain reconciliation changes for Voyager to access and send to the LDAP gateway. The subpool is located in the ECSA Subpool 231. The Subpool size is governed by the parameter passed by Voyager using the parameter SUBPOOL_SIZE=. This parameter accepts values in the range of 0200K to 7500K. The number of messages stored is based on the amount of SUBPOOL allocated. For example, an allocation of 0200K will yield 2048 – 100 byte messages,and an allocation of 7500K will yield 76800 – 100 byte messages. It is generally a temporary staging area for reconciliation requests and if there is an outage, Voyager saves the subpool to a //CACHESAV disk file in the Voyager STC. When Voyager is restarted and the subpool is rebuilt, the CACHESAV file is reloaded into the subpool. Once the LDAP connects, the subpool data is sent to the LDAP.
It is recommended that an automation product be used to intercept messages from Voyager to indicate that the LDAP is unavailable. This facilitates correct action to ensure a safe shutdown of Voyager.
Both Pioneer and Voyager require LE runtime options to be set as listed below. IBM defaults are without an existing CEEPRM member in the 'SYS1.PARMLIB'.
- ALL31(ON) - This is the default provided by IBM. ALL31 specifies whether an application can run entirely in AMODE 31 or the application has one or more AMODE 24 routines.
- ANYHEAP(16K,8K,ANYWHERE,FREE) - This is the default provided by IBM.
- HEAP(32K,32K,ANYWHERE,KEEP,8K,4K) - This is the default provided by IBM.
- STACK(128K,128K,ANYWHERE,KEEP,512K,128K) - This is the default but we need more STACKStorage so we use STACK(128K,128K,ANYWHERE,KEEP,512K,512K).
To temporarily override the LE runtime options only for Pioneer and Voyager STC (Started Task), add a //CEEOPTS DD * in both STCs and add the above options. These options are only in effect during the duration of the STC. After the STCs shutdown, the LE runtime options overridden go back to the normal IBM defaults.

Verify if the permanent environment has the following options:

All31(ON)
ANYHEAP(16384,8192,ANYWHERE,FREE)
HEAP(32768,32768,ANYWHERE,KEEP,8192,4096)
STACK(131072,131072,ANYWHERE,KEEP,524288,524288)

If the permanent environment does not have the preceding options, you can temporarily override by using the following:

//PIONEER  PROC HLQ=++hlq++,STEPLIB=++linklib++,
//             REXXLIB=++rexxlib++
.....
//PIONEER  EXEC PGM=PIONEERX,PARM='/RPTSTG(ON),RPTOPTS(ON)',
//         REGION=0M,TIME=1440
.....
//CEEOPTS  DD  *
All31(ON)
ANYHEAP(16384,8192,ANYWHERE,FREE)
HEAP(32768,32768,ANYWHERE,KEEP,8192,4096)
STACK(131072,131072,ANYWHERE,KEEP,524288,524288)

You can use a normal non-privileged RACF user ID for Pioneer and Voyager.
A RACF group containing the SPECIAL attribute RACF userids is recommended.
A RACF facility class is required for usage with the SPECIAL attribute.
A RACF userid with SPECIAL must be created for Pioneer to issue commands to RACF.
Pioneer plays the role of a central site administrator and performs all the related tasks. Voyager collects the RACF event data by using 3 modified RACF passive exits such as ICHPWX01, ICHRIX02, and IRREVX01. There are no changes in the RACF storage or system storage due to these exits.
The exits ICHPWX01 and ICHRIX02 reside in a load library and must be in the Linked Pack Area (LPA). However, the IRREVX01 exit must not reside in the LPA.

The RACF command exit IRREVX01 must not reside in the LPA as recommended by IBM. Otherwise, an S0C4 abend will occur. The exits ICHPWX01 and ICHRIX02 both internal cache RACF IDs and passwords and the caching routine adds them to the subpool created by STARTUP. If the exits are enabled and the subpool is not available, then a message indicating that the subpool is not available is displayed and the messages are lost.

The exit IRREVX01 caches RACF commands and calls an external caching routine called LOGCACHE. You can dynamically activate IRREVX01 using the z/OS command T PROG=75 to activate the IRREVX01 command exit. To deactivate or remove the IRREVX01 exit, issue the z/OS command T PROG=76.

Each cache message is 100 bytes long. When Voyager connects to the LDAP gateway, Voyager polls cache and reads all the messages up to a maximum size of the subpool. At this point the cache is empty. Once installed, you must IPL the z/OS to bring in the ICHPWX01 and ICHRIX02 exits.

You can dynamically activate the IRREVX01 exit by using the z/OS command T PROG=75. To deactivate or remove the IRREVX01 exit, issue the z/OS command T PROG=76. Once activated, all RACF commands are cached.

Note:
It is mandatory for Voyager to have RACF permissions to issue an IRR.RADMIN.LISTUSER call through the RACF API service. This call is issued through the IRRSEQ00 module of IBM. This is the only required permission in addition to the PERMIT for the CACHESAV file that Voyager reads and writes while it is active.

4.2 Installing the Mainframe Agents

The IBM RACF Advanced connector is shipped with a pair of agents, one for the provisioning (Pioneer) and one for real-time reconciliation (Voyager). If real-time reconciliation is not required, then install and start only the provisioning agent.

Note:

If the mainframe agents are already installed, and you are planning to install a new version, then take a back-up of the following files:

<HLQ>.pioneer.control.file
<HLQ>.voyager.control.file

When you install a new version, both the control files are set to default settings. You can restore the contents of the control files from the back-up copies.

On the computer hosting the mainframe, extract the contents of the RACF-<TIMESTAMP>-<VERSION>.zip file located in the connector installation media.
The following XMIT files are extracted:
- CLISTLIB.XMIT
- JCLLIB.XMIT
- LINKLIB.XMIT
- PARMLIB.XMIT
- PROCLIB.XMIT
Transmit the extracted XMIT files to z/OS by using the following specifications:
- RECFM=FB
- LRECL=80
- BLKSIZE=3120
- DSORG=PS
For example, you can use 3270 or FTP to transfer the files.
The following datasets will exist on z/OS:
- <HLQ>.CLISTLIB.XMIT
- <HLQ>.JCLLIB.XMIT
- <HLQ>.LINKLIB.XMIT
- <HLQ>.PARMLIB.XMIT
- <HLQ>.PROCLIB.XMIT
Note:
In the preceding list, <HLQ> is the high-level-qualifier used when transmitting the files to z/OS.
For each of the XMIT files that have been transmitted, execute the following command at the TSO prompt: TSO RECEIVE INDA('<HLQ>.<FILE>.XMIT') .
When prompted to specify restore parameters, enter DA('<HLQ>.<FILE>') .

For example, if the high-level qualifier is IDF and the file is CLISTLIB.XMIT, then execute the following command:
TSO RECEIVE INDA('IDF.CLISTLIB.XMIT')
When prompted, respond with: DA('IDF.CLISTLIB')
The following datasets will exist on z/OS:
- <HLQ>.CLISTLIB
- <HLQ>.JCLLIB
- <HLQ>.LINKLIB
- <HLQ>.PARMLIB
- <HLQ>.PROCLIB
Note:
In the preceding list, <HLQ> is the high-level-qualifier used when receiving the previously transmitted files.

Edit each of the following installed job streams to replace any placeholders in them with actual values.

<HLQ>.CLISTLIB.ENVINFO
<HLQ>.JCLLIB.CREATDSN
<HLQ>.JCLLIB.IEBCOPYL
<HLQ>.JCLLIB.IEBCOPYP
<HLQ>.JCLLIB.IEBCPYPR
<HLQ>.JCLLIB.KEYMODR
<HLQ>.PARMLIB.PROGID

Note:
In the preceding job stream, update the ++vol++ placeholder with the VOLUME from where you have received LINKLIB.
<HLQ>.PROCLIB.PIONEER
<HLQ>.PROCLIB.STARTUP
<HLQ>.PROCLIB.VOYAGER
<HLQ>.PROCLIB.WRAPUP
<HLQ>.JCLLIB.IEBCPYCL
<HLQ>.JCLLIB.LOADDSN
<HLQ>.JCLLIB.RACFDEF
<HLQ>.JCLLIB.RACFDEL
<HLQ>.JCLLIB.RACFRC
<HLQ>.JCLLIB.RACFRCOG
<HLQ>.JCLLIB.RACFRCOU
<HLQ>.JCLLIB.SECUTLD
<HLQ>.JCLLIB.SECUTLE
<HLQ>.JCLLIB.PROG75
<HLQ>.JCLLIB.ASMJCL

Note:

In the preceding list, <HLQ> is the high-level-qualifier used when receiving the previously transmitted files.

The following table lists the installation placeholders found in job streams, their description, and example.

Table 4-2 Installation Placeholders

Placeholder	Description	Example
`++hlq++`	The high-level qualifier where the mainframe agent is to be installed. You must include all the multiple segments, if any.	`IDF.PROD`
`++hlq1++`	The top-most segment of the high-level qualifier where the mainframe agent is to be installed	`IDF`
`++vol++`	The volume where the mainframe agent is to be installed.	`SDWRK1`
`++lpalib++`	The DSN of the data set that contains customized lpalibs. Customize based on the z/OS environment.	`USER.LPALIB`
`++parmdtr++`	The name of the `PARMLIB` XMIT that was trasmitted to z/OS (without the `.XMIT`).	`<HLQ>.PARMLIB`
`++parmlib++`	The DSN of the data set that contains customized parmlibs. Customize based on z/OS environment.	`USER.PARMLIB`
`++procdtr++`	The name of the `PROCLIB` XMIT that was transmitted to z/OS (without the `.XMIT`).	`<HLQ>.PROCLIB`
`++proclib++`	The DSN of the data set that contains customized proclibs. Customize based on z/OS environment.	`USER.PROCLIB`
`++linkdtr++`	The name of the `LINKLIB` XMIT that was trasmitted to z/OS (without the `.XMIT`).	`<HLQ>.LINKLIB`
`++linklib++`	The DSN where the `LINKLIB` XMIT that was received.	`<HLQ>.LINKLIB`
`++rexxdtr++`	The name of the `CLISTLIB` XMIT that was transmitted to z/OS (without the `.XMIT`).	`<HLQ>.CLISTLIB`
`++rexxlib++`	The DSN where the `CLISTLIB` XMIT that was received.	`<HLQ>.CLISTLIB`
`++pionprms++`	The DSN of the control (configuration) file for the provisioning agent.	`PIONEER.CONTROL.FILE`
`++voyprms++`	The DSN of the control (configuration) file for the reconciliation agent.	`VOYAGER.CONTROL.FILE`
`++pionlog++`	The DSN of the control log (configuration) file for the LOGGERX feature of provisioning agent.	`PIONEER.CONTROL.LOG`
`++voyglog++`	The DSN of the control log (configuration) file for the LOGGERX feature of reconciliation agent.	`VOYAGER.CONTROL.LOG`
`++pstcuserid++`	The ACID of the user to be created for running the provisioning agent STC.	`PIONEER`
`++vstcuserid++`	The ACID of the user to be created for running the reconciliation agent STC.	`VOYAGER`
`++pstcnm++`	The name / description for the provisioning agent STC.	`'PIONEER STARTED TASK'`
`++vstcnm++`	The name / description for the reconciliation agent STC.	`'VOYAGER STARTED TASK'`
`++pstcuid++`	The OMVS UID assigned to the provisioning agent STC. Customize based on z/OS environment.	`80`
`++vstcuid++`	The OMVS UID assigned to the reconciliation agent STC. Customize based on z/OS environment.	`90`
`++stcgrp++`	The group assigned to the provisioning and reconciliation agent STCs. Ensure the group has UID(0) or BPX.SUPERUSER assigned. Customize based on z/OS environment.	`OMVSGRP`
`++secgrp++`	The Secure ID user default group.	`IDFSGRP`
`++secuid++`	The Secure ID user ACID.	`IDFAGNT`
`++secidnm++`	The Secure ID name.	`SECURE_ID`
`++cailink++`	The CA Linklist Library DSN. Customize based on RACF environment.	`CAI.CAKOLINK`

For example, in the following snippet from CREATEDSN, replace the placeholders ++hlq++ and ++vol++ with values such as IDF.PROD and SDWRK1:

//*
//S1       SET  PHLQ=++hlq++.PIONEER
//S2       SET  VHLQ=++hlq++.VOYAGER
//S3       SET  PVOL=++vol++
//S4       SET  VVOL=++vol++
//*

The following snippet displays the placeholders replaced with values:

//*
//S1       SET  PHLQ=IDF.PROD.PIONEER
//S2       SET  VHLQ=IDF.PROD.VOYAGER
//S3       SET  PVOL=SDWRK1
//S4       SET  VVOL=SDWRK1
//S5       SET THLQ=IDF.PROD
//*

Execute each of the following job streams in the order as shown in the following table to complete installation.

Table 4-3 Job Streams to Execute

Job Stream	Description
`<HLQ>.JCLLIB.IEBCOPYP`	Copies PARMLIB members to user PARMLIB.
`<HLQ>.JCLLIB.IEBCPYPR`	Copies PROCLIB members to user PROCLIB.
`<HLQ>.JCLLIB.IEBCPYCL`	Copies Rexx execs to user Rexx library.
`<HLQ>.JCLLIB.IEBCOPYL`	Copies exit routines to use LPA library.
`<HLQ>.JCLLIB.CREATDSN`	Allocates run time data sets, deleting the data sets first if they already exist.
`<HLQ>.JCLLIB.LOADDSN`	Copies PIONEER & VOYAGER configuration (control) files.
`<HLQ>.JCLLIB.RACFDEL`	Deletes pre-existing user accounts and privileges on the user accounts required to execute agent STCs.
`<HLQ>.JCLLIB.RACFDEF`	Defines users and permissions required to run the mainframe agent STCs.

The installation of the provisioning and reconciliation agents, Pioneer and Voyager, is complete. At this point, you can optionally remove the XMIT datasets that were originally transmitted to z/OS.

4.3 Configuring the Mainframe Agents

After installing Pioneer and Voyager, you must configure the mainframe agents to receive requests from and send responses to the LDAP gateway.

This section discusses the following topics:

4.3.1 Configuring the Provisioning Agent

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 using the IDCAMS JCL (from INJCLR DD) submission to the internal reader. If you set it to `F`, then all LDAP Alias requests are processed internally by the Pioneer Agent. Note: With MF Agent version 6.10.0 onwards, the default value for this parameter will be set to `F`, rather than `T`. The Alias process will continue to work as before. If you set the value of this parameter to `T`, then Alias processing will be performed using IDCAMS JCL present in the dataset referenced by Pioneer DD INJCLR.
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)	Controls how long the agent waits for the execution of the IDCAMS job (submitted for Alias.processing).
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=nnnnn`	If you do not want to monitor user or group imports, then set the value of this parameter to `NO`. Set the value of this parameter to `YES` in the following format if you want to monitor user or group imports displaying a message every nnnnn records: `YES,REC=nnnnn` In this format, ensure that you replace nnnnn with a 5-digit format. For example, to monitor progress for every 5000 records, set the value of this parameter to `YES,REC=05000`
IP	`V4` or `V6`	IP version to be used for communication between LDAP gateway and PIONEER agent. Value `V4` would be used as an IPv4 based IP address or hostname for communication. (e.g. In tops.properties value for host=192.168.100.0) Value `V6` would be used as an IPv6 based IP address or hostname for communication. (e.g. In tops.properties value for host=FE80::A0:A001:A0:A0A0%tap0) Default value is `V4`, when not specified in `<HLQ>.PIONEER.CONTROL.FILE`.
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.

4.3.2 Configuring the Reconciliation Agent

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.

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.
IP	`V4` or `V6`	IP version to be used for communication between LDAP gateway and VOYAGER agent. Value `V4` would be used as an IPv4 based IP address or hostname for communication. (e.g. IPAD entry in `VOYAGER.CONTROL.FILE` = 192.168.100.10) Value `V6` would be used as an IPv6 based IP address or hostname for communication. (e.g. IPAD entry in `VOYAGER.CONTROL.FILE` = fe80::74c3:eeff:fe1e:60fd)
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.

4.4 Configuring Logging

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: MSG_TYPE with types of messages such as `INFO`, `WARN`, `ERR`, or `DBG`. DEVICE with any combination of `SYSOUT`, `CONSOLE`, `FILE`, or `NONE` by using a vertical bar (`\|`) as the delimiter.	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: MSGID with the message ID corresponding to a message text. DEVICE with any combination of `SYSOUT`, `CONSOLE`, `FILE`, or `NONE` by using the vertical bar (`\|`) as the delimiter.	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 Messages 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
- LOGGERX_LEVEL_ROUTING=AUDT:FILE
- LOGGERX_LEVEL_ROUTING=WARN:FILE
- LOGGERX_LEVEL_ROUTING=ERR:FILE
- LOGGERX_LEVEL_ROUTING=DBG:FILE
- LOGGGERX_FILE_WARN=SYSOUT
- LOGGGERX_FILE_INFO=SYSOUT
- LOGGGERX_FILE_AUDT=SYSOUT
- LOGGGERX_FILE_DEBG=SYSOUT
- LOGGGERX_FILE_EROR=SYSOUT
The above combination results in all INFO, AUDT, WARN, ERR, and DBG messages written onto INFOUT, WARNOUT, ERROUT, and DBGOUT in spool/Sysout.
LOGGERX_LEVEL_ROUTING=INFO:FILE|SYSOUT
- LOGGERX_LEVEL_ROUTING=AUDT:FILE|SYSOUT
- LOGGERX_LEVEL_ROUTING=WARN:FILE|SYSOUT
- LOGGERX_LEVEL_ROUTING=ERR:FILE|SYSOUT
- LOGGERX_LEVEL_ROUTING=DBG:FILE|SYSOUT
- LOGGGERX_FILE_WARN=SYSOUT
- LOGGGERX_FILE_INFO= SYSOUT
- LOGGGERX_FILE_AUDT=SYSOUT
- LOGGGERX_FILE_DEBG= SYSOUT
- LOGGGERX_FILE_EROR= SYSOUT
The above combination results in all INFO, AUDT, WARN, ERR, DBG messages written onto INFOUT, WARNOUT, ERROUT, and DBGOUT in spool and all the messages will also be written onto SYSOUT file in job output.
LOGGERX_LEVEL_ROUTING=INFO:FILE|SYSOUT|CONSOLE
- LOGGERX_LEVEL_ROUTING=AUDT:FILE|SYSOUT|CONSOLE
- LOGGERX_LEVEL_ROUTING=WARN:FILE|SYSOUT|CONSOLE
- LOGGERX_LEVEL_ROUTING=ERR:FILE|SYSOUT|CONSOLE
- LOGGERX_LEVEL_ROUTING=DBG:FILE|SYSOUT|CONSOLE
- LOGGGERX_FILE_WARN=SYSOUT
- LOGGGERX_FILE_INFO= SYSOUT
- LOGGGERX_FILE_AUDT= SYSOUT
- LOGGGERX_FILE_DEBG= SYSOUT
- LOGGGERX_FILE_EROR= SYSOUT
The above combination results in all INFO, AUDT, WARN, ERR, and DBG messages written onto INFOUT, WARNOUT, ERROUT, and DBGOUT 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
- LOGGERX_LEVEL_ROUTING=AUDT:NONE
- LOGGERX_LEVEL_ROUTING=WARN:NONE|SYSOUT|CONSOLE
- LOGGERX_LEVEL_ROUTING=ERR:NONE|SYSOUT|CONSOLE
- LOGGERX_LEVEL_ROUTING=DBG:NONE|SYSOUT|CONSOLE
- LOGGGERX_FILE_WARN=SYSOUT
- LOGGGERX_FILE_INFO= SYSOUT
- LOGGGERX_FILE_AUDT=SYSOUT
- LOGGGERX_FILE_DEBG= SYSOUT
- LOGGGERX_FILE_EROR= SYSOUT
- LOGGERX_MSG_ROUTING=IDMP000I :CONSOLE
- LOGGERX_MSG_ROUTING=IDMP010I :CONSOLE
- LOGGERX_MSG_ROUTING=IDMP300I :CONSOLE
- LOGGERX_MSG_ROUTING=IDMP001E: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.

4.5 Customizing the Reconciliation Exit

You can customize the default IRREVX01 exit to meet any special requirements in your environment.

Note:

Perform the procedure described in this section only if you use a custom RACF command exit (IRREVX01).

The IRREVX01 exit is invoked each time a RACF command is executed and the specific data from the command is written to subpool 231. This data is used during reconciliation. This connector lets you use the default reconciliation exit (IRREVX01) that is shipped with the connector installation package as well as any custom command exit that you may have created in your environment.

This connector is shipped with two sample modules namely IRREVX1I and CUSTINSX that are available in the <HLQ>.JCLLIB library. The CUSTINSX module is a sample source that also includes Write-to-operator (WTO) statements to test the execution flow. Include any site-specific changes or customization in the CUSTINSX module. The IRREVX1I source module is a sample driver module source that includes a call to IDFINSTX, which is IDMWORKS's modified logic and a commented call to the CUSTINSX module. Use the sample IRREVX1I module to call the CUSTINSX module that includes your custom logic. Then, activate the IRREVX01 exit to add the IRREVX1I load module dynamically to the IRREVX01 exit point.

To call a custom exit module:

Open the IRREVX1I member module, located in the <HLQ>.JCLLIB library, for editing.

Delete the * symbol from column 1 to uncomment the statements to call the CUSTINSX module as shown in the code snippet below:

*---------------------------------------------------------------------*
UNCOMMENT BELOW COMMENTED BLOCK TO CALL CUSTOMER MODIFIED IRREVX01
REFER TO PDF ADMIN GUIDE (Documentation) BEFORE MAKING CHANGE
*---------------------------------------------------------------------*
L R15,=V(CUSTINSX) LOAD CUSTOMER IRREVX01 ENTRY POINT ADDR
BASR R14,R15 INVOKE CUSTOMER IRREVX01
*---------------------------------------------------------------------*
UNCOMMENT ABOVE COMMENTED BLOCK TO CALL CUSTOMER MODIFIED IRREVX01
*---------------------------------------------------------------------*

Save the file.
Refer to the sample CUSTINSX module source supplied in the <HLQ>.JCLLIB library, and then add your custom code within the same CUSTINSX module. Ensure to remove the default WTO statements (included to track the execution flow) in the CUSTINSX module to avoid flooding the system log with messages.
Assemble and link-edit the CUSTINSX module and the IRREVX1I driver-source module by using the ASMJCL job that is supplied in the <HLQ>.JCLLIB library. Change placeholders such as ++linklib++ and ++hlq++ with the site-specific load library and source dataset high-level qualifier, respectively and then submit the job. Ensure that the job completes with MAX-CC of 0 or 4.
Check for and delete any dynamic module (such as IRREVX1I or LOGEVX01) that might already exist at the IRREVX01 exit point as follows:

Note:

From LDAP Gateway version 6.3.1 onward, the name of the exit module provided by IDMWORKS has been changed from LOGEVX01 to IRREVX01. If you have upgraded to LDAP Gateway version 6.3.1 or later versions, then you must ensure to delete the LOGEVX01 module from the dynamic exit point. The procedure to delete the LOGEVX01 module is described later in this topic.
1. Run the following command to check whether the IRREVX1I or LOGEVX01 module already exists at the IRREVX01 exit point:
```
/D PROG,EXIT,EXITNAME=IRREVX01
```
2. If the IRREVX1I module exists, then delete it by using the PROG76 PARMLIB member. Run the following command from the z/OS operator interface:
```
/T PROG=76
```
3. If the LOGEVX01 module exists, then delete it by updating the PROG76 parmlib member to specify the module as LOGEVX01 as shown below:
```
EXIT,DELETE,EXITNAME=IRREVX01,MODNAME=LOGEVX01
```
  Then, issue the /T PROG=76 operator command.
Add the updated IRREVX1I load module (assembled and integrated with the CUSTINSX module) dynamically to the IRREVX01 exit point by using the PROG75 PARMLIB member. To do so, you must activate the IRREVX01 exit as described in Activating and Deactivating Reconciliation Exits.

4.6 Activating and Deactivating Reconciliation Exits

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.

Activate the system exits to capture target system changes in real-time. To do so, run the following command from the z/OS operator interface:

T prog=75

When you run this command, the IRREV1I load module that is supplied with the connector is dynamically added to the IRREVX01 exit point using the PROG75 PARMLIB member that supplied with the <HLQ>.PARMLIB library.

Deactivate the system exits to disable the reconciliation of real-time changes to the target system. To do so, run the following command from the z/OS operator interface:

T prog=76

4.7 Operator Interface for Mainframe Agents

Both provisioning and reconciliation agents have an operator interface, and you can control the agents by passing commands through the interface.

The following topics are discussed in this section:

4.7.1 Provisioning Agent Commands

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.

4.7.2 Reconciliation Agent Commands

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.
`T PROG=75`	Activates system exits - required for real-time reconciliation as described in Activating and Deactivating 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.