This article describes how to troubleshoot problems during the installation of IBM Lotus Connections. The first and most important step is to review the Lotus Connections installation process thoroughly as described in the IBM Lotus Connections Information Center and to make sure you have followed all steps accurately. If you are satisfied that you have followed the directions correctly, ask yourself these questions:

• Where is the problem?
• What is the problem?
• How can I resolve the problem?

The content of this article is intended for I/T specialists and architects who undertake a deployment of Lotus Connections.

The article draws on first-hand experience gained from conducting Lotus Connections installations and describes some common problems and their solutions. The first section describes how to find a problem at a high level. The next three sections focus on specific components and describe how to troubleshoot and fix an error once it has been found. The final section details how to gather additional diagnostic information

Locating the problem

The first indication you get of a problem with Lotus Connections is an error page displayed in a Web browser. This section covers the different types of error displays and their meanings. The type of error page displayed points you to the next steps in diagnosing the problem.

HTTP 404 or Not Found error page

If the Web browser displays an HTTP 404 error (see figure 1), this indicates the problem is likely in the configuration of the Web server. There may be problems with starting the Web server, Web server plug-in issues, Lotus Connections Navigation Bar configuration, or SSL.

To gather more information, check the Web server logs located in the following places:

<IHS_install_directory>\logs\access.log
<IHS_install_directory>\logs\error.log

The server access log records all Web server activity, including the following information for each request:

• What was requested
• Who requested it
• When it was requested
• The method used
• The type of file sent in response
• The return code

The error log contains diagnostic information and records any errors that it encounters in processing requests.

HTTP 500 Internal Server Error

Another common error is a 500 Internal Server Error (see figure 2). This page is displayed when an error occurs before executing any Lotus Connections processes or for an error that is not handled in Lotus Connections. To discover the cause of these errors, examine the Java Virtual Machine (JVM) logs. The default names of the logs are SytemOut.log and SystemErr.log. The logs are located in:

<WAS_install_directory>\profiles\<profileName>\logs\<servername>\

The logs contain stack traces of exceptions thrown by the JVM. Examine the traces to determine where the problem lies.

If the problem is database related, an exception similar to the one shown in listing 1 may be present. To further troubleshoot this, review the "Database errors" section of this article.

[30/05/07 14:53:48:941 BST] 00000025 OpenActivitie E 
org.apache.commons.logging.impl.Jdk14Logger error CLFRA0091E:
 internal error
com.ibatis.dao.client.DaoException: Error getting MemberProfile: 
java.sql.SQLException: Error: executeQueryForObject returned 
too many results.
Caused by: java.sql.SQLException: Error: executeQueryForObject 
returned too many results

If the problem is related to security, exceptions similar to the one shown in listing 2 may be present. To further troubleshoot this, review the "Problems with WebSphere Application Server security" section of this article.

	
[29/05/07 21:19:46:315 BST] 00000026 LdapAdapter   E 
com.ibm.ws.wim.adapter.ldap.LdapAdapter authenticateWithPassword 
javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: 
LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 52e, 
vece ]; resolved object com.sun.jndi.ldap.LdapCtx@18621862

A further complication involves diagnosing in a clustered environment. In this scenario, you need to examine the logs of each application server in the cell. The problem may exist on all servers or just one, and you may need to stop some of the application servers to isolate the problem.

Lotus Connections error

Lotus Connections displays an error page (see figure 3) when an exception is thrown during the execution of a function. Clicking Show Full Error Message shows details of the exception. Sometimes the underlying cause of the error message is not conveyed to the browser. If this happens, perform further diagnosis by examining the SystemOut.log and the SystemErr.log.

Back to top

Page Not Found and Web server plug-in problems

This section covers steps for diagnosing and resolving issues related to the Web server, Web server plug-ins, and Page Not Found errors. These errors usually represent themselves as HTTP 404 errors.

Ensure your Web server has started

First check that the HTTP server is up and running.

In Microsoft Windows, the HTTP server is most likely to be run as a service:

