You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2022/06/15 11:28:51 UTC
[tomcat-native] 03/03: Update docs etc for changes in Tomcat Native 2.0.x
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat-native.git
commit aa3e7f5969c78426d81d7847eb67825d7d54ac1b
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Wed Jun 15 12:01:51 2022 +0100
Update docs etc for changes in Tomcat Native 2.0.x
---
README.txt | 13 ++----
native/BUILDING | 123 ++++++++++++++++++++++++++++++++------------------------
xdocs/index.xml | 71 +++++++++-----------------------
3 files changed, 94 insertions(+), 113 deletions(-)
diff --git a/README.txt b/README.txt
index e004aadb8..ca5213fab 100644
--- a/README.txt
+++ b/README.txt
@@ -5,10 +5,9 @@
What is it?
-----------
-The Apache Tomcat Native Library provides portable API for features
-not found in contemporary JDK's. It uses Apache Portable Runtime as
-operating system abstraction layer and OpenSSL for SSL networking and
-allows optimal performance in production environments.
+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.
Licensing
@@ -30,15 +29,11 @@ included in HTML format in the docs directory.
The most up-to-date documentation can be found at
http://tomcat.apache.org/native-doc/
-Documentation about the Tomcat APR connector which is based
-on this library can be found at
-http://tomcat.apache.org/tomcat-9.0-doc/apr.html.
-
Building
--------
-To build the Java API. Note that Java 1.8 is required to build the Java API.
+To build the Java API. Note that Java 11 is required to build the Java API.
> ant
To build the native part see native/BUILDING.
diff --git a/native/BUILDING b/native/BUILDING
index 9bf7cc6e9..0e6763d61 100644
--- a/native/BUILDING
+++ b/native/BUILDING
@@ -20,8 +20,8 @@ Linux / Unix / OSX (dynamic linking)
1. Prerequisites
- Install OpenSSL version 1.0.2 or higher
- Install APR version 1.4.3 or higher.
+ Install OpenSSL version 3.0.0 or higher
+ Install APR version 1.7.0 or higher.
Download and expand the source package or use an git checkout
> cd native
@@ -38,26 +38,19 @@ Linux / Unix / OSX (dynamic linking)
> configure --with-apr=apr_install_location --with-ssl=openssl_install_location
> make
- This should produce a file named libtcnative-1.so
+ This should produce a file named libtcnative-2.so
- Note: To build without SSL support use:
-
- > configure --disable-openssl --with-apr=apr_install_location
-
Linux / Unix / OSX (static linking)
===================================
-1. Build static version of OpenSSL 1.0.2 or later
+1. Build static version of OpenSSL 3.0.0 or later
- > ./Configure --prefix=~/natives/openssl no-shared -fPIC
+ > ./Configure --prefix=~/natives/openssl enable-fips
> make
- > make install_sw
-
- Note: For the Solaris platform you should use -KPIC instead -fPIC so that the
- library is compiled with position independent code.
+ > make install
-2. Build static version of APR 1.4.0 or later
+2. Build static version of APR 1.7.0 or later
> ./configure --prefix=~/natives/apr
> make
@@ -67,7 +60,7 @@ Linux / Unix / OSX (static linking)
3. Ensure the static APR library is used
- Edit the ~/natives/apr/lib/libapr-1.la file and comment or delete the
+ Edit the ~/natives/apr/lib/libapr-2.la file and comment or delete the
following sections: dlname='...' and library_names='...'
This is needed so that libtool picks the static version of the library.
@@ -93,59 +86,85 @@ Windows
3. Build APR
Unpack the APR source distribution into native\srclib\apr
- Apply apr-enable-ipv6.patch
-
+
> c:\cmsc\setenv.bat /x86
> nmake -f NMAKEmakefile BUILD_CPU=x86 APR_DECLARE_STATIC=1
- > mkdir WINXP_X86_LIB_RELEASE\include
- > mkdir WINXP_X86_LIB_RELEASE\lib
- > xcopy /E include WINXP_X86_LIB_RELEASE\include\
- > copy WINXP_X86_LIB_RELEASE\apr-1.lib WINXP_X86_LIB_RELEASE\lib
-
+
> c:\cmsc\setenv.bat /x64
> nmake -f NMAKEmakefile BUILD_CPU=x64 APR_DECLARE_STATIC=1
- > mkdir WINXP_X64_LIB_RELEASE\include
- > mkdir WINXP_X64_LIB_RELEASE\lib
- > xcopy /E include WINXP_X64_LIB_RELEASE\include\
- > copy WINXP_X64_LIB_RELEASE\apr-1.lib WINXP_X64_LIB_RELEASE\lib
-
+
4. Build OpenSSL
- Unpack the OpenSSL source distribution into native\srclib\openssl
- Apply openssl-msvcrt.patch
-
+ > cd ..\openssl
+
+ Unpack the OpenSSL 3.0.x source distribution in this directory
+
+ Apply openssl-msvcrt-3.0.x.patch. Note that you may need to skip and/or use an offset to get the patch to apply.
+
> c:\cmsc\setenv.bat /x86
- > perl Configure VC-WIN32
- > ms\do_nasm
- > nmake -f ms\nt.mak
- > mkdir release-x86
- > mkdir release-x86\include
- > mkdir release-x86\lib
- > xcopy /E inc32 release-x86\include\
- > copy out32\*.lib release-x86\lib\
+ > perl Configure no-shared VC-WIN32
+ > nmake
+ > mkdir out32-x86
+ > copy libssl.lib out32-x86\
+ > copy libcrypto.lib out32-x86\
+ > copy apps\openssl.exe out32-x86\
+ > nmake clean
+
> c:\cmsc\setenv.bat /x64
- > perl Configure VC-WIN64A
- > ms\do_win64a
- > nmake -f ms\nt.mak clean
- > nmake -f ms\nt.mak
- > mkdir release-x64
- > mkdir release-x64\include
- > mkdir release-x64\lib
- > xcopy /E inc32 release-x64\include\
- > copy out32\*.lib release-x64\lib\
+ > perl Configure no-shared VC-WIN64A
+ > nmake
+ > mkdir out32-x64
+ > copy libssl.lib out32-x64\
+ > copy libcrypto.lib out32-x64\
+ > copy apps\openssl.exe out32-x64\
-5. Build tc-native
+5. Copy APR and OpenSSL to versioned directories
- > SET JAVA_HOME=C:\Program Files\Java\jdk1.7.0_71
+ Keeping the various libraries in versioned directories saves having to
+ rebuild them next time if the version remains unchanged.
+
+ > cd ..
+ > set OPENSSL_VER=3.0.0
+ > set APR_VER=1.7.0
+
+ > mkdir \deps-x86\apr-%APR_VER%\include
+ > mkdir \deps-x86\apr-%APR_VER%\lib
+ > mkdir \deps-x86\openssl-%OPENSSL_VER%\include
+ > mkdir \deps-x86\openssl-%OPENSSL_VER%\lib
+ > xcopy /E \deps-x86\apr-%APR_VER% \deps-x64\apr-%APR_VER%\
+ > xcopy /E \deps-x86\openssl-%OPENSSL_VER% \deps-x64\openssl-%OPENSSL_VER%\
+
+ > xcopy /E apr\include \deps-x86\apr-%APR_VER%\include\
+ > xcopy /E apr\include \deps-x64\apr-%APR_VER%\include\
+
+ > copy apr\WIN7_X86_LIB_RELEASE\apr-1.lib \deps-x86\apr-%APR_VER%\lib
+ > copy apr\WIN7_X64_LIB_RELEASE\apr-1.lib \deps-x64\apr-%APR_VER%\lib
+ > xcopy /E openssl\include\openssl \deps-x86\openssl-%OPENSSL_VER%\include\openssl\
+ > xcopy /E openssl\include\openssl \deps-x64\openssl-%OPENSSL_VER%\include\openssl\
+ > copy openssl\out32-x86\*.lib \deps-x86\openssl-%OPENSSL_VER%\lib\
+ > copy openssl\out32-x64\*.lib \deps-x64\openssl-%OPENSSL_VER%\lib\
+
+ > copy openssl\out32-x86\openssl.exe \deps-x86\openssl-%OPENSSL_VER%\
+ > copy openssl\out32-x64\openssl.exe \deps-x64\openssl-%OPENSSL_VER%\
+
+
+ 6. Build Tomcat Native
+
+ > cd ..
+ >set JAVA_HOME=\java\jdk11
> c:\cmsc\setenv.bat /x86
- > nmake -f NMAKEMakefile WITH_APR=srclib\apr\WINXP_X86_LIB_RELEASE WITH_OPENSSL=srclib\openssl\release-x86 APR_DECLARE_STATIC=1
+ > nmake -f NMAKEMakefile WITH_APR=C:\deps-x86\apr-%APR_VER% WITH_OPENSSL=C:\deps-x86\openssl-%OPENSSL_VER% APR_DECLARE_STATIC=1 OPENSSL_NEW_LIBS=1 ENABLE_OCSP=1
+ > move WIN7_X86_DLL_RELEASE WIN7_X86_OCSP_DLL_RELEASE
+ > nmake -f NMAKEMakefile WITH_APR=C:\deps-x86\apr-%APR_VER% WITH_OPENSSL=C:\deps-x86\openssl-%OPENSSL_VER% APR_DECLARE_STATIC=1 OPENSSL_NEW_LIBS=1
> c:\cmsc\setenv.bat /x64
- > nmake -f NMAKEMakefile WITH_APR=srclib\apr\WINXP_X64_LIB_RELEASE WITH_OPENSSL=srclib\openssl\release-x64 APR_DECLARE_STATIC=1
+ > nmake -f NMAKEMakefile WITH_APR=C:\deps-x64\apr-%APR_VER% WITH_OPENSSL=C:\deps-x64\openssl-%OPENSSL_VER% APR_DECLARE_STATIC=1 OPENSSL_NEW_LIBS=1 ENABLE_OCSP=1
+ > move WIN7_X64_DLL_RELEASE WIN7_X64_OCSP_DLL_RELEASE
+ > nmake -f NMAKEMakefile WITH_APR=C:\deps-x64\apr-%APR_VER% WITH_OPENSSL=C:\deps-x64\openssl-%OPENSSL_VER% APR_DECLARE_STATIC=1 OPENSSL_NEW_LIBS=1
- Note: Use ENABLE_OCSP=1 to create OCSP enabled builds
+ Tomcat Native Connector DLLs may then be found in native\WIN7_*_[OCSP_]DLL_RELEASE
FIPS
diff --git a/xdocs/index.xml b/xdocs/index.xml
index 927b286ba..5f4b2f8f2 100644
--- a/xdocs/index.xml
+++ b/xdocs/index.xml
@@ -33,28 +33,10 @@
<p>
The Apache Tomcat Native Library is an optional component for use with
- Apache Tomcat that allows Tomcat to use certain native resources
- for performance, compatibility, etc.
+ Apache Tomcat that allows Tomcat to use OpenSSL as a replacement for JSSE
+ to support TLS connections.
</p>
- <p>
- Specifically, the Apache Tomcat Native Library gives Tomcat access to
- the Apache Portable Runtime (APR) library's network connection (socket)
- implementation and random-number generator.
- See the Apache Tomcat documentation for more information on how to
- configure Tomcat to use the APR connector.
- </p>
-
- <p>
- Features of the APR connector:
- </p>
- <ul>
- <li>Non-blocking I/O for Keep-Alive requests (between requests)</li>
- <li>Uses OpenSSL for TLS/SSL capabilities (if supported by linked APR library)</li>
- <li>FIPS 140-2 support for TLS/SSL (if supported by linked OpenSSL library)</li>
- <li>Support for IPv4, IPv6 and Unix Domain Sockets</li>
- </ul>
-
</section>
<section name="Headlines">
@@ -113,21 +95,21 @@ list of changes.
<p>
to create the includes and makefiles to be able to build tc-native.<br/>
Where:<br/>
- <code>$HOME/APR</code> is something like /usr/bin/apr-1-config or the path where apr is
- installed.<br/>
- <code>$JAVA_HOME</code> is something /home/jfclere/JAVA/jdk1.7.0_80 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.<br/>
+ <code>$HOME/APR</code> is something like /usr/bin/apr-1-config or the path
+ where apr is installed.<br/>
+ <code>$JAVA_HOME</code> 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.<br/>
<code>$HOME/OPENSSL</code> is the path where OpenSSL is installed.<br/>
<code>$CATALINA_HOME</code> is the path where the produced libraries will be
- installed. Something like $HOME/apache-tomcat-8.0.47/<br/>
+ installed. Something like $HOME/apache-tomcat-10.0.2<br/>
<br/>
The configure is able to guess most of OpenSSL standard installations.
So most of the time the following will be enough:
</p>
<source
>./configure --with-apr=/usr/bin/apr-1-config \
- --with-java-home=/home/jfclere/JAVA/jdk1.7.0_80/ \
+ --with-java-home=/home/jfclere/JAVA/jdk11 \
--with-ssl=yes \
--prefix=$CATALINA_HOME</source>
<p>
@@ -176,13 +158,6 @@ list of changes.
Please see the Apache Tomcat documentation for configuration specifics.
</p>
- <p>
- When using Unix Domain Sockets a cleanup is registered to delete the
- socket on destruction of the socket, or shutdown of the application.
- Should the application terminate abnormally, the socket deletion will
- need to be handled by the caller or by the administrator.
- </p>
-
</subsection>
<subsection name="UNIX">
@@ -193,21 +168,17 @@ list of changes.
<source>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CATALINA_HOME/lib
export LD_LIBRARY_PATH</source>
<p>
- Start tomcat and check for the messages like this ones:
+ Start tomcat and check for the messages like these ones:
</p>
<source wrapped="true"
->Nov 29, 2020 12:27:41 PM org.apache.catalina.core.AprLifecycleListener init
-INFO: Loaded APR based Apache Tomcat Native library 1.x.y.
-Nov 29, 2020 12:27:41 PM org.apache.catalina.core.AprLifecycleListener init
-INFO: APR capabilities: IPv6 [true], sendfile [true], accept filters [false], random [true], UDS [true].
-Nov 29, 2020 12:27:41 PM org.apache.coyote.http11.Http11AprProtocol init
-INFO: Initializing Coyote HTTP/1.1 on http-8080</source>
+>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]</source>
<p>
Refer to the tomcat documentation to configure the connectors (See
- <a href="http://tomcat.apache.org/tomcat-10.0-doc/apr.html">Tomcat 10.0.x</a>,
- <a href="http://tomcat.apache.org/tomcat-9.0-doc/apr.html">Tomcat 9.0.x</a> and
- <a href="http://tomcat.apache.org/tomcat-8.5-doc/apr.html">Tomcat 8.5.x</a>)
+ <a href="https://tomcat.apache.org/tomcat-10.1-doc/config/http.html">Tomcat 10.1.x</a>,
+ <a href="https://tomcat.apache.org/tomcat-9.0-doc/config/http.html">Tomcat 9.0.x</a> and
+ <a href="https://tomcat.apache.org/tomcat-8.5-doc/config/http.html">Tomcat 8.5.x</a>)
</p>
</subsection>
@@ -220,15 +191,11 @@ INFO: Initializing Coyote HTTP/1.1 on http-8080</source>
<source wrapped="true"
>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</source>
<p>
- Start tomcat and check for the messages like this ones:
+ Start tomcat and check for the messages like these ones:
</p>
- <source wrapped="true"
->Nov 29, 2020 2:48:17 PM org.apache.catalina.core.AprLifecycleListener init
-INFO: Loaded APR based Apache Tomcat Native library 1.x.y.
-Nov 29, 2020 2:48:17 PM org.apache.catalina.core.AprLifecycleListener init
-INFO: APR capabilities: IPv6 [false], sendfile [true], accept filters [false], random [true], UDS [false].
-Nov 29, 2020 2:48:18 PM org.apache.coyote.http11.Http11AprProtocol init
-INFO: Initializing Coyote HTTP/1.1 on http-8080</source>
+ <source wrapped="true"
+>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]</source>
</subsection>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org