Sun and OracleChannel SunHow to BuyLog InEnglish

Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide
  Search only this book
Search Help
Contained Within
Find More Documentation
Featured Support Resources
 Download this book in PDF (1816 KB)

Chapter 7 Implementing OpenSSO Enterprise Session Failover

SunTM OpenSSO Enterprise provides a web container independent session failover implementation using Sun Java System Message Queue (Message Queue) as the communications broker and the Oracle Berkeley DB as the session store database. This chapter describes these topics:

Overview of OpenSSO Enterprise Session Failover

OpenSSO Enterprise Session Failover Components

A OpenSSO Enterprise session failover deployment scenario includes these components:

  • Two or more OpenSSO Enterprise instances running on different host servers and configured as a site.

    To configure the OpenSSO Enterprise instances as a site, use one of these methods:

    • When you run the Configurator for the OpenSSO Enterprise instances, specify the same Site Name and load balancer Primary URL on the Site Configuration page for each instance. For information, see Configuring OpenSSO Enterprise With a Custom Configuration.

      or

    • If you did not configure the deployment as a site when you ran the Configurator, use either the Administrator Console or the ssoadm command-line utility to configure the OpenSSO Enterprise instances as a site.

  • Load balancer for the OpenSSO Enterprise instances.

  • Message Queue brokers, running in cluster mode on different servers.

  • Oracle Berkeley DB client (amsessiondb) and database, running on the same servers as the Message Queue brokers.

    OpenSSO Enterprise uses the Oracle Berkeley DB Java Edition as the session data store. For information see http://www.oracle.com/database/berkeley-db/je/index.html.

  • Client requests, which can originate from a Web browser, C or Java application using the OpenSSO Enterprise SDK, or a J2EE or web policy agent.

  • OpenSSO Enterprise configuration data store (not shown in the figure):

    • Sun Java System Directory Server: All OpenSSO Enterprise instances must access the same Directory Server.

      or

    • OpenSSO data store: Instances must be configured for replication and act as a single directory server.

    The configuration data store must be running and accessible in the deployment.

  • OpenSSO Enterprise user data store (not shown in the figure):

    • Sun Java System Directory Server

    • Microsoft Active Directory

    • IBM Tivoli Directory Server

    Note: The OpenSSO user data store is recommended only for prototype, proof of concept (POC), or developer deployments that have a small number of users. It is not recommended for production deployments.

The following figure shows a session failover deployment with three OpenSSO Enterprise instances. (The OpenSSO Enterprise configuration data store and user data store are not shown.)

Figure 7–1 OpenSSO Enterprise Session Failover Components

OpenSSO Enterprise session failover scenario

OpenSSO Enterprise Session Failover Flow

OpenSSO Enterprise session failover follows the Message Queue publish/subscribe delivery model:

  1. When a user initiates, updates, or ends a session, the OpenSSO Enterprise instance publishes a session creation, update, or deletion message to the Message Queue broker cluster.

  2. The Oracle Berkeley DB client (amsessiondb) subscribes to the Message Queue broker cluster, reads the session messages, and stores the session operations in the database.

The OpenSSO Enterprise instances communicate with each other using an internal routing mechanism. If an OpenSSO Enterprise instance goes down due to a single hardware or software problem, a user’s session associated with that instance moves to a secondary OpenSSO Enterprise instance, as follows:

  1. The secondary OpenSSO Enterprise instance publishes a query request to the Message Queue broker cluster to get the user’s session information.

  2. The Oracle Berkeley DB client (amsessiondb) receives the query request, retrieves the corresponding user entry from the session database, and then publishes the user’s session information to the Message Queue broker cluster.

  3. The secondary OpenSSO Enterprise instance receives the response with the user’s session information from the Message Queue broker and continues the session, without losing any session information or requiring the user to login again.

If a Message Queue broker goes down, OpenSSO Enterprise continues to operate in non-session failover mode. When the Message Queue broker is later restarted, OpenSSO Enterprise returns to session failover mode.

For more information about the Message Queue components and the publish/subscribe delivery model, see the Sun Java System Message Queue 4.1 Technical Overview in the following collection:

http://docs.sun.com/coll/1307.3

