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 by Sleepycat Software, Inc. as the session store database. Access Manager 7 2005Q4 enhancements includes the amsfoconfig script to configure the session failover environment and the amsfo script to start and stop the Message Queue broker and Berkeley DB client.
This section covers these topics:
The following figure 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.
Table 6–1 Installation of Access Manager Session Failover Components
Component |
How to install ... |
---|---|
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. Reference: Sun Java Enterprise System 2005Q4 Installation Guide for UNIX When you install Access Manager using the Java ES installer, you can select either Realm Mode (version 7.x) or Legacy Mode (version 6.x). Access Manager session failover is supported in both modes. After you run the Java ES installer, run the amconfig script to:
For information, see Installing Access Manager on Multiple Host Servers. |
Message Queue |
Install Message Queue using the Java ES installer. Reference: Sun Java Enterprise System 2005Q4 Installation Guide for UNIX |
Berkeley DB Client (Access Manager subcomponent) |
The Java ES installer and amconfig script adds the Access Manager packages or RPMs required for the Berkeley DB client. However, if you want to install the Berkeley DB client on a server where you have not installed Access Manager, you must manually add the following packages or RPMs, depending on your operating system. For the Solaris OS, add the following packages using the pkgadd command: SUNWamsfodb, SUNWbdb, and SUNWbdbj. Reference: Solaris documentation For the Linux OS, add the following RPMs using the rpm command: sun-identity-sfodb, sun-berkeleydatabase-core, and sun-berkeleydatabase-java. Reference: Linux online man pages. |
In a multiple server deployment that shares the same Directory Server, all instances of Access Manager 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 deploy Access Manager instances on other host servers, use this same value for the password encryption key.
To configure Access Manager for session failover, follow 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 in the /var/opt/SUNWam/debug directory on Solaris systems or the /var/opt/sun/identity/debug directory on Linux systems.
On each host server that is running an Access Manager instance, disable cookie encoding:
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, set the encodeCookies property to false. For example:
<sun-web-app> <property name="encodeCookies" value="false"/> ... </sun-web-app>
If 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, add the installed locations of imq.jar and jms.jar in the server.xml (or equivalent) configuration file for the Access Manager web container. For example, on Solaris systems:
<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"
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 7 2005Q4 provides the amsfoconfig script to configure an Access Manager deployment for session failover.
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 |
amsfopasswd |
Script to generate the encrypted Message Queue broker user password. Solaris systems: AccessManager-base/SUNWam/bin Linux systems: AccessManager-base/identity/bin |
amsfo.conf |
Session failover configuration file. Solaris systems: AccessManager-base/SUNWam/lib Linux systems: AccessManager-base/sun/identity/lib |
amProfile.conf |
Session failover environment file. Solaris systems: etc/opt/SUNWam/config Linux systems: etc/opt/sun/identity/config |
AccessManager-base represents the base installation directory for Access Manager. The default values are: Solaris systems: /opt Linux systems: /opt/sun |
To run the amsfoconfig script to configure Access Manager for session failover, follow these steps.
Log in as or become superuser (root).
Set the variables in the amsfo.conf file, as described in Table 6–3.
Run the script. 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 amsfoconfig 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: (nothing will be echoed): password2 Verify: password2 Retrieving Platform Server list... Validating server entries. Done... Retrieving Site list... Validating site entries. Done... Validating host: http://amhost1.example.com:7001|02 Validating host: http://amhost2.example.com:7001|01 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 Platform Server List File... Platform Server List server entries loaded successfully. Loading Organization Alias List File... Organization Alias List loaded successfully. Please refer to the log file /var/tmp/amsfoconfig.log for additional information. ############################################################### Session Failover Setup Script. Execution end time 10/05/05 13:34:44 ###############################################################
Access Manager 7 2005Q4 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–4
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. For information, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.
The amsfo script includes the start and stop options:
Usage: amsfo { start | stop }
To run the amsfo script, follow these steps:
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.
The following table describes the variables in the amsfo.conf configuration file. Set these 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 amsfopasswd script, as described in amsfopasswd Script The default is $AM_HOME_DIR/.password, where $AM_HOME_DIR specifies the Access Manager default installation directory. |
The amsfopasswd 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 amsfopasswd 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 amsfopasswd script.
amsfopasswd -f filename | --passwordfile filename -e password | --encrypt password amsfopasswd -h | --help
The following table describes the amsfopasswd script arguments.
Table 6–5 amsfopasswd Script Arguments
Argument |
Description |
---|---|
-f filename | --passwordfile filename |
Path to the destination file where amsfopasswd stores the encrypted password. |
-e password | --encrypt password |
Clear text password that amsfopasswd encrypts. |
-h | --help |
Display the amsfopasswd command usage and then exit. |
The following example shows the amsfopasswd script. The encrypted password is stored in the /opt/SUNWam/.password file.
# ./amsfopasswd -f /opt/SUNWam/.password -e mypassword
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 2005Q4 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):
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 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–Edit 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 amsfopasswd 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
Performance tests with the amsessiondb client include this criteria:
The approximate number of operations on the Berkeley DB was two times the number of authentications per second.
Tests were conducted with the following configuration:
Write data – 3 Kbytes
Duration – 1 minute
Berkeley DB cache size – 28 Mbytes (default cache size in Access Manager 7 2005Q4 is 32 Mbytes)
The following table shows the results of the tests.
Table 6–7 Performance Tests With the amsessiondb Client
Disk |
Notes |
---|---|
Normal IDE disk: 666 writes per second |
Each site can support up to 300 authentications per second. Therefore, IDE disks are not recommended. |
Normal 10K RPM SCSI disk on Sun Blade server: 1520 writes per second |
Each site can support up to 750 authentications per second. |
Seagate Cheetah 15K RPM SCSI disk: 1860 writes per second |
Each site can support up to 900 authentications per second. |
Sun T-300 disk array: 2700 writes per second |
Each site can support up to 1300 authentications per second. |
Disk using swap space in /tmp: 3300 writes per second |
Each site can support up to 1600 authentications per second. |