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

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

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

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


Introduction
""""""""""""
'GoServe' is a multi-purpose server for OS/2, which supports the
HyperText Transfer Protocol (HTTP), used by the World-Wide Web (often
known as 'the Web' or 'WWW').

Providing that you already have TCP/IP installed and started, GoServe
can be running and serving documents and other files across a network in
minutes.  There are no configuration files to be edited first.

This document describes how to use GoServe as a Web server, and includes
instructions on how to set up your own home page.  GOHTTP.ZIP includes a
working home page and customization filter, together with several other
sample pages.  The GoServe Web documentation is also included, linked to
the sample home page.

Note: It is assumed that you have some familiarity with the Web, and
have (and know how to use) a Web client, such as Web Explorer.


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 GOHTTP.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 GOHTTP (for example, D:\GOHTTP).

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

  4. Start GoServe with the parameter "http", for example using:

       start goserve http

You should then see a GoServe window (titled 'GoServe [HTTP]') 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 Web browser (available
as a separate program).  For example, if the name of your machine is
"fred.hursley.ibm.com" (use the "hostname" command, while connected to
your network, to find it out if you don't know it) then specifying a URL
of "http://fred.hursley.ibm.com/" should display the sample home page.

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

To set up an icon (program reference object) for a GoServe Web 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 http

     This should make an icon called 'GoServe - Web' 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 home page
""""""""""""""""""
The sample filter can be used to serve files such as HTML documents,
images, and so on, 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 'home page', given that
the sample page above works:

  1. Make a new directory for your own World-Wide Web data (for example,
     called D:\WWWHOME).

  2. Copy the file D:\GOHTTP\INDEX.HTM to your new directory, and modify
     it to make your 'home page'.  To start with, to see if it works,
     it's probably best to change a few words only.  For example, change
     the line

       Welcome to this sample home page.

     to something different.

     If you leave any references in it to any of the other sample files,
     you'll need to copy those over, too, for the links to work.

  3. If GoServe is not already running, start it as before (don't forget
     the 'HTTP' 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:\WWWHOME).

  4. Try your favourite WWW client, connecting to your machine as before,
     and it should now display your new home page.

  5. All you have to do now is modify the home page to your liking.
     Most of the tags needed (<h1> indicates Header level 1, etc.) are
     quite simple to use, but you'll probably want to find an
     introduction to the tag language (HTML, the HyperText Markup
     Language).  A good place to start is the Web "home" at CERN:
     http://info.cern.ch/

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.

This document, the latest GoServe package, and other relevant links,
information, and programs are available at the GoServe Web page at
http://www2.hursley.ibm.com/goserve/


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 HTML document or a GIF image file).  It
is the filter's responsibility to choose or create the file, given the
incoming request string.

A sample filter (GoFilter.80) 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 verb (method) specified in the request.

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. Only the most common verbs are handled by the sample filter:

       o GET is the most common ('send me some data') request.  In most
         cases, this sends back a file to the client, using the GoServe
         FILE command.

       o HEAD is the same as GET, except that the data are not sent back
         to the client.  GoServe automatically ensures that only
         'header' lines, which describe the data, are sent.  HTTP
         requires that all servers handle both GET and HEAD verbs.

       o POST is used by a client when data are to be sent to the server
         (for example, text filled in for a Form, or a "post" to a
         newsgroup).  When the data is known to be short (fewer than 250
         characters), GET may be used instead; the specification of
         which method to use is included in the <form ...> tag of the
         source document.

  3. A default document is provided if none is specified.
     Conventionally, this is called 'index.htm' or 'index.html'; a
     sample 'index.htm' is provided (you can rename this to 'index.html'
     if you are using an HPFS disk).

  4. The TYPE option, where specified on a FILE response, indicates that
     the server should prefix an HTTP 'OK' response and header to the
     beginning of the file returned.  The TYPE option is followed by the
     MIME type (e.g., text/html or image/gif) of the file being
     returned.  Web servers should normally always specify a TYPE on a
     FILE command.

  5. Requests should be specified in URI form in that forward slashes
     should be used instead of backslashes to indicate directories.  For
     example, with the sample setup, the tag <a href="fred/%7Edata.htm">
     would cause the filter to receive the URI '/fred/%7Edata.htm'.  The
     packed URI (third argument string) would then be 'fred/~data.htm'.
     The filter then prefixes the home directory name, resulting in a
     file specification such as 'd:/gohttp/fred/~data.htm'.  This would
     refer to the OS/2 file 'd:\gohttp\fred\~data.htm'.  GoServe
     (actually the OS/2 I/O routines) will make the appropriate '/' to
     '\' adjustments.

  6. Errors are signalled to the client by sending back files that start
     with the appropriate HTTP header line; these are generated by an
     internal subroutine, which can be modified for more detailed or
     personal error messages.  This subroutine could be made external if
     the TEMPFILE value is passed as an argument when it is called.

  7. The sample 'globemap' routine shows how the coordinates of a click
     on an active image can be processed.  This particular routine
     returns the coordinates as a percentage of half the image size,
     relative to the middle and with map-style coordinates (X is
     positive to the East, Y is positive to the North).

  8. Certain special 'test and control' requests 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.  Other possibilities include allowing 'ANY'
     as the allowed name [so anyone can use them], or, conversely, using
     a privately-selected URL for the controls--which would act as a
     password.  See GOSERVE.DOC for more information on control options.

  9. HTTP defines a simple 'basic' access control mechanism, and an
     example of using this is included in the filter and sample pages.
     When used, the person using the browser is prompted for a userid
     and password; the filter checks the validity of this.


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 Gopher server,
as the control files (Filter, audit files, etc.) will normally have a
different extension (.80).

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 '\gohttp' 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.

- - - - -

Mike Cowlishaw, IBM UK Laboratories
[e-mail]