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 - Directories
 109 JavaScript
 110   CGIscriptorSession.js - Example JavaScript code for login sessions
 111   SecureHash.js - Cryptographic Secure Hash code for login sessions
 112 Private
 113   .Passwords    - Directory with server SALT and account information
 114   .Sessions     - Directory to store the Session Tickets
 115   ChangePassword.html - Example HTML file for password change
 116   Login.html    - Example HTML file for login page
 117   index.html    - Example HTML file
 118   manual.html   - Example HTML file
 119
 120
 121 - Files
 122 BinaryMapFile.xmr
 123 CGIscriptor.html
 124 CGIscriptor.pl
 125 CGIservlet.html
 126 CGIservlet.pl
 127 CGIservletSETUP.pl
 128 Hello.html
 129 README.txt
 130 StartServlet
 131 StopServlet
 132 gpl.html
 133 gpl.txt
 134 index.html
 135 philosophical-gnu-sm.jpg
 136 test.html
 137
 138 - StartServlet & StopServlet
 139 Two sh shell scripts to start and stop the servlet. The stop command
 140 and errors are written to pid.log. StartServlet creates a link to the
 141 perl interpreter if it doesn't exist.
 142
 143 - CGIservlet.pl
 144 A pocket-size HTTP daemon. The Internet connection for a WWW script or
 145 server.
 146
 147 - CGIscriptor.pl
 148 A CGI-aware HTML processor with server-side perl and shell script
 149 execution to serve up integrated HTML/Perl/CGI forms and documents.
 150 Works with any WWW-server that can execute perl scripts.  Together
 151 with CGIservlet.pl and BinaryMapFile.xmr this makes a full-fledged
 152 WWW-server.
 153
 154 - BinaryMapFile.xmr
 155 A special CGIscriptor.pl document that will serve binary files
 156 (CGIscriptor.pl only serves text-files). This file contains
 157 plain Perl code with a CGI connection.
 158 Currently, it implements two on-line 'tricks': BinaryMapFile.xmr
 159 will create on-line compressed files (.gz) and compressed archives
 160 (.tar.gz) whenever the appropriate extension is seen, e.g.,
 161 CGIscriptor.pl.gz will result in a GNU-zipped version of CGIscriptor.pl,
 162 and CGIscriptor.tar.gz will result in a compressed tar file of the whole
 163 CGIscriptor directory (stops at the $SERVER_ROOT directory).
 164 The other trick is that 'multipart/mixed' documents are created
 165 when a *-separated list of files is ended with the '.multipart' extension.
 166 For example: http://localhost:8080/audio.wav*Hello.html.multipart
 167 would result in a single multipart document being served containing
 168 both 'audio.wav' and 'Hello.html'.
 169
 170 - CGIscriptor.html
 171 The CGIscriptor manual of CGIscriptor.pl (i.e., the comments) in
 172 HTML format.
 173
 174 - CGIservlet.html
 175 The CGIservlet manual of CGIservlet.pl (i.e., the comments) in
 176 HTML format.
 177
 178 - Hello.html & test.html
 179 A sample integrated HTML/Perl/CGI document for CGIscriptor.pl.
 180
 181 - index.html
 182 A server-root home page for CGIservlet/CGIscriptor
 183
 184 - gpl.html
 185   gpl.txt
 186   philosophical-gnu-sm.jpg
 187 The GPL license and an attached GNU picture.
 188
 189 - README.txt
 190 This file.
 191
 192 #######################################################################
 193
 194 Installation:
 195 CGIscriptor.pl and CGIservlet.pl will come configured to run perl, or a
 196 link to it, from the "current" working directory (`pwd`). Change the
 197 first line in the files to point to your perl distribution if you want
 198 it otherwise.
 199
 200 CGIscriptor.pl can be added to the script directory of your WWW server.
 201 Default, CGIscriptor.pl will serve documents from the SERVER_ROOT directory
 202 tree.  You can point it to any other directory (see the text inside
 203 CGIscriptor.pl).
 204
 205 If your perl distribution (5.002 or higher) is configured to use sockets,
 206 you can start the demo version by entering:
 207
 208 > cd CGIscriptor
 209
 210 perform once:
 211 > ln -s /bin/perl perl          # a link to perl 5.002 is necessary
 212
 213 select one of:
 214 > CGIservlet.pl 2>pid.log&      # SH
 215 > CGIservlet.pl >&pid.log&      # CSH
 216
 217 or alternatively
 218 > cd CGIscriptor
 219 > StartServlet                  # combines the 'ln -s' and 'CGIservlet' commands
 220
 221 Pointing your browser to URL:
 222 http://localhost:8080/Hello.html
 223 should result in a page saying "Hello World" and displaying some HTTP
 224 related parameters.
 225 URL: http://localhost:8080/ gives a WWW vision on this distribution.
 226
 227 The file pid.log contains a 'kill -9' command and the process number of
 228 the servlet on the first line. To stop the servlet use:
 229 > sh pid.log
 230 or
 231 > StopServlet
 232
 233 All requests are logged in the file "Client.log".
 234
 235 NOTE: You can also run CGIscriptor.pl from the command line with the file path
 236 and query string as arguments. The resulting text will be send to STDOUT,
 237 e.g.:
 238 > CGIscriptor.pl 'Hello.html' 'Input=Get Out' 'Button=3'
 239 will print a lot of HTML text to your screen.