memcached session manager SetupAndConfiguration for tomcat

285572001

[size=120%]SetupAndConfiguration  
This page shows what's necessary to get the memcached-session-manager up and running.

Featured,
Phase-Deploy
Updated
Jun 15, 2013 by
martin.grotzke

• Introduction
  
• Decide which serialization strategy to use
  
• Configure tomcat
  
  
  
  • Add memcached-session-manager jars to tomcat
    
  • Add custom serializers to your webapp (optional)
    
  • Configure memcached-session-manager as <Context> Manager
    
  • Overview over memcached-session-manager configuration attributes
    
  
  
  
• Configure logging
  

Introduction
　　For the most simple integration you just need to have a tomcat (6 or 7) and a memcached installed (or s.th. supporting the memcached protocol). In your production environment you probably will have several tomcats and you should
also have several memcached nodes available, on different pieces of hardware. You can use sticky sessions or non-sticky sessions, memcached-session-manager (msm) supports both operation modes.
　　The following description shows an example for a setup with sticky sessions, with two instances of tomcat and two instances of memcached installed.
　　Tomcat-1 (t1) will primarily store it's sessions in memcached-2 (m2) which is running on another machine (m2 is a regular node for t1). Only if m2 is not available, t1 will store it's sessions in memcached-1 (m1, m1 is the failoverNode
for t1). With this configuration, sessions won't be lost when machine 1 (serving t1 and m1) crashes. The following really nice ASCII art shows this setup.

<t1>   <t2>
  . \ / .
  .  X  .
  . / \ .
<m1>   <m2>
　　So what needs to be done for this?

Decide which serialization strategy to use
　　Starting with release 1.1 there are several session serialization strategies available, as they are described onSerializationStrategies.
The default strategy uses java serialization and is already provided by the memcached-session-manager jar. Other strategies are provided by separate jars, in the section below you'll see which jars are required for which strategy.

Configure tomcat
　　The configuration of tomcat requires two things: you need to drop some jars in your$CATALINA_HOME/lib/ and
WEB-INF/lib/ directories and you have to configure the memcached session manager in the related<Context> element (e.g. in
$CATALINA_HOME/conf/context.xml).

Add memcached-session-manager jars to tomcat
　　Independent of the chosen serialization strategy you always need thememcached-session-manager-${version}.jar and either
memcached-session-manager-tc6-${version}.jar for tomcat6 or
memcached-session-manager-tc7-${version}.jar for tomcat7.
　　If you're using memcached or couchbase, you also need thespymemcached-2.8.12.jar and
couchbase-client-1.1.4.jar.
　　If you're using couchbase, you need additionally these jars:jettison-1.1.jar,
commons-codec-1.5.jar,
httpcore-4.1.1.jar,
httpcore-nio-4.1.1.jar,
netty-3.5.5.Final.jar.
　　Please download the appropriate jars and put them in$CATALINA_HOME/lib/.


Add custom serializers to your webapp (optional)
　　If you want to use java's built in serialization nothing more has to be done. If you want to use a custom serialization strategy (e.g. because ofbetter
performance) this has to be deployed with your webapp so that they're available inWEB-INF/lib/.

　　As msm is available in maven central (under groupIdde.javakaffee.msm) you can just pull it in using the dependency management of your build system. With maven you can use this dependency definition for the kryo-serializer:

<dependency>
    <groupId>de.javakaffee.msm</groupId>
    <artifactId>msm-kryo-serializer</artifactId>
    <version>1.6.5</version>
    <scope>runtime</scope>
</dependency>
　　For javolution the artifactId is msm-javolution-serializer, for xstreammsm-xstream-serializer and for flexjson it's
msm-flexjson-serializer.
　　If you're not using a dependency management based on maven repositories these are the jars you need for the different serializers:

