Jargon Tunnel Broker

Configuring the jsihttp Script

For Windows NT/2000/2003

Version 1.03 - July 2001

OVERVIEW:

This version of jsihttp.dll and jsihttp.ini provides several new features:

Support for any number of tunnel brokers
Ability to specify timeout value in seconds for each broker
Inquiry to display current configuration of the jsihttp.dll script

DETAILS

This new version of the tunnel broker script for WinNT/2000/2003 provides support for any number of tunnel brokers. These brokers may be running on the same host as the web server where the script is run, or on separate hosts, or both. The tunnel brokers supported by the jsihttp.dll script on a web server are configured in multiple sections within one jsihttp.ini file. The folders where these files are located is the same as in previous versions.

Here is an example of a script that supports three brokers:

[General]
ErrorLogFile=C:\tunnel\logs\jsihttp_error.log
[DevBroker]
HostName=localhost
Port=8001
Timeout=10
TraceLogFile=C:\tunnel\logs\dev_trace.log
TraceMode=off
[TestBroker]
HostName=localhost
Port=8003
Timeout=10
TraceLogFile=C:\tunnel\logs\test_trace.log
TraceMode=on
[RelBroker]
HostName=sun5
Port=8001
Timeout=30
TraceLogFile=C:\tunnel\logs\rel_trace.log
TraceMode=off

General Section

At the top of the jsihttp.ini file, the "[General]" section has one parameter ("ErrorLogFile"). Specify the full pathname of the error log file for this jsihttp.dll script. All error messages for all tunnel brokers will be written to this log file. If available, the tunnel broker name will be included in the error message. Be sure the specified folders exist.

ex: ErrorLogFile=C:\tunnel\logs\jsihttp_error.log

Broker Sections

1. [brokername]
Each tunnel broker is configured in the jsihttp.ini file under its own section name, with the name of the tunnel broker in square brackets.

ex: [DevBroker]

This broker name should be the same as the "BrokerName" configured in the tunnel.ini for the broker that it references. You can use any names that you like. Use only letters, numbers and underscores (no spaces).

2. HostName
Within each broker section, specify the hostname or IP address of the host on which that tunnel broker is being run. For brokers running on the same host as the web server, you may use "localhost". If you use a hostname, be sure the server can translate it to an IP address. You can
test this by doing a "ping [hostname]" from a DOS command line. Hostnames are defined in the etc/hosts file or by a local name server.

ex:
HostName=localhost
HostName=192.168.1.25
HostName=TestLinuxBox

3. Port
Specify the port number that the script will use to communicate with the tunnel broker. This must be the same port that the tunnel.ini for that broker specifies as the BrokerPort.

ex: Port=8001

If you are running multiple tunnel brokers on the same host, each one must use unique values for its AdminPort and BrokerPort, as defined in each broker's tunnel.ini and in the corresponding section of jsihttp.ini.

For example:

broker1 could use AdminPort=8000 and BrokerPort=8001
broker2 could use AdminPort=8002 and BrokerPort=8003
etc.

In other words, the combination of HostName and Port must be unique for each defined broker. If two brokers have different HostName values, they could use the same ports on those two hosts. However if two brokers have the same HostName values, then they must have different Port values.

There is no practical limit to the number of tunnel brokers that can be defined in the jsihttp.ini file.

4. Timeout
Another new parameter allows control of the timeout period in seconds that the jsihttp.dll will wait after sending a request to a broker. If no response is received within the specified number of seconds, the broker will time out, log an error and return an error to the client. The value is specified as an integer number of seconds.

ex: Timeout=60

This assigns a 60 second (one minute) timeout value for this broker.

Configuration Inquiry

Another new feature is the ability is to query the script with a web browser for the configuration data. Type in the appropriate data in a web browser URL location box, such as:

http://www.abc.com/scripts/jsihttp.dll/ConfigData

and it will echo all the configurations from the ini file that were present at startup. This will show how the settings were interpreted by the script.

Specifying a Tunnel Broker in Script parameters

To use the new script, you must specify a broker name in the script portion of the URL that is constructed for host tasks, as follows:

http://www.abc.com/scripts/jsihttp.dll/Broker=DevBroker/statusas.p?ProcName=GetStatus

This value is in the startup HTML parameters for Jargon ReaderX and for Jargon Reader (in applet mode). For Jargon Writer and Jargon Reader (in application mode), it is in the preferences.ini file.

The script parameter value used to be just:

scripts/jsihttp.dll

Now it is:

scripts/jsihttp.dll/Broker=[broker name]

example:

scripts/jsihttp.dll/Broker=devbroker

There is no default, you must specify the "Broker=" portion.

The broker name MUST exactly match the broker name specified within square brackets in the jsihttp.ini file, including upper/lower case spelling.

Multiple Tunnel Broker Setup

You can make a separate "tunnel" folder for each tunnel broker that will be run, or they can all run from one common folder, with each broker having a separate set of configuration and script files.

To do multiple brokers within one "tunnel" folder:
1. Make a copy of tunnel.ini for each broker that you want. Each ini file will use a separate set of ports (broker and admin).

Ex: dev.ini test.ini rel.ini

2. Make copies of the server.bat, gui.bat, stop.bat, status.bat scripts for each of these brokers. In server.bat and gui.bat, change the last parameter from tunnel.ini to the new ini file name for that broker. In stop.bat and status.bat, change the Admin Port from 8000 to whatever port you use for that broker.

Then you can run multiple brokers, one for each ini file that you define. The jsihttp.dll will communicate with each broker using the broker port number in that broker's section of jsihttp.ini, and that port number must match the broker port number defined in that brokers copy of tunnel.ini

Converting from older versions

Stop all tunnel brokers that are running on the web server host.
Install the new jsihttp.dll and jsihttp.ini
Configure the jsihttp.ini for the multiple tunnel brokers to be run.
Configure the tunnel brokers themselves.
Configure the startup HTML pages and preferences.ini files to reflect the desired tunnel broker that they should use.
Reboot Windows NT/2000/2003 to clear any copy of the old jsihttp.dll that may have been cached in memory by Windows. Stopping and restarting the IIS service itself may also do this on some versions of Windows, however stopping and starting an individual web site within IIS will NOT do so.
Start the tunnel brokers.
Test that each configured tunnel broker can be accessed from Jargon Writer, Jargon Reader and/or Jargon ReaderX (whichever you are using).