Forked Tomcat Native

netty-tcnative is a fork of Tomcat Native. It includes a set of changes contributed by Twitter, Inc, such as:

• Simplified distribution and linkage of native library
• Complete mavenization of the project
• Improved OpenSSL support

To minimize the maintenance burden, we create a dedicated branch for each stable upstream release and apply our own changes on top of it, while keeping the number of maintained branches to minimum.

Artifacts

netty-tcnative is a multi-module project and builds a few artifacts, allowing it to be used in a variety of environments.

How to download netty-tcnative-boringssl "uber" jar

This is the simplest dependency to use, since it doesn't require a platform-specific classifier:

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative-boringssl-static</artifactId>
      <version>1.1.33.Fork15</version>
    </dependency>
    ...
  </dependencies>
  ...
</project>

How to download netty-tcnative-boringssl-static

In your application's pom.xml, add the os-maven-plugin extension and the netty-tcnative-boringssl-static dependency appropriate for your platform:

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative-boringssl-static</artifactId>
      <version>1.1.33.Fork15</version>
      <classifier>${os.detected.classifier}</classifier>
    </dependency>
    ...
  </dependencies>
  ...
  <build>
    ...
    <extensions>
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    ...
  </build>
  ...
</project>

Netty-tcnative uses classifiers when deploying to Maven Central and provide distributions for the following platforms:

How to download netty-tcnative

In your application's pom.xml, add the os-maven-plugin extension and netty-tcnative dependency:

<project>
  <properties>
    <!-- Configure the os-maven-plugin extension to expand the classifier on -->
    <!-- Fedora-"like" systems. -->
     <os.detection.classifierWithLikes>fedora</os.detection.classifierWithLikes>
  </properties>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative</artifactId>
      <version>1.1.33.Fork15</version>
      <classifier>${os.detected.classifier}</classifier>
    </dependency>
    ...
  </dependencies>
  ...
  <build>
    ...
    <extensions>
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    ...
  </build>
  ...
</project>

Netty-tcnative uses classifiers when deploying to Maven Central to provide distributions for the various platforms. On Linux it should be noted that OpenSSL uses a different soname for Fedora derivatives than other Linux releases. Starting with version 1.1.33.Fork7, we work around this limitation by deploying two separate versions for Linux (see the table below).

Using classifierWithLikes will configure the os-maven-plugin to alter the generated os.detected.classifier property. If your build contains other dependencies that rely on os.detected.classifier, you can manually create the netty-tcnative classifier with the antrun plugin:

<project>
  <dependencies>
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative</artifactId>
      <version>1.1.33.Fork15</version>
      <classifier>${tcnative.classifier}</classifier>
    </dependency>
  </dependencies>

  <build>
    <extensions>
      <!-- Use os-maven-plugin to initialize the "os.detected" properties -->
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    <plugins>
      <!-- Use Ant to configure the appropriate "tcnative.classifier" property -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-antrun-plugin</artifactId>
        <executions>
          <execution>
            <phase>initialize</phase>
            <configuration>
              <exportAntProperties>true</exportAntProperties>
              <target>
                <condition property="tcnative.classifier"
                           value="${os.detected.classifier}-fedora"
                           else="${os.detected.classifier}">
                  <isset property="os.detected.release.fedora"/>
                </condition>
              </target>
            </configuration>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

How to use

To use the OpenSSL-based SSLEngine implementation, use io.netty.handler.ssl.SslContext class:

public static void main(String[] args) throws Exception {
  SslContext sslCtx = SslContext.newServerContext(SslProvider.OPENSSL, ...);
  ...
}

public class MyChannelInitializer extends ChannelInitializer<SocketChannel> {

  private final SslContext sslCtx;

  public MyChannelInitializer(SslContext sslCtx) {
    this.sslCtx = sslCtx;
  }

  @Override
  public void initChannel(SocketChannel ch) throws Exception {
    ChannelPipeline p = ch.pipeline();
    if (sslCtx != null) {
      p.addLast(sslCtx.newHandler(ch.alloc()));
    }
    ...
  }
}

Netty will unpack the shared library provided by the netty-tcnative-XXX artifact into a temporary directory and load it using java.lang.System.load(String).

Prerequisites for Dynamically Linked netty-tcnative

Note that the shared library in the netty-tcnative artifact is dynamically linked against Apache Portable Runtime (APR) and OpenSSL. They must be in the library load path such as system library directories, $LD_LIBRARY_PATH, and %PATH%.

