Sun Java System Reference Configuration Series: Portal Service on Application Server Cluster

Implementing Session Failover for Access Manager

The implementation of session failover involves establishing a persistence layer that uses Message Queue to write session information to a replicated Access Manager session database (see Figure 5–1). If the Access Manager instance that owns a session fails, the session information is retrieved and passed to another Access Manager instance.

You implement session failover by first creating what is called a secondary configuration instance. The secondary configuration instance specifies values that are needed to store and recover persistent session information. You then use Access Manager utilities to set up the session persistence database.


Note –

Access Manager provides the amsfoconfig script, which performs some of the procedures that are needed to implement service failover and session failover. However, the amsfoconfig script is not used in this reference configuration because service failover and session failover are independent functions that are best implemented and verified separately.


ProcedureTo Create a Secondary Configuration Instance

  1. Log in to the Access Manager Console.

    1. Confirm that Application Server on am1 is running.

      # /opt/SUNWappserver/appserver/bin/asadmin list-domains --user admin --terse=true

      When prompted, type the app-server-admin-password.

      If the Application Server is not running, then start it.

      # /opt/SUNWappserver/appserver/bin/asadmin start-domain --user admin domain1

      When prompted, type the app-server-admin-password.

    2. Start a browser.

    3. Go to the Access Manager login page:

      http://am.pstest.com/amconsole

      The Access Manager Console login page opens.

    4. Log in to the Access Manager Console by typing the following values and clicking Login.

      Input Field 

      Value 

      User ID 

      amadmin

      Password 

      access-manager-admin-password

      The Access Manager Console opens.

  2. In the Access Manager Console main page, click the Service Configuration tab.

  3. In the Service Configuration tab, navigate to the New Secondary Configuration dialog box.

    1. Locate the Service Name pane on the left side of the tab.

    2. In the Service Name pane, scroll down and click the arrow to the right of Session.

      The Session detail is displayed in the right pane.

    3. In the Session detail pane, locate the Secondary Configuration Instances and click New.

      The New Secondary Configuration dialog box opens.

  4. In the New Secondary Configuration dialog box, type the following values and click Add.

    Input Field 

    Value 

    Instance Name 

    http://am.pstest.com:80 (this is the URL for the load balancer)

    Session Store User 

    am-svr-usr (the user name you establish in the following procedure for connecting to the Message Queue Server)

    Session Store Password 

    am-svr-usr-password (the password you set in the following procedure)

    Maximum Wait Time 

    5000

    Database URL 

    am1.pstest.com:7777,am2.pstest.com:7777 ( the list of broker addresses in the Message Queue broker cluster)

    The Secondary Configuration dialog box closes.

  5. Click Save to save your changes.

