go4gw version 1.01
------------------

go4gw is a daemon which can handle many different gopher gateways
written in perl. It should be started from inetd.

Bugs to gopher@boombox.micro.umn.edu

INSTALLATION
------------

You need to put the following line in /etc/services:

go4gw     	4320/tcp

And the following line in /etc/inetd.conf (depending on your system type):

go4gw  stream  tcp     nowait  /usr/local/etc/go4gw  go4gw

The go4gw script has a few variables you might want to change:

$Gconf_file = "/usr/local/etc/go4gw.conf"; # configuration file
$Gport=4320;                               # port THIS daemon is running on
$Ghost="Slapshot.Stanford.EDU";            # host THIS daemon is running on

You need to set Gport to the same port as in /etc/services, and Ghost to
your fully qualified host name.

Why aren't these two auto-magically figured out?
Mainly for speed, but also because some `hostname` commands don't
have the domain, some do, etc. Its easier just to define them here.
Since all the other gateways are run in the context of this perl script,
the gateways don't need any of this stuff in them.

Gconf_file should be set to the location of your go4gw.conf file. The
format of this file is:

#
# format
# gateway : user : module : gopher title
#
whois:-2:/usr/local/etc/g2whois:Whois:
nntp:-2:/usr/local/etc/g2nntp:USENET News:
webster:-2:/usr/local/etc/g2webster:Webster:
#

Where gateway is the name of the gateway, user is either a numeric uid
or name,  module is the name of the perl script that go4gw will dynamically 
load, and title is the title that will show up in the gopher menu if go4gw 
is sent the string "". If the gateway doesn't take an empty string, the title
should be "" and it won't show up in the menu. By writing all your gateways so
they take a "" command, you can point a link at the go4gw daemon with
path set to "" and get a menu of all your gateways. The menu order will
be the same order as the go4gw.conf file.

Once you've done all this configuration you'll want to try HUP inetd.
Then you can test it out by running a gopher client to the newly
created port..


Writing go4gw gateways
-----------------------
go4gw gateways need to a follow a few simple conventions:

You need to have a routine called "${gateway}_main", where gateway
is the name of your gateway. For example, if your gateway is called 
whois, then you need:

whois_main {
  local($_) = @_;
  ...
}

In your module (/usr/local/etc/g2whois for example).

Your *_main will be passed the string sent to go4gw WITHOUT your gateway 
prefix. For example, if someone sends the following string to go4gw:

nntp ls su.jobs

Then go4gw will call &nntp_main("ls su.jobs"),  after loading g2nntp.

You should define any variables that users might have to change at the
front of your script, and prefix them with your gateway name. 

When your gateway has to return selector string, hostname, and port, it
should use the following variables:

$Ggw    -> name of this gateway
$Gport  -> port this gateway is running on
$Ghost  -> host this gateway is running on

For example, nntp might do the following:

&Greply("0$Subject\t$Ggw article $group $article\t$Ghost\t$Gport");

So when the user selects this they will send:

nntp article su.jobs 104

Back to the go4gw daemon, which will figure out that "article su.jobs 104"
needs to get passed to g2nntp.

The following variables and routines are defined in go4gw, and can be used 
by gateways:

$GnotServer    You can define this in perl scripts that want to include
               the go4gw script without running the server. See the
               g2nntp_groups script.

$Ggw           Can be used by gateway routines to determine their gateway     
               name.

$Gport         Can be used by gateway routines to determine which port go4gw
               is running on.

$Ghost         Can be used by gateway routines to determine which host go4gw
               is running on.

GSERVER        File handle which is opened when GopenServer is called.

&Greply(reply) Sends string back to gopher client with \r\n on the end.

&Gabort(mess)  Sends error message back to gopher client with 
               "3mess\r\n.\r\n" on end.
              
&GopenServer(server,port)
               Opens TCP port at server or calls Gabort.

&GcloseServer  Closes server.

$Gdebug        define this to turn on debugging in &Gsend and &Grecv.

&Gsend(cmd)    Sends "cmd\r\n" to GSERVER.

$_ = &Grecv;   Gets response from GSERVER and strips \r and \n.

&Gsorry        Sends message about data that cannot be delivered due to
               restrictions.

Other "standard" routines and variables may be added. They will start
with a 'G'.

Roland