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.
Documentation Index
Introduction
Headlines
- 7 August 2023 - TC-Native-2.0.5
released
The Apache Tomcat team is proud to announce the immediate availability of Tomcat Native 2.0.5 Stable.
The sources and the binaries for selected platforms are available from the Download page.
Please see the Changelog for a full list of changes.
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 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]