• If you are on Linux, you probably don't need to do anything because you can install them using your system's package manager.
• If you are on Mac, you have to install openssl package using Homebrew.
• If you are on Windows, you have to:
  • Build APR by yourself (or get the 64-bit DLL from our CI server),
  • Install OpenSSL for Windows, and
  • Add the directories that contain the .DLL files to %PATH%.

Important: If you use Linux and want to make use of ALPN (you will need this for http2) you need to ensure you have openssl >= 1.0.2 installed. If this is not provided by the package system of your distro you will need to compile it by your own and set the LD_LIBRARY_PATH as explained in How to built.

How to build

You don't usually need to build netty-tcnative by yourself because we officially ship the JARs with the native libraries for Linux x86_64, Mac OS X x86_64, and Windows x86_64. If you are looking for a SNAPSHOT build, browse our CI server.

If you are on a platform we don't ship the JARs with the native libraries, such as Windows x86_32, follow the instructions in this section.

Building on Linux

Build the package and install it into your local Maven repository:

git clone https://github.com/netty/netty-tcnative.git
cd netty-tcnative
# To build a specific version: (e.g. netty-tcnative-1.1.33.Fork15)
git checkout netty-tcnative-[version]
# To build a snapshot: (e.g. 1.1.33)
git checkout [branch]
mvn clean install

Building on Mac OS X

First of you need to install Xcode. After this make sure you install the command line tools as well:

xcode-select --install

Use Homebrew to install the required packages:

brew install autoconf automake libtool openssl perl ninja golang cmake

Add the following exports to your ~/.bash_profile, so that the compiler and linker finds OpenSSL built by Homebrew.

export CPPFLAGS="-I/usr/local/opt/openssl/include $CPPFLAGS"
export LDFLAGS="-L/usr/local/opt/openssl/lib $LDFLAGS"

Build the package and install it into your local Maven repository:

git clone https://github.com/netty/netty-tcnative.git
cd netty-tcnative
# To build a specific version: (e.g. netty-tcnative-1.1.33.Fork15)
git checkout netty-tcnative-[version]
# To build a snapshot: (e.g. 1.1.33)
git checkout [branch]
mvn clean install

Building on Windows

This section describes how to build on 64-bit Windows. Some of these steps may have to be tailored when building on 32-bit systems.

Install the following packages:

• Visual C++ 2013 Express
• Windows 10 SDK
• CMake
  • During installation, select Add CMake to the system PATH for current user
• Perl
• Ninja
  • Extract the executable to C:\Workspaces\ and add C:\Workspaces to PATH
• Go
• Yasm
  • Download to C:\Workspaces
  • Set the environment variable ASM_NASM=C:\Workspaces\yasm-1.3.0-win64.exe.
• OpenSSL.
  • During installation, select Copy OpenSSL DLLs to: The OpenSSL binaries (/bin) directory
  • Set the following environment variables:
    • OPENSSL_INCLUDE_DIR=C:\OpenSSL-Win64\include
    • OPENSSL_LIB_DIR=C:\OpenSSL-Win64\lib
• Apache Portable Runtime (APR) 1.5.2
  • Extract into: C:\Workspaces\apr-1.5.2
  • Run the following commands in command prompt (cmd.exe) from C:\Workspaces\apr-1.5.2:
    • "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86_amd64
    • nmake /f Makefile.win ARCH="x64 Release" PREFIX=..\apr-1.5.2-dist buildall install
    • xcopy include\arch\win32\*.h ..\apr-1.5.2-dist\include /d
    • xcopy include\arch\*.h ..\apr-1.5.2-dist /d
  • Set the following environment variables:
    • APR_INCLUDE_DIR=C:\Workspaces\apr-1.5.2-dist\include
    • APR_LIB_DIR=C:\Workspaces\apr-1.5.2-dist\lib

Now, start the command prompt (cmd.exe) and load the environment variables required for Visual C++:

"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86_amd64

Clone netty-tcnative and build it:

git clone https://github.com/netty/netty-tcnative.git
cd netty-tcnative
REM To build a specific version: (e.g. netty-tcnative-1.1.33.Fork15)
git checkout netty-tcnative-[version]
REM To build a snapshot: (e.g. 1.1.33.Fork15)
git checkout [branch]
mvn clean install

Creating a new fork

Checking out the branch bootstrap and running the new-fork script with the upstream tcnative version will bring you to a new fully mavenized branch whose name is identical to the upstream tcnative version. For example:

$ git checkout bootstrap
$ ./new-fork 1.1.29 1

will create a new branch called 1.1.29, which contains a mavenized fork of tcnative-1.1.29. Please note that the fork does not contain any patches that will change the main source code of tcnative. You will probably want to cherry-pick some commits from other branches that were patched already.