Copyright Information

StarPipes
Version 4
StarQuest Ventures, Inc.

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of StarQuest Ventures, Inc.

StarQuest products contain certain trade secrets and confidential and proprietary information of StarQuest Ventures, Inc. StarQuest may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from StarQuest, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Additionally, any public network IDs or addresses referenced in this document are for demonstration/example purposes only. The inclusion of such IDs and addresses in this document does not grant you any express or implied right to test or otherwise use or access any such network ID or address.

StarQuest, StarSQL, StarQuest Data Replicator, SQDR, and SQDR Plus are trademarks of StarQuest Ventures, Inc.
Java and Java-related products are registered trademarks of Oracle.
Microsoft, Windows, Windows Server, are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

©Copyright 1994-2019. StarQuest Ventures, Inc. All rights reserved.

121319 edition


Contacting StarQuest

Please use the methods described in this topic to contact StarQuest Ventures if you have suggestions or need information about StarQuest products.

See the README.HTML file for late-breaking release notes and hints. If you have received an error message, refer to the topic StarPipes Event Codes.

Support

Technical support may be available subject to the prices, terms, and conditions specified in your organization's maintenance contract with StarQuest Ventures, Inc. Before you contact us be prepared to provide the following information:

  • Company Name

  • Contact Name

  • Phone

  • Email Address

  • IBM Host/Version (e.g. IBM i 7.1, DB2 for z/OS 9)

  • SNA Gateway Product/Version if relevant (e.g. HIS 2006, IBM Communications Server)

  • Windows Version

  • StarQuest Product and Version

  • Application/Version (if applicable)

  • Exact Error Message (if applicable)

  • Nature of your request

Sales and Service

If you have ideas for product enhancements or need more information about how StarQuest products can provide solutions for connecting Windows and UNIX applications to IBM host resources, please contact us via any of the following methods.

Address | StarQuest Ventures, Inc. 548 Market St, #22938 San Francisco, CA 94104-5401
Telephone | 415-669-9619 Option 1: Sales Option 2: Technical Support
Fax | 415-669-9639
Email | support@starquest.com
World Wide Web |


About StarPipes for Windows

The StarPipes for Windows software uses the Distributed Relational Database Architecture (DRDA) to provide a gateway for connecting a client computer on a TCP/IP or SSL network to a DB2 host. StarPipes implements an "intermediary DRDA Server" as that is described by The Open Group's DRDA Architecture Specification Version 4.

StarPipes allows advanced DRDA application requesters, such as StarSQL, to use native TCP/IP connections to interoperate with IBM SNA-based DB2 systems. The StarPipes software runs on a Windows computer and appears to the application requester (client) as a TCP/IP server. StarPipes fields incoming requests from DB2 users who are running applications that communicate using the TCP/IP network protocol.

StarPipes can be configured to transfer the incoming messages as SNA-APPC conversations to DB2, or to allow the TCP/IP messages to flow directly to the DB2 host unchanged. The DB2 system must support DRDA over TCP/IP to receive TCP/IP messages unchanged. See the System Requirements topic for details about specific DB2 releases.

StarPipes provides advanced functionality, such as support for encrypted datastreams, for TCP/IP clients that connect to an SNA network that supports DRDA Level 3 or higher (such as OS/400 v5r2, UDB v8, and z/OS v8 and later releases). Be sure to review the topic, DRDA Security Flows, if you want to configure StarPipes to pass encrypted user IDs and passwords to a DB2 host.

In addition, StarPipes provides support for both inbound and outbound SSL (encrypted) communications. This ability is useful for supporting encrypted communications between DRDA clients or DB2 hosts that do not support or have not been configured for SSL. Using the SSL functionality of StarPipes avoids the complexity of configuring SSL on the clients and the host, and offloads the CPU intensive task of handling encryption. In addition, a pair of StarPipes servers can be used to create an encrypted tunnel over the Internet to connect remote data centers without configuration changes or updates to the clients or hosts. See SSL Scenarios.


Features

StarPipes for Windows provides:

  • a standards-based implementation with high-performance access to DB2 hosts

  • access to multiple DB2 systems from one StarPipes server

  • remote management and configuration of StarPipes

  • installation as a Windows service

  • advanced tracing services for diagnosing communication failures. StarPipes is especially useful for problem determination of applications that run as a Windows service, such as StarQuest Data Replicator and SQL Server Linked Servers.

  • log files that detail access, which can be used to monitor performance and produce accounting chargebacks based upon actual usage

  • support for PEM (Password Expiration Management), which allows users to change their mainframe or AS/400 host password from the desktop, when SNA communication is being used between StarPipes and the host.

  • support for using database aliases, which can help minimize the affect of administrative changes to databases for client computers that connect to the databases

  • support for both inbound and outbound SSL (encrypted) communications. This ability is useful for supporting encrypted communications between older DRDA clients or older DB2 hosts that do not support SSL. Even in the case of newer DRDA clients or DB2 hosts that do support SSL, using the SSL functionality of StarPipes avoids the complexity of configuring SSL on the clients and the host, and offloads the CPU intensive task of handling encryption. In addition, a pair of StarPipes servers can be used to create an encrypted tunnel over the Internet to connect remote data centers without configuration changes or updates to the clients or hosts. See SSL Scenarios.

  • support for centralized licensing of StarSQL and StarSQL for Java client computers


System Requirements

You can install and run StarPipes for Windows on a computer that meets the following requirements.

  • Windows Server 2008R2sp1, Server 2012, Server 2012R2, Server 2016, Server 2019, Windows 7sp1, 8, 8.1, 10

  • StarPipes for Windows requires Visual C++ 2015/2017/2019 runtimes. The StarPipes installer will install the Microsoft-supplied Microsoft Visual C++ 2015/2017/2019 Redistributable package if it is not already present on the system. The Microsoft Redistributable package will remain on the system if StarPipes is upgraded or uninstalled.

  • If you are using a 64-bit version of one of these operating systems, you can install either the 32-bit or the 64-bit version of StarPipes.

  • Only one of the two products (StarPipes for Windows and StarPipes for Windows (x64)) may be installed on a system. The 64-bit installer will not allow you to install on a 64-bit system where the 32-bit version of StarPipes is already installed, and the 32-bit installer for StarPipes 4.0 will not allow you to install on a system where the 64-bit version already is installed. However, the installer for older (pre-4.0) versions of 32-bit StarPipes does not check for the presence of the 64-bit version; installing an older version of StarPipes on a system with the 64-bit version will result in unpredictable behavior.

  • TCP/IP support configured and running on the Windows system. Use of a static IP address, rather than DHCP, is highly recommended.

  • StarSQL driver or other DRDA client software using native TCP/IP connections. To take advantage of the StarPipes support for database aliasing the client computer must use the StarSQL ODBC driver v5.42 or later.

  • For SNA-APPC connections with the 32-bit version of StarPipes you can use either:

    • Microsoft Host Integration Server 2000 (SP2) or later

    • IBM Communications Server for Windows, version 5.01 or later

  • For SNA-APPC connections with the 64-bit version of StarPipes use:

    • Microsoft Host Integration Server 2006 or later

StarPipes for Windows will work with either the client or server software of the SNA server. However, performance is optimized when StarPipes is installed on the same computer as the SNA server software. You choose which SNA Server to use (Microsoft Host Integration Server, IBM Communications Server, or none) when you install StarPipes. This choice cannot be changed without re-installing StarPipes.

The following host databases provide native DRDA over TCP/IP support:

  • DB2 for z/OS and OS/390 v5.1 and later

  • DB2 for i (DB2/400, DB2 UDB for iSeries, and DB2 for i5/OS) v4r2 and later

  • DB2 Universal Database for Linux, UNIX and Windows v6.1 and later

  • Apache Derby (JavaDB) 10.3 or later

  • DB2 for VM 7.1 and later

The following host databases provide SSL support:

  • DB2 for z/OS v9.1 and later

  • DB2 for i (DB2/400, DB2 UDB for iSeries, and DB2 for i5/OS) v5r1 and later

  • DB2 Universal Database for Linux, UNIX and Windows v9.1 and later

  • Apache Derby (JavaDB) 10.3 or later

StarPipes provides advanced functionality, such as support for encrypted datastreams, for TCP/IP clients that connect to an SNA network that supports DRDA Level 3, such as OS/400 v5r2, UDB v8, and z/OS v8 and later releases. Be sure to review the topic, DRDA Security Flows, if you want to configure StarPipes to pass encrypted user IDs and passwords to a DB2 host.


SSL

SSL Scenarios

Introduction to SSL

Secure Sockets Layer (SSL) is a protocol that provides a secure connection over an insecure network. It is commonly used by Internet applications such as web-based banking and commerce; whenever you see a URL beginning with https, you know that your web browser is communicating using SSL.

SSL can also be used to secure DRDA connections, and is supported by recent versions of DB2 and some DB2 DRDA clients such as StarSQL 6.0x and StarSQL for Java. However, since SSL support is a recent enhancement to DB2, it is common to find older DB2 servers and clients that do not have SSL support. In addition, the configuration of SSL on a host system like z/OS can be complicated, and the processing of encrypting and decrypting the secure communications requires extra processing power.

StarPipe's SSL support provides a solution for all of these issues - it can act as an SSL proxy for either the client or the host or both, without changes to either client or host, it off-loads the processing load of encryption to a Windows server, and it is simple to configure and manage.

In the following scenarios, the DRDA client and the DB2 server are in different locations, and wish to communicate securely over the Internet using port 448 for encrypted traffic. You may need to configure firewalls to allow communication using port 448, or use a multi-homed StarPipes server with one network interface directly connected to the Internet listening for incoming SSL DRDA traffic.

Scenario 1: Provide SSL for the host

In this scenario, we have an SSL-enabled DRDA client like StarSQL for Java at a remote site, and a StarPipes server collocated with a DB2 server that does not support (or is not configured for) SSL. The Starpipes server acts as an SSL proxy for the DB2 server.

The SSL-enabled client communicates with StarPipes using SSL (e.g. port 448); StarPipes communicates with the host using unencrypted DRDA (e.g. port 446).

