You can configure Microsoft Windows client applications to connect to a Greenplum Database system that is configured to authenticate with Kerberos.

When a Greenplum Database system is configured to authenticate with Kerberos, you can configure Kerberos authentication for the Greenplum Database client utilities gpload and psql on a Microsoft Windows system. The Greenplum Database clients authenticate with Kerberos directly.

This section contains the following information.

These topics assume that the Greenplum Database system is configured to authenticate with Kerberos. For information about configuring Greenplum Database with Kerberos authentication, refer to Using Kerberos Authentication.

Parent topic: Configuring Client Authentication

Installing and Configuring Kerberos on a Windows System

The kinit, kdestroy, and klist MIT Kerberos Windows client programs and supporting libraries are installed on your system when you install the Greenplum Database Client and Load Tools package:

  • kinit - generate a Kerberos ticket
  • kdestroy - destroy active Kerberos tickets
  • klist - list Kerberos tickets

You must configure Kerberos on the Windows client to authenticate with Greenplum Database:

  1. Copy the Kerberos configuration file /etc/krb5.conf from the Greenplum Database master to the Windows system, rename it to krb5.ini, and place it in the default Kerberos location on the Windows system, C:\ProgramData\MIT\Kerberos5\krb5.ini. This directory may be hidden. This step requires administrative privileges on the Windows client system. You may also choose to place the /etc/krb5.ini file in a custom location. If you choose to do this, you must configure and set a system environment variable named KRB5_CONFIG to the custom location.

  2. Locate the [libdefaults] section of the krb5.ini file, and remove the entry identifying the location of the Kerberos credentials cache file, default_ccache_name. This step requires administrative privileges on the Windows client system.

    This is an example configuration file with default_ccache_name removed. The [logging] section is also removed.

    1. [libdefaults]
    2.  debug = true
    3.  default_etypes = aes256-cts-hmac-sha1-96
    4.  default_realm = EXAMPLE.LOCAL
    5.  dns_lookup_realm = false
    6.  dns_lookup_kdc = false
    7.  ticket_lifetime = 24h
    8.  renew_lifetime = 7d
    9.  forwardable = true
    11. [realms]
    12.  EXAMPLE.LOCAL = {
    13.   kdc =bocdc.example.local
    14.   admin_server = bocdc.example.local
    15.  }
    17. [domain_realm]
    18.  .example.local = EXAMPLE.LOCAL
    19.  example.local = EXAMPLE.LOCAL

  3. Set up the Kerberos credential cache file. On the Windows system, set the environment variable KRB5CCNAME to specify the file system location of the cache file. The file must be named krb5cache. This location identifies a file, not a directory, and should be unique to each login on the server. When you set KRB5CCNAME, you can specify the value in either a local user environment or within a session. For example, the following command sets KRB5CCNAME in the session:

    1. set KRB5CCNAME=%USERPROFILE%\krb5cache

  4. Obtain your Kerberos principal and password or keytab file from your system administrator.

  5. Generate a Kerberos ticket using a password or a keytab. For example, to generate a ticket using a password:

    1. kinit [<principal>]

    To generate a ticket using a keytab (as described in Creating a Kerberos Keytab File):

    1. kinit -k -t <keytab_filepath> [<principal>]

  6. Set up the Greenplum clients environment:

    1. set PGGSSLIB=gssapi
    2. "c:\Program Files\Greenplum\greenplum-clients\greenplum_clients_path.bat"

Running the psql Utility

After you configure Kerberos and generate the Kerberos ticket on a Windows system, you can run the Greenplum Database command line client psql.

If you get warnings indicating that the Console code page differs from Windows code page, you can run the Windows utility chcp to change the code page. This is an example of the warning and fix:

  1. psql -h prod1.example.local warehouse
  2. psql (9.4.20)
  3. WARNING: Console code page (850) differs from Windows code page (1252)
  4.  8-bit characters might not work correctly. See psql reference
  5.  page "Notes for Windows users" for details.
  6. Type "help" for help.
  8. warehouse=# \q
  10. chcp 1252
  11. Active code page: 1252
  13. psql -h prod1.example.local warehouse
  14. psql (9.4.20)
  15. Type "help" for help.

Creating a Kerberos Keytab File

