CGIservlet

A HTTPd "connector" for running CGI scripts on unix systems as WWW accessible Web sites. The servlet starts a true HTTP daemon that channels HTTP requests to forked daughter processes. CGIservlet.pl is NOT a full fledged server. Moreover, this servlet is definitely NOT intended as a replacement for a real server (e.g., Apache). It's design goal was SIMPLICITY, and not mileage.

Note that a HTTP server can be accessed on your local machine WITHOUT internet access (but WITH a DNS?): use "http://localhost[:port]/[path]" or "http://127.0.0.1[:port]/[path]" as the URL. It is also easy to restrict access to the servlet to localhost users (i.e., the computer running the servlet).

Suggested uses:

• A testbed for CGI-scripts and document-trees outside the primary server. When developing new scripts and services, you don't want to mess up your current Web-site. CGIservlet is an easy way to start a temporary (private) server. CGIservlet allows to test separate HTTP server components, e.g., user authentication, in isolation.

• A special purpose temporary server (WWW everywhere/anytime). We run identification and other experiments over the inter-/intra-net using CGI-scripts. This means a lot of development and changes and only little actual run-time. The people doing this do not want "scripting" access to our departmental server with all its restrictions and security. So we need a small, lightweigth, easy-to-configure server that can be run by each investigator on her own account (and risk).

• Interactive WWW presentations. Not everyone is content with the features of "standard" office presentation software. HTML and its associated browsers are an alternative (especially under Linux). However, you need a server to realize the full interactive nature of the WWW. CGIservlet with the necessary scripts can be run from a floppie (a Web server in 100 kB). The CGIservlet can actually run a (small) web site from RAM, without disk access (if you DONOT use the 2>pid.log redirection on startup). With the "localhost" or "127.0.0.1" id in your browser you can use it standalone.

When the servlet is started with the -r option, only requests from "localhost" or "127.0.0.1" are accepted (default) or from addresses indicated after the -r switch.

Running demo's and more information can be found at http://www.fon.hum.uva.nl/rob/OSS/OSS.html

Inner workings

Whenever an HTTP request is received, the specified CGI script is started inside a child process as if it was inside a real server (e.g., Apache). The evironment variables are set more or less as in Apache. Note that CGIservlet only uses a SINGLE script for ALL requests. No attemps for security are made, it is the script's responsibility to check access rights and the validity of the request.
When no scripts are given, CGIservlet runs as a bare bone WWW server configurable to execute scripts (the default setting is as a STATIC server).

Use:    CGIservlet.pl -<switch> <argument> 2>pid.log &     (sh)
        CGIservlet.pl -<switch> <argument> >&pid.log &     (csh)
        

The servlet prints out pid and port number on STDERR. It is adviced to store these in a separate file (this will become the error log).
NOTE: When running CGIservlet from a Memmory Image (i.e. RAM), do NOT redirect the error output to a file, but use something like MAILTO!

Stop:   sh pid.log                      (kills the server process)

The first line in the file that receives STDERR output is a command to stop CGIservlet.

examples:

CGIservlet.pl -p 2345 -d /cgi-bin/CGIscriptor.pl -t /WWW 2>pid.log &
CGIservlet.pl -p 8080 -b 'require "CGIscriptor.pl";' -t $PWD -e 'Handle_Request();' 2>pid.log &

The following example settings implement a static WWW server using 'cat' (and prohibiting Queries):

-p 8080

-t `pwd`

-b ''

-e 'exit if $ENV{QUERY_STRING};$ENV{PATH_INFO}=~/\.([\w]+)$/; "Content-type: ".$mimeType{uc($1)}."\n\n";'

-d 'cat -u -s'

-w '/index.html'

-c 32

-l 512

Another setting will use a package 'CGIscriptor.pl' with a function 'HandleRequest()' to implement an interactive WWW server with inline Perl scripting:

-p 8080

-t `pwd`

-b 'require "CGIscriptor.pl";'

-e 'HandleRequest();'

-d ''

-w '/index.html'

-c 32

-l 32767

