tomcat

Table of Contents

1. Overview - What is the tomcat module?
2. Module Description - What does the module do?
3. Setup - The basics of getting started with tomcat

• Installation scenarios
• Configuration scenarios

4. Usage - The classes and defined types available for configuration

• Classes and Defined Types
  • Class: tomcat
  • Define: tomcat::instance
  • Common parameters
  • Define: tomcat::userdb_entry
  • Define: tomcat::userdb_role_entry
  • Define: tomcat::context
  • Define: tomcat::web

5. Testing - How to run the included spec tests
6. Contributors

Overview

The tomcat module installs and configures Apache Tomcat instances from either the packages available in your distribution's repositories, or from any archive file you provide to it.

Module description

This module will install the desired version of the Apache Tomcat Web Application Container from almost any possible source, including the repositories available on the target system (distribution repositories or third-party sources like JPackage and EPEL)
A long list of parameters allow a fine tuning of the server and the JVM. Tomcat's most common elements are provided, and virtually any missing parameters can be included using the hash parameters present in each block.
It is also possible to configure, besides the server itself, admin applications, extra libraries, etc.
The creation of individual instances following Apache's guidelines is supported via a custom type.

Setup

tomcat will affect the following parts of your system:

• tomcat packages and dependencies
• tomcat service(s)
• instances configuration
• tomcat user database(s) and authorized users (defined type)

Including the main class is enough to install the default version of Tomcat provided by your distribution, and run it with default settings.

include tomcat

Installation scenarios

Install from archive instead of distribution package

class { 'tomcat':
  install_from => 'archive',
  version      => '8.0.15'
}

Disable main instance and setup 2 individual instances

class { 'tomcat':
  service_ensure => 'stopped',
  service_enable => false
}
tomcat::instance { 'instance1':
  server_control_port => 8005,
  http_port           => 8080,
  ajp_connector       => false,
  …
}
tomcat::instance { 'instance2':
  server_control_port => 8006,
  http_port           => 8081,
  manage_firewall     => true,
  …
}

Start a second instance with a different tomcat version

class { 'tomcat':
  install_from => 'archive',
  version      => '7.0.55'
  …
}
tomcat::instance { 'my_app':
  version => '8.0.18'
  …
}

Use a non-default JVM and run it with custom options

class { 'tomcat':
  java_home => '/usr/java/jre1.7.0_65',
  java_opts => ['-server', '-Xmx2048m', '-Xms256m', '-XX:+UseConcMarkSweepGC']
}

Enable the manager/host-manager webapps and configure default admin

class { 'tomcat':
  …
  admin_webapps        => true,
  create_default_admin => true,
  admin_user           => 'tomcatmaster',
  admin_password       => 'meow'
}

Use with custom packages/custom installation layouts (eg. with Ulyaoth)

class { 'tomcat':
  package_name               => 'ulyaoth-tomcat8',
  version                    => '8.0.15'
  service_name               => 'tomcat',
  config_path                => '/opt/tomcat/bin/setenv.sh',
  catalina_home              => '/opt/tomcat',
  catalina_pid               => '$CATALINA_TMPDIR/$SERVICE_NAME.pid',
  admin_webapps_package_name => 'ulyaoth-tomcat8-admin',
  tomcat_native              => true,
  tomcat_native_package_name => 'ulyaoth-tomcat-native'
  …
}

Download Tomcat archives behind a proxy server

class { 'tomcat':
  …
  proxy_server => 'http://user:password@proxy.example.com:8080'
}

Configuration scenarios

Enable the standard AJP connector on non-default port with custom parameters

class { 'tomcat':
  …
  ajp_connector => true,
  ajp_port      => 8090,
  ajp_params    => { 'address' => '127.0.0.1', 'packetSize' => 12288 }
}

Configure custom connectors

class { 'tomcat':
  …
  connectors => [
    { 'port'        => 9080,
      'protocol'    => 'org.apache.coyote.http11.Http11Nio2Protocol',
      'maxPostSize' => 2500000
    },
    { 'port' => 9081,
      'allowTrace' => true
    }
  ]
}

Configure a nested HTTP/2 connector (Tomcat 8.5+)

class { 'tomcat':
  …
  connectors => [
    { 'port'                     => 8443,
      'protocol'                 => 'org.apache.coyote.http11.Http11AprProtocol',
      'SSLEnabled'               => true,
      'defaultSSLHostConfigName' => 'example.com',
      'upgradeprotocol'          => {
        'className'   => 'org.apache.coyote.http2.Http2Protocol',
        'readTimeout' => 5000
      },
      'sslhostconfigs'           => [
        { 'hostName'         => 'example.com',
          'honorCipherOrder' => true,
          'certificates'     => [
            { 'certificateKeystoreFile' => 'conf/localhost.jks',
              'type'                    => 'RSA'
            },
            { 'certificateKeyFile'   => 'conf/localhost-key.pem',
              'certificateFile'      => 'conf/localhost-crt.pem',
              'certificateChainFile' => 'conf/localhost-chain.pem',
              'type'                 => 'RSA'
            }
          ]
        }
      ]
    }
  ]
}

Configure custom Listeners

class { 'tomcat':
  …
  listeners => [
    { 'className' => 'org.apache.catalina.storeconfig.StoreConfigLifecycleListener'
    },
    { 'className'     => 'org.apache.catalina.startup.UserConfig',
      'directoryName' => 'public_html'
    }
  ]
}