ProcedureTo Configure Session Failover on am1

  1. Shut down the Access Manager instance on am1.

    You shut down the Access Manager instance by shutting down the Application Server instance in which it runs.

    # /opt/SUNWappserver/appserver/bin/asadmin stop-domain

    The response should resemble the following:

    Domain domain1 stopped.

  2. Add the required Java Archive (JAR) files to the web container classpath.

    1. Start a browser.

    2. Go to the following URL:

      https://am1.pstest.com:4849

      The Application Server login page opens.

    3. Log in to the Application Server Admin Console by typing the following values and clicking Login.

      Input Field 

      Value 

      User ID 

      admin

      Password 

      app-server-admin-password

      The Application Server Admin Console opens.

    4. Click on the small triangle next to Configurations on the Common Tasks panel.

      The configurations are expanded.

    5. Click on the small triangle next to server-config.

      The pscluster configuration is expanded.

    6. Click on JVM Settings.

      The frame on the right shows the configuration options.

    7. In the right frame, select the Path Settings tab.

      The JVM Classpath Settings panel opens.

    8. Add /usr/share/lib/imq.jar and /usr/share/lib/jms.jarto the Classpath Suffix list.

    9. Click Save.

  3. Create a Message Queue user for Access Manager session failover.

    This user will be used internally to send and retrieve session information. To use the imqusermgr utility in the following steps, you must first create a default user repository, which is done automatically the first time you start the Message Queue broker.

    1. Start the Message Queue broker to be used for session failover.

      # bash

      This opens the bash shell, which supports background processes.

      # /usr/bin/imqbrokerd -name aminstance -port 7777 &


      Note –

      Before using port 7777, check that it is not being used by some other process.


      The output should resemble the following:


      [25/Oct/2007:16:17:00 MEST] 
      ================================================================================ 
      Sun Java(tm) System Message Queue 3.7 
      Sun Microsystems, Inc. 
      Version:  3.7 UR2  (Build 3-b) 
      Compile:  Mon May  7 22:37:30 PDT 2008 
      Copyright (c) 2007 Sun Microsystems, Inc.  All rights reserved. 
      SUN PROPRIETARY/CONFIDENTIAL.  Use is subject to license terms. 
      This product includes code licensed from RSA Data Security.
      ================================================================================
      Java Runtime: 1.5.0_12 Sun Microsystems Inc. /usr/jdk/instances/jdk1.5.0/jre 
      [25/Oct/2007:16:17:00 MEST]    IMQ_HOME=/
      [25/Oct/2007:16:17:00 MEST] IMQ_VARHOME=/var/imq 
      [25/Oct/2007:16:17:00 MEST] SunOS 5.10 sparc am1(24 cpu) root
      [25/Oct/2007:16:17:00 MEST] Max file descriptors: 65536 (65536) 
      [25/Oct/2007:16:17:00 MEST] Java Heap Size: max=174784k, current=35328k
      [25/Oct/2007:16:17:00 MEST] Arguments:
      [25/Oct/2007:16:17:00 MEST] [B1060]: Loading persistent data... 
      [25/Oct/2007:16:17:00 MEST] Using built-in file-based persistent store: 
         /var/imq/instances/aminstance/ 
      [25/Oct/2007:16:17:01 MEST] [B1039]: Broker "aminstance@am1:7777" ready.
    2. Change the default Message Queue administrative user password.

      # /usr/bin/imqusermgr update -i aminstance -u admin -p MQ-admin-psssword

      The response should resemble the following:


      User repository for broker instance: aminstance 
      Are you sure you want to update user admin? (y/n) y 
      User admin successfully updated. 
    3. Add a new Message Queue user to be used for Access Manager session failover..

      # /usr/bin/imqusermgr add -i aminstance -u am-svr-usr -p am-svr-usr-password

      The response should resemble the following:


      User repository for broker instance: aminstance 
      User amSvrUsr successfully added. 
    4. Delete the default guest user.

      # /usr/bin/imqusermgr update -i aminstance -u guest -a false

      The response should resemble the following:


      User repository for broker instance: aminstance 
      Are you sure you want to update user guest? (y/n) y 
      User guest successfully updated.
    5. Shut down the Message Queue broker.

      # imqcmd shutdown bkr -b am1:7777 -u admin

      When prompted, type the MQ-admin-password.

  4. Check the installation directories in the amsessiondb file.

    1. In a text editor, open the following file:

      /opt/SUNWam/bin/amsessiondb

    2. If you have installed Access Manager, JDK, or Message Queue in non-default directories, you must make the appropriate changes to the amsessiondb file.

  5. Generate an encrypted password file.

    # /opt/SUNWam/bin/amsfopassword -f /opt/SUNWam/.password -e am-svr-usr-password


    os.name=SunOS
    SUCCESSFUL
  6. Edit the amsfo.conf file.

    1. Open the amsfo.conf file in a text editor.

      The file, which is used to configure Access Manager session failover, is located at:

      /opt/SUNWam/lib/amsfo.conf

    2. Type the following values:

      Parameter 

      Value 

      AM_HOME_DIR 

      /opt/SUNWam

      AM_SFO_RESTART 

      true

      CLUSTER_LIST 

      am1.pstest.com:7777,am2.pstest.com:7777

      DATABASE_DIR 

      /tmp/amsession/sessiondb

      LOG_DIR 

      /tmp/amsession/logs

      START_BROKER 

      true

      BROKER_INSTANCE_NAME 

      aminstance

      BROKER_PORT 

      7777

      USER_NAME 

      am-svr-usr

      lbServerPort 

      80

      lbServerProtocol 

      http

      lbServerHost 

      am.pstest.com:80

      SiteID 

      10

      JAVA_HOME 

      /usr/jdk/entsys-j2se

  7. Run the amsfo script:

    # /opt/SUNWam/bin/amsfo start

    The script starts the Message Queue broker on am1, the Access Manager session database on am1, and initializes the Message Queue and Access Manager session database clients needed to implement session persistence.

  8. Verify that the Message Queue connections are working.

    Open the following log file:

    /tmp/amsession/logs/amsessiondb.log

    Check for errors in the file.

  9. Restart the Access Manager instance on am1.

    You start the Access Manager instance by starting the Application Server instance in which it runs.

    # /opt/SUNWappserver/appserver/bin/asadmin start-domain --user admin domain1

    When prompted, type the app-server-admin-password.

