Data Platform Architecture

Connecting SQuirreL SQL to HiveServer2 with Kerberos (Updated)

By
Kerberos-secured HiveServer2 environments require proper JAAS configuration, a valid Kerberos ticket and the correct Hive JDBC driver. This updated guide explains how to configure SQuirreL SQL with current Hive JDBC drivers, how Kerberos authentication works today and how to avoid the outdated manual classpath and script edits used in early Hadoop distributions. It also explains why HiveServer2 replaced the old Hive CLI, which bypassed security and could not handle many users, and shows how to use Beeline over the same JDBC URL, including running scripts in the background.

SQuirreL SQL remains a lightweight and reliable JDBC client for connecting to HiveServer2, especially in on-prem Kerberized clusters. While older Hadoop versions required assembling dozens of JAR dependencies manually, modern Hive distributions ship a shaded JDBC driver that simplifies configuration significantly.

Prerequisites for Kerberos Authentication

Before launching SQuirreL, ensure that you obtain a valid Kerberos ticket:

kinit [email protected]

Most Hadoop distributions automatically pick up krb5.conf from system paths (/etc/krb5.conf on Linux, /Library/Preferences on macOS).

If you need to override these settings, create a small JAAS file such as:

com.sun.security.jgss.initiate {
  com.sun.security.auth.module.Krb5LoginModule required
  useTicketCache=true
  renewTGT=true;
};

The entry name matters: with useSubjectCredsOnly=false, Java's GSS layer looks for com.sun.security.jgss.krb5.initiate or com.sun.security.jgss.initiate, so an entry with any other name is never used.

Then launch SQuirreL with the JAAS and Kerberos system properties:

export JAVA_OPTS="-Djava.security.auth.login.config=jaas.conf \
  -Djavax.security.auth.useSubjectCredsOnly=false"

If your SQuirreL launcher does not pick up JAVA_OPTS, add the two -D options to the java call in its start script (squirrel-sql.sh or squirrel-sql.bat).

Adding the Hive JDBC Driver

Use the current “shaded” Hive JDBC driver, which bundles most dependencies:

hive-jdbc-version-standalone.jar

This avoids the large dependency list required by older CDH 4.x and Hive 0.10 clients. Add the shaded JAR via:

  1. Open Drivers in SQuirreL.
  2. Click + to create a new driver.
  3. Enter a name, e.g., HiveServer2 Kerberos.
  4. Driver Class: org.apache.hive.jdbc.HiveDriver
  5. Extra Class Path → Add the shaded JAR.

Connection URL for Kerberos

Use the HiveServer2 Kerberos-enabled URL format:

jdbc:hive2://HOST:PORT/DB;principal=hive/[email protected]

If you are not using Kerberos, remove the principal portion:

jdbc:hive2://HOST:PORT/DB

No additional JAAS settings are required in non-Kerberos mode.

Java Version Compatibility

Kerberos authentication can fail if the client JVM version mismatches the server’s expectations. If you encounter GSS errors, try matching the JDK major version used on the HiveServer2 host.

Why HiveServer2 Replaced the Hive CLI

SQuirreL connects through HiveServer2 (HS2), and so should everything else. When Hive 0.11 introduced HS2, it broke with the old Hive CLI for good reasons, and they still hold today.

  • The CLI bypassed security. It talked straight to the Hive Metastore and launched jobs without a controlled service layer. No Kerberos impersonation, no authorization (Sentry back then, Ranger today), no consistent audit logs. HS2 enforces all of this in one central service.
  • The CLI was single user. HS2 added a stable Thrift service, many concurrent sessions, JDBC and ODBC support, and reliable Beeline connections.
  • Hive moved past MapReduce. With Tez, LLAP and Spark execution, HS2 became the gateway for every engine.

Today the Hive CLI is deprecated in all major distributions. A good practice is to remove execute permissions from the old hive binary so nobody bypasses HS2.

Using Beeline with HiveServer2

Beeline is the command-line client for HS2. It uses the same JDBC URL as SQuirreL:

beeline -u jdbc:hive2://HOST:PORT/DB -n USER -p PASSWORD

On a Kerberized cluster, add the principal= part from above to the URL. A shell alias saves typing:

alias hive2='beeline -u jdbc:hive2://HOST:PORT/DB -n $USER'

Run Beeline in the background

export HADOOP_CLIENT_OPTS="-Djline.terminal=jline.UnsupportedTerminal"
nohup beeline -u jdbc:hive2://HOST:PORT/DB -n USER \
  -p PASS -d org.apache.hive.jdbc.HiveDriver -f script.hql &

Run a query from the command line

beeline -u jdbc:hive2://HOST:PORT/DB -n USER -p PASS \
-e "select count(*) from (
  select a.sender, a.recipient, b.recipient as c
  from transactions a
  join transactions b on a.recipient = b.sender
  where a.time < b.time
    and b.time - a.time < 5
) q;"

Historical Context

Early Hadoop deployments (circa 2014) required:

  • modifying SQuirreL’s startup script
  • manually inserting 15-20 JAR files from CDH or HDP
  • hardcoding Kerberos system properties
  • using the Hive CLI, with Sentry and HDP 2.x docs as the security reference (today that is HiveServer2 and Apache Ranger)

Modern distributions ship shaded Hive JDBC drivers and rely on system-level Kerberos configuration, making the process far simpler and more reliable.

For reference, SQuirreL SQL is available at: https://squirrel-sql.sourceforge.io

Need help with distributed systems, backend engineering or data platforms? See my consulting services.

Alexander Alten

Alexander Alten

Founder of Scalytics, co-creator and PMC member of Apache Wayang, and author of KafScale. I write about Kafka, streaming, data platforms, IoT and AI agent infrastructure in production.