Maintenance
Ongoing Administration and Monitoring
The AUDIT log
When an AUDIT DD statement is present in the Mainframe Connector startup procedure, additional information related to password change requests is generated. The audit log is useful for monitoring the results of all password change requests sent to a Bravura Pass server.
The AUDIT DD can specify either a target dataset or a JES SYSOUT dataset. The attributes of an AUDIT dataset must be sequential with a record length of 133 characters.
When this dataset is filled, the following message is displayed on the operator console and the Mainframe Connector AUDIT feature is disabled.
PSYNC551I -- AUDIT DATASET IS FULL. LOGGING HAS BEEN DISABLED.
Allocating a larger dataset for a subsequent startup of Mainframe Connector is one method of capturing data for a longer period. Another method is to regularly copy the log to a backup and clear the log thus keeping a history of log data over time.
You can disable the AUDIT feature by removing the DD statement entirely or by specifying a DD DUMMY statement in the startup procedure.
The example below shows a sample of the type of data written to the audit log.
2000 050 13:21:42.19 MTCJDL1 UPDATEOK 2000 050 13:40:29.10 MTCRDR1 TIMEOUT 2000 050 14:22:10.45 MTCSKG1 UPDATEFAIL 2000 050 15:45:20.32 MTCJDL1 CONNECTFAIL 2000 050 17:12:36.56 MTCRDR2 UNKNOWN
The fields in the Mainframe Connector audit log are described below:
Date
The julian date of the password change request.
Time
The time of the password change request.
Userid
The userid of the user for which the password change request is being made.
Result
The condition which resulted from a password change request. Possible values and their descriptions follow:
UPDATEOK indicates that the request went to and returned from the Bravura Pass server and that the password was deemed acceptable. The local password will be reset.
UPDATEFAIL indicates that the request went to and returned from the Bravura Pass server and that the password was deemed unacceptable. The local password will NOT be reset.
TIMEOUT indicates that the request reached the configurable timeout value before a response was received from the Bravura Pass server. The local password reset event continues.
TIMEOUT1 indicates that the request timed out waiting for the Mainframe Connector subsystem to respond to the subsystem interface request. The local password reset event continues.
TIMEOUT2 indicates that the request reached the configurable timeout value while waiting in the subsystem interface request module for a response from the Bravura Pass server. The local password reset event continues.
CONNECTFAIL indicates that a network connection error condition occurred during the request. The local password reset event continues.
UNKNOWN indicates an unknown error condition. The local password reset event continues.
BYPASS indicates that the LISTCHECK parameter value is set to either INOUT or OUTBOUNDONLY and the userid for which the current password change request is being made has been rejected by the current INLIST or EXLIST list. The local password reset event continues.
The SYNCHLOG log
When a SYNCHLOG DD statement is present in the Mainframe Connector startup procedure, additional information related to inbound requests is generated. The synchlog log is useful for monitoring the results of all inbound requests that have been sent from a Bravura Pass server.
The SYNCHLOG DD can specify either a target dataset or a JES SYSOUT dataset. The attributes of a SYNCHLOG dataset must be sequential with a record length of 133 characters.
When this dataset is filled, the following message is displayed on the operator console and the Mainframe Connector SYNCHLOG feature is disabled.
PSYNC553I - SYNCHLOG DATASET IS FULL. LOGGING HAS BEEN DISABLED.
Allocating a larger dataset for a subsequent startup of Mainframe Connector is one method of capturing data for a longer period. Another method is to regularly copy the log to a backup and clear the log thus keeping a history of log data over time.
You can disable the SYNCHLOG feature by removing the DD statement entirely or by specifying a DD DUMMY statement in the startup procedure.
Mainframe Connector SMF records
If you specify an SMFREC parameter in the PARMLIB dataset for Mainframe Connector startup, Mainframe Connector will capture z/OS SMF records for Mainframe Connector events. The following are the Mainframe Connector events that will be captured for SMF recording:
Locally initiated password change successful
Locally initiated password change rejected by the Bravura Pass server
Locally initiated password change timed out waiting for a response from the Bravura Pass server. The password change is allowed to continue.
Locally initiated password change experienced a network connection failure. The password change is allowed to continue.
Locally initiated password change experienced an unknown failure. The password change is allowed to continue.
A Bravura Pass server initiated password VERIFY is successful
A Bravura Pass server initiated password CHANGE is successful
A Bravura Pass server initiated password RESET is successful
A Bravura Security Fabric server initiated USERPOLL is successful
A Bravura Pass server initiated RESETEXPIRE is successful
A Bravura Security Fabric server initiated EXPIRE is successful
A Bravura Security Fabric server initiated ENABLE is successful
A Bravura Security Fabric server initiated DISABLE is successful
A Bravura Security Fabric server initiated revoke status check occurred
An Bravura Identity server initiated userid CREATE is successful
An Bravura Identity server initiated userid DELETE is successful
An Bravura Identity server initiated LISTGROUP is successful
An Bravura Identity server initiated LISTMEMBERS is successful
An Bravura Identity server initiated userid group add is successful
An Bravura Identity server initiated userid group delete is successful
An Bravura Identity server initiated userid attribute update is successful
An Bravura Identity server initiated userid attribute extract is successful
A Bravura Pass server initiated password phrase RESET is successful
A Bravura Pass server initiated password phrase RESETEXPIRE is successful
An Bravura Identity server initiated resource userid/groupid access update is successful
See SMF Record Mapping for details regarding the SMF record mapping for Mainframe Connector SMF records.
Mainframe Connector Operator Commands
Stopping the Mainframe Connector subsystem
The STOP command is used to end Mainframe Connector processing on a system. This is an MVS system command and is entered at a console. The form of the STOP command is:
STOP mfc P mfc
where mfc specifies the name of your Mainframe Connector catalogued procedure used at startup.
Mainframe Connector issues the following message upon successful termination.
PSYNC041I - MAINFRAME CONNECTOR TERMINATED
If the Mainframe Connector listener was processing any operations when the stop request was made, the termination process may require some time to allow for the completion or graceful termination of the active operations.
Displaying the Mainframe Connector subsystem parameter status
While Mainframe Connector is up and running, the active parameter values can be displayed at an MVS console using the MVS MODIFY command.
See the detailed explanation of the display listing under message PSYNC934I .
Syntax:
MODIFY mfc,DISPLAY=PARMS MODIFY mfc,D=PARMS F mfc,DISPLAY=PARMS F mfc,D=PARMS
mfc is the Mainframe Connector started task name.
Modifying the LISTCHECK value
The MODIFY command can be used to dynamically change the LISTCHECK value.
Syntax:
MODIFY mfc,LISTCHECK=(INOUT/INBOUNDONLY/OUTBOUNDONLY) F mfc,LISTCHECK=(INOUT/INBOUNDONLY/OUTBOUNDONLY)
Specifying LISTCHECK=INOUT will cause include or exclude list checking to occur for both inbound and outbound password reset events. Specifying LISTCHECK=INBOUNDONLY will cause include or exclude list checking to occur for only inbound password reset events. Specifying LISTCHECK=OUTBOUNDONLY will cause include or exclude list checking to occur for only outbound password reset events.
Modifying the LISTENONLY value
The MODIFY command can be used to dynamically change the LISTENONLY value.
Syntax:
MODIFY mfc,LISTENONLY=(YES/NO) F mfc,LISTENONLY=(YES/NO)
Specifying LISTENONLY=YES will prevent Mainframe Connector from forwarding password change information to the Bravura Pass server for validation and synchronization.
Modifying the LISTENMAX value
The MODIFY command can be used to dynamically change the LISTENMAX value.
Syntax:
MODIFY mfc,LISTENMAX=nn F mfc,LISTENMAX=nn
Where nn represents the new LISTENMAX value in the range 1 – 99.
Modifying the TIMEOUT value
The MODIFY command can be used to dynamically change the TIMEOUT value.
Syntax:
MODIFY mfc,TIMEOUT=nnn F mfc,TIMEOUT=nnn
Where nnn represents the new TIMEOUT value in the range 20 – 120.
Modifying the ADMINIDS list
The ADMINIDS DD statement is used to define a dataset(s) that contains a list of userids that will be permitted to have password reset requests that are being made for third party userids (i.e. - not their own) forwarded to the Bravura Pass server for strength validation and synchronization. At Mainframe Connector startup, the contents of the ADMINIDS datasets(s) are copied to an in-storage list which exists, and governs ADMINIDS-related processing, while Mainframe Connector is active.
A number of operator commands are available to dynamically influence the contents of this list and how it is to be interpreted.
Adding a userid to the ADMINIDS list
The MODIFY command can be used to dynamically add a userid to the list of ADMINIDS.
Syntax:
MODIFY mfc ,ADD,ADMINID= userid F mfc ,ADD,ADMINID= userid
Where ’userid’ indicates the administrator userid that should be added to the ADMINIDS list. Optional Run-time parameters describes acceptable syntax for userid.
If ADMINIDS datasets(s) were absent from the Mainframe Connector startup JCL, the first ADD command will dynamically create an in-storage ADMINIDS list as described previously.
Removing a userid from the ADMINIDS list
The MODIFY command can be used to dynamically remove a userid from the list of ADMINIDS.
Syntax:
MODIFY mfc ,DEL,ADMINID= userid F mfc ,DEL,ADMINID= userid
Where ’userid indicates the administrator userid that should be removed from the ADMINIDS list.
If the specified userid is not currently included in the ADMINIDS list, a message is issued and processing continues.
Disabling an active ADMINIDS list
The MODIFY command can be used to dynamically disable an active list of ADMINIDS.
Syntax:
MODIFY mfc ,DEACTIVATE,ADMINIDS F mfc ,DEACTIVATE,ADMINIDS
Using this command will disable administrator-issued password resets from being sent to the Bravura Pass server for validation and synchronization.
If ADMINIDS list processing is not currently active, a message is issued and processing continues.
Enabling a deactivated ADMINIDS list
The MODIFY command can be used to dynamically enable a deactivated list of ADMINIDS.
Syntax:
MODIFY mfc,REACTIVATE,ADMINIDS F mfc ,REACTIVATE,ADMINIDS
Using this command will re-enable administrator-issued password resets being sent to the Bravura Pass server for validation and synchronization. Only resets by those administrator userids in the list will be processed.
If ADMINIDS list processing is already active or did not previously exist, a message is issued and processing continues.
Reloading the ADMINIDS list
The MODIFY command can be used to reload the list of ADMINIDS from the ADMINIDS DD dataset concatenation.
Syntax:
MODIFY mfc ,RELOAD,ADMINIDS F mfc ,RELOAD,ADMINIDS
Using this command causes Mainframe Connector to create a new copy of the ADMINIDS list from the current contents of the datasets in the ADMINIDS DD concatenation. This command permits sites to update their static ADMINIDS datasets and activate the contents of those datasets dynamically. To get the expected results, the ADMINIDS DD concatenation must be kept to a maximum of 32 DD statements.
If no ADMINIDS list processing was active, a message is issued and processing continues.
Note that RELOAD will nullify updates resulting from any prior ADD or DEL commands issued against the ADMINIDS list unless the ADMINIDS dataset(s) are updated as well (eg. - via ISPF EDIT) to reflect the ADD or DEL changes prior to issuance of the RELOAD.
Modifying the INLIST list
The INLIST DD statement is used to define a dataset(s) that contains a list of userids and/or groupids that Mainframe Connector will be permitted to process requests against. At Mainframe Connector startup, the contents of the INLIST datasets(s) are copied to an in-storage list which exists, and governs INLIST-related processing, while Mainframe Connector is active. If outbound requests are being checked (LISTCHECK=INOUT or LISTCHECK=OUTBOUNDONLY), the z/OS based password reset requests will be assessed by Mainframe Connector to determine if the requesting userid is in an active INLIST and if it is, the request will be forwarded to the Bravura Pass server for strength validation and synchronization. If inbound requests are being checked (LISTCHECK=INOUT or LISTCHECK=INBOUNDONLY), Bravura Pass server driven reset, resetexpire, and expire requests will be assessed by Mainframe Connector to determine if the target userid is in an active INLIST and if it is, the request will proceed.
A number of operator commands are available to dynamically influence the contents of this list and how it is to be interpreted.
Adding a userid to the INLIST list
The MODIFY command can be used to dynamically add a userid to the INLIST list.
Syntax:
MODIFY mfc ,ADD,INCLUDEUSER= userid F mfc ,ADD,INCLUDEUSER= userid
Where userid indicates the userid that should be added to the INLIST list. Subsection 7.1.2 describes acceptable syntax for userid.
If INLIST dataset(s) were absent from the Mainframe Connector startup JCL, the first ADD command will dynamically create an in-storage INLIST as described previously. If an EXLIST is already active, the initial status of this INLIST will be deactivated because of the mutual exclusivity of INLIST and EXLIST as described earlier in this guide.
Removing a userid from the INLIST list
The MODIFY command can be used to dynamically remove a userid from the INLIST list.
Syntax:
MODIFY mfc ,DEL,INCLUDEUSER= userid F mfc ,DEL,INCLUDEUSER= userid
Where userid indicates the userid that should be removed from the INLIST list.
If the specified userid is not currently included in the INLIST list or INLIST processing is currently not active, a message is issued and processing continues.
Adding a groupid to the INLIST list
The MODIFY command can be used to dynamically add a groupid to the INLIST list.
Syntax:
MODIFY mfc ,ADD,INCLUDEGROUP= groupid F mfc ,ADD,INCLUDEGROUP= groupid
Where ’groupid’ indicates the groupid that should be added to the INLIST list.
If INLIST dataset(s) were absent from the Mainframe Connector startup JCL, the first ADD command will dynamically create an in-storage INLIST as described previously. If an EXLIST is already active, the initial status of this INLIST will be deactivated because of the mutual exclusivity of INLIST and EXLIST as described earlier in this guide.
Removing a groupid from the INLIST list
The MODIFY command can be used to dynamically remove a groupid from the INLIST list.
Syntax:
MODIFY mfc ,DEL,INCLUDEGROUP= groupid
F mfc ,DEL,INCLUDEGROUP= groupid
Where ’groupid’ indicates the groupid that should be removed from the INLIST list.
If the specified groupid is not currently included in the INLIST list or INLIST processing is currently not active, a message is issued and processing continues.
Disabling an active INLIST list
The MODIFY command can be used to dynamically disable an active INLIST list.
Syntax:
MODIFY mfc ,DEACTIVATE,INLIST F mfc ,DEACTIVATE,INLIST
Using this command will disable INLIST list validation.
If INLIST list processing is not currently active, a message is issued and processing continues.
Enabling a deactivated INLIST list
The MODIFY command can be used to dynamically enable a deactivated INLIST list.
Syntax:
MODIFY mfc ,REACTIVATE,INLIST F mfc ,REACTIVATE,INLIST
Using this command will re-enable INLIST validation.
If INLIST list processing is already active or did not previously exist, a message is issued and processing continues.
If EXLIST list processing is already active, the command will be disallowed and a message issued, because of the mutual exclusivity of INLIST and EXLIST as described earlier in this guide. It will first be necessary to deactivate the EXLIST.
Reloading the INLIST list
The MODIFY command can be used to reload the INLIST list from the INLIST DD dataset concatenation.
Syntax:
MODIFY mfc ,RELOAD,INLIST F mfc ,RELOAD,INLIST
Using this command causes Mainframe Connector to create a new copy of the INLIST list from the current contents of the datasets in the INLIST DD concatenation. This command permits sites to update their static INLIST datasets and activate the contents of those datasets dynamically. To get the expected results, the INLIST DD concatenation must be kept to a maximum of 32 DD statements.
If no INLIST list processing was active, a message is issued and processing continues.
Note that RELOAD will nullify updates resulting from any prior ADD or DEL commands issued against the INLIST list unless the INLIST dataset(s) are updated as well (eg. - via ISPF EDIT) to reflect the ADD or DEL changes prior to issuance of the RELOAD.
Modifying the EXLIST list
The EXLIST DD statement is used to define a dataset(s) that contains a list of userids and/or groupids that Mainframe Connector will be excluded from processing requests against. At Mainframe Connector startup, the contents of the EXLIST datasets(s) are copied to an in-storage list which exists, and governs EXLIST-related processing, while Mainframe Connector is active. If outbound requests are being checked (LISTCHECK=INOUT or LISTCHECK=OUTBOUNDONLY), the z/OS based password reset requests will be assessed by Mainframe Connector to determine if the requesting userid is in an active EXLIST and if it is, the request will not be forwarded to the Bravura Pass server for strength validation and synchronization. If inbound requests are being checked (LISTCHECK=INOUT or LISTCHECK=INBOUNDONLY), Bravura Pass server driven reset, resetexpire, and expire requests will be assessed by Mainframe Connector to determine if the target userid is in an active EXLIST and if it is, the request will not proceed.
A number of operator commands are available to dynamically influence the contents of this list and how it is to be interpreted.
Adding a userid to the EXLIST list
The MODIFY command can be used to dynamically add a userid to the EXLIST list.
Syntax:
MODIFY mfc ,ADD,EXCLUDEUSER= userid F mfc ,ADD,EXCLUDEUSER= userid
Where userid indicates the userid that should be added to the EXLIST list. Optional Run-time parameters describes acceptable syntax for userid.
If EXLIST dataset(s) were absent from the Mainframe Connector startup JCL, or ignored because of the mutual exclusivity of INLIST and EXLIST as described earlier in this guide; the first ADD command will dynamically create an in-storage EXLIST as described previously. If an INLIST is already active, this EXLIST will initially be deactivated because of the aforementioned mutual exclusivity.
Removing a userid from the EXLIST list
The MODIFY command can be used to dynamically remove a userid from the EXLIST list.
Syntax:
MODIFY mfc ,DEL,EXCLUDEUSER= userid F mfc ,DEL,EXCLUDEUSER= userid
Where userid indicates the userid that should be removed from the EXLIST list.
If the specified userid is not currently included in the EXLIST list or EXLIST processing is currently not active, a message is issued and processing continues.
Adding a groupid to the EXLIST list
The MODIFY command can be used to dynamically add a groupid to the EXLIST list.
Syntax:
MODIFY mfc,ADD,EXCLUDEGROUP=groupid F mfc,ADD,EXCLUDEGROUP=groupid
Where groupid indicates the groupid that should be added to the EXLIST list.
If EXLIST dataset(s) were absent from the Mainframe Connector startup JCL, or ignored because of the mutual exclusivity of INLIST and EXLIST as described earlier in this guide; the first ADD command will dynamically create an in-storage EXLIST as described previously. If an INLIST is already active, this EXLIST will initially be deactivated because of the aforementioned mutual exclusivity.
Removing a groupid from the EXLIST list
The MODIFY command can be used to dynamically remove a groupid from the EXLIST list.
Syntax:
MODIFY mfc,ADD,EXCLUDEGROUP= groupid F mfc,ADD,EXCLUDEGROUP= groupid
Where groupid indicates the groupid that should be removed from the EXLIST list.
If the specified groupid is not currently included in the EXLIST list or EXLIST processing is currently not active, a message is issued and processing continues.
Disabling an active EXLIST list
The MODIFY command can be used to dynamically disable an active EXLIST list.
Syntax:
MODIFY mfc,DEL,EXCLUDEGROUP= groupid F mfc,DEL,EXCLUDEGROUP= groupid
Using this command will disable EXLIST list validation.
If EXLIST list processing is not currently active, a message is issued and processing continues.
Enabling a deactivated EXLIST list
The MODIFY command can be used to dynamically enable a deactivated EXLIST list.
Syntax:
MODIFY mfc,REACTIVATE,EXLIST F mfc,REACTIVATE,EXLIST
Using this command will re-enable EXLIST validation.
If EXLIST list processing is already active or did not previously exist, a message is issued and processing continues.
If INLIST list processing is already active, the command will be disallowed and a message issued, because of the mutual exclusivity of INLIST and EXLIST as described earlier in this guide. It will first be necessary to deactivate the INLIST.
Reloading the EXLIST list
The MODIFY command can be used to reload the EXLIST list from the EXLIST DD dataset concatenation.
Syntax:
MODIFY mfc,RELOAD,EXLIST F mfc,RELOAD,EXLIST
Using this command causes Mainframe Connector to create a new copy of the EXLIST list from the current contents of the datasets in the EXLIST DD concatenation. This command permits sites to update their static EXLIST datasets and activate the contents of those datasets dynamically. To get the expected results, the EXLIST DD concatenation must be kept to a maximum of 32 DD statements.
If no EXLIST list processing was active, a message is issued and processing continues.
Note that RELOAD will nullify updates resulting from any prior ADD or DEL commands issued against the EXLIST list unless the EXLIST dataset(s) are updated as well (eg. - via ISPF EDIT) to reflect the ADD or DEL changes prior to issuance of the RELOAD.
Modifying the DEBUGLEVEL
The MODIFY command can be used to dynamically change the debugging level being used by Mainframe Connector.
Syntax:
MODIFY mfc,DEBUGLEVEL= n F mfc,DEBUGLEVEL= n
Where n represents the new DEBUGLEVEL value in the range 0 – 9.
The DEBUGLEVEL parameter described in Mainframe Connector subsystem internal configuration provides a detailed description of the various debugging levels. A DEBUGLEVEL other than 0 should only be used on recommendation of Bravura Security technical support.
Modifying the ENCRYPTION value
The MODIFY command can be used to dynamically change the encryption format being used by Mainframe Connector to communicate with a Bravura Security Fabric server.
Syntax:
MODIFY mfc,ENCRYPTION= n F mfc,ENCRYPTION= n
Where n represents the new ENCRYPTION value.
The ENCRYPTION parameter described in Mainframe Connector subsystem internal configuration provides a detailed description of the supported encryption values.
Modifying the ENTROPYFALLBACK value
The MODIFY command can be used to dynamically change the entropy fallback indicator being used by Mainframe Connector .
Syntax:
MODIFY mfc,ENTROPYFALLBACK= n F mfc,ENTROPYFALLBACK= n
Where n represents the new ENTROPYFALLBACK value. Valid values are YES and NO.
Modifying the SOCKETCLOSEWAIT
The MODIFY command can be used to dynamically change the socket close wait time used by Mainframe Connector.
Syntax:
MODIFY mfc,SOCKETCLOSEWAIT= n F mfc,SOCKETCLOSEWAIT= n
Where n represents the new SOCKETCLOSEWAIT value in the range 0 – 5.
The SOCKETCLOSEWAIT parameter described in Mainframe Connector subsystem internal configuration provides a description of the socket close wait.
Modifying the OUTBOUNDPWCASE
The MODIFY command can be used to dynamically change the case of outbound password values sent by Mainframe Connector to a Bravura Pass server for synchronization.
Syntax:
MODIFY mfc,OUTBOUNDPWCASE= n F mfc,OUTBOUNDPWCASE= n
Where n represents the new OUTBOUNDPWCASE value. Valid values are ASIS, LOWER, and UPPER.
The OUTBOUNDPWCASE parameter described in Mainframe Connector subsystem internal configuration provides a description of this parameter value.
Modifying the DATASPACE logging options
If the DATASPACE parameter was specified for Mainframe Connector startup, the MODIFY command can be used to dynamically influence which types of logging information are collected in the Mainframe Connector dataspace.
Activating SMF record log data collection
The MODIFY command can be used to activate the collection of Mainframe Connector SMF record log information.
Syntax:
MODIFY mfc,REACTIVATE,DSSMF F mfc,REACTIVATE,DSSMF
The REACTIVATE option can be specified even if the SMF value was not specified on the DATASPACE parameter at Mainframe Connector startup.
Deactivating SMF record log data collection
The MODIFY command can be used to deactivate the collection of Mainframe Connector SMF record log information.
Syntax:
MODIFY mfc,DEACTIVATE,DSSMF F mfc,DEACTIVATE,DSSMF
Activating AUDIT log data collection
The MODIFY command can be used to activate the collection of Mainframe Connector AUDIT log information.
Syntax:
MODIFY mfc,REACTIVATE,DSAUDIT F mfc,REACTIVATE,DSAUDIT
The REACTIVATE option can be specified even if the AUDIT value was not specified on the DATASPACE parameter at Mainframe Connector startup.
Deactivating AUDIT log data collection
The MODIFY command can be used to deactivate the collection of Mainframe Connector AUDIT log information.
Syntax:
MODIFY mfc,DEACTIVATE,DSAUDIT F mfc,DEACTIVATE,DSAUDIT
Activating SYNCHLOG log data collection
The MODIFY command can be used to activate the collection of Mainframe Connector SYNCHLOG log information.
Syntax:
MODIFY mfc,REACTIVATE,DSSYNCHLOG F mfc,REACTIVATE,DSSYNCHLOG
The REACTIVATE option can be specified even if the SYNCHLOG value was not specified on the DATASPACE parameter at Mainframe Connector startup.
Deactivating SYNCHLOG log data collection
The MODIFY command can be used to deactivate the collection of Mainframe Connector SYNCHLOG log information.
Syntax:
MODIFY mfc,DEACTIVATE,DSSYNCHLOG F mfc,DEACTIVATE,DSSYNCHLOG
SMF Record Mapping
If Mainframe Connector SMF records are being created, it will be necessary to post process the SMF record data to obtain information about the individual Mainframe Connector events. An SMF record mapping macro can be found in member PSNCSMF of the INSTLIB dataset. The following is the SMF record mapping for a Mainframe Connector SMF record:
SMFLEN DS XL2 SMF RECORD LENGTH SMFSEG DS XL2 SMF RECORD SEGMENT SMFFLSG DS XL1 FLAG BYTE SMFTYPE DS XL1 SMF RECORD NUMBER SMFTIME DS XL4 0.01 SECONDS SINCE MIDNIGHT SMFDATE DS XL4 DATE IN 0CYYDDDF FORMAT SMFSYSID DS CL4 SMF SYSID OF SYSTEM SMFUID DS CL8 UID FOR WHICH FUNCTION OCCURRED SMFOFLAG DS XL1 OUTBOUND REQUEST STATUS SMFOPWOK EQU X'80' PWD VALUE IS OK SMFOPWRJ EQU X'40' PWD VALUE HAS BEEN REJECTED SMFOBRTO EQU X'20' OUTBOUND REQUEST TIMED OUT SMFOBRCF EQU X'10' OUTBOUND REQUEST CONNECTION FAIL SMFOBRUN EQU X'08' OUTBOUND REQUEST UNKNOWN FAILURE SMFIFLAG DS XL1 INBOUND REQUEST SMFIVRFY EQU X'80' REQUEST WAS AN INBOUND VERIFY SMFICHNG EQU X'40' REQUEST WAS AN INBOUND CHANGE SMFIREST EQU X'20' REQUEST WAS AN INBOUND RESET SMFIPOLL EQU X'10' REQUEST WAS AN INBOUND POLL SMFIRSXP EQU X'08' REQUEST WAS AN INBOUND RESETEXP SMFIXPIR EQU X'04' REQUEST WAS AN INBOUND EXPIRE SMFIUEN EQU X'02' REQUEST WAS AN INBOUND ENABLE SMFIUDIS EQU X'01' REQUEST WAS AN INBOUND DISABLE SMFIUIEN EQU X'03' REQUEST WAS AN INBOUND ISENABLED SMFIFLG2 DS XL1 INBOUND REQUEST SMFIUDEF EQU X'20' REQUEST WAS AN INBOUND CREATE SMFIUDEL EQU X'10' REQUEST WAS AN INBOUND DELETE SMFILGRP EQU X'04' REQUEST WAS AN INBOUND LISTGROUP SMFILMEM EQU X'02' REQUEST WAS AN INBOUND LISTMEMBERS SMFIFLG3 DS XL1 INBOUND REQUEST SMFIGRPA EQU X'80' REQUEST WAS AN INBOUND GRP USR ADD SMFIGRPD EQU X'40' REQUEST WAS AN INBOUND GRP USR DEL SMFIUUPD EQU X'20' REQUEST WAS AN INBOUND UPDATE SMFIGTUA EQU X'10' REQUEST WAS AN INBOUND GET USR ATT SMFIPHRS EQU X'08' REQUEST WAS AN INBOUND PHRASE RESET SMFIPHRX EQU X'04' REQUEST WAS AN I/B PHRASE RESETEXP SMFIRSCU EQU X'02' REQUEST WAS AN INBOUND RESOURCE UPDATE SMFRSRV2 DS XL4 RESERVED SMFSSNM DS CL4 SUBSYS NAME OF CREATING SUBSYS SMFLN EQU *-SMFLEN SMF RECORD LENGTH SMFRSRCU DS 0F RACF RESOURCE UPDATE AREA SMFRCLAS DS CL8 RESOURCE CLASS SMFRPROF DS CL255 RESOURCE PROFILE SMFRRSV1 DS XL1 RESERVED SMFRUSER DS CL8 RESOURCE USERID SMFRACC DS CL8 RESOURCE ACCESS REQUEST SMFRCMAJ DS CL8 RESOURCE MAJOR CONDITION SMFRCMIN DS CL8 RESOURCE MINOR CONDITION SMFRGEN DS CL8 RESOURCE GENERIC INDICATOR SMFLN2 EQU *-SMFLEN SMF RECORD LENGTH
Password Change Notification Exit Conflict
At some sites, the password exit that is invoked for password change events may already be in use for another function. Mainframe Connector provides a collection of macros that can be used to drive the individual exits and package them into a single exit replacement.
These macros can be used in RACF environments for the ICHPWX01 exit and in ACF2 environments for the NEWPXIT exit. TopSecret customers who are already using TSSINSTX in their environment should contact Bravura Security for recommendations on how to incorporate the Mainframe Connector requirements for TSSINSTX with those of the customer.
Three macros are used for this purpose. They are
#SETUP
#XITRTN
#TERM
These macros have been included in the installation sample job library included with the Mainframe Connector installation material.
#SETUP
The #SETUP macro is used to initialize the exit environment. Three parameters can be coded on the macro: BASE , AMODE , and RMODE .
BASE is used to indicate the base register for the exit driver module. The default is BASE=R12. Although no validation checks are made in the #SETUP macro, the value for BASE should be restricted to R2 – R12, inclusive.
AMODE is used to indicate the addressing mode of the exit driver module. The default is AMODE=31 . Valid values are AMODE=24 and AMODE=31 .
RMODE is used to indicate the residency mode of the exit driver module. The default is RMODE=ANY . Valid values are RMODE=24 and RMODE=ANY .
#SETUP macro usage examples might look like the following:
ICHPWX01 #SETUP BASE=R10,AMODE=31,RMODE=24 ICHPWX01 #SETUP
The label is required for the #SETUP macro.
#XITRTN
The #XITRTN macro is used to include the individual exit routines. Two parameters can be coded on the macro: NAME and COND.
NAME is used to indicate the module name of a particular individual exit. There is no default for NAME and it must be coded if the #XITRTN macro is used.
COND is used to indicate the maximum highest return code from a previous #XITRTN routine that will be tolerated for the current routine to still execute. For example, COND=4 indicates that the current routine should execute if no previous exit routine has returned a return code greater than 4. A default of COND=0 is assumed if no COND parameter is coded on the #XITRTN macro.
#XITRTN macro usage examples would look as follows:
EXIT1 #XITRTN NAME=PSYNCXIT,COND=0 EXIT2 #XITRTN NAME=OURPWXIT,COND=8
#TERM
The #TERM macro is used to perform cleanup for the #SETUP macro and to return control to the MVS security product caller. The #TERM macro accepts one parameter: RC.
RC is used to indicate the exit return code that will be passed back to the original caller. It should be set to the highest return code value that was returned from any of the #XITRTN exit routines.
#TERM macro usage examples would look as follows:
#TERM RC=(R5) END #TERM RC=8
The #TERM exit establishes register equates and a DSECT mapping for temporary storage obtained in the #SETUP macro. The following labels are used by the temporary storage mapping:
TEMPSTOR
SAVEAREA
R1VAL
LASTRC
HIGHRC
External to the scope of the macro calls, LASTRC can be used to determine the return code value returned by the last successfully executed #XITRTN exit routine. HIGHRC can be used to determine the highest return code that has been returned from any prior execution of a #XITRTN exit routine.
Recommendations
The Bravura Pass server expects that password update requests that it has approved will not be rejected by the z/OS security product. New password values will have been validated against any installation rules prior to the call to the Bravura Pass server. As a result, if the Mainframe Connector password change exit is used in conjunction with other exits, the following recommendations should be considered:
Place the Mainframe Connector exit last in the exit call sequence.
Do not invoke the Mainframe Connector exit if a previous exit routine has set a return code that would cause the password update to be rejected (see the Exit driver example).
When multiple exits are linked together, it may be necessary to alter the CSECT names of existing modules. The linkage editor can be used for that purpose. The following example would link an exit driver with CSECT name ICHPWX01 with PWXIT001 , PWXIT002 , and the Mainframe Connector password change exit into a single load module with a name of ICHPWX01 and change the name of the Mainframe Connector password exit to PSNCPWX1 :
INCLUDE OBJ(XITDRVR)
INCLUDE OBJ(PWXIT001)
INCLUDE OBJ(PWXIT002)
CHANGE ICHPWX01(PSNCPWX1)
INCLUDE PSNCOBJ(ICHPWX01)
ENTRY ICHPWX01
SETCODE AC(1)
NAME ICHPWX01(R)Exit driver example
Following is an example of a simple exit driver:
ICHPWX01 #SETUP Perform exit driver setup
#XITRTN NAME=PWXIT001 Execute the PWXIT001 exit
#XITRTN NAME=PWXIT002,COND=8 Execute the PWXIT002 exit
* routine if PWXIT001 return code
* was 8 or less
#XITRTN NAME=PSNCPWX1,COND=0 Execute the PSNCPWX1 exit rtn
* if no previous exit had a return
* code greater than 0
L R15,HIGHRC Load the max return code
#TERM RC=(R15) Return to the security product
ENDMultiple Mainframe Connector Started Tasks and New Password Exits
This section pertains to sites who plan on running multiple Mainframe Connector started tasks on the same z/OS image AND who also want to use z/OS as a trigger system for transparent synchronization. In order to accomplish this, the customer must build a table that maps userids to subsystem names. The generated table is a non-executable load module named PSNCUIDT that must reside in a multi-address space accessible location (most probably either the link pack area or the system linklist).
A table generation macro is provided in the .INSTLIB Mainframe Connector dataset in member UIDSSN . This macro is used for three purposes:
To define the table header record that contains, if specified, the default subsystem name to be used by any userid entry definitions that have omitted a subsystem name parameter
To define userid entry records that specify userids (that can be fully qualified or masked) and the associated Mainframe Connector subsystem name
To define the table trailer record that is used to indicate the end of the table
A sample PSNCUIDT source deck using the UIDSSN macro would look similar to the following:
*
* HEADER record sets DFLTSSN to PS1. This indicates that any
* UIDENTRY record that does not include a SSNAME parameter will
* have its SSNAME set to PS1.
PSNCUIDT UIDSSN HEADER,DFLTSSN=PS1
* Target userid MTECH1 to Mainframe Connector subsystem PS1
UIDSSN UIDENTRY,USERID=MTECH1,SSNAME=PS1
* Target userid MTECH2 to Mainframe Connector subsystem PS2
UIDSSN UIDENTRY,USERID=MTECH2,SSNAME=PS2
* Target userid MTECH3 to Mainframe Connector subsystem PS1
UIDSSN UIDENTRY,USERID=MTECH3,SSNAME=PS1
* Target any userid prefixed MTCH to Mainframe Connector subsys PS3
UIDSSN UIDENTRY,USERID=MTCH-,SSNAME=PS3
* Target a userid prefixed DBA followed by any other character
* to the default Mainframe Connector subsystem PS1
UIDSSN UIDENTRY,USERID=DBA*
* TRAILER record indicates the end of the table
UIDSSN TRAILER
ENDThe number of UIDENTRY table entry definitions required will obviously depend on the number of Mainframe Connector subsystems that will be operational and the uniqueness of the userids. The more generic the userid, the more likely a masked UIDENTRY table entry can be used.
Once the source deck has been created, it will need to be assembled using a standard assembly job similar to the following:
//ASM EXEC PGM=ASMA90,REGION=6M, // PARM='LIST,NODECK,OBJECT,XREF(SHORT)' //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=mfc.V700.INSTLIB,DISP=SHR //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(3,3)) //SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(3,3)) //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(3,3)) //SYSLIN DD DSN=mfc.V702.F1(PSNCUIDT),DISP=SHR //SYSIN DD DSN=psncuidt.source.dataset(PSNCUIDT),DISP=SHR
To create the PSNCUIDT load module table, run a linkedit job similar to the following:
//IEWL EXEC PGM=HEWLH096,PARM='XREF,LIST,MAP' //SYSPRINT DD SYSOUT=* //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1)) //OBJECT DD DSN=mfc.V702.F1,DISP=SHR //SYSLMOD DD DSN=target.load.library,DISP=SHR //SYSLIN DD * INCLUDE OBJECT(PSNCUIDT) NAME PSNCUIDT(R)
Depending on the site’s performance expectation and the anticipated frequency on how often the PSNCUIDT table will change, the two most likely locations for PSNCUIDT are the system link pack area (LPA) or the system linklist (SYS1.LINKLIB or one of the other datasets in the system linklist concatenation).
PSNCUIDT is loaded dynamically by Mainframe Connector each time it is referenced so this allows for the table to be dynamically updated and refreshed as required. This can be accomplished by z/OS operator commands for either location choice - either the system LPA or the system linklist.