Sun Java Enterprise System 2005Q1 Technical Note

Sun Java™ Enterprise System Technical Note: Troubleshooting Sun Java System Communications Express

2005Q1

Part Number 819-3602-10

The Sun Java Enterprise System 2005Q1 Technical Note: Troubleshooting Sun Java System Communications Express describes how to troubleshoot common installation and configuration problems for Sun Java System Communications Express 6 2005Q1.

The component products affected by this technical note are:

This technical note contain the following sections:

Technical Note Revision History

Table 1  Revision History 

Date

Description of Changes

September 22, 2005

Initial release of this technical note.

Troubleshooting Communications Express Installation and Configuration

Currently, installing and configuring Communications Express is not trouble-free. This seems especially true for a two-tiered deployment, with Communications Express on a front-end host separate from a back-end Access Manager host.

The following problem topics will aid you in troubleshooting your deployment:

Problem: Unable to Configure Messaging Server

Solution: Check that DNS is running and configured properly.

  To Troubleshoot DNS

  1. Make sure that the /etc/resolv.conf file has name server entries with the IP addresses of valid name servers. For example:

    2. nameserver 192.168.100.22

    nameserver 192.168.100.23

    nameserver 192.168.100.24

    nameserver 192.168.100.25

  2. Make sure that the /etc/hosts file has an entry for the fully qualified host name of the server. This fully qualified host name should be listed before the non fully qualified host name. For example:

    3. 10.1.82.52 host1.red.example.com host1 loghost

    Solaris™ 10 Operating System (OS) systems: Make sure the /etc/inet/ipnodes file also has an entry for the fully qualified host name of the server.

  3. Make sure that the /etc/nsswitch.conf file is configured to use files first to resolve host names. The hosts line in the nsswitch.conf file should list files first in its entry:

    4. hosts: files dns nis [NOTFOUND=return]

    # OR (if NIS is not used)

    hosts: files dns

    Verify that you can resolve a host name to an IP address.

    For example:

    # nslookup host1.red.example.com

    Server: 192.168.100.161

    Address: 192.168.100.161#53

    Name: host1.red.example.com

    Address: 10.1.82.52

    Solaris 10 systems: Add this additional line to the /etc/nsswitch.conf file:

    ipnodes: files dns nisplus [NOTFOUND=return]

Problem: Web Server Exceptions

Solution: Verify the Web Server and Access Manager SDK configuration.

When configuring Communications Express in a two-tiered deployment, the following steps are involved:

  1. Configuring the Communications Express web container’s (Sun Java System Web Server 2005Q1) server.xml file with all required jar file settings
  2. Pointing the Communications Express Identity SSO to the external Access Manager from the uwcauth.properties file
  3. Installing the Access Manger SDK on the same Web Server instance where the Communications Express application is running (that is, on the front-end host)

If you see errors such as the following for Web Server, then use the troubleshooting steps that follow.

[30/Jun/2005:11:05:33] failure (13862): WebModule[/uwc]: WEB2680: Exception starting filter

