GateKeeper Guide : Troubleshooting GateKeeper

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.
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.
Log file
Specifies the name of the file where the log is recorded.
ORB
Forces the internal buffer manager to display the buffers used by ORB.
ORB
Displays debugging from the ORB
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.
ORB
Specifies the application name to be displayed in the log.
Event Service
Displays Event Service diagnostic messages.
GateKeeper
Displays trace information from GateKeeper's built-in trace facility.
GateKeeper and Smart Agent
Displays debugging information of interactions between GateKeeper and the Smart Agent.
Location Service
Displays debugging information of the Location Service.
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.
POA
Displays debugging information from the POA. GateKeeper has exterior, interior and iiop_tp POA.
Pass-through
Displays debugging information of pass-through mode in GateKeeper.
Security Service
Displays logging information of the security service such as SSL on 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:
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
2
3
4
5
The following table lists the common environment variables used by GateKeeper.
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:
Note: On UNIX systems, this variable must be set. On Windows systems, it may be preset in the registry.
Note: On UNIX systems, this variable must be set. On Windows systems, it may be preset in the registry.
Tools for troubleshooting
The following table describes some tools that are useful for troubleshooting GateKeeper.
osfind (Windows and UNIX)
printIOR (Windows and UNIX)
ping (Windows and UNIX)
tracert (Windows)
traceroute (UNIX)
route (Windows and UNIX)
netstat (Windows and UNIX)
nslookup (Windows and UNIX)
regedit (Windows)
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
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 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:
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.
Common errors and FAQs
1
<install_dir>\doc\faqs\VisiGateKeeperFAQ.html
2
3
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.