Implementing Access Manager Session Failover
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:
Access Manager Session Failover Scenario
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.
Figure 6–1 Access Manager Session Failover Scenario
Installing the Session Failover Components
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:
-
Configure the first Access Manager instance, if you specified the
Configure Later option during installation.
-
Redeploy or reconfigure an installed Access Manager instance.
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.
|
Caution –
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.
Configuring Access Manager for Session Failover
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.
1–Disable Cookie Encoding
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.
2–Edit the Web Container server.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"
3–Add a New User in the Message Queue Server
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
4–Edit the amsessiondb Script (if
Needed)
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.
5–Run the amsfoconfig Script
Access Manager 7 2005Q4 provides the amsfoconfig script
to configure an Access Manager deployment for session failover.
Requirements to Run the amsfoconfig Script
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.
Functions of the amsfoconfig Script
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
|
Running the amsfoconfig Script
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:
-
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.
|
amsfoconfig Script Sample Run
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
###############################################################
Starting the Session Failover Components
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.
Running the amsfo Script
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.
|
amsfopasswd Script
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:
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
Configuring Session Failover Manually
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:
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.
1–Install the Required Components in the Deployment
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.
2–Configure the Access Manager Deployment as a Site
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.
3–Create a New Secondary Configuration Instance for
the Load Balancer
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.
4–Perform Session Failover Miscellaneous Configuration
Tasks
Perform the following tasks (which are the same as if you are running the amsfoconfig script):
5–Start the Session Failover Components
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.
amsessiondb Script
The amsessiondb script is called by the amsfo script
to start the Berkeley DB client (amsessiondb), create the database,
and set specific database values.
Note –
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
Performance tests with the amsessiondb client include this
criteria:
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.
|
Download this book in PDF (796 KB)