1. Open the services window by navigating from the Start menu to Administrative Tools - Services.
2. Check that the IBM HTTP Server service has started.
3. If the service has not started, right-click the service and click Start.

In Unix, follow these steps:

1. Execute the command cd <IHS_install_directory>/bin.
2. Execute the command ./apachectrl start.

If the HTTP server starts successfully, try accessing the Lotus Connections URL again.

If the server does not start, examine the HTTP server logs for further diagnosis and refer to the next subsections of this article.

Web server configuration error

If the Web server fails to start, manual changes may have corrupted the HTTP configuration file (httpd.conf if using IBM HTTP Server). Review all your manual changes and cross-reference the Lotus Connections Information Center. One common mistake is to forget to enable the module for rewrite rules. Before you can use the rewrite rules, you must uncomment this line:

LoadModule rewrite_module modules/mod_rewrite.so

After you have fixed this problem, restart the Web server and try again.

Web server plug-in

If the server starts successfully, check that it is possible to access a Lotus Connections component by going directly to the IBM WebSphere Application Server, bypassing the HTTP server.

To do this, use the host name of the application server and port when accessing a Lotus Connections service. This approach indicates whether or not the application server is properly listening for HTTP requests (usually on port 9080). For example, to access profiles, use the URL http://serverhostname:9080/profiles.

If the page displays, this may indicate a problem with the module mappings and Web server plug-in. If so, you need to regenerate the plug-in. To do this, follow these steps:

1. Access the WebSphere Administrative Console, for example, http://serverhostname:9060/ibm/console.
2. Navigate to Applications - Enterprise Applications - <Connection component> - Manage Modules.
3. In the Clusters and Servers box, select the name of the application server and Web server, in this case server1 and webserver1.
4. Select the checkboxes of all the modules listed, and then click Apply and Save. See figure 4.
   
   
   Figure 4. Manage Modules dialog box
   
   
   
5. From the Administrative Console, navigate to Servers - Web servers.
6. Select the checkbox beside the Web server, and click the Generate Plug-in button. See figure 5.
   
   
   Figure 5. Web servers dialog box
   
   
   
7. Click the checkbox beside the Web server again, and click the Propagate Plug-in button.
8. Finally, restart your Web server, and navigate to the Web address of the Lotus Connections component.

Back to top

Lotus Connections navigation bar

Error 404 resulting from clicking links on the Lotus Connections navigation bar can also occur. This problem may be the result of incorrect entry of host names during the installation. These host names are held in the configuration file named LotusConnections-config.xml. The current settings can be viewed and modified by using the connectionsConfig.py script file with wasadmin. For further details on how to do this, see the Lotus Connections documentation.

HTTPS problems

In some cases, HTTPS does not work with a Web server plug-in. If this occurs, you may have a GSK_ERROR. If you see an error 500 when using HTTPS through IBM HTTP Server to get to a WebSphere Application Server application, check both your Web server and WebSphere Application Server logs. If these logs contain no errors, examine the plug-in logs located in this directory:

<IHS_install_directory\Plugins\logs\webserver1\http_plugin.log

The following error is generated if your WebSphere Application SSL certificate is not trusted by the plug-in:

ERROR: lib_stream: openStream: Failed in r_gsk_secure_soc_init:
GSK_ERROR_BAD_CERT(gsk rc = 414)

See the Lotus Connections documentation for steps to fix this error.

Back to top

Problems with WebSphere Application Server security

Problems with security can arise from the misconfiguration of LDAP settings in WebSphere Application Server.

Configure local user

It is important to always configure a local administrative user for accessing the WebSphere Administrative Console. This name is stored in the InternalFileRepository, a local file, which always allows access to the Administrative Console without relying on LDAP. It is possible to change or remove these names at any time.

To do this, follow these steps:

1. In the WebSphere Administrative Console, navigate to Security - Security Administration, applications, and infrastructure.
2. Click Configure.
3. On the General Properties screen, leave the Realm name as is, and add a primary administrative user name. Make sure that you add a name that is not present in the LDAP directory because this causes a problem when trying to login to the Administrative Console if there is an LDAP connection.
4. Next, select the "Automatically generated server identity" option.
   
   
   Figure 6. Local administrative user
   
   
   
