netty: Updated ALPN error message and added troubleshooting procedures

1 files changed, 57 insertions, 0 deletions

diff --git a/SECURITY.md b/SECURITY.md
index b32338970..c6d1b77bc 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -287,6 +287,63 @@ public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(ServerCall<RespT> c
 
 [Mutual authentication]: http://en.wikipedia.org/wiki/Transport_Layer_Security#Client-authenticated_TLS_handshake
 
+## Troubleshooting
+
+If you received an error message "ALPN is not configured properly" or "Jetty ALPN/NPN has not been properly configured", it most likely means that:
+ - ALPN related dependencies are either not present in the classpath
+ - or that there is a classpath conflict
+ - or that a wrong version is used due to dependency management.
+
+### Netty
+If you aren't using gRPC on Android devices, you are most likely using `grpc-netty` transport.
+
+If you are developing for Android and have a dependency on `grpc-netty`, you should remove it as `grpc-netty` is unsupported on Android. Use `grpc-okhttp` instead.
+
+Find the dependency tree (e.g., `mvn dependency:tree`), and look for versions of:
+ - `io.grpc:grpc-netty`
+ - `io.netty:netty-codec-http2`
+ - `io.netty:netty-tcnative-boringssl-static:jar` 
+
+If `netty-tcnative-boringssl-static` is missing, then you either need to add it as a dependency, or use alternative methods of providing ALPN capability by reading the *Transport Security (TLS)* section carefully.
+
+If you have both `netty-codec-http2` and `netty-tcnative-boringssl-static` dependencies, then check the versions carefully. These versions could've been overridden by dependency management from another BOM. You would receive the "ALPN is not configured properly" exception if you are using incompatible versions.
+
+If you have other `netty` dependencies, such as `netty-all`, that are pulled in from other libraries, then ultimately you should make sure only one `netty` dependency is used to avoid classpath conflict. The easiest way is to exclude transitive Netty dependencies from all the immediate dependencies, e.g., in Maven use `<exclusions>`, and then add an explict Netty dependency in your project along with the corresponding `tcnative` versions. See the versions table below.
+
+If you are using `musl` libc (e.g., with Alpine Linux), then `netty-tcnative-boringssl-static` won't work. There are several alternatives:
+ - Use [netty-tcnative-alpine] (https://github.com/pires/netty-tcnative-alpine)
+ - Use a distribution with `glibc`
+
+If you are running inside of an embedded Tomcat runtime (e.g., Spring Boot), then some versions of `netty-tcnative-boringssl-static` will have conflicts and won't work. You must use gRPC 1.4.0 or later.
+
+Below are known to work version combinations:
+
+grpc-netty version | netty-code-http2 version | netty-tcnative-boringssl-static version
+------------------ | ------------------------ | ---------------------------------------
+1.0.0              | 4.1.3.Final              | 1.1.33.Fork19
+1.1.0              | 4.1.8.Final              | 1.1.33.Fork26
+1.2.0              | 4.1.8.Final              | 1.1.33.Fork26
+1.3.0              | 4.1.8.Final              | 1.1.33.Fork26
+1.4.0              | 4.1.11.Final             | 2.0.1.Final
+1.5.0              | 4.1.12.Final             | 2.0.5.Final
+1.6.1              | 4.1.14.Final             | 2.0.5.Final
+1.7.0              | 4.1.16.Final             | 2.0.6.Final
+
+### OkHttp
+If you are using gRPC on Android devices, you are most likely using `grpc-okhttp` transport.
+
+Find the dependency tree (e.g., `mvn dependency:tree`), and look for versions of:
+ - `io.grpc:grpc-okhttp`
+ - `com.squareup.okhttp:okhttp`
+
+If you don't have `grpc-okhttp`, you should add it as a dependency.
+
+If you have both `io.grpc:grpc-netty` and `io.grpc:grpc-okhttp`, you may also have issues. Remove `grpc-netty` if you are on Android.
+
+If you have `okhttp` version below 2.5.0, then it may not work with gRPC.
+
+It is OK to have both `okhttp` 2.x and 3.x since they have different group name and under different packages.
+
 # gRPC over plaintext
 
 An option is provided to use gRPC over plaintext without TLS. While this is convenient for testing environments, users must be aware of the security risks of doing so for real production systems.