NAME

TN3270RG - TN3270 Resource Gateway

REQUIREMENTS

TN3270RG has been tested with Debian 3.1. It should work with other distributions, but some of the documented file locations may be incorrect and the init script may not work.

CONFIGURATION

Configuration is through the %GLOBALS hash at the top of the tn3270rg.pl file. All file locations should include the full path. Because passwords are contained in this file it is recommended that it be made readable only by those users that need to see it (root).

local_port
Port that you want TN3270RG to listen on.

remote_address
Address (IP or host name) to forward requests to.

remote_port
Port to forward requests to.

log_file
File to write log to.

pid_file
File to write the PID to.

sql_datasource
The SQL datasource. This should be in the format that DBI expects, and the first part will always be dbi:Pg. The rest is dependent on the setup. Example: dbi:Pg:dbname=tn3270rg;host=127.0.0.1.

sql_username
The SQL username.

sql_password
The SQL password.

replace_token
To prevent accidental modification of data, TN3270RG will only replace the token specified here with the resource assigned to the connection from the pool. No other data will be modified during the forwarding process. It will also only replace that token once (which should happen at the beginning of the session when the resource name is negotiated). This should be something that is not likely to appear anywhere else. Example: !_TN3270RG_RESOURCE_!.

USAGE

The program takes no arguments. When run, it will become a daemon, write its PID to the file specified in the configuration, and output important events to syslog. Upon startup it will mark all resources as available in case it was not properly shut down. It is recommended that you place the init script in the /etc/init.d folder and set it to start up some time after PostgreSQL does.

Logging

TN3270RG logs through the Unix Syslog daemon. It logs with the ident of tn3270rg to the LOG_DAEMON facility.

Shutdown

To shutdown, send a SIGTERM signal (a regular kill) and TN3270RG will close all connections, write a notice to Syslog that it is closing, and then exit.

DATABASE

TN3270RG requries a PostgreSQL database (actually it should work with most databases that have a Perl DBD). It is recommended that you create a user and database specifically for TN3270RG. The program uses only one table, which lists the resource name, IP address it has been allocated to, the time it was allocated, and when that resource was last allocated. It may be created with the PostgreSQL script below:

        CREATE TABLE "tn3270rg" (
                "resource" character varying(50) NOT NULL,
                "ip" inet,
                "time" timestamp with time zone DEFAULT now(),
                "last" timestamp with time zone,
                Constraint "tn3270rg_pkey" Primary Key ("resource")
        );

Database disconnects

Without a good connection to the database, it is impossible for TN3270RG to allocate new sessions because it must query the resource list. However, as of version 1.1.0, it can survive a disconnection from the database and will continue to allow existing sessions to pass traffic back and forth and disconnect. New connections will be refused until a new connection can be made to the database (it will try to connect again every time a new connection is requested). When the database comes back up, the list of resources will be brought up to date and everything will continue as normal.

WEB INTERFACE

TN3270RG comes with an easy to use web based interface for database management and status information.

Configuration

Configuration for the web interface is similar to the configuration for the main program and is through the %GLOBALS hash at the top of the TN3270RG.pm file. Because passwords are contained in this file it is recommended that it be made readable only by those users that need to see it (webserver).

templates
Absolute path to the directory containing the templates.

htmlbase
Path as seen by the web browser as the base directory for the HTML files.

main_page
Path as seen by the web browser for the main_page.pl CGI script.

cgi_status
Path as seen by the web browser for the status.pl CGI script.

cgi_resources
Path as seen by the web browser for the resources.pl CGI script.

cgi_manage
Path as seen by the web browser for the manage_resources.pl CGI script.

sqldatasource, sqlusername, sqlpassword
See configuration for main program.

Speed

The TN3270RG web interface scripts were written with mod_perl in mind and will run significantly faster if used with mod_perl (but it is not required). If you use mod_perl, Apache::DBI may help performance as well.

FILE LOCATIONS

Recommended locations for the files needed for this program.

        /var/run/tn3270rg.pid
        /var/www/perl/tn3270rg/status.pl
        /var/www/perl/tn3270rg/tn3270rg.pl
        /var/www/perl/tn3270rg/TN3270RG.pm
        /var/www/perl/tn3270rg/resources.pl
        /var/www/perl/tn3270rg/manage_resources.pl
        /var/www/tn3270rg/templates
        /var/www/tn3270rg/templates/resources.html
        /var/www/tn3270rg/templates/main_page.html
        /var/www/tn3270rg/templates/status.html
        /var/www/tn3270rg/templates/error.html
        /var/www/tn3270rg/templates/manage_resources.html
        /var/www/tn3270rg/templates/manage_resources_confirm.html
        /var/www/tn3270rg/style.css
        /usr/local/sbin/tn3270rg.pl
        /etc/init.d/tn3270rg

AUTHOR

Curtis ``Mr_Person'' Hawthorne, mr_person@users.sourceforge.net