5. Click the Apply button, and then click the Save button.
6. Enter a password for the primary administrative user name when you are prompted.

Verify LDAP settings

To check if there is a problem with the LDAP settings, follow these steps:

1. Try to access the WebSphere Administrative Console using the administrative user name stored in the LDAP directory.
2. If login is successful, proceed to checking the next step. If it is not successful, log in using the local administrative user name (see the previous section).
3. Navigate to Security Settings.
4. Check that the current realm definition is set to Federated repositories. If it is not, select Federated repositories in the Available realm definitions, and click Set as current. Apply and save the change.
5. Select Federated repositories in the Available realm definitions, and then click Configure.
6. Click the link to the Repository Identifier to view the General properties on the Repository Reference page.
7. Check that all the LDAP settings shown in figure 7 are correct, in particular these settings:
   
   • Directory type
   • Primary host name and port
   • Bind distinguished name
   • Bind password
   • Login properties
   
   
   
   Figure 7. LDAP General Properties dialog box
   
   
   
8. Check the LDAP entity types shown in figure 8, and verify that the search bases and search filter are correct.
   
   
   Figure 8. LDAP entity types
   
   
   
9. Navigate to Secure administration, applications, and infrastructure. Ensure that the Administrative security and Application security checkboxes are selected as shown in figure 9.
   
   
   Figure 9. Secure administration, applications, and infrastructure configuration
   
   
   
10. Click the Apply button, and then click the Save button.
11. Verify that a connection from the application server box to the LDAP directory is possible. Use an LDAP browser, such as Softerra LDAP Administrator, to connect using the credentials shown in step 7 to verify the connection.

Back to top

Database errors

In this section, errors relating to databases, data sources, and IBM Tivoli Directory Integrator are covered.

Databases

Lotus Connections uses five databases, namely BLOGS, DOGEAR, PEOPLEDB (profiles), OPNACT (Activities), and SNCOMM (Communities). Ensure that you have created all the databases and that they are running.

The following steps check whether or not the databases have been created and started. They are IBM DB2-specific; similar steps for Oracle are not documented here.

1. Check that the database has started on the database server machine.
   
   • Windows:
     Choose Start - Administrative Tools - Services.
     If the service has not started, right-click the service and click the Start button.
   • Unix:
     Change the directory to /opt/sqllib/bin/.
     Execute the command ./db2start.
2. After the database has started, open a db2 command window on the system where the database is installed.
3. Enter a connect command to a Lotus Connections database; for example, db2 connect to peopledb user db2admin using <password>
4. If this command is not successful, the database has not been created. Run the database creation scripts (refer to the Lotus Connections documentation page for more information).
5. Next, check the connection between the Application Server box and the database box by performing a simple telnet command from a command window. For example, use this command:
   telnet <ip_address_of_db_box> <port_number_db_listening_on>
   A successful connection is indicated by a blank command window with the title Telnet <ip address>. If the connection is not successful, check the database system's firewall settings.

For the following steps, a DB2 client is required. Lotus Connections uses only the JDBC type 4 driver, which does not require native DB2 support on the client machine (application server). That is, no DB2 client is required and no cataloging of databases is necessary. These steps, however, may be useful if a client is available, to check connectivity to databases from a remote system.

1. Open a db2 command window on the system where the application server is installed.
2. Enter a connect command to a Lotus Connections database:
   Db2 connect to peopledb user db2admin using <password>
3. If the command is not successful and using DB2, ensure that the database is cataloged on the Application Server system. For example, use this command:
   db2 catalog database <database name> at node <node name>


For more information on cataloging a database, see the DB2 Database Information Center.

Data sources

After you have verified the database creation and connection external to the application server, test the Data sources in the application server. Errors here may be a result of errors made entering database information during the installation of Lotus Connections.

To check the data sources, do the following:

