Install and configure Tomcat using official Apache binaries. Multiple instances are supported.
This cookbook does NOT use or depend on OS packages for Tomcat, nor does it expect to play well with them. If using OS packages, use the tomcat cookbook instead.
This cookbook has been tested with the following platforms and service providers. Other combinations of compatible platforms and service providers will likely work with proper tweaking, but have not been tested:
- CentOS (6.6 - sysvinit, 7.0 - systemd)
- Ubuntu (14.04 - upstart)
Required:
- logrotate- used by the
default
recipe to install logrotate - poise-service - used to manage Tomcat service(s) (see below)
Suggested:
java
(see below)
This cookbook does not install Java. You should install Java earlier in your runlist before consuming recipes/resources in this cookbook. For example...
- java community cookbook
- oracle_jdk - a cookbook dedicated to installing the Oracle JDK
This cookbook depends on poise-service
to create and manage Tomcat service(s). On RHEL platforms < 7.0 (and Amazon
Linux), this cookbook defaults to the :sysvinit
provider and includes a suitable
init template instead of using the poise-service default. The poise-service cookbook
allows a considerable amount of flexibility for setting/overriding service behavior,
init scripts, etc. Refer to that cookbook's documentation for implementation
details.
mirror
- Tomcat mirror URLversion
- version of Tomcat to download/installchecksum
- sha256 checksum of downloaded Tomcat tarballhome
- installation path of Tomcat (equiv. to CATALINA_HOME)base
- default CATALINA_BASE path for base instancebase_instance
- name of base instance; default: basename ofbase
run_base_instance
- whether to run an instance inbase
create_service_user
- whether to create service user/group specified inuser
andgroup
attributes
Attributes for Tomcat instance(s):
shutdown_port
- Shutdown port (integer)shutdown_command
- Shutdown command (string); default:SHUTDOWN
http_port
- HTTP port (integer)ssl_port
- SSL port (integer)ajp_port
- AJP port (integer)jmx_port
- JMX port (integer); default:nil
(see "JMX Remote Management" section below)debug_port
- JDWP debug port (integer); default:nil
(debug disabled ifnil
)user
- service user for Tomcat instances; default:tomcat
group
- primary group of service user; default:tomcat
webapps_mode
- optional permissions for webapps directory; default:0775
conf_mode
- optional permissions for conf directory; default:0640
enable_manager
- whether to enable manager webapp by copying fromhome
tobase
; default:false
log_dir
- optional directory for Tomcat logs; must be absolute if specifiedlogrotate_frequency
- rotation frequency; default:weekly
logrotate_count
- logrotate file count; default:4
kill_delay
- seconds to wait before kill -9 on service stop/restart; default: 45 (integer)initial_heap_size
- optional java initial heap size; adds-Xms
to CATALINA_OPTSmax_heap_size
- optional java max heap size; adds-Xmx
to CATALINA_OPTSmax_perm_size
- optional java max permanent size; adds-XX:MaxPermSize
to CATALINA_OPTScatalina_opts
- optional string or array of CATALINA_OPTS in setenv.shjava_opts
- optional string or array of JAVA_OPTS in setenv.shjava_home
- optional JAVA_HOME environment variable in setenv.shsetenv_additional
optional hash of environment vars to export in setenv.shjmx_authenticate
- whether JMX authentication is enabled; default:true
jmx_users
- optional hash of JMX users/access (see "JMX Remote Management" section below for expected format) (ignored unlessjmx_port
set andjmx_authenticate
true)context_entries
- optional array of entries to add tocontext.xml
pool_enabled
- enable shared executor (thread pool); default:false
access_log_enabled
- whether to enable access log valve; default:false
http_additional
- hash of additional http connector attributesajp_additional
- hash of additional ajp connector attributesssl_additional
- hash of addtional ssl connector attributespool_additional
- hash of additional executor (thread pool) attributesaccess_log_additional
- hash of additional access log valve attributesengine_valves
- nested hash of one or more engine valves (see below for format)host_valves
- nested hash of one or more host valvestomcat_users
- optional array of Tomcat-users (see below for expected format)
Additionally, the following attributes allow you override the included templates
with your own. Use name
to reference a template in the calling cookbook or
cookbook:name
to reference a template in another cookbook:
setenv_template
- bin/setenv.shserver_xml_template
- conf/server.xmllogging_properties_template
- conf/logging.propertiestomcat_users_template
- conf/tomcat-users.xmlcontext_template
- conf/context.xmllogrotate_template
- /etc/logrotate.d/service_name
Include the default recipe to install and configure Tomcat.
Tomcat will be installed in home
, and becomes CATALINA_HOME. If run_base_instance
is true
, an instance will be created in base
and becomes CATALINA_BASE. The
instance will be configured using the instance-related node attributes listed
above.
A Tomcat service user/group will also be created if create_service_user
is true
.
To run multiple instances of Tomcat, populate the instances attribute, which is
a dictionary of instance name => array of attributes. Most of the same attributes
that can be used globally for the tomcat cookbook can also be set per-instance -
see resources/instance.rb
for detail.
If the base
attribute is NOT set for a particular instance, it will be derived
from node['apache_tomcat']['base']
. For example, for instance 'instance1' if
node['apache_tomcat']['base']
is /var/lib/tomcat7, then base
for 'instance1'
will be set to /var/lib/tomcat7-instance1.
The port attributes - http_port
, ssl_port
, ajp_port
, jmx_port
, debug_port
,
shutdown_port
- are not inherited from node attributes and must be set per-instance
if they are to be used. Other attributes for an instance that aren't set are
inherited unmodified from global node attributes.
If you only want to run specific instances and not the base instance specified
in node['apache_tomcat']['base']
, set run_base_instance
to false
.
Example of partial role:
...
"override_attributes": {
"apache_tomcat": {
"run_base_instance": false,
"http_additional": {
"protocol": "org.apache.coyote.http11.Http11NioProtocol"
},
"instances": {
"instance1": {
"http_port": 8081,
"shutdown_port": 8006
},
"instance2": {
"http_port": 8082,
"shutdown_port": 8007,
"catalina_opts": [
"-XX:+UseConcMarkSweepGC"
]
}
},
...
}
...
}
Install or remove Tomcat binaries. In typical applications this is used to create a CATALINA_HOME for one or more instances of Tomcat.
install
- Default action. Install Tomcat binaries intopath
remove
- Uninstalls Tomcat binaries frompath
path
- Directory to install Tomcat binaries; default: name of resource blockmirror
,version
,checksum
- see Attributes above; inherits from node attributes if not specified.
Install and/or configure an instance of Tomcat. In typical applications this is
used to create one or more instances of Tomcat (CATALINA_BASE) after installing
Tomcat with the apache_tomcat
LWRP.
create
- Default action. Install and configure Tomcat instance inbase
The following attributes are specific to each instance and are not inherited from node attributes:
instance_name
- name of service; default: name of resource blockbase
- directory to create this Tomcat instance; default: dirname ofnode['apache_tomcat']['base']
+instance_name
shutdown_port
- Shutdown port (integer)http_port
- HTTP port (integer)ssl_port
- SSL port (integer)ajp_port
- AJP port (integer)jmx_port
- JMX port (integer); default:nil
(JMX management is disabled ifnil
)
Additional attributes for this resource are described in Attributes above. If not specified they will be inherited from node attributes. Also see resources/instance.rb for further details.
To define a non-SSL HTTP Connector, set http_port
to a port number. If nil
the
connector will not be created in server.xml. To specify additional attributes
for this connector, specify them using http_additional
. For example:
node['apache_tomcat']['http_port'] = 8080
will generate the following connector using cookbook defaults:
<Connector port="8080"
protocol="HTTP/1.1"
connectionTimeout="20000"
URIEncoding="UTF-8"
/>
To override connector attributes, or to add additional ones, use http_additional
:
node['apache_tomcat']['http_port'] = 8080
node['apache_tomcat']['http_additional']['protocol'] = 'org.apache.coyote.http11.Http11NioProtocol'
node['apache_tomcat']['http_additional']['connectionTimeout'] = '15000'
node['apache_tomcat']['http_additional']['address'] = '10.0.0.5'
creates the following connector:
<!-- Define a non-SSL HTTP Connector on port 8080 -->
<Connector port="8080"
protocol="org.apache.coyote.http11.Http11NioProtocol"
connectionTimeout="15000"
URIEncoding="UTF-8"
address="10.0.0.5"
/>
Of course if desired it can also be specified with a raw hash:
node['apache_tomcat']['http_additional'] = {
'protocol' => 'org.apache.coyote.http11.Http11NioProtocol',
'connectionTimeout' => '15000',
'address' => '10.0.0.5'
}
An SSL connector can be specified in much the same way as the HTTP connector
examples shown above, using ssl_port
and ssl_additional
. If only ssl_port
is specified, the default settings for the connector are:
<!-- Define an SSL Connector on port xxxx -->
<Connector port="xxxx"
protocol="HTTP/1.1"
connectionTimeout="20000"
URIEncoding="UTF-8"
SSLEnabled="true"
scheme="https"
secure="true"
sslProtocol="TLS"
clientAuth="false"
/>
If desired these can be overridden with ssl_additional
.
NOTE: If the ssl connector is enabled, it will by default add the redirectPort
attribute to the http connector (and the ajp connector if enabled) with the value
set to the ssl_port
(override with ssl_additional
).
TODO
TODO
Example:
node.default['apache_tomcat']['engine_valves']['org.apache.catalina.valves.RemoteIpValve']['internalProxies'] = '127\.0\.0\.1'
node.default['apache_tomcat']['engine_valves']['org.apache.catalina.valves.RemoteIpValve']['protocolHeader'] = 'x-forwarded-proto'
node.default['apache_tomcat']['engine_valves']['org.apache.catalina.valves.RemoteIpValve']['portHeader'] = 'x-forwarded-port'
Will render the following engine valve in server.xml
<Valve className="org.apache.catalina.valves.RemoteIpValve"
internalProxies="127\.0\.0\.1"
protocolHeader="x-forwarded-proto"
portHeader="x-forwarded-port"
/>
The conf/context.xml
file can be customized with the context_entries
attribute.
You can also choose a different template for context.xml with the
context_template
attribute.
The context_entries
attribute accepts an array of strings, each string being a
valid XML fragment:
[
'<Transaction factory="myTransFactory" />',
'<Resource name="my/Resource" type="bacon" description="Something"/>'
]
The tomcat_users
attribute accepts an array of user hashes like so:
[
{
'id' => 'frank',
'password' => 'bacon',
'roles' => ['admin']
},
{
'id' => 'bob',
'password' => 'eggs',
'roles' => ['admin', 'foo']
}
]
While it's possible to set node['apache_tomcat']['tomcat_users']
node attribute
for use with the default
or configure
recipes, it's probably not a good idea.
The attribute is more suited for apache_tomcat_instance
LWRP consumers...
setting the LWRP attribute from a data bag or some other means in a wrapper cookbook.
Support for setting tomcat_users from a data bag (or run_state) for use with
the default recipe may be considered in the future.
JMX remote management settings will be enabled in setenv.sh
if the jmx_port
attribute is set. Furthermore, the jmx_authenticate
boolean attribute will
enable/disable JMX authentication, and jmx_users
will control access by
creating jmxremote access and password files. The jmx_users
settings will be
ignored unless jmx_authenticate
is true
.
The jmx_users
attributes accepts a nested hash of users like the example below.
Each user should include password
and access
. Access must be one of
readonly
or readwrite
. If access
any other value besides readonly
or readwrite
, the user will be removed.
{
'monitorMe' => {
'password' => 'bacon',
'access' => 'readonly'
},
'controlMe' => {
'password' => 'supersecret',
'access' => 'readwrite'
},
# this user will not be present
'some_user' => {
'password' => 'notRelevant',
'access' => 'disabled' # could be anything other than readonly or readwrite
},
}
- Author:: Brian Clark ([email protected])
Copyright 2015, Brian Clark
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.