README.txt

   1 Version 2.3 (15 Jan 2002)
   2 CGIscriptor.pl and CGIservlet.pl (zipped tar file)
   3
   4 License:
   5 All programs are subject to the GNU Public License (GPL) version 2 or later.
   6 The text of the GPL is included in the distribution.
   7
   8 NOTE: Be sure to read the disclaimer in the GPL license and inside
   9 the perl scripts. Executing any of the scripts implies that you have
  10 agreed to these disclaimers in full.
  11
  12 Rob van Son
  13 R.J.J.H.vanSon@uva.nl
  14
  15 Security:
  16 Using these programs can pose security risks. They should be
  17 used with care, preferentially not on mission-critical systems or
  18 systems containing sensitive data. In case of doubt, run CGIservlet.pl
  19 with the -r option (i.e., restrict access to localhost).
  20 Note the disclaimer in the GPL license.
  21
  22 Requirements:
  23 CGIscriptor.pl requires perl 5.000, CGIservlet.pl requires perl 5.002.
  24 CGIservlet needs full socket support.  Currently, CGIservlet expects
  25 a perl link in the startup directory (or a full path on the first line of
  26 CGIservlet.pl).  The supplied StartServlet script will create a link to
  27 perl if it doesn't exist.
  28
  29 Unpacking:
  30 > tar -xzf CGIscriptor.tar.gz
  31
  32 ########################################################################
  33
  34 CGIscriptor.pl is a HTML 4 compliant script/module for integrating HTML,
  35 CGI, and perl scripts at the server side.
  36
  37 CGIservlet.pl is a pocket-size HTTP daemon that will run a single script.
  38
  39 Together with CGIscriptor.pl and a special file (BinaryMapFile.xmr),
  40 CGIservlet.pl will make a complete WWW-server that can fit a running
  41 Web-site on a single floppy.
  42
  43 Although this µ-server distribution itself is of some use (to me at least),
  44 it is only included as a demonstration of CGscriptor.pl.  Previous
  45 experience has shown me that most prospective users had difficulties
  46 accessing and configuring their web-servers.  Although adding CGIscriptor.pl
  47 to an Apache web-server amounts to adding a few directory paths to
  48 CGIscriptor.pl itself and only a single ScriptAlias line to the srm.conf
  49 file of Apache (and a HUP), even this seemed to be too intimidating.
  50 Therefore, this package runs out-of-the-box as a micro "web-site" to
  51 allow some experimenting before adding it to the "real" server.
  52
  53 ########################################################################
  54
  55 After unpacking the GNUzipped TAR file, the WWW server can be started
  56 with only three commands
  57 (sh, use your own path to perl 5.002 or higher, if necessary):
  58
  59 > cd CGIscriptor; ln -s /bin/perl perl; CGIservlet.pl 2>pid.log&
  60
  61 or
  62
  63 > cd CGIscriptor; StartServlet
  64 (StartServlet is an sh script that combines the last two commands)
  65
  66 It can be stopped with:
  67 > sh pid.log
  68 or
  69 > StopServlet
  70
  71 point your browser to URL:
  72 http://localhost:8080/
  73 or
  74 http://localhost:8080/Hello.html
  75
  76 If port 8080 is already in use on your platform, change the command to (sh):
  77 > cd CGIscriptor; ln -s /bin/perl perl; CGIservlet.pl -p 2345 2>pid.log&
  78 and use URL:
  79 http://localhost:2345/
  80 (or use any other convenient port number to replace 2345, you can also
  81 change StartServlet or the default setting inside CGIservlet.pl)
  82
  83 The package is configured to run "out-of-the-box" but can be fully
  84 configured to fit your personal environment.
  85
  86 Note:
  87 All programs contain their documentation as comments. Please read them.
  88 At the end of this file there is some more information on the
  89 installation procedure.
  90
  91 #######################################################################
  92
  93 The current default setting of CGIservlet.pl implements an interactive
  94 WWW server using the CGIscriptor package and the BinaryMapFile.xmr page.
  95 These settings correspond to:
  96  -p 8080
  97  -t `pwd`
  98  -b 'require "CGIscriptor.pl";'
  99  -e 'HandleRequest();'
 100  -d ''
 101  -w '/index.html'
 102  -c 32
 103  -l 32767
 104
 105 ########################################################################
 106
 107 The directory CGIscriptor contains:
 108 BinaryMapFile.xmr
 109 CGIscriptor.html
 110 CGIscriptor.pl
 111 CGIservlet.html
 112 CGIservlet.pl
 113 CGIservletSETUP.pl
 114 Hello.html
 115 README.txt
 116 StartServlet
 117 StopServlet
 118 gpl.html
 119 gpl.txt
 120 index.html
 121 philosophical-gnu-sm.jpg
 122 test.html
 123
 124 - StartServlet & StopServlet
 125 Two sh shell scripts to start and stop the servlet. The stop command
 126 and errors are written to pid.log. StartServlet creates a link to the
 127 perl interpreter if it doesn't exist.
 128
 129 - CGIservlet.pl
 130 A pocket-size HTTP daemon. The Internet connection for a WWW script or
 131 server.
 132
 133 - CGIscriptor.pl
 134 A CGI-aware HTML processor with server-side perl and shell script
 135 execution to serve up integrated HTML/Perl/CGI forms and documents.
 136 Works with any WWW-server that can execute perl scripts.  Together
 137 with CGIservlet.pl and BinaryMapFile.xmr this makes a full-fledged
 138 WWW-server.
 139
 140 - BinaryMapFile.xmr
 141 A special CGIscriptor.pl document that will serve binary files
 142 (CGIscriptor.pl only serves text-files). This file contains
 143 plain Perl code with a CGI connection.
 144 Currently, it implements two on-line 'tricks': BinaryMapFile.xmr
 145 will create on-line compressed files (.gz) and compressed archives
 146 (.tar.gz) whenever the appropriate extension is seen, e.g.,
 147 CGIscriptor.pl.gz will result in a GNU-zipped version of CGIscriptor.pl,
 148 and CGIscriptor.tar.gz will result in a compressed tar file of the whole
 149 CGIscriptor directory (stops at the $SERVER_ROOT directory).
 150 The other trick is that 'multipart/mixed' documents are created
 151 when a *-separated list of files is ended with the '.multipart' extension.
 152 For example: http://localhost:8080/audio.wav*Hello.html.multipart
 153 would result in a single multipart document being served containing
 154 both 'audio.wav' and 'Hello.html'.
 155
 156 - CGIscriptor.html
 157 The CGIscriptor manual of CGIscriptor.pl (i.e., the comments) in
 158 HTML format.
 159
 160 - CGIservlet.html
 161 The CGIservlet manual of CGIservlet.pl (i.e., the comments) in
 162 HTML format.
 163
 164 - Hello.html & test.html
 165 A sample integrated HTML/Perl/CGI document for CGIscriptor.pl.
 166
 167 - index.html
 168 A server-root home page for CGIservlet/CGIscriptor
 169
 170 - gpl.html
 171   gpl.txt
 172   philosophical-gnu-sm.jpg
 173 The GPL license and an attached GNU picture.
 174
 175 - README.txt
 176 This file.
 177
 178 #######################################################################
 179
 180 Installation:
 181 CGIscriptor.pl and CGIservlet.pl will come configured to run perl, or a
 182 link to it, from the "current" working directory (`pwd`). Change the
 183 first line in the files to point to your perl distribution if you want
 184 it otherwise.
 185
 186 CGIscriptor.pl can be added to the script directory of your WWW server.
 187 Default, CGIscriptor.pl will serve documents from the SERVER_ROOT directory
 188 tree.  You can point it to any other directory (see the text inside
 189 CGIscriptor.pl).
 190
 191 If your perl distribution (5.002 or higher) is configured to use sockets,
 192 you can start the demo version by entering:
 193
 194 > cd CGIscriptor
 195
 196 perform once:
 197 > ln -s /bin/perl perl          # a link to perl 5.002 is necessary
 198
 199 select one of:
 200 > CGIservlet.pl 2>pid.log&      # SH
 201 > CGIservlet.pl >&pid.log&      # CSH
 202
 203 or alternatively
 204 > cd CGIscriptor
 205 > StartServlet                  # combines the 'ln -s' and 'CGIservlet' commands
 206
 207 Pointing your browser to URL:
 208 http://localhost:8080/Hello.html
 209 should result in a page saying "Hello World" and displaying some HTTP
 210 related parameters.
 211 URL: http://localhost:8080/ gives a WWW vision on this distribution.
 212
 213 The file pid.log contains a 'kill -9' command and the process number of
 214 the servlet on the first line. To stop the servlet use:
 215 > sh pid.log
 216 or
 217 > StopServlet
 218
 219 All requests are logged in the file "Client.log".
 220
 221 NOTE: You can also run CGIscriptor.pl from the command line with the file path
 222 and query string as arguments. The resulting text will be send to STDOUT,
 223 e.g.:
 224 > CGIscriptor.pl 'Hello.html' 'Input=Get Out' 'Button=3'
 225 will print a lot of HTML text to your screen.