Connecting to the IBM Social Media Analytics Database (DB2)

Technote (FAQ)


Question

Can I access the underlying DB2 database behind Social Media Analytics so I can run additional analytics in tools such as SPSS Modeler or Cognos Business Intelligence?

Cause

Social Media Analytics provides DB2 views for integrating analytics into other applications. Instructions for how to connect to the DB2 instance on the Social Media Analytics server when DB2 is configured to use SSL encryption are not included in the product documentation and may require assistance from system administrators or IBM.

Answer

The DB2 instance used to store IBM Social Media Analytics (SMA) results may be used by other products. While connecting to DB2 over an unencrypted connection is relatively straightforward and well-documented elsewhere, when DB2 connections are encrypted using SSL, connectivity is more difficult. These instructions will describe the steps necessary to connect to an IBM Social Media Analytics server DB2 instance if it is encrypted using SSL.

First, collect from the system administrator or IBM the following information about the connection to the DB2 database. Most of these values will be referred to later in the instructions:
1) DB2 Server Name/IP (<SMA_DB2SERVER>):
2) DB2 Server Port (<SMA_DB2PORT>):
3) Username (<DB2_USER>):
4) Password (<DB2_PASSWORD>):
5) Project Name:
6) Project Database Name (<PROJECT_DB>):
7) The ARM file (the Signer Certificate which is an ASCII text file containing the public key needed to connect to the DB2 server)

TROUBLESHOOTING NOTES:

    1. Verify that the local network does not block the access to DB2 Server by issuing the command tracert <DB2 Server Name/IP. At least one valid hop should be received. Alternatively, run telnet <DB2 Server Name/IP> <DB2 Server Port> and if DB2 server host is reachable, a blank screen should appear.
    2. If using a 3rd party application, for example SPSS modeler used as a client to access the SMA database, make sure 32/64bit DB2 client and GSK versions are properly lined up with the 3rd party application.
    3. If the db2 cli tool can connect to db2 but IBM SPSS Modeler can't, try reinstalling Modeler.

Follow the steps below.

1. Download and install the IBM Data Server Runtime Client (DB2 CLI and JDBC Drivers)


    The IBM Data Server Runtime Client provides a way to run applications on remote databases. GUI tools are not shipped with the IBM Data Server Runtime Client. Capabilities include the following:
    · DB2 Command Line Processor Plus for dynamically creating, editing, and running SQL statements and scripts
    · Support for applications that use ODBC, CLI, PHP, or RUBY to access databases
    · On Windows operating systems, support for applications that use .NET or OLE DB to access databases
    · Support for client applications and applets that are written in the Java language using JDBC and for embedded SQL for Java (SQLJ)
    Download and install the DB2 Version 9.7 Fix Pack 6 Client for Linux, UNIX, and Windows. An IBM ID is needed to download software from IBM FixCentral:
    http://www-01.ibm.com/support/docview.wss?uid=swg24032754
    Be sure to choose the IBM Data Server Runtime Client.
    Additional instructions on the IBM InfoCenter:
    http://pic.dhe.ibm.com/infocenter/db2luw/v9r7/topic/com.ibm.swg.im.dbclient.install.doc/doc/c0022615.html



2. Download and install the 64-bit (if appropriate) or 32-bit (if appropriate) IBM Global Security Kit v8 (GSKit, or GSK8) which is needed for SSL encryption of data



3. Configure the environment for GSK8


    In order for the GSKit to work, its binaries and libraries must be added to the PATH environment variable. This is slightly different for different versions of Windows and Linux. In Windows 7, you should
    1) Go to the “Control Panel”,
    2) Choose “System”
    3) Choose “Advanced system settings”
    4) Click “Environment Variables.”
    5) Highlight “Path”
    6) Click “Edit…”
    7) Add “C:\Program Files\IBM\GSK8\lib64” (or the installation path where you installed the 64-bit GSKit)
    8) Add “C:\Program Files\IBM\GSK8\bin” (or the installation path where you installed the 64-bit GSKit)
    9) Add “C:\Program Files (x86)\IBM\GSK8\lib” if you installed the 32-bit libraries on 64-bit Windows
    10) Add “C:\Program Files (x86)\IBM\GSK8\bin” if you installed the 32-bit libraries on 64-bit Windows

    NOTE: A semicolon before or after the new entries is required.

    11) Continue pressing “OK” until all dialog boxes have closed.
    12) If you have opened any command prompts, you will need to close and reopen them for them to get the new Path setting.

    Testing this change:
    1) Open a command prompt
    2) Type “gsk8capicmd_64 -version”
    3) Type “gsk8capicmd -version”
    If you receive output after each command resembling the following, the path has been properly set up:

    GSKCAPICMD
    ==========
    @(#)CompanyName: IBM Corporation
    @(#)LegalTrademarks: IBM
    @(#)FileDescription: IBM Global Security Toolkit
    @(#)FileVersion: 8.0.14.26
    @(#)InternalName: gskcapicmd
    @(#)LegalCopyright: Licensed Materials - Property of IBM GSKit
    (C) Copyright IBM Corp.1995, 2011
    All Rights Reserved. US Government Users
    Restricted Rights - Use, duplication or disclosure
    restricted by GSA ADP Schedule Contract with IBM Corp.
    @(#)OriginalFilename: gsk8capicmd_64.exe
    @(#)ProductName: gsk8b (GoldCoast Build) 121010
    @(#)ProductVersion: 8.0.14.26
    @(#)ProductInfo: 12/09/02.23:51:34.12/10/10.09:12:58
    @(#)CMVCInfo: gsk8b_111013/gsk8b_pkg gsk8b_120615/gsk8b_ikm gsk8b_121010/gsk8b_ssl gsk8b_101019/gsk8b_support gsk8b_120710/gsk8b_acme gsk8b_120816/gsk8b_cms gsk8b_120926/gsk8b_doc


4. Obtain the Signer Certificate from the SMA Server


    Signer Certificates establish the trust relationship in SSL communication. Signer certificates are also known as public keys. The Signer Certificate we are using is extracted into a text format which can be used by GSKit, and is a text file with a “.arm” extension such as “usrd11q78100XX.adm.rtp.ssm.sdc.gts.ibm.com.arm” and will need to be provided to you by the system administrator or IBM as the file is created and stored on the DB2 server.


5. Use the GSKit commands to store the signer certificate in a new client key database


    The signer certificate must be stored in a key database (kdb), which holds the encrypted key information and is locked with a password. There are several types of key databases, and we will require one for Certificate Management System (CMS). The password to the key database is stored encrypted in a file known as a stash file. GSKit uses the stash file to obtain the password to the key database.

    Create a new folder and copy or move the .arm file to it.
    Open a DOS command prompt and change directory to the new folder.
    Run the following commands, changing only the italicized text to represent the actual file that was given to you. Long lines have been reverse-indented for clarity.
    Create a key database (this only happens once, as the key database is used for all connections from this client):
    gsk8capicmd_64 -keydb -create -db client.kdb -pw ccipass –stash

    For each SMA server you have received a key for, add that key into the Key Database by using the following command. Replace <UNIQUELABEL> with a unique identifier for this key such as the server name (usrd11q78100XX).
    gsk8capicmd_64 -cert -add -db client.kdb -pw ccipass -label <UNIQUELABEL> -format ascii -file usrd11q78100XX.adm.rtp.ssm.sdc.gts.ibm.com.arm

    As a result of running the above commands, the directory will contain several new files with different extensions.

    Additional reading: http://pic.dhe.ibm.com/infocenter/db2luw/v9r7/topic/com.ibm.db2.luw.admin.sec.doc/doc/t0053518.html


6. Configure the DB2 Runtime Client to support SSL and catalog the remote SMA database server


    In order to access the remote database using the DB2 command line tools and ODBC driver, it is necessary to configure the local DB2 client by telling it where the key database and stash files are.

    Open DB2 Command Prompt by finding the Command Line Tools under IBM DB2 in the Windows Start Menu. Change to the same directory used in the previous step and, in the command prompt, type the following commands, replacing c:\path\to with the actual path to those files, putting single-quotes around the file paths if there are special characters such as spaces in the path.

    db2 update dbm cfg using SSL_CLNT_KEYDB ' c:\path\to\client.kdb'
    db2 update dbm cfg using SSL_CLNT_STASH ' c:\path\to\client.sth'

    db2 catalog tcpip node <MY_NODE_ALIAS> remote <SMA_DB2SERVER> server <SMA_DB2PORT> security ssl
    where:
    · <MY_NODE_ALIAS> is a name that you choose to access the SMA node
    · <SMA_DB2SERVER> is the host name or IP address given to you by IBM SMA
    · <SMA_DB2PORT> is the port number at which the server is configured for an SSL connection, given to you by IBM SMA
    Sample:
    db2 catalog tcpip node CustomerDB remote 170.224.177.168 server 4444 security ssl

7. Catalog each database on the remote server and connect


    After cataloging the server itself, it is necessary to catalog each database you wish to connect to. SMA databases are named sequentially on each server in the format PROXXXX, where XXXX is a number. You can determine the database name by connecting to your project’s document limiter Admin.jsp page as documented in the SMA documentation at http://pic.dhe.ibm.com/infocenter/sma/v1r2m0/topic/com.ibm.swg.ba.cognos.ag_ci.1.2.0.doc/t_ag_ci_settingdocumentlimits.html

    1. Log in to Social Media Analytics as a user with administrator or system administrator role.

    2. Substituting in the proper IP address or hostname for "<ui_node_host_name>", enter the following web address in to the address of the web browser:
    http://<ui_node_host_name>/documentlimiter/Admin.jsp

    With the database name now known, enter the following command at the command prompt to make an alias to the database locally.

    db2 catalog database <PROJECT_DB> as <PROJECT_DB_ALIAS> at node <MY_NODE_ALIAS>

    where:
    · <PROJECT_DB> is the database name on the server corresponding to the required project
    · <PROJECT_DB_ALIAS> is how the DB name will later appear in your environment
    · <MY_NODE_ALIAS> is the name you chose in step 7


    After these connections are all set up, we must reset the DB2 client in order for the settings to take affect. Run the command
    db2 terminate

    With the database server and the database both cataloged, we can connect to the database using the DB2 Command Line Interface (CLI).
    db2 connect to <PROJECT_DB_ALIAS> user <DB2_USER> using "<DB2_PASSWORD>"

    where:
    <PROJECT_DB_ALIAS> is the name you chose previously,
    <DB2_USER> is the DB2 user assigned to you by the SMA team
    <DB2_PASSWORD> is the password for the above user, provided by the SMA team. The password should be in quotes as it likely contains non alpha-numeric characters.



8. Access for Cognos BI: Create a Cognos Business Intelligence Data Source

    The easiest connection in Cognos Business Intelligence to your SMA database is a CLI connection. Cognos always uses a 32-bit connection (even on a 64-bit server), so it is necessary to have the 32-bit version of GSK8 installed and in the PATH environment variable.

    To create the connection
    1. Log in to Cognos as an administrator
    2. Open IBM Cognos Administration
    3. Navigate to the Configuration tab
    4. Ensure you are on the Data Source Connections screen
    5. Click the “New Connection” icon
    6. Give the connection a name and any other optional information you desire, and click next


9. Access for SPSS Modeler: Create an ODBC data source to the SMA DB2 database

    Many applications use ODBC to connect to databases. To create an ODBC data source to use by your application:
    1) Create an ODBC Data Source
    a. On Windows XP: Open Settings -> Control Panel -> Administrative Tools -> Data Sources (ODBC)
    b. On Windows 7: Search for ‘ ODBC’ from the Start Menu and select ‘Set up data sources (ODBC)’.
    2) Select the “System DSN” tab
    3) Click “Add”
    4) Select “IBM DB2 ODBC Driver”
    5) Click “Finish”
    6) Enter a datasource name of your choice
    7) Choose the database alias <PROJECT_DB_ALIAS> you created earlier
    8) Click “OK”


10. Create a JDBC Type-2 DB2 data source that points to the SMA DB2 database

    You can use a Type-2 or Type-4 JDBC driver to connect to the database. The benefit of using the Type-2 driver is that we can use the previous steps to perform the SSL encryption and it is very easy to set up once the previous steps are done. The Type-2 driver works by tunneling the database traffic through the DB2 CLI driver. A type-4-driver is written completely in Java and connects directly to the DB2 database. To do that, changes need to be made to the Java security settings, a new Java keystore needs to be created.

    To use the Type-2 driver, set up a JDBC connection using the JDBC URL, substituting in the same Project DB Alias used from the db2 catalog database command
    jdbc:db2: <PROJECT_DB_ALIAS>
    The classname to use is com.ibm.db2.jcc.DB2Driver
    The JDBC driver files are db2jcc.jar and db2jcc_license_cu.jar.

    Alternatively, to configure the pure Java Type-4 driver, rather than use the CLI to connect to DB2, JDBC can connect to DB2 over SSL directly but needs configuration. Changes must be made to the Java security providers, as well as the JDBC connection string. The changes necessary on the server have already been done, so it is only the client-side settings that need to be made. These instructions are based on the page: http://www.ibm.com/developerworks/industry/library/ind-configure-fips-db2-ws/index.html?ca=drs-#ConfiguretheJREtouseSSL

    Create a Java keystore to hold the certificate file. To do so, open a command prompt and change to the directory holding the signer certificate with the .arm extension. Run the command to create a java keystore named client.jks. You will need to enter a password, which you will need later, and verify the import.

    keytool -import -trustcacerts -alias SMA -file usrd11q78100XX.adm.rtp.ssm.sdc.gts.ibm.com.arm  -keystore client.jks

    Follow these steps to configure Java Runtime Environment to use Secure Sockets Layer (SSL):

    10.1 Configure the Java security provider in java.security file


      Edit the file java.security in [JAVA_HOME]\lib\security to include IBMJSSEProvider2 as the security provider. The configuration in the specified file depends on the Java development kit you have. In this example, we are considering the use of IBM Software Development Kit (SDK).

      Include the security provider in the list of providers and rearrange the rest of the providers.

      security.provider.1=com.ibm.jsse2.IBMJSSEProvider2

      After the change, the list of providers in the java.security file is displayed as:

      #
      # List of providers and their preference orders (see above):
      #
      security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
      security.provider.2=com.ibm.crypto.fips.provider.IBMJCEFIPS
      security.provider.3=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl
      security.provider.4=com.ibm.crypto.provider.IBMJCE
      security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
      security.provider.6=com.ibm.security.cert.IBMCertPath
      security.provider.7=com.ibm.security.cmskeystore.CMSProvider
      security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
      security.provider.9=com.ibm.security.sasl.IBMSASL
      security.provider.10=com.ibm.xml.crypto.IBMXMLCryptoProvider
      security.provider.11=com.ibm.xml.enc.IBMXMLEncProvider
      security.provider.12=org.apache.harmony.security.provider.PolicyProvider

    10.2 Set the Java system property

      Because the IBM Data Server Driver for JDBC must be in FIPS-compliant mode, you must set the com.ibm.jsse2.JSSEFIPS Java system property in the application or application server using the driver:
      -Dcom.ibm.jsse2.JSSEFIPS=true

    10.3 Configure SSL socket factory providers in java.security file

      Edit the file java.security in [WAS_HOME]\ java\jre\lib\security to include the SSL socket factory providers. Uncomment the following socket factory providers:
      ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
      ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl

      After the change, the list of SSL socket factory providers in the java.security file is displayed as:

      #
      # Determines the default SSLSocketFactory and SSLServerSocketFactory
      # provider implementations for the javax.net.ssl package. If due to
      # export and/or import regulations, the providers are not allowed to be
      # replaced, changing these values will produce non-functional
      # SocketFactory or ServerSocketFactory implementations.
      #
      # Default JSSE socket factories
      ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
      ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
      # WebSphere socket factories (in cryptosf.jar)
      #ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
      #ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol
      .SSLServerSocketFactory

      Set parameters in the JVM arguments or in the JDBC connection string. To set the parameter in the JVM arguments, use the following parameters when you run your application. This configuration must be done in the JVM arguments. The truststore parameters refer to the java keystore created earlier.

      javax.net.ssl.trustStore=certificate path

      javax.net.ssl.trustStorePassword=certificate password

      com.ibm.jsse2.JSSEFIPS=true

      Example of the JVM arguments:

      -Djavax.net.ssl.trustStore="c:\path\to\client.jks" -Djavax.net.ssl
      .trustStorePassword=ccipass -Dcom.ibm.jsse2.JSSEFIPS=true

      Alternatively, use the JDBC Connection string to connect to the database
      The JDBC Connection string is in the format:
      jdbc:db2://< db2-server>: <db2_port>/ <SMA_PROJECT_NAME>:sslConnection=true;sslTrustStoreLocation= <KEYSTORE_LOCATION>;sslTrustStorePassword= <KEYSTORE_PASSWORD>;

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

Social Media Analytics

Software version:

1.2

Operating system(s):

Linux

Reference #:

1633189

Modified date:

2013-11-27

Translate my page

Machine Translation

Content navigation