1. Log on to the WebSphere Administrative Console.
2. Choose Resources - JDBC - Data sources.
3. Select a data source, and then click Test Connection. See figure 10.
   
   
   Figure 10. List data sources in WebSphere Administrative Console
   
   
   
   A successful response, which tells the user "The test connection for data source profiles on server server1 at node uklondmvmlabp3Node01 was successful," is shown in figure 11.
   
   
   Figure 11. Successful test connection
   
   
   
4. If the test is not successful, click the Name of data source, verify Server name and Port number on the data source properties screen (see figure 12), and amend accordingly. Click Apply and Save if any settings have changed.
   
   
   Figure 12. Data source properties
   
   
   
5. Next, select JAAS – J2C authentication data as shown in figure 13.
   
   
   Figure 13. JAAS – J2C authentication data
   
   
   
6. Select the Alias used for the data source being tested. Verify the user ID and password, and modify accordingly. Click Apply, and then click Save if necessary. See figure 14.
   
   
   Figure 14. JAAS entry configuration
   
   
   

Back to top

Tivoli Directory Integrator

Tivoli Directory Integrator is used for loading data into the Profiles (PEOPLEDB) database. Many installations require customization of the scripts provided with Lotus Connections to load data because the data sources differ from customer to customer. Provided here is only a selection of the steps for basic troubleshooting; the topic is much larger than the scope of this article.

Logs

The ibmdi.log is generated after each script is run in the following directory:

<TDI_install_directory>/tdisol/TDI/logs/

The log provides information about the success of the run and reports any errors that occurred.

Other logs to check are the specific logs pertaining to the script run. For example, running the populate_from_dn_file.bat creates a log file named populatefromdnfile.log.

Properties

The following steps detail the files that should be verified if an error occurs while running a Tivoli Directory Integrator script or if data is not populated as expected.

1. Check map_dbrepos_from_source.properties located in <TDI_install_directory>/tdisol/TDI, and ensure that all desired fields are mapped correctly.
2. Check profiles_tdi.properties, paying particular attention to the following properties:
   
   • source_ldap_url
   • source_ldap_user_login
   • source_ldap_user_password
   • source_ldap_search_base
   • source_ldap_search_filter
   • dbrepos_jdbc_url
   • dbrepos_jdbc_driver
   • dbrepos_username
   • dbrepos_password
3. Check the tdienv file, located in <TDI_install_directory>/tdisol/TDI, and ensure that the path is set correctly to the Tivoli Directory Integrator installation directory.
4. Ensure that the database drivers are accessible to Tivoli Directory Integrator. For example, if you use DB2, copy the db2jcc_license_cu.jar file from <DB2_install_directory>/java/ to <TDI_install_directory>/jvm/jre/lib/ext/.
5. To gather additional debug information, in the profiles_tdi.properties, set source_ldap_debug to true. This flag prints additional debug information to the log. It also sets the detailed log setting of the connectors used in the assembly lines of Tivoli Directory Integrator, which are used as part of the processing of the data source to the database repository.

Back to top

Server tracing

This section describes how to enable tracing on WebSphere Application Server and on IBM HTTP Server. Tracing is useful when log files do not provide enough information to determine the exact problem.

WebSphere Application Server tracing

In the WebSphere Application Server, you can enable tracing for specific components. This practice, though, is recommended only with the help of the support staff, but we include it here for completeness.

To enable tracing, perform the following steps:

1. From the WebSphere Administrative Console, choose Troubleshooting - Logs and Trace.
2. Select the name of the application server being used from the list of servers.
3. Select Diagnostic Trace Service, and then select the Configuration tab if it is not already displayed.
   NOTE: You can enable tracing on a running server, but only for the duration of the server process running by selecting the Runtime, thus removing the need for a server restart in step 8.
4. Select the Enable Log option.
5. Select whether the Trace Output is written to a File or to Memory Buffer.
6. Select the Change Log Detail Levels option (you can also reach this option by choosing Troubleshooting - Logs and Trace - <application server name> - Change Log Detail Levels).
7. Each component in the application server can be set to different information levels. You can do this manually by entering a trace string in the text box or by clicking a component in the list and selecting a log level from the pop-up box. See figure 15.
   
   
   Figure 15. Change Log Detail Levels dialog box
   
   
   
