Sun Java System Access Manager 7.1 Postinstallation Guide

Configuring Access Manager for Session Failover

Configuring Access Manager for session failover involves these steps:

Each step is described in detail in the following sections.

Tip –

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.

1–Disabling Cookie Encoding

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.

2–Modifying the Web Container Server classpath

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.

3–Adding 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–Editing 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–Running the `amsfoconfig` Script

Access Manager provides the amsfoconfig script to configure an Access Manager deployment for session failover.

Note –

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.

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`
`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`

Running the `amsfoconfig` Script

The amsfoconfig script configures Access Manager for session failover.

To Run the `amsfoconfig` Script

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.

Variables in the `amsfo.conf` 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: 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
###################################################################

Configuring Access Manager for Session Failover

1–Disabling Cookie Encoding

2–Modifying the Web Container Server classpath

3–Adding a New User in the Message Queue Server

4–Editing the amsessiondb Script (if Needed)

5–Running the amsfoconfig Script

Requirements to Run the amsfoconfig Script

Functions of the amsfoconfig Script

Running the amsfoconfig Script

To Run the amsfoconfig Script

Variables in the amsfo.conf File

amsfoconfig Script Sample Run