Linux and UNIX systems: DB2 Exit integration with S-TAP

The DB2 exit mechanism enables Guardium to pick up all DB2 traffic, whether encrypted or not and whether local or remote. It does not require A-TAP or K-TAP.

About this task

DB2 exit embeds a Guardium library into DB2 via the DB2_Exit mechanism. The DB2_Exit communicates directly with the Guardium S-TAP to forward all DB2 traffic, whether encrypted or not, and both local and remote. DB2 exit captures TCP as well as SHM traffic. Enabling UID chain with DB2 consumes much less CPU resource than KTAP and UID chain.

The DB2 exit library is a dynamic linked library. The DB2 database loads during database starts.

DB2 exit supports firewall (from STAP 10.1.2, also requires DB2 version 10.1 or later), terminate, and UID chain.

If there is no other Inspection Engine (IE) on the S-TAP that requires K-TAP, then you don't need to load K-TAP: set ktap_installed=0 in guard_tap.ini, or with GIM set ktap_enabled to no, in the GIM dialog for that STAP. You can upgrade the Linux OS and the STAP without being concerned about K-TAP module compatibility. However, if there is another IE in the S-TAP that requires the K-TAP module, you must ensure that a compatible K-TAP module is available when you upgrade your Linux version.

Limitations:
  • DB2 Exit does not support Guardium data masking (scrub/redact)
  • The Guardium firewall (V10.1.2 and later) requires DB2 version 10.1 or later
  • Stored Procedures: DB2 Exit monitors stored procedures. Since Guardium does not know what is in the stored procedure, SQL from inside the procedure is not captured.
When upgrading STAP and DB2
  1. Stop the DB2.
  2. Upgrade STAP.
  3. Copy latest db2 exit lib to DB2 commexit directory.
  4. Start the DB2.
When patching STAP
  1. Stop the DB2.
  2. Patch the DB2 Database
  3. In case the DB2 configuration was overwritten you need to re-enable using db2 UPDATE DBM CFG USING COMM_EXIT_LIST libguard_db2_exit_64
  4. Start the DB2.

The Guardium installer has two versions of the DB2 EXIT library: 32- and 64-bit. Use the one that matches your installed DB2. Both versions are in the Guardium installation directory in the lib sub-directory. On Linux servers, the 64-bit version is in lib64.

DB2 versions V101FP4 and V105FP3 support UID chain.

Library names

  • libguard_db2_exit_32.so
  • libguard_db2_exit_64.so

Procedure

  1. Determine the DB2's bitwise. Log in as root and run db2level. The output is similar to
    DB21085I Instance db2inst1 uses 64 bits and DB2 code release SQL09070, with level identifier 08010107
  2. Locate the communication buffer exit library location (DB2PATH)
    1. Log in as DB2 user trip
    2. In the DB2 clp, run db2 get database manager configuration
    3. In the output, look for default database path: Default database path
      (DFTDBPATH) = /DB2/trip
      DFTDBPATH is the value you need for the environment parameter DB2PATH.
  3. Set up the DB2 Exit library.
    1. Log in as user root
    2. Set the environment parameter: # export DB2PATH=/DB2/trip
    3. Create the directory by entering one of these commands. (This is done only the first time the library is installed, as the directory does not exist)
      • mkdir $DB2_PATH/sqllib/security/plugin/commexit
      • mkdir $DB2_PATH/sqllib/security64/plugin/commexit
    4. Change permission: # chown ${DB2 user}:${DB2 group} $DB2PATH/security64/plugin/commexit
    5. Copy Guardium's libguard file to commexit by entering one of: 
      # cp /opt/IBM/guardium/module/modules/STAP/libguard_db2_exit_64.so $DB2PATH/security64/plugin/commexit
# cp /opt/IBM/guardium/module/modules/STAP/libguard_db2_exit_64.so $DB2PATH/security/plugin/commexit
      where $DB2_PATH is the db2 installation directory.

      If the copy fails with the error ....: Text file busy, remove the file from the target directory, make a copy and repeat.

    6. Change permission by entering one of: 
      # chown ${DB2 user}:${DB2 group} $DB2PATH/security64/plugin/commexit/libguard_db2_exit_64.so
# chown ${DB2 user}:${DB2 group} $DB2PATH/security/plugin/commexit/libguard_db2_exit_64.so
  4. Add the DB2 instance to the Guardium group. The Guardium group is created during S-TAP installation. This requirement increases the security of shared memory regions that are created by the S-TAP.
    1. If DB2 user is 'trip', verify if 'trip' has been authorized already. Use guardctl under the ATAP folder.
      # /opt/IBM/guardium/module/modules/ATAP/10.1.0_r88469_1-1468880597/files/bin/guardctl is-user-authorized trip
User 'trip' is authorized.
    2. If the user trip is not authorized, authorize it now:
      # /opt/IBM/guardium/module/modules/STAP/10.1.0_r88469_1-1468880597/guardctl authorize-user trip