Follow the following steps for this scenario:

  1. Install a StarPipes server certificate; see Certificate Management for details.

  2. Configure a StarPipes SSL listener; see Listeners Properties for details.

  3. Configure a TCP/IP route to the DB2 host (you will need to know the hostname or IP address and listening port of the DB2 host); see Routing Properties.

  4. Configure the SSL-enabled DRDA client; see Listeners Properties for an example of configuring a StarSQL for Java client; see Certificate Management for an example of configuring an IBM i 7.1 server as a client to StarPipes.

Scenario 2: Provide SSL for the client

In this scenario, we have a StarPipes server collocated with a DRDA client that does not support (or is not configured for) SSL at a remote site, communicating over the Internet with an SSL-enabled DB2 server.

The client communicates with StarPipes using unencrypted DRDA (e.g. port 446), and StarPipes communicates with the host using SSL (e.g. port 448).

Follow the following steps for this scenario:

  1. Create a TCP/IP listener listening on port 446; see Listeners Properties.

  2. Confirm that SSL is enabled on the DB2 host computer. If necessary, contact your DB2 or network administrator to obtain the listening port that the host is using for SSL connections to DB2. See Configuring SSL for DB2 for z/OS, Configuring SSL on DB2 for i, Configuring SSL for DB2 UDB, or Configuring SSL for Apache Derby.

  3. Configure an SSL route to the host; see Routing Properties.

  4. Configure the DRDA client to communicate via TCP/IP to the StarPipes server on port 446.

Scenario 3: Provide an encrypted tunnel

In this scenario, two StarPipes servers provide a secure tunnel over the Internet in the situation where neither the client nor the DB2 server are configured for SSL. One StarPipes server is collocated with the DRDA client at a remote site; the other StarPipes server is collocated with the DB2 host. This is useful for providing secure communications between two data centers without the need for configuration changes or updates for the client or host.

At the remote site, the client communicates with Starpipes using unencrypted DRDA (e.g. port 446). That StarPipes server communicates over the Internet to another StarPipes server using SSL (e.g. port 448), which in turn communicates with the DB2 host using unencrypted DRDA (e.g. port 446).

Follow the following steps for this scenario.

This example shows the use of a StarPipes client certificate issued by a Certificate Authority trusted by both StarPipes servers; the client certificate is installed on the "client" StarPipes server, and the "server" StarPipes server is configured to require client authentication, providing an additional level of security.

In addition, this example assumes that the StarPipes server at the central site is multi-homed, with one network interface connected directly to the Internet and dedicated to incoming DRDA SSL connections; use the Windows Firewall or another mechanism to block all other ports on this interface.

On the StarPipes server at the remote site (collocated with the DRDA client):

  1. Install a client certificate named StarPipesClient; see Certificate Management.

  2. Create a TCP/IP listener listening on port 446; see Listeners Properties.

  3. Configure an SSL route to the other StarPipes server. You will need to know its IP address or hostname and SSL listening port number (448 in this example). See Routing Properties.

  4. Configure the DRDA client to communicate via TCP/IP to its collocated StarPipes server via port 446.

On the StarPipes server at the central site (collocated with the DB2 host):

  1. Install a StarPipes server certificate; see Certificate Management for details.

  2. Configure a StarPipes SSL listener for port 448. For the IP address of the listener, enter the IP address of the Internet-connected network interface; StarPipes will listen only on this interface. In addition, click SSL Options and select Require Client Authentication. See Listeners Properties for details

  3. Configure a TCP/IP route to the host; see Routing Properties.

Certificates:

SSL uses certificates to provide credentials; See Certificate Management.


Setting Up StarPipes

The topics in this section describe how to install StarPipes, and how to start and stop the StarPipes service.


Installing StarPipes

To install StarPipes, execute the Setup.exe program from the installation image. To install the StarPipes Management Console, you need Administrator level privileges on the computer where StarPipes is installed.

Important Note

If you are upgrading from StarPipes v2.20 or earlier you must remove the older version before you install this version of the StarPipes software. Record your current configuration before you remove the previous version of StarPipes, and then select Uninstall StarPipes for Windows NT from the StarPipes program group menu.

If you are upgrading from StarPipes 3.11 or earlier, your configuration will be replaced during the update; record your current configuration before running the update.

If you are replacing a 32-bit version of StarPipes with the 64-bit version, you must remove the 32-bit version first; record your current configuration before running the update.

During the installation, you are given the option to install the full StarPipes for Windows product or only the StarPipes Management Utilities. Select the Complete setup type unless you only want to manage StarPipes remotely from this computer, in which case you can select the Custom setup option to install only the StarPipes Management Utilities.

The installation Wizard also prompts you to specify which SNA connectivity method you will be using. The choices are:

  • None

  • Microsoft Host Integration Server (formerly called Microsoft SNA Server)

  • IBM Communications Server for Windows (32-bit StarPipes only)

Select "None" if you are using TCP/IP passthrough. Otherwise, select one of the SNA connectivity methods. Note that you cannot change the connectivity method without re-installing StarPipes.

If you choose an SNA server it should already be configured for LU 6.2 (APPC) connectivity to your host. See the topics Setting Up Microsoft Host Integration Server or Setting up IBM Communications Server for additional information.


Licensing

Service License

A license for the StarPipes service is required for operation; without a valid service license (type SP), the StarPipes service can be configured and will start, but it will reject any client connections, and an error message will appear in the Application Event Log.

Install the service license using License Configuration from the StarPipes Program Group and restart the StarPipes service. See the StarPipes for Windows Quick Start Guide for details.

Client Licenses

Most StarQuest client products such as StarSQL require a license to operate. In a smaller installation, a node-locked license is typically installed on each client machine. In a larger installation, a StarLicense server is run as a service on a central Windows or UNIX server and all clients are configured to request licenses from the StarLicense server.

StarPipes 4.0 introduces another method of deploying licenses in a larger installation. The client licenses are installed on the StarPipes server and are allocated to the clients as they request connections to the host. This simplifies deployment in that only one server is required - there is no need to install, configure and manage a StarLicense server - and the client configuration involves only one server (the StarPipes server).

Use of StarPipes-based licensing also simplifies the use of Java applets with StarSQL for Java.

The following clients can obtain licenses from a StarPipes 4.0 server:

" StarSQL v5.56 and later

" StarSQL for Java v2.58 and later

Install the client licenses (type SQ) using License Configuration from the StarPipes Program Group. See the StarPipes for Windows Quick Start Guide for details.

The StarPipes server can also be configured to obtain licenses from a StarLicense server for redistribution to the StarSQL clients.

No licensing configuration is required on the client machines.


Starting and Stopping StarPipes

Starting and Stopping the StarPipes Service

There are two methods for starting and stopping StarPipes:

  • Using the Windows Services Control Panel

  • Using the StarPipes Configuration Utility

Starting StarPipes Using the Windows Services Control Panel

StarPipes is installed as a Windows service and can be started and stopped from the Windows Services console. The shortcut for starting the Services console is typically located within Administrative Tools of the Control Panel. Select the StarPipes service and right-click to display the available commands.

managing the StarPipes service from Services console

You can configure the StarPipes service to start automatically when Windows is started. To automatically start StarPipes, highlight the StarPipes service, click the Startup button and chose Automatic as the Startup Type.

Starting StarPipes Using the StarPipes Configuration Application

The StarPipes service can also be started and stopped using the Service Control pane in the StarPipes Configuration application.


Using the StarPipes Configuration Application

StarPipes Server Configuration

There are two methods for accessing the StarPipes Configuration dialog:

  • Select StarPipes Configuration from the StarPipes program group of the Windows Start menu, and then select the StarPipes server you wish to configure.

  • From the StarPipes Management Console, right-click on the StarPipes server that you wish to configure and select Properties. For more information on the Management Console, refer to Managing StarPipes.

The StarPipes Configuration dialogs allows you to:

  • Start and stop the StarPipes service from the Service Control tab.

  • Configure TCP/IP and SSL listeners from the Listeners tab.

  • Configure database routes (TCP/IP, SSL, and SNA) from the Routing tab.

  • Configure aliases from the Aliasing tab.

  • Configure tracing and logging options from the Logging tab.


Using StarPipes

Using the StarPipes Management Console

The StarPipes Management Console uses the standard Microsoft Management Console (MMC) interface.

At the top of the console window are main menus--File, Server, View, and Help--which provide commands for acting on the objects in the console display and controlling how the console appears. You also can select an object and right-click the mouse to display a context-sensitive menu of commands that perform valid actions based on the object that is selected.

Below the menu bar is a toolbar that contains icons for performing common operations. You can control whether the toolbar appears by toggling the Status Bar command of the View menu. The toolbar icons are described in the following table.

Add Server icon Add Server | The Add Server icon displays the StarPipes Configuration dialog so you can select which StarPipes server computer you want to add to the management console.
Remove icon Remove Server | Select a StarPipes server and click the Remove toolbar icon to remove the server from the console display.
Server Properties icon Server Properties | Select a StarPipes server and click the Properties icon to display the StarPipes Configuration dialog with tabs for setting the Service Control, Communications, and Logging properties.
Refresh icon Refresh | Click the Refresh button to refresh the console display with current information.
About StarPipes icon About StarPipes | Click the Help button displays a dialog with information about the StarPipes software version and copyright.

After you add a server the name of the server computer appears in the left pane of the console. Active StarPipes connections are displayed in the right pane so you can view and manage connections. The Split command on the View menu lets you adjust the width of the left and right panes.


Selecting a StarPipes Server

When you select StarPipes Configuration from the Windows program group, or when you add a server to the StarPipes Management Console, a dialog appears so you can specify which StarPipes server computer you want to configure or add.

Select a computer from the drop-down list box, or enter the TCP/IP host name or the IP address where the StarPipes server is installed. Select the default [Local Machine] if you want to manage or add the computer you are using.

After you select the StarPipes server, either the StarPipes Configuration dialog appears, or the server name appears in the left pane of the StarPipes Management Console, depending on whether you started the StarPipes Configuration program or you are adding a server to the console.


Service Control

Service Control tab

The Service Control tab of the Configuration application displays the current status of the StarPipes service, as well as the number of active connections. You can also use this pane to start and stop StarPipes.

StarPipes Configuration Service Control tab

If you click the Stop button to stop the StarPipes service, you are presented with three methods of stopping the StarPipes server: Immediate, Controlled and Quiesce.

options for stopping the StarPipes service

The differences between these methods are described below.

