This chapter contains detailed instructions for the following tasks:
When session failover is implemented for Access Manager, session information is replicated in two backend session store databases. This ensures that when one Access Manager fails or stops, the information stored in the backend session databases can be used to keep the user continuously authenticated. If session failover is not implemented, when one Access Manager fails, if the user's session was created in the failed Access Manager server, the next time the user performs an operation that requires a session token, the user will have to use a login page to re-authenticate.
Use the following as your checklist for installing the Message Queue instances:
Access Manager provides a web container-independent session failover feature that uses Sun Java System Message Queue (Message Queue). Message Queue is a messaging middleware product that enables distributed applications to communicate and exchange data by sending and receiving messages. In this Deployment Example, Access Managers uses Message Queue as a communications broker, and uses the Berkeley DB by Sleepycat Software, Inc. for the backend session store databases.
For detailed information about how Access Manager and Message Queue interact, see Implementing Access Manager Session Failover in Sun Java System Access Manager 7 2005Q4 Deployment Planning Guide in the Access Manager Deployment Planning Guide.
The Java ES installer must be mounted on the host computer system where you will install Message Queue. See the section “To Download and Unpack the Java Enterprise System 2005Q4 Installer”3.2 Downloading and Mounting the Java Enterprise System 2005Q4 Installer in this document.
Log in as a root user to the host MessageQueue–1.
Start the installer with -nodisplay option. Example:
# cd /mnt/Solaris_sparc # ./installer -nodisplay
When prompted, provide the following information:
|
Press Enter. |
|
|
Press Enter. |
|
|
Enter 8 for English. |
|
|
Press Enter. |
|
|
Enter 12 for Message Queue. |
|
|
Press Enter. |
|
|
Accept the default value. |
|
|
Accept the default value. |
|
|
Enter 1 for Configure Now. |
|
|
First, see the following (Optional) Step 4. When you're ready to install, press Enter to accept the default value. |
|
|
Enter ! when you're ready to exit the installer program. |
(Optional) Monitor the log files and watch for installation errors.
# cd /var/sadm/install/logs # tail -f Java_Enterprise_System_install.B10110830 |
Log in as a root user to the host MessageQueue–2.
Start the installer with -nodisplay option. Example:
# cd /mnt/Solaris_sparc # ./installer -nodisplay
When prompted, provide the following information:
|
Press Enter. |
|
|
Press Enter. |
|
|
Enter 8 for English. |
|
|
Press Enter. |
|
|
Enter 12 for Message Queue. |
|
|
Press Enter. |
|
|
Accept the default value. |
|
|
Accept the default value. |
|
|
Enter 1 for Configure Now. |
|
|
First, see the following (Optional) Step 4. When you're ready to install, press Enter to accept the default value. |
|
|
Enter ! when you're ready to exit the installer program. |
(Optional) Monitor the log files and watch for installation errors.
# cd /var/sadm/install/logs # tail -f Java_Enterprise_System_install.B10110830 |
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. In this deployment example, for the Solaris OS, you add the following packages using the pkgadd command: SUNWbdb, SUNWbdbj, and SUNWamsfodb. In this deployment example, it is not necessary to run the amsfoconfig utility.
Use the following as your checklist for installing the Access Manager session failover components:
Install Access Manager session failover components on Message Queue 1.
Install Access Manager session failover components on Message Queue 2.
As root, log in to the host MessageQueue-1.
Use the pkgadd command to install the Access Manager session failover component packages.
Add a new user and password.
These are the user and password you will use connect to the Message Queue broker on servers where Message Queue is installed. Using this new user ensures that the guest user will not be able to access the other Access Manager server.
Create a new instance named msgqbroker by running the following command:
/bin/imqbrokerd -name msgqbroker -port 7777 &
Run the netstat command to verify that the new Message Queue instance is up and running.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN
Add a new user named msgquser.
For this deployment example, create a specific user who will be used only for session failover purposes. This new user does not assume the privileges of the guest user. It is a good practice to create a custom user for such purposes, and not to rely on the known user accounts or default user accounts. This helps to prevent brute force or DOS attacks.
# /bin/imqusermgr add -u msgquser -g admin -p m5gqu5er -i msgqbroker
Update the guest user.
This step effectively disables the guest user.
# /bin/imqusermgr update -u guest -a false -i msgqbroker
User repository for broker instance: msgqbroker Are you sure you want to update user guest? (y/n) y User guest successfully updated.
Edit the /opt/SUNWam/lib/amsfo.conf file.
Make a backup of the amsfo.conf file, and then set the following properties:
CLUSTER_LIST=MessageQueue-1.example.com:7777,MessageQueue-2.example.com:7777 BROKER_INSTANCE_NAME=msgqbroker USER_NAME=msgquser lbServerPort=9443 lbServerProtocol=https lbServerHost=LoadBalancer-3.example.com SiteID=11
Run the amsfopassword command.
This command generates an encrypted password, creates a new file named .password, and stores the encrypted password in the new file.
# cd /opt/SUNWam/bin
# ./amsfopassword -e m5gqu5er -f /opt/SUNWam/.password
To view the encrypted password:
# more /opt/SUNWam/.password
M27OGb6U4ufRu+oWAzBdWw==
Edit the /opt/SUNWam/bin/amsessiondb script.
Make a backup of the /opt/SUNWam/bin/amsessiondb script before making any changes to the 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. 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 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.
Edit the /opt/SUNWam/bin/amsfoscript.
Make a backup of the /opt/SUNWam/bin/amsfo script before making any changes to the script. In the following line, add the the parameter —name $BROKER_INSTANCE_NAME as follows:
$JMQEXECUTABLE -bgnd $BROKER_OPTIONS -vmargs $BROKER_VM_ARGS -name $BROKER_INSTANCE_NAME -port $BROKER_PORT -cluster $CLUSTER_LIST & -jmqpid=$! echo $_jmqpid > $JMQ_PID_FILE |
Restart the Access Manager session failover components.
Stop the Message Queue broker instance.
# cd /opt/SUNWam/bin # ./amsfo stop |
Run the netstat command to verify that the Message Queue broker instance is stopped.
# netstat -an | grep 7777 |
If netstat returns no result, then the Message Queue broker instance is stopped.
If the Message Queue broker instance is not stopped, run the following commands:
# cd /tmp/amsession/logs # cat *.pid |
Process IDs are displayed. Example:
4940 4924 |
Kill these Java processes. Example:
# kill -9 4940 4924 |
If you don't see the process-ids in that file, and the netstat is still listening on port 7777, then it's possible that the amsfo script did not stop properly. In this case, run the following command to identify the java processes:
# ps -ef | grep java |
Then kill those identified processes as shown in the kill command example above.
Then check with netstat again. The port socket should be relinquished before you start up amsfo again. Otherwise, session failover problems may occur.
Restart the Message Queue broker instance.
# ./amsfo start |
Run the netstat command to verify that the Message Queue port is open and listening.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN
As root, log in to the host MessageQueue-2.
Use the pkgadd command to install the Access Manager session failover component packages.
Add a new user and password.
This is the user and password you will use connect to the Message Queue broker on servers where Message Queue is installed. Using this new user ensures that the guest user will not be able to access the other Access Manager server.
Create a new instance named msgqbroker by running the following command:
/bin/imqbrokerd -name msgqbroker -port 7777 &
Run the netstat command to verify that the new Message Queue instance is up and running.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN
Add a new user named msgquser.
# /bin/imqusermgr add -u msgquser -g admin -p m5gqu5er -i msgqbroker
Update the guest user.
# /bin/imqusermgr update -u guest -a false -i msgqbroker
User repository for broker instance: msgqbroker Are you sure you want to update user guest? (y/n) y User guest successfully updated.
Edit the /opt/SUNWam/lib/amsfo.conf file.
Make a backup of the amsfo.conf file, and then set the following properties:
CLUSTER_LIST=MessageQueue-1.example.com:7777,MessageQueue-2.example.com:7777 BROKER_INSTANCE_NAME=msgqbroker USER_NAME=msgquser lbServerPort=9443 lbServerProtocol=https lbServerHost=LoadBalancer-3.example.com SiteID=11
Run the amsfopassword command.
This command generates an encrypted password, creates a new file named .password, and stores the encrypted password in the new file.
# cd /opt/SUNWam/bin
# ./amsfopassword -e m5gqu5er -f /opt/SUNWam/.password
To view the encrypted password:
# more /opt/SUNWam/.password
M27OGb6U4ufRu+oWAzBdWw==
Edit the /opt/SUNWam/bin/amsessiondb script.
Make a backup of the /opt/SUNWam/bin/amsessiondb script before making any changes to the 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. 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 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.
Edit the /opt/SUNWam/bin/amsfoscript.
Make a backup of the /opt/SUNWam/bin/amsfo script before making any changes to the script. In the following line, add the parameter —name $BROKER_INSTANCE_NAME as follows:
$JMQEXECUTABLE -bgnd $BROKER_OPTIONS -vmargs $BROKER_VM_ARGS -name $BROKER_INSTANCE_NAME -port $BROKER_PORT -cluster $CLUSTER_LIST & -jmqpid=$! echo $_jmqpid > $JMQ_PID_FILE |
Restart the Access Manager session failover components.
Stop the Message Queue broker instance.
# cd /opt/SUNWam/bin # ./amsfo stop |
Run the netstat command to verify that the Message Queue broker instance is stopped.
# netstat -an | grep 7777 |
If netstat returns no result, then the Message Queue broker instance is stopped.
If the Message Queue broker instance is not stopped, run the following commands:
# cd /tmp/amsession/logs # cat *.pid |
Process IDs are displayed. Example:
4940 4924 |
Kill these Java processes. Example:
# kill -9 4940 4924 |
If you don't see the process-ids in that file, and the netstat is still listening on port 7777, then it's possible that the amsfo script did not stop properly. In this case, run the following command to identify the java processes:
# ps -ef | grep java |
Then kill those identified processes as shown in the kill command example above.
Then check with netstat again. The port socket should be relinquished before you start up amsfo again. Otherwise, session failover problems may occur.
Restart the Message Queue broker instance.
# ./amsfo start |
Run the netstat command to verify that the Message Queue port is open and listening.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN
Run the netstat command to verify that the Message Queue port is open and listening.
# netstat -an | grep 7777 *.7777 *.* 0 0 49152 0 LISTEN
Create a new secondary configuration instance for the Access Manager load balancer.
Go to the Access Manager URL:
https://LoadBalancer-3.example.com:9443/amserver/UI/Login
Log in to the Access Manager console using the following information:
amadmin
4m4dmin1
Click Configuration > Global Properties > Session > Secondary Configuration Instance.
Click New, and add the following values:
Load balancer URL. Example:
https://LoadBalancer-3.example.com:9443
msgquser
m5gqu5er
m5gqu5er
5000 (This is the default value.)
Message Queue broker address list. Example:
MessageQueue-1.example.com:7777, MessageQueue-2.example.com:7777 |
Click Add, and then click Save.
Log in as a root user to the host Access Manager 1.
# cd /opt/SUNWwbsvr/https-AccessManager-1.example.com/config |
Edit file server.xml.
Make a backup of this file, and then make the following changes:
Edit the file sun-web.xml.
cd /opt/SUNWwbsvr/https-AccessManager-1.example.com/is-web-apps/services/WEB-INF |
Log in as a root user to the host Access Manager 2.
# cd /opt/SUNWwbsvr/https-AccessManager-2.example.com/config |
Edit file server.xml.
Make a backup of this file, and then make the following changes:
Edit the file sun-web.xml.
cd /opt/SUNWwbsvr/https-AccessManager-2.example.com/is-web-apps/services/WEB-INF |
Restart Access Manager 1 and Access Manager 2.
# cd /opt/SUNWwbsvr/https-AccessManager-1
# ./stop; ./start
# cd /opt/SUNWwbsvr/https-AccessManager-2
# ./stop; ./start
Both Access Manager 1 and Access Manager 2 should be up and running before you begin this verification procedure.
Stop Access Manager 1.
# cd /opt/SUNWwbsvr/https-AccessManager-1 # ./stop |
Open a browser (Browser 1) and go to the following Access Manager load balancer URL:
https://LoadBalancer-3.example.com:9443/amserver/UI/Login?realm=users |
Log in to the Access Manager console using the following information:
testuser1
password
The Edit User page for testuser1 is displayed.
This indicates that although Access Manager 1 was stopped (see step 1), the Access Manager load balancer (LoadBalancer-3) directed your login request to Access Manager 2, and the session for testuser1 was successfully created in Access Manager 2.
Leave Browser 1 open.
On the host AccessManager–1, at the command line, start Access Manager 1.
# cd /opt/SUNWwbsvr/https-AccessManager-1 # ./start |
Both Access Manager 1 and Access Manager 2 are now up and running.
Open a second browser (Browser 2) and go to the following Access Manager URL:
http://accessmanager-1.example.com:1080/amserver/UI/Login |
Log in to the Access Manager console using the following information:
amadmin
4m4dmin1
On the Realms page, click the Sessions tab.
Stop Access Manager 2.
# cd /opt/SUNWwbsvr/https-AccessManager-2 # ./stop |
Access Manager 1 is still up and running, and Access Manager 2 is now stopped.
In Browser 1, in the Edit User page for testuser1, modify the user profile.
In the Full Name field, enter NewTestUser1, and then click Save.
The message “Profile was updated” is displayed.
In Browser 2, in the Realms page, click the Sessions tab.
In the View: list, select AccessManager-1.example.com:1080.
Verify that now two UserIds, named amAdmin and testuser1, exist in the Sessions list. This indicates that the session successfully failed over to Access Manager 1.
Close Browser 2.
Start Access Manager 2.
# cd /opt/SUNWwbsvr/https-AccessManager-2 # ./start |
Both Access Manager 1 and Access Manager 2 are now up and running.
Stop Access Manager 1.
# cd /opt/SUNWwbsvr/https-AccessManager-1 # ./stop |
Access Manager now down, and Access Manager 2 is still up and running.
In a new browser (Browser 3), go to the following Access Manager URL:
http://accessmanager-2.example.com:1080/amserver/UI/Login |
Log in to the Access Manager console using the following information:
amadmin
4m4dmin1
Leave the browser open.
In Browser 1, in the Edit User page for testuser1, modify the user profile.
In the Full Name field, change NewTestUser1 back to TestUser1, and then click Save.
The message “Profile is updated” is displayed.
In Browser 3, on the Sessions tab, click Search to refresh the page.
Under Sessions, two UserIDs, named amAdmin and testuser1 , are now displayed in the Sessions list. This indicates that the session successfully failed back to Access Manager 2.