To install and configure the OpenSSO Enterprise session failover components, follow this procedure on each server in the Message Queue broker cluster:
Encrypting the Message Queue Broker Password Using the amsfopassword Script (Required)
Running the amsfo Script to Start and Stop the Session Failover Components
The ssoSessionTools.zip file, which is part of the opensso_enterprise_80.zip file, contains the session failover scripts, JAR, properties, and related files.
Unzip the opensso_enterprise_80.zip file. The ssoSessionTools.zip file is then available in the zip-root/opensso/tools directory, where zip-root is where you unzipped opensso_enterprise_80.zip.
Log in to the server where you want to install and configure the session failover components.
Create a new directory to unzip the ssoSessionTools.zip. For example: sfo-zip-root
Copy the ssoSessionTools.zip file to the new directory.
Unzip the ssoSessionTools.zip file in the new directory.
The following table describes the layout after you unzip the ssoSessionTools.zip file. The directory where you unzip ssoSessionTools.zip is represented by sfo-zip-root.
The session failover setup script installs these files:
Sun Java System Message Queue JAR and related files
Oracle Berkeley DB JAR and related files
amsfo, amsfopassword, and amsessiondb scripts on Solaris and Linux system
amsfo.pl, amsfopassword.bat, and amsessiondb.bat on Windows systems
amsfo.conf session failover configuration file
The setup script requires Java Runtime Environment (JRE) 1.5 or later. Make sure that your JAVA_HOME environment variable points to your JDK installation directory.
On Solaris and Linux systems, you might need to issue the following command before you run the setup script: chmod +x setup
In the directory where you unzipped the ssoSessionTools.zip file, run the setup script.
On Solaris and Linux systems, use this syntax to run the setup script:
setup -p|--path dirname
where dirname is a directory under the current directory where the setup script places the session failover scripts and related files. If dirname does not exist, the script will create the directory for you.
For example: # ./setup -p sfo
Considerations:
On Windows systems, run the setup.bat script.
If you run the setup script without any options, the script prompts you for a path.
If the path contains a space, run the setup script without any options and then provide the path when you are prompted.
To display the help for the setup script: setup -h|--help
The setup (or setup.bat) script installs the session failover scripts and related files in the following directories:
The amsfo script calls amsessiondb to start the Oracle Berkeley DB client (amsessiondb), create the database, and set specific database values. The amsessiondb script contains variables that specify various default paths and directories. For example:
JAVA_HOME=/usr/jdk/entsys-j2se/ AM_HOME=/opensso/tools/sfo-zip-root/sfo JMS_JAR_PATH=/usr/share/lib IMQ_JAR_PATH=/usr/share/lib BDB_JAR_PATH=/usr/share/db.jar BDB_SO_PATH=/usr/lib
If any of these components are not installed in the directories shown in the amsessiondb script, edit the script and set each variable, as needed, to the path where the component is installed.
The amsfopassorwd script accepts the password for the Message Queue broker user (default is guest) in clear text and returns the encrypted password in a file. You can then use this file as input to the amsfo script by setting the PASSWORDFILE variable in the amsfo.conf configuration file.
To run the amsfopassword script, use the following syntax:
amsfopassword -f|--passwordfile password-file -e|--encrypt clear-text-password
password-file is the path to the destination file where amsfopassword stores the encrypted password.
clear-text-password is the clear text password that amsfopassword encrypts.
To display help, specify -h|--help.
On the server where you ran the setup script, run the amsfopassword script.
For example, on a Solaris system:
# cd /sfo-zip-root/sfo/bin # ./amsfopassword -f /sfo-zip-root/sfo/mqpassword -e clear-text-password
You are not required to run amsfopassword as superuser (root).
Use the encrypted password in the mqpassword file as input to the amsfo script by setting the PASSWORDFILE variable in the amsfo.conf file.
For information about the PASSWORDFILE variable, see Table 8–1.
The amsfo script (or amsfo.pl on Windows systems) reads variables in the amsfo.conf configuration file and then performs these functions:
Starts or stops the Message Queue broker and the Oracle Berkeley DB client (amsessiondb) on each server in the broker list (CLUSTER_LIST variable).
Deletes and then recreates the Oracle Berkeley DB database, if requested.
Writes 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 run the script on Windows systems, Active Perl version 5.8 or later is required.
To run amsfo, use the following syntax:
amsfo start | stop
The amsfo command then automatically finds the amsfo.conf file.
The following table describes the variables in the amsfo.conf file. Some variables are set when you run the setup (or setup.pl) script. Before you run the amsfo script, set other variables as required for your deployment.
Table 8–1 amsfo.conf Configuration File Parameters
Variable |
Description |
---|---|
AM_HOME_DIR |
Specifies the following directory: sfo-zip-root/dirname where:
|
AM_SFO_RESTART |
Specifies (true or false) whether the script should automatically restart the Oracle Berkeley DB client (amsessiondb). The default is true (restart the amsessiondb client). |
CLUSTER_LIST |
Specifies the Message Queue broker list participating in the cluster. The format is: host1:port,host2:port, ... hostn:port For example: mq1.example.com:7777,mq2.example.com:7777,mq3.example.com:7777 You can deploy the Message Queue brokers on the same servers that are running OpenSSO Enterprise instances. However, for improved performance, consider installing the brokers on different servers. |
DATABASE_DIR |
Specifies the directory where the session database files will be created. Default: /tmp/amsession/sessiondb |
DELETE_DATABASE |
Specifies (true or false) whether the script should delete and then create a new database each time the Oracle Berkeley DB client (amsessiondb) is restarted. Default: true |
LOG_DIR |
Specifies the location of the log directory. Default: /tmp/amsession/logs |
START_BROKER |
Specifies (true or false) whether the Message Queue broker should be started with the amsessiondb process on the same server: true - The Message Queue broker will run on the same server as the amsessiondb process. false - The Message Queue broker and the amsessiondb process will run on different servers. Default: true |
BROKER_INSTANCE_NAME |
Specifies the name of the Message Queue broker instance to start. For example: mqbroker |
BROKER_PORT |
Specifies the port for the local Message Queue broker instance. Default: 7777 |
BROKER_VM_ARGS |
Specifies the Java VM arguments. Set to a maximum of 1024m, based on the system resources. Default: "-Xms256m -Xmx512m" |
USER_NAME |
Specifies the user name used to connect to the Message Queue broker. Default: guest |
PASSWORDFILE |
Location of the password file that contains the encrypted password of the user name (default is guest) used to connect to the Message Queue broker. To generate the encrypted password, use the amsfopassword script, as described in Encrypting the Message Queue Broker Password Using the amsfopassword Script (Required). Default: sfo-zip-root/dirname/.password |
AMSESSIONDB_ARGS |
amsessiondb script arguments. The amsessiondb script is called by the amsfo (or amsfo.pl) script. To determine the list of arguments, run: amsession db -h |
Stop each of the OpenSSO Enterprise instances in the session failover deployment.
Set the variables in the amsfo.conf file, as required for your deployment.
For a description of all variables, see Table 8–1.
Run the amsfo script on Solaris or Linux systems or the amsfo.pl script on Windows systems.
For example, to start the session failover components on a Solaris system:
# cd /sfo-zip-root/sfo/bin # ./amsfo start
The amsfo command then automatically finds the amsfo.conf file and displays status information as it runs.
To check the results, see the /var/tmp/amsfo.log file.