ProcedureTo Configure Session Failover on am2

  1. Repeat the procedure that appears in To Configure Session Failover on am1, except for the following:

    Replace all occurrences of am1 with am2.

ProcedureTo Verify Session Failover

In this procedure, a user logs in to the Access Manager Console, and you determine the Access Manager instance that is handling the Access Manager Console request. You then simulate a failure of that instance, have the user make another Access Manager Console request, and note which Access Manager instance is handling the second request. If session failover is working properly, the Access Manger service fails over to the failover Access Manager instance without the user having to log in a second time.

  1. Log in to the Access Manager Console, if you are not already logged in.

    1. Start a browser.

    2. Go to the Access Manager Console login page by using the load balancer URL

      http://am.pstest.com/amconsole

      The Access Manager Console login page opens.

    3. Log in to the Access Manager Console by typing the following values and clicking Login.

      Input Field 

      Value 

      User ID 

      amadmin

      Password 

      access-manager-admin-password

      The Access Manager Console opens.

  2. Determine which Access Manager instance handled the login request in Step 1.

    1. Click on the Current Sessions tab.

      The left panel shows both Access Manager instances: http://am1.pstest.com:80 and http://am2.pstest.com:80

    2. Check for an amadmin session on each instance.

      You can display the sessions existing on each instance by clicking on the small triangle adjacent to each.

    3. Note the instance that owns the amadmin session.

  3. Simulate a failure of the Access Manager instance that was noted in Step 2.

    Failure of an Access Manager instance can result from a computer failure, a software failure, or a network failure. The method employed for simulating a failure in this session failover verification procedure is to shut down the Access Manager instance (by shutting down the Application Server instance in which it runs). Additionally, you could also simulate failure by unplugging the network cable or disabling the interface.

    Run the following command on the computer (am1 or am2) hosting the instance identified in Step 2.

    # /opt/SUNWappserver/appserver/bin/asadmin stop-domain

  4. Perform another Console request.

    For example, click the Identity Management tab, then click the pstest link.

    If session failover is working correctly, the Console session will fail over to the other Access Manager instance and display a list of Organization Aliases in the right pane. The fact that you did not have to log in again confirms that session failover is working.

  5. Confirm that your Access Manager Console session is now owned by the other Access Manager instance.

    You can do this step by repeating Step 2 or by checking the access logs on your web containers.

  6. Recover the simulated failure of your original Access Manager instance.

    Run the following command on the computer (am1 or am2) on which the Application Server instance was shut down in Step 3.

    # /opt/SUNWappserver/appserver/bin/asadmin start-domain --user admin domain1

    When prompted, type the app-server-admin-password.