Installing and Configuring the OpenSSO Enterprise Session Failover Components

To install and configure the OpenSSO Enterprise session failover components, follow this procedure on each server in the Message Queue broker cluster:

Unzipping the ssoSessionTools.zip File

The ssoSessionTools.zip file, which is part of the opensso_enterprise_80.zip file, contains the session failover scripts, JAR, properties, and related files.

ProcedureTo Unzip the ssoSessionTools.zip File

Before You Begin

Unzip the opensso_enterprise_80.zip file. The ssoSessionTools.zip file is then available in the zip-root/opensso/tools directory, where zip-root is where you unzipped opensso_enterprise_80.zip.

  1. Log in to the server where you want to install and configure the session failover components.

  2. Create a new directory to unzip the ssoSessionTools.zip. For example: sfo-zip-root

  3. Copy the ssoSessionTools.zip file to the new directory.

  4. Unzip the ssoSessionTools.zip file in the new directory.

    The following table describes the layout after you unzip the ssoSessionTools.zip file. The directory where you unzip ssoSessionTools.zip is represented by sfo-zip-root.

    sfo-zip-root File or Directory

    Description 

    README.txt

    Description of the ssoSessionTools.zip file.

    setup

    Script to install the session tools on Solaris and Linux systems. 

    setup.bat

    Script to install the session tools on Windows systems. 

    ext directory

    • Message Queue JAR files for Solaris SPARC, Solaris x86, Linux. and Windows systems.

    • Oracle Berkeley DB JAR file (je.jar)

    lib directory

    • JAR file for the setup scripts (am_session_setup.jar)

    • JAR file for the session API (am_sessiondb.jar)

    locale directory

    Properties file for the session API (amSessionDB.properties)

    template directory

    Script templates for Solaris, Linux, and Windows systems. 

Running the Session Failover setup Script

The session failover setup script installs these files:

  • Sun Java System Message Queue JAR and related files

  • Oracle Berkeley DB JAR and related files

  • amsfo, amsfopassword, and amsessiondb scripts on Solaris and Linux system

    amsfo.pl, amsfopassword.bat, and amsessiondb.bat on Windows systems

  • amsfo.conf session failover configuration file

ProcedureTo Run the Session Failover setup Script

Before You Begin

  • The setup script requires Java Runtime Environment (JRE) 1.5 or later. Make sure that your JAVA_HOME environment variable points to your JDK installation directory.

  • On Solaris and Linux systems, you might need to issue the following command before you run the setup script: chmod +x setup

  1. In the directory where you unzipped the ssoSessionTools.zip file, run the setup script.

    On Solaris and Linux systems, use this syntax to run the setup script:

    setup -p|--path dirname

    where dirname is a directory under the current directory where the setup script places the session failover scripts and related files. If dirname does not exist, the script will create the directory for you.

    For example: # ./setup -p sfo

    Considerations:

    • On Windows systems, run the setup.bat script.

    • If you run the setup script without any options, the script prompts you for a path.

    • If the path contains a space, run the setup script without any options and then provide the path when you are prompted.

    • To display the help for the setup script: setup -h|--help

    The setup (or setup.bat) script installs the session failover scripts and related files in the following directories:

    sfo-zip-root Directory

    Script or File 

    jmq/mq

    Message Queue scripts and related files 

    dirname/config/lib

    amsfo.conf session failover configuration file

    dirname/bin

    • Scripts to start and stop the Message Queue broker and amsessiondb client:

      • amsfo on Solaris and Linux systems

      • amsfo.pl on Windows systems

    • Scripts to run the Oracle Berkeley DB client (called by amsfo):

      • amssessiondb on Solaris and Linux systems

      • amssessiondb.bat on Windows systems

    • Scripts to encrypt the Message Queue broker user password:

      • amsfopassword on Solaris and Linux systems

      • amsfopassword.bat on Windows systems

Creating a New User to Connect to the Message Queue Broker (Optional)

OpenSSO Enterprise requires a user and password to connect to the Message Queue broker. Message Queue provides the default guest user with password guest to connect to the broker.

However, if you don’t want to use the guest user, you can create a new user and password using the Message Queue User Manager utility (imqusermgr).

The following example creates a new user named openssomqusr on a Solaris system.

