Error messages and problem solving

A warning or error message might be displayed in the user interface to provide information about the adapter or when an error occurs.

Error messages

agentCfg configuration key minimum characters

A configuration key is not allowed to be less than 5 characters. Otherwise, when you start agentCfg to configure an active adapter, the following message is displayed:

Configuration key too short - 5 characters minimum. Aborting...

After which the agentCfg processing aborts.

Registry file initialization

Additional information is logged in the z/OS syslog during adapter initialization. It is about the initialization of the registry file for the following scenarios:

The registry file that is configured in the shell script is used to start the adapter does not exist. In this event a new registry file is created and the following messages are written to the syslog:
```
racfAgent: Registry file specified by environment
REGISTRY is '<adapter_read_write_home>/data/<adapter_name>.dat'
racfAgent: REGISTRY does not exist
racfAgent: Creating a new registry file
```

The registry file does exist, but cannot be accessed (for example, incorrect file permissions). In this event the adapter aborts initialization and the following messages are written to the syslog:


racfAgent: Registry file specified by environment
REGISTRY is '<adapter_read_write_home>/data/<adapter_name>.dat'
racfAgent: FATAL ERROR: REGISTRY file open error: EDC5111I Permission
denied.
racfAgent: can't continue without access to the registry file
racfAgent: exiting process

The registry does exist but the adapter can't access part of the path. In this event the adapter aborts initialization and the following messages are written to the syslog:

racfAgent: Registry file specified by environment
REGISTRY is '<adapter_read_write_home>/data/<adapter_name>.dat'
racfAgent: FATAL ERROR: REGISTRY file stat error:
EDC5111I Permission denied.
racfAgent: can't continue without access to the registry file
racfAgent: exiting process

The registry does exist, but is not specified in the shell script that is used to start the adapter. In this event a new registry file is created in /tmp and the following messages are written to the syslog:
```
racfAgent: WARNING no REGISTRY file specified by the environment
racfAgent: Creating a new registry file
racfAgent: Registry to be created is '/tmp/<adapter_name>.dat'
```

Max Thread settings for adapter operations

The default maximum number of threads for all adapter operations (search, modify, add, delete) is set to three at adapter initialization. The default minimum number of threads for all adapter operations is set to one at adapter initialization since at least one thread is required to perform an operation. The adapter now writes debug messages to the adapter log regarding the number of threads currently still available for performing new operations. This provides more insight in possible thread availability-related delays in processing.

Starting the adapter in console mode

For debugging purposes, it might be useful to start the adapter directly from the command line in console mode. Doing so provides all messages that are otherwise written to either the syslog or the adapter log to be displayed on the console used to start the adapter from. Starting the adapter in console mode can be done by executing all export commands as configured in the shell script. The script is used to start the adapter to ensure that all libraries are available to the adapter and then executes the following command to start the adapter:

/<adapter_readonly_home/lpp/bin/racfAgent -name <adapter_name> -registry
<adapter_readwrite_home>/data/<adapter_name>.dat -console

Added AES to KERB form (and changed DESD description)

On the Security Identity Manager server, the description for the DESD field in the Kerberos tab was incorrect. This is corrected and a new field was added for the AES encryption type and support for the new field was added to the RACF agent.

Warnings and error messages

All errors returned by RACF when executing RACF commands using the R_Admin calleable service IRRSEQ00 are recorded in the adapter log. If a command cannot be run, the adapter records the SAF return code, the RACF return code and RACF reason codes in the adapter log. For example:

ERR:15/05/01 11:48:47 issueRadmin: safRC = 8, racfRC = 8 racfReason = 24, returning rc = 5

It is likely that the AdapterID or SURROGATID does not have permission to all the required profiles as described in the RACF Access Configuration. Detailed information on these return and reason codes can be found in the z/OS Security Server RACF Callable Services documentation in the z/OS Knowledge Center.

BSE:_ermAlloc: ERROR: malloc FAILED: size 60

The adapter stops processing when it encounters errors during memory allocation.

The following messages are displayed to indicate that the adapter is aborting from the process:

ERR: racfSearch: Entry creation returned failure 
ERR:racfSearch: reconciliation ABORTED

After which, this final error message is written to the adapter log: ERR: "FATAL memory error encountered, shutting down now"

The IBM® Security Identity server displays Fatal error encountered

Memory allocation errors might be caused from inadequate Language Environment (LE) HEAP size settings.

The HEAP size settings can be diagnosed when you add the following line to the adapter start script:

export _CEE_RUNOPTS='RPTOPTS(ON),RPTSTG(ON)'

This line ensures that the adapters started task log displays the current heap size allocations and suggested minimal sizes.

You can use the following general settings for the RACF adapter:

