OS/2 Shareware BBS: 35 Internet/35-Internet.zip/gosrv250.zip/gogopher.doc

Text File | 1997-02-07 | 12KB | 281 lines

                                                               GoServe 2.50
How to start using GoServe as a Gopher server
"""""""""""""""""""""""""""""""""""""""""""""

Copyright (c) IBM Corporation, 1994, 1995.  All rights reserved.


Introduction
""""""""""""
'GoServe' is a multi-purpose server for OS/2, which supports the
'Gopher' client-server protocol (as well as the World-Wide Web
protocol).  The Gopher protocol is described in documents distributed by
the University of Minnesota Microcomputer and Workstation Networks
Center.

Providing that you already have TCP/IP installed and started, GoServe
can be running and serving files across a network in minutes.

This document describes how to use GoServe as a Gopher server, and
includes instructions on how to set up your own main menu.  GOGOPHER.ZIP
includes a working sample main menu and customization filter, together
with other sample data.

Note: It is assumed that you have some familiarity with Gopher, and have
(and know how to use) a Gopher client.


Quick start
"""""""""""
Assuming you have unzipped GOSERV.ZIP into the directory of your choice
(for example, D:\GOSERVE), then:

  1. Open an OS/2 window

  2. Unzip the included file GOGOPHER.ZIP to a different directory.  To
     use the default setup, put this 'data directory' on the same drive
     as the first directory, and call it GOGOPHER (for example,
     D:\GOGOPHER).

  3. The sample files include two menu templates; you must generate
     working menu files from these which include your network address.
     To do this, run the GOSMENU.CMD command against the two templates,
     using these two commands:

        gosmenu mainmenu.men
        gosmenu test.men

     Assuming no errors were reported there should now be two new files
     in the directory (MAINMENU.70 and TEST.70).

  4. Change your current directory back to the GoServe directory (for
     example, D:\GOSERVE)

  5. Start GoServe with the parameter "gopher", for example using:

       start goserve gopher

You should then see a GoServe window (titled 'GoServe [Gopher]') appear.
If there are no error messages, the server is now active, and you should
be able to connect to the sample pages with any Gopher client.  For
example, if the name of your machine is "fred.hursley.ibm.com", specify
this as the name for Gopher to use.  The OS/2 Gopher client (available
separately) may be started with this name as a command line parameter,
thus:

  start gopher fred.hursley.ibm.com

If GOPHER.EXE is neither in the current directory nor is in a directory
on your PATH, you will need to include its directory information in the
command, for example:

  start e:\tools\gopher fred.hursley.ibm.com

Alternatively, you should be able to use a World-Wide Web client by, for
example, specifying a URL of "gopher://fred.hursley.ibm.com/".

If you don't know the name of your machine, try the command "hostname"
from an OS/2 prompt.

--- Setting up an icon for GoServe ---

To set up an icon (program reference object) for a GoServe gopher
server and (optionally) ensure that GoServe is started automatically
when OS/2 is booted:

  1. With your current directory being the GoServe directory (for
     example, D:\GOSERVE), run the command:

       makeicon gopher

     This should make an icon called 'GoServe - Gopher' appear on the
     Desktop.  You can Move or drag it to another folder if you wish.
     The server can now be started by clicking on the new icon (you may
     want to check that this works).

  2. Open the Startup folder (this may be on the Desktop or in the 'OS/2
     System' folder).

  3. Make a shadow of the GoServe icon in the Startup folder.  To do
     this, hold down the Ctrl+Shift keys and then drag the icon to the
     Startup folder, drop it, and release Ctrl+Shift.  (See the OS/2
     documentation if you need more details.)

With the shadow in the Startup folder, the server will be started
automatically whenever OS/2 is booted or rebooted.


Your own main menu
""""""""""""""""""
The sample filter can be used to serve different menus and files without
any changes or programming.  All you need to do is change the data
files.

Here's what you need to do to set up your own 'main menu', given that
the sample described above works:

  1. Make a new directory for your own Gopher data (for example,
     called D:\GODATA).

  2. Copy the files from the sample directory to your new directory,
     using (for example):

       copy d:\gogopher\*.* d:\godata

     This leaves the original files unchanged, as a backup.

  3. Modify the file ABOUT.DOC in your new directory, to refer to your
     own address and so on.  To start with, to see if it works, it's
     probably best to change a few words only.  For example, change the
     line

       Administrator: Your Name Here

     to something more helpful.

  4. If GoServe is not already running, start it as before (don't forget
     the 'GOPHER' parameter, if starting from a command prompt).

     Choose 'Directory selection' from the 'Options' menu, and use the
     dialog there to change the data directory to be your new directory
     (for example, to D:\GODATA).

  5. Try your favourite Gopher client, connecting to your machine as
     before, and it should now display your main menu; selecting 'About
     this Gopher server' should then display your new ABOUT.DOC.

  6. All you have to do now is modify the data to your liking.
     To add documents or menus to the main menu, you will need to edit
     the file MAINMEN.MEN -- see below for details of the format.

All of the details above can be customized if you wish, but you will
probably need to learn more about GoServe and Rexx to change things
effectively.  Please see GOSERVE.DOC for more information.


An overview on how GoServe works
""""""""""""""""""""""""""""""""
(To make sense of this, you may need to read GOSERVE.DOC too.)

Whenever a client connects to your machine, it sends a 'request string'.
GoServe receives the string and passes it to a 'filter'.  This filter (a
program, written in Rexx) checks that the request is valid, and normally
responds with a file (such as an document or a menu file).  It is the
filter's responsibility to choose or create the file, given the incoming
request string.

A sample filter (GoFilter.70) is provided--see commentary in that
program for details.  In brief, it asks the server for the name of the
data directory, checks for certain errors, and then processes the
request according to the contents of the request string.

Notes:

  1. The sample filter gets the root, or home, directory for the data it
     is to serve by calling the DATADIR() function.  The value this
     returns is set by GoServe (which, in turn, is derived from the
     GoServe startup parameter or the Directory Selection dialog).

  2. A default menu is provided if none is specified.  Conventionally,
     this is called 'mainmenu.70' (you can change this if you wish).
     A sample 'mainmenu.men', from which 'mainmenu.70' can be generated,
     is provided.

  3. Certain special 'test and control' selectors are supported by the
     sample filter (for example, return server statistics).  In the
     sample filter, these are only allowed from a client with the same
     address as the server, or those listed in the filter.  Other
     possibilities include not checking the client's address [so anyone
     can use them], or, conversely, using a privately-selected selector
     string for the controls--which would act as a password.  See
     GOSERVE.DOC for more information on control options.

  4. File names in selectors or the FILE command can be specified with
     either forward slashes or backslashes as directory separators.
     Forward slashes are recommended, as some Unix-based clients may not
     correctly handle backslashes.


