test

Sun Java System Access Manager 7 2005Q4 Deployment Planning Guide

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:

Figure 6–1 Access Manager Session Failover Scenario

Access Manager session failover deployment 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 – 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:

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:

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:

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.

  1. Log in as or become superuser (root).

  2. Set the variables in the amsfo.conf file, as described in Table 6–3.

  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.

  4. When the amsfoconfig script prompts you, enter the following passwords:

    • Access Manager administrator (amAdmin) password

    • Message Queue broker user password

  5. 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:

To start the Access Manager session failover components, follow this sequence:

  1. 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

  2. Run the amsfo script to start the Java Message Queue (MQ) broker and the amsessiondb client. For detailed information, see Running the amsfo Script.

  3. 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:

  1. Log in as or become superuser (root).

  2. Set the variables in the amsfo.conf file, as required for your deployment. For a description of these variables, see Table 6–4.

  3. 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

  4. 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:

  1. Log in to the Access Manager 7 2005Q4 Console as amAdmin.

  2. Click Configuration, Global Properties, Session, and then Secondary Configuration Instance.

  3. 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.

  4. 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.