Look in the source code or in the CGIservletSETUP.pl file for the current default settings.

Command-line switches

There are many switches to tailor the workings of CGIservlet.pl. Some are fairly esoteric and you should only look for them if you need something special urgently. When building a Web site, the specific options you need will "suggest" themselves (e.g., port number, script, or server-root directory). Most default settings should work fine.

You can add your own configuration in a file called 'CGIservletSETUP.pl'. This file will be executed ("eval"-ed) after the default setup, but before the command line options take effect. CGIservlet looks for the SETUP file in the startup directory and in the CGIscriptor subdirectory.
(Note that the $beginarg variable is evaluated AFTER the setup file).

In any case, it is best to change the default settings instead of using the option switches. All defaults are put in a single block.

switches and arguments

Realy important

• -p[ort] port number
  For example -p 2345
  Obviously the port CGIservlet listenes to. Default: -p 8080
• -a[lias] Alias1 RealURL1 ...
  For example -a '/Stimulus.aifc' '/catAIFC.xmr'
  Replaces the given Alias URL path by its real URL path. Accepts full regular expressions too (identified by NON-URL characters).
  That is, on each request it performs (in order):
  

  if($AliasTranslation{$Path})
  { 
      $Path = $AliasTranslation{$Path};
  }
  elsif(@RegAliasTranslation)
  {  
      my $i;
      for($i=0; $i<scalar(@RegAliasTranslation); ++$i)
      { 
          my $Alias   = $RegAliasTranslation[$i];
          my $RealURL = $RegURLTranslation[$i];
          last if ($Path =~ s#$Alias#$RealURL#g);
      };
  };
           

  The effects can be quite drastic, so be carefull. Note also, that entering many Regular Expression aliases could slow down your servlet. Checking stops after the first match.
  Full regular expression alias translations are done in the order given! They are recognized as Aliases containing regexp's (i.e., non-URL) operator characters like '^' and '$'.
  Note: The command line is NOT a good place for entering Aliases, change the code below or add aliases to CGIservletSETUP.pl.

• --help
  Prints the manual

Script related

• -b[egin] perl commands
  For example -b 'require "CGIscriptor.pl";' or 'require "/WWW/cgi-bin/XMLelement.pl";'
  Perl commands evaluated at startup
• -d[o] perl script file
  For example -d '/WWW/cgi-bin/CGIscriptor.pl'
  The actual CGI-script started as a perl {do "scriptfile"} command. The PATH_INFO and the QUERY are pushed on @ARGV.
• -x shell command
• -qx shell command
• -exec shell command
  OS shell script or command, e.g., -x 'CGIscriptor.pl' or -x '/WWW/cgi-bin/my-script'
  The actual CGI-script started as `my-script \'$Path\' \'$QueryString\'`. -qx and -exec[ute] are aliases of -x. For secutiry reasons, Paths or queries containing '-quotes are rejected.
• -e[val] perl commands
  For example -e 'Handle_Request();'
  The argument is evaluated as perl code. The actual CGI-script can be loaded once with -b 'require module.pm' and you only have to call the central function(s).

WWW-tree related

• -t[extroot] path For example -t "$PWD" or -t "/WWW/documents"
  The root of the server hierachy. Defaults to the working directory at startup time (`pwd`)
• -w[elcome] filepath For example -w "/index.html" (default)
  The default welcome page used when no path is entered. Note that this path can point to anything (or nothing real at all).

Security related
The following arguments supply some rudimentary security. It is the responsibility of the script to ensure that the requests are indeed "legal".

• -c[hildren] maximum child processes
  For example -c 32
  The maximum number of subprocesses started. If there are more requests, the oldest requests are "killed". This should take care of "zombie" processes and server overloading. Note that new requests will be serviced irrespective of the success of killing it's older siblings.
• -xtime maximum running time of a child
  For example -xtime 36000
  The maximum time a child may run in seconds. After a new request has been servised, all children that have run for longer than this time will be killed. This stops runaway processes, often connected to web-crawlers.
• -l[ength] maximum length of request in bytes
  For example -l 32768
  This prevents overloading the server with enormous queries. Reading of requests simply stops when this limit is reached. This DOES affect POST requests. If the combined length of the COMPLETE HTTP request, including headers, exceeds this limit, the whole request is dropped.
• -r[estrict] [Remote-address [Remote-host]]
  For example -r 127.0.0.1 (default of -r)
  A space separated list of client IP addresses and/or domain names that should be serviced. Default, i.e., '-r' without any addresses or domain names, is the localhost IP address '127.0.0.1'.
  When using CGIservlet for local purposes only (e.g., development or a presentation), it would be unsafe to allow others to access the servlet. If -r is used (or the corresponding @RemoteAddr or @RemoteHost lists are filled in the code below), all requests from clients whose Remote-address or Remote-host do not match the indicated addresses will be rejected. Partial addresses and domain names are allowed. Matching is done according to Remote-addr =~ /^\Q$pattern\E/ (front to back) and Remote-host =~ /\Q$pattern\E$/ (back to front)
• -m[emory]
  No arguments.
  Reads complete Web site into memory and runs from this image. Set $UseRAMimage = 1; to activate memory-only running.
  Note that running osshellscripts from this image makes any "security" related claims very shaky.
  

Speedup

• -n[oname]
  No arguments.
  Retrieving the domain name of the Client (i.e., Remote-host) is a very slow process and normally useless. To skip it, enter this option. Note that you cannot use '-r Remote-host' anymore after you enter -n, only IP addresses will work.

Configuration with the CGIservletSETUP.pl file

You can add your own configuration in a file called 'CGIservletSETUP.pl'. This file will be executed ("eval"-ed) after the default setup, but before the command line options take effect. CGIservlet looks for the SETUP file in the startup directory and in the CGIservlet and CGIscriptor subdirectories. (Note that the $beginarg variable is evaluated even later).

Changing POST to GET requests

CGIservlet normally only handles requests with the GET method. Processing the input from POST requests is left to the reading application. POST requests add some extra complexity to processing requests. Sometimes, the reading application doesn't handle POST requests. CGIservlet already has to manage the HTTP request. Therefore, it can easily handle the POST request. If the variable $POSTtoGET is set to any non-false value, the content of whole POST request is added to the QUERY_STRING environment variable (preceeded by a '&' if necessary). The content-length is set to 0. If $POSTtoGET equals 'GET', the method will also be changed to 'GET'.

remarks:

All of the arguments of -d, -x, and -e are processed sequentially in this order. This might not be what you want so you should be carefull when using multiple executable arguments. If none of the executable arguments is DEFINED (i.e., they are entered as -d '' -e '' -x ''), each request is treated as a simple text-retrieval. THIS CAN BE A SECURITY RISK!

The wiring of an interactive web-server, which also calls shell scripts with the extension '.cgi', is in place. You can "activate" it by changing the "$ExecuteOSshell = 0;" line to "$ExecuteOSshell = 1;".
If you have trouble doing this, it might be a good idea to reconsider using a dynamic web server. Executing shell scripts inside a web server is a rather dangerous practise.

CGIservlet can run its "standard" web server from memory. At startup, all files are read into a hash table. Upon request, the contents of the file are placed in the environment variable: CGI_FILE_CONTENTS.
No further disk access is necessary. This means that:

1. CGIservlet can run a WWW site from a removable disk, e.g., a floppy
2. The web servlet can run without any read or write privilege.
3. The integrity of the Web-site contents can be secured at the level you want

license

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Author: Rob van Son 
        email:
        R.J.J.H.vanSon@uva.nl 
        Institute of Phonetic Sciences/ACLC
        University of Amsterdam

        copying freely from the mhttpd server by Jerry LeVan (levan@eagle.eku.edu)
Date:   15 Jan 2002
Ver:    1.3
Env:    Perl 5.002 and later

Note:   CGIservlet.pl was directly inspired by Jerry LeVan's 
        (levan@eagle.eku.edu) simple mhttpd server which again was 
        inspired by work of others. CGIservlet is used as a bare bones 
        socket server for a single CGI script at a time.