This document outlines the steps to configure IBM Data Management Console (DMC) to connect securely to a Db2 database using Kerberos authentication.

1. Install and Configure Kerberos Client on DMC Server

Install the Kerberos client:

sudo apt install krb5-user

During installation, you will be prompted to enter:

• Default Kerberos realm: e.g., EXAMPLE.COM (must be uppercase)
• Kerberos server (KDC): e.g., kdc.example.com
• Admin server: usually the same as the KDC

Configure /etc/krb5.conf

Ensure your /etc/krb5.conf file reflects the correct realm and KDC details.

Example:

[libdefaults]
    default_realm = EXAMPLE.COM
    dns_lookup_realm = false
    dns_lookup_kdc = false

[realms]
    EXAMPLE.COM = {
        kdc = kerberos-console-server1.example.com
        admin_server = kerberos-console-server1.example.com
    }

[domain_realm]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

2. Update JVM Options for DMC

Add the following option to the DMC JVM configuration to allow Kerberos to access credentials:

-Djavax.security.auth.useSubjectCredsOnly=false

File: ibm-datamgmtconsole/wlp/usr/servers/dsweb/jvm.options

Example:

-Xms512m
-Xmx2048m
-Duser.language=en
-Duser.region=US
-Dclient.encoding.override=UTF-8
-Djava.awt.headless=true
-Ddb2.jcc.charsetDecoderEncoder=3
-Dfile.encoding=UTF-8
-Dsun.jnu.encoding=UTF-8
-Djavax.security.auth.useSubjectCredsOnly=false

3. Create the Db2 Service Principal in Kerberos

On the Kerberos server, you need to create a Kerberos principal for the Db2 user that will be added to DMC and used to connect to the Db2 database.

💡 Note: The Kerberos principal should correspond to a valid OS user on the Db2 server with the necessary privileges to connect to and monitor the database. If the user does not already exist, create it. This user doesn't have to be the instance owner (e.g., db2inst1); it can be any user with appropriate permissions in Db2.

1. Open the Kerberos administrative shell:

   sudo kadmin.local
   

2. Create the service principal for the Db2 user using the fully qualified hostname and correct realm:

   addprinc -randkey db2inst1/db2server.example.com@EXAMPLE.COM
   

   • This creates the principal with a randomly generated key (no password login).
   • Replace db2server.example.com and EXAMPLE.COM with your actual FQDN and Kerberos realm.

4. Obtain a Kerberos Ticket on the DMC Server

Use the kinit command to authenticate and get a Kerberos ticket for db2inst1.

kinit db2inst1@EXAMPLE.COM

You will be prompted to enter the Kerberos password.

Verify the ticket:

klist

Example output:

Ticket cache: FILE:/tmp/krb5cc_0
Default principal: db2inst1@EXAMPLE.COM

Valid starting       Expires              Service principal
09/15/2025 06:50:24  09/15/2025 16:50:24  krbtgt/EXAMPLE.COM@EXAMPLE.COM
    renew until 09/16/2025 06:50:20

The file /tmp/krb5cc_0 stores the cached Kerberos ticket.

5. Set the Ticket Cache Location for DMC

DMC needs to know where to find the Kerberos ticket. Set the KRB5CCNAME environment variable in the DMC configuration.

File: ibm-datamgmtconsole/Config/dswebserver_override.properties

Add the following line:

KRB5CCNAME=/tmp/krb5cc_0

Example:

cat ibm-datamgmtconsole/Config/dswebserver_override.properties | grep KRB5CCNAME
KRB5CCNAME=/tmp/krb5cc_0

6. Restart the DMC Console

After setting the environment variable, restart the DMC application:

ibm-datamgmtconsole/bin/restart.sh

7. Connect to Kerberos-Enabled Db2 from DMC

1. Open the DMC web interface.

2. Log in with your DMC user credentials.

3. Go to Repository or Connection Setup.

