Skip Navigation

Preferences

Kerberos

Where KafkIO finds its krb5 configuration for GSSAPI clusters, and setting the default realm and KDC host directly.

To connect to a cluster that uses Kerberos (SASL type GSSAPI), KafkIO needs to know your Kerberos realm and where its KDC (key distribution centre) is. Usually that comes from a krb5.conf file your administrator gives you, and KafkIO finds it on its own. The Kerberos page of Preferences is for when it doesn't: the file is somewhere else, or you have no file and just want to name the realm and KDC. If you don't use Kerberos, leave this page blank.

Open File ▸ Preferences (see Opening Preferences) and select Kerberos.

The KafkIO Preferences window with Kerberos selected in the list on the left (General, Network, Kafka, Kerberos). The Kerberos page has a Kerberos configuration section with three fields: Kerberos configuration file (java.security.krb5.conf) set to C:\kerberos\krb5.conf, with a clear button and a folder button, and the note: If left blank, the default location is used. If the KRB5_CONFIG environment variable is set, that will be used (as long as this field is not set). Default realm (java.security.krb5.realm) and KDC host (java.security.krb5.kdc) are empty, showing Leave blank for default, each with an information icon and the note: Leave blank to use the value from the KRB5 config file or system defaults. Save and Cancel are at the bottom right. 1 2 3 4
The Kerberos preferences, pointing KafkIO at a krb5.conf file in a non-standard place.
  1. The Kerberos page of Preferences.
  2. Kerberos configuration file: the krb5.conf to use. Type a path or pick the file with the folder button; the ✖ clears it.
  3. Default realm, for example EXAMPLE.COM.
  4. KDC host: the KDC's host name or address.

The small grey name under each label is the Java system property KafkIO sets from it. Each field is optional: leave it blank and that property isn't set, so Java falls back to its normal behaviour.

Warning: these settings are applied when KafkIO starts. After you change any of them and select Save, a Restart required message says Kerberos configuration changed: close and reopen KafkIO before you connect, or the old settings stay in use.

The krb5 configuration file

A krb5.conf file (called krb5.ini on Windows by convention) describes your realms, their KDCs and other Kerberos options. KafkIO decides which one to use when it starts, in this order:

  1. The Kerberos configuration file preference, if it's filled in.
  2. Otherwise the file named by the KRB5_CONFIG environment variable, if it's set. This is the variable MIT Kerberos tools such as kinit use, so if your machine is already set up for them, KafkIO follows along without any preference.
  3. Otherwise Java's default location: krb5.ini in the Windows folder (usually C:\Windows\krb5.ini) on Windows, and /etc/krb5.conf on Linux and macOS.

So the preference only matters when your file isn't where Java or KRB5_CONFIG would find it, or when you want KafkIO to use a different file from the rest of your tools. On Windows you can paste the path with backslashes as it is (this field is a file path, unlike the JAAS config, which needs forward slashes). A minimal file looks like this:

[libdefaults]
    default_realm = EXAMPLE.COM

[realms]
    EXAMPLE.COM = {
        kdc = kdc.example.com
    }

KafkIO doesn't check that the file exists or is valid when you save. A wrong path shows up later, as an error when you connect to a Kerberos cluster.

Default realm and KDC host

If you have no krb5.conf and your setup is simple (one realm, one KDC), you can name them here instead: Default realm (realms are usually upper case, such as EXAMPLE.COM) and KDC host (such as kdc.example.com). When set, they override the realm and KDC from the configuration file. Anything more involved, such as several realms or cross-realm trust, belongs in a krb5.conf file.

Note: fill in both fields or neither. Java refuses a realm without a KDC (or the other way round), and the Kerberos login then fails with an error saying that java.security.krb5.kdc and java.security.krb5.realm must both be set or neither.

Using it with a GSSAPI cluster

These preferences apply to the whole of KafkIO, every cluster at once; what differs per cluster is set in the cluster's properties. To connect to a Kerberos-secured cluster:

  1. Make sure KafkIO can find your realm and KDC

    Usually nothing to do: your krb5.conf is in the default place or in KRB5_CONFIG. Otherwise set the fields above, select Save and restart KafkIO.

  2. Set up the cluster's security

    In the cluster's Kafka Security tab, choose a SASL security type, SASL type GSSAPI, start from the GSSAPI (Kerberos) example, and fill in your keytab, principal and the brokers' service name. The details are in Security & Authentication (and Kerberos service name).

  3. Test the connection

    Use Test Connection in the cluster dialog, or just connect. If it fails, see Troubleshooting Connections.

To confirm which settings KafkIO picked up, look in its log: at startup it writes a line for each property it sets, such as Set java.security.krb5.conf=C:\kerberos\krb5.conf (with (from KRB5_CONFIG env var) added when the path came from the environment variable). No line means the property wasn't set and Java's defaults apply. See File Locations for where the logs are.