John Alvord, IBM Corporation

jalvord@us.ibm.com

Draft #1 – 18 March – Level 1.00000

Follow on twitter

Inspiration

When you use Portal Client sessions which connect to a Portal Server [TEPS] with the default interfaces, everything is simple. You sometimes have to clear a Java Cache but otherwise Things Just Work. That is when you are connecting via the http protocol to the default port [15200 from ITM 623] and not using any secure communications. When you stray from the default settings things get more complex. This document explains the background and implementation to handle non-default configurations.

The TEPS Interface [TEPSI] represents how a TEP user connects. Many users will use the default definition, however some sites will require TEPSI definitions, each with their own name. For example one TEPSI could represent a user connecting beyond a firewall which needs a different ip address and port. Another TEPSI could represent a secure communication connection. A third TEPSI could represent a connection which is limited to using one specific TEPS ip address or interface. There are many possibilities and many can be in service at the same time.

Background

Default TEP to TEPS Communication

In all cases TEP to TEPS communication architecture uses two independent communication methods. At first connection, the TEP uses HTTP(S) to a web server. The URL needs hostname or ip address for the TEPS and port 15200. Before ITM 623, the connection port was always default 1920. After 623 there was a default IHS web server at port 15200. However the TEPS can be configured to the earlier port if desired. During this first startup phase the needed java files are loaded and then given control.

After startup, the portal client uses CORBA IIOP communications. During the startup phase, the client retrieves an Interoperable Object Reference [IOR] object. The IOR contains the ip address and port number to be used to connect to the server for IIOP work. It also has many other values. This allows the Java user interface logic at the TEP to work smoothly with the C/C++ TEPS logic. The IOR is generated by the TEPS Interface definition.

You can specify to use just http protocol. In that case you communicate only with the web server. However the web server currently uses the default iiop to work with the TEPS.

Variation 1 – Secure Communications

The initial stage can use https [secure communications] by connecting to the default https/15201 ports.

The second IIOP stage can also be configured to use secure communications. This could be a changed default IOR or by a second IOR for the purpose.

Variation 2 – NATing firewall

In this setup the TEP is behind a Network Address Translation Firewall. In this configuration the TEP connects to a given ip address and port which communicates to the Portal Server and appears in the usual way as if it was arriving at the normal address like 15200 or 15201.

The related TEPSI also needs to have the TEP side ip address and port set in the IOR so the Java/C++ communications connection will work smoothly.

Variation 3 – Fixed TEPS interface

The TEPS IIOP communications can be forced to one specific interface or ip address. This might be for a TEPS which was working with multiple companies as a service. Each company might require that its communications be transmitted on its own communications path. That does not affect the initial startup phase, where java program objects are being set up, but when company data is being transmitted, they want isolation.

Variation 4 – HTTP mode

A recent addition is where the TEP to TEPS is pure HTTP [or HTTPS]. In this mode, TEP communicates to the web server at 15200 [for example] and the web server does the IIOP communications to the TEPS.

Future Variations

There will very likely be future variations.

Background Summary

Whenever you need non-default TEP connections, you will need multiple TEPSIs. One easy example is if you are using default configuration and one set of users ask to use secure communications and you need to support both secure and default. In that case you create a second TEPSI with a separate name. Maybe a third group requires a NATing firewall TEP. In that case you need a third TEPSI with another name.

The rest of the document shows how you create TEPSI object in Linux/Unix and in Windows. There is a second piece of work required to make use of TEPSI objects. Jar description files are used to get the jar files loaded. There will be one set of those jar description files for each of the TEPSI objects. See this blog post for a convenient and mostly automated way of creating those files base on the default files.

Linux/Unix TEPSI objects

The following is a quote from the installation guide. It is followed by explanations to cover all the possible uses and clarify usages.

Begin quote from manual:

“Defining a Tivoli Enterprise Portal Server interface on Linux or UNIX”

To define an additional Tivoli Enterprise Portal interface on Linux or UNIX, edit the install_dir/config/cq.ini file as described in this section.

Procedure

    Locate the KFW_INTERFACES= variable and add the one-word name of the new interface, separating it from the preceding name by a space. For example:

    KFW_INTERFACES=cnps myinterface

    Following the entries for the default cnps interface, add the following variables as needed, specifying the appropriate values:

    KFW_INTERFACE_interface_name_HOST=

        If you are defining an interface for a specific NIC or different IP address on this computer, specify the TCP/IP host address.

    KFW_INTERFACE_interface_name_PORT=

        Type a port number for the Tivoli Enterprise Portal Server. The default 15001 is for the server host address, so a second host IP address or a NATed address requires a different port number.

    KFW_INTERFACE_interface_name_PROXY_HOST=

        If you are using address translation (NAT), type the TCP/IP address used outside the firewall. This is the NATed address.

    KFW_INTERFACE_interface_name_PROXY_PORT=

        If the port outside the firewall will be translated to something different than what is specified for Port, set that value here.

    KFW_INTERFACE_interface_name_SSL=Y

        If you want clients to use Secure Sockets Layers (SSL) to communicate with the Tivoli Enterprise Portal Server, add this variable.

End quote from manual.

1) KFW_INTERFACES=cnps myinterface

This environment variable specifies all the TEPSI interface names. The default one is “cnps” and in this case “myinterface” represents the new TEPSI you are defining. You do not need to specify the cnps values. These are followed by TEPSI name specific environment variables.

 

2) KFW_INTERFACE_<interface_name>_PORT=

This environment variable defines the port number for incoming IIOP [Corba] communications traffic at the TEPS.  The default cnps uses 15001. By convention these values are typically set to 15002, 15003, etc. Because of the embedded interface_name there will be one such for each non-default TEPSI mentioned in KFW_INTERFACES.

3) KFW_INTERFACE_<interface_name>_HOST=

This environment variable is used when there is more than one Network interface [NIC] on the server running TEPS and you wish to restrict this TEPSI Portal Client communications to a single specific network interface. It is typically given as a numeric ip address.

One use case would be a server that has an interface or NIC that allows communication with the public internet. Someone outside the company network running portal client must use only that network interface and all responses must go through that NIC. Another example would be an outsourcing company providing services for several other companies. Each company could want to have its own protected communications.

4) KFW_INTERFACE_<interface_name>_PROXY_HOST= and KFW_INTERFACE_<interface_name>_PROXY_PORT=

These two environment variables are used when the portal client is behind a NATing firewall. In this case the client must use different ip address and port number which will be translated to the TEPS system and port number expected. PROXY_HOST must be a numeric address.

5) KFW_INTERFACE_<interface_name>_SSL=N/Y

Communications security is required for this TEPSI. If the value is N, no security is used. The second stage CORBA communications uses a certificate which is built-in to one of the jar files which is transmitted across during the initial connection. If you are using non-default security certificate, the documentation shows how to accomplish that.

When the TEPS is restarted, all the needed the <interface_name>.ior records will be created as necessary.

Windows TEPSI Objects

In a Windows environment, you configure TEPS Interfaces in a MTEMS dialog. Right click on the Portal Server select Advanced, Configure, TEPS Interfaces:

In this dialog you will create new TEPSIs as required.

1) Name supplies the TEPSI name

2) Host is used when there is more than one Network interface [NIC] on the server running TEPS and you wish to restrict Portal Client communications to a single specific network interface. It is must be supplied as a numeric ip address.

3) Port defines the port number for incoming IIOP [Corba] communications traffic at the TEPS.  The default cnps uses 15001. By convention these values are typically set to 15002, 15003, etc.

4) Proxy Host and Proxy Port are used when the portal client is behind a NATing firewall. In this case the client must use different ip address and port number which will be translated to the TEPS system and port number expected. PROXY_HOST must be a numeric address.

5) SSL is used to define communication security for IIOP. If the value is N, no security is used. The second stage CORBA communications uses a certificate which is built-in to one of the jar files which is transmitted across during the initial connection. If you are using non-default security certificate, the documentation shows how to accomplish that.

When the TEPS is restarted, the  Name.ior records will be created as necessary.

Troubleshooting

1) The Proxy host is coded as a numeric value since it is encoded into the IOR record during portal server startup. If it is blank, then the local TEPS server is used. In one memorable case, the server running the Portal Server had an entry in /etc/hosts that specified the host as having ip_address of 127.0.0.1. Initial connection worked fine, the ior record was transferred and then the Java CORBA attempted to communicate to 127.0.0.1 port 15001 which was localhost on the client machine. The testing worked fine on the server running the portal server. You can do a ping hostname on both the machine running the portal server and make sure it resolves into the expected address.

2) Having two or more NICs requires careful evaluation if they are not equal in function. You need to specify the Host variable if there is a specific interface to be used for the needed communications. In addition, you may need to add KDEB_INTERFACE=ip_address for the TEPS communications with the TEMS in such cases. Usually things work with defaults, but when there are NICs with unequal scope you need to watch carefully. This can also be a problem with virtual NICs as those created with some products.

3) If you are experiencing connection problems, here is a ==>URL<== to parse the ior record. Edit the IOR record and copy/paste the text to display the contents. Use it to verify that the ior record is presenting the ip address and port number that is required at the Portal Client endpoint.

Summary

This post explains how to create TEPS Interfaces in Linux/Unix and Windows.

Sitworld: Table of Contents

Feedback Wanted!!

Please report back experience and suggestions. If  Agent Health Survey does not work well in your environment, repeat the test and add  “-debuglevel 300” and after a retry send the health.log [compressed] for analysis.

History and Earlier versions

There are no binary objects connected with the post. This will record summary of changes.

1.00000

Initial publication

Photo Note: Stone Fireplace in Big Sur 2009