Immediate | Causes active StarPipes sessions to end abruptly, relying on the DBMS to recover any pending transactions. This is the fastest way to stop the StarPipes service.
Controlled | Forces an end to sessions as soon as the current transaction for each client is complete. This option terminates client sessions quickly, but insures that all transactions are complete before ending the StarPipes service. No new sessions will be allowed to start. A Controlled stop causes active sessions to end on command chain boundaries, thus facilitating a clean shutdown. It is recommended that you use this option to allow the service to terminate in a normal manner.
Quiesce | Allows each client session to complete. StarPipes waits until the client disconnects from the DBMS before ending the service. No new sessions are allowed to start. This is the preferred way to end sessions.

Expediting a Quiesce or Controlled Stop

The Service Status indicator on the Service Control screen in the configuration tool displays the current status of the StarPipes server. If a Quiesce or Controlled stop has been selected, a yellow bar with the stopping status is displayed while StarPipes waits for clients to complete the termination process. If you find that during a Quiesce or Controlled stop, certain client connections are not terminating, you can change the Stop Type to Immediate. To do this, click Stop. The dialog will reappear and the Controlled and Quiesce buttons will be dimmed. Then select Immediate and click OK.


Communications

The communication properties that StarPipes uses to service database requests are configured with the following panels:

  • The Listeners panel specifies the TCP/IP ports that StarPipes monitors, and whether SSL is used for incoming connections.

  • The Routing panel defines TCP/IP, SSL and SNA routes to databases, and

  • The Aliasing panel defines aliases to redirect a database request to a different database.


Listeners Properties

The Listeners tab lets you specify the TCP/IP and SSL properties (IP address and port) that StarPipes uses to listen for client connections. You may choose to configure multiple listeners if require need both SSL and non-SSL connections, or if are you using a multi-homed server and desire to enable listeners for some but not all of the IP interfaces.

To create a new listener, Click the Add Button. You will see the following dialog:

IP

Specify the IP address on which StarPipes should listen.

You can configure the listener to accept connections on all addresses by using an IP address of 0.0.0.0, or you can specify particular IP address(es) for which you want the listener to be active. For a multi-homed server, this allows you to limit which IP addresses on the computer are available for accepting connections. For example, for a computer that has an IP address for an Internet connection and an IP address for a local area network, you can listen for license requests only on the LAN IP address to avoid exposure from Internet connections.

TCP/IP Port

The TCP/IP Port specifies the number of the port that StarPipes monitors for incoming and outgoing DRDA messages. The port number must match the one used by the StarSQL ODBC data source or the StarSQL for Java URL on the client computer. Typical values are 446 for unencrypted communications and 448 for SSL.

Idle Timeout

Specifies the number of seconds that a connection may remain idle before the StarPipes process disconnects the socket. If you specify 0 or no value, connections remain active regardless of how long they are idle.

SSL/TLS

Select this checkbox to enable SSL communications for this listener.

You must install a StarPipes server certificate prior to creating an SSL listener - see Certificate Management.

The client computer must also be configured for SSL communications. For example:

  • To configure StarSQL for Java for SSL, include both StarSQL_SSL14.jar and StarSQL_JDBC.jar in the CLASSPATH and include the ssl property in the URL (possible values are TLS, SSL, SSLv3, TLSv1). Here is a typical URL:

jdbc:StarSQL_JDBC://mystarpipes:448/MYRDB;ssl=TLS

  • To configure StarPipes running on two different computers to communicate with each other via SSL, select the SSL radio button when configuring the Routing properties on the "client" StarPipes machine.

Select SSL/TLS options to define optional SSL parameters:

Protocol Version can be one of the following values. Note that only protocol versions supported by the version of Windows running on the machine hosting the StarPipes server are displayed in the dropdown menu.

  • Negotiate (Default)

  • SSL V2

  • SSL V3

  • TLS V1

  • TLS V1 + 3DES

  • TLS V1 + AES256

  • TLS V1.2

  • TLS V1.2 + AES256

Require Client Authentication: Require that a client certificate (issued by a Certificate Authority trusted by the computer running StarPipes) be installed on the client computer. see Certificate Management.

Require 128-bit encryption: Require that the client use 128-bit encryption.


Routing Properties

Database Routing Properties

The Routing section of the Communications tab lists the RDB names and routes that have been specified. Click the Add button to add a database name and route, or select a defined route and click Edit to change the properties or Remove to delete the route. Note that clicking Remove immediately and permanently removes the route with no confirmation.

Defining Routes

To access multiple DB2 systems, you must define additional routes. StarPipes routes database requests based on the RDB name. After you click the Add button under the table of RDB routes another dialog appears so you can define the route. The TCP/IP protocol is the default connection type for routes.

defining a TCP/IP route

Adding TCP/IP and SSL Routes

Enter the TCP/IP configuration parameters (Host Name and Port number) for the desired host connection, as well as the RDB name for the DB2 system. The RDB Name should match the Database Server Name that is configured in the StarSQL data source and is case-sensitive; it is typically entered in upper case.

Adding SNA Routes

To specify an SNA route, click the SNA LU6.2 radio button of the RDB Route dialog to change the prompts to be appropriate for an SNA connection. Enter the SNA configuration parameters (Local LU, Remote LU, and Mode) for the desired host connection, as well as the RDB name for the DB2 system. The RDB Name should match the Database Server Name that is configured in the data source name (DSN) that is used to access this DB2 system.

defining an SNA route

If the DB2 system is configured with a custom transaction program name rather than the default service TP name 0x'7F6C4C2', select the Use Custom DRDA TP Name checkbox, enter the TP Name and click OK.

Enabling Password Management

StarPipes supports calling the host PEM (Password Expiration Management) procedure when using SNA communication between StarPipes and the host. This capability is defined on an RDBNAME basis. When StarPipes encounters the CHANGE PASSWORD codepoint from the StarSQL client, it then calls the IBM supplied PEM program on the host, and executes the password change. The old and new passwords are specified on the StarSQL client computer.

This capability is defined on an RDB Name basis, and can only be called via an SNA-APPC connection. If you are creating a new SNA route, or editing an existing one, you can click the Password Management button on the RDB Route dialog to display the following Password Management dialog.

enabling Password Management

Select the Enable Password Management checkbox, and enter the LOCAL LU, REMOTE LU and MODE for accessing the PEM transaction program (TP). The default PEM Service TP name is 0x06F3F0F1. Click OK to approve the Password Management properties.

Defining a Default Route

The Default Route is the route that StarPipes uses when an RDB name is not specified. Click on the ellipses button to the right of the Default Route field to display the following dialog:

changing the default TCP/IP route

TCP/IP or SSL Connection Information

To specify a default TCP/IP or SSL route, enter the name of the host and the port on which it listens for connections. The host system must support DRDA over native TCP/IP to use TCP/IP routes. The System Requirements topic details which versions of DB2 support DRDA over native TCP/IP connections. Similarly, refer to the System Requirements topic for a list of versions of DB2 that support SSL.

SNA Connection Information

To specify a default SNA route, click on the SNA LU6.2 radio button to change the prompts to be appropriate for an SNA connection.

changing the default SNA route

Enter the SNA configuration parameters (Local LU, Remote LU, and Mode) for the host connection as defined on your SNA gateway. If necessary contact your SNA gateway administrator to obtain this information.


Aliasing Properties

Database Aliasing Properties

The Aliasing section of the Communications tab allows a StarPipes administrator to map a database name that is sent in a client connection request to another database. When a StarSQL client (v5.42 or later) requests a connection to the database, the request is instead routed using the alias.

Using an alias can help insulate client computers from administrative changes to the database namespace. When an alias is specified, StarPipes routes the connection request as if the StarSQL ODBC DSN defined the connection using the alias name. Specifically, database references use the alias name instead of the original database name when such qualification is required by DRDA.

Note that the alias mapping occurs prior to the routing lookup. If the alias name is not a defined route, the default route (if any is defined) will be used to route the request. Because alias mapping is performed prior to routing, any reference to the original database name in a routing entry is effectively ignored.

StarSQL is designed to dynamically incorporate the alias name into subsequent DRDA flows. Other DRDA drivers are not notified of the mapping and may not function properly in all respects. Although the RDBNAME alias that is used for the connection is reflected in the StarSQL ODBC DSN Configuration Summary pane, the original RDBNAME is not changed in the actual DSN configuration.

  1. Click the Add button within the Aliasing section to define an alias for a database, or select an alias and click Edit to change the names or Remove to immediately and permanently delete the entry.

The following graphic shows a StarSQL DSN that is configured to connect to a database named SAMPLE.

From the StarPipes Configuration tab the SAMPLE database can be mapped to connect to a different database, such as REALRDB used in the following example.

defining a database alias


Certificate Management

SSL requires the use of certificates. A StarPipes server certificate must be installed in the Windows certificate store prior to configuring an SSL listener, and a client certificate may be optionally required for all clients connecting to the StarPipes server via SSL. In the case where multiple certificate authorities are involved, you may need to ensure that the StarPipes server, the hosts that it is connecting to, and clients that are connecting to StarPipes recognize the certificate authorities involved so that certificates are trusted.

Below are some typical scenarios:

Requesting and installing a server certificate before enabling the SSL listener

Requesting and installing a client certificate

Other Certificate Authorities

Requesting and installing a server certificate before enabling the SSL listener

  • Configure the Subject (CN) in the Registry

  • Create a CSR (Certificate Signing Request)

  • Submit the CSR to the Certificate Authority (CA)

  • Receive the certificate from the Certificate Authority

  • Install the certificate

  • Configure the SSL listener

Configure the Subject (CN = Common Name) of the Server Certificate

  • Use regedit to create a new string value named Subject in the registry key HKEY_LOCAL_MACHINE\SOFTWARE\StarQuest\StarPipesNT\StarPipesConfig. Set the value to the desired name; this is typically the fully qualified hostname of the server running StarPipes e.g. myserver.mydomain.com. You will use this name when creating the certificate request. If you do not configure this value, StarPipes will look for a valid certificate that contains the Subject StarPipes.

Create a CSR (Certificate Signing Request)

