home *** CD-ROM | disk | FTP | other *** search
/ Mega Top 1 / os2_top1.zip / os2_top1 / APPS / DATACOM / INTERNET / GOSERV / GOHTTP.DOC < prev    next >
Text File  |  1995-02-14  |  11KB  |  250 lines
  1.                                                                GoServe 2.00
  2. How to start using GoServe as a Web server
  3. """"""""""""""""""""""""""""""""""""""""""
  4.  
  5. Copyright (c) International Business Machines Corporation, 1994, 1995.
  6. All rights reserved.
  7.  
  8.  
  9. Introduction
  10. """"""""""""
  11. 'GoServe' is a multi-purpose server for OS/2, which supports the
  12. HyperText Transfer Protocol (HTTP), used by the World-Wide Web (often
  13. known as 'the Web' or 'WWW').
  14.  
  15. Providing that you already have TCP/IP installed and started, GoServe
  16. can be running and serving documents and other files across a network in
  17. minutes.  There are no configuration files to be edited first.
  18.  
  19. This document describes how to use GoServe as a Web server, and includes
  20. instructions on how to set up your own home page.  GOHTTP.ZIP includes a
  21. working home page and customization filter, together with several other
  22. sample pages.  The GoServe Web documentation is also included, linked to
  23. the sample home page.
  24.  
  25. Note: It is assumed that you have some familiarity with the Web, and
  26. have (and know how to use) a Web client, such as Web Explorer.
  27.  
  28.  
  29. Quick start
  30. """""""""""
  31. Assuming you have unzipped GOSERV.ZIP into the directory of your choice
  32. (for example, D:\GOSERVE), then:
  33.  
  34.   1. Open an OS/2 window
  35.  
  36.   2. Unzip the included file GOHTTP.ZIP to a different directory.  To
  37.      use the default setup, put this 'data directory' on the same drive
  38.      as the first directory, and call it GOHTTP (for example, D:\GOHTTP).
  39.  
  40.   3. Change your current directory back to the GoServe directory (for
  41.      example, D:\GOSERVE)
  42.  
  43.   4. Start GoServe with the parameter "http", for example using:
  44.  
  45.        start goserve http
  46.  
  47. You should then see a GoServe window (titled 'GoServe [HTTP]') appear.
  48. If there are no error messages, the server is now active, and you should
  49. be able to connect to the sample pages with any Web browser (available
  50. as a separate program).  For example, if the name of your machine is
  51. "fred.hursley.ibm.com" (use the "hostname" command to find it out if you
  52. don't know it) then specifying a URL of "http://fred.hursley.ibm.com/"
  53. should display the sample home page.
  54.  
  55. --- Setting up an icon for GoServe ---
  56.  
  57. To set up an icon (program reference object) for a GoServe Web server
  58. and (optionally) ensure that GoServe is started automatically when OS/2
  59. is booted:
  60.  
  61.   1. With your current directory being the GoServe directory (for
  62.      example, D:\GOSERVE), run the command:
  63.  
  64.        makeicon http
  65.  
  66.      This should make an icon called 'GoServe - Web' appear on the
  67.      Desktop.  You can Move or drag it to another folder if you wish.
  68.      The server can now be started by clicking on the new icon (you may
  69.      want to check that this works).
  70.  
  71.   2. Open the Startup folder (this may be on the Desktop or in the 'OS/2
  72.      System' folder).
  73.  
  74.   3. Make a shadow of the GoServe icon in the Startup folder.  To do
  75.      this, hold down the Ctrl+Shift keys and then drag the icon to the
  76.      Startup folder, drop it, and release Ctrl+Shift.  (See the OS/2
  77.      documentation if you need more details.)
  78.  
  79. With the shadow in the Startup folder, the server will be started
  80. automatically whenever OS/2 is booted or rebooted.
  81.  
  82.  
  83. Your own home page
  84. """"""""""""""""""
  85. The sample filter can be used to serve files such as HTML documents,
  86. images, and so on, without any changes or programming.  All you need to
  87. do is change the data files.
  88.  
  89. Here's what you need to do to set up your own 'home page', given that
  90. the sample page above works:
  91.  
  92.   1. Make a new directory for your own World-Wide Web data (for example,
  93.      called D:\WWWHOME).
  94.  
  95.   2. Copy the file D:\GOHTTP\INDEX.HTM to your new directory, and modify
  96.      it to make your 'home page'.  To start with, to see if it works,
  97.      it's probably best to change a few words only.  For example, change
  98.      the line
  99.  
  100.        Welcome to this sample home page.
  101.  
  102.      to something different.
  103.  
  104.      If you leave any references in it to any of the other sample files,
  105.      you'll need to copy those over, too, for the links to work.
  106.  
  107.   3. If GoServe is not already running, start it as before (don't forget
  108.      the 'HTTP' parameter, if starting from a command prompt).
  109.  
  110.      Choose 'Directory selection' from the 'Options' menu, and use the
  111.      dialog there to change the data directory to be your new directory
  112.      (for example, to D:\WWWHOME).
  113.  
  114.   4. Try your favourite WWW client, connecting to your machine as before,
  115.      and it should now display your new home page.
  116.  
  117.   5. All you have to do now is modify the home page to your liking.
  118.      Most of the tags needed (<h1> indicates Header level 1, etc.) are
  119.      quite simple to use, but you'll probably want to find an
  120.      introduction to the tag language (HTML, the HyperText Markup
  121.      Language).  A good place to start is the Web "home" at CERN:
  122.      http://info.cern.ch/
  123.  
  124. All of the details above can be customized if you wish, but you will
  125. probably need to learn more about GoServe and Rexx to change things
  126. effectively.  Please see GOSERVE.DOC for more information.
  127.  
  128.  
  129. An overview on how GoServe works
  130. """"""""""""""""""""""""""""""""
  131. (To make sense of this, you may need to read GOSERVE.DOC too.)
  132.  
  133. Whenever a client connects to your machine, it sends a 'request string'.
  134. GoServe receives the string and passes it to a 'filter'.  This filter (a
  135. program, written in Rexx) checks that the request is valid, and normally
  136. responds with a file (such as an HTML document or a GIF image file).  It
  137. is the filter's responsibility to choose or create the file, given the
  138. incoming request string.
  139.  
  140. A sample filter (GoFilter.80) is provided--see commentary in that
  141. program for details.  In brief, it asks the server for the name of the
  142. data directory, checks for certain errors, and then processes the
  143. request according to the verb (method) specified in the request.
  144.  
  145. Notes:
  146.  
  147.   1. The sample filter gets the root, or home, directory for the data it
  148.      is to serve by calling the DATADIR() function.  The value this
  149.      returns is set by GoServe (which, in turn, is derived from the
  150.      GoServe startup parameter or the Directory Selection dialog).
  151.  
  152.   2. Only the most common verbs are handled by the sample filter:
  153.  
  154.        o GET is the most common ('send me some data') request.  In most
  155.          cases, this sends back a file to the client, using the GoServe
  156.          FILE command.
  157.  
  158.        o HEAD is the same as GET, except that the data are not sent back
  159.          to the client.  GoServe automatically ensures that only
  160.          'header' lines, which describe the data, are sent.  HTTP
  161.          requires that all servers handle both GET and HEAD verbs.
  162.  
  163.        o POST is used by a client when data are to be sent to the server
  164.          (for example, text filled in for a Form, or a "post" to a
  165.          newsgroup).  When the data is known to be short (fewer than 250
  166.          characters), GET may be used instead; the specification of
  167.          which method to use is included in the <form ...> tag of the
  168.          source document.
  169.  
  170.   3. A default document is provided if none is specified.
  171.      Conventionally, this is called 'index.htm' or 'index.html'; a
  172.      sample 'index.htm' is provided (you can rename this to 'index.html'
  173.      if you are using an HPFS disk).
  174.  
  175.   4. The TYPE option, where specified on a FILE response, indicates that
  176.      the server should prefix an HTTP 'OK' response and header to the
  177.      beginning of the file returned.  The TYPE option is followed by the
  178.      MIME type (e.g., text/html or image/gif) of the file being
  179.      returned.  Web servers should normally always specify a TYPE on a
  180.      FILE command.
  181.  
  182.   5. Requests should be specified in URI form in that forward slashes
  183.      should be used instead of backslashes to indicate directories.  For
  184.      example, with the sample setup, the tag <a href="fred/%7Edata.htm">
  185.      would cause the filter to receive the URI '/fred/%7Edata.htm'.  The
  186.      packed URI (third argument string) would then be 'fred/~data.htm'.
  187.      The filter then prefixes the home directory name, resulting in a
  188.      file specification such as 'd:/gohttp/fred/~data.htm'.  This would
  189.      refer to the OS/2 file 'd:\gohttp\fred\~data.htm'.  GoServe
  190.      (actually the OS/2 I/O routines) will make the appropriate '/' to
  191.      '\' adjustments.
  192.  
  193.   6. Errors are signalled to the client by sending back files that start
  194.      with the appropriate HTTP header line; these are generated by an
  195.      internal subroutine, which can be modified for more detailed or
  196.      personal error messages.  This subroutine could be made external if
  197.      the TEMPFILE value is passed as an argument when it is called.
  198.  
  199.   7. The sample 'globemap' routine shows how the coordinates of a click
  200.      on an active image can be processed.  This particular routine
  201.      returns the coordinates as a percentage of half the image size,
  202.      relative to the middle and with map-style coordinates (X is
  203.      positive to the East, Y is positive to the North).
  204.  
  205.   8. Certain special 'test and control' requests are supported by the
  206.      sample filter (for example, return server statistics).  In the
  207.      sample filter, these are only allowed from a client with the same
  208.      address as the server.  Other possibilities include allowing 'ANY'
  209.      as the allowed name [so anyone can use them], or, conversely, using
  210.      a privately-selected URL for the controls--which would act as a
  211.      password.  See GOSERVE.DOC for more information on control options.
  212.  
  213.   9. HTTP defines a simple 'basic' access control mechanism, and an
  214.      example of using this is included in the filter and sample pages.
  215.      When used, the person using the browser is prompted for a userid
  216.      and password; the filter checks the validity of this.
  217.  
  218.  
  219. Data organization and setup
  220. """""""""""""""""""""""""""
  221. It is recommended that the control and execution files be placed in a
  222. directory separate from your data, perhaps called GOSERVE.  This may be
  223. the same directory as is already being used for running a Gopher server,
  224. as the control files (Filter, audit files, etc.) will normally have a
  225. different extension (.80).
  226.  
  227. Note that the filter must be in the working directory for GoServe,
  228. though you may change its name (an extension matching the port is
  229. recommended).  If you make changes to the default filter, it's a good
  230. idea to change its name, too, so if you install a new version of GoServe
  231. your filter will not be overwritten by the new default filter.
  232.  
  233. The sample filter assumes that the data are held in a tree starting at
  234. the directory known by GoServe as the data directory (by default,
  235. GoServe assumes that is the directory '\gohttp' on the same drive as the
  236. working directory).  You should normally change this, using GoServe, to
  237. point to a different subdirectory tree that holds your own data.  This
  238. tree can be on any drive and start at any depth (it may even start at
  239. the root directory of a disk).
  240.  
  241. Note that the sample filter allows unrestricted access to all files in
  242. the subtree starting at your data directory.
  243.  
  244. For more details, see GOSERVE.DOC.
  245.  
  246. - - - - -
  247.  
  248. Mike Cowlishaw, IBM UK Laboratories
  249. mfc@vnet.ibm.com
  250.