Installs/Configures Tomcat high-availability clusters with memcached using Martin Grotzke's https://code.google.com/p/memcached-session-manager.
- This cookbook expects
$CATALINA_HOME
to be defined in the environment. If$CATALINA_HOME
is not defined, then please overridenode['memcached_session_manager']['tomcat']['lib']
attribute. - Java & Tomcat must be installed outside of this cookbook.
- Chef 11.14 or higher.
- CentOS
- RedHat
- Ubuntu
The default
recipe adds required memcached_session_manager jars to Tomcat. Use the attributes below to configure
memcached_session_manager. Note memcached_session_manager_context
resource will automatically include the default
recipe.
node['memcached_session_manager']['version']
- The version of memcached_session_manager to install.node['memcached_session_manager']['flavor']
- Flavorsmemcached
andcouchbase
are supported. Defaults tomemcached
.node['memcached_session_manager']['tomcat']['base_version']
- Defaults to7
.node['memcached_session_manager']['tomcat']['lib']
- Defaults to$CATALINA_HOME/lib/
. Be sure to override this if $CATALINA_HOME is not defined in your environment.node['memcached_session_manager']['memcached']['spymemcached']
-
The version ofspymemcached
to install formemcached
.node['memcached_session_manager']['couchbase']['couchbase-client']
- The version ofcouchbase-client
to install forcouchbase
.node['memcached_session_manager']['couchbase']['jettison']
- The version ofjettison
to install forcouchbase
.node['memcached_session_manager']['couchbase']['commons-codec']
- The version ofcommons-codec
to install forcouchbase
.node['memcached_session_manager']['couchbase']['httpcore']
- The version ofhttpcore
to install forcouchbase
.node['memcached_session_manager']['couchbase']['httpcore-nio']
- The version ofhttpcore-nio
to install forcouchbase
.node['memcached_session_manager']['couchbase']['netty']
- The version ofnetty
to install forcouchbase
.
Updates the element in context.xml
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 "n1". The attribute failoverNodes="n1" tells msm to store sessions preferably in memcached "n2" and only store sessions in "n1" (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 "n2" and could be served by the tomcat on host2). For the second tomcat (on host2) you just need to change the failover node to "n2", so that it prefers the memcached "n1". Everything else should be left unchanged.
memcached_session_manager_context '/path/to/context.xml' do
memcachedNodes 'n1:host1.yourdomain.com:11211,n2:host2.yourdomain.com:11211'
failoverNodes 'n1'
requestUriIgnorePattern '.*\.(ico|png|gif|jpg|css|js)$'
end
The following example shows a configuration for non-sticky sessions. In this case there's no need for failoverNodes, 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:
memcached_session_manager_context '/path/to/context.xml' do
memcachedNodes 'n1:host1.yourdomain.com:11211,n2:host2.yourdomain.com:11211'
sticky false
sessionBackupAsync false
lockingMode 'uriPattern:/path1|/path2'
requestUriIgnorePattern '.*\.(ico|png|gif|jpg|css|js)$'
end
To connect to a membase bucket bucket1
the configuration would look like this:
memcached_session_manager_context '/path/to/context.xml' do
memcachedNodes 'http://host1.yourdomain.com:8091/pools'
username 'bucket1'
password 'topsecret'
memcachedProtocol 'binary'
sticky false
sessionBackupAsync false
requestUriIgnorePattern '.*\.(ico|png|gif|jpg|css|js)$'
end
If you are running multiple webapps/contexts sharing the same session id (e.g. by having set sessionCookiePath="/") you must tell memcached session manager to add a prefix to the session id when storing a session in memcached. For this you can use the storageKeyPrefix attribute as shown by this example (see also the more detailed attribute description below):
memcached_session_manager_context '/path/to/context.xml' do
memcachedNodes 'n1:host1.yourdomain.com:11211,n2:host2.yourdomain.com:11211'
failoverNodes 'n1'
storageKeyPrefix 'context'
requestUriIgnorePattern '.*\.(ico|png|gif|jpg|css|js)$'
end
install
- Adds or updates the element incontext.xml
so that it contains the Manager configuration for the memcached-session-manager.remove
- Removes the element incontext.xml
so that it contains the Manager configuration for the memcached-session-manager.
Documentation below has been trimmed down from the original. Please read the complete documentation here.
path
(required) - Defaults to name of the resource block. Specifies direct path to context.xml file.className
- Defaults tode.javakaffee.web.msm.MemcachedBackupSessionManager
.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.failoverNodes
(optional, must not be used for non-sticky sessions) - Defaults tonil
. Specifies ids of the memcached nodes that must only be used for session backup when none of the other memcached nodes are available. Several memcached node ids are separated by space or comma.username
- Defaults tonil
. Specifies the username used for a membase bucket or SASL.password
- Defaults tonil
. Specifies the password used for membase bucket or SASL authentication (can be left empty / omitted if the "default" membase bucket without a password shall be used).memcachedProtocol
- Defaults totext
- Specifies the memcached protocol to use, one oftext
orbinary
.sticky
- Defaults totrue
. Specifies if sticky or non-sticky sessions are used.lockingMode
(optional, for non-sticky sessions only) - Defaults tonone
. 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. Session locking is done using memcached. Possible values for lockingMode are:none
,all
,auto
, anduriPattern:<regexp>
.requestUriIgnorePattern
- Defaults tonil
. Specifies a regular expression for request URIs, that shall not trigger a session backup.sessionBackupAsync
- Defaults totrue
. Specifies if the session shall be stored asynchronously in memcached. If this is true, the backupThreadCount setting is evaluated. If this is false, the timeout set via sessionBackupTimeout is evaluated.backupThreadCount
- Defaults tonil
(number-of-cpu-cores). The number of threads that are used for asynchronous session backup (if sessionBackupAsync="true"). For the default value the number of available processors (cores) is used.sessionBackupTimeout
- Defaults to100
milliseconds. The timeout in milliseconds after that a session backup is considered as being failed. This property is only evaluated if sessions are stored synchronously (set via sessionBackupAsync).operationTimeout
- Defaults to1000
. The memcached operation timeout used at various places, e.g. used for the spymemcached ConnectionFactory.storageKeyPrefix
- Defaults towebappVersion
Allows to configure a prefix that's added to the session id when a session is stored in memcached.sessionAttributeFilter
- Defaults tonil
. A regular expression to control which session attributes are serialized to memcached.transcoderFactoryClass
- Defaults tode.javakaffee.web.msm.JavaSerializationTranscoderFactory
.copyCollectionsForSerialization
- Defaults tofalse
. A boolean value that specifies, if iterating over collection elements shall be done on a copy of the collection or on the collection itself.customConverter
- Defaults tonil
. 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).enableStatistics
- Defaults totrue
. A boolean value that specifies, if statistics shall be gathered.enabled
- Defaults totrue
. Specifies if session storage in memcached is enabled or not, can also be changed at runtime via JMX. Only allowed in sticky mode.
This cookbook includes custom ChefSpec matchers you can use to test your own cookbooks.
Example Matcher Usage
expect(chef_run).to install_memcached_session_manager_context('/path/to/context.xml').with(
memcachedNodes: 'n1:host1.yourdomain.com:11211,n2:host2.yourdomain.com:11211',
failoverNodes: 'n1',
storageKeyPrefix: 'context',
requestUriIgnorePattern: '.*\.(ico|png|gif|jpg|css|js)$'
)
Cookbook Matchers
- install_memcached_session_manager_context(path)
- remove_memcached_session_manager_context(path)
- Ask specific questions on Stack Overflow.
- Report bugs and discuss potential features in Github issues.
Please refer to CONTRIBUTING.
MIT - see the accompanying LICENSE file for details.