Most public Certificate Authorities publish instructions for creating a CSR from Windows; for example, you can use these instructions from Entrust and RapidSSL as an illustrated guide.

  • Start MMC

  • Select Add/Remove Snap-in... from the File menu

  • Choose Certificates from Available Snap-ins and select the Add Button.

  • Select the radio button to manage certificates for Computer Account.

  • Choose the radio button to manage the Local Computer.

  • Click Finish and OK.

  • Expand Certificates (Local Computer)/Personal.

  • Right-click on the Personal folder and select All Tasks/Advanced Operations/Create Custom Request

  • The CSR Generation Wizard will open. Click Next.

  • Select the option to Proceed without enrollment policy. Click Next.

  • Click Next at the No Template/ PKCS #10 window.

  • Expand the Details drop down menu and click Properties.

  • Enter a Friendly Name of your choosing.

  • Go to the Subject tab. In the Subject name box, enter appropriate values. The most important item (and usually the only required one) is Common Name (CN); this must match the value you entered in the registry above.

Example:
CN = myserver.mydomain.com
O = Your organization name
OU = Department or Division (optional)
S = State
L = City or Locality
C = Country

  • Click the Private Key tab.

  • Under Key Options, set Key size: 2048 and select the checkbox to Make private key exportable.

  • Under Key Permissions, select the checkbox for custom permissions and examine the key permissions. If the StarPipes service will be running as Local System Account, make sure that the System group has access to the private keys; if the StarPipes service will be running as a different user, make sure that user has access.

  • Click Next > Click Browse and select a location to save the CSR file as Base 64 (text) format. Enter a name for the file and click Save.

  • Click Finish.

Submit the CSR to the Certificate Authority (CA)

The following example shows the use of Microsoft Active Directory Certificate Services. Both Certificate Services and the WWW Publishing Service (IIS) should be running on the certificate server. Note that Certificate Services do not necessarily need to be run on a domain controller.

Using a public Certificate Authority is similar in concept but differs in the details. Using a public Certificate Authority usually involves some form of verification process.

  • Use Internet Explorer to open https://mycertsrv/certsrv. You will be prompted for the credentials of a domain user.

  • On the Welcome page, select Request a certificate

  • On the Request a Certificate page, select submit an advanced certificate request.

  • On the Advanced Certificate Request page, select Submit a certificate request by using a base-64-encoded CMC or PKCS #10 file.

  • On the Submit a Certificate Request or Renewal Request page

  • Paste in the contents of the CSR file created above into the Saved Request field; this is a plain text file and can be opened in Notepad.

  • Select Web Server from the Certificate Template dropdown and click Submit.

  • If the Certificate Server has been configured to automatically issue certificates (this is typically defined in the Certificate Template), the certificate is already available; select Download certificate chain as Base 64 encoded. If issuing the certificate requires approval from the administrator, the request will be set to pending, and you can retrieve the certificate later through the same web interface.

If necessary, the Certificate Server administrator approves the request using the following steps on the Certificate Server:

  • Start MMC.

  • Select Add/Remove Snap-in... from the File menu.

  • Select the Add Button and choose Certification Authority.

  • Choose Local Computer.

  • Expand the Certification Authority tree and open the Pending Requests folder.

  • Right click on the Request and select Issue from All Tasks.

Receive the certificate from the Certificate Authority

Back on the StarPipes machine, retrieve the certificate:

  • Use Internet Explorer to open https://mycertsrv/certsrv and log on as a domain user if necessary.

  • Select View the Status of a Pending Certificate Request.

  • Select the certificate request and select Download certificate chain as Base 64 encoded.

Install the certificate

  • As above, Start MMC, Select Add/Remove Snap-in... from the File menu, choose Certificates and select the Add Button, Select the radio button to manage certificates for Computer Account, Choose the radio button to manage the Local Computer. and Expand Certificates (Local Computer)/Personal.

  • Right-click on the Personal folder and select All Tasks/Import...

  • Browse to the location of the Base 64 certificate file you received from the CA. If you do not see the file listed (e.g. you saved the file with an extension of .txt or something other than the extensions listed in the dropdown of the browse window), select All files (*.*) from the dropdown. Select the certificate file and click OK.

  • The server certificate (and possibly the Certificate Authority certificate) will appear in the Personal/Certificate folder. Double-click the server certificate to view its details. Check that the statement You have a private key that corresponds to this certificate appears.

Configure the SSL listener

After installing the server certificate, you can now create the SSL listener in StarPipes.

  • Open the StarPipes Management Console.

  • Right-click on the server name and select Properties.

  • On the Listeners tab, select Add, configure a port, select the SSL/TLS checkbox, and click OK.

  • If all is well, the listener is created and will show a status of Running. Test that you can connect with an SSL-enabled DRDA client such as StarSQL or StarSQL for Java.

  • If you get the error A server certificate could not be found, the listener status will show as Error. Once a valid certificate is installed, restart the StarPipes service and check that the error TLA0055 Unable to find server certificate for SSL listener no longer appears in the Application event log.

Requesting and installing a client certificate

Requesting and installing a client (aka user) certificate is necessary if your StarPipes server is connecting to another StarPipes server that requires a client certificate, or if you are configuring a client to communicate with a StarPipes server configured to require a client certificate. Requesting a client certificate from Microsoft Active Directory Certificate Services is similar to the process above except

  • The Subject (CN) is configured in a registry value named ClientSubject; default value is StarPipesClient. In the case of a user certificate issued by a Microsoft Certificate Server, this value is the name of the domain user that was used when submitting the CSR via Internet Explorer.

  • Select User or Client Authentication Certificate for Certificate Template or Type of Certificate Needed.

Unless you are using a client certificate from a public certificate authority, make sure that you import the CA certificate of the CA that issued the client certificate into the Trusted Root Certification Authorities folder of the StarPipes server that is configured to require a client certificate - i.e. the CA certificate should exist on both StarPipes systems.

Other Certificate Authorities

The above examples demonstrate the use of Microsoft Active Directory Certificate Services. Depending on your host and client environments, you may need to work with certificates created or used by other certificate mechanisms such as:

  • The Java keytool application, included in the JRE.

  • IBM i Digital Certificate Manager (DCM)

  • IBM Global Security Kit (GSKit), included with IBM DB2 LUW.

  • Commercial third party certificate authorities

If you are using a mix of Certificate Authorities, you may need to export and import certificates between certificate stores.

Below is an example of connecting an IBM System i server running i 7.x as a client to a StarPipes server. If the i 7.1 machine does not trust the CA that issued the Starpipes server certificate, you will get an error "CPD3E3C DDM TCP/IP Secure Sockets error occurred on SSL_Init() - Reason code 23" (reason code 23 is defined as SSL_ERROR_NOT_TRUSTED_ROOT in qsossl.h) when attempting a connection from the i Server to StarPipes.

  • On the Windows machine running StarPipes, use MMC to export the root certificate of your CA to a .ARM file.

  • On the i 7.x machine, Use DCM to create a certificate store and import the ARM file.

  • On the i 7.1 machine, use the following command to access a database called "MYRDB" through a StarPipes server at IP address "myspip" listening on port 448:

ADDRDBDIRE RDB(MYRDB) RMTLOCNAME(myspip *IP) PORT(448) SECCNN(*SSL)


Logging and Tracing

Logging and Tracing tab

StarPipes supports several levels of status reporting. This panel in the Configuration application controls most of the StarPipes tracing and logging capabilities. However, dynamic "toggle tracing" for specific servers and/or connections, is available through the StarPipes Management Console (see Managing StarPipes).

Select a checkbox to enable:

  • Accounting Statistics

  • Event Logging

  • Tracing

These actions are global, and will affect all connections associated with the server you are configuring You can simultaneously select one or more of the logging or tracing options.

configuring Logging for StarPipes

Accounting Statistics

Selecting Enable Accounting Statistics causes StarPipes to log usage information in two files: PIPESUM and PIPEDTL. These are written to the StarQuest\StarPipes\Trace directory under \Documents and Settings\All Users\Shared Documents (Windows XP & Windows Server 2003) or under \Users\Public\Documents (Windows Vista & later). Comma delimiters separate the different field (column) values. Numeric fields will be unquoted, while strings will be double quoted. The PIPESUM and PIPEDTL files can be imported into a spreadsheet for sorting and processing.

The PIPESUM file keeps a record of all client connections and can be used for accounting purposes and to examine usage patterns. If this file already exists, StarPipes appends new records. If you track accounting information, you may want to periodically delete or rename existing files.

Description of PIPESUM log fields:

Field | Description
Connection timestamp | Time connection started.
Connection ID | Unique ID associated with this connection.
Server class | As passed on the EXCSAT, the type of requester.
Machine name | As passed on the EXCSAT, the client's machine name.
User name | As passed on the EXCSAT, the user ID associated with the command.
Computer name | The computer name associated with this command.
EXTNAM | The value in the EXCSAT command for the "EXTNAME" (external name).
DB2 user name | The user ID connected to the host.
RDB host | The DB2 database server name.
Port | The TCP/IP port.
Session | The side information record (LLU:RLU:MODE) used to connect to the host.
IP address of the client | Either host name or IP address.

The PIPEDTL file keeps detailed information per StarPipes connection. The file is updated when a connection terminates. If this file already exists, StarPipes will append new records.

Description of PIPEDTL log fields:

Field

Description

Connection timestamp

Time connection ended.

Connection ID

Unique ID associated with this connection.

Endcode

The end state of StarPipes. The codes are listed in Appendix A.

The most common end state codes are:

0=normal end

2=APPC communications error

35=An error occurred while StarPipes was attempting to write to the TCP socket, i.e. the application terminated abnormally on the PC end.

36=An error occurred while StarPipes was attempting to read from the TCP socket, i.e. the TCP/IP connection was terminated on the Windows system

DB2 user name

The user ID connected to the host.

RDB host

The DB2 database server name.

Bytes sent

Total bytes sent by the client (PC application).

Bytes received

Total bytes received by the client (PC application).

nbrccs

Number of command chains (SQL commands) sent by StarPipes.

If no command chains were sent, no connection to DB2 was established. This indicates a problem with APPC connectivity. If you see only a few command chains being sent, the problem might be a bad userid or bad password.

Elapsed time

Total time of the connection in seconds, including idle time and time waiting for DB2 to respond.

Avg turn

Average turn-around time (in seconds) for StarPipes to receive a request from the PC client and return.

Avg response

Average response time (in seconds) for StarPipes to receive data from DB2 and return data to the PC client.

Subtract AVG TURN from AVG RESPONSE to calculate StarPipes processing time for the client request.

Event Logging