Customize Host

class { 'tomcat':
  …
  host_autodeploy      => false,
  host_deployonstartup => false,
  host_unpackwars      => true,
  host_params          => { createDirs => true },
  contexts             => [{ path => '', docBase => '/home/app', crossContext => true }]
}

or for more complex setup

class { 'tomcat':
  …
  hosts                => [
    {
      name            => 'www.example.org',
      deployonstartup => false,
      unpackwars      => true,
      createDirs      => true,
      contexts        => [{ path => '', docBase => '/home/app', crossContext => true }],
      valves          => [{ className => 'org.apache.catalina.valves.AccessLogValve', directory => 'logs', prefix => 'app_access_log', suffix => '.txt', pattern => '%h %l %u %t "%r" %s %b'}]
    },
    {
      name            => 'cas.example.org',
      deployonstartup => false,
      unpackwars      => true,
      createDirs      => true,
      contexts        => [{ path => '', docBase => '/home/cas', crossContext => true }],
      valves          => [{ className => 'org.apache.catalina.valves.AccessLogValve', directory => 'logs', prefix => 'cas_access_log', suffix => '.txt', pattern => '%h %l %u %t "%r" %s %b'}]
    }
  ]
  
}

Enable the remote JMX listener and remote JVM monitoring

class { 'tomcat':
  …
  jmx_listener      => true,
  jmx_registry_port => '8050',
  jmx_server_port   => '8051',
  jmx_bind_address  => $ipaddress_eth0,
  catalina_opts     => [ '-Dcom.sun.management.jmxremote',
                         '-Dcom.sun.management.jmxremote.ssl=false',
                         '-Dcom.sun.management.jmxremote.authenticate=false' ]
}

Configure custom Realms

class { 'tomcat':
  …
  realms => [
    { 'className' => 'org.apache.catalina.realm.MemoryRealm',
      'pathname'  => 'conf/myUsersDb.xml'
    },
    { 'className'         => 'org.apache.catalina.realm.DataSourceRealm',
      'dataSourceName'    => 'jdbc/myDataSource',
      'credentialhandler' => {
        'className' => 'org.apache.catalina.realm.MessageDigestCredentialHandler',
        'algorithm' => 'md5'
      }
    }
  ]
}

Configure main context.xml

class { 'tomcat':
  …
  context_params  => { 'docBase' => 'myapproot', 'useHttpOnly' => false },
  context_manager => { 'maxActiveSessions' => 1000 },
  context_resourcelinks => [
    { 'name'   => 'linkToGlobalResource',
      'global' => 'simpleValue',
      'type'   => 'java.lang.Integer'
    },
    { 'name'   => 'appDataSource',
      'global' => 'sharedDataSource',
      'type'   => 'javax.sql.DataSource'
    }
  ]
}

Configure default servlet (web.xml)

class { 'tomcat':
  …
  default_servlet_listings => true,
  default_servlet_gzip     => true,
  default_servlet_params   => { 'sendfileSize' => 64 }
}

Configure security constraints (web.xml)

