tomcat

Overview

The tomcat module allows you to set up and manage a standalone or multiple instances.

Module Description

Compatibility

This module is currently aimed at the RHEL and Debian packaged versions of Tomcat versions 6 and 7.

It has only been tested on CentOS 6/7 and Debian 6/7/8 with the base OS tomcat 6 and tomcat 7 (EPEL for RHEL) packages.

Requirements

Puppet 3.x
puppetlabs/stdlib >= 3.2.1
puppetlabs/concat >= 1.0.1

Setup

Beginning with Tomcat

All tomcat packages will be installed and tomcat is configured as standalone server. The OS specific file and directory structure is used, i.e. /etc/tomcat6/server.xml. Hash config could contain the hole configuration or just a part of it. For defaults take a look to manifests/params.pp, defaults hash.

class { 'tomcat': }

To install tomcat 7 standalone with an AJP connector instead of HTTP use the following:

class { 'tomcat':
  version  => '7',
  services => {
    Catalina => {
      connectors => {
        ajp-8009 => {
          port     => '8009',
          protocol => 'AJP/1.3',
        },
      },
    },
  }, # services
}

Or use this yaml file in your hiera datastore:

tomcat::version: '7'
tomcat::services:
  Catalina:
    connectors:
      ajp-8009:
        port: '8009'
        protocol: 'AJP/1.3'

Configure a virtual host

Setup a new virtual host instead the default host 'localhost', using a JRE 6.

tomcat::java_home: '/etc/alternatives/jre_1.6.0'
tomcat::services:
  Catalina
    engine:
      Catalina:
        default_host: 'www.example.com'
        hosts:
          www.example.com:
            app_base: 'webapps'
            unpack_wars: true
            auto_deploy: true
            xml_validation: false
            xml_namespace_aware: false

Configure and manage another virtual host. First part of the title is the servername, tomcat6 or tomcat7 for standalone server. The second part is the service, the third the engine there the virtual host 'www.example.com' belongs to.

tomcat::host { 'tomcat6:Catalina:Catalina:www.example.com': app_base => 'webapps', unpack_wars => true, auto_deploy => true, xml_validation => false, xml_namespace_aware => false, }

Configure multiple instances

For using tomcat as multi instance server, set ensure to 'stopped' and enable to 'false'. That will shutdown and disable the the standalone server.

class { 'tomcat':
   ensure => stopped,
   enable => false,
}

Installs base OS tomcat version 6 packages in specified version 6.0.24-72.el6_5. All configuration files and webapps for instances of tomcat will be stored under /var/tomcat in a subdirectory named as the tomcat::server title.

class { 'tomcat':
   ensure  => stopped,
   enable  => false,
   version => '6',
   release => '6.0.24-72.el6_5',
   basedir => '/var/tomcat',
}

Setup a new instance of tomcat, using a Java Runtime Environment 1.6.0 and management port 8005. Base directory for this instance is $basdir/myapp1, $basedir (default /var/tomcat) set in tomcat class.

tomcat::server { 'myapp1':
   ensure   => 'running',
   enable   => false,
   port     => '8005',
   java_home => '/etc/alternatives/jre_1.6.0',
}

Usage

Classes and Defined Types

Class: `tomcat`

Parameters within tomcat:

`ensure`

present or running (present), stopped

`enable`

Enables (true, default) or disables (false) the service to start at boot.

`version`

The version of Apache Tomcat server, supported versions are 6 (default) and 7.

`release`

Valid values are 'latest', 'installed' or an exact release version, i.e. '6.0.24-64.el6_5'.

`port`

Management port (default 8005) on localhost.

`listeners`

Hash of listeners in the global server section (server.xml).

`resources`

Hash of global resources in the server section (server.xml).

`services`

Hash of services and their attributes.

`manage`

Enables (default) the configuration by this module. Disable means, that you have to manage the configuration in server.xml outside and notify the service.

`setenv`

Handles environment variables in sysconfig file.

`basedir`

Base directory where to install server instances and their configurations. Directory 'basedir' has to exist. Ignored for multi instance setup (config => false).

Defined Type: `tomcat::server`

Notice: parameters you set in declaration of class tomcat acts as defaults for tomcat::server.

Parameters within tomcat::server:

`ensure`

Valid values are present or running (present), stopped.

`enabled`

Enables (true, default) or disables (false) the service to start at boot.

`user`

user context for running of this instance.

`group`

same for group

class { 'tomcat':
   ensure  => stopped,
   enable  => false,
   version => 6,
}

tomcat::server { 'myapp1': }

group { 'myapp2':
   ensure => present,
}

user { 'myapp2':
   ensure => present,
   gid    => 'myapp2',
   shell  => '/sbin/nologin',
   home   => '/var/tomcat/myapp1',
} ->

tomcat::server { 'myapp2':
   user     => 'myapp2',
   group    => 'myapp2',
   port     => '8006',
   services => {
      'Catalina' => {
         connectors => {
            'ajp-8009' => {
               port => '8009',
               protocol => 'AJP/1.3',
               redirect_port => '8443',
            },
         },
      },
   },
}

`port`

Management port (default 8005) on localhost for this instance.

`listeners`

Hash of listeners in the global server section (server.xml). Default, for Tomcat 6

'listeners' => {
  'org.apache.catalina.core.AprLifecycleListener' => { 'ssl_engine' => 'On', },
  'org.apache.catalina.core.JasperListener' => {},
  'org.apache.catalina.core.JreMemoryLeakPreventionListener' => {},
  'org.apache.catalina.mbeans.GlobalResourcesLifecycleListener' => {},
  'org.apache.catalina.mbeans.ServerLifecycleListener' => {},
},

rather for Tomcat 7

'listeners' => {
  'org.apache.catalina.core.AprLifecycleListener' => { 'ssl_engine' => 'On', },
  'org.apache.catalina.core.JasperListener' => {},
  'org.apache.catalina.core.JreMemoryLeakPreventionListener' => {},
  'org.apache.catalina.mbeans.GlobalResourcesLifecycleListener' => {},
  'org.apache.catalina.core.ThreadLocalLeakPreventionListener' => {},
},

`resources`

Hash of global resources in the server section (server.xml), default sets to:

