JVM SSL Debugging in Hadoop

Luke Hebert

- 2 minutes read - 323 words

When a Hadoop or Cloudera service drops a TLS connection, the default JVM logs rarely tell you which certificate, cipher, or protocol step failed. The javax.net.debug system property gives you a full handshake trace, and this guide walks through setting it, narrowing the output, and reading the results.

Setting the Debug Flag

The property you want is -Djavax.net.debug. You can scope it to ssl for a focused trace or set it to all for maximum verbosity. In a Hadoop environment, the flag goes into the standard HADOOP_OPTS or HADOOP_CLIENT_OPTS variables:

export HADOOP_OPTS="-Djavax.net.debug=ssl"
export HADOOP_CLIENT_OPTS="-Djavax.net.debug=all"

If you are running a standalone JVM or a service that reads JVMFLAGS, the same property applies:

JVMFLAGS="-Djavax.net.debug=ssl"

Narrowing the Output

The ssl level can still produce a lot of lines. If you only care about the handshake exchange, use the more specific form:

-Djavax.net.debug=ssl:handshake:verbose

This prints the ClientHello, ServerHello, certificate chains, and cipher negotiation without the surrounding session-management noise.

Cloudera-Specific Note

In a Cloudera Manager deployment, you can append the flag to the service-level Java options without editing shell profiles directly:

CSD_JAVA_OPTS="-Djavax.net.debug=ssl:handshake:verbose"

Cloudera Manager will merge this value with the existing JAVA_OPTS for the target service, so you do not need to restart the entire cluster.

Reading the Output

Once the flag is active, look for these markers in the log:

  • Consuming server certificate and Producing client certificate confirm which side presented what.
  • No cipher suites in common means the server and client disagree on supported ciphers.
  • Received fatal alert: handshake_failure usually points to a protocol version mismatch (TLS 1.0 vs 1.2) or a missing intermediate certificate.
Important

The debug output includes certificate details and, in some cases, key exchange material. Treat the log file as sensitive and restrict access accordingly.

Turning It Off

Remove the -Djavax.net.debug entry from the relevant environment variable or CSD_JAVA_OPTS and restart the service. Leaving it on in production adds noticeable I/O overhead and can slow down high-throughput connections.