JARGON TUNNEL BROKER

INSTALLATION CHECKLIST FOR UNIX/LINUX


OVERVIEW

This is a summary of the steps to install the Jargon Tunnel Broker with the Progress AppServer on a Unix or Linux system, using an Apache or Netscape web server or any similar web server with CGI features.

For more complete information, see the "Overview of Jargon Tunnel Broker" document that is included in the tunnel.tar and tunnel.zip installation files, in the "doc/" subdirectory.
 

A. CONFIGURATION INFORMATION

1. Fill out the Installation Worksheet.

B: INSTALLATION STEPS

1. Extract Tunnel Broker Files.

Use the "tar" command to extract (untar) the files contained in tunnel.tar into a directory of your choice on the server that will run the tunnel broker. For example, under "/var" or "/usr". Anywhere with a little space is fine (it is about 3MB). This will extract as ./tunnel/*, so it would end up as /var/tunnel etc.

2. Install Progress AppServer.

Follow Progress instructions for installing and configuring AppServer on Unix or Linux. The Jargon Tunnel Broker does not have any special requirements for doing this, using the default installation choices is the safest way to proceed in our experience. It is similar to NT installations except for the lack of a GUI admin tool like Progress Explorer. For testing purposes, you may wish to start with the default "out-of-the-box" asbroker1, not changing anything nor adding any database connections, until you know that everything is working correctly.

3. Install Java JVM.

If a Java 1.1 (or higher) JVM is not present, one should be installed. One may be downloaded from http://www.javasoft.com or from your Unix or Linux vendor. The Progress Appserver installation will install a 1.1.8 version of the JVM, which will work. However, version 1.2 or higher is needed to use the GUI Control Panel (assuming you have a graphical terminal or workstation on which to run it).

4. Compile Script.

Compile jsihttp.c (in tunnel/unix/cgi-bin/src) using the command:
cc jsihttp.c -o jsihttp
   or, for systems using the GNU compiler:
gcc jsihttp.c -o jsihttp

5. Install jsihttp Files.

Copy the jsihttp object file (from step 4) and the tunnel/unix/cgi-bin/jsihttp.sh shell script file to the web server’s cgi-bin directory. Make sure both have full read and execute permissions.

For the Apache web server, edit the httpd.conf configuration file (which may be located in: /etc/httpd/conf/httpd.conf ) and make sure the ScriptAlias directory is defined. If you are using multiple virtual hosts, this is defined separately for each host.
Example: ScriptAlias /cgi-bin/ "/home/httpd/cgi-bin/"

See: http://httpd.apache.org/docs-2.1/howto/cgi.html#configuring

Also, Apache changed some things about cgi environment variables at one point, so you might have to add the following option in the apache config file at the appropriate place, then restart apache: 

       AcceptPathInfo on
See: http://httpd.apache.org/docs-2.0/mod/core.html#acceptpathinfo

6. Configure Script.

Edit jsihttp.sh to reflect the host name and broker port of the server that will run the Tunnel Broker. When the web server and the tunnel broker are on the same machine, use "localhost" instead of the machine's IP address or hostname

7. Configure Tunnel Broker.

Edit the tunnel/system/tunnel.ini file to reflect the parameters of your installation. Often the defaults are fine. If the tunnel broker and the Progress Appserver are on the same machine, use "localhost:5162" for the AppServer parameter instead of using an IP address (as in #6).

8. Configure Scripts.

The script files with a ".sh" extension for Unix are used to start, stop, test and check status of the tunnel broker. The scripts are located in the tunnel/unix directory. For ease of use, you may wish to add their directory location to your search path environment variable. Make sure they all have full read and execute permissions.

These scripts assume that the "java" executable can be found in the search path of your environment settings. If not, then the full path of the java executable must be specified in the command line in each script.

The "server.sh" script, by default, requires that the shell session from which it was started stays running. This means that session window cannot be closed, and the user cannot log out. To run this script in the background and change it to a child process of 'root' instead of the user who started it, change it from:

   java -classpath ../lib/jtunnel.jar:../lib/o4glrt.zip b.Server ../system/tunnel.ini

to this (adding 'nohup' at the front and '&' at the end)
 

   nohup java -classpath ../lib/jtunnel.jar:../lib/o4glrt.zip b.Server ../system/tunnel.ini &

This script can also be run from 'cron', however you must then also change all relative paths to full paths in the server.sh script and in the tunnel.ini file.

9. Start AppServer.

Use the normal Progress scripts to start AppServer. Check its status to see if agents start and are available. Also look at the broker and server logs to see if there are any error messages.

10. Start the Tunnel Broker.

Use the server.sh or gui.sh to start the tunnel broker. Check its status to see if agents start and are available. If so, re-check the Appserver agent status, they should now show some or all of the agents as connected (as many as the number of tunnel broker agents).

11. Install Jargon Host Programs.

Install the host programs for jsi, util, sports2000 demo and your application. Copy the "jsi.tar", "utilprog23.tar" and "sports2000prog.tar" files (using the "binary" option in FTP) from the ".\Progress\unix" subdirectory under your Jargon Writer directory to the appserver working  directory, then use commands such as "tar xvf jsi.tar" (etc.) to uncompress each one. Make sure all directories have full read and execute (search) permissions and that all .p and .i files have full read permissions.

12. Configure Host Middleware Type.

Change the "HostType" parameter in line 7 of the jsi/jsi.ini file to use "AS" (AppServer) mode instead of "WS" (WebSpeed) mode.

13. Install Status Programs.

Copy tunnel/test/statusas.p and tunnel/test/statusas.i to the appserver working directory (for the following tests).

14. Check Status from Test Script.

Try the test.sh script (may have to modify for your application program/database). The output will appear in one long (messy-looking) line, because it is formatted for use with Jargon Reader. However, if you get back a long response that includes Propath directory entries, etc then it is working.

For the Apache web server, there are several pages in the Apache docs that may be helpful in tracking down any script problems. See:
http://httpd.apache.org/docs-2.1/mod/mod_cgi.html
especially the ScriptLog directive section at
http://httpd.apache.org/docs-2.1/mod/mod_cgi.html#scriptlog
This directive causes the error log to provide more information on why a script isn't running.

15. Check Status from Web Browser.

Try running statusas.p from a web browser. Type in a URL like:
http://999.999.999.999/cgi-bin/jsihttp.sh/statusas.p?ProcName=GetStatus
where you substitute the IP address of the machine that the web server is running on for the "999.999.999.999" above. You can use either a symbolic or numeric address, as long as the symbolic name is getting converted to an IP address correctly by DNS or other means. You can test this by trying to "ping" the symbolic address.

16. Install Deployment Products.

When this is all working ok, install and configure the Jargon Reader files, html startup pages, image files, HTML online documentation files, and your application's xml files somewhere under the web server root directory. If the web server root is "/html", then you might use:
"/html/doc"
"/html/jrx"
"/html/images"
"/html/lib"
"/html/system"
"/html/xml"
(etc.)

17. Test Your Application.

Test applications to make sure everything works. If there are problems, turn on all trace options in jsihttp.sh and tunnel.ini and look at logs after trying more tests. Also look at AppServer broker and server logs for any error messages. See the Debugging Guide document for more debugging tips.