• kryo-serializer:
  msm-kryo-serializer,
  kryo-serializers-0.10 (0.10 is needed, as 0.20&#43; is for kryo2),
  kryo,
  minlog,
  reflectasm,
  asm-3.2
  
• javolution-serializer:
  msm-javolution-serializer,
  javolution-5.4.3.1
  
• xstream-serializer:
  msm-xstream-serializer,
  xstream,
  xmlpull,
  xpp3_min
  
• flexjson-serializer:
  msm-flexjson-serializer,
  flexjson
  

Configure memcached-session-manager as<Context> Manager
　　Update the <Context> element (in $CATALINA_HOME/conf/context.xml or what else you choose for context definition, please check the relatedtomcat
documentation for this) so that it contains the Manager configuration for the memcached-session-manager, like in the examples below.
　　The following examples show configurations for sticky sessions and non-sticky sessions with memcached servers and for non-sticky sessions with membase. The examples with memcached servers assume that there are two memcacheds
running, one on host1 and another one on host2. All sample configurations assume that you want to use kryo based serialization.
　　The following example shows the configuration of the first tomcat, assuming that it runs on host1, together with memcached &quot;n1&quot;. The attributefailoverNodes=&quot;n1&quot; tells msm to store sessions preferably in memcached &quot;n2&quot;
and only store sessions in &quot;n1&quot; (running on the same host/machine) if no other memcached node (here only n2) is available (even if host1 goes down completely, the session is still available in memcached &quot;n2&quot; and could be served by the tomcat on host2). For
the second tomcat (on host2) you just need to change the failover node to &quot;n2&quot;, so that it prefers the memcached &quot;n1&quot;. Everything else should be left unchanged.

<Context>
  ...
  <Manager className=&quot;de.javakaffee.web.msm.MemcachedBackupSessionManager&quot;
    memcachedNodes=&quot;n1:host1.yourdomain.com:11211,n2:host2.yourdomain.com:11211&quot;
    failoverNodes=&quot;n1&quot;
    requestUriIgnorePattern=&quot;.*\.(ico|png|gif|jpg|css|js)$&quot;
    transcoderFactoryClass=&quot;de.javakaffee.web.msm.serializer.kryo.KryoTranscoderFactory&quot;
    />
</Context>
　　The following example shows a configuration for non-sticky sessions. In this case there's no need forfailoverNodes, as sessions are served by all tomcats round-robin and they're not bound to a single tomcat. For non-sticky
sessions the configuration (for both/all tomcats) would look like this:

<Context>
  ...
  <Manager className=&quot;de.javakaffee.web.msm.MemcachedBackupSessionManager&quot;
    memcachedNodes=&quot;n1:host1.yourdomain.com:11211,n2:host2.yourdomain.com:11211&quot;
    sticky=&quot;false&quot;
    sessionBackupAsync=&quot;false&quot;
    lockingMode=&quot;uriPattern:/path1|/path2&quot;
    requestUriIgnorePattern=&quot;.*\.(ico|png|gif|jpg|css|js)$&quot;
    transcoderFactoryClass=&quot;de.javakaffee.web.msm.serializer.kryo.KryoTranscoderFactory&quot;
    />
</Context>
　　To connect to a membase bucket &quot;bucket1&quot; the configuration would look like this:

<Context>
  ...
  <Manager className=&quot;de.javakaffee.web.msm.MemcachedBackupSessionManager&quot;
    memcachedNodes=&quot;http://host1.yourdomain.com:8091/pools&quot;
    username=&quot;bucket1&quot;
    password=&quot;topsecret&quot;
    memcachedProtocol=&quot;binary&quot;
    sticky=&quot;false&quot;
    sessionBackupAsync=&quot;false&quot;
    requestUriIgnorePattern=&quot;.*\.(ico|png|gif|jpg|css|js)$&quot;
    transcoderFactoryClass=&quot;de.javakaffee.web.msm.serializer.kryo.KryoTranscoderFactory&quot;
    />
</Context>
　　More details for all configuration attributes are provided in the section below.
　　After you have configured msm in the Context/Manager element, you can just start your application and sessions will be stored in the memcached nodes or in membase as configured. Now you should do some tests with a simulated
tomcat failure, a restart of a memcached node etc. - have fun! :-)

Overview over memcached-session-manager configuration attributes
　　className (required)

This should be set to de.javakaffee.web.msm.MemcachedBackupSessionManager to get sessions stored in memcached. However, since version 1.3.6 there's also ade.javakaffee.web.msm.DummyMemcachedBackupSessionManager
that can be used for development purposes: it simply serializes sessions to a special in memory map and deserializes the serialized data at the next request when a session is requested (without really using this session) - just to see if deserialization is
working for each request. Your application is still using sessions as if the memcached-session-manager (or DummyMemcachedBackupSessionManager) would not be existing. Session serialization/deserialization is done asynchronously. The configuration attributes
memcachedNodes andfailoverNode are not used to create a memcached client, so serialized session data willnot be sent to memcached - and therefore no running memcacheds are required.

　　memcachedNodes (required)

This attribute must contain all memcached nodes you have running, or the membase bucket uri(s). It should be the same for all tomcats.



memcached nodes: Each memcached node is defined as <id>:<host>:<port>. Several definitions are separated by space or comma (e.g.memcachedNodes=&quot;n1:app01:11211,n2:app02:11211&quot;). For a single node the
<id> is optional so that it's allowed to set only <host>:<port> (e.g.memcachedNodes=&quot;localhost:11211&quot;). Then the sessionId will be left unchanged (no node id appended). This option is useful for the usage with e.g. membase&#43;moxi, where
each tomcat knows only a single &quot;memcached&quot; node (moxi actually).



membase bucket uris (since 1.6.0): For usage with membase it's possible to specify one or more membase bucket uris, e.g.http://host1:8091/pools,http://host2:8091/pools. Bucket name and password are specified via the attributesusername and
password (see below). Connecting to membase buckets requires the binary memcached protocol. Also remember to have thejettison.jar and
netty.jar available in CATALINA_HOME/lib/.

　　failoverNodes (optional, must not be used for non-sticky sessions)

This attribute must contain the ids of the memcached nodes, that shall not be used by this tomcat for session backup, but only if no other memcached nodes are available. Therefore, you should list those memcached nodes,
that are running on the same machine as this tomcat. Several memcached node ids are separated by space or comma. For non-sticky sessions failoverNodes must not be specified as a session is not tied to a single tomcat. For membase buckets this attribute should
also be left out.

　　username (since 1.6.0, optional)

Specifies the username used for a membase bucket or SASL. If thememcachedNodes contains a membase bucket uri (or multiple) this is the bucket name. If thememcachedNodes contains memcached node definitions
this is the username used for SASL authentication. Both require the binary memcached protocol.

　　password (since 1.6.0, optional)

Specifies the password used for membase bucket or SASL authentication (can be left empty / omitted if the &quot;default&quot; membase bucket without a password shall be used).

　　memcachedProtocol (since 1.3, optional, defaulttext)

This attribute specifies the memcached protocol to use, one oftext or
binary.

　　sticky (since 1.4.0, optional, default
true)

Specifies if sticky or non-sticky sessions are used.

　　lockingMode (since 1.4.0, optional, for non-sticky sessions only, defaultnone)

Specifies the locking strategy for non-sticky sessions. Session locking is useful to prevent concurrent modifications and lost updates of the session in the case of parallel requests (tabbed browsing with long requests,
ajax etc.). Session locking is done using memcached. Possible values for lockingMode are:

• none: sessions are never locked
  
• all: the session is locked when requested by the app until the end of the request
  
• auto: readonly requests are detected, for them the session is not locked. For requests that are not classified as &quot;readonly&quot; the session is locked
  
• uriPattern:<regexp>: the provided
  regular expression pattern is compared with the requestURI &#43; &quot;?&quot; &#43;
  queryString and the session is locked if they match.
  

　　requestUriIgnorePattern (optional)

This attribute contains a regular expression for request URIs, that shall not trigger a session backup. If static resources like css, javascript, images etc. are delivered by the same tomcat and the same web application
context these requests will also pass the memcached-session-manager. However, as these requests should not change anything in a http session, they should also not trigger a session backup. So you should check if any static resources are delivered by tomcat
and in this case you should exclude them by using this attribute. The requestUriIgnorePattern must follow the java regexPattern.

　　sessionBackupAsync (optional, default
true)

Specifies if the session shall be stored asynchronously in memcached. If this istrue, the
backupThreadCount setting is evaluated. If this is false, the timeout set via
sessionBackupTimeout is evaluated.

　　backupThreadCount (since 1.3, optional, defaultnumber-of-cpu-cores)

The number of threads that are used for asynchronous session backup (ifsessionBackupAsync=&quot;true&quot;). For the default value the number of available processors (cores) is used.

　　sessionBackupTimeout (optional, default
100)

The timeout in milliseconds after that a session backup is considered as beeing failed. This property is only evaluated if sessions are stored synchronously (set viasessionBackupAsync). The default value is
100 milliseconds.

　　operationTimeout (since 1.6.0, optional, default1000)

The memcached operation timeout used at various places, e.g. used for the spymemcached ConnectionFactory.

　　sessionAttributeFilter (since 1.5.0, optional)

A regular expression to control which session attributes are serialized to memcached. The regular expression is evaluated with session attribute names. E.g.sessionAttributeFilter=&quot;^(userName|sessionHistory)$&quot;
specifies that only &quot;userName&quot; and &quot;sessionHistory&quot; attributes are stored in memcached. Works independently from the chosen serialization strategy.

　　transcoderFactoryClass (since 1.1, optional, defaultde.javakaffee.web.msm.JavaSerializationTranscoderFactory)

The class name of the factory that creates the transcoder to use for serializing/deserializing sessions to/from memcached. The specified class must implementde.javakaffee.web.msm.TranscoderFactory and provide
a no-args constructor. OtherTranscoderFactory implementations are available through other packages/jars likemsm-kryo-serializer,
msm-xstream-serializer and msm-javolution-serializer (as describe above), those are listed and compared onSerializationStrategies.

Available TranscoderFactory implementations:

• Java serialization: de.javakaffee.web.msm.JavaSerializationTranscoderFactory
  
• Kryo based serialization:de.javakaffee.web.msm.serializer.kryo.KryoTranscoderFactory
  
• Javolution based serialization: de.javakaffee.web.msm.serializer.javolution.JavolutionTranscoderFactory
  
• XStream based serialization: de.javakaffee.web.msm.serializer.xstream.XStreamTranscoderFactory
  

　　copyCollectionsForSerialization (since 1.1, optional, defaultfalse)

A boolean value that specifies, if iterating over collection elements shall be done on a copy of the collection or on the collection itself. This configuration property must be supported by the serialization strategy
specified with transcoderFactoryClass. Which strategy supports this feature can be seen in the columnCopy Collections before serialization in the list of
available serialization strategies. This feature and its motivation is described more deeply atSerializationStrategies#Concurrent_modifications_of_collections.

　　customConverter (since 1.2, optional)

Custom converter allow you to provide custom serialization of application specific types. Multiple custom converter class names are specified separated by comma (with optional space following the comma). Converter classes
must be available in the classpath of the web application (place jars in WEB-INF/lib).



This option is useful if you need some special serialization for a certain type or if reflection based serialization is just very verbose and you want to provide a more efficient serialization for a specific type.



Custom converter must be supported by the serialization strategy specified with
transcoderFactoryClass. Requirements regarding the specific custom converter classes depend on the actual serialization strategy, but a common requirement would be that they must provide a default/no-args constructor. For more details have a look atavailable
serialization strategies.

Available converter implementations:

• Kryo (converters provided by msm-kryo-serializer jar)
  
  
  
  • de.javakaffee.web.msm.serializer.kryo.JodaDateTimeRegistration: A more efficient serialization of Joda'sDateTime
    with kryo.
    
  • de.javakaffee.web.msm.serializer.kryo.CGLibProxySerializerFactory: serializes/deserializes CGLIB proxies.
    
  • de.javakaffee.web.msm.serializer.kryo.HibernateCollectionsSerializerFactory: serializes/deserializes hibernate persistent collections (required if you store collections loaded by hibernate in your session).
    
  • de.javakaffee.web.msm.serializer.kryo.WicketSerializerFactory: required if you're running a wicket web application.
    
  • de.javakaffee.web.msm.serializer.kryo.FacesLRUMapRegistration: Needed if kryo serialization shall be used in combination with JSF2/Mojarra (see alsoissue
    #97).
    
  • de.javakaffee.web.msm.serializer.kryo.GrailsFlashScopeRegistration: Support for grails flash scope (see alsoissue #107).
    
    
  
  
  
• Javolution (converters provided by msm-javolution-serializer jar)
  
  
  
  • de.javakaffee.web.msm.serializer.javolution.JodaDateTimeFormat: A more efficient serialization of Joda'sDateTime,
    see also
    issue #32.
    
  • de.javakaffee.web.msm.serializer.javolution.CGLibProxyFormat : serializes/deserializes CGLIB proxies, see alsoissue #59.
    
    
  • de.javakaffee.web.msm.serializer.javolution.HibernateCollectionsXMLFormat: serializes/deserializes hibernate persistent collections (required if you store collections loaded by hibernate in your session).
    
  
  
  

　　enableStatistics (since 1.2, optional, defaulttrue)

A boolean value that specifies, if statistics shall be gathered. For more info see theJMXStatistics page.

　　enabled (since 1.4.0, optional, default
true)

Specifies if session storage in memcached is enabled or not, can also be changed at runtime via JMX. Only allowed in sticky mode.

Configure logging
　　If you want to enable fine grained / debug logging you can add

de.javakaffee.web.msm.level=FINE
　　to $CATALINA_HOME/conf/logging.properties.
　　As the memcached-session-manager uses
spymemcached also the
logging hints of spymemcached might be interesting to you. A short summary how you can make spymemcached more silent:

• Add the following to $CATALINA_HOME/bin/catalina.sh:
  CATALINA_OPTS=&quot;-Dnet.spy.log.LoggerImpl=net.spy.memcached.compat.log.SunLogger&quot;
  
• Add this to $CATALINA_HOME/conf/logging.properties:
  # A handler's log level threshold can be set using SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST or ALL
  net.spy.memcached.level = WARNING
  # To make only the MemcachedConnection less verbose:
  #net.spy.memcached.MemcachedConnection.level = WARNING
  

　　More info about logging in tomcat can be found in thetomcat logging documentation.