AWS SDK for Java
Developer Guide

Managing Tomcat Session State with DynamoDB

Tomcat applications often store session-state data in memory. However, this approach doesn't scale well because once the application grows beyond a single web server, the session state must be shared among servers. A common solution is to set up a dedicated session-state server with MySQL. However, this approach also has drawbacks: you must administer another server, the session-state server is a single pointer of failure, and the MySQL server itself can cause performance problems.

DynamoDB, which is a NoSQL database store from AWS, avoids these drawbacks by providing an effective solution for sharing session state across web servers.

Download the Session Manager

You can download the session manager from the aws/aws-dynamodb-session-tomcat project on GitHub. This project also hosts the session manager source code, so you can contribute to the project by sending us pull requests or opening issues.

Configure the Session-State Provider

To use the DynamoDB session-state provider, you must do the following:

  1. Configure the Tomcat server to use the provider.

  2. Set the security credentials of the provider so that it can access AWS.

Configure a Tomcat Server to Use DynamoDB as the Session-State Server

Copy AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar to the lib directory of your Tomcat installation. AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar is a complete, standalone JAR that contains all the code and dependencies to run the DynamoDB Tomcat Session Manager.

Edit your server's context.xml file to specify as your session manager.

<?xml version="1.0" encoding="UTF-8"?> <Context> <WatchedResource>WEB-INF/web.xml</WatchedResource> <Manager className="" createIfNotExist="true" /> </Context>

Configure Your AWS Security Credentials

You can specify AWS security credentials for the session manager in multiple ways. They are loaded in the following order of precedence:

  1. The AwsAccessKey and AwsSecretKey attributes of the Manager element explicitly provide credentials.

  2. The AwsCredentialsFile attribute on the Manager element specifies a properties file from which to load credentials.

If you don't specify credentials through the Manager element, DefaultAWSCredentialsProviderChain continues searching for credentials in the following order:

  1. Environment variables –AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

  2. Java system properties –aws.accessKeyId and aws.secretKey

  3. Instance profile credentials delivered through the Amazon EC2 instance metadata service (IMDS)

Configure with Elastic Beanstalk

If you're using the session manager in Elastic Beanstalk, ensure your project has an .ebextensions directory at the top level of your output artifact structure. Put the following files in .ebextensions directory:

  • The AmazonDynamoDBSessionManagerForTomcat-1.x.x.jar file

  • A context.xml file, described previously, to configure the session manager

  • A configuration file that copies the JAR into Tomcat's lib directory and applies the overridden context.xml file.

For more information about customizing Elastic Beanstalk environments, see AWS Elastic Beanstalk Environment Configuration in the AWS Elastic Beanstalk Developer Guide.

If you deploy to Elastic Beanstalk with the AWS Toolkit for Eclipse, you can have the toolkit set up the session manager for you; use the New AWS Java Web Project wizard and choose DynamoDB for session management. The AWS Toolkit for Eclipse configures the required files and puts them in the .ebextensions directory in the WebContent directory of your project. If you have problems finding this directory, be sure you aren't hiding files that begin with a period.

Manage Tomcat Session State with DynamoDB

If the Tomcat server is running on an Amazon EC2 instance that is configured to use IAM roles for EC2 instances, you don't need to specify any credentials in the context.xml file. In this case, the AWS SDK for Java uses IAM roles credentials obtained through the instance metadata service (IMDS).

When your application starts, it looks for a DynamoDB table named, by default, Tomcat_SessionState. The table should have a string hash key named "sessionId" (case-sensitive), no range key, and the desired values for ReadCapacityUnits and WriteCapacityUnits.

We recommend that you create this table before running your application for the first time. If you don't create the table, however, the extension creates it during initialization. See the context.xml options in the next section for a list of attributes that configure how the session-state table is created when it doesn't exist.


For information about working with DynamoDB tables and provisioned throughput, see the Amazon DynamoDB Developer Guide.

After the application is configured and the table is created, you can use sessions with any other session provider.

Options Specified in context.xml

You can use the following configuration attributes in the Manager element of your context.xml file:

  • AwsAccessKey– Access key ID to use.

  • AwsSecretKey– Secret key to use.

  • AwsCredentialsFile– A properties file containing accessKey and secretKey properties with your AWS security credentials.

  • Table– Optional string attribute. The name of the table used to store session data. The default is Tomcat_SessionState.

  • RegionId– Optional string attribute. The AWS Region in which to use DynamoDB. For a list of available AWS Regions, see Regions and Endpoints in the Amazon Web Services General Reference.

  • Endpoint– Optional string attribute that, if present, overrides any value set for the Region option. This attribute specifies the regional endpoint of the DynamoDB service to use. For a list of available AWS Regions, see Regions and Endpoints in Amazon Web Services General Reference.

  • ReadCapacityUnits– Optional int attribute. The read capacity units to use if the session manager creates the table. The default is 10.

  • WriteCapacityUnits– Optional int attribute. The write capacity units to use if the session manager creates the table. The default is 5.

  • CreateIfNotExist– Optional Boolean attribute. The CreateIfNotExist attribute controls whether the session manager autocreates the table if it doesn't exist. The default is true. If this flag is set to false and the table doesn't exist, an exception is thrown during Tomcat startup.


If you encounter issues with the session manager, the first place to look is in catalina.out. If you have access to the Tomcat installation, you can go directly to this log file and look for any error messages from the session manager. If you're using Elastic Beanstalk, you can view the environment logs with the AWS Management Console or the AWS Toolkit for Eclipse.


The session manager doesn't support session locking. Therefore, applications that use many concurrent AJAX calls to manipulate session data may not be appropriate for use with the session manager, due to race conditions on session data writes and saves back to the data store.