IdentitySSOAuthFilter

  To Troubleshoot Communications Express

  1. Check if the Web Server runtime owner is root:other. That is, the runtime owner should be the same for Access Manager, Access Manager SDK, and Communications Express. It is preferred that the runtime owner be root:other.

    2. If the runtime owner for Web Server is not root (but webservd), then do the following:

    1. Change the ownership of the /opt/SUNWwbsvr/https-host.domain directory to root:other (recursively).
    2. Edit the /opt/SUNWwbsvr/https-host.domain/config/magnus.conf file and change the line containing “user webservd” to “user root”.
    3. Restart Web Server.
  2. Check the Access Manager SDK by running the following command from the front-end AM SDK location (host).

    3. cd /opt/SUNWam/bin

    ./amadmin -u amadmin -w password -m http://host:80

    You should see output similar to the following:

    Get Sessions: Server Name = http://host1.red.siroe.com:80

    [Current Session] User Id: amAdmin Time Remain: 120 Max Session Time: 120 Idle Time: 0 Max Idle Time: 30

    To invalidate sessions, enter the index numbers

    [CR without a number to exit]:

    Success 0: Successfully completed

  3. If Step 2 does not work as expected, then check that the Access Manager SDK classpath is correct in the Web Server on the Communications Express host (that is, the front end).

    4. Make sure that /opt/SUNWam/lib/am_services.jar, /opt/SUNWam/lib/am_sdk.jar, and /opt/SUNWam/lib/am_sso_provider.jar are in the classpath suffix of the /opt/SUNWwbsvr/https-host.domainconfig/server.xml file.

    Note

    Manually editing the server.xml file is generally not recommended. The correct way is to use the /opt/SUNWam/bin/amconfig command. See Step 6.

  4. Create a new state file similar to the following for the Access Manager SDK configuration.
    1. Change to the directory that contains the amconfig input file template, amsamplesilent.

      2. # cd /opt/SUNWam/bin

    2. Copy the input template file to a new file.

      3. # cp amsamplesilent amconfigcommx

    3. Edit the amconfigcommx file to set the Access Manager SDK configuration parameters as follows (non-default values are shown in bold):

      		4.

      DEPLOY_LEVEL=4

      SERVER_PROTOCOL=http #### (If you need secure access, change to https)

      SERVER_NAME=AM_SERVER_HOSTNAME #### (Access Manager hostname)

      SERVER_HOST=AM_SERVER_HOSTNAME_FQDN #### (Access Manager fully qualified domain name)

      SERVER_PORT=AM_SERVER_WEB_CONTAINER_PORT

      ADMIN_PORT=AM_SERVER_WEB_ADMIN_PORT

      DS_HOST=DS_HOSTNAME_FQDN #### (Directory Server fully qualified domain name)

      DS_DIRMGRPASSWD=DM_PASSWORD

      ROOT_SUFFIX=UG_SUFFIX

      ADMINPASSWD=AMADMIN_PASSWORD

      AMLDAPUSERPASSWD=AMLDAPUSERPASSWORD

      COOKIE_DOMAIN=.example.com #### (Modify to reflect default domain)

      AM_ENC_PWD="myQDWqCBhvI0bfp/BF/1b7+k/BiEpVcY" #### Get from AMConfig.properties file of fully installed Access Manager host

      NEW_OWNER=root

      NEW_GROUP=other

      WEB_CONTAINER=WS6

      SSL_PASSWORD="ssl_password" #### (If SSL used)

      BASEDIR=/opt/SUNWam

      CONSOLE_HOST=$SERVER_HOST

      CONSOLE_PORT=$SERVER_PORT

      CONSOLE_PROTOCOL=$SERVER_PROTOCOL

      CONSOLE_REMOTE=true

      SERVER_DEPLOY_URI=/amserver

      if [ $DEPLOY_LEVEL -eq 2 -o $DEPLOY_LEVEL -eq 12 ]; then

         CONSOLE_DEPLOY_URI=$SERVER_DEPLOY_URI

      else

         CONSOLE_DEPLOY_URI=/amconsole

      fi

      PASSWORD_DEPLOY_URI=/ampassword

      COMMON_DEPLOY_URI=/amcommon

      DIRECTORY_MODE=4 ####

      DS_PORT=389

      DS_DIRMGRDN="cn=Directory Manager"

      USER_NAMING_ATTR=uid

      ORG_NAMING_ATTR=o

      ORG_OBJECT_CLASS=sunismanagedorganization

      USER_OBJECT_CLASS=inetorgperson

      DEFAULT_ORGANIZATION=

      JAVA_HOME=/usr/jdk/entsys-j2se

      AM_REALM=disabled #### (For legacy use)

      PLATFORM_LOCALE=en_US

      XML_ENCODING=ISO-8859-1

      NEW_INSTANCE=false

      ############### Required for Web Server ###############################

      WS61_INSTANCE=https-COMMS_EX_HOSTNAME_FQDN #### Modify to reflect front-end hostname

      WS61_HOME=/opt/SUNWwbsvr

      WS61_PROTOCOL=$SERVER_PROTOCOL

      WS61_HOST=$SERVER_HOST

      WS61_PORT=$SERVER_PORT

      WS61_ADMINPORT=$ADMIN_PORT

      WS61_ADMIN="admin"

      WS61_IS_SECURE=false

      DIRECTORY_MODE=4

      DS_PORT=389

      DS_DIRMGRDN="cn=Directory Manager"

      USER_NAMING_ATTR=uid

      ORG_NAMING_ATTR=o

      ORG_OBJECT_CLASS=sunismanagedorganization

      USER_OBJECT_CLASS=inetorgperson

      DEFAULT_ORGANIZATION=

      JAVA_HOME=/usr/jdk/entsys-j2se

      AM_REALM=disabled

  5. Make a backup copy of the /etc/opt/sun/identity/AMConfig.properties file. Check the content of the following lines in that file:

    6. com.iplanet.am.directory.host=AM_SERVER_HOSTNAME_FQDN

    com.iplanet.am.server.host=AM_SERVER_HOSTNAME_FQDN

    com.iplanet.am.console.host=AM_SERVER_HOSTNAME_FQDN

    com.iplanet.am.profile.host=AM_SERVER_HOSTNAME_FQDN

    com.iplanet.am.naming.url=http://AM_SERVER_HOSTNAME_FQDN:WEBCONTAINER_PORT/amserver/namings ervice

    com.iplanet.am.notification.url=http://COMMS_EX_HOSTNAME_FQDN:WEBCONTAINER_PORT/notificatio nservice

  6. Run the following command:

    7. /opt/SUNWam/bin/amconfig -s Newly_Created_AMSAMPLESILENT

  7. Make sure the default domain contains the Core and LDAP services, which you can find in the Access Manager console under the Services tab.
  8. Make sure that the uwcauth.properties reads the complete dn for the variable uwcauth.identity.binddn as shown below:

    9. !Bind DN of AdmAdmin

    uwcauth.identity.binddn=uid=amadmin,ou=people,o=usergroup

