Using log files for problem diagnosis if LDAP user authentication fails

When users cannot log on with LDAP user authentication, there might be errors in the configuration parameters. You can find information about the problem and how to solve it by using the log files.

Symptom

The LDAP user authentication process fails, and users cannot log on to a server.

Possible cause

Errors in the LDAP configuration parameters might exist.

Actions

  1. Check that the LDAP exit routine is executing.
    1. Turn on tracing for the library server and try again to log on.
    2. View the log file. Verify that the file ICMXLSLG.DLL exists in the directory indicated in the DLL Path entry in the log file. If it does not exist in this location, see the LDAP integration steps, including the step to install the user exit for LDAP authentication.
    3. In the log file, look for the ICMPLSLG CallUserExit entry.

      If the entry is not present, the LDAP exit routine was not called. There is a problem with the LDAP configuration. See the LDAP integration steps, including the steps to generate and install the properties file and the step to install the user exit for LDAP authentication.

      If the entry is present, then the LDAP exit routine was called but it was not successful. Continue with the next step.

  2. Enable the LDAP log facility on the library server.
    Restriction: If the library server is installed on a Windows™ system, LDAP logging is not available by using any of the following methods. For a library server on a Windows system, use the library server log file to find return codes and messages for LDAP errors.

    If you experience failures with LDAP user authentication, you can further analyze why LDAP user authentication is failing by setting the LDAP log to debug for better troubleshooting analysis. Setting the LDAP log to debug creates the UE.LOG log file on the machine where the library server is installed. On a Linux® or AIX® system, the UE.LOG file is written to /tmp/UE.LOG.

    The UE.LOG file traces each step of the LDAP user authentication process. When authentication is failing, the UE.LOG file provides information that can guide you with debugging the problem. The log file also captures detailed information about other LDAP processes, such as importing users.

    You can set the LDAP log to debug by using two different procedures, by setting an integer value for the library server logging level in the log configuration utility or by setting the value of the LDAPDEBUG environment variable. The recommended procedure is to set a value on the logging level because it does not require a restart of the library server or database.

    After LDAP authentication is operating successfully and users are able to log in with no error messages, disable the LDAP log facility. Generating the UE.LOG file each time that a user is authenticated slows system performance. Choose one of the following options, based upon how the LDAP logging was enabled:
    • To disable LDAP logging from the library server logging level in the log configuration utility, use the steps for changing the logging level to change the integer value to one of the predefined logging levels for the library server, such as Error or Warning.
    • To disable LDAP logging from the LDAPDEBUG environment variable, use the steps for Linux and AIX systems to set the value of LDAPDEBUG equal to 0. Alternatively, you can remove the environment variable from the system.

Enabling LDAP logging dynamically from the library server logging level on Linux and AIX systems

Use the log configuration utility to enable LDAP logging by changing the logging level for the library server.

Tip: To check whether LDAP logging is already enabled:
  1. Get the current trace level settings from TraceLevel parameter in the ICMSTSysControl system control table.
  2. Use a calculator to convert this value to a binary equivalent. The numeric value for LDAP logging, 4096, is equivalent to bit 12 of the binary number. If bit 12 is turned on, then LDAP logging is already enabled.
To enable LDAP logging in the log configuration utility:
  1. From the system administration client, click Tools > Log Configuration.
  2. Click Library server.
  3. In the Logging level field, choose one of the following actions:
    • If you want to enable LDAP logging only, enter 4096 as the logging level. This value is the numeric equivalent of LDAP logging. It does not include any library server logging functions.
    • If you want to enable LDAP logging plus a logging level for the library server, enter 4096 plus the numeric value of the library server logging level. For example, if you want to enable LDAP logging plus library server logging at the full trace level, enter 4111, the sum of 4096 + 15.
  4. After you diagnose the problem by using the LDAP logs, disable LDAP logging by entering a logging level for the library server only in the log configuration utility. LDAP logging consumes a large amount of system resources and can affect the overall performance of your content management system.

Enabling LDAP logging with LDAPDEBUG on Linux and AIX systems

To enable LDAP logging by setting the LDAPDEBUG system variable for a Linux or AIX environment:
  1. Log on to the Linux or AIX system where the library server is installed with a user ID that has Db2® administrator privileges, or log on as the root user.
  2. Change to the /home/DB2INSTANCE/sqllib/ path where DB2INSTANCE is the Db2 instance name.
  3. Make a backup copy of the userprofile file.
  4. Open the userprofile file in a text editor.
  5. Modify the userprofile file by adding the LDAPDEBUG variable name and value information. For example, add export LDAPDEBUG=1.
  6. Add LDAPDEBUG to the DB2ENVLIST in /home/DB2INSTANCE/sqllib/profile.env path.
  7. Verify that the export variables for ICMDLL and IBMCMROOT contain the correct path values for your system.
  8. Restart Db2 Universal Database to ensure that the new LDAPDEBUG environment variable is picked up in the environment.