Data organization and setup
"""""""""""""""""""""""""""
It is recommended that the control and execution files be placed in a
directory separate from your data, perhaps called GOSERVE.  This may be
the same directory as is already being used for running a Web server,
as the control files (Filter, audit files, etc.) will have a different
extension (.70).

Note that the filter must be in the working directory for GoServe,
though you may change its name (an extension matching the port is
recommended).  If you make changes to the default filter, it's a good
idea to change its name, too, so if you install a new version of GoServe
your filter will not be overwritten by the new default filter.

The sample filter assumes that the data are held in a tree starting at
the directory known by GoServe as the data directory (by default,
GoServe assumes that is the directory '\gogopher' on the same drive as
the working directory).  You should normally change this, using GoServe,
to point to a different subdirectory tree that holds your own data.
This tree can be on any drive and start at any depth (it may even start
at the root directory of a disk).

Note that the sample filter allows unrestricted access to all files in
the subtree starting at your data directory.

For more details, see GOSERVE.DOC.


GOSMENU.CMD
"""""""""""
The GoServe package includes a simple utility in the GoGopher collection
that makes it easier to create 'canonical' Gopher menu files.  See the
start of GOSMENU.CMD for details.  A 'menu template' file, perhaps
called MAINMENU.MEN, might look like this:

  Sample main menu
  ; rexx.central.edu 70
  0 About this Gopher server; about.doc
  1 IBM Almaden Gopher server;; index.almaden.ibm.com
  1 Test and control menu; test.70

The first line is a description; the second gives the field separator
character (which will become Tab in the generated menu), together with
the default server address and port.  (If the last two are not
specified, GOSMENU will try and determine the address from TCP/IP, and
will assume the port is 70.)

Subsequent lines are menu lines, as required by the Gopher protocol.
Lines whose first character is a blank are ignored (that is, they are
not included in the menu file).  If the first character is a 0, the menu
line refers to a document; a 1 indicates a menu is expected; 9 indicates
a binary file (such as a Zip file), and so on.

Running GOSMENU against this file (with a different output filename)
like this:

  gosmenu mainmenu.men mainmenu.70

will create a 'canonical' menu file, with real tab characters instead of
semicolons, address and port added where required, and extra blanks
removed.  The Gopher protocol suggests that the first (description)
field be no more than 70 characters, and requires that the entire menu
line (including address and port) fit within 255 characters.

Notes:

  1. The default output filename for GOSMENU.CMD is constructed by
     replacing the extension of the input filename by '70', so the
     sample command could have been simply:

       gosmenu mainmenu.men

     Or, of course, the file MAINMENU.MEN could simply have been dropped
     on a Program Reference object that starts GOSMENU.CMD

  2. It is recommended that 'active' menu files be identified by an
     extension which is the Gopher port for which they are to be used.

- - - - -

Mike Cowlishaw, IBM UK Laboratories
[e-mail]