Ansible Role apache_tomcat

This role installs and configures one Apache Tomcat instance.

It is possible to configure whether the Manager Web GUI should be installed (it is installed by default). When installed, the Manager Web GUI is accessible via http://tomcat:8080/manager/. The role uses the operating system’s package manager, so EPEL is a must on RHEL. Logrotation in Tomcat is disabled and is done by logrotated.

Runs on

  • RHEL 7 (and compatible) - Installs Tomcat 7.0.76+ and Java 1.8.0

  • RHEL 8 (and compatible) - Installs Tomcat 9.0.65+ and Java 1.8.0

Mandatory Requirements

Tags

Tag

What it does

apache_tomcat

* Install tomcat-admin-webapps, or install tomcat only
* Copy tomcat logrotate template to /etc/logrotate.d
* mkdir -p /etc/systemd/system/tomcat.service.d
* Deploy /etc/systemd/system/tomcat.service.d/override.conf
* Deploy /etc/tomcat/context.xml
* Deploy /etc/tomcat/logging.properties
* Deploy /etc/tomcat/server.xml
* Deploy /var/lib/tomcat/webapps/manager/META-INF/context.xml
* Deploy /var/lib/tomcat/webapps/manager/WEB-INF/web.xml
* Deploy /etc/tomcat/tomcat-users.xml
* systemctl enable/disable --now tomcat.service

apache_tomcat:configure

* Copy tomcat logrotate template to /etc/logrotate.d
* mkdir -p /etc/systemd/system/tomcat.service.d
* Deploy /etc/systemd/system/tomcat.service.d/override.conf
* Deploy /etc/tomcat/context.xml
* Deploy /etc/tomcat/logging.properties
* Deploy /etc/tomcat/server.xml
* Deploy /var/lib/tomcat/webapps/manager/META-INF/context.xml
* Deploy /var/lib/tomcat/webapps/manager/WEB-INF/web.xml
* Deploy /etc/tomcat/tomcat-users.xml

apache_tomcat:users

* Deploy /etc/tomcat/tomcat-users.xml

apache_tomcat:state

* systemctl enable/disable --now tomcat.service

Mandatory Role Variables

Only mandatory if installing the Manager Web GUI.

Note that for Tomcat 7 onwards, the roles required to use the manager application were changed from the single manager role to the following four roles. You will need to assign the role(s) required for the functionality you wish to access:

  • manager-gui: Allows access to the HTML GUI and the status pages.

  • manager-script: Allows access to the text interface and the status pages.

  • manager-jmx: Allows access to the JMX proxy and the status pages.

  • manager-status: Allows access to the status pages only.

The GUI is protected against CSRF, but the text and JMX interfaces are not. To maintain CSRF protection, users with the manager-gui role should not be given the manager-script or manager-jmx roles.

Variable

Description

apache_tomcat__webapps_manager_context_xml_allow

String. Manager App. A regex that describes which IP addresses are allowed to access the manager and host-manager webapps.

apache_tomcat__users__host_var /
apache_tomcat__users__group_var

List of dictionaries. Users allowed to access the Manager Web GUI. Subkeys:

  • password: Mandatory, string.
  • roles: Mandatory, list. Any of admin, admin-gui, admin-script, manager, manager-gui, manager-script, manager-jmx, manager-status
  • state: Optional, string. Either present or absent.
  • username: Mandatory, string.

Example:

# only mandatory if installing the Manager Web GUI
apache_tomcat__users__host_var:
  - username: 'tomcat-admin'
    password: 'linuxfabrik'
    roles:
      - 'admin-gui'
      - 'manager-gui'
    state: 'present'
apache_tomcat__webapps_manager_context_xml_allow: '|192\.168\.122\.\d+|10\.80\.32\.\d+'

Optional Role Variables

Variable

Description

Default Value

apache_tomcat__context_xml_cache_max_size