ProcedureTo Create a New User to Connect to the Message Queue Broker

  1. Change to the Message Queue /bin directory. For example:

    # cd sfo-zip-root/sfo/jmq/bin

  2. Create a new broker instance named mqbroker:

    # ./imqbrokerd -name mqbroker -port 7777 &

  3. Check to make sure that the new broker instance is running:

    netstat -an | grep 7777

  4. Create the new Message Queue user and password:

    # ./imqusermgr add -u openssomqusr -p mq-password -i mqbroker

  5. Disable the guest user so guest will not be able to access OpenSSO Enterprise. For example:

    1. # ./imqusermgr update -u guest -a false -i mqbroker

    2. When prompted, reply y to update the guest user:

      Are you sure you want to update user guest? (y/n)[n] y

  6. Stop the broker instance. For example:

    1. # ./imqcmd shutdown bkr -b mq1.example.com:7777 -u admin

    2. When prompted, enter the admin password.

See Also

For more information, see Using the User Manager Utility in Sun Java System Message Queue 4.1 Administration Guide.

Editing the amsessiondb Script (if Needed)

The amsfo script calls amsessiondb to start the Oracle Berkeley DB client (amsessiondb), create the database, and set specific database values. The amsessiondb script contains variables that specify various default paths and directories. For example:

JAVA_HOME=/usr/jdk/entsys-j2se/
AM_HOME=/opensso/tools/sfo-zip-root/sfo
JMS_JAR_PATH=/usr/share/lib
IMQ_JAR_PATH=/usr/share/lib
BDB_JAR_PATH=/usr/share/db.jar
BDB_SO_PATH=/usr/lib

If any of these components are not installed in the directories shown in the amsessiondb script, edit the script and set each variable, as needed, to the path where the component is installed.

Encrypting the Message Queue Broker Password Using the amsfopassword Script (Required)

The amsfopassorwd script accepts the Message Queue broker password in clear text and returns the encrypted password in a file. You can then use this file as input to the amsfo script by setting the PASSWORDFILE variable in the amsfo.conf configuration file.

To run the amsfopassword script, use the following syntax:

amsfopassword
-f|--passwordfile password-file -e|--encrypt clear-text-password

  • password-file is the path to the destination file where amsfopassword stores the encrypted password.

  • clear-text-password is the clear text password that amsfopassword encrypts.

To display help, specify -h|--help.

ProcedureTo Encrypt the Message Queue Broker Password Using the amsfopassword Script

  1. On the server where you ran the setup script, run the amsfopassword script.

    For example, on a Solaris system:

    # cd /sfo-zip-root/sfo/bin
# ./amsfopassword -f /sfo-zip-root/sfo/mqpassword -e cleat-text-password

    You are not required to run amsfopassword as superuser (root).

  2. Use the encrypted password in the mqpassword file as input to the amsfo script by setting the PASSWORDFILE variable in the amsfo.conf file.

    For information about the PASSWORDFILE variable, see Table 7–1.

Running the amsfo Script to Start and Stop the Session Failover Components

The amsfo script (or amsfo.pl on Windows systems) reads variables in the amsfo.conf configuration file and then performs these functions:

  • Starts or stops the Message Queue broker and the Oracle Berkeley DB client (amsessiondb) on each server in the broker list (CLUSTER_LIST variable).

  • Deletes and then recreates the Oracle Berkeley DB database, if requested.

  • Writes the amsessiondb.log, jmq.pid, and amdb.pid files in the /tmp/amsession/logs/ directory. The default log directory is determined by the LOG_DIR variable in the amsfo.conf file.

To run the script on Windows systems, Active Perl version 5.8 or later is required.

To run amsfo, use the following syntax:

amsfo start | stop

The amsfo command then automatically finds the amsfo.conf file.

The following table describes the variables in the amsfo.conf file. Some variables are set when you run the setup (or setup.pl) script. Before you run the amsfo script, set other variables as required for your deployment.

Table 7–1 amsfo.conf Configuration File Parameters

Variable 

Description 

AM_HOME_DIR

Specifies the following directory: sfo-zip-root/dirname

