Spring Boot Tomcat Listener's Full Config Starter

A spring boot starter which gives the user very fine grained control over Tomcat's APR and HTTP connectors via properties.

Contents

• Intended Use Case
• Requirements
• Quick Start
• Default Behavior
• Support Matrix
• Documentation
• In-Depth Examples

Intended Use Case

This starter should be used when one requires very fine grained control over embedded Tomcat connectors, but wishes that control to remain externalized. This is a very narrow use case, and if you are usure about whether or not you need the fine grained control offered, it's likely that it is not needed.

In most cases, Spring Boot's standard server.* and server.tomcat.* properties give embedded Tomcat users enough external configuration options to meet their needs. In rare cases, such as when multiple connectors with different options are required, more control over Tomcat's configuration is needed. To that end, Spring Boot provides programatic methods of fine-tuning Tomcat. The downside to the programatic approach is that the fine-tuning isn't inherently external. This starter remedies that sitution by providing externalized, application.properties based configuration for any and all tuning which is supported by Tomcat 8.0.

Requirements

See Support Matrix below.

Quick Start

<!-- pom.xml -->
<dependency>
  <groupId>com.github.ja391045<groupId>
  <artifactId>tclisten-fullcfg-spring-boot-starter<artifactId>
  <version>1.3.0.RELEASE</version>
</dependency>

application.yaml: An example of a single, HTTP Blocking I/O connector, listening on port 8080.

---
tc:
  nioHttpConnectors:
    - address: 0.0.0.0
      port: 8080

application.yaml: An example of a NIO2 HTTP connector listening on port 8080 of an interface, and an AJP connector, listening on port 8080 of localhost.

---
tc:
  nio2HttpConnectors:
    - address: myhost.mydomain.com
      port: 8080
  nio2AjpConnectors:
  	- address: localhost
  	  port: 8080

application.yaml: An example of a BIO HTTP listener on port 8080, redirecting to an APR/Native SSL listener on port 8443.

---
tc:
  bioHttpConnectors:
    - address: 0.0.0.0
    - port: 8080
    - redirectPort: 8443
  aprHttpConnectors:
    - address: 0.0.0.0
      port: 443
      secure: true
      scheme: https
      sslEnabled: true
      ssl:
        SSLCertificateKeyFile: path/to/my-key.pem
        SSLCertificateFile: path/to/my-cert.pem

Finally, an example of a NIO2 SSL listener, with SSL Client Authentication.

---
tc:
  nio2HttpConnectors:
  - address: 0.0.0.0
    port: 8443
    scheme: https
    secure: true
    sslEnabled: true
    ssl:
      clientAuth: true
      keystoreFile: /path/to/my-keystore.jks
      keystorePass: mykeypass
      keyAlias: my-server-certificate
      truststoreFile: /path/to/my-cacerts.jks
      truststorePass: my-cacerts-password

Default Behavior

If no tc.* properties are supplied in application.properties or external configuration, the following defaults are assumed. You may note that these defaults exactly mirror a vanilla server.xml configuration from a binary distribution of Tomcat 8.

• If APR/Native is available.
  • An APR AJP listener binds to 0.0.0.0:8009 with a port 8443 redirect.
  • An APR HTTP listener binds to 0.0.0.0:8080 with a port 8443 redirect.
• If APR/Native is absent.
  • A NIO AJP listener binds to 0.0.0.0:8009 with a port 8443 redirect.
  • A NIO HTTP listener binds to 0.0.0.0:8080 with a port 8443 redirect.

Support Matrix

• 1.3.0.RELEASE
  • Java 1.8
  • Spring Boot 1.3.0
  • Embedded Tomcat 8
  • (Optional) APR/Native 1.2

Documentation

Configuring embedded tomcat connectors all takes place under tc.* properties. Under tc, there are 8 main sub-properties, each of which correspond to a main "type" of Tomcat connector.

tc:
  bioHttpConnectors:
  bioAjpConnectors:
  nioHttpConnectors:
  nioAjpConnectors:
  nio2HttpConnectors:
  nio2AjpConnectors:
  aprHttpConnectors:
  aprAjpConnectors:

Under each tc.\*Connectors heading, a list of maps should be present. Each list element represents a separate connector of the heading type. And the map elements inside the list elements represent individual properties for the separate connector. All properties documented in the Apache Tomcat 8 Configuration Reference are supported.

To continue with our yaml example, the following snippet outlines the arrangement of property data within the defined YAML structure.

tc:
  nioHttpConnectors:  
    - connector1-property1: value1
      connector1-property2: value2
      connector1-property3: value3
    - connector2-property1: value1
      connector2-property2: value2
      connector2-property3: value3
  nio2AjpConnectors:
    - connector1-property1: value1
      connector1-property2: value2
    - connector2-property1: value1

Finally, certain connectors have even more nested elements. All HTTP type connectors may utilize the ssl sub-element. The NIO2 type connectors, both HTTP & AJP, have a socket sub-element, and NIO type connectors have a socket and selectorPool sub-element.

tc:
    bioHttpConnectors:
      - connector1-property1: value1
        ssl:
      	  connector1-ssl-property1: value
    nioHttpConnectors:
      - connector1-property1: value1
        ssl:
          connector1-ssl-property1: value
        socket:
          connector1-socket-property1: value
        selectorPool:
          connector1-selectorpool-property1: value

Any default values listed in Apache Tomcat 8 Configuration Reference are retained as the default value here, so not every property need be specified. In short, if you must specify a value in Tomcat's server.xml, then you must specify the value here. Otherwise, the default may be accepted.

Finally, a quick note on APR connectors. If an APR type connector is specified by configuration, but the APR/Native library is not installed, or is not available, an error will occur on application startup. Right now, this is a feature, not a bug. If a production specification dictates that APR/Native must be used, it is important that the use of the connector is assured, rather than auto-selecting another connector in the absence of APR. On the TODO list is the addition of the HTTP/1.1 & AJP/1.3 protocols as top level connectors. These protocols when specified should auto-switch between APR when available, or NIO if APR is absent.

In-Depth Examples

Hardened SSL with non-secure redirection (Pure Java NIO).

tc:
  nioHttpConnectors:
    - allowTrace: false
      enableLookups: false
      address: 0.0.0.0
      port: 8080
      maxConnections: 1000
      redirectPort: 8443
    - allowTrace: false
      enableLookups: false
      address: 0.0.0.0
      port: 8443
      scheme: https
      secure: true
      sslEnabled: true
      ssl:
        sslEnabledProtocols: TLSv1.2
        sslProtocol: TLSv1.2
        ciphers: ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
        useServerCipherSuitesOrder: true
        keystoreFile: /path/to/my-keystore.jks
        keystorePass: somepassword
        keyAlias: my-cert-alias

Hardened SSL with non-secure redirection (APR/Native)

tc:
  aprHttpConnectors:
    - enableLookups: false
      allowTrace: false
      address: 0.0.0.0
      port: 8080
      redirectPort: 8443
    - enableLookups: false
      allowTrace: false
      address: 0.0.0.0
      port: 8443
      scheme: https
      secure: true
      sslEnabled: true
      ssl:
        SSLProtocol: TLSv1.2
        SSLDisableSessionTickets: true
        SSLHonorCipherOrder: true
        SSLCipherSuite: ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
        SSLCertificateFile: /path/to/my-cert.pem
        SSLCertificateKeyFile: /path/to/my-key.pem
        SSLPassword: mykeypassphrase