Troubleshooting GateKeeper

This section describes how to obtain debugging information from GateKeeper and its clients and servers. It also highlights potential problems such as incorrect environment and registry settings and describes some common tools useful for troubleshooting GateKeeper.

Preparation for troubleshooting

The following sections describe the preparations that must be done or observed before troubleshooting GateKeeper.

Getting debugging information

Comprehensive debugging information can be obtained by setting the properties of the client, server and GateKeeper. The following table shows the relevant settings and whether they are applicable to the client, server, or GateKeeper. The properties must be set in their respective properties file.

Log levels have numeric levels along with corresponding text values and either can be used to describe the situation. Levels 4 and higher are useful for debugging. The following table describes the log level values.

Log level value	Description
0 or EMER	System is unusable. A panic condition.
1 or ALERT	A condition that should be corrected immediately, such as a corrupted system database.
2 or CRIT	Critical conditions, such as hard device errors.
3 or ERR	Error conditions.
4 or WARNING	Warning conditions such as connection failures due to authentication problems, such as incorrect password and authorization failures. This is the default.
5 or NOTICE	Conditions that are not critical, but may require special handling configuration settings.
6 or INFO	Informational such as all user accesses to specific methods requested to the server.
7 or DEBUG	Debug information meant to be understood only by the developer. These messages are not internationalized

The following table describes the property settings useful for debugging GateKeeper. See also the sections VisiBroker Properties and Debug Logging Properties in the VisiBroker for Java Developer's Guide or VisiBroker for C++ Developer's Guide for more detailed information on how the logging features and properties in VisiBroker operate.

Property	Description	Set in Property File
vbroker.orb.logger.output=<filename>	Log file Specifies the name of the file where the log is recorded. If not specified, the default is gkdebugfile.log. Log information can also be sent to stdout.	Server, client and GateKeeper
vbroker.orb.bufferDebug=true	ORB Forces the internal buffer manager to display the buffers used by ORB.	Server, client and GateKeeper
vbroker.orb.debug=true	ORB Displays debugging from the ORB	Server, client and GateKeeper
vbroker.orb.warn=<warning level>	ORB Specifies which warning of a particular level to be displayed by the ORB. The values can be 0, 1 or 2. Level 2 will display warnings of all levels.	Server, client and GateKeeper
vbroker.orb.logLevel=<loglevel>	ORB The log level can take one of the values described above.	Server, client and GateKeeper
vbroker.orb.logger.appName=<Application Name>	ORB Specifies the application name to be displayed in the log.	Server, client and GateKeeper
vbroker.events.debug=true	Event Service Displays Event Service diagnostic messages.	Event Service
vbroker.orb.dynamicLibs=com.inprise.vbroker.gatekeeper.trace.Init vbroker.gatekeeper.trace.demo=true	GateKeeper Displays trace information from GateKeeper's built-in trace facility.	GateKeeper
vbroker.agent.debug=true	GateKeeper and Smart Agent Displays debugging information of interactions between GateKeeper and the Smart Agent.	GateKeeper
vbroker.locationservice.debug=true	Location Service Displays debugging information of the Location Service.	Server, client and GateKeeper
vbroker.URLNaming.debug=true	URLNaming Displays debugging information of the URLNaming service loaded in the ORB runtime. This setting is often used to detect if the correct IOR is retrieved.	Server, client and GateKeeper
vbroker.poa.logLevel=emerg	POA Displays debugging information from the POA. GateKeeper has exterior, interior and iiop_tp POA.	Server and Server Side of GateKeeper
vbroker.gatekeeper.passthru.logLevel=<emerg>	Pass-through Displays debugging information of pass-through mode in GateKeeper.	GateKeeper
vbroker.security.logLevel=<logLevel>	Security Service Displays logging information of the security service such as SSL on GateKeeper.	GateKeeper

Starting GateKeeper in debugging mode

In addition to the properties described above, the gatekeeper and vbj command line utilities can output additional environment and parameter setting information at start-up. The -VBJdebug option produces this additional output. The following table shows examples of the debugging commands:

Component	Command line options example
Java Server	vbj -VBJdebug Server -DORBpropStorage=server.prop Server
GateKeeper	gatekeeper -VBJdebug -J-Dvbroker.log.enable=true -J-Dvbroker.log.logLevel=debug -props gk.prop
Java Client	vbj -VBJdebug Client -DORBpropStorage=client.prop Client

Note

The -VBJdebug option affects only the gatekeeper and vbj commands and has no relationship to the diagnostic property settings described above. The diagnostic properties will produce the same output regardless of whether or not the -VBJdebug option is used.

Environment settings

GateKeeper reads in the environmental variables at startup. On Windows, GateKeeper also reads settings in the registry. The precedence of the settings (UNIX and Windows) is as follows:

1	command line

2	properties file

3	environment settings

4	registry settings (Windows only)

5	system default (Windows only)

The following table lists the common environment variables used by GateKeeper.

Environment variable	Description
CLASSPATH	CLASSPATH should include the directories of the Java Development Kit and Java Servlet Development Kit. Specifically, CLASSPATH must include servlet.jar. For example, in Windows NT, at the DOS prompt enter: set CLASSPATH=C:\BES\lib\servlet.jar;c:\bes\jdk\jdk1.4.1\lib If the classpath includes multiple versions of the JDK, compatibility issues may arise.
JAVA_HOME	Specifies the home directory of Java. If the Java directory is not defined in the CLASSPATH environment variable, the system will try to locate Java libraries from this directory. Note: On UNIX systems, this variable must be set. On Windows systems, it may be preset in the registry.
JDK_HOME	Specifies the home directory of JDK. If the JDK directory is not defined in the CLASSPATH environment, the system will try to locate JDK libraries from this directory. Note: On UNIX systems, this variable must be set. On Windows systems, it may be preset in the registry.
PATH	The PATH environment is set automatically during VisiBroker installation and should include the directory in which GateKeeper exists. For example, on Windows, at the command prompt enter: set PATH=%VBROKERDIR%\bin;%PATH%
OSAGENT_PORT	Specifies the port used to contact the Smart Agent. Ensure the appropriate Smart Agent listens to this port and GateKeeper is able to reach this port (and the host).
BES_LIC_DIR	Specifies the path of the directory location in which the license data file exists.

Tools for troubleshooting

The following table describes some tools that are useful for troubleshooting GateKeeper.

Names	Description
osfind (Windows and UNIX)	Included with the VisiBroker distribution. It is used to locate all objects registered within a given Smart Agent domain and to display information known to the agent. Normally, Smart Agents are restricted to a subnet only.
printIOR (Windows and UNIX)	Included with the VisiBroker distribution. It is used to print all the information encoded in an IOR into a human readable format.
ping (Windows and UNIX)	Part of TCP/IP networking tool set and usually included with the operating system. It is used to test where a packet is bounced back from a remote host to the current host and can be useful for firewall configuration verification.
tracert (Windows) traceroute (UNIX)	Part of TCP/IP networking tool set and distributed with some operating systems. It prints the route or path taken by a data packet to reach the destination host. It can help you identify a problem with firewalls as it shows where packets fail when being forwarded by routers.
route (Windows and UNIX)	Part of TCP/IP networking tool set and distributed with some operating systems. It prints the routing table and can be useful with firewall configurations.
netstat (Windows and UNIX)	Part of TCP/IP networking tool set and distributed with some operating systems. It displays protocol statistics and current TCP/IP network connections and can be useful to verify the state of connections and port availability.
nslookup (Windows and UNIX)	Part of TCP/IP networking tool set and distributed with some operating systems. It queries Internet domain name servers for hostname mapping.
regedit (Windows)	Part of Microsoft Windows operating system distribution and lets you to edit the Windows registry.

Getting information about the computer network

A good understanding of the computer network is needed to configure GateKeeper properly. You should work closely with the network administrators to identify problems that might arise from an improper configuration of GateKeeper and the firewall or the network itself. Many times configuration problems arise due to an incorrect configuration of the router or firewalls.

Firstly, you should try to understand the network diagram, firewall policies, routing tables, packet filters, and the location and configuration of basic TCP/IP stack servers. Most network administrators can provide you with logical network diagrams that show the physical wiring and the components in their network. When making deployment plans for GateKeeper, we recommend that you start by analyzing and understanding these diagrams.

Next, you need to understand the firewall policies in place. Understanding the firewall policies and the physical network diagrams will help you determine whether messages from the client application are allowed to pass through various hops of the networks to reach the server and vice versa. This information in turn determines where you should deploy GateKeeper and it will save a considerable amount of time when troubleshooting GateKeeper's configuration.

An external router routes packets to/from the Internet and perimeter networks. Additionally, the external router can be programmed so that only a restricted set of protocols can enter from the Internet to the perimeter network. This additional information is only available in the firewall policy. If the routes are not configured properly, the packets will be forwarded to the wrong destination or will be ignored. Whenever there is any change in the routing table or firewall policies, the network administrator should notify you.

A multi-homed firewall can filter and route packets from the perimeter network into the internal network and the de-militarized zone. It may also perform Network Address Translation in which the real IP address of the internal network is replaced with the fake IP address and vice versa.

The following figure is an example of a network diagram that shows the physical wiring layout of three subnets; the Perimeter Internet, Demilitarized zone, and internal network.

Figure 18

Typical network diagram example

•

The External Router routes packets to/from the Internet and Perimeter Internet. Additionally, the external router can be programmed such that only a small restricted set of protocols enter from Internet to the Perimeter Internet. This additional information is only available in the Firewall policy; that is the routing table.

•

The Multi-Homed Firewall filters packets and routes packets from the Perimeter Internet into the two subnets; internal Network and Demilitarized Zone. It may also perform Network Address Translation in which the real IP address of the internal network is replaced with the fake IP address and vice versa.

Note

The example above illustrates one of many possible network configurations and, therefore, it is very important to know where such information can be obtained before deploying GateKeeper.

Essential checks

GateKeeper acts like a proxy and problems can arise in the client, GateKeeper, or the server. The following sections describe some essential checks you can make when GateKeeper fails to work properly. The checks described below are not meant to be exhaustive and are not arranged in order of importance or performance sequence, but are provided here to serve as a guideline for preliminary troubleshooting.

Check the Smart Agent

GateKeeper uses the Smart Agent to locate server objects and it can automatically locate the Smart Agent on the network. If the Smart Agent fails to detect the server object or if GateKeeper is unable to locate the Smart Agent automatically, you may use one of the following solutions to troubleshoot the Smart Agent:

•	Check the environment variable settings described above.

•	Start the Smart Agent in debugging mode: osagent -v

•	Find all Smart Agents that are reachable from where GateKeeper is installed. You may use the osfind command.

•	Check if the IP and port addresses are set correctly in the client, GateKeeper, and the server.

Check the property files

Check the settings in the property files of the client, server and GateKeeper. The most common problem is setting the port and host addresses incorrectly.

Check the routing table

A multi-homed host allows communication between the connected networks. In order for the multi-homed host to route data packets from one network to another correctly, you must configure the routing tables correctly in the hosts. If the routing table fails to send data correctly, you may use the following methods to troubleshoot this program:

•	Use route print and traceroute to check for routing tables. Locate the communication breakdown and configure the routing tables correctly.

•	Use tools such as ping and tracert to examine and verify the communication paths.

Check pass-through connections

You may use one of the following methods to check if the pass-through connection is set correctly:

•	If you are using GateKeeper in the pass-through mode, you must set the following properties in GateKeeper correctly:

vbroker.gatekeeper.passthru.inPortMin
vbroker.gatekeeper.passthru.inPortMax
vbroker.gatekeeper.passthru.outPortMin
vbroker.gatekeeper.passthru.outPortMax

The inPortMin and inPortMax properties specify the range of ports a client uses to connect to GateKeeper. Therefore, you must ensure that the clients are able to overcome firewalls to connect to these ports.

Similarly, the outPortMin and outPortMax properties specify the range of ports GateKeeper uses to connect to the server-side network. Therefore, you must ensure that GateKeeper is able to overcome the firewalls to connect to these ports on the server.

•	Use tools such as ping, tracert, traceroute, and route to check if the destination is reachable.

Check the Java policy

If the client is an applet using the java plug-in, make sure the following properties are added to the java.policy file. If these settings are not specified in the JRE's java.policy file, a security exception may occur. Note that these properties are the client's settings and “192.73.8.25:25001” is the IP and port address of GateKeeper's host and HIOP port.

grant codeBase ”http://192.73.8.25:25001/*” {
permission java.lang.reflect.ReflectPermission”suppressAccessChecks”;
permission java.io.SerializablePermission ”enableSubclassImplementation”;
permission java.lang.RuntimePermission ”accessDeclaredMembers”;
};

Check SSL

If you are using SSL, ensure the certificate is installed properly in the client (Web browser), the server, and GateKeeper.

Check the IOR files

To check the content of an IOR file, use the following methods:

•	Set the vbroker.URLNaming.debug property in the client, GateKeeper, or the server to trace which IOR files are retrieved.

•	Use the printIOR command to print the content of an IOR file.

Check firewall settings

Firewall settings can be the most problematic settings.

•	See “Configuring the firewall” and “Troubleshooting GateKeeper”

•	Work closely with the network administrator to understand the firewall restrictions.

•	Check the NAT (Network Address Translation) configuration.

Common errors and FAQs

1	A comprehensive list of Frequently Asked Questions is included in your VisiBroker installation for more information. You can find this at:

<install_dir>\doc\faqs\VisiGateKeeperFAQ.html

2	Common errors made while setting properties are spelling mistakes for property names, such as ”vroker” instead of “vbroker”. Also, on Windows, some word processors automatically change the first character on a line into a capital letter. Therefore, vbroker becomes Vbroker which is not valid.

3	Socket binding errors can occur when the IP and/or port addresses are invalid or are already in use. The following table shows some typical errors:

Error Message	Error Type	Solution
“Bind Exception: Cannot assign requested address”	Wrong IP Address	Correct the IP and/or port address.
“Bind Exception: Address in use”	IP port already in use	Correct the IP and/or port address.
“Invalid GIOP Proxy ior: Communication Problem”	Wrong IP Address	Correct the IP and/or port address.
“Invalid GIOP Proxy ior: Connect Exception”	Wrong Port Address	Correct the IP addresses in the IOR file (property file)
“Invalid GIOP Proxy ior: Invalid Object Ref, File Not Found Exception”	Wrong IOR Name	Correct the name of the referenced IOR file.

Proxy servers and GateKeeper

GateKeeper can work in conjunction with HTTP proxy servers. These proxy servers are used by the HIOP protocol for the HTTP Tunneling feature of GateKeeper.

In general, the latest firewall products have a built-in capability to handle HTTP traffic. Certain firewalls have built-in HTTP proxy servers (such as Microsoft's ISA Server) while other firewalls can forward HTTP messages to an HTTP proxy server that can perform load balancing using proprietary mechanisms. In some cases, an HTTP proxy server uses caching techniques to increase performance. GateKeeper requests that HTTP proxy server caching is disabled for its messages.

When an HTTP proxy server is used in conjunction with GateKeeper, the HTTP proxy server acts like a NAT device for GateKeeper because the HTTP proxy server forwards packets. GateKeeper is hidden behind the HTTP proxy server and, as such, it is important to configure the proxy host properties or TCP firewall properties to specify the HIOP fake host/port.