<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! CCPL HEADER START
  !
  ! This work is licensed under the Creative Commons
  ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
  ! To view a copy of this license, visit
  ! http://creativecommons.org/licenses/by-nc-nd/3.0/
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! src/main/resources/legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
  ! If applicable, add the following below this CCPL HEADER, with the fields
  ! enclosed by brackets "[]" replaced with your own identifying information:
  !      Portions Copyright [yyyy] [name of copyright owner]
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011 ForgeRock AS
  !    
-->
<chapter xml:id='chap-session-failover'
 xmlns='http://docbook.org/ns/docbook'
 version='5.0' xml:lang='en'
 xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'
 xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Setting Up OpenAM Session Failover</title>

 <para>This chapter covers setting up session failover when using multiple
 instances of OpenAM for high availability.</para>
 
 <section>
  <title>Java EE Based Session Failover</title>
  <para>OpenAM includes a beta version session failover mechanism designed to
  replace the existing implementation that relies on Message Queue and Berkeley
  DB with a highly scalable, pure Java implementation.</para>
  
  <!-- TODO: Incorporate README themes below, modulo integration of components:
  
  1. Overview

amsessiondb is designed as a drop in replacement for the existing OpenAM session
failover system that uses MQ and Berkley DB.

2. Installation

Copy the following files into your OpenAM webapp WEB-INF/lib directory and
restart the container.

* AMSessionRepository-0.1-SNAPSHOT.jar
* AMSessionStoreCommon-0.1-SNAPSHOT.jar
* org.restlet.lib.org.json-2.0.jar
* commons-net-2.2.jar                   
* jackson-core-asl-1.4.3.jar            
* jackson-mapper-asl-1.4.3.jar          
* org.osgi.core-4.0.0.jar               
* org.restlet-2.0.6.jar                 
* org.restlet.ext.jackson-2.0.6.jar     
* org.restlet.ext.json-2.0.6.jar

3. Configuration

3.1. OpenAM Configuration

For OpenAM session failover to be configured, OpenAM must be running in a site
configuration. Please site this article to assist in configuring sites:

https://wikis.forgerock.org/confluence/display/openam/5+Extending+to+a+Dual+Instance+Deployment

When configuring the session service in OpenAM; the same procedure should be
followed only with these configuration changes to the secondary session
configuration instance.

* Session Store User : admin
* Session Store Password : <password>
* Session Store Password (confirm) : <password>
* Maximum Wait Time : 5000
* Database Url : http://localhost:8182/amsessiondb
* Session Failover Enabled : (True) Enabled

3.2 amsessiondb configuration.

amsessiondb is configured using the configuration files in the config directory:

* amsessiondb.properties : General configuration; port number, URI et cetera
* amsessiondblog.properties : Controls the log level of the components
* dbconfig.xml : Configures the embedded OrientDB server

4. Startup

In the amsessiondb/bin directory, run the start.sh command.

5. Operational

When the amsessiondb server is running, there are two useful URLs:

http://localhost:8182/amsessiondb/stats

This returns the following information in JSON format.

* uptime : The uptime of the server in ms
* numSessions : The number of sessions in the database
* totalRequests : The total number of requests received.
* totalReads : The total number of read requests received.
* totalWrites : The total number of write requests received.
* totalDeletes : The total number of delete requests received.
* totalReadSessionCount : The total number of read session count requests
  received.

http://localhost:8182/amsessiondb/config

This returns the configuration of the amsessiondb server in JSON format. This is
useful for debugging and support purposes.

6. Troubleshooting

amsessiondb logs its operations to the amsessiondb-0-0.log in the logs
directory.

To enable debugging change this entry amsessiondb.level in the
amsessiondblog.properties configuration file to FINEST and restart.
  
 -->
 </section>
 
 <section>
  <title>Message Queue Based Session Failover</title>
  
  <para>OpenAM fully supports Message Queue based session failover.</para>
  
  <!-- TODO: Explain how to set it up. -->
 </section>
</chapter>