Number. The maximum size of the static resource cache in kilobytes. If not specified, the default value is 10240 (10 megabytes). This value may be changed while the web application is running (e.g. via JMX). If the cache is using more memory than the new limit the cache will attempt to reduce in size over time to meet the new limit. If necessary, cacheObjectMaxSize will be reduced to ensure that it is no larger than cacheMaxSize/20. Doc

102400

apache_tomcat__env_xms

Number. CATALINA_OPTS=-Xms. Specifies the initial heap size.

'1024M'

apache_tomcat__env_xmx

Number. CATALINA_OPTS=-Xmx. Specifies the maximum heap size.

'1024M'

apache_tomcat__env_xx

For specifiying various JVM Options after -XX::
* Boolean options are turned on with -XX:+ and turned off with -XX:-.
* Numeric options are set with -XX:=. Numbers can include 'm' or 'M' for megabytes, 'k' or 'K' for kilobytes, and 'g' or 'G' for gigabytes (for example, 32k is the same as 32768).
* String options are set with -XX:=, are usually used to specify a file, a path, or a list of commands.

'+UseParallelGC'

apache_tomcat__logrotate

Number. Log files are rotated count days before being removed or mailed to the address specified in a logrotate mail directive. If count is 0, old versions are removed rather than rotated. If count is -1, old logs are not removed at all (use with caution, may waste performance and disk space).

{{ logrotate__rotate | d(14) }}

apache_tomcat__roles__host_var /
apache_tomcat__roles__group_var

List of dictionaries. Tomcat roles to deploy. Subkeys:

  • name: Mandatory, string. Name of the role.
  • state: Optional, string. Either present or absent.

Built-in Tomcat manager roles are:
  • manager-gui: Allows access to the HTML GUI and the status pages.
  • manager-script: Allows access to the HTTP API and the status pages.
  • manager-jmx: Allows access to the JMX proxy and the status pages.
  • manager-status: Allows access to the status pages only.

['admin-gui', 'manager-gui']

apache_tomcat__server_xml_ajp_port

Number. The TCP port number on which this Connector will create a server socket and await incoming connections. Your operating system will allow only one server application to listen to a particular port number on a particular IP address. If the special value of 0 (zero) is used, then Tomcat will select a free port at random to use for this connector. This is typically only useful in embedded and testing applications. Doc

unset (not listening on AJP)

apache_tomcat__server_xml_connector_compression

String. The Connector may use HTTP/1.1 GZIP compression in an attempt to save server bandwidth. The acceptable values for the parameter is „off“ (disable compression), „on“ (allow compression, which causes text data to be compressed), „force“ (forces compression in all cases), or a numerical integer value (which is equivalent to „on“, but specifies the minimum amount of data before the output is compressed). If the content-length is not known and compression is set to „on“ or more aggressive, the output will also be compressed. If not specified, this attribute is set to „off“.
Note: There is a tradeoff between using compression (saving your bandwidth) and using the sendfile feature (saving your CPU cycles). If the connector supports the sendfile feature, e.g. the NIO connector, using sendfile will take precedence over compression. The symptoms will be that static files greater that 48 Kb will be sent uncompressed. You can turn off sendfile by setting useSendfile attribute of the connector, as documented below, or change the sendfile usage threshold in the configuration of the DefaultServlet in the default conf/web.xml or in the web.xml of your web application. Doc

'on'

apache_tomcat__server_xml_connector_connection_timeout

The number of milliseconds this Connector will wait, after accepting a connection, for the request URI line to be presented. Use a value of -1 to indicate no (i.e. infinite) timeout. The default value is 60000 (i.e. 60 seconds) but note that the standard server.xml that ships with Tomcat sets this to 20000 (i.e. 20 seconds). Unless disableUploadTimeout is set to false, this timeout will also be used when reading the request body (if any). This parameter is there specifically to fight one type of Denial-Of-Service attack, whereby some malicious client(s) create a TCP connection to the server (which has the effect of reserving some resources on the server for handling this connection), and then just sit there without sending any HTTP request on that connection. By making this delay shorter, you shorten the time during which the server resources are allocated, to serve a request that will never come. Doc

20000

apache_tomcat__server_xml_connector_max_threads