Problem: User Authentication Failed

Solution: Verify operation of Directory Server, availability of user, baseDN, and LDAP service property values.

  To Troubleshoot Authentication Problems

  1. Verify that the Directory Server is running.

    2. For example:

    /usr/bin/ps -ef | grep slapd

    ./ns-slapd -D /var/opt/mps/serverroot/slapd-host1 -i /var/opt/mps/serverroot/slapd-host1

  2. If necessary, start Directory Server using one of the following commands:

    3. For example, if Directory Server 5.2 is the default version:

    On Solaris: /usr/sbin/directoryserver start

    On Linux: /opt/sun/sbin/directoryserver start

  3. Check that the user ID in question exists in the directory.

    4. For example:

    ldapsearch -h host -p port -D dn -w password -s sub -b basedn "uid=uid"

    This will return the user entry, if it exists, or ’No such object’ if the entry does not exist.

  4. Check the uwcauth.properties file is using the correct baseDN and credentials.

    5. See the following for more information:

    http://docs.sun.com/source/819-0115/config_3.html#wp20397

  5. In an Access Manager deployment, check that the LDAP service property values are valid.
    1. Log in to the Access Manager console as amAdmin.
    2. Under Identity Management, click the appropriate organization.
    3. Choose Services from the View menu.

      4. The services list should have at a minimum Authentication Configuration, and Authentication Modules Core and LDAP. Click the LDAP Properties arrow and verify the information that appears in the Data pane.

    4. If the service is not added, continue with the steps that follow.
    5. Click Add in the Navigation pane.

      6. A list of available services is displayed in the Data pane.

    6. Select the checkbox for Authentication Configuration and click OK.

      7. The Authentication Configuration service will appear in the Navigation pane assuring you that it has been added.

    7. Click the Authentication Configuration Properties arrow.

      8. The Service Instance List is displayed in the in the Data pane.

    8. Click New to add the service instance.

      9. Type the name and click Submit.

Problem: Communications Express Login Page Redirects to the Messenger Express Login Page

Solution: Most likely there is a misconfiguration. Verify the SSO settings. See the following for more information:

http://docs.sun.com/source/819-0115/SSOverview.html

