NAME
TN3270RG - TN3270 Resource Gateway
REQUIREMENTS
- Perl 5.6
- Perl modules
- DBI and DBD::Pg modules
- Proc::Daemon
- Proc::PID_File
- POE
- POE::Wheel::ReadWrite
- POE::Wheel::SocketFactory
- POE::Filter::Stream
- Socket
- Template Toolkit
- Sys::Syslog
- CGI
- PostgreSQL database
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: "!TN3270RGRESOURCE_!".
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