class { 'tomcat':
  …
  security_constraints => [
    { 'display-name'            => 'Security constraint 1',
      'auth-constraint'         => { 'role-name' => ['admin', 'authenticated'] },
      'web-resource-collection' => { 'web-resource-name' => 'My sample web resource',
                                     'url-pattern'       => ['/example', '*.gif'],
                                     'http-method'       => ['GET', 'POST'] }
    },
    { 'display-name'            => 'Security constraint 2',
      'user-data-constraint'    => { 'transport-guarantee' => 'CONFIDENTIAL',
      'web-resource-collection' => { 'url-pattern'          => ['/protected/*'],
                                     'http-method-omission' => ['DELETE', 'PUT'] }
    }
  ]
}

Add an additional admin for the manager using a defined type

tomcat::userdb_entry { 'foo':
  database => 'main UserDatabase',
  password => 'bar',
  roles    => ['manager-gui', 'manager-script']
}

Add roles and users using helper parameters

class { 'tomcat':
  …
  tomcat_roles => {
    'opsgroup' => {} ,
    'qagroup'  => {}
  },
  tomcat_users => {
    'opsguy' => {
      password => 'qwerty',
      roles    => [ 'opsgroup', 'admin-gui' ]
    },
    'qaguy' => {
      password => '01234',
      roles    => [ 'qagroup', 'manager-gui' ]
    }
  }
}

Usage

This module distinguishes two different contexts:

• global: default instance and global libraries
• instance: individual tomcat instance

Both contexts share most of their parameters.

Classes and Defined Types

Class: tomcat

Primary class and entry point of the module

Parameters within tomcat:

Packages and service

install_from

What type of source to install from. The module will download the necessary files by itself. Valid values are package and archive. Defaults to package.

package_name

Tomcat package name. Ignored if installed from archive. Default depends on the distribution.

package_ensure

Tomcat package ensure attribute. Valid values are undef, present and latest. Defaults to undef (falls back to ${version}).

tomcat_native

Whether to install the Tomcat Native library. Boolean value. Defaults to false.

tomcat_native_package_name

Tomcat Native library package name. Default depends on the distribution.

extras_package_name

Package name for Tomcat extra libraries. If set, forces installation of Tomcat extra libraries from a package repository instead of Apache servers. The ensure attribute of the package resource will then default to the same value as ${package_ensure}. Defaults to undef.

admin_webapps_package_name

Admin webapps package name. Default depends on the distribution.

See also Common parameters

Define: tomcat::instance

Create a Tomcat instance

Parameters within tomcat::instance:

root_path

Absolute path to the root of all Tomcat instances. Defaults to /var/lib/tomcats.
Note: instances will be installed in ${root_path}/${title} and $CATALINA_BASE will be set to that directory

See also Common parameters

Common parameters

Parameters common to both tomcat and tomcat::instance

Packages and service

version

Tomcat full version number. The valid format is 'x.y.z[.M##][-package_suffix]'. The package ensure attribute will be enforced to this value if Tomcat is installed from a package repository.
Must include the full package suffix on Debian variants.
Note: multi-version only supported if installed from archive

archive_source

Base path of the source of the Tomcat installation archive, if installed from archive. Supports local files, puppet://, http://, https:// and ftp://. Defaults to ${archive_mirror}/dist/tomcat/tomcat-<maj_version>/v<version>/bin.

archive_filename

File name of the Tomcat installation archive, if installed from archive. Defaults to apache-tomcat-<version>.tar.gz.

archive_mirror

Mirror to use if installed from archive and no archive source was provided but version was. Defaults to http://archive.apache.org.

proxy_server

URL of a proxy server used for downloading Tomcat archives

proxy_type

Type of the proxy server. Valid values are none, http, https and ftp. Optional. Default determined by the scheme used in ${proxy_server}

checksum_verify

Whether to enable the checksum verification of Tomcat installation archive. Boolean value. Defaults to false.

checksum_type

Checksum type. Valid values are none, md5, sha1, sha2, sh256, sha384 and sha512. Defaults to none.

checksum

Checksum to test against. Defaults to undef.

service_name

Tomcat service name. Defaults to ${package_name} (global) / ${package_name}_${title} (instance).

service_ensure

Whether the service should be running. Valid values are stopped and running. Defaults to running.

service_enable

Whether to enable the Tomcat service. Boolean value. Defaults to true.

restart_on_change

Whether to restart Tomcat service after configuration change. Boolean value. Defaults to true.

systemd_service_type

The value for the systemd service type if applicable. Defaults to 'simple' for install_from = package, 'forking' for install_from = archive.

force_init

Whether to force the generation of a generic init script/unit for the tomcat service. Useful for custom OS packages which do not include any. Defaults to false.

service_start

Optional override command for starting the service. Default depends on the platform.

service_stop

Optional override command for stopping the service. Default depends on the platform.

tomcat_user

Tomcat user. Defaults to ${service_name} (Debian) / tomcat (all other distributions).

tomcat_user_id

Tomcat user id. Defaults to undef, will be generated at user creation.

tomcat_group

Tomcat group. Defaults to ${tomcat_user}.

tomcat_group_id

Tomcat group id. Defaults to undef, will be generated at group creation.

file_mode

File mode for certain configuration xml files. Defaults to '0600'.

extras_enable

Whether to install Tomcat extra libraries. Boolean value. Defaults to false.
Warning: extra libraries are enabled globally if defined within the global context

extras_source

Base path of the source of the Tomcat extra libraries. Supports local files, puppet://, http://, https:// and ftp://. Defaults to ${archive_mirror}/dist/tomcat/tomcat-<maj_version>/v<version>/bin/extras.

manage_firewall

Whether to automatically manage firewall rules. Boolean value. Defaults to false.

Security and administration

admin_webapps

Whether to enable admin webapps (manager/host-manager). This will also install the required packages if Tomcat was installed from package. This parameter is ignored if Tomcat was installed from archive, since Tomcat archives always contain these apps. Boolean value. Defaults to true.

create_default_admin

Whether to create default admin user (roles: 'manager-gui', 'manager-script', 'admin-gui' and 'admin-script'). Boolean value. Defaults to false.

admin_user

Admin user name. Defaults to tomcatadmin.

admin_password

Admin user password. Defaults to password.

tomcat_users

Optional hash containing UserDatabase user entries. See tomcat::userdb_entry. Defaults to an empty hash.

tomcat_roles

Optional hash containing UserDatabase role entries. See tomcat::userdb_role_entry. Defaults to an empty hash.

Server configuration

server_control_port

Server control port. Defaults to 8005 (global) / 8006 (instance). The Server can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• server_shutdown: command string that must be received in order to shut down Tomcat. Defaults to SHUTDOWN.
• server_address: address on which this server waits for a shutdown command
• server_params: optional hash of additional attributes/values to put in the Server element

jrememleak_attrs

Optional hash of attributes for the JRE Memory Leak Prevention Listener. Defaults to an empty hash.

versionlogger_listener

Whether to enable the Version Logging Lifecycle Listener. The Listener can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• versionlogger_logargs: log command line arguments
• versionlogger_logenv: log current environment variables
• versionlogger_logprops: log current Java system properties

apr_listener

Whether to enable the APR Lifecycle Listener. The Listener can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• apr_sslengine: name of the SSLEngine to use with the APR Lifecycle Listener

jmx_listener

Whether to enable the JMX Remote Lifecycle Listener. The listener can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• jmx_registry_port: JMX/RMI registry port for the JMX Remote Lifecycle Listener. Defaults to 8050 (global) / 8052 (instance).
• jmx_server_port: JMX/RMI server port for the JMX Remote Lifecycle Listener. Defaults to 8051 (global) / 8053 (instance).
• jmx_bind_address: JMX/RMI server interface address for the JMX Remote Lifecycle Listener
• jmx_uselocalports: force usage of local ports to connect to the the JMX/RMI server

listeners

An array of custom Listener entries to be added to the Server block. Each entry is to be supplied as a hash of attributes/values for the Listener XML node. See Listeners for the list of possible attributes.

svc_name

Name of the default Service. Defaults to Catalina. The Service can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• svc_params: optional hash of additional attributes/values to put in the Service element

threadpool_executor

Whether to enable the default Executor (thread pool). Boolean value. Defaults to false. The Executor can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• threadpool_name: a unique reference name. Defaults to tomcatThreadPool.
• threadpool_nameprefix: name prefix for each thread created by the executor
• threadpool_maxthreads: max number of active threads in this pool
• threadpool_minsparethreads: minimum number of threads always kept alive
• threadpool_params: optional hash of additional attributes/values to put in the Executor

executors

An array of custom Executor entries to be added to the Service block. Each entry is to be supplied as a hash of attributes/values for the Executor XML node. See Executor for the list of possible attributes.

http_connector

Whether to enable the HTTP connector. Boolean value. Defaults to true. The Connector can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• http_port: HTTP connector port. Defaults to 8080 (global) / 8081 (instance).
• http_protocol: protocol to use
• http_use_threadpool: whether to use the default Executor within the HTTP connector. Defaults to false.
• http_connectiontimeout: timeout for a connection
• http_uriencoding: encoding to use for URI
• http_compression: whether to use compression. Defaults to false.
• http_maxthreads: maximum number of executor threads
• http_params: optional hash of additional attributes/values to put in the HTTP connector

ssl_connector

Whether to enable the SSL-enabled HTTP connector. Boolean value. Defaults to false. The Connector can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• ssl_port: SSL connector port. Defaults to 8443 (global) / 8444 (instance). The HTTP connector's redirect port will also be set to this value.
• ssl_protocol: protocol to use
• ssl_use_threadpool: whether to use the default Executor within the HTTPS connector
• ssl_connectiontimeout: timeout for a connection
• ssl_uriencoding: encoding to use for URI
• ssl_compression: whether to use compression. Defaults to false.
• ssl_maxthreads: maximum number of executor threads
• ssl_clientauth: whether to require a valid certificate chain from the client
• ssl_sslenabledprotocols: SSL protocol(s) to use (explicitly by version)
• ssl_sslprotocol: SSL protocol(s) to use (a single value may enable multiple protocols and versions)
• ssl_keystorefile: path to keystore file
• ssl_params: optional hash of additional attributes/values to put in the HTTPS connector

ajp_connector

Whether to enable the AJP connector. Boolean value. Defaults to true. The Connector can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• ajp_port: AJP connector port. Defaults to 8009 (global) / 8010 (instance).
• ajp_protocol: protocol to use. Defaults to AJP/1.3.
• ajp_use_threadpool: whether to use the default Executor within the AJP connector. Defaults to false.
• ajp_connectiontimeout: timeout for a connection
• ajp_uriencoding: encoding to use for URI
• ajp_maxthreads: maximum number of executor threads
• ajp_params: optional hash of additional attributes/values to put in the AJP connector

connectors

An array of custom Connector entries to be added to the Service block. Each entry is to be supplied as a hash of attributes/values for the Connector XML node. See HTTP/AJP for the list of possible attributes.
Additionally, the following attributes are treated differently and used to configure nested elements:

• upgradeprotocol: HTTP Upgrade Protocol element. Hash parameter
• sslhostconfigs: SSLHostConfig element(s). Array of Hashs parameter
  • certificates: Certificate element(s). Array of Hashs parameter

engine_name

Name of the default Engine. Defaults to Catalina. The Engine can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• engine_defaulthost: default host name. Defaults to ${host_name}.
• engine_jvmroute: identifier which must be used in load balancing scenarios to enable session affinity
• engine_params: optional hash of additional attributes/values to put in the Engine container

combined_realm

Whether to enable the Combined Realm. Boolean value. Defaults to false.

lockout_realm

Whether to enable the LockOut Realm. Boolean value. Defaults to true.

userdatabase_realm

Whether to enable the UserDatabase Realm. Boolean value. Defaults to true. The User Database Realm is inserted within the Lock Out Realm if it is enabled.

realms

An array of custom Realm entries to be added to the Engine container. Each entry is to be supplied as a hash of attributes/values for the Realm XML node. See Realm for the list of possible attributes.
Additionally, the following attributes are treated differently and used to configure nested elements:

• credentialhandler: CredentialHandler Component. Hash parameter

host_name

Name of the default Host. Defaults to localhost. The Host can be further configured via a series of parameters (will use Tomcat's defaults when not specified):

• host_appbase: Application Base directory for this virtual host
• host_autodeploy: whether Tomcat should check periodically for new or updated web applications while Tomcat is running
• host_deployonstartup: whether web applications from this host should be automatically deployed when Tomcat starts
• host_undeployoldversions: whether to clean unused versions of web applications deployed using parallel deployment
• host_unpackwars: whether to unpack web application archive (WAR) files
• host_params: optional hash of additional attributes/values to put in the Host container

hosts

An array of Host entries. Use this if you need more complex setup. You can nest valves and contexts with their parameters. See Host for the list of possible attributes.

contexts

An array of custom Context entries to be added to the Host container. Each entry is to be supplied as a hash of attributes/values for the Context XML node. See Context for the list of possible attributes.

singlesignon_valve

Whether to enable the Single Sign On Valve. Boolean value. Defaults to false.

accesslog_valve

Whether to enable the Access Log Valve. Boolean value. Defaults to true.

accesslog_valve_pattern

Pattern to use for the Access Log Valve.

valves

An array of custom Valve entries to be added to the Host container. Each entry is to be supplied as a hash of attributes/values for the Valve XML node. See Valve for the list of possible attributes.

engine_valves

An array of custom Valve entries to be added to the Engine container. Each entry is to be supplied as a hash of attributes/values for the Valve XML node. See Valve for the list of possible attributes.

globalnaming_environments

An array of Environment entries to be added to the GlobalNamingResources component. Each entry is to be supplied as a hash of attributes/values for the Environment XML node. See Global Resources for the list of possible attributes.

globalnaming_resources

An array of Resource entries to be added to the GlobalNamingResources component. Each entry is to be supplied as a hash of attributes/values for the Resource XML node. See Global Resources for the list of possible attributes.

Context configuration

context_params, context_cookieprocessor, context_loader, context_manager, context_realm, context_resources, context_watchedresource, context_parameters, context_environments, context_listeners, context_valves, context_resourcedefs, context_resourcelinks

See tomcat::context defined type.

Servlets configuration

default_servlet_*

initParameters for the default servlet. Generate a single hash for the ${default_servlet_params} parameter of the tomcat::web defined type (will use Tomcat's defaults when not specified)

• default_servlet_debug: debugging level. Defaults to 0.
• default_servlet_listings: whether directory listing is shown if no welcome file is present. Defaults to false.
• default_servlet_gzip: whether to serve gzipped files if the user agent supports gzip
• default_servlet_input: input buffer size in bytes when reading resources to be served
• default_servlet_output: output buffer size in bytes when writing resources to be served
• default_servlet_readonly: whether to reject PUT and DELETE commands (http)
• default_servlet_fileencoding: file encoding used for reading static resources
• default_servlet_showserverinfo: whether to present server information in response sent to clients
• default_servlet_params: optional hash of additional attributes/values to configure the default servlet

jsp_servlet_*

initParameters for the jsp servlet. Generate a single hash for the ${jsp_servlet_params} parameter of the tomcat::web defined type (will use Tomcat's defaults when not specified)

• jsp_servlet_checkinterval: time in seconds between checks to see if a JSP page needs to be recompiled
• jsp_servlet_development: whether to use Jasper in development mode
• jsp_servlet_enablepooling: whether to enable tag handler pooling
• jsp_servlet_fork: whether to perform JSP page compiles in a separate JVM from Tomcat. Defaults to false.
• jsp_servlet_genstringaschararray: whether to generate text strings as char arrays
• jsp_servlet_javaencoding: Java file encoding to use for generating java source files
• jsp_servlet_modificationtestinterval: interval in seconds to check a JSP for modification
• jsp_servlet_trimspaces: whether to trim white spaces in template text between actions or directives
• jsp_servlet_xpoweredby: whether X-Powered-By response header is added by servlet. Defaults to false.
• jsp_servlet_params: optional hash of additional attributes/values to configure the jsp servlet

default_servletmapping_urlpatterns, jsp_servletmapping_urlpatterns, sessionconfig_sessiontimeout, sessionconfig_trackingmode, welcome_file_list, security_constraints

See tomcat::web defined type.

Global configuration file / environment variables

config_path

Absolute path to the environment configuration (setenv). Default depends on the platform.

See catalina.sh for a description of the following environment variables.

catalina_home

$CATALINA_HOME. Default depends on the platform.

catalina_base

$CATALINA_BASE. Default depends on the platform.

jasper_home

$JASPER_HOME. Defaults to catalina_home.

catalina_tmpdir

$CATALINA_TMPDIR. Defaults to ${catalina_base}/temp.

catalina_pid

$CATALINA_PID. Defaults to: /var/run/${service_name}.pid.

catalina_opts

$CATALINA_OPTS. Array. Defaults to [].

java_home

$JAVA_HOME. Defaults to undef (use Tomcat default).

java_opts

$JAVA_OPTS. Array. Defaults to ['-server'].

jpda_enable

Enable JPDA debugger. Boolean value. Effective only if installed from archive. Defaults to false.

jpda_transport

$JPDA_TRANSPORT. Defaults to undef (use Tomcat default).

jpda_address

$JPDA_ADDRESS. Defaults to undef (use Tomcat default).

jpda_suspend

$JPDA_SUSPEND. Defaults to undef (use Tomcat default).

jpda_opts

$JPDA_OPTS. Array. Defaults to [].

security_manager

Whether to enable the Security Manager. Boolean value. Defaults to false.

lang

Tomcat locale. Defaults to undef (use Tomcat default).

shutdown_wait

How long to wait for a graceful shutdown before killing the process. Value in seconds. Only available on RedHat 6 systems if installed from package. Defaults to 30.

shutdown_verbose

Whether to display start/shutdown messages. Boolean value. Only available on RedHat 6 systems if installed from package. Defaults to false.

custom_variables

Hash of custom environment variables.

Logging

log_path

Absolute path to the log directory. Defaults to /var/log/${service_name}.

log_folder_mode

Mode for log folder, in case of archive install. Defaults to '0660'.

Define: tomcat::userdb_entry

Create Tomcat UserDatabase user entries. For creating a tomcat::userdb_entry using Hiera, see parameter tomcat_users.

Parameters within tomcat::userdb_entry:

database

Which database file the entry should be added to. main UserDatabase (global) / instance ${title} UserDatabase (instance)

username

User name (string). Namevar.

password

User password (string)

roles

User roles (array)

Define: tomcat::userdb_role_entry

Create Tomcat UserDatabase role entries. For creating a tomcat::userdb_role_entry using Hiera, see parameter tomcat_roles.

Parameters within tomcat::userdb_role_entry:

database

Which database file the entry should be added to. main UserDatabase (global) / instance ${title} UserDatabase (instance)

rolename

Role name (string). Namevar.

Define: tomcat::context

Create Tomcat context files

Parameters within tomcat::context:

path

Absolute path indicating where the context file should be created. Mandatory. Does not create parent directories.

owner

File owner. Defaults to ${tomcat_user}.

group

File group. Defaults to ${tomcat_group}.

file_mode

File mode. Defaults to ${file_mode}.

params

A hash of attributes/values for the Context container. See Context for the list of possible attributes.

cookieprocessor

A hash of attributes/values for the CookieProcessor nested component. See CookieProcessor for the list of possible attributes.

loader

A hash of attributes/values for the Loader nested component. See Loader for the list of possible attributes.

manager

A hash of attributes/values for the Manager nested component. See Manager for the list of possible attributes.

realm

A hash of attributes/values for the Realm nested component. See Realm for the list of possible attributes.
Additionally, the following attributes are treated differently and used to configure nested elements:

• credentialhandler: CredentialHandler Component. Hash parameter

resources

A hash of attributes/values for the Resources nested component. See Resources for the list of possible attributes.

watchedresource

An array of WatchedResource entries to be added to the Context container. Each entry is to be supplied as a string. Defaults to ['WEB-INF/web.xml','${catalina.base}/conf/web.xml'].

parameters

An array of Parameter entries to be added to the Context container. Each entry is to be supplied as a hash of attributes/values for the Parameter XML node. See Context Parameters for the list of possible attributes.

environments

An array of Environment entries to be added to the Context container. Each entry is to be supplied as a hash of attributes/values for the Environment XML node. See Environment Entries for the list of possible attributes.

listeners

An array of Listener entries to be added to the Context container. Each entry is to be supplied as a hash of attributes/values for the Listener XML node. See Lifecycle Listeners for the list of possible attributes.

valves

An array of Valve entries to be added to the Context container. Each entry is to be supplied as a hash of attributes/values for the Valve XML node. See Valve for the list of possible attributes.

resourcedefs

An array of Resource entries to be added to the Context container. Each entry is to be supplied as a hash of attributes/values for the Resource XML node. See Resource Definitions for the list of possible attributes.

resourcelinks

An array of ResourceLink entries to be added to the Context container. Each entry is to be supplied as a hash of attributes/values for the ResourceLink XML node. See Resource Links for the list of possible attributes.

Define: tomcat::web

Create Tomcat web.xml files

Parameters within tomcat::web:

path

Absolute path indicating where the web.xml file should be created. Mandatory. Does not create parent directories.

owner

File owner. Defaults to ${tomcat_user}.

group

File group. Defaults to ${tomcat_group}.

file_mode

File mode. Defaults to ${file_mode}.

default_servlet_params

A hash of properties/values for the default servlet. See Default Servlet for the list of possible initParameters.

jsp_servlet_params

A hash of properties/values for the jsp servlet. See Jasper 2 JSP Engine for the list of possible initParameters.

default_servletmapping_urlpatterns

List of request URI mapped to the default servlet. Defaults to ['/'].

jsp_servletmapping_urlpatterns

List of request URI mapped to the jsp servlet. Defaults to ['*.jsp', '*.jspx'].

sessionconfig_sessiontimeout

Default session timeout for applications, in minutes. Defaults to 30. See SessionConfig for details about session configuration.

sessionconfig_trackingmode

Default session tracking mode for applications. See Enum SessionTrackingMode for a list of possible values, and ServletContext.getEffectiveSessionTrackingModes() for a description of the default behaviour.

welcome_file_list

List of file names to look up and serve when a request URI refers to a directory. Defaults to ['index.html', 'index.htm', 'index.jsp' ].

security_constraints

List of nested Hashs describing global Security Constraints. The following keys accept an Array value:

• role-name (child of auth-constraint)
• url-pattern (child of web-resource-collection)
• http-method (child of web-resource-collection)

Testing

The only prerequisite is to have the Bundler gem installed:

$ gem install bundler

Install gem dependencies using Bundler (related documentation page here):

$ bundle install

When your environment is set up, run the spec tests inside the module directory using:

$ bundle exec rake spec

Check the puppetlabs_spec_helper GitHub repository for more information.

Contributors

• ETL
• Jason Hane
• Josh Baird
• Frank Holtz
• Vincent Kramar
• Joshua Roys
• Martin Zehetmayer
• Rurik Ylä-Onnenvuori
• Hal Deadman
• Hervé Martin
• Alessandro Franceschi
• Daryl Piffre
• ronnbcnews

Features request and contributions are always welcome!

1.9.0

• Add support for nested Host elements, controlled via the hosts parameter (HerveMARTIN)
• New parameters:
  • tomcat_user_id (HerveMARTIN)
  • tomcat_group_id (HerveMARTIN)
  • context_cookieprocessor (HerveMARTIN)
  • archive_mirror (azryelryvel)
• Fix usage of 'user-data-constraint' key in security_constraints hash (ronnbcnews)

1.8.4

• Fix admin contexts resources ordering (alvagante)
• Update default package versions

1.8.3

• Add configuration of
  • nested Host contexts (contexts parameter) (HerveMARTIN)
  • global security constraints (security_constraints parameter)
• Update default package versions
• Add support for SuSE 12.3

1.8.2

• New parameters log_folder_mode and accesslog_valve_pattern (HerveMARTIN)
• Add support for Debian 9, OpenSuSE 42.3
• Drop support for Ubuntu 12.04, 12.10, 13.04, 13.10, Fedora 23, 24
• Update default package versions

1.8.1

Hotfix: remove references to tomcat-juli extra libraries

1.8.0

• Drop support for internal logging with log4j
  • Removed in Tomcat 8.5
• Update default package versions

1.7.0

• Add support for Tomcat 9
  • Configurable nested UpgradeProtocol, SSLHostConfig and Certificate elements (Connector)
  • Configurable nested CredentialHandler element (Realm)
  • Refer to the configuration examples for further usage instructions
• Make the VersionLogger Listener attributes configurable via versionlogger_* parameters
• Make the JreMemoryLeakPrevention Listener attributes configurable via jrememleak_attrs parameter
• New parameter jmx_uselocalports for the JMX Listener
• Warning: the path to Tomcat archives is now composed of both archive_source and archive_filename (new) parameters
• Fix ignored listeners parameter

1.6.2

• Add proxy support via new parameters proxy_server and proxy_type
• New parameter force_init which generates a generic init script/unit for packages which do not include any
• Add support for SuSE 12.1
• Update default package versions

1.6.1

• Unset provider parameter on all archive resources (from puppet-archive module)
  • quick and dirty workaround until SERVER-94 gets fixed
  • Warning: may break behind a HTTP proxy (untested)

1.6.0

• Configurable web.xml files
  • Warning: replaces default_servlet instance parameter
  • New tomcat::web defined type to manage web.xml files
  • See default_servlet*, jsp_servlet*, sessionconfig_sessiontimeout and welcome_file_list parameters
• Update systemd unit, expect tomcat script path as set in latest available packages
  • Warning: check the current location of your tomcat startup script, especially if using an old OS package version
• Replace or remove calls to deprecated validate_* stdlib functions
• Add support for Fedora 25 and Amazon Linux 2016.09
• Drop support for Fedora 22

1.5.0

Warning: the host_deployOnStartup parameter was renamed to host_deployonstartup (lowercase) in this release. Backward compatibility will be maintained until the next minor release only.

• New tomcat::userdb_role_entry defined type to manage roles in the user database (hdeadman)
• New tomcat_users and tomcat_roles hash parameters to help the definition of users and roles (hdeadman)
• Add support for Engine scoped valves: engine_valves parameter (hdeadman)
• New parameters restart_on_change and file_mode (ruriky)
• Allow enabling the Security Manager on archive installations (hdeadman)
• Fix default systemd service type on archive installations (hdeadman)
• Improve usage of clustering features (SimpleTcpCluster) (hdeadman)
  • see undocumented cluster_* parameters
• Fix empty user/group in systemd units
• Encode values in XML templates (scitechfh)
• Set default provider to curl for archive resources (scitechfh)
• Add support for Ubuntu 16.10 (Yakkety), OpenSuSE 42.2, SuSE 12.1
• Update default package versions

1.4.0

Warning: the enable_extras parameter was renamed to extras_enable in this release. Backward compatibility will be maintained until the next minor release only.

• New parameters: package_ensure and extras_package_name (scitechfh)
• New parameters: checksum_verify, checksum_type, checksum and extras_source (angrox)
• Replace dependency on puppet/staging by puppet/archive
• Align content of systemd templates on current state of official RPM packages (RedHat and derivatives)
• Add support for Ubuntu 16.04 (Xenial), Fedora 24 and Amazon Linux 2016.03
• Drop support for Debian 6 (Squeeze), OpenSuSE 13.1 and below, Fedora 21 and below
• Update default package versions
• Bug fixes:
  • parameters left blank in systemd units on some Puppet versions
  • work around for PUP-1597 on RHEL 7
  • dependency cycle between service and context resources
  • file permissions too strict on configuration files
  • activation of extras/log4j not working with multi-version setups
  • tomcat service not notified of all relevant changes

1.3.2

• New parameters: globalnaming_environments and ssl_sslenabledprotocols (roysjosh)
• Support Amazon Linux 2015.x (thkrmr)
• Update default package versions (Fedora 23)

1.3.1

• New systemd_service_type parameter (joshuabaird)
• Reload systemd daemon after unit update (scitechfh)
• Update deprecated port firewall parameter (scitechfh)
• Support Fedora 23

1.3.0

• Support per-instance user
• New tomcat::instance parameter: default_servlet
• Fix default owner/group on context.xml
• Contain sub-classes
• Update default package versions (Debian 6/7)
• Support Ubuntu 15.10

1.2.1

• Fix obsolete start/stop commands and systemd unit on RHEL7
• Support Epoch tag in package version
• Move information about tomcat user/group to the right place in the documentation
• Update default package versions (RHEL6/7)

1.2.0

Enforce tomcat package version. version now takes a full package version when tomcat is installed from a package repository.

1.1.0

New tomcat::context defined type to manage context.xml files

1.0.3

Fix regression due to changes in pid file management

1.0.2

• Add missing ensure attributes (hanej)
• Do not force pid file creation (fixes startup issue with Tomcat 6)

1.0.1

Fix documentation format and add Context config example

1.0.0

• New Context parameters for configuring context.xml:
  • context_params
  • context_loader
  • context_manager
  • context_realm
  • context_resources
  • context_parameters
  • context_environments
  • context_listeners
  • context_valves
  • context_resourcedefs
  • context_resourcelinks
• Support Debian 8, Fedora 22 and RHEL 5
• Do not create user/group if already defined
• Minor bugfixes

0.9.3

• Allow several instances to use the same log_path
• Parameters validation
• Partial spec tests

0.9.2

• Enable multi-version tomcat installation
• New parameter log_path: define log directory
• Fix issue with generic init script always returning 0

0.9.1

Fix compatibility with future parser in Puppet 3.7.4 (PUP-3615)

0.9.0

Warning: this release is a big step forward, please read the documentation carefully

• New listeners parameters: create custom Listener components within the server configuration
• New Server parameters. Warning: control_port renamed to server_control_port
  • server_control_port
  • server_shutdown
  • server_address
• New Service parameters.
  • svc_name
  • svc_params
• New Engine parameters. Warning: jvmroute renamed to engine_jvmroute
  • engine_name
  • engine_defaulthost
  • engine_jvmroute
  • engine_params
• New Host parameters. Warning: all old parameters renamed and default values removed!
  • host_name
  • host_appbase
  • host_autodeploy
  • host_deployOnStartup
  • host_undeployoldversions
  • host_unpackwars
  • host_params
• Fix instance startup on Fedora 20+, drop support for Fedora 15 and 16
• custom_fragment renamed to custom_variables (hash)
• Refactoring

0.8.2

• New parameters related to Executors
  • threadpool_name
  • threadpool_nameprefix
  • threadpool_maxthreads
  • threadpool_minsparethreads
  • threadpool_params
  • executors

0.8.1

• Fix Critical messages generated when concaneting empty fragments to server.xml
• New parameter valves: create custom Valve components within the server configuration
• Change default value for catalina_pid (instance context) and manage pid file
• Improve template formatting

0.8.0

• Numerous new Connector parameters (see documentation, thanks etlweather for the help)
• Split bulky server.xml template into independant fragments
• New context_resources parameter: add ResourceLink elements to context.xml (etlweather)
• Added basic support for SimpleTcpCluster (etlweather, experimental and undocumented, need contributions)
• Updated documentation

0.7.0

• New realm parameters: $lockout_realm, $userdatabase_realm (etlweather)
• New globalnaming_resources and realms parameters: possibility to define custom GlobalNamingResources and Realm elements (etlweather)
• Changed root_path default value (instance context)
• Proper startup script for distributions without systemd
• Better support of SuSE OS family
• Fix tomcat6 startup script on RHEL (warning: now requires stdlib >= 4.4.0)

0.6.0

• Compatible with future parser
• Minor code improvements

0.5.4

Fix compatibility issue with Puppet versions between 3.4 and 3.6

0.5.3

Removed root_path parameter from main class (redundant with catalina_home)

0.5.2

• installation_support renamed to install_from
• New debugging parameters: jpda_enable, jpda_transport, jpda_address, jpda_suspend and jpda_opts

0.5.1

• tomcat_user defaults to service_name if installed from package
• Log name in Access Log valve now matches hostname
• Fixed log folder permissions

0.5.0

• Support SuSE OS family
• Configures instance admin webapps properly when installed from archive
• Does not uninstall unrequired libraries anymore (native, log4j)
• Improve warning logging
• Cleanup

0.4.1

• Document missing parameter installation_support
• Improve documentation

0.4.0

• Support installation from archive
• Use nanliu/staging instead of nanliu/archive to download and extract files
• Improved systemd support
• create_default_admin defaults to false
• Numerous improvements in code and documentation

0.3.2

New parameter manage_firewall

0.3.1

• java_opts and catalina_opts are now array parameters
• Path to "setenv" file can be set using config_path
• extras renamed to enable_extras
• tomcat_native and log4j default to false

0.3.0

Warning: this release is a big step forward, please read the documentation carefully

• New type tomcat::instance, allows creation of individual instances
• Old log4j parameter now split between log4j (package) and log4j_enable (conf)
• New parameters apr_listener, apr_sslengine
• Removed parameters logfile_days and logfile_compress
• Reorganized files and templates
• Fixed broken init script (service status check)
• Use nanliu/archive module to download extra libraries

0.2.1

• New parameters logfile_days and logfile_compress
• Added log rotation
• catalina_base defaults to catalina_home on RedHat (inverted the logic)
• merged Debian and RedHat main configuration files

0.2.0

• New parameter jmx_bind_address
• catalina_home now defaults to catalina_base on RedHat
• Removed defaulthost parameter
• Minor improvements in code quality, documentation and metadata

0.1.0

• Support Debian/Ubuntu
• Renamed enable_manager parameter to admin_webapps
• New parameters admin_webapps_package_name and log4j_package_name

0.0.4

Stop managing tomcat user, RPMs already take care of it

0.0.3

• The package name for Tomcat native library can now be set
• Notify tomcat service when a package resource is modified

0.0.2

Fixed a bug with 'extras' libraries get path

0.0.1

First forge release