Problem: Unable to Access the Calendar Tab

Solution: Verify that Calendar Server is running, and that the ics.conf file is properly configured.

  To Verify that Calendar Server is Running

  1. Verify that the Calendar Server processes are running.

    2. For example:

    /usr/bin/ps -ef | grep cal

    /opt/SUNWics5/cal/lib/cshttpd -d 3

    /opt/SUNWics5/cal/lib/enpd -p 57997 -c config/ics.conf

    /opt/SUNWics5/cal/lib/csadmind

    /opt/SUNWics5/cal/lib/csnotifyd

  2. If necessary, start Calendar Server.
    1. Change to the sbin directory.

      2. On Solaris: /opt/SUNWics5/cal/sbin

      On Linux: /opt/sun/calendar/cal/sbin

    2. Enter the following command to start Calendar Server.

      3. ./start-cal

  To Verify the ics.conf File Configuration

  1. Change to the /etc/opt/SUNWics5/cal/config directory.
  2. In the ics.conf file, verify that the service.http.allowadminproxy parameter is set to "yes".
  3. Check if the virtual domain is either set to "yes" or "no" in both the ics.conf and uwcauth.properties files. It cannot be "yes" in one file and "no" in the other file.
  4. If you make edits to either the ics.conf or the uwcauth.properties files, restart Calendar Server.

Problem: Log Files Do Not Appear in the /var/opt/SUNWuwc/logs Directory

Solution: Enable logging. See the following for more information:

http://docs.sun.com/source/819-0115/tshooting.html#wp20705

Further Reading

Refer to the Chapter 5, “Troubleshooting” in the Sun Java System Communications Express 6 2005Q1 Administration Guide:

http://docs.sun.com/source/819-0115/tshooting.html

Refer to Chapter 1, “Access Manager 2005Q1 Configuration Scripts,” in the Sun Java System Access Manager Administration Guide, for more information on Access Manager SDK-only configuration installation notes:

http://docs.sun.com/source/817-7647/ConfigScripts.html

Known Issues and Limitations

See the Java Enterprise System Release Notes Collection at the following URL to find out about known problems:

How to Report Problems and Provide Feedback

If you have problems with Communications Express, contact Sun customer support using one of the following mechanisms:

So that we can best assist you in resolving problems, please have the following information available when you contact support:

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions.

To share your comments, go to http://docs.sun.com and click Send Comments. In the online form, provide the document title and part number. The part number is a seven-digit or nine-digit number that can be found on the title page of the book or at the top of the document. For example, the title of this book is Communications Express 2005Q1 Technical Note: Troubleshooting Sun Java System Communications Express, and the part number is 819-3602-10.

Additional Sun Resources

Useful Sun Java System information can be found at the following Internet locations:

Copyright � 2005 Sun Microsystems, Inc. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries.

SUN PROPRIETARY/CONFIDENTIAL.

U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements.

Use is subject to license terms.

This distribution may include materials developed by third parties.

Portions may be derived from Berkeley BSD systems, licensed from U. of CA.

Sun, Sun Microsystems, the Sun logo, Java and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries.

Copyright � 2005 Sun Microsystems, Inc. Tous droits r�serv�s.

Sun Microsystems, Inc. d�tient les droits de propri�t� intellectuels relatifs � la technologie incorpor�e dans le produit qui est d�crit dans ce document. En particulier, et ce sans limitation, ces droits de propri�t� intellectuelle peuvent inclure un ou plusieurs des brevets am�ricains list�s � l'adresse http://www.sun.com/patents et un ou des brevets suppl�mentaires ou des applications de brevet en attente aux Etats - Unis et dans les autres pays.

Propri�t� de SUN/CONFIDENTIEL.

L'utilisation est soumise aux termes du contrat de licence.

Cette distribution peut comprendre des composants d�velopp�s par des tierces parties.

Des parties de ce produit pourront �tre d�riv�es des syst�mes Berkeley BSD licenci�s par l'Universit� de Californie.

Sun, Sun Microsystems, le logo Sun, Java et Solaris sont des marques de fabrique ou des marques d�pos�es de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays.