Troubleshooting Sun Java System Communications Express

Troubleshooting Sun Java System Communications Express

This technical note describes how to troubleshoot common installation and configuration problems for Sun Java System Communications Express 6 2005Q4.

The component products affected by this technical note are:

This technical note contain the following sections:

Technical Note Revision History


Description of Changes 

August 2, 2006 

Corrected Web Server parameters in the amconfigcommx file. Corrected file name to /etc/opt/SUNWam/config/ and parameter to in Step 5 of the task “To Troubleshoot Communications Express.”

June 2, 2006 

Re-issue of this technical note for Sun Java Enterprise System 2005Q4. 

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.

ProcedureTo 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. 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: host1 loghost

    SolarisTM 10 Operating System (OS) hosts: 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:

    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

    Solaris 10 hosts: 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 6.1 2005Q4 SP5) server.xml file with all required jar file settings

  2. Pointing the Communications Express Identity SSO to the external Access Manager from the 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

ProcedureTo 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.

    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).

    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 =
    [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).

    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 Problem: Web Server Exceptions.

  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.

      # cd /opt/SUNWam/bin

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

      # 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):

      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)
      DS_HOST=DS_HOSTNAME_FQDN  #### (Directory Server fully qualified domain name)
      AMLDAPUSERPASSWD=AMLDAPUSERPASSWORD #### (Modify to reflect default domain)
      #### Get from file of fully installed Access Manager host
      SSL_PASSWORD="ssl_password" #### (If SSL used)
      if [ $DEPLOY_LEVEL -eq 2 -o $DEPLOY_LEVEL -eq 12 ]; then
      DIRECTORY_MODE=4  ####
      DS_DIRMGRDN="cn=Directory Manager"
      AM_REALM=disabled #### (For legacy use)
      ############### Required for Web Server  ###############################
      WS61_INSTANCE=https-COMMS_EX_HOSTNAME_FQDN ####Modify to reflect front-end hostname
      WS61_HOST=COMMS_EX_HOST ####NOT $SERVER_HOST in an AM SDK remote AM Server configuration
      WS61_PORT=COMMS_EX_PORT ####NOT $SERVER_PORT in an AM SDK remote AM Server configuration
      DS_DIRMGRDN="cn=Directory Manager"
  5. Make a backup copy of the /etc/opt/SUNWam/config/ file. Check the content of the following lines in that file:
  6. Run the following command:

    /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 reads the complete dn for the variable uwcauth.identity.binddn as shown below:

    !Bind DN of AdmAdmin

Problem: User Authentication Failed

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

ProcedureTo Troubleshoot Authentication Problems

  1. Verify that the Directory Server is running.

    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:

    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.

    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 file is using the correct baseDN and credentials.

    See the following for more information:

    Communications Express Configuration Files in Sun Java System Communications Express 6 2005Q4 Administration Guide

  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.

      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.

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

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

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

    7. Click the Authentication Configuration Properties arrow.

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

    8. Click New to add the service instance.

      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:

Chapter 1, Overview of Communications Express, in Sun Java System Communications Express 6 2005Q4 Administration Guide

Problem: Unable to Access the Calendar Tab

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

ProcedureTo Verify that Calendar Server is Running

  1. Verify that the Calendar Server processes are running.

    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
  2. If necessary, start Calendar Server.

    1. Change to the sbin directory.

      On Solaris: /opt/SUNWics5/cal/sbin

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

    2. Enter the following command to start Calendar Server.


ProcedureTo 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 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 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:

Log Files in Sun Java System Communications Express 6 2005Q4 Administration Guide

Further Reading

Refer to Chapter 5, Troubleshooting, in Sun Java System Communications Express 6 2005Q4 Administration Guide.

Refer to Chapter 1, Access Manager 7 2005Q4 Configuration Scripts, in Sun Java System Access Manager 7 2005Q4 Administration Guide, for more information on Access Manager SDK-only configuration installation notes.

Documentation, Support, and Training

The Sun web site provides information about the following additional resources:

Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note –

Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, go to and click Send Comments. In the online form, provide the full document title and part number. The part number is a 7-digit or 9-digit number that can be found on the book's title page or in the document's URL. For example, the part number of this book is 819-5198.