8. Click the Apply button, and then click the Save button.
9. Restart the application server.

Sometimes the default log sizes are too small and are overwritten before you have a chance to make a diagnosis. To avoid this situation, consider increasing the log size to 20-30 MB and retaining a number of old logs.

To do this, follow these steps:

1. From the WebSphere Administrative Console, choose Troubleshooting - Logs and Trace.
2. Select the name of the application server being used from the list of servers.
3. Click JVM.
4. Change the Maximum Size and Maximum Number of Historical Log Files in both the System.out and System.err sections.
5. Click the Apply button, and then click the Save button.

Web Server plug-in tracing

You can change the log level of the Web server plug-in to provide more information. The possible values are Trace, Stats, Warn, Error (Default) in order of least to most significant. Specifying a level includes functions from more significant levels. For example, the Warn level includes warning messages and error messages.

To change the log level, do the following:

1. From the WebSphere Administrative Console, choose Servers - Web Servers.
2. Select the name of the Web server.
3. Select Plug-in properties.
4. In the Plug-in logging section, change the log level.
5. Click the Apply button, and then click the Save button.
6. Navigate back to Web Servers, select the checkbox beside the Web server, and click Generate Plug-in.
7. Restart the Web server.

Back to top

Web server tracing

The log level of the Web server can also be changed by modifying the LogLevel of the HTTP Server by following these steps:

1. Open the httpd.conf found in <IHS_install_directory>/conf in a text editor, and then find the LogLevel parameter.
2. Set the level to one of the following:
   
   • emerg: Emergencies - system is unusable
   • alert: Action must be taken immediately
   • crit: Critical conditions
   • error: Error conditions
   • warn: Warning conditions
   • notice: Normal but significant condition
   • info: Informational
   • debug: Debug level messages
3. Save and close the file.
4. Restart the Web server.

Back to top

Conclusion

In this article, you learned about troubleshooting, and you saw how to locate, diagnose, and resolve some common problems that may occur during the installation of Lotus Connections. You learned about the different types of errors and their diagnosis and remedy. This article describes problem resolution steps relating to the Web server and HTTP plug-ins, application server security, databases, and Tivoli Directory Integrator.

Resources

Learn

• Read the developerWorks article, "Deploying IBM Lotus Connections: Planning and architecture considerations."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Post-installation tuning."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Maintenance."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Branding and customization."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Integrating with other systems."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Application programming interface."
  
  
• Read the developerWorks article, "IBM Lotus Connections: Enhancing productivity with social computing."
  
  
• Visit the developerWorks Lotus Connections page.
  
  
• Read the Lotus Connections V1.0 Reviewer's Guide.
  
  
• Consult the Lotus Connections documentation page for details on the installation, configuration, and administration of Lotus Connections.
  
  
• Consult the WebSphere Application Server V6.1 Information Center for details on the installation, configuration, clustering, and administration of WebSphere Application Server, IBM HTTP Server, and WebSphere Edge components.
  
  
• Read more about WebSphere Application Server, Version 6.0.x - Diagnosing problems (using diagnosis tools).
  
  
• Consult the IBM DB2 Database Information Center.
  
  
• Consult the DB2 V9.1 Data Recovery and High Availability Guide and Reference.
  
  
• Read "Backing up and recovering the application serving environment: WebSphere Application Server."
  
  
• Read the IBM Redbooks publication, WebSphere Application Server V6.1: System Management and Configuration.
  
  
• Read the IBM Redbooks publication, DB2 UDB V7.1 Performance Tuning Guide.
  
  
• Read the IBM Redbooks publication, Database Performance Tuning on AIX.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in the developerWorks Lotus team blog.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Locating the problem
• Page Not Found and Web server plug-in problems
• Lotus Connections navigation bar
• Problems with WebSphere Application Server security
• Database errors
• Tivoli Directory Integrator
• Server tracing
• Web server tracing
• Conclusion
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Lotus on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers