test

Sun Java System Access Manager 7 2005Q4 Deployment Planning Guide

Chapter 6 Implementation of an Access Manager Design

During the implementation phase of the solution life cycle, you implement various solutions for your deployment. This chapter describes the following implementation scenarios for Sun JavaTM System Access Manager:

Installing Access Manager on Multiple Host Servers

Installing Access Manager instances on multiple host servers, with each instance accessing the same Directory Server, includes these steps:

Deploying Access Manager Instances

To install Access Manager instances on multiple host servers, with each instance accessing the same Directory Server, follow these steps.

  1. Install Access Manager on a host server by running the Java Enterprise System (Java ES) installer. When you run the installer, specify either the Configure Now or Configure Later option. For information about running the installer, see the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.

    When you run the installer, you can also install Web Server or Application Server as the Access Manager web container. To use BEA WebLogic Server or IBM WebSphere Application Server as the web container, you must first install the product before you run the run the amconfig script in the following steps. For installation instructions, see the respective BEA or IBM product documentation.

  2. If you specified the Configure Later option during installation or if you need to reconfigure the Access Manager instance (for example, to use BEA WebLogic Server or IBM WebSphere Application Server as the web container), you must run the amconfig script. The amconfig script and the amsamplesilent configuration file are located in the AccessManager-base/bin directory, where AccessManager-base represents the default installation directory: /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.

    Run the amconfig script as follows:

    1. Copy the amsamplesilent file to a writable directory and make that directory your current directory. For example, you might create a directory named /newinstances.

    2. Rename the copy of the amsamplesilent file to describe the new instance you want to configure. For example, if you plan to create a new Access Manager instance for Web Server 6.1, you might rename the file to amwebsvr6.

    3. Set the variables in the amwebsvr6 file to configure the new instance. For example, to configure Access Manager in Realm mode:

      AM_REALM=true
DEPLOY_LEVEL=1
NEW_INSTANCE=true
WEB_CONTAINER=WS6 # Web Server is the web container
DIRECTORY_MODE=1 
...

      In case you might need to reconfigure or uninstall this instance later, save the new amwebsvr6 file.

    4. Run the amconfig script, specifying the new amwebsvr6 file as the silent configuration input file. For example, on Solaris systems with Access Manger installed in the default directory:


      # cd /opt/SUNWam/bin/
# ./amconfig -s ./newinstances/amwebsvr6

      Run amconfig with full path to the amsamplesilent file (or copy of the file). The script reads the variables in the amwebsvr6 file and then runs in silent mode (-s option) to configure Access manager for the web container. For more information about the amsamplesilent file and running the amconfig script, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.

  3. Repeat these steps on the other host servers to deploy additional Access Manager instances.

Several considerations for deploying additional Access Manager instances are:

Caution – Caution –

In a multiple server deployment that shares the same Directory Server, all Access Manager instances must use the same value for the password encryption key.

If you run the Java ES installer to install Access Manager on subsequent (second, third, and so on) servers in a multiple server deployment, the installer generates a new random password encryption key for each server. Therefore, when you run the installer on a subsequent server, use the encryption key value from the first Access Manager instance, which you can copy from the am.encryption.pwd attribute in the AMConfig.properties file and set as follows:

However, if you need to change the password encryption key for an Access Manager instance, see Appendix B, Changing the Password Encryption Key.

Adding Additional Instances to the Platform Server List and Realm/DNS Aliases

When you install multiple instances of Access Manager on different host servers, the additional instances are not added to the platform server list or the realm/DNS aliases. You must explicitly add the values for the additional Access Manager instances, as follows:

  1. Log in to the Access Manager 7 2005Q4 Console as amadmin on the first Access Manager host server.

  2. In the Access Manager Console, click Configuration, System Properties, and then Platform.

  3. Add each additional Access Manager instance to the Platform Server List under Instance Name:

    1. In the Platform Server List under Instance Name Name, click New.

    2. In New Server Instance, add the Server and Instance Name. For example:

      • Server: http://amserver2.example.com:80

      • Instance Name: 02

    3. Click OK to add the instance.

    4. After you have added all instances, click Save.

  4. Add the Realm/DNS alias for each additional Access Manager instance:

    1. In the Access Manager Console, click Access Control and then the root (top-level) realm under Realm Name.

    2. Under Realm Attributes, add the Access Manager instance to Realm/DNS Aliases and then click Add. For example: amserver2.example.com

    3. After you have added all instances, click Save.

Configuring an Access Manager Deployment as a Site

Access Manager 7 2005Q4 introduces the “site concept,” which provides centralized configuration management for an Access Manager deployment. When Access Manager is configured as a site, client requests always go through the load balancer, which simplifies the deployment as well as resolves issues such as a firewall between the client and the back-end Access Manager servers. A site includes the following components:

The following procedures refer to the Access Manager 7 2005Q4 Console in Realm Mode.

Site Configuration

If you have an Access Manager multiple server deployment, use either of these methods to configure your deployment as a site:

When you configure a deployment as a site, you perform these functions in the Access Manager Console:

In addition, Access Manager automatically sets the fqdnMap property (in memory) to include the load balancer, so you do not need to explicitly set this property in the AMConfig.properties file.

To configure an Access Manager deployment as a site, follow this procedure:

  1. Log in to the Access Manager Console as amAdmin.

  2. Add the load balancer URL to the Site Name:

    1. In the Access Manager Console, click Configuration, System Properties, and then Platform.

    2. Under Site Name, click New and enter the following values for the load balancer:

      • Server: Load balancer protocol, host name, and port. For example: http://lb.example.com:80

      • Site Name: Unique two-digit site identifier (site ID). For example: 10

        When you are finished, click OK.

    3. After adding the load balancer to the Site Name, click Save. The entry for the load balancer now includes the site ID. For example: http://lb.example.com:80|10

      The site ID must be unique with respect to server IDs and other site IDs. For example, you cannot use 01 for both a site ID and a server ID.

  3. On the same Console panel, map the load balancer to each Access Manager instance:

    1. In the Server list under Instance Name, click each instance name to display the Edit Server Instance panel for the instance.

    2. Map the Site Name (site ID) for the load balancer to the Access Manager instance. For example, using a load balancer with a Site Name of 10, for the first server, the Instance Name would 01(|10).

    3. Click OK and repeat the steps for the other Access Manager instances.

      When you are finished, all Access Manager instances should be mapped to the load balancer. For example: 

      http://amserver1.example.com:8080|01|10
http://amserver2.example.com:8080|02|10
http://amserver3.example.com:8080|03|10

    4. Click Save to save the configuration.

  4. Add the Realm/DNS alias for the load balancer:

    1. In the Access Manager Console, click Access Control and then the root or top-level realm under Realm Name.

    2. Under Realm Attributes, add the load balancer to Realm/DNS Aliases and then click Add. For example: lb.example.com.

    3. Click Save to save your changes.

  5. For clients such as a policy agent, the load balancer (as opposed to the individual Access Manager instances) should be the sole entry point. For example, if you are using a policy agent, modify the appropriate entries in the AMAgent.properties file to point to the load balancer.

Using a Load Balancer With Access Manager

The load balancer distributes the client requests between the Access Manager instances in multiple server deployment. Before you use this information in the section, configure your Access Manager deployment as a site, as described in Configuring an Access Manager Deployment as a Site. A site includes multiple (two or more) instances of Access Manager installed on different host servers. All Access Managers instances must access the same Directory Server and use the same password encryption key. For information about installing Access Manager, see Installing Access Manager on Multiple Host Servers.

This section include the following information about using a load balancer:

Configuring SSL Termination for a Load Balancer

Before you configure a load balancer to handle SSL requests, first configure SSL for the Access Manger web container. For instructions, see Chapter 3, Configuring Access Manager in SSL Mode, in Sun Java System Access Manager 7 2005Q4 Administration Guide.

To configure SSL for a load balancer and Access Manager servers, consider the following cases:

For all cases, except for the SSL pass-through configuration, you can use a normal server certificate to enable SSL termination for the load balancer. However, when you configure SSL pass-through for the load balancer and the Access Manager servers and the load balancer bypasses all the requests from the client to the Access Manager server, the following SSL problems exist for a normal server certificate:

To solve these problems, Access Manager provides these properties:

Generating a CSR with the SubjectAltName Extension

To generate a certificate signing request (CSR) with the SubjectAltName extension, use the Certificate Database Tool (certutil). If certutil is not available in the /usr/sfw/bin directory, first install the SUNWtlsu package on Solaris systems or the sun-nss-sun-nss-devel RPM on Linux systems. If necessary, set the LD_LIBRARY_PATH environment variable to the appropriate certutil path.

For information about certutil, see: http://www.mozilla.org/

This section describes how to use the certutil if you are using Web Server or Application Server as the web container. If you are using BEA WebLogic Server or IBM WebSphere Application Server as the web container, refer to the respective BEA or IBM product documentation.

To generate a CSR with the SubjectAltName extension, follow these steps:

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

  2. Create a new certificate database (cert8.db) using the certutil -N option. If necessary, first create a directory for your database. For example: 

    # mkdir certdbdir 
# cd certdbdir 
# certutil -N -d .

    When prompted by certutil, enter the password to encrypt your keys:

    Enter a password which will be used to encrypt your keys. 
The password should be at least 8 characters long, 
and should contain at least one non-alphabetic character.

Enter new password: your-password 
Re-enter password:  your-password

  3. Generate the CSR with the SubjectAltName extension. For example:

    # certutil -R -s "cn=lb.example.com,o=example.com,c=us" 
-o server.req -d . -a -8 amserv1.example.com,amserv2.example.com

    When prompted by certutil, enter the password (or pin) and then type keys to generate the random seed to create your key: 

    Enter Password or Pin for "NSS Certificate DB": your-password

A random seed must be generated that will be used in the  
creation of your key.  One of the easiest ways to create a  
random seed is to use the timing of keystrokes on a keyboard.   

To begin, type keys on the keyboard until this progress meter  
is full.  DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!   

Continue typing until the progress meter is full:   

|************************************************************|   

Finished.  Press enter to continue:   

Generating key.  This may take a few moments...

  4. Send the CSR (server.req file in the example) to the Certificate Authority (CA). Get the server certificate and add it to the certificate database using the certutil -A option.

  5. Copy the certificate database (cert8.db) to the web container directory.

    • Web Server. Copy the cert8.db and key3.db databases to the /opt/SUNWwbsrv/alias directory and rename them using the Web Server instance name. For example: 

      https-webserver.example.com-webserver-cert8.db
https-webserver.example.com-webserver-key3.db

    • Application Server. Copy the cert8.db and key3.db databases to the instance /config directory. For example: 

      /var/opt/SUNWappserver/domains/domain1/config/cert8.db 
/var/opt/SUNWappserver/domains/domain1/config/key3.db

Configuring Access Manager For Load Balancer Cookies

To configure Access Manager for load balancer cookies, update the configuration for all Access Manager instances in the deployment so that the instances can recognize the load balancer. In this scenario, multiple (two or more) Access Manager instances are deployed on different host servers. A load balancer routes client requests to the various Access Manager instances. All Access Manager instances use the same Directory Server.

  1. In the Access Manager Console, configure the Access Manager deployment as a site, as described in Configuring an Access Manager Deployment as a Site. When you configure a deployment as a site, Access Manager automatically sets the fqdnMap property (in memory) to include the load balancer.

  2. In the AMConfig.properties file for each Access Manager instance, add the following properties: 

    com.iplanet.am.lbcookie.name=amlbcookie
com.iplanet.am.lbcookie.value=amserver

    where amlbcookie is the load balancer cookie, and amserver is the name of the Access Manager host server for the instance.

  3. Restart all Access Manager instances by restarting the respective web container.

Configuring a Load Balancer with SAML

In this scenario, an Access Manager site is using a load balancer to distribute client requests to various Access Manager instances, and the site has implemented the Security Assertions Markup Language (SAML) service. When a request is sent to an Access Manager instance through a load balancer, the instance must know which other Access Manager server in the deployment issued the original assertion or artifact in order to retrieve the SAML assertion.

The deployment must first be configured as a site. Multiple Access Manager instances are installed on host servers, and a load balancer routes client requests to the various instances. All Access Manager instances access the same Directory Server. Access Manager session failover is optional.

To configure a site to use a load balancer with SAML, follow these steps:

  1. The Access Manager deployment must be configured as a site in order for SAML load balancing to work. If you haven't configured the Access Manager deployment as a site, follow the instructions in Configuring an Access Manager Deployment as a Site.

  2. Log in to the Access Manager Console as amadmin.

  3. In the Access Manager Console, click Federation and then SAML.

  4. Under the Properties section in SAML Profile, add or modify the following entries:

    • Site Identifiers. Add each Access Manager instance in the deployment. All Access Manager instances must share the same Site ID and Site Issuer Name.

    • Trusted Partners. Add your partner's deployment site's Source ID (site ID), Issuer Name, and Host List. The unique Source ID (site ID) and Issuer Name for the Access Manager servers and the URL or IP address or host name of the load balancer will identify the deployment and will be given out to your partner's site for configuration.

      For information about these fields, see the Sun Java System Access Manager 7 2005Q4 Federation and SAML Administration Guide.

  5. Click Save to save your changes.

Setting the fqdnMap Property

If you have configured an Access Manager deployment as a site, Access Manager automatically sets the fqdnMap property (in memory) to include the load balancer , and you do not need to set this property in the AMConfig.properties file. However, for the following Access Manager deployments, you must explicitly set the property:

If you need to set the fqdnMap property, set the property to the load balancer in the AMConfig.properties file for each Access Manager instance in the deployment. If necessary, first remove the comment character (#) from the property. For example:

com.sun.identity.server.fqdnMap[lb.example.com]=lb.example.com

Accessing an Access Manager Instance Through a Load Balancer

Accessing an Access Manager instance through a load balancer depends on the mode (realm or legacy) and the console you want to access. Use the following syntax to access an Access Manager instance through a load balancer: 

http://loadbalancer.domain:port/amserver/console|/amconsole

In legacy mode, you can access both consoles:

In realm mode, you can access only the new Access Manager 7 2005Q4 Console. For example:

http://loadbalancer.example.com:80/amserver/console

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. 

Setting Session Quota Constraints

Access Manager 7 2005Q4 includes the new session quota constraints feature, which allows Access Manager to limit users to a specific number of active, concurrent sessions based on configurable attributes. An Access Manager administrator can set session quota constraints at the following levels:

Deployment Scenarios for Session Quota Constraints

The following Access Manager deployments support session quota constraints:

In a session failover deployment, when a user attempts to log in, the Access Manager server receiving the session creation request first retrieves the session quota for the user from the Access Manager identity repository. Then, the Access Manager server fetches the session count for the user directly from the centralized session repository (accumulating all the sessions from all the Access Manager servers within the same site) and checks whether the session quota has been exhausted. If the session quota has been exhausted for the user, the Access Manager server takes action based on the configured session quota constraints options.

If session constraints are enabled in a session failover deployment and the session repository is not available, users (except superuser) are not allowed to log in.

In a session failover deployment, if an Access Manager instance is down, all the valid sessions previously hosted by that instance are still considered to be valid and are counted when the server determines the actual active session count for a given user. An Access Manager multiple server deployment that is not configured for session failover does not support session quota constraints.

Configuration of Session Quota Constraints

To configure session quota constraints, the top-level Access Manager administrator (such as amAdmin) must set the following attributes in the Access Manager Console for one of the Access Manager instances. If you reset any of these attributes, you must restart the server for the new value to take effect.

Multiple Settings For Session Quotas

If a user has multiple settings for session quotas at different levels, Access Manager follows this precedence to determine the actual quota for the user:

For example, Ken is a member of both the marketing and management roles. Session quotas are defined as follows (all have the same conflict resolution level):

Ken's quota is 3.

For more information about the session quota constraints attributes, see the Access Manager Console online help.

Enabling Session Property Change Notifications

The session property change notification feature causes Access Manager to send a notification to all registered listeners when a change occurs on a specific session property. This feature takes effect when the “Enable Property Change Notifications” attribute is enabled (ON) in the Access Manager Console.

For example, in a single sign-on (SSO) environment, one Access Manager session can be shared by multiple applications. When a change occurs on a specific session property defined in the “Notification Properties” list, Access Manager sends a notification to all registered listeners.

All client applications participating in the SSO automatically get the session notification if they are configured in the notification mode. The client cached sessions are automatically updated based on the new session state (including the change of any session property, if there is any). An application that wants to take a specific action based on a session notification can write an implementation of the SSOTokenListener interface and then register the implementation through the SSOToken.addSSOTokenListener method. For more information, see the Sun Java System Access Manager 7 2005Q4 Developer’s Guide.

To configure session property change notifications, follow these steps:

  1. Log in to Access Manager Console as amAdmin.

  2. Click the Configuration tab.

  3. Under Global Properties, click Session.

  4. Set “Enable Property Change Notifications” to ON.

  5. In the “Notification Properties” list, add each property for which you want a notification sent when the property is changed.

  6. When you have finished adding properties to the list, click Save.

Tuning Your Deployment

After you install Access Manager, you can tune your deployment for optimum performance using the amtune and related scripts. These scripts allow you to tune Access Manager, the SolarisTM Operating System (OS), the web container, and Directory Server.

The Java Enterprise System installer installs the tuning scripts and related files in the bin/amtune directory.

The amtune script is not interactive. Before you run amtune, you must edit the parameters in the amtune-env configuration file to specify the tuning you want amtune to perform for your specific environment. The amtune-env configuration file includes two major sections:

You can run the amtune script in two modes:

The amtune script does not automatically tune Directory Server. Most deployments have applications other than Access Manager that also access Directory Server, so you don’t want to make tuning changes without considering how they would affect your other applications.

Before you tune Directory Server, first back up your Directory Server data using db2bak.

When you run amtune, the script creates a tar file that contains the Directory Server tuning script, amtune-directory. Untar this file in a temporary directory and then run the script in review mode. When you are certain that your changes are acceptable for all applications at your deployment, run amtune-directory in change mode.

For detailed information about running the tuning scripts and setting tuning parameters in the amtune-env configuration file, see the Sun Java System Access Manager 7 2005Q4 Performance Tuning Guide.