You can create and use a Kerberos keytab file to avoid entering a password at the command line or listing a password in a script file when you connect to a Greenplum Database system, perhaps when automating a scheduled Greenplum task such as gpload. You can create a keytab file with the Java JRE keytab utility ktab. If you use AES256-CTS-HMAC-SHA1-96 encryption, you need to download and install the Java extension Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for JDK/JRE from Oracle.

Note

You must enter the password to create a keytab file. The password is visible onscreen as you enter it.

This example runs the Java ktab.exe program to create a keytab file (-a option) and list the keytab name and entries (-l -e -t options).

  1. C:\Users\dev1>"\Program Files\Java\jre1.8.0_77\bin"\ktab -a dev1
  2. Password for dev1@EXAMPLE.LOCAL:<your_password>
  3. Done!
  4. Service key for dev1 is saved in C:\Users\dev1\krb5.keytab
  6. C:\Users\dev1>"\Program Files\Java\jre1.8.0_77\bin"\ktab -l -e -t
  7. Keytab name: C:\Users\dev1\krb5.keytab
  8. KVNO Timestamp Principal
  9. ---- -------------- ------------------------------------------------------
  10.  4 13/04/16 19:14 dev1@EXAMPLE.LOCAL (18:AES256 CTS mode with HMAC SHA1-96)
  11.  4 13/04/16 19:14 dev1@EXAMPLE.LOCAL (17:AES128 CTS mode with HMAC SHA1-96)
  12.  4 13/04/16 19:14 dev1@EXAMPLE.LOCAL (16:DES3 CBC mode with SHA1-KD)
  13.  4 13/04/16 19:14 dev1@EXAMPLE.LOCAL (23:RC4 with HMAC)

You can then generate a Kerberos ticket using a keytab with the following command:

  1. kinit -kt dev1.keytab dev1

or

  1. kinit -kt %USERPROFILE%\krb5.keytab dev1

Example gpload YAML File

When you initiate a gpload job to a Greenplum Database system using Kerberos authentication, you omit the USER: property and value from the YAML control file.

This example gpload YAML control file named test.yaml does not include a USER: entry:

  1. ---
  2. VERSION: 1.0.0.1
  3. DATABASE: warehouse
  4. HOST: prod1.example.local
  5. PORT: 5432
  7. GPLOAD:
  8.    INPUT:
  9.     - SOURCE:
  10.          PORT_RANGE: [18080,18080]
  11.          FILE:
  12.            - /Users/dev1/Downloads/test.csv
  13.     - FORMAT: text
  14.     - DELIMITER: ','
  15.     - QUOTE: '"'
  16.     - ERROR_LIMIT: 25
  17.     - LOG_ERRORS: true
  18.    OUTPUT:
  19.     - TABLE: public.test
  20.     - MODE: INSERT
  21.    PRELOAD:
  22.     - REUSE_TABLES: true

These commands run kinit using a keytab file, run gpload.bat with the test.yaml file, and then display successful gpload output.

  1. kinit -kt %USERPROFILE%\krb5.keytab dev1
  3. gpload.bat -f test.yaml
  4. 2016-04-10 16:54:12|INFO|gpload session started 2016-04-10 16:54:12
  5. 2016-04-10 16:54:12|INFO|started gpfdist -p 18080 -P 18080 -f "/Users/dev1/Downloads/test.csv" -t 30
  6. 2016-04-10 16:54:13|INFO|running time: 0.23 seconds
  7. 2016-04-10 16:54:13|INFO|rows Inserted = 3
  8. 2016-04-10 16:54:13|INFO|rows Updated = 0
  9. 2016-04-10 16:54:13|INFO|data formatting errors = 0
  10. 2016-04-10 16:54:13|INFO|gpload succeeded

Issues and Possible Solutions

  • This message indicates that Kerberos cannot find your Kerberos credentials cache file:

    1. Credentials cache I/O operation failed XXX
    2. (Kerberos error 193)
    3. krb5_cc_default() failed

    To ensure that Kerberos can find the file, set the environment variable KRB5CCNAME and run kinit.

    1. set KRB5CCNAME=%USERPROFILE%\krb5cache
    2. kinit

  • This kinit message indicates that the kinit -k -t command could not find the keytab.

    1. kinit: Generic preauthentication failure while getting initial credentials

    Confirm that the full path and filename for the Kerberos keytab file is correct.