Martin's Server Suite
 

Snug HTTP server - CGI


Introduction

Let's start of with a warning, this part of the instruction manual will get technical.The server supports CGI (Common Gateway Interface), which enables the use of scripting. Scripting can be used to produce dynamic content and extend the functionality of the server without changing the server itself. There are however some limitations in the server's current CGI implementaion. Only NPH scripts (Non-Parsed Header) is supported. The use of NPH scripts requires that all scripts begin with the characters nph- in its filename. This is the convention used by servers to recognize an NPH script. If you rename the script, the server will not know to treat it as an NPH script and instead will treat it as a normal file (probably sending the content of the file, thus exposing the script to the client). The server looks at the requested file's filename to determine the MIME-type (Multipurpose Internet Mail Extensions). If there is an interpreter added in the server's configuration (see AddType and AddInterpreter in the Configuration section) for that MIME-type, the server will treat the file as a script. Only the HTTP method GET is supported in the server's current CGI implentation. POST request requires (for some clients that don't follow standards) persistent connections, which is not yet implemented. The server will never send the content of a script file if the requested file is recognized as a script. The server will only return the result returned by the interpreter.


Environment variables

The server sets some standard environment variables as well as the fields in the request header as per standard. Here is a list of the environment variables expected to be set by the server. Not all variables will be set for all requests. HTTP_REFERER will only be set for clients with referrer logging enabled. QUERY_STRING will only be set when there is a query string to set and so on. If the amount of supplied data is larger than the maximum number of characters that the server can place in the QUERY_STRING environment variable, the QUERY_STRING variable will not be set. However, CONTENT_LENGTH will be set even if the QUERY_STRING is too long for the server to handle. That fact must be used for the script to determine if the QUERY_STRING was too long for the server to handle.
Below is a sample printout of all environment variables set for the script. The list may differ some between different ports of the server.

QUERY_STRING=data=ggg
SERVER_SOFTWARE=Snug/1.7.2
SERVER_NAME=http://192.168.0.7
GATEWAY_INTERFACE=CGI/1.1
SERVER_PORT=80
REQUEST_METHOD=GET
REMOTE_ADDR=192.168.0.7
DOCUMENT_ROOT=c:
=C=c:
CONTENT_LENGTH=8
SCRIPT_NAME=/cgi-bin/nph-test.cgi
SCRIPT_FILENAME=/cgi-bin/nph-test.cgi
HTTP_USER_AGENT=Opera/9.21 (Windows 98; U; en)
HTTP_HOST=192.168.0.7
HTTP_ACCEPT_LANGUAGE=en
HTTP_ACCEPT_CHARSET=iso-8859-1, utf-8, utf-16, *;q=0.1
HTTP_ACCEPT_ENCODING=deflate, gzip, x-gzip, identity,*;q=0
HTTP_REFERER=http://192.168.0.7/temp/cgi-test.htm
HTTP_PRAGMA=no-cache
HTTP_CACHE_CONTROL=no-cache
HTTP_CONNECTION=Keep-Alive, TE



As per standard, request header lines are converted to environment variabels with HTTP_ added. Strings are also converted to upper-case letters only, blank spaces and other some other characters are replaced with _ (underscore). Accept Language: en will be converted to HTTP_ACCEPT_LANGUAGE=en, but also the non-standard Accept Language:en will be converted to HTTP_ACCEPT_LANGUAGE=en. The difference beeing the missing blank space in the second example.

AddCustomEnvironment can be used to replace a default environment variable. AddCustomEnvironment=SERVER_SOFTWARE;Snug can for example be used to replace the default SERVER_SOFTWARE=Snug/1.7.2 (version may vary).

The environment size

This section only applies to some certain operating systems such as Microsoft Windows 95 and Windows for Workgroups 3.11. The server sends information to scripts by using environment variables. It is sometimes necessary to increase the memory size allocated for environment variables.Increase the amount of environment space by adding the following line to your CONFIG.SYS file: "SHELL=X:\PATH\COMMAND.COM /P /E:NNNN" where "X:\PATH" is the directory where the COMMAND.COM command interpreter is located, and NNNN is the new size of the DOS environment area in bytes. Suggested is 512 or 1024; don't make this too large because increasing it reduces available conventional memory.

Start Snug HTTP server from a batch-file (.bat). Right-click the batch-file if you are running Windows 9x and later, and then click Properties. On the Memory tab, type or click the number of bytes the program requires (recommended: 4096) in the Initial Environment box, and then click OK. NOTE: The maximum amount of memory you can allocate for a MS-DOS program is 4096 bytes.


CGI scripts

CGI requests using method GET are limited in the way that not all characters can be used in the supplied data. This is because the client sends data using the request string in the HTTP header. Some characters are treated as forbidden by the server (as set by the configuration). Strings and single characters marked as forbidden with AddForbidden in the configuration can not be used.
The length of the QUERY_STRING is limited to a low number of characters. CGI programs can be password protected with AddForbidden (e.g. AddForbidden=/cgi-bin/;user). CGI request using GET will be visible in the log if enabled. CGI scripts can be used as index pages by using AddIndex.
It is not necessary for a requested script to really exist as a file on the server. It is up to the interpreter to respond to the request. The environment variable SCRIPT_NAME together with DOCUMENT_ROOT can be used to determine the script name. Also, the first real parameter (except for the interpreter itself as per standard) sent to the interpreter is the full path to the script name including the script name.


Enable scripting

The server need to know two things for scripting to be enabled. First it need to know what interpreters to use and what files to be associated with that interpreter. This is done by using the AddInterpreter= in the main configuration file. The interpreter must be set to work in CLI (Command Line Interface) mode. If for example php.exe should be used with php files (files with MIME-type application/x-httpd-php), AddInterpreter=c:\Programs\php\php.exe;application/x-httpd-php can be used. The MIME-type for a php file is application/x-httpd-php. So by using AddType=.php;application/x-httpd-php the server will put all files ending with .php through the interpreter. If no interpreters are added to the configuration, scripting will be disabled. To put all files through the an interpreter named filter.exe, leave out the MIME part of AddInterpreter; AddInterpreter=filter.exe;.


LUA on AROS

Here's an example on how to set up the server to use the LUA scripting language on AROS. Lua as a CGI interpreter is preconfigured. The path to the interpreter is set to be Work:Extras/Development/Lua/Lua. If this is not the case you must change this in the configuration file (usually snug.ini). There is also a simple lua script in the cgi-bin directory. To run this script, start the server and browse to the cgi-bin drawer and open the lua script. This should invoke the interpreter and return the result to your web browser.


PHP 5.2.6 on Windows 98

Snug HTTP server is partially preconfigured for PHP. The server uses the PHP CLI executable (php.exe in version 5.2.6).
A few things is needed in the configuration as follow.

AddType=.php;application/x-httpd-php
(added to the configuration as default)

The exact path to the PHP CLI executable may need some tweaking.
AddInterpreter=C:\PHP\php.exe;application/x-httpd-php
(added to the configuration as default)

The environment variable REDIRECT_STATUS may need to be set for PHP to work.
AddCustomEnvironment=REDIRECT_STATUS;200
(added to the configuration as default)