guardctl authorize-user guardium
User 'guardium' is already authorized.
  5. Enable db2 exit in DB2 (so it will send the SQL traffic to the S-TAP).
    1. Log in as db2 user and use the db2 clp commands to enable:
      db2 UPDATE DBM CFG USING COMM_EXIT_LIST libguard_db2_exit_64
    2. Once enabled, db2 sends SQL traffic to the STAP. Verify if db2 exit is successfully enabled by entering
      db2 get database manager configuration
      The output should include
      Communication buffer exit library list (COMM_EXIT_LIST) = libguard_db2_exit_64
  6. Restart DB2.
    1. Login as db2 user and enter:
      # db2stop force; ipclean; db2start
    2. Verify the response includes:
      The DB2START command completed successfully
    3. If the restart was unsuccessful, stop db2 exit to clear any warnings in DB2 by entering:
      db2 UPDATE DBM CFG USING COMM_EXIT_LIST NULL
      then restart by entering
      db2 restart
    4. If not, check the log file for clues: ~/sqllib/db2dump/db2diag.log
  7. If A-TAP is not activated: Configure STAP for DB2_EXIT. (If A-TAP is activated, continue with 8)
    1. Configure the IE for DB2 as usual either in the guard_tap.ini or via GIM. For ease of identification, set db_type=db2.
    2. Unix-type platforms only: Verify that the parameter db_install_dir for DB2_EXIT IE is set to the value of $DB2_HOME or $HOME of DB2 environment variable.
    3. Windows only: Add the instance_name=Service_name. Determine the service name by using the db2tap utility in the S-TAP installation folder, or from the control panel. Set the instance name to the portion of the service name that follows the second dash ( - ) delimiter. For example, if the service name in the control panel is DB2 - DB2COPY1 - DB2-01-0, set INSTANCE_NAME to DB2-01-0
    4. Restart S-TAP with new configuration.
  8. If A-TAP was activated when you started.
    1. Stop the DB2 by entering
      # db2stop force; ipclean
    2. Deactivate the A-TAP by entering
      # /opt/IBM/guardium/module/modules/ATAP/10.1.0_r88469_1-1468880597/files/bin/guardctl db_instance=<db_instance> [--force-action=yes ] deactivate
    3. Configure the IE for DB2 as usual either in the guard_tap.ini or via GIM . For ease of identification, set db_type=db2.
    4. Unix-type platforms only: Verify that the parameter db_install_dir for DB2_EXIT IE is set to the value of $DB2_HOME or $HOME of DB2 environment variable.
    5. Windows only: Add the instance_name=Service_name. Determine the service name by using the db2tap utility in the S-TAP installation folder, or from the control panel. Set the instance name to the portion of the service name that follows the second dash ( - ) delimiter. For example, if the service name in the control panel is DB2 - DB2COPY1 - DB2-01-0, set INSTANCE_NAME to DB2-01-0
    6. Restart S-TAP with new configuration.
  9. Set up Zones/WPARs.
    1. Copy the S-TAP to the Zones/WPARs.
      1. On the master/global Zone/WPAR: (assuming Guardium software is installed on the master Zone/WPAR under /usr/local/guardium, and there exists a writable directory /usr/local with enough free space on the sub-Zone/sub-WPAR), enter: 
        cd /usr/local
tar -cvf - guardium | ssh root@subzonehost 'cd /usr/local && tar -xvf -'
      2. On Zone/WPARs, add DB2_EXIT IE in the guard_tap.ini with:
        • -- ktap_installed = 0
        • -- tap_run_as_root = 1
        • -- tap_ip = zones/WPAR local IP address
        • No other IEs should be specified in order to start S-TAP on the zone.
    2. Create /var/guard directory.
    3. Start the S-TAP.
      • on WPARs, manually copy/add the utap server entry in inittab file
      • On Solaris zone use the command svcadm -v enable guard_utap
    4. If relevant, configure the tap_debug_output_level.
      Note: Impact of debug logging on the database server: The logging is done by the DB2 Exit module. This module is loaded by DB2 and the diagnostics are piped to the log files. Since the database server is performing the actual logging, there is some impact, depending on how much logging is done. Remember that S-TAP logging is meant to be used as part of troubleshooting and not a standard feature, so the impact is only when logging is turned on.
      • When S-TAP log level = 10, debug info is logged into both S-TAP log and db2_exit log (db2diag.log)
      • When S-TAP log level = 11, debug info is only logged into db2_exit log (db2diag.log)
    Note: In a WPAR environment when running discovery, if the instance name is the same on both slave zone and master zone, then only one Inspection Engine entry is added that belongs to the master zone.
    Note: When changing tap_identifier in the inspection engine, in order for the change to take effect with Informix exit or DB2 exit, the database must be restarted. With ATAP enabled, the database has to be stopped, ATAP deactivated, reactivated, and finally the database started again. For Informix exit, stop ifxguard, then restart the database, then start ifxguard.
Parent topic: Linux and UNIX systems: Using Exit libraries