Set up for the GSSAPI plug-in

This section describes how to configure the server to use the Authentication Service for IBM DB2 GSSAPI plug-in.

  1. As root, use the adjoin command to join the UNIX DB2 server machine and each UNIX DB2 client using GSSAPI to the same Active Directory domain. See the Administrator’s Guide for Windows for the adjoin command options. Be careful to join the appropriate Active Directory organizational unit and Centrify zone for your configuration.

    Note:   You must have the account name and password for an Active Directory user that has administrator privileges on the Active Directory domain controller to use adjoin. If you do not specify the account name in the adjoin command line you will be prompted to enter the administrator password.

  2. As root, use the adkeytab command to create a Kerberos service account for the DB2 instance and generate a keytab file. (The adkeytab tool is included in the Server Suite package; see /usr/sbin.)

    The following example creates the account for the database instance db2inst1 in the Users container in the currently joined domain. The account resides on a DB2 server with host name (not fully-qualified) hostname, and generates a keytab file (db2inst1.keytab) in the $INSTHOME directory. Substitute your own instance, host, and keytab file names as appropriate.

    adkeytab -n -c CN=Users -u Administrator -K \
    $INSTHOME/db2inst1.keytab -P db2inst1/hostname db2inst1

    If you had wanted to create the account in a different domain than the currently joined domain, you would have used the adkeytab -d option.

    This example uses the domain controller’s Administrator account to generate the keytab file and requires root to know the administrator password. If you do not know the administrator password, use the -u option to specify any user with administrator privileges on the Active Directory domain controller.

    The adkeytab command always sets the password of the domain account to a random value regardless of whether the account already exists. Use the following command to change the Active Directory password. This example uses db2inst1 for the DB2 instance name and password for the password string for the instance user’s account in Active Directory. Substitute your own instance and password as appropriate.

    adkeytab -C db2inst1 -w password

    Note:   If there is a local user (for example, in /etc/passwd or /etc/shadow) with the same account name as the instance user, the adkeytab command does not change the local password.

    In both examples, you are prompted for the Active Directory Administrator password before the command is executed.

    After you have generated the keytab file with the adkeytab command, do not move or delete it. If you do, the agent will not renew the keytab.

    In addition, set the service account password in Active Directory to “never expire.”

  3. Open the file /etc/centrifydc/user.ignore and add the instance user to the end of the file. (This file contains user names that are always treated as local—for example, root, mail, and daemon—when looking up user information.) This allows the instance user to log in as a local user to perform maintenance tasks.

  4. Set appropriate permissions to protect the keytab file generated in Step 2.

    For the GSSAPI plug-in to work, the keytab file must be made readable by the DB2 instance owner. In addition, because the keytab file contains sensitive information such as the secret key associated with the DB2 instance service account, it should be properly protected. Execute the following commands as root to achieve this. The following example uses db2inst1 for the DB2 instance name and db2grp1 for the primary group of the instance user. Substitute your own instance and group names as appropriate.

    chmod 600 $INSTHOME/db2inst1.keytab
    chown db2inst1:db2grp1 $INSTHOME/db2inst1.keytab
  5. Set up the DB2 environment variables to use the new keytab file. By default, DB2 uses the keytab file defined in the KRB5_KTNAME environment variable for authentication. The default is /etc/krb5.keytab. The following procedures describe how to set the variable for different UNIX shells. Perform the action as the DB2 instance owner, and replace db2inst1 with your actual instance name.

    For Bourne, Korn and bash shell users, add the following lines to $INSTHOME/sqllib/userprofile:

    export KRB5_KTNAME

    For C shell users, add the following line to $INSTHOME/sqllib/usercshrc:

    setenv KRB5_KTNAME $INSTHOME/db2inst1.keytab

    By default, DB2 filters out all user environment variables except for those prefixed with DB2 or db2. To pass the value stored in KRB5_KTNAME to the DB2 instance, the variable must be added to the DB2ENVLIST parameter. To do so, run the following command as the DB2 instance user:


    Note:   Before executing db2set, you must either:

    • Log out after updating the userprofile and usercshrc files to set the KRB5_KTNAME environment and log back in again; or

    • Set the environment variable in your shell before issuing the command.

  6. On some platforms, the DB2 server may not be able to start due to the Kerberos library conflict between the system and DirectControl. The centrifydc_db2gsskrb5 plugin has to be linked against the one from DirectControl.

    To work around this issue, Centrify recommends that you add the library search path and make it readable by DB2 server. Please revise the changes above and do the modification as below:

    Note:   The environment variable name and value for library search path is platform specific, and the example below is for Linux x86_64.

    For Bourne, Korn and bash shell users, add the following lines to $INSTHOME/sqllib/userprofile:

    export KRB5_KTNAME
    export LD_LIBRARY_PATH

    For C shell users, add the following line to $INSTHOME/sqllib/usercshrc:

    setenv KRB5_KTNAME $INSTHOME/db2inst1.keytab
    setenv LD_LIBRARY_PATH=/usr/share/centrifydc/lib64:/usr/share/centrifydc/kerberos/lib64:$LD_LIBRARY_PATH

    Run the following command as the DB2 instance user: