Testing connectivity to a database

You can create a Transport Layer Security (TLS) or non-TLS connection between IBM® Data Server Client or IBM Data Server Runtime Client and a database by using the Db2 CLI or CLP.

Before you begin

Obtain and apply the IBM Data Server Client or IBM Data Server Runtime Client Version 11.5 package that applies to your client machine’s operating system. Refer to the link to download and install it: IBM Data Server Client or IBM Data Server Runtime Client.

If you intend to connect by using the TLS protocol, download and install GSKit V8: GSKit V8 - Install, Uninstall and Upgrade instructions. Click the operating system tab that applies to your client machine’s operating system. If you are installing the GSKit on a Windows computer, ensure that you specify the GSKit installation directory path installation_directory\gsk8\bin for the PATH environment variable.

Before you can connect to your database, you must perform two steps:

  • Verify prerequisites, including installing driver packages, configuring your local environment, and if needed downloading TLS certificates.
  • Collect connect information, including database details such as host name and port numbers, and connect credentials such as user ID and password.

If you intend to connect by using the TLS protocol, download the appropriate TLS certificate (for example, SampleSSLCert.crt) to a directory on the client machine.

About this task

Complete the set of steps that applies to the type of connection that you want to create.

Procedure

Use one of the following approaches:

  • To create a connection without using TLS, complete the following steps:
    1. Catalog the Server node so that client applications can connect to it.
      Issue the following command:
      db2 catalog tcpip node node_name remote dashDB_IP_address server port
      Where:
      • node_name represents your name for the node.
      • dashDB_IP_address represents the IP address of the server.
      • port is the port that is used to connect to Server without using an TLS connection. If you are using the default port, specify 50000.
    2. Catalog the remote Server database so that client applications can connect to it.
      Issue the following command:
      db2 catalog database SAMPLEDB as db_alias at node node_name
      Where db_alias represents your name for the Server database.
    3. Test the non-TLS connection that uses CLP by issuing the following command to connect to the database:
      db2 connect to db_alias user user_id
      Where user_id represents your Db2® Warehouse user ID. You are prompted to enter your password.

      Or

      Test the TLS connection that uses CLI by issuing the following command to connect to the database:
      db2cli validate -dsn alias -connect -user userid -passwd password
      Where:
      • alias is an alias that you created with the db2cli writecfgcommand.
      • userid is your Db2 user ID.
      • password is your Db2 password.
  • To create a connection by using TLS, complete the following steps:
    1. Issue the following command:
      cd /ssl_directory_name/ssl

      Where /ssl_directory_name/ssl represents the path to the directory into which you downloaded the SamplSSLCert.crt TLS certificate.

    2. Create a client key database and a stash file by using the GSKCapiCmd tool.
      For example, the following command creates a client key database that is called dashclient.kdb and a stash file that is called dashclient.sth:
      gsk8capicmd_64 -keydb -create -db "dashclient.kdb" -pw "passw0rdpw0" -stash
      Where:
      • passw0rdpw0 is a password.
      • -stash creates a stash file in the same path as that of the client key database, with a file extension of .sth.
      At connection time, GSKit uses the stash file to obtain the password to the client key database.
    3. Add the certificate to the client key database.
      For example, the following gsk8capicmd command imports the certificate from the /ssl_directory_name/ssl/SamplSSLCert.crt file into the client key database called dashclient.kdb:
      gsk8capicmd_64 -cert -add -db "dashclient.kdb" -pw "passw0rdpw0" -label "DigiCert" -file "/ssl_directory_name/ssl/SampleSSLCert.crt" -format ascii -fips
    4. Update the values of the SSL_CLNT_KEYDB and SSL_CLNT_STASH database manager configuration parameters on the client to specify the client key database and the stash file.
      An example of the following is presented below:
      db2 update dbm cfg using SSL_CLNT_KEYDB /ssl_directory_name/ssl/dashclient.kdb
      db2 update dbm cfg using SSL_CLNT_STASH /ssl_directory_name/ssl/dashclient.sth
      
    5. Catalog the server node so that client applications can connect to it. Issue the following command:
      db2 catalog tcpip node node_name remote dashDB_IP_address server port security ssl

      Where:

      • node_name represents your name for the node.
      • dashDB_IP_address represents the IP address of the server.
      • port is the port that is used to connect to Server by using an TLS connection. If you are using the default port, specify 50001.
    6. Catalog the remote server database so that client applications can connect to it. Issue the following command:
      db2 catalog database SAMPLEDB as db_alias at node node_name

      Where db_alias represents your name for the Server database.

    7. Test the TLS connection that uses CLP by issuing the following command to connect to the database:
      db2 connect to db_alias user user_id

      Where user_id represents your Db2 user ID. You are prompted to enter your password.

      Or

      Test the TLS connection that uses CLI by issuing the following command to connect to the database:

      db2cli validate -dsn alias -connect -user userid -passwd password

      where:

      • alias is an alias that you created with the db2cli writecfg command.
      • userid is your Db2 user ID.
      • password is your Db2 password.