Shasum adaption
[CGIscriptor.git] / README.txt
blob21bd020fd053a78c57b46591948518d27412dd9e
1 Version 2.3 (15 Jan 2002)
2 CGIscriptor.pl and CGIservlet.pl (zipped tar file) 
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.
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.
12 Rob van Son
13 R.J.J.H.vanSon@uva.nl
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.
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.
29 Unpacking:
30 > tar -xzf CGIscriptor.tar.gz
32 ########################################################################
34 CGIscriptor.pl is a HTML 4 compliant script/module for integrating HTML, 
35 CGI, and perl scripts at the server side.  
37 CGIservlet.pl is a pocket-size HTTP daemon that will run a single script.  
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. 
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.
53 ########################################################################
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):
59 > cd CGIscriptor; ln -s /bin/perl perl; CGIservlet.pl 2>pid.log& 
63 > cd CGIscriptor; StartServlet
64 (StartServlet is an sh script that combines the last two commands)
66 It can be stopped with:
67 > sh pid.log 
69 > StopServlet
71 point your browser to URL:
72 http://localhost:8080/
74 http://localhost:8080/Hello.html
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)
83 The package is configured to run "out-of-the-box" but can be fully 
84 configured to fit your personal environment.
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.
91 #######################################################################
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
105 ########################################################################
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
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.
129 - CGIservlet.pl
130 A pocket-size HTTP daemon. The Internet connection for a WWW script or 
131 server.
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.
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'.
156 - CGIscriptor.html
157 The CGIscriptor manual of CGIscriptor.pl (i.e., the comments) in
158 HTML format.
160 - CGIservlet.html
161 The CGIservlet manual of CGIservlet.pl (i.e., the comments) in
162 HTML format.
164 - Hello.html & test.html
165 A sample integrated HTML/Perl/CGI document for CGIscriptor.pl.
167 - index.html
168 A server-root home page for CGIservlet/CGIscriptor
170 - gpl.html
171   gpl.txt
172   philosophical-gnu-sm.jpg
173 The GPL license and an attached GNU picture.
175 - README.txt
176 This file.
178 #######################################################################
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.
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).
191 If your perl distribution (5.002 or higher) is configured to use sockets, 
192 you can start the demo version by entering:
194 > cd CGIscriptor
196 perform once:
197 > ln -s /bin/perl perl          # a link to perl 5.002 is necessary
199 select one of:
200 > CGIservlet.pl 2>pid.log&      # SH
201 > CGIservlet.pl >&pid.log&      # CSH
203 or alternatively
204 > cd CGIscriptor
205 > StartServlet                  # combines the 'ln -s' and 'CGIservlet' commands
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.
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
217 > StopServlet
219 All requests are logged in the file "Client.log".
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.