resources => {
  'UserDatabase' => {
    'auth'        => 'Container',
    'type'        => 'org.apache.catalina.UserDatabase',
    'extra_attrs' => {
    'description' => 'User database that can be updated and saved',
    'factory'     => 'org.apache.catalina.users.MemoryUserDatabaseFactory',
    'pathname'    => 'conf/tomcat-users.xml',
  },
},

`services`

Hash of services and their attributes.

`java_home`

Directory where to find the java binary in subdirectory bin.

`manage`

Enables (default) the configuration of server.xml by this module. Disable means, that you have to manage the configuration outside and start/restart the service.

class { 'tomcat':
   ensure  => stopped,
   enable  => false,
   version => '6',
}

tomcat::server { 'myapp1':
   manage => false,
}

file { '/var/tomcat/myapp1/conf/server.xml':
   ensure => file,
   owner  => 'root',
   group  => 'root',
   mode   => '0644',
   source => 'puppet:///modules/tomcat/example-server.xml',
   notify => Tomcat::Server::Service['myapp1'],
}

Notice notifying Tomcat::Server does not work, you have to do this against Tomcat::Server::Service.

`setenv`

Handles environment variables in 'bin/setenv.sh'.

setenv => [ 'JAVA_XMX="256m"', 'JAVA_XX_MAXPERMSIZE="256m' ]

Variables to use:

DSUN_JAVA2D_OPENGL true|false
DJAVA_AWT_HEADLESS true|false
JAVA_XMX
JAVA_XX_MAXPERMSIZE

Use ADD_JAVA_OPTS for all other environment variables.

setenv => [ 'ADD_JAVA_OPTS="-Xminf0.1 -Xmaxf0.3"' ]

Defined Type: `tomcat::resource`

tomcat::resource { 'myapp1:UserDatabase':
  auth        => 'Container',
  type        => 'org.apache.catalina.UserDatabase',
  extra_attrs => {
    description => 'User database that can be updated and saved',
    factory     => 'org.apache.catalina.users.MemoryUserDatabaseFactory',
    pathname    => 'conf/tomcat-users.xml',
  },
}

Parameters within tomcat::resource:

`server`

Name of tomcat server instance to add a resource, automaticly taken from 'title' then using 'title' like 'server:resource' otherwise undef.

`resource`

Name of the resource, automaticly taken from 'title' then using 'title' like 'server:resource' otherwise undef.

`auth`

authentication, default 'container'

`type`

Take a look at Apache Tomcat documentation.

`extra_attrs`

Hash of extra attributes (key => value) for this resource.

Defined Type: `tomcat::listener`

tomcat::listener { 'myapp1:org.apache.catalina.core.AprLifecycleListener':
  ssl_engine => 'On',
}

Parameters within tomcat::listener:

`server`

Name of tomcat server instance to add the listener, automaticly taken from 'title' then using 'title' like 'server:class_name' otherwise undef.

`class_name`

Listener with class_name 'class_name', automaticly taken from 'title' then using 'title' like 'server:class_name' otherwise undef.

`ssl_engine`

Specify the ssl_engine, default 'undef' (disabled).

Defined Type: `tomcat::service`

tomcat::service { 'myapp1:Catalina':
  connetcors => {},
  engine     => {},
}

Parameters within tomcat::service:

`server`

Name of tomcat server instance to add the service, automaticly taken from 'title' then using 'title' like 'server:service' otherwise undef.

`service`

Service with name 'service', automaticly taken from 'title' then using 'title' like 'server:service' otherwise undef.

`connectors`

Hash of connectors and their attributes. If sets and non equal to empty hash {}, the default is used:

connectors => {
  'http-8080' => {
    port          => '8080',
    protocol      => 'HTTP/1.1',
    redirect_port => '8443',
}

`engine`

Hash of the engine and their attributes.

Defined Type: `tomcat::connector`

tomcat::connector { 'myapp1:Catalina:ajp-8009':
  port          => '8009',
  protocol      => 'AJP/1.3',
  redirect_port => '8443',
}

Parameters within tomcat::connector:

`server`

Name of tomcat server instance to add the connector, automaticly taken from 'title' then using 'title' like 'server:service:connector' otherwise undef.

`service`

Name of tomcat service to add the connector, automaticly taken from 'title' then using 'title' like 'server:service:connector' otherwise undef.

`connector`

Name of the connector, automaticly taken from 'title' then using 'title' like 'server:service:connector' otherwise undef.

`uri_encoding`

accepted encoding

`port`

Listen port, default 8080 (HTTP/1.1)

`address`

Address to bind, default is false that means bind to all interfaces.

`protocol`

Supported protocols are HTTP/1.1 (default) and AJP/1.3.

For these parameters, take a look at the Apache Tomcat documentation:

connection_timeout
redirect_port
options
scheme
executor

Defined Type: `tomcat::engine`

tomcat::engine { 'myapp1:Catalina:Catalina':
  default_host => 'localhost'
  hosts => {},
  realms => {
    'org.apache.catalina.realm.UserDatabaseRealm' => {
      'attrs' => {
        'resource_name' => 'UserDatabase',
      },
    },
  },
}

Parameters within tomcat::engine:

`server`

Name of tomcat server instance to add the connector, automaticly taken from 'title' then using 'title' like 'server:service:engine' otherwise undef.

`service`

Name of tomcat engine to add the service 'service', automaticly taken from 'title' then using 'title' like 'server:service:engine' otherwise undef.

`engine`

Name of the engine, automaticly taken from 'title' then using 'title' like 'server:service:engine' otherwise undef.

`default_host`

Every engine has to have a default host, default 'localhost'.

`hosts`

Hash of hosts defined under this engine.

`realms`

Hash of realms defined under this engine.

Defined Type: `tomcat::realm`

tomcat::realm { 'myapp1:Catalina:Catalina:www.example:': }

tomcat::realm { 'myapp1:Catalina:Catalina:*:': }

Parameters within tomcat::realm:

`server`

Name of tomcat server instance to add the connector, automaticly taken from 'title' then using 'title' like 'server:service:engine:host:realm:class_name' otherwise undef.

`service`

Name of tomcat engine to add the service 'service', automaticly taken from 'title' then using 'title' like 'server:service:engine:host:realm:class_name' otherwise undef.

`engine`

Name of the engine, automaticly taken from 'title' then using 'title' like 'server:service:engine:host:realm:class_name' otherwise undef.

`host`

Name of the host, automaticly taken from 'title' then using 'title' like 'server:service:engine:host:realm:class_name' otherwise undef.

`realm`

Name of the realm, automaticly taken from 'title' then using 'title' like 'server:service:engine:host:realm:class_name' otherwise undef.

`class_name`

Classname used for this realm, automaticly taken from 'title' then using 'title' like 'server:service:engine:host:realm:class_name' otherwise undef.

`attrs`

Hash of attributes defined for this realm.

`realms`

Hash of realms defined under this realm.

Defined Type: `tomcat::host`

tomcat::host { 'myapp1:Catalina:Catalina:www.example.com':
  realms              => {},
  app_base            => 'webapps',
  unpack_wars         => true,
  auto_deploy         => true,
  xml_validation      => false,
  xml_namespace_aware => false,
}

Parameters within tomcat::host:

`server`

Name of tomcat server instance to add the connector, automaticly taken from 'title' then using 'title' like 'server:service:engine:host' otherwise undef.

`service`

Name of tomcat engine to add the service 'service', automaticly taken from 'title' then using 'title' like 'server:service:engine:host' otherwise undef.

`engine`

Name of the engine, automaticly taken from 'title' then using 'title' like 'server:service:engine:host' otherwise undef.

`host`

Name of the host, automaticly taken from 'title' then using 'title' like 'server:service:engine:host' otherwise undef.

`realms`

Hash of realms defined for this host.

For these parameters, take a look at the Apache Tomcat documentation:

app_base
auto_deploy
unpack_wars
xml_validation
xml_namespace_aware

tomcat

Overview

Module Description

Compatibility

Requirements

Setup

Beginning with Tomcat

Configure a virtual host

Configure multiple instances

Usage

Classes and Defined Types

Class: tomcat

ensure

enable

version

release

port

listeners

resources

services

manage

setenv

basedir

Defined Type: tomcat::server

ensure

enabled

user

group

port

listeners

resources

services

java_home

manage

setenv

Defined Type: tomcat::resource

server

resource

auth

type

extra_attrs

Defined Type: tomcat::listener

server

class_name

ssl_engine

Defined Type: tomcat::service

server

service

connectors

engine

Defined Type: tomcat::connector

server

service

connector

uri_encoding

port

address

protocol

Defined Type: tomcat::engine

server

service

engine

default_host

hosts

realms

Defined Type: tomcat::realm

server

service

engine

host

realm

class_name

attrs

realms

Defined Type: tomcat::host

server

service

engine

host

realms

Class: `tomcat`

`ensure`

`enable`

`version`

`release`

`port`

`listeners`

`resources`

`services`

`manage`

`setenv`

`basedir`

Defined Type: `tomcat::server`

`ensure`

`enabled`

`user`

`group`

`port`

`listeners`

`resources`

`services`

`java_home`

`manage`

`setenv`

Defined Type: `tomcat::resource`

`server`

`resource`

`auth`

`type`

`extra_attrs`

Defined Type: `tomcat::listener`

`server`

`class_name`

`ssl_engine`

Defined Type: `tomcat::service`

`server`

`service`

`connectors`

`engine`

Defined Type: `tomcat::connector`

`server`

`service`

`connector`

`uri_encoding`

`port`

`address`

`protocol`

Defined Type: `tomcat::engine`

`server`

`service`

`engine`

`default_host`

`hosts`

`realms`

Defined Type: `tomcat::realm`

`server`

`service`

`engine`

`host`

`realm`

`class_name`

`attrs`

`realms`

Defined Type: `tomcat::host`

`server`

`service`

`engine`

`host`

`realms`