TN3270RG

File Release Notes and Changelog

Release Name: 1.1.1

Notes:
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: "!_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



Changes:
1.1.1 (12/20/2005)
----------
Switched to using Sys::Syslog (which is actively maintained
and is included in the main Perl distribution) and updated
all Syslog calls to prevent a highly unlikely (but still
possible) format string vulnerability.

Now cleanly exits from a SIGTERM with useful logging
information

1.1.0 (7/12/2004)
-----------------
Changed the DBI code to use eval and RaiseError instead of
die statements on every call, which makes it more robust and
flexible.

Added capability to survive a database disconnect.  When the
database is disconnected, existing sessions will continue to
function without any problems and can disconnect, but new
connections will be refused (because it can't find out what
resources are available from the database).  When the
database comes back up, the resource list will be updated
and new connections will be accepted.

1.0.1 (8/6/2003)
----------------
Fixed small bug that caused new resources added through the
web interface to be unavailable for use until the next
restart of the program.

1.0.0 (7/2/2003)
----------------
First public release