StarPipes has the ability to log both error and informational messages which can be useful for debugging purposes. Selecting Enable Event Logging, provides the opportunity to select your logging level: Error (the default) or Informational.

The Error level causes StarPipes application errors and SNA communications errors to be written to the Windows Event Log. See StarPipes Event Codes, for a list of event codes and messages.

The Informational level logs occurrences of a connection starting and stopping to the Windows Event Log. It does not include error logging.

Tracing

There are two options that you can enable to trace operations of the StarPipes server and/or to trace DRDA data streams. StarQuest Ventures Customer Support may request a trace log to help troubleshoot problems. Trace files are written to the StarQuest\StarPipes\Trace directory under \Documents and Settings\All Users\Shared Documents (Windows XP & Windows Server 2003) or under \Users\Public\Documents (Windows Vista & later).

Enable Debug Tracing. The Enable Debug Tracing option creates a detailed trace file for the StarPipes server and a distinct trace file for each active connection through that server. The trace file for the StarPipes server is called DRDAPIPE.trc. StarPipes creates a trace file for each connection, called SP<connection.id>.<timestamp>.trc. View the trace files with a text editor, such as Notepad.

When you enable the Enable Debug Tracing option you can further select a tracing level: Notify (the default) or Debug.

  • The Notify level traces only when the host (DB2) reports an error. It records the last command change sent by the database and client.

  • The Debug level traces all of the time. It provides a trace of StarPipes calls and also captures the data stream.

If tracing is turned on in the Configuration Tool, it traces on all active connections for the StarPipes Server. Debug tracing may degrade StarPipes performance. If you want to trace a specific connection, or a specific set of connections, use the StarPipes Management Console to toggle tracing on and off dynamically.

Enable DRDA Tracing. The Enable DRDA Tracing option creates a file with a .SQD extension in the StarQuest\StarPipes\Trace directory under \Documents and Settings\All Users\Shared Documents (Windows XP & Windows Server 2003) or under \Users\Public\Documents (Windows Vista & later). The filename indicates the connection ID, using the format SP-<connection.id>-<timestamp>.sqd (such as SP-0FAC-20110505-105812.093.0000.SQD). The DRDA trace files can be read by the StarSQL DRDA Trace Viewer application.

You can control the maximum size and number of DRDA trace files, as well as the ability to either wrap (re-use trace files) or stop when the maximum number of trace files have been used.

  • When you use the checkbox to Enable DRDA Tracing, the default will be a single file of unlimited size for each connection.

  • If you select the radio button for Limit File Size, then the file size field is enabled and you can enter a value in MB. When that size is reached, the trace file is closed and a new one is started; there is no maximum to to number of trace files to create.

  • If you select Roll into Multiple Files, you can specify both the maximum file size and the maximum number of trace files, after which tracing stops.

  • If you select Wrap Multiple Files, you can specify both the maximum file size and the maximum number of trace files; when the maximum number of trace files is reached, tracing continues, re-using the existing trace files.


Notification

The Notification tab allows you to send an email notification when the StarPipes service encounters errors, or encounters errors or warnings. The SMTP mail server must be able to direct email to the user accounts specified in the Recipients list and accept any value as the sender.

Enabling and Disabling Email Notifications

Complete the Email Properties to enable sending notifications from the StarPipes service to one or more email addresses. If you need to disable this feature, unselect the Enable email notifications checkbox. The notification feature and the Test button are enabled only when all required fields have values.

Important: You may need to restart the StarPipes service after modifying the Email Properties.

Email Properties

Complete the following fields to enable the email notification feature. The StarPipes service automatically adds a Subject line to each email that identifies the severity of the notification: StarPipes Information Notification, StarPipes Warning Notification, or StarPipes Error Notification.

Enable email notifications | Select this checkbox to enable email notifications.
Recipient List | Select the Recipient List button to add or delete recipients. For each recipient, select the Add button and enter a valid email address, in the form of name@domain.com.
From | The From field can contain any character string. The text that you enter appears in the From field of the notification email. If one person will receive StarPipes notifications from multiple computers, you can use the From field to identify the computer from which the notification is sent, such as StarPipes Service on COMPUTERNAME. If you are sending the notifications to another person you may want to enter your own email address in the From field, in the form of yourname@domain.com, to help identify the origin of the email and provide a valid address for return communications.
SMTP Server | Specify the Internet address of an SMTP server that provides outgoing email service. An Internet address can be an IPv4 address, an IPv6 address, or a DNS domain name. If the SMTP server requires authentication, enable SMTP Server requires authentication and enter a user and password.
Port | Specify the number of the port on which the SMTP server is listening for sendmail requests. The default port number is 25.
SMTP Server requires authentication | Select this checkbox if your SMTP server requires authentication. Note that this is often optional if the domain of the recipients matches that of the SMTP server.
User ID | User ID for the SMTP server.
Password | Password for the SMTP server.

Click the Test button to send a test email to the specified recipients, and click OK to save the properties. If you want to discontinue sending notifications to email, unselect the Enable email notifications checkbox.

Message Types

In the Message Types pane you select which type of messages you want to receive. You can choose one of the following message categories, with All being the most inclusive.

All | Sends an email when a group of subscriptions completes successfully or encounters warnings or errors. For groups of subscriptions that perform incremental replication, notifications also are sent if there are errors polling the source, if the subscription is paused, and when incremental counters are reset.
Warning and Errors | Sends an email if a group of subscriptions encounters a warning or error.
Errors Only | Sends an email if a group of subscriptions encounters an error.


Event Codes

This is a list of StarPipes codes and messages.

Some messages indicate a problem with your use of an application. An example is the message:

TLA0002: Communication error occurred.

Codes

TLA0000 function request terminated normally

TLA0001 remote system rejected request

TLA0002 communication error occurred

TLA0004 user cancelled Request

TLA0007 usage: required parameters missing

TLA0011 gateway required: . . .

TLA0014 unique_session_name required: . . .

TLA0015 userid required: . . .

TLA0027 Unexpected what-received

TLA0028 remote application protocol error detected

TLA0030 usage: no arguments to procedure

TLA0031 cannot obtain sufficient dynamic memory

TLA0032 application logic error detected

TLA0033 command string too large

TLA0034 open operation failed

TLA0035 write operation failed

TLA0036 read operation failed

TLA0039 could not open message file

TLA0040 could not open log file

TLA0041 Unknown request

TLA0042 flush operation failed

TLA0043 transferring file

TLA0044 local system failure, errno=

TLA0045 Connection <name> was closed by an administrator

TLA0046 Connection <name> was closed for exceeding the idle time limit of %2!s! seconds

TLA0048 StarQuest license request failed - No more connections available

TLA0054 The listener port/address is already in use

TLA0055 Unable to find server certificate for listener

TLA0056 The account StarPipes is running under does not have the authority required to run SSL/TLS connections

TLA0057 The configuration of the machine that StarPipes is running on does not support SSL/TLS

TLA0058 Failed to create listener. Check machine configuration or policy settings for the account under which StarPipes is running

TLA0059 Failed to connect to license server during StarPipes service startup.

TLA0060 The service license has expired, no listeners can be enabled

TLA0061 No license has been configured, no listeners can be enabled

TLA0062 Unable to contact license server during StarPipes connection setup

TLA0063 StarPipes connection rejected, license expired

TLA0064 StarPipes connection rejected, no more licenses available

TLA0065 StarPipes connection rejected, no license has been configured

TLA0066 StarPipes connection terminated, license has been revoked

TLA0067 Unexpected license error encountered during StarPipes connection setup

TLA0068 Service license acquired, starting listeners

TLA0069 An unexpected internal error encountered during a configuration operation

TLA0070 Client connection from %1!s! to RDB %2!s! was terminated due to idle timeout (%!s! seconds)%.

TLA0100 <APPC subsystem errors>

Communications Messages for StarPipes

This is a list of codes and their corresponding messages from the host and indicate communication and SNA server status.

TLC0000 Receive & wait

TLC0003 Deallocate (local)

TLC0008 Send data

TLC0009 Open gateway

TLC0010 Allocate (source)

TLC0013 Prepare to receive


Managing StarPipes

Use the StarPipes Management Console to monitor the status of the StarPipes server and the active connections. From the StarPipes Management Console you can administer servers, connections, and tracing. You can install only the StarPipes Management Console on a Windows computer from which you want to manage other computers that are running StarPipes. See Installing StarPipes for information on installing only the StarPipes Management Console tool.

The left pane of the StarPipes Management Console displays a list of StarPipes servers that you have defined. If no servers appear, select Add from the Server menu. The right pane of the main window displays active connections.

StarPipes Management Console

To manage any of the StarPipes servers or connections, select the item, and then select a command from.

  • the menu bar,

  • the shortcut menu that appears when you select an item and right-click the mouse, or

  • the toolbar, which displays icons for common tasks.


Managing Servers

You can use the Management Console to:

  • Add a Server

  • Remove a Server

  • View Server Properties

StarPipes servers are displayed on the left pane of the Management Console. An active StarPipes server has an icon with a green arrow pointing up ( service is running). An inactive StarPipes server has a red arrow pointing down ( service is not running).

Adding a Server

You can add a StarPipes server and subsequently have the ability to view its active connections.

To add a server:

  1. From the Server menu bar, select Add or click on the icon for new server.

  2. Enter the TCP/IP host name of the computer or the IP address where the StarPipes Server is installed. If it is the computer you are using, you can select the default [Local Machine].

  3. Click OK to add the server.

After you add the StarPipes server, it's name appears in the left pane.

Removing a Server

Removing a StarPipes server from the Management Console only deletes it from the list of StarPipes servers being managed.

To remove a server:

  1. From the Server menu bar, select Remove or click on the Delete icon on the toolbar.

  2. Click OK to confirm removing the server.

View Server Properties

This option displays the StarPipes Configuration Application menu. If you want to stop or start a StarPipes server, use the Service Control panel of this application.

To view server properties from the Server menu bar, select Properties or click on the Properties icon on the toolbar.

For more information see Using the StarPipes Configuration application.


Managing Connections

You can use the Management Console to:

  • View a Connection

  • Kill a Connection

Active StarPipes connections are displayed in the right pane. To refresh the display, click on the Refresh icon from the toolbar, press F5, or choose View Refresh from the menu bar. To sort the active connections into different categories, click on the column header on the right pane. A count of all the active connections is displayed in the lower left corner of the Management Console. You can also view the count of active connections in the Configuration Application Service panel.

Viewing a Connection

The right pane displays session details including connection id, username, RDB name, and the client application name. Information may vary according to the ODBC driver being used and whether it is 32-bit or 16-bit. This pane also allows you to trace a specific connection or terminate an active one.

The StarPipes Management Console displays the following fields:

Field | Description
Connection ID | The Windows process ID associated with this connection.
Username | The user ID used to login into DB2 as passed on the EXCSAT. This field may be blank if password encryption is used.
RDB name | The DB2 database server name and the relational database name specified in the StarSQL data source setup. This value is used to route the connections.
Client Application (EXTNAM) | The value in the EXCSAT command for EXTNAM. This value may vary depending on your ODBC or JDBC driver. If you are using StarSQL, the client machine login, the application name and the StarSQL version are displayed.
Connect time | Total time of the connection, including idle time and time waiting for DB2 to respond. The format is HH:MM:SS.
Idle time | The total idle time since the last client activity. Each time the connection becomes active, the idle timer is reset. The format is HH:MM:SS.
Avg turn | Average turn-around time in seconds for StarPipes to receive a request from PC client and return DB2 response.
Avg rsp | Average response time in seconds for StarPipes to receive data from DB2 and return data to PC client. Subtract the average turnaround time from average response to calculate the average StarPipes processing time for the client request
Bytes sent | Total bytes sent by the client.
Bytes rcvd | Total bytes received by the client
#CCs | The number of command chains (SQL commands) sent by StarPipes
Client IP | The IP address of the client machine.
Route (CSI) | The connection parameters that StarPipes uses to connect to DB2. If the connection is an SNA-APPC connection, the format is Local LU:Remote LU: Mode. If the connection is a native TCP/IP connection, the format is RDBNAME:Listening Port:*TCPIP. If the connection is an SSL connection, the format is RDBNAME:Listening Port:*SSL.
Trace | The status of tracing for this connection.

Killing a Connection

To kill a connection:

  1. Highlight the connection you want to terminate.

  2. Right-click and select Kill from the context menu.


Managing Dynamic Tracing

Dynamic Tracing

You can dynamically start and stop tracing for each StarPipes server or for a specific StarPipes connection.

To trace a connection:

  1. Highlight the connection to be traced.

  2. Right-click and select trace to toggle the tracing status. Select the type and level of tracing. The icon for the connection will change to a bright yellow arrow.

To trace a server and all of its connections:

  1. Highlight the server to be traced.

  2. Right click and select trace to toggle the tracing status.

  3. Select the type and level of tracing. The icon for the server and any exiting connections will change to a bright yellow arrow.

For more information about the different tracing levels, see Logging and Tracing.


Host and Network Connections

The Distributed Relational Database Architecture (DRDA) is an open architecture that allows disparate applications and database systems to communicate and interoperate. DRDA communications can occur over multiple network transport protocols.

Each level of DRDA implementations has increased the level of support for distributed computing. Along with other significant enhancements, DRDA Level 3 introduced support for direct TCP/IP connections. DB2 hosts that support DRDA Level 3 or later can use either of the following network protocols to communicate with client computers:

  • SNA LU 6.2, which exchanges commands and data as SNA LU 6.2 conversations.

  • TCP/IP, which uses Distributed Data Management (DDM) commands to send requests and replies between the requester and the database server.

StarPipes for Windows can transfer the incoming messages as SNA-APPC conversations to DB2, or allow the TCP/IP messages to flow directly to the DB2 host unchanged. The DB2 system must support DRDA over TCP/IP to receive TCP/IP messages unchanged. (Refer to System Requirements for a list of the DB2 versions that support native TCP/IP connections.)

Be sure to review the topic, DRDA Security Flows, if you want to allow StarPipes to pass encrypted user IDs and passwords to a DB2 host.


DRDA Security Flows

DRDA Level 3 introduced support for TCP/IP connections. DB2 hosts that support DRDA Level 3 or later can use either the SNA LU 6.2 or TCP/IP network transport protocols, as described in Host and Network Connections.

DRDA Level 3 also provided for enhanced security with support for DRDA authentication security mechanisms. DRDA Level 3 allows encryption flows to both TCP/IP and APPC hosts. When StarPipes is supporting encrypted security, it passes the encrypted flows to the DB2 host unchanged.

For clients and hosts that support DRDA Level 3 or later, an encrypted user ID and password can be sent in the security check (SECCHK) command to the security manager rather than in the SNA conversation.

To support encrypted DRDA flows to an SNA network, the DB2 host must be configured to accept SNA conversation requests with SECURITY(NONE). To help avoid security exposures you may want to:

  • configure dedicated LUs to support conversations with this minimal level of security. With Session-Level Security configured between the local and remote LUs, each LU-LU partner uses a unique key to authenticate each other.

  • Restrict the applications that are allowed to attach to a Local LU that is configured to allow flows to pass with SECURITY(NONE). For example, you might restrict use of the Local LU to STARPIPES.

The procedures for implementing security differ depending on the version of DB2 that you are using and the operating system and network protocol being used. Refer to the IBM documentation for your DB2 system for details about implementing security. For example, if you are running DB2 for z/OS v8, the DB2 UDB for z/OS V8 Administration Guide (SC18-7413-04), may be particularly useful.


Setting Up Microsoft Host Integration Server

Setting Up the Microsoft Host Integration Server

The following tables summarize the correspondence between the Microsoft Host Integration Server properties and key VTAM and DB2 parameters. For complete information, see the Microsoft SNA Server documentation.

If you want to allow StarPipes to pass encrypted user IDs and passwords to the Host Intergration Server, be sure to review the topic, DRDA Security Flows,

Microsoft HIS APPC Mode Property | MVS/OS390 Parameter
Session Limit | DSESLIM from APPL Definition
Min Con Winners | DMINWNR from APPL Definition
Min Con Losers | DMNWNL from APPL Definition
Autoactivation Lim | AUTOSES from APPL Definition
Pacing Send Count | SRVPAC from mode table entry
Pacing Recv Count | PSNDPAC from mode table entry
Max Send RU | RUSIZES from mode table entry
Max Receive RU | RUSIZES from mode table entry
Microsoft HIS Server Property | MVS/OS390 Parameter
Control Point Name | CP Name defined in the PU in VTAM, or PU name if CPNAME is not defined
Network Name | VTAM Network ID
Microsoft HIS Connection Property | MVS/OS390 Parameter
Local Block Number | IDBLK in VTAM-PU/LU
Local Node Number | IDNUM in VTAM-PU/LU
Control Point Name | CP Name defined in the PU in VTAM, or PU name if CPNAME is not defined
Network Name | VTAM Network ID
Remote Network Address | Host Network Address


Setting Up IBM Communications Server

Configuration of IBM Communications Server

To use StarPipes for Windows with IBM Communications Server for Windows, configure an SNA Gateway to your host. You will need to create a node, device, connection, local LU6.2, partner LU6.2, and mode.

For clients and hosts that support DRDA Level 3 or later, an encrypted user ID and password can be sent in the security check (SECCHK) command to the security manager rather than in the SNA conversation. If you want to allow StarPipes to pass encrypted user IDs and passwords to the IBM Communications Server, be sure to review the topic, DRDA Security Flows,

Configuration in StarPipes

During configuration of StarPipes for Windows, you will be asked to supply the names of the local LU6.2, partner LU6.2, and mode. Be sure that these names are in upper-case in the IBM Communications Server configuration.


Preparing DB2/MVS Hosts

Preparing DB2 for z/OS Hosts

The Distributed Data Facility (DDF) is a component of DB2 for z/OS. Its primary task is to process Distributed Relational Database Architecture (DRDA) requests. DDF must be active for a desktop to connect to DB2 using StarSQL.

If your organization has not implemented distributed database capabilities, DDF may not be configured and active.

Preparing a z/OS host for access through StarSQL primarily involves configuring DDF. This section highlights some aspects of that task that are especially important for supporting a connection through StarSQL. It covers:

  • Virtual Telecommunications Access Method (VTAM)

  • APPL Statement

  • DDF Record in BSDS

  • Starting DDF

  • SYSIBM.SYSLUNAMES Table

  • SNA Server or Stack Software Configuration

  • Configuring SSL for DB2 for z/OS

For complete information about configuring DDF, consult IBM’s DB2 for z/OS installation documentation.


Virtual Telecommunications Access Method (VTAM)

VTAM handles network communications for MVS for direct VTAM and SNA gateway configurations. The VTAM programmer creates a mode table entry and a major node definition in VTAM for the StarSQL connection.

Consult your VTAM documentation for detailed instructions on configuring VTAM.

If you are using direct TCP/IP to connect to the host, this topic is not applicable.

Logmode Table Entry

The logmode table entry contains information governing how conversations take place in VTAM. It defines pacing, RU sizes and COS (class of service parameters).The mode entry can be placed in any mode table under VTAM — the default mode table or the one used in the APPL statement (see APPL Statement below) for DB2's LU definition.

One of the most important entries in the logmode table is the PSERVIC field, which identifies the LU traffic protocols. Set the value of PSERVIC value as follows:

  • If you are using an independent LU, set PSERVIC=X'060200000000000000002F00'.

  • If you are using dependent LUs, set PSERVIC=X'060200000000000000002C00'.

The LU dependent/independent status affects the value of the PSERVIC setting in the mode table entry. In general, independent LUs are preferable, since ODBC applications often require more than the one connection permitted by dependent LUs.

Record the LOGMODE name. In the example below the LOGMODE is LU62STAR. You will need to use the same name for DLOGMODE in the major node definition and again for SNA configuration.

This is an example of a mode table entry with an independent LU:

LU62STAR MODEENT LOGMODE=LU62STAR,
FMPROF=X'13',
TSPROF=X'07',
PRIPROT=X'B0',
SECPROT=X'B0',
COMPROT=X'50A1',
RUSIZES=X'8989',
TYPE=0,
PSNDPAC=X'03',
SRVCPAC=X'03',
SSNDPAC=X'02',
PSERVIC=X'060200000000000000002F00'

This is an example of a mode table entry with a dependent LU:

LU62STAR MODEENT LOGMODE=MLU62A,
FMPROF=X'13',
TSPROF=X'07',
PRIPROT=X'B0',
SECPROT=X'B0',
COMPROT=X'50A1',
RUSIZES=X'8989',
TYPE=0,
PSNDPAC=X'03',
SRVCPAC=X'03',
SSNDPAC=X'02',
PSERVIC=X'060200000000000000002C00'

Major Node Definition

The VTAM programmer creates a major node definition for the connection to the DB2/ MVS host from the desktop. You can use a switched, non-switched, or channel attach major node. Switched major nodes are most commonly used with StarSQL.

In the major node definition, the DLOGMOD must match mode table entry LOGMODE.

Record these major node configuration values: PU name, IDBLK, IDNUM, CPNAME, LU, DLOGMODE. You will need them later for SNA configuration.

This is an example of a major node definition with an independent LU:

STAR2 PU ADDR=02,
IDBLK=05D,
IDNUM=10092,
CPNAME=PC0IYG01,
DLOGMOD=LU62STAR,
MODETAB=MODELU62,
SSCPFM=USSSCS,
PUTYPE=2,
MAXDATA=521, MAXPATH=1, PASSLIM=4,
DISCNT-NO,
ANS=CONT,
PACING=0

INDLOCAL LU LOCADDR=0, PACING=0, VPACING=0

This is an example of the configuration of a PU with dependent LUs:

STAR1 PU ADDR=01,
IDBLK=05D,
IDNUM=10092
SSCPFM=USSSCS,
ISTATUS=ACTI
MAXDATA=521
MAXOUT=7
PASSLIM=15,
DLOGMOD=D4C32782
MODETAB=ISTINCLM,
IRETRY=NO
RETRIES=(,4,3),
PUTYPE=2,
VPACING=0

LOCALLU1 LU LOCADDR=2
USSTAB=USSTAB01,
DLOGMOD=MLU62A,
ID=LU1
MODETAB=MTSNA

LOCALLU2 LU LOCADDR=3
USSTAB=USSTAB01,
DLOGMOD=MLU62A,
ID=LU2
MODETAB=MTSNA

LOCALLU3 LU LOCADDR=4
USSTAB=USSTAB01,
DLOGMOD=MLU62A,
ID=LU3
MODETAB=MTSNA

LOCALLU4 LU LOCADDR=5
USSTAB=USSTAB01,
DLOGMOD=MLU62A,
ID=LU4
MODETAB=MTSNA


APPL Statement

The APPL statement defines the DB2 subsystem to VTAM to support remote access.

If the APPL statement does yet not exist, you must create it. If a password is required for VTAM to communicate with DB2 in your environment, specify it in the APPL statement.

Record the ACB name and the password, if you specified one. The ACB name is the word immediately preceding the APPL parameter in the APPL statement. For example, the ACB name is LUDB2T in the example below. You will need this information when you configure DDF with the inventory change log utility.

Following is an example APPL statement:

DB2APPL VBUILD TYPE=APPL
LUDB2T APPL AUTH=(ACQ),
APPC=YES,
AUTOSES=1,
DMINWNL=10,
DMINWNR=10,
DSESLIM=20,
MODETAB=MODEDB2,
SECACPT=ALREADYV,
SRBEXIT=YES,
VERIFY=NONE,
VPACING=2


DDF Record in BSDS

To obtain system installation parameters during startup, DB2 reads the BSDS (Bootstrap Data Set). One of the records stored in the BSDS is the DDF record. This record contains information used by DDF to connect to VTAM.

If you are installing DB2, use the DDF installation panel DSNTIPR to provide:

  • DDF location name

  • DDF LUNAME

  • Password used when connecting DB2 to VTAM, if a password is required

If DB2 is already installed, use the change log inventory utility (DSNJU003) to update this information in BSDS.

Record the DDF location name. You will use it for the Database Server Name during data source configuration on the desktop. You can also determine the DDF location name from the syslog. Look for a DB2 message DSNL004I (starting DDF) that contains the location name. Also record the DDF LUNAME, which you will need for SNA configuration.

This is an example of a BSDS updated with a location name of STARDB, LU name of DSNV510, and a password of STARPASS.

//*
//DSNTLOG EXEC PGM=DSNJU003,COND=(4,LT)
//STEPLIB DD DISP=SHR,DSN=DSN510.SDSNLOAD
//SYSUT1 DD DISP=OLD,DSN=DSN5CAT.BSDS01
//SYSUT2 DD DISP=OLD,DSN=DSN5CAT.BSDS02
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DDF LOCATION=STARDB,LUNAME=DSNV510,
PASSWORD=STARPASS,RESPORT=5020,PORT=446
//*

If your system does not require a password to connect DB2 to VTAM, leave the PASSWORD field blank.

The PORT and RESPORT parameters are required for TCP/IP access. If you are using SNA only, you can omit them.


Starting DDF

If DDF has not already been started, start it with the command:

-START DDF

The START DDF command requires authority of SYSOPR or higher.

When DDF starts successfully, the following messages are displayed:

DSNL003I - DDF IS STARTING

DSNL004I - DDF START COMPLETE LOCATION locname LU netname.luname

If DDF has not been properly installed, the START DDF command fails and displays the following message:

DSN9032I - REQUESTED FUNCTION IS NOT AVAILABLE

If DDF has already been started, the START DDF command fails and displays the following message:

DSNL001I - DDF IS ALREADY STARTED


SYSIBM.SYSLUNAMES Table

The SYSIBM.SYSLUNAMES table defines the network attributes of remote systems on DB2/MVS v4.1. To enable communication between StarSQL and the DB2/MVS host, there must be an entry in this SYSIBM.SYSLUNAMES table. On DV2/MVS 5.1 (DB2 for OS/390), the name of this table is SYSIBM.LUNAMES.

The SYSIBM.SYSLUNAMES /SYSIBM.LUNAMES columns are:

LUNAMES | This is the LUNAME of the remote system. An empty string means that any LU is valid for this row.
SYSMODENAME | This is the VTAM logon mode name used for DB2 for MVS/ESA intersystem conversations. A blank indicates that IBMDB2LM should be used.
USERSECURITY | This describes the network security acceptance options required of the remote system when the DB2 for MVS/ESA system acts as a server for the remote system (inbound security requirements).
ENCRYPTPSWDS | This indicates whether passwords exchanged with this partner are encrypted.
MODESELECT | If ‘Y’, the SYSMODESELECT table is used to obtain the mode name for each outbound distributed database request. If not ‘Y‘, the mode name IBMDB2LM is used for system-directed access requests, and the mode name IBMRDB is used for DRDA requests.
USERNAMES | This is the level of come-from checking and user ID translation required. It also specifies the security parameters this DB2 for MVS/ESA subsystem uses when requesting data from the remote partner (outbound security requirements).‘I‘ indicates an "inbound" ID is subject to translation. ‘O‘ indicates an "outbound" ID, sent to the corresponding LUNAME and subject to translation. &lsquo;B&rsquo; indicates that both inbound and outbound IDs are subject to translation. A blank indicates no translation for inbound or outbound IDs.
SECURITY_IN | This column defines the security options that are accepted by this host when an SNA client connects. It is only in SYSIBM.LUNAMES, not SYSIBM.SYSLUNAMES. V for verify indicates that the incoming connection request must include a password. A for already verified indicates that the request does not require a password, although the password is checked if it is sent. This column is not used by StarSQL.
SECURITY_OUT | This column defines the security option that is used when local DB2 SQL applications connect to any remote server associated with this LUNAME. It is only in SYSIBM.LUNAMES, not SYSIBM.SYSLUNAMES. A for already verified indicates that outbound connection requests contain an authorization id and no password. P for password indicates that outbound connection requests contain an authorization id and password. R for RACF PassTicket indicates that outbound connection requests contain a userid and RACF PassTicket. This column is not used by StarSQL.

This command inserts a row that any LU can use. The value of the LUNAME column is an empty string:

INSERT INTO SYSIBM.SYSLUNAMES (LUNAME, SYSMODENAME, USERSECURITY, ENCRYPTPSWDS, MODESELECT, USERNAMES) VALUES (' ',' ', 'C', 'N', 'N', '');

This command inserts a row for a specific LU named RLU4 :

INSERT INTO SYSIBM.SYSLUNAMES (LUNAME, SYSMODENAME, USERSECURITY, ENCRYPTPSWDS, MODESELECT, USERNAMES) VALUES ('RLU4', ' ', 'A', 'N', 'N', ' ');


SNA Server or Stack Software Configuration

If communication between the desktop and the host uses SNA, you must configure the SNA Server or SNA stack software.

Keep in mind these relationships between SNA settings and the values configured in VTAM:

  • For the Mode Name setting, use the VTAM major node value for DLOGMOD, which should also match the LOGMODE value in the mode table entry.

  • For the Control Point Name setting, use the VTAM major node CPNAME.

  • For local APPC LUs associated with the server, use the VTAM major node LU name or names.

  • For the connection to DB2/MVS, set the Local Block Number to the IDBLK value in the VTAM major node PU definition. Set the Local Node Number to the IDNUM value in the VTAM major node PU definition.

  • For the remote APPC LUs assigned to the DB2/MVS connection, set the LU Alias, the LU Name, and the Uninterpreted LU Name to the LUNAME used when you configured the DDF record for BSDS. The LUNAME should match the ACB name in the VTAM APPL statement.

Consult your SNA Server or SNA stack documentation for detailed SNA configuration instructions.


Configuring SSL for DB2 for z/OS

To configure a DB2 for z/OS host system for SSL communications, you must be using DB2 for z/OS 9.1 or later. Refer to the section Encrypting your data with Secure Socket Layer support in the DB2 for z/OS documentation.

You must configure AT-TLS (z/OS® Communications Server IP Application Transparent Transport Layer Security) as well as configuring the DB2 server.

The listening port number (typically 448) is specified in the DRDA SECURE PORT field of the Distributed Data Facility Panel 2 (DSNTIP5) during DB2 installation. After initial installation, you can update the SECPORT parameter of the DDF statement in the BSDS with the change log inventory (DSNJU003) stand-alone utility.

The following IBM Redbooks may also be of assistance:

Securing and Auditing Data on DB2 for z/OS (SG24-7720)

DB2 9 for z/OS: Distributed Functions (SG24-6952-01)


Preparing DB2/UDB Hosts

Preparing DB2 for Linux, UNIX & Windows Hosts

Note: Support for the SNA protocol was discontinued in DB2 LUW v8. As a result, StarPipes no longer supports connecting to DB2 LUW via SNA; only direct TCP/IP and SSL connections are supported.

The following topics are covered in this section:

  • Configuring SSL for DB2 LUW

For complete information about setting up DB2 LUW, consult IBM’s installation documentation.


Configuring SSL for DB2 UDB

Configuring SSL for DB2 for LUW

For DB2 LUW 9.7 & later:

Refer to the Configuring Secure Sockets Layer (SSL) support in a DB2 instance chapter in the DB2 documentation for details.

The following is an example of using self-signed certificates.

Use GSKit to create a keystore file (certificate database) and a certificate. Export the certificate if desired:

C> cd C:\Program Files\ibm\gsk8\bin\gsk8capicmd

C> gsk8capicmd -keydb -create -db "mydbserver.kdb" -pw "mypassword" -stash

C> gsk8capicmd -cert -create -db "mydbserver.kdb" -pw " mypassword " -label "SelfSigned" -dn "CN=myhost.mydomain.com,O=MyCompany,OU=CustomerSupport,L=California,ST=ON,C=CA"

C> gsk8capicmd -cert -extract -db "mydbserver.kdb" -pw "mypassword" -label "SelfSigned" -target "MYHOSTserver.arm" -format ascii -fips

On UNIX, make sure that the DB2 instance owner has read access to the keystore file.

Update DB2 and restart it:

C> db2 update dbm cfg using SSL_SVR_KEYDB "C:\Program Files\ibm\gsk8\bin\mydbserver.kdb"

C> db2 update dbm cfg using SSL_SVR_LABEL SelfSigned

C> db2 update dbm cfg using SSL_SVR_STASH "C:\Program Files\ibm\gsk8\bin\mydbserver.sth"

C> db2 update dbm cfg using SSL_SVCENAME 50029

C> db2set -i db2 DB2COMM=SSL,TCPIP

C> db2stop

C> db2start

Note that there is a problem in DB2 LUW 9.7 fp3 (resolved in fp4); see IC72728: THE PORT NUMBER FOR SSL_SVCENAME IN THE SERVICE FILE IS USED FOR SVCENAME. The value specified for SSL_SVCENAME is being used for both SSL and non-SSL listeners, causing a conflict. The workaround is to set the SVCENAME parameter using an explicit port number:

C> db2 update dbm cfg using SVCENAME 50000

For DB2 LUW 9.1 & 9.5:

The procedure is similar to the above instructions for DB2 LUW 9.7, except

  • The gskit is v7 rather than v8 (e.g. run C:\Program Files\ibm\gsk7\bin\ gsk7capicmd instead of C:\Program Files\ibm\gsk8\bin\gsk8capicmd)

  • Rather than using DBM configuration, the DB2 SSL parameters are stored in a configuration file sslconfig.ini located in the following directory:

  • Linux and UNIX: INSTHOME/cfg/SSLconfig.ini

  • Windows: INSTHOME/SSLconfig.ini

where INSTHOME is the home directory of the instance.

Here is a sample sslconfig.ini:

DB2_SSL_KEYSTORE_FILE=C:\Program Files\ibm\gsk7\bin\mydbserver.kdb

DB2_SSL_LISTENER=50448

DB2_SSL_KEYSTORE_PW=mypassword

DB2_SSL_KEYSTORE_LABEL=SelfSigned

After configuring gsk7 and creating sslconfig.ini, enter db2set -i db2 DB2COMM=SSL,TCPIP and restart DB2


Preparing DB2 for i Hosts

The following topics are covered in this section:

  • Configuring SSL on DB2 for i


Configuring SSL on DB2 for i

To configure a System i host system to use the Secure Sockets Layer (SSL) protocol you must have the following components:

  • Digital Certificate Manager - option 34 of 5722-SS1 (v5r4), 5761-SS1 (6.1), or 5770-SS1(7.x)

  • TCP/IP Connectivity Utilities - 5722-TC1(v5r4), 5761-TC1 (6.1), or 5770-SS1 (7.x)

  • IBM HTTP Server - 5722-DG1 (v5r4), 5761-DG1 (6.1) or 5770-DG1 (7.x)

Following are general procedures for configuring SSL on the IBM i host. Refer to your IBM documentation for details, especially the IBM i product documentation and the IBM Redbook IBM iSeries Wired Network Security OS/400 V5R1 DCM and Cryptography Enhancements (GSG24-6168).

  1. Start the Admin HTTP instance. To verify that it is running, enter WRKACTJOB JOB(ADMIN). If it is not running, start it with STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN).

  2. Use a browser and the URL https://myas400:2001 to connect to the Digital Certificate Manager. On i 6.1 and later, this URL will redirect you to IBM Navigator for i, running on port 2005; from there, select IBM i Tasks Page to see the previous version of the 2001 port tasks, which includes the Digital Certificate Manager.

  3. Create a local Certificate Authority or obtain a certificate from a public Internet Certificate Authority.

  4. Create a *SYSTEM certificate store.

  5. Use “Manage Applications” to assign a server certificate to the OS/400 DDM/DRDA server.

  6. After you assign the certificate, restart the DDM/DRDA server:

  7. ENDTCPSVR *DDM

  8. STRTCPSVR *DDM

  9. If necessary, set the port on which the DDM/DRDA server listens for SSL conversations. Use WRKSRVTBLE to view and modify service table entries; the entry for SSL is ddm-ssl, and the default value is 448.


Prepaing Derby Hosts

Preparing Derby Hosts

The following topics are covered in this section:

  • Configuring SSL for Apache Derby


Configuring SSL for Apache Derby

To enable SSL support, use the ssl keyword on the command line when starting the Network Server, or specify the derby.drda.sslMode property in derby.properties.

In addition, you will need to create a server key pair, and you will need to specify the keystore and password when starting the server. For more information about key and certificate handling see http://db.apache.org/derby/docs/10.4/adminguide/cadminsslkeys.html

  1. Run keytool to create the key pair. keytool is located in the JRE bin directory:

keytool -genkey -alias myDatabase -keystore serverKeyStore.key

You will be prompted for various values, such as Name, Organization, etc. One of those parameters will be the password for access to the keystore.

Name: ..

Organization: ...

....

password: myPassword

  1. Specify the keystore and password and the ssl keyword when starting the server:

java -Djavax.net.ssl.keyStore=serverKeyStore.key \

-Djavax.net.ssl.keyStorePassword=myPassword \

-jar %DERBY_HOME%\lib\derbyrun.jar server start -h 0.0.0.0 -p 446 -ssl basic


Cleaning Up Client License Connections

Cleaning Up Client Connections

The StarPipes server uses the system TCP/IP KeepAlive parameter settings to clean up connections from clients that have disconnected from the network without releasing their connection to the host. The default values for the KeepAlive parameter should be sufficient for most users, but you can change them if necessary, such as to clean up abandoned license connections more frequently. The KeepAlive parameter names vary by operating system but generally specify:

  • the interval to wait before probing the idle connection (on most platforms the default is 2 hours)

  • the interval to wait before retrying the probe after an initial failure to respond

  • the maximum number of times to retry the probe

Modifying the KeepAlive parameter settings may affect the operation of other applications on the computer. You also may want to set additional TCP/IP parameters that affect TCP connections, depending on the overall impact to other TCP/IP parameters after you modify the KeepAlive settings.

This technical document describes the general steps for displaying and modifying the KeepAlive parameter settings.

The following table shows the names of the KeepAlive parameters:

Table 1: KeepAlive Parameters

Operating System | Parameter wait time before probing the connection | Parameter interval between retry probes | Parameter maximum retry probes | Unit of measure
Windows | KeepAliveTime | KeepAlive Interval | TcpMaxDataRetransmission | milliseconds

(1): tcp_keepalives_kill cannot be modified on HP. It is set to 1.

Displaying and Modifying KeepAlive Values

Follow these steps to modify the values.

  1. Log in as an Administrator on the Windows computer running StarPipes.

  2. To display information about the network tuning parameters:

Platform | Operating System Command
Windows | Refer to http://technet.microsoft.com/en-us/library/bb726981.aspx#EDAA

  3. Display the current KeepAlive settings:

Platform | Operating System Command
Windows | From the Start menu, choose Run and enter regedit to view the parameter located in the Registry file HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Tcpip\Parameters

  4. Display the range of available settings:

Platform | Operating System Command
Windows | Refer to http://technet.microsoft.com/en-us/library/bb726981.aspx#EDAA.

  5. Modify the KeepAlive values as desired.

Platform | Operating System Command
Windows | Run regedit to edit the Windows Registry key located in the path HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Tcpip\Parameters. After you change the Registry value you must restart the computer for the change to take affect.


Configuring Authentication Parameters

If you are using DB2 with IBM Communications Server or Microsoft Host Integration Server, you need to set the authentication parameter to client. Be aware that this reduces the level of the database security.

To set the authentication parameter on Windows, enter the following command in the Command Line Processor within the DB2 for Windows (Common) Group, or preface it with the db2 command if you enter it from the operating system command-line prompt:

update database manager configuration

AUTHENTICATION CLIENT

If you are using TCP/IP or any SNA stack other than Communications Server or Microsoft Host Integration Server, the authentication parameter should be set to server, which is the default.


Creating DB2CLI.PROCEDURES

Create the DBCLI.PROCEDURES table on the host before attempting to access the DB2 database through StarSQL.

On Windows Hosts

  1. Start DB2.

  2. Start a DB2 command window.

  3. Change directory (cd) to C:\SQLLIB\MISC.

  4. From the C:\SQLLIB\MISC directory, run the connect command to connect to the database:

DB2 CONNECT TO <database_name>

  5. From the C:\SQLLIB\MISC directory, run the STROPPROC.DDL command:

db2 -TF STORPROC.DDL

STORPROC.DDL is a text file. You can read it for more detailed instructions for its usage.

On UNIX Hosts

  1. Start DB2.

  2. Log on as the owner of the DB2 instance.

  3. Change directory (CD) to sqllib/misc.

  4. From the sqllib/misc directory, run the connect command:

DB2 CONNECT TO <database_name>

  5. From the sqllib/misc directory, run the STROPPROC.DDL command:

db2 -tf STORPROC.DDL


Recording the Database Name

Record the name of the DB2 database. You will use it for the Database Server Name during data source configuration on the desktop.