Installing Session failover This chapter covers setting up session failover when using multiple instances of OpenAM in a site configuration for high availability. The basic idea followed here is that you configure load balancing to be sticky, based on the value of an OpenAM cookie, amlbcookie, different for each OpenAM server. Should that server become unavailable, the load balancer fails client requests over to another OpenAM server. The other OpenAM server must then fail over the user session associated with the client. Session failover uses a highly available data store for OpenAM session data, shared by OpenAM servers in a site configuration. When the OpenAM server where a user authenticated goes down, other OpenAM servers can read the user session information from the highly available store, so the user does not have to authenticate again. When the original OpenAM server becomes available again, it can also read session information from the store, and carry on serving users with active sessions. Session failover is supported within a site or data center with a shared local area network. Session failover is not supported across sites and data centers linked by wide area networks (WAN). Latency over the WAN can cause issues with the underlying message queue, and therefore prevents reliable session failover. Before you set up session failover, first configure OpenAM in a site configuration with a load balancer as the entry point to the site. The most expedient way to configure the site is to set it up during initial OpenAM configuration, where OpenAM can manage and replicate server configuration for availability. If you did not set up the site during initial configuration, then follow all the steps below. In the OpenAM console for one of the servers in the site, select Configuration > Servers and Sites > Sites > New..., and then create a new site. The site URL is the URL to the load balancer in front of your OpenAM servers in the site. For example, if your load balancer listens on host lb.example.com and port 8080, with OpenAM under /openam, then your site URL is http://lb.example.com:8080/openam. On each OpenAM server console in the site, select Configuration > Servers and Sites > Servers > Server Name, and then set Parent Site to the site you created before saving your work. If you want to use sticky load balancing, configure your load balancer to inspect the value of the amlbcookie to determine which OpenAM server should receive the client request. As your load balancer depends on the amlbcookie value, on each OpenAM server console in the site, select Configuration > Servers and Sites > Servers > Server Name > Advanced, set com.iplanet.am.lbcookie.value to a unique value, and save your work. After you restart the OpenAM server, amlbcookie values from OpenAM should be as you configured them. (To check, login to the console and check the cookie value in your browser.) Restart each OpenAM server or the web containers where the OpenAM servers run so that all configuration changes take effect. The session data service relies on Java Message Queue and Berkeley DB Java Edition. You set up the session failover service in a site cluster to serve as the highly available session data store. Install the session tools from ssoSessionTools.zip on at least two, and generally not more than four, servers where you run OpenAM.You install more than one instance of the session tools in case an instance crashes and must fail over to another instance. At the same time, session failover requires that messages be sent across the network from one instance to another to stay in sync in case of failover. If you install too many instances, however, then the increase in network traffic for synchronization can impair performance. For example, you can install the session tools in the OpenAM configuration directory. $ cd $HOME/openam $ unzip /path/to/OpenAM/tools/ssoSessionTools.zip ... $ ./setup Name of the directory to install the scripts (example: sfoscripts):sfoscripts The scripts are properly setup under directory: /home/user/openam/sfoscripts JMQ is properly setup under directory /home/user/openam/jmq Start the Message Queue broker in order to configure user accounts. $ cd jmq/imq/bin $ ./imqbrokerd -name aminstance -port 7777 & Change the default admin password from admin to something else. $ ./imqusermgr update -u admin -p password -i aminstance User repository for broker instance: aminstance Are you sure you want to update user admin? (y/n)[n] y User admin successfully updated. Disable the default guest account. $ ./imqusermgr update -u guest -a false -i aminstance User repository for broker instance: aminstance Are you sure you want to update user guest? (y/n)[n] y User guest successfully updated. Add a user for the session failover service. $ ./imqusermgr add -u openamuser -g admin -p secret12 -i aminstance User repository for broker instance: aminstance User openamuser successfully added. Create a password file for the session failover service. $ cd sfoscripts/bin/ $ ./amsfopassword --encrypt secret12 --passwordfile /home/user/openam/mqpwd.txt os.name=Linux SUCCESSFUL Stop the broker you started on port 7777. Configure the session failover service for the site. For each session tools installation, edit the /home/user/openam/sfoscripts/config/lib/amsfo.conf configuration file to change at least the USER_NAME, CLUSTER_LIST, and PASSWORDFILE parameters. USER_NAME should match the user you created for the session failover service. USER_NAME=openamuser CLUSTER_LIST specifies the host:port combinations for all the session failover services you configure for the site. CLUSTER_LIST=openam.example.com:7777,openam2.example.com:7777 PASSWORDFILE specifies the path to the password file you created. PASSWORDFILE=/home/user/openam/mqpwd.txt You can optionally set AMSESSIONDB_ARGS="-v" to log additional information. Enabling session failover at this point involves configuring OpenAM to use the session data store, and then starting services. Examples in this procedure show OpenAM running in Apache Tomcat. On each OpenAM server console in the site, select Configuration > Global > Session > Instances > New... to set up session data store access. Provide a user name for the Session Store User, such as openamuser, with the same password you entered into the password file, and the Database Url is the host:port combination that you entered for the CLUSTER_LIST parameter. Be sure to Add the new instance, and then also Save your configuration changes. The configuration changes take effect after you restart OpenAM. Stop each OpenAM server in the site. $ /etc/init.d/tomcat stop Start each session data service in the cluster. $ cd /home/user/openam/sfoscripts/bin $ ./amsfo start By default, the log and session data store are located under /tmp/amsession/. $ tail -f /tmp/amsession/logs/amsessiondb.log ... Initializing and connecting to the Message Queue server ... Successfully started. Start each OpenAM server in the site. $ /etc/init.d/tomcat start Wait for each OpenAM server to start before starting another. $ tail -f /path/to/tomcat/logs/catalina.out ... INFO: Server startup in 26047 ms After OpenAM has started, you can test session failover.