where: 

  • sfo-zip-root is where you unzipped the ssoSessionTools.zip file.

  • dirname is the name you specified when you ran the setup script to install the session failover scripts and related files.

AM_SFO_RESTART

Specifies (true or false) whether the script should automatically restart the Oracle Berkeley DB client (amsessiondb).

The default is true (restart the amsessiondb client).

CLUSTER_LIST

Specifies the Message Queue broker list participating in the cluster. The format is:  

host1:port,host2:port, ... hostn:port

For example:  

mq1.example.com:7777,mq2.example.com:7777,mq3.example.com:7777

You can deploy the Message Queue brokers on the same servers that are running OpenSSO Enterprise instances. However, for improved performance, consider installing the brokers on different servers. 

DATABASE_DIR

Specifies the directory where the session database files will be created.  

Default: /tmp/amsession/sessiondb

DELETE_DATABASE

Specifies (true or false) whether the script should delete and then create a new database each time the Oracle Berkeley DB client (amsessiondb) is restarted.

Default: true

LOG_DIR

Specifies the location of the log directory.  

Default: /tmp/amsession/logs

START_BROKER

Specifies (true or false) whether the Message Queue broker should be started with the amsessiondb process on the same server:

true - The Message Queue broker will run on the same server as the amsessiondb process.

false - The Message Queue broker and the amsessiondb process will run on different servers.

Default: true

BROKER_INSTANCE_NAME

Specifies the name of the Message Queue broker instance to start.  

For example: mqbroker

BROKER_PORT

Specifies the port for the local Message Queue broker instance.  

Default: 7777 

BROKER_VM_ARGS

Specifies the Java VM arguments. Set to a maximum of 1024m, based on the system resources.

Default: "-Xms256m -Xmx512m"

USER_NAME

Specifies the user name used to connect to the Message Queue broker. 

Default: guest

If you specified a different user name. as described in Creating a New User to Connect to the Message Queue Broker (Optional), set USER_NAME to that name.

PASSWORDFILE

Location of the password file that contains the encrypted password used to connect to the Message Queue broker. To generate the encrypted password, use the amsfopassword script, as described in Encrypting the Message Queue Broker Password Using the amsfopassword Script (Required).

Default: sfo-zip-root/dirname/.password

AMSESSIONDB_ARGS

amsessiondb script arguments.

The amsessiondb script is called by the amsfo (or amsfo.pl) script. To determine the list of arguments, run: amsession db -h

ProcedureTo Run the amsfo Script

Before You Begin

Stop each of the OpenSSO Enterprise instances in the session failover deployment.

  1. Set the variables in the amsfo.conf file, as required for your deployment.

    For a description of all variables, see Table 7–1.

  2. Run the amsfo script on Solaris or Linux systems or the amsfo.pl script on Windows systems.

    For example, to start the session failover components on a Solaris system:

    # cd /sfo-zip-root/sfo/bin
# ./amsfo start

    The amsfo command then automatically finds the amsfo.conf file and displays status information as it runs.

  3. To check the results, see the /var/tmp/amsfo.log file.

Configuring Session Failover in the OpenSSO Enterprise Console

ProcedureTo Configure Session Failover in the OpenSSO Enterprise Console

Before You Begin

If necessary, start each OpenSSO Enterprise instance in the session failover deployment.

  1. Log in to the OpenSSO Enterprise Console as amadmin.

  2. Click Configuration, Global, and then Session.

  3. Under Secondary Configuration Instance, click the site Name for the session failover configuration.

  4. On the Edit Sub Configuration page, specify the Global Attributes.

    When applicable, use the same values for the corresponding parameters in the amsfo.conf configuration file.

    • Session Store User is the user that connects to the Message Queue broker. For example: openssomquser

    • Session Store Password (and confirmation) is the password for the user that connects to the Message Queue broker.

    • Maximum Wait Time should be the default value of 5000 milliseconds.

    • Database Url is the Message Queue broker address list, which is the list of Message Queue brokers participating in the cluster. For example:

      mq1.example.com:7777,mq2.example.com:7777,mq3.example.com:7777

    • Session Failover Enabled must be Enabled.

  5. Check Save and log out of the console.

  6. Restart each OpenSSO Enterprise instance in the site for the new session failover values to take effect.