export _CEE_RUNOPTS='HEAP(80K,8K,ANYWHERE,,1K,1K),AN(1450K,4K,ANY,FREE),AL(ON),
HEAPPOOLS(ON,8,8,16,16,24,17,32,3,56,8,72,3,136,4,296,7,480,3,848,4,2080,,4104,)'

Adapter messages

RACF® UNLOAD missing 0102 record processing

In case a RACF database unload 0102 record is missing, so the true connect authority value is unknown, <AUTHORITY>USE</AUTHORITY> is generated.

In case a 0102 record is missing, a message starting with "Fix0205" is printed to the SYSPRINT of the ISIMRECO program. This message shows the group and user information for which the default authority USE is generated.

IRRDBU00 does not unload a Group Members data record (0102) for every user connected to a universal group. Only users who are listed in the group's member list have 0102 records. Users listed in the group member list are those users with group-level user attributes, such as group-SPECIAL, or group authority higher than USE.

The adapter will not write the Unload 0102 record is missing message to the log for universal groups. These records are expected to be missing for users that are not listed in the group's member list.

Server messages

The following table contains warnings or errors that might be displayed on the user interface if the adapter is installed on your workstation.

Table 1. Error messages, warnings, and corrective actions
Error message or warning	Additional warnings, messages, or information	Corrective action
Adapter error message: could not set security environment for SURROGAT.	Adapter log: ERR:14/07/31 10:42:31 racfModify: pthread_security_np() create failed. errno2=0BE800D8: EDC5139I Operation is not permitted	PERMIT UPDATE access for ISIAGNT on BPX.SERVER in CLASS FACILITY
racfSearch: failed to create RECOJOB thread	z/OS® Syslog might provide INSUFFICIENT AUTHORITY message	Verify that the adapter RACF ID and SURROGAT ID have read and write access to the READWRITE data directory.
Could not set security environment for SURROGAT user	Not applicable	PERMIT READ access for ISIAGNT on BPX.SRV.`<SURROGATID>` in CLASS SURROGAT
racfSearch: failed to create RECOJOB thread	DETAIL Adapter log: tsoCmd: result is IKJ56644I NO VALID TSO USERID, DEFAULT USER ATTRIBUTES USED	Ensure that the ADAPTER ID has a valid TSO USERID.
CTGIMU107W `The connection to the specified service cannot be established. Verify the service information, and try again`	An IO error occurred sending a request. Error: `Connection refused: connect`	Ensure that the adapter service is running. For more information about starting the adapter service, see Restarting the adapter service.
	The adapter returned an error status for a bind request. Status code: invalid credentials adapter error message: `Authentication Failed`	Check the adapter authentication ID and password match the installed values. See the screen for Adapter-specific parameters in the task Running the ISPF dialog.
	An IO error occurred sending a request. Error: `com.ibm.daml.jndi. JSSESocketConnection .HANDSHAKE_FAILED:`	If SSL is enabled, check the configuration. See Configuring SSL authentication. The adapter log contains details about the certificates that are loaded during initialization.
	User `user name` add Successful. Some attributes were not modified: `attr1,attr2`	An attempt is made to add a user account. However, certain attributes are not set during the user add operation. For more information, see the adapter log file at /var/ibm/isimracf/log/racfagent.log.. The log file contains information about the attributes that are not set during the user add operation.
	User `user name` modify Successful. Some attributes were not modified: `attr1,attr2`	An attempt is made to modify a user account. However, modification failed for certain attributes during the operation. For more information, see the adapter log file at /var/ibm/isimracf/log/racfagent.log. The log file contains information about the attributes that are not set during the modify operation.
CTGIMD812E `An error occurred while processing the adapter response message. The following error occurred. Error: Premature end of file.`		Ensure that the adapter service is running. For more information about starting the adapter service, see Restarting the adapter service
tsoCmd: result is YOUR TSO ADMINISTRATOR MUST AUTHORIZE USE OF THIS COMMAND	Not applicable.	PERMIT READ access for ISIAGNT on JCL in CLASS TSOAUTH For example: PE JCL CLASS(TSOAUTH) ID(ISIAGNT) ACCESS(READ)SETROPTS RACLIST(TSOAUTH) REFRESH
tsoCmd: RECOJOB was not submitted	tsoCmd: result is `<result string>` racfSearch: failed to initiate reco_open	Verify whether the result string is a standard TSO message as defined in SYS1.MSGENU(IKJSCHEN). If a custom exit that returns a non-standard message is implemented, exclude the reconciliation job from this exit.
LDAP: error code 92		Increase the size of the transaction log. See DB2 transaction log size.
`*BPXI040I PROCESS LIMIT MAXPROCUSER HAS REACHED XX % OF ITS CURRENT CAPACITY OF XX FOR PID=XXX IN JOB ISIAGNT`		Increase the amount of processes available to the adapter's RACF logonid.