Number. The maximum number of request processing threads to be created by this Connector, which therefore determines the maximum number of simultaneous requests that can be handled. If not specified, this attribute is set to 200. If an executor is associated with this connector, this attribute is ignored as the connector will execute tasks using the executor rather than an internal thread pool. Note that if an executor is configured any value set for this attribute will be recorded correctly but it will be reported (e.g. via JMX) as -1 to make clear that it is not used. Doc

200

apache_tomcat__server_xml_connector_min_spare_threads

Number. The minimum number of threads always kept running. This includes both active and idle threads. If an executor is associated with this connector, this attribute is ignored as the connector will execute tasks using the executor rather than an internal thread pool. Note that if an executor is configured any value set for this attribute will be recorded correctly but it will be reported (e.g. via JMX) as -1 to make clear that it is not used. Doc

10

apache_tomcat__server_xml_connector_port

The TCP port number on which this Connector will create a server socket and await incoming connections. Your operating system will allow only one server application to listen to a particular port number on a particular IP address. If the special value of 0 (zero) is used, then Tomcat will select a free port at random to use for this connector. This is typically only useful in embedded and testing applications. Doc

8080

apache_tomcat__server_xml_shutdown_port

8005

apache_tomcat__service_enabled

Bool. Enables or disables the service, analogous to systemctl enable/disable --now.

true

apache_tomcat__service_state

String. Changes the state of the service, analogous to systemctl start/stop/restart/reload. Possible options:
* reloaded
* restarted
* started
* stopped

'started'

apache_tomcat__skip_manager

Bool. If set to true, installation of the Manager Web GUI will be skipped.

false

apache_tomcat__webapps_manager_web_xml_max_file_size

Number. Manager App. File size limit for WAR file uploads in bytes. Defaults to 50MB.

52428800

apache_tomcat__webapps_manager_web_xml_max_request_size

Number. Manager App. Request limit in bytes. Defaults to 50MB.

52428800

Example:

# optional
apache_tomcat__context_xml_cache_max_size: 102400
apache_tomcat__env_xms: '1024M'
apache_tomcat__env_xmx: '1024M'
apache_tomcat__env_xx: '+UseParallelGC'
apache_tomcat__logrotate: 7
apache_tomcat__roles__host_var:
  - name: 'admin-gui'
    state: 'present'
  - name: 'manager-gui'
    state: 'absent'
apache_tomcat__server_xml_ajp_port: 8009
apache_tomcat__server_xml_connector_compressable_mime_types: 'text/html,text/xml,text/plain'
apache_tomcat__server_xml_connector_compression: 'on'
apache_tomcat__server_xml_connector_connection_timeout: 60000
apache_tomcat__server_xml_connector_max_threads: 200
apache_tomcat__server_xml_connector_min_spare_threads: 10
apache_tomcat__server_xml_connector_port: 8080
apache_tomcat__server_xml_shutdown_port: 8005
apache_tomcat__service_enabled: true
apache_tomcat__service_state: 'started'
apache_tomcat__skip_manager: false
apache_tomcat__webapps_manager_web_xml_max_file_size: 209715200
apache_tomcat__webapps_manager_web_xml_max_request_size: 209715200

Troubleshooting

WARN org.hibernate.engine.jdbc.internal.JdbcServicesImpl:169 - HHH000342: Could not obtain connection to query metadata : Cannot create PoolableConnectionFactory (Communications link failure`
The last packet sent successfully to the server was 0 milliseconds ago. The driver has not received any packets from the server.
Caused by: org.hibernate.HibernateException: Connection cannot be null when 'hibernate.dialect' not set
  • chown -R root:tomcat /var/lib/tomcat/webapps/?

  • Database Credentials correct?

  • Connection string correct? Example: jdbc:mysql://localhost/linuxfabrik?createDatabaseIfNotExist=true&useEncoding=true&characterEncoding=UTF-8

  • SELinux Boolean for Tomcat set? setsebool tomcat_can_network_connect_db on

License

The Unlicense

Author Information

Linuxfabrik GmbH, Zurich