Documentation Index

Introduction

The Apache Tomcat Native Library is an optional component for use with Apache Tomcat that allows Tomcat to use OpenSSL as a replacement for JSSE to support TLS connections.

Headlines

Building

Requirements

Build tc-native requires three components to be installed:

  • APR library
  • OpenSSL libraries
  • Java SE Development Kit (JDK)

In debian based Linux those dependencies could be installed by something like:

apt-get install libapr1.0-dev libssl-dev

In rpm based Linux those dependencies could be installed by something like:

yum install apr-devel openssl-devel

UNIX

On all the POSIX systems (Linux, Solaris, HP-UX, AIX etc...) a well-known configure and make is used to build tc-native.
In the jni/native runs:

./configure --help

to read the description of all the parameters.

./configure --with-apr=$HOME/APR \
            --with-java-home=$JAVA_HOME \
            --with-ssl=$HOME/OPENSSL \
            --prefix=$CATALINA_HOME

to create the includes and makefiles to be able to build tc-native.
Where:
$HOME/APR is something like /usr/bin/apr-1-config or the path where apr is installed.
$JAVA_HOME is something like /home/jfclere/JAVA/jdk11 or the path to a JDK installation. Any JDK should work but it is advisable to use the same JVM version the JVM you use with Tomcat.
$HOME/OPENSSL is the path where OpenSSL is installed.
$CATALINA_HOME is the path where the produced libraries will be installed. Something like $HOME/apache-tomcat-10.1.0

The configure is able to guess most of OpenSSL standard installations. So most of the time the following will be enough:

./configure --with-apr=/usr/bin/apr-1-config \
            --with-java-home=/home/jfclere/JAVA/jdk11 \
            --with-ssl=yes \
            --prefix=$CATALINA_HOME

To build the libraries and install them:

make && make install

The libraries will be found in $CATALINA_HOME/lib

Windows

Download the Windows sources of tc-native and extract them.

Obtain the Windows sources for APR and OpenSSL. Apply the patches from native/srclib and build APR and OpenSSL for your platform (X86 or X64).

Build with

nmake -f NMAKEMakefile WITH_APR=... WITH_OPENSSL=... APR_DECLARE_STATIC=1

More detailed instructions including the steps to create a standard release distribution are provided on the Wiki.

Install and tests

Configuring Tomcat

Apache Tomcat comes with the AprLifecycleListener enabled by default. Still, you should check your conf/server.xml to ensure that something like the following is present, and uncommented:

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />

Please see the Apache Tomcat documentation for configuration specifics.

UNIX

Edit $CATALINA_HOME/bin/setenv.sh (creating the file if necessary) and add the path to the tc-native libraries to LD_LIBRARY_PATH. Something like:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CATALINA_HOME/lib
export LD_LIBRARY_PATH

Start tomcat and check for the messages like these ones:

15-Jun-2022 11:06:23.274 INFO [main] org.apache.catalina.core.AprLifecycleListener.lifecycleEvent Loaded Apache Tomcat Native library [2.0.0-dev] using APR version [1.7.0]
15-Jun-2022 11:06:23.298 INFO [main] org.apache.catalina.core.AprLifecycleListener.initializeSSL OpenSSL successfully initialized [OpenSSL 3.0.4-dev 3 May 2022]

Refer to the tomcat documentation to configure the connectors (See Tomcat 11.0.x, Tomcat 10.1.x, Tomcat 9.0.x and Tomcat 8.5.x)

Windows

Edit $CATALINA_BASE\bin\setenv.bat (creating the file if necessary) and add the path to the tc-native libraries, apr and OpenSSL to PATH. For example:

set PATH=%PATH;C:\cygwin\home\support\tomcat-native-current-win32-src\jni\native\Debug;C:\cygwin\home\support\tomcat-native-current-win32-src\jni\apr\Debug;C:\OpenSSL\lib\VC

Start tomcat and check for the messages like these ones:

15-Jun-2022 11:06:23.274 INFO [main] org.apache.catalina.core.AprLifecycleListener.lifecycleEvent Loaded Apache Tomcat Native library [2.0.0-dev] using APR version [1.7.0]
15-Jun-2022 11:06:23.298 INFO [main] org.apache.catalina.core.AprLifecycleListener.initializeSSL OpenSSL successfully initialized [OpenSSL 3.0.4-dev 3 May 2022]