4. Under Security and Credentials, choose:

   • Security Type: Kerberos

   • Authentication Method:

     • Use cached ticket-granting ticket (recommended)
     • Or provide username and password (if required)

Important Notes:

• If using cached ticket-granting ticket: You must manually log in to the DMC server and run kinit to obtain a valid Kerberos ticket. This ticket will need to be renewed manually whenever it expires. After renewing the ticket, you can proceed to use DMC.

• If providing username and password: DMC will automatically renew the Kerberos ticket as needed, so no manual renewal is required.

8. Troubleshooting Connection Issues

If the Kerberos-authenticated connection from DMC to Db2 fails, follow these steps to identify and resolve the issue:

1. Monitor DMC Logs in Real Time

Use the following command to tail the DMC system log:

tail -n 0 -f ibm-datamgmtconsole/logs/DS_System.0

While this command is running, go back to the DMC interface and retry the connection test. Any errors related to Kerberos authentication, ticket validation, or Db2 connectivity will be logged here.

2. Check for Common Issues

• Invalid or expired Kerberos ticket Run klist to verify if a valid ticket exists. If not, re-run kinit.

• Incorrect KRB5CCNAME value Ensure that the KRB5CCNAME environment variable in dswebserver_override.properties points to the correct ticket cache file.

• Missing or incorrect keytab/principal Make sure the keytab file used includes the correct service principal and is readable by the DMC process.

• DNS or FQDN mismatch The hostname used in the Kerberos principal must match the server's FQDN as seen by the Kerberos client.

• Clock skew Ensure the system time on the DMC server and KDC are in sync (use NTP if necessary).

9. Common Issues

9.1 Issue: HWCREP0011E: Failed to connect to the repository database

Error Message:

HWCREP0011E: Failed to connect to the repository database. Unexpected Throwable caught: empty realm part not allowed. ERRORCODE=-4228, SQLSTATE=null

Cause:

This error typically occurs when the DB2_KRB5_PRINCIPAL environment variable is not set, or it is incorrectly configured on the Db2 server. Without this variable, Db2 does not know which Kerberos principal to use for authentication, resulting in a malformed or incomplete realm during connection.

Solution:

Set the DB2_KRB5_PRINCIPAL variable in the /etc/environment file on the Db2 server with the correct service principal name in the following format:

<instance_name>/<fully_qualified_hostname>@<REALM>

Example:

db2inst1@db2-enterprise1:~$ cat /etc/environment
PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin"
DB2_KRB5_PRINCIPAL=db2inst1/db2-enterprise1.example.com@EXAMPLE.COM

After updating the file:

1. Reboot the server or log out and log back in as the instance user (db2inst1) to apply the change.

2. Restart the Db2 instance:

   db2stop force
   db2start
   

9.2 Issue: org.ietf.jgss.GSSException is thrown when attempting to get a ticket from JGSS. The error details include:

ERRORCODE=-4225, SQLSTATE=null.

Cause: This error is typically caused by an incorrect KRB5CCNAME environment variable pointing to the wrong Kerberos ticket cache file. For example, it may be set to /tmp/krb5cc_root instead of the correct path.

Resolution:

1. Verify the actual Kerberos ticket cache file location using:

   klist
   

   You should see output like:

   Ticket cache: FILE:/tmp/krb5cc_0
   

2. Update the KRB5CCNAME property in the DMC configuration file ibm-datamgmtconsole/Config/dswebserver_override.properties to point to the correct cache file:

   KRB5CCNAME=/tmp/krb5cc_0
   

3. Restart the DMC server to apply the change:

   ibm-datamgmtconsole/bin/restart.sh
   

Notes

• The Kerberos principal used for connecting must match the principal in the keytab.
• The hostname must match what was used when creating the principal.
• The Kerberos ticket must be valid at the time of connection.
• Ensure KRB5CCNAME is always pointing to the valid ticket cache file.