Access Manager provides a web container independent session failover implementation using Sun Java System Message Queue (Message Queue) as the communications broker and the Berkeley DB as the session store database. This chapter describes these topics:
Figure 6–1 shows an Access Manager session failover deployment scenario that includes these components:
Three Access Manager instances, running on different host servers on supported web containers. All Access Manager instances access the same Directory Server (not shown in the figure).
Message Queue brokers, running in cluster mode on different servers.
Berkeley DB client (amsessiondb), running on the same servers as the Message Queue brokers.
Load balancer to improve performance and security.
Client requests can originate from a Web browser, C or Java application using the Access Manager SDK, or a J2EE/web agent.
The following table describes how to install the components required for Access Manager session failover using the Java ES installer. If you are deploying an Access Manager WAR file, see Chapter 12, Deploying Access Manager as a Single WAR File.
Table 6–1 Installation of Access Manager Session Failover Components Using the Java ES Installer
Component |
Installation |
---|---|
Sun Java System Access Manager |
Install the first instance of Access Manager on each host server using the Java ES installer. The installer adds the required session failover Solaris packages or Linux RPMs. Installation reference: Sun Java Enterprise System 5 Installation Guide for UNIX or the Sun Java Enterprise System 5 Installation Guide for Microsoft Windows When you install Access Manager using the Java ES installer, select either Realm Mode or Legacy Mode. Access Manager session failover is supported in both modes. After you run the Java ES installer, run the amconfig script to:
Reference: Chapter 3, Deploying Multiple Access Manager Instances |
Sun Java System Message Queue |
Install Message Queue using the Java ES installer. Installation reference: Sun Java Enterprise System 5 Installation Guide for UNIX or the Sun Java Enterprise System 5 Installation Guide for Microsoft Windows Message Queue documentation: http://docs.sun.com/coll/1307.2 |
Session Failover Client Berkeley DB |
Install the Session Failover Client using the Java ES installer. On the installer Component Selection page, check Session Failover Client. The Java ES installer adds the Access Manager packages or RPMs required for the Berkeley DB and amsessiondb client:
You can install the Session Failover Client on a server that is running Access Manager; however, for improved performance, consider installing the subcomponent on a server that is not running Access Manager. |
In a multiple server deployment where all Access Manager instances share the same Directory Server, all Access Manager instances must use the same password encryption key value. When you install the first Access Manager instance, save the password encryption key value from the am.encryption.pwd property in the AMConfig.properties file. Then, when you run the Java ES installer or amconfig script to install or configure Access Manager instances on other host servers, use this same value for the password encryption key.
Configuring Access Manager for session failover involves these steps:
Each step is described in detail in the following sections.
To determine if session failover is enabled for a deployment, change the com.iplanet.services.debug.level property from error to message in the AMConfig.properties file. Then, check the amSession logs, depending on your platform:
Solaris systems: /var/opt/SUNWam/debug directory
Linux and HP-UX systems: /var/opt/sun/identity/debug directory
Windows systems: javaes-install-dir\identity\debug
javaes-install-dir represents the Java ES 5 installation directory. The default value is C:\Program Files\Sun\JavaES5.
On each host server that is running an Access Manager instance, disable cookie encoding as follows, depending on the web container:
If Web Server is the web container, make sure the following property in the AMConfig.properties file is set to false (which is the default value set by the Java ES installer):
com.iplanet.am.cookie.encode=false
In the sun-web.xml file in directories that begin with https-, set the encodeCookies property to false. For example:
<sun-web-app> <property name="encodeCookies" value="false"/> ... </sun-web-app>
If Sun Java System Application Server, BEA WebLogic, or IBM WebSphere Application Server is the web container, set the following property in the AMConfig.properties file to false:
com.iplanet.am.cookie.encode=false
The Access Manager client should not do any cookie encoding or decoding. A remote SDK client must be in sync with the Access Manager server side settings, either in the AMConfig.properties file or the web container’s sun-web.xml file.
On each host server that is running an Access Manager instance, use the web container Admin console or CLI command to add the installed locations of the imq.jar and jms.jar files to the server classpath.
If you don’t want to use the guest user as the Message Queue user name and password, add a new user and password to connect to the Message Queue broker on servers where Message Queue is installed. For example, on Solaris systems, to add a new user named amsvrusr:
# /usr/bin/imqusermgr add -u amsvrusr -p password
Then, make the guest user inactive by issuing the following command:
# /usr/bin/imqusermgr update -u guest -a false
The amsessiondb script is called by the amsfo script to start the Berkeley DB client (amsessiondb), create the database, and set specific database values. The script contains variables that specify various default paths and directories:
JAVA_HOME=/usr/jdk/entsys-j2se/ IMQ_JAR_PATH=/usr/share/lib JMS_JAR_PATH=/usr/share/lib BDB_JAR_PATH=/usr/share/db.jar BDB_SO_PATH=/usr/lib AM_HOME=/opt/SUNWam
If any of these components are not installed in their default directories, edit the amsessiondb script and set the variables, as needed, to the correct locations.
Access Manager provides the amsfoconfig script to configure an Access Manager deployment for session failover.
On Windows systems, Access Manager provides the amsfo.pl script and amsfo.conf file to configure an Access Manager deployment for session failover. To run this script, Active Perl version 5.8 or later is required.
To run the amsfoconfig script, an Access Manager deployment must meet the following requirements:
Two or more Access Manager instances must be installed and configured in the deployment, but the deployment cannot be configured as a site. If the amsfoconfig script determines that the deployment is configured as a site or that any of the server entries in the platform server list are site enabled, the script displays a message and exits. To configure session failover manually, see Configuring Session Failover Manually
The Java Message Queue (MQ) broker must be installed and configured on at least two servers in the deployment.
The Berkeley DB client and database must be installed and configured in the deployment.
Directory Server must be running, accessible to the script, and configured with Access Manager data.
The amsfoconfig script reads the amsfo.conf configuration file and then configures an Access Manager deployment for session failover by performing these functions:
Configures a new site. The script uses the Access Manager instances in the platform server list and the load balancer information from the amsfo.conf file to create a new site for the Access Manager session failover deployment. The script modifies the existing platform server list, so that after the site is configured, all server entries under the platform server list then belong to the site.
For example, http://server1.example.com:80|01 changes to http://server1.example.com:80|01|10, if the default value of 10 is used as the SiteID.
Modifies the existing Realm/DNS alias list. The script appends the host name of the load balancer to the list. This host name is obtained from the lbServerHost variable of the amsfo.conf file.
Loads session failover configuration XML into Directory Server. The script dynamically generates the session configuration XML file based on the configuration information and loads the generated XML into Directory Server. This information corresponds to the Secondary Configuration Instance under Session in the Access Manager Console.
The following table lists the Access Manager session failover scripts and configuration files.
Table 6–2 Access Manager Session Failover Scripts and Configuration Files
Name |
Description and Location |
---|---|
amsofconfig |
Script to configure Access Manager for session failover. Solaris systems: AccessManager-base/SUNWam/bin Linux systems: AccessManager-base/identity/bin |
amsfo |
Script to start and stop the Message Queue broker and amsessiondb client. Solaris systems: AccessManager-base/SUNWam/bin Linux systems: AccessManager-base/identity/bin |
amsfopassword |
Script to generate the encrypted Message Queue broker user password. Solaris systems: AccessManager-base/SUNWam/bin Linux and HP-UX systems: AccessManager-base/identity/bin Windows systems: javaes-install-dir\identity\bin javaes-install-dir represents the Java ES 5 installation directory. The default value is C:\Program Files\Sun\JavaES5. |
amsfo.conf |
Session failover configuration file. Solaris systems: AccessManager-base/SUNWam/lib Linux and HP-UX systems: AccessManager-base/sun/identity/lib Windows systems: javaes-install-dir\identity\lib javaes-install-dir represents the Java ES 5 installation directory. The default value is C:\Program Files\Sun\JavaES5. |
amProfile.conf |
Session failover environment file. Solaris systems: etc/opt/SUNWam/config Linux and HP-UX systems: etc/opt/sun/identity/config Windows systems: javaes-install-dir\identity\config javaes-install-dir represents the Java ES 5 installation directory. The default value is C:\Program Files\Sun\JavaES5. |
AccessManager-base represents the base installation directory for Access Manager. The default values are: Solaris systems: /opt Linux and HP-UX systems: /opt/sun |
The amsfoconfig script configures Access Manager for session failover.
Log in as or become superuser (root).
Set the variables in the amsfo.conf file, as described in Table 6–3.
Run the amsfoconfig script (or amsfo.pl script on Windows systems) . For example, on a Solaris system with Access Manager installed in the default directory:
# cd /opt/SUNWam/bin # ./amsfoconfig
The script displays status information as it runs.
When the script prompts you, enter the following passwords:
Access Manager administrator (amAdmin) password
Message Queue broker user password
To check the results, see the /var/tmp/amsfoconfig.log file.
The following table describes the variables in the amsfo.conf file that are used by the amsfoconfig script. Set these variables as needed for your deployment before you run the amsfoconfig script.
Table 6–3 Variables in the amsfo.conf File Used by the amsfoconfig Script
Variable |
Description |
---|---|
CLUSTER_LIST |
Message Queue broker list participating in the cluster. The format is: host1:port,host2:port,host3:port For example: jmq1.example.com:7777,jmq2.example.com:7777,jmq3.example.com:7777 There is no default. |
lbServerPort |
Port for the load balancer. The default is 80. |
lbServerProtocol |
Protocol (http or https) used to access the load balancer. The default is http. |
lbServerHost |
Name of the load balancer. For example: lbhost.example.com |
SiteID |
Identifier for the new site (and the load balancer) that the amsfoconfig script will create. SiteID can be any value greater than the Server IDs that already exist in the platform server list. The default is 10. |
The following example shows a sample run of the amsfoconfig script.
==================================================================== Welcome to Sun Java System Access Manager 7 2005Q4 Session Failover Configuration Setup script. ==================================================================== ==================================================================== Checking if the required files are present... ==================================================================== Running with the following Settings. ------------------------------------------------- Environment file: /etc/opt/SUNWam/config/amProfile.conf Resource file: /opt/SUNWam/lib/amsfo.conf ------------------------------------------------- Using /opt/SUNWam/bin/amadmin Validating configuration information. Done... Please enter the LDAP Admin password: (nothing will be echoed): password1 Verify: password1 Please enter the JMQ Broker User password: password2(nothing will be echoed): Verify: password2 Retrieving Platform Server list... Validating server entries. Done... Retrieving Site list... Validating site entries. Done... Validating host: http://amhost1.example.com:80|01 Validating host: http://amhost2.example.com:80|02 Done... Creating Platform Server XML File... Platform Server XML File created successfully. Creating Session Configuration XML File... Session Configuration XML File created successfully. Creating Organization Alias XML File... Organization Alias XML File created successfully. Loading Session Configuration schema File... Session Configuration schema loaded successfully. Loading Organization Alias List File... Organization Alias List loaded successfully. Loading Platform Server List File... Platform Server List server entries loaded successfully. Please refer to the log file /var/tmp/amsfoconfig.log for additional information. ################################################################### Session Failover Setup Script. Execution end time 12/12/06 15:03:30 ###################################################################
Access Manager provides the amsfo script to perform these functions:
Start and stop the Java Message Queue (MQ) broker specified for the session failover deployment.
Start and stop the amsessiondb client specified for the session failover deployment.
Read the amsfo.conf configuration file and take specific actions based on variables in the file. For example, you can have the script first delete and then recreate the Berkeley DB database.
Write 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 start the Access Manager session failover components, follow this sequence:
Set the variables in the in the amsfo.conf configuration file, as required by your deployment. For a description of these variables, see Table 6–3.
Run the amsfo script to start the Java Message Queue (MQ) broker and the amsessiondb client. For detailed information, see Running the amsfo Script.
Start each Access Manager instance by starting the respective web container.
The amsfo script includes the start and stop options:
Usage: amsfo { start | stop }
Log in as or become superuser (root).
Set the variables in the amsfo.conf file, as required for your deployment. For a description of these variables, see Table 6–4.
Run the script. For example, to start the session failover components on a Solaris system with Access Manager installed in the default directory:
# cd /opt/SUNWam/bin # ./amsfo start
To check the results of the script, see the /tmp/amsession/logs/amsessiondb.log file.
Set the following variables as needed for your deployment before you run the amsfo script.
Table 6–4 amsfo.conf Configuration File
Variable |
Description |
---|---|
AM_HOME_DIR |
Access Manager default installation directory. The default directory depends on the platform: Solaris systems: AccessManager-base/SUNWam Linux systems: AccessManager-base/identity AccessManager-base represents the base installation directory for Access Manager. The default values are /opt on Solaris systems and /opt/sun on Linux systems. |
AM_SFO_RESTART |
Specifies (true or false) whether the script should automatically restart the amsessiondb client. The default is true (restart the amsessiondb client). |
CLUSTER_LIST |
Message Queue broker list participating in the cluster. The format is: host1:port,host2:port,host3:port For example: jmq1.example.com:7777,jmq2.example.com:7777,jmq3.example.com:7777 There is no default. |
DATABASE_DIR |
Directory where the session database files will be created. The default is "/tmp/amsession/sessiondb". |
DELETE_DATABASE |
Specifies (true or false) whether the script should delete and then create a new database when the amsessiondb process is restarted. The default is true. |
LOG_DIR |
Location of the log directory. The default is "/tmp/amsession/logs". |
START_BROKER |
Specifies (true or false) whether the Message Queue broker should be started with the amsessiondb process. Set this variable as follows: true - The Message Queue broker will run on the same machine as the amsessiondb process. false - The Message Queue broker and the amsessiondb process will run on different machines. The default is true. |
BROKER_INSTANCE_NAME |
Name of the Message Queue broker instance to start. The default is aminstance. |
BROKER_PORT |
Port for the local Message Queue broker instance. The default is 7777. |
BROKER_VM_ARGS |
Java VM arguments. The default is "-Xms256m -Xmx512m", which sets the maximum value based on the system resources. |
USER_NAME |
User name used to connect to the Message Queue broker. The default is guest. If you specified a different user name under step 3–Add a New User in the Message Queue Server, 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 amsfopassword Script The default is $AM_HOME_DIR/.password, where $AM_HOME_DIR specifies the Access Manager default installation directory. |
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 (PASSWORDFILE variable).
The amsfopassword script is located in the following directory:
Solaris systems: AccessManager-base/SUNWam/bin
Linux systems: AccessManager-base/identity/bin
The default AccessManager-base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.
Use the following syntax to run the amsfopassword script.
amsfopassword -f filename | --passwordfile filename -e password | --encrypt password amsfopassword -h | --help
The following table describes the amsfopassword script arguments.
Table 6–5 amsfopassword Script Arguments
Argument |
Description |
---|---|
-f filename | --passwordfile filename |
Path to the destination file where amsfopassword stores the encrypted password. |
-e password | --encrypt password |
Clear text password that amsfopassword encrypts. |
-h | --help |
Display the amsfopassword command usage and then exit. |
Log in as or become superuser (root).
Run the amsfopassword script. For example, on a Solaris system with Access Manager installed in the default directory:
# cd /opt/SUNWam/bin # ./amsfopassword -f /opt/SUNWam/.password -e mypassword
Use the encrypted password in the /opt/SUNWam/.password file as input to the amsfo script (PASSWORDFILE variable)
In some situations, you might need to manually configure Access Manager for session failover. For example, you do not plan to run the amsfoconfig script. Or, the amsfoconfig script exited with one of the following messages before finishing the configuration: “Site is already configured” or “Server entry is already site configured”.
These steps describe how to manually configure Access Manager for session failover:
3–Create a New Secondary Configuration Instance for the Load Balancer
4–Perform Session Failover Miscellaneous Configuration Tasks
These steps are equivalent to the previous steps that described how to install the required components, configure session failover using the amsfoconfig script and then start the various components.
Install all components in the deployment, including Access Manager instances, load balancer, Message Queue, and the Berkeley DB client. For more information, see Installing the Session Failover Components.
If you do not plan to run the amsfoconfig script, which configures multiple Access Manager instances and a load balancer as a site, you must configure the deployment, as described in Configuring an Access Manager Deployment as a Site.
To create a new secondary configuration instance for your load balancer, follow these steps:
Log in to the Access Manager 7.1 Console as amAdmin.
Click Configuration, Global Properties, Session, and then Secondary Configuration Instance.
c. Click New, and add the following values:
Name. Load balancer URL. For example: http://lb.example.com:80
Session Store User. Name you are using to connect to the Message Queue Server (if other than guest).
Session Store Password. Password for the Session Store User.
Maximum Wait Time. 5000 (Use the default unless you require another value).
Database Url: Message Queue broker address list. For example:
mqsvr1.example.com:7777,mqsvr2.example.com:7777,mqsvr3.example.com:7777
The default Message Queue port is 7676. If you are using Application Server as the web container, however, consider using another port, because port 7676 might already be in use by Application Server. For the range of the valid port numbers, refer to the Message Queue documentation.
Click Add to save your changes.
Perform the following tasks (which are the same as if you are running the amsfoconfig script):
Disable Cookie Encoding.
Edit the Web Container server.xml File.
Add a New User in the Message Queue Server.
Edit the amsessiondb Script (if needed).
Run the amsfo script to start the Message Queue broker and Berkeley DB client (amsessiondb). Then, start each Access Manager instance by starting the respective web container. See Starting and Stopping the Session Failover Components.
The amsessiondb script is called by the amsfo script to start the Berkeley DB client (amsessiondb), create the database, and set specific database values.
The recommended method to start and stop the Access Manager session failover components is to run the amsfo script and let it call the amsessiondb script. The following information is included only in case you might need to run the amsessiondb script independently.
Before you run the amsessiondb script, make sure you have the paths set correctly, as described under 4–Editing the amsessiondb Script (if Needed).
When you run the amsessiondb script, you can enter the Message Queue broker password on the command line as clear text (-w or --password option). However, if you prefer to use an encrypted password in a file (-f or --passwordfile option), first run the amsfopassword script to encrypt the Message Queue broker clear text password to a file. Then run the amsessiondb script, using this file for the -f or --passwordfile option.
Use the following syntax to run the amsessiondb script.
amsessiondb [ -u username | --username username ] [ -w password | --password password | -f filename | --passwordfile filename ] [ -c cachesize | --cachesize cachesize ] [ -b dbdirectory | --dbdirectory dbdirectory ] -a MQServerAddressList | --clusteraddress MQServerAddressList [ -s numcleanexpiredsessions | --numcleansessions numcleanexpiredsessions ] [ -v | --verbose ] [ -i statsinterval | --statsInterval statsinterval ] amsessiondb -h | --help amsessiondb -n | --version
The following table describes the amsessiondb script arguments.
Table 6–6 amsessiondb Script Arguments
Argument |
Description |
---|---|
-u username | --username username |
User name to connect to the Message Queue broker. Specify the user you specified under 3–Add a New User in the Message Queue Server. Default is “guest”. |
-w password | --password password |
Clear text password for the user name used to connect to the Message Queue broker. Specify the password you specified under 3–Add a New User in the Message Queue Server. Default is “guest”. |
-f filename | --passwordfile filename |
File that contains the encrypted password for accessing the Message Queue broker. Note If you specify this option, do not specify the -w or --password option. |
-c cachesize | --cachesize cachesize |
Cache size in MB. Default is 8 MB. |
-b dbdirectory | --dbdirectory dbdirectory |
Base directory where the Berkeley DB database (amsessions.db) is created. Default is “sessiondb”, created in the directory where you are running the amsessiondb script. Note To ensure that you have sufficient disk space where you are creating the database, allow 1 GB for each 100,000 sessions. |
-a MQServerAddressList | --clusteraddress MQServerAddressList |
Message Queue broker address list, in the format: host1:port[,host2:port,host3:port,...] For example: mqsvr1:7777,mqsvr2:7777 |
-s numcleanexpiredsessions | --numcleansessions numcleanexpiredsessions |
Number of expired sessions to be deleted for each cleanup interval. Default is 1000. |
-v | --verbose |
Run in verbose mode. Results are sent to the standard output. Default is non-verbose mode. |
-i statsinterval | --statsInterval statsinterval |
Interval in seconds to print the statistics for total requests, reads, writes, and deletes to the standard output. Default is 60 seconds. |
-h | --help |
Display amsessiondb command usage and then exit. |
-n | --version |
Return the version of Access Manager currently installed and then exit. |
The following example shows the amsessiondb script.
amsessiondb -u amsvrusr -f pwfile -c 128 -b sessiondb -a host1:7777,host2:7777
In this scenario, you want to remove the session failover configuration for a deployment.
In the Access Manager Administration Console, remove the session failover configuration (that is, the secondary configuration under Session Service in the Console).
Restart all the Access Manager servers participating in the cluster.
Shutdown the Message Queue broker instances and amsessiondb instances using the amsfo script on the target systems.
For more information, see Running the amsfo Script.
In the web container server.xml file, remove the installed locations of the imq.jar and jms.jar files. For example:
<JAVA javahome="/usr/jdk/entsys-j2se" serverclasspath= "/usr/share/lib/imq.jar:/usr/share/lib/jms.jar: /opt/SUNWwbsvr/bin/https/jar/webserv-rt.jar: ${java.home}/lib/tools.jar: /opt/SUNWwbsvr/bin/https/jar/webserv-ext.jar: /opt/SUNWwbsvr/bin/https/jar/webserv-jstl.jar: /usr/share/lib/ktsearch.jar"
Optionally, uninstall the Message Queue and Berkeley DB components from the target systems.
Several other considerations are:
After you remove the session failover configuration, determine whether you also want to remove the site configuration for the deployment. If you keep the site configuration without session failover, session constraints (if configured) are not supported.
If the cookie encoding setting on the Access Manager server side is restored, the corresponding setting of the cookie encoding for a remote client might also need to be restored.