OmniHTTPd has the ability to run both Standard CGI and Windows CGI scripts. Scripts must be placed in their respective directories so that the server can determine how to correctly execute the script. Use the administration tool to define these directories. Do not alias to these directories as an alias definition will override a CGI directory definition.
In addition, scripts must be placed in the base of the CGI directory. For example, if you have /cgi-bin defined as c:\httpd\cgi-bin, scripts must be placed in c:\httpd\cgi-bin. You cannot put them in a child directory like c:\httpd\cgi-bin\child\dir. This, however, does not prevent scripts from storing their own information in child directories.
This restriction allows OmniHTTPd to efficiently parse path information without the access overhead of attempting each possible path.
If you get errors when launching standard CGI scripts or not all environment variable are present, you are running out of DOS environment space. To fix this, add the following lines to your SYSTEM.INI:
[NonWindowsApp] CommandEnvSize=8192
How do I get information from the server?
Each time a client requests the URL corresponding to your CGI program, the server will execute it in real-time. The output of your program will go more or less directly to the client.
A common misconception about CGI is that you can send command-line options and arguments to your program, such as
command% myprog -qa blorf
CGI uses the command line for other purposes and thus this is not directly possible. Instead, CGI uses environment variables to send your program its parameters. The two major environment variables you will use for this purpose are:
QUERY_STRING is defined as anything which follows the first ? in the URL. This information could be added either by an ISINDEX document, or by an HTML form (with the GET action). It could also be manually embedded in an HTML anchor which references your gateway. This string will usually be an information query, i.e. what the user wants to search for in the archie databases, or perhaps the encoded results of your feedback GET form.
This string is encoded in the standard URL format of changing spaces to +, and encoding special characters with %xx hexadecimal encoding. You will need to decode it in order to use it.
If your gateway is not decoding results from a FORM, you will also get the query string decoded for you onto the command line. This means that each word of the query string will be in a different section of ARGV. For example, the query string "forms rule" would be given to your program with argv[1]="forms" and argv[2]="rule". If you choose to use this, you do not need to do any processing on the data before using it.
CGI allows for extra information to be embedded in the URL for your gateway which can be used to transmit extra context-specific information to the scripts. This information is usually made available as "extra" information after the path of your gateway in the URL. This information is not encoded by the server in any way.
The most useful example of PATH_INFO is transmitting file locations to the CGI program. To illustrate this, let's say I have a CGI program on my server called /cgi-bin/foobar that can process files residing in the DocumentRoot of the server. I need to be able to tell foobar which file to process. By including extra path information to the end of the URL, foobar will know the location of the document relative to the DocumentRoot via the PATH_INFO environment variable, or the actual path to the document via the PATH_TRANSLATED environment variable which the server generates for you.
How do I send my document back to the client?
I have found that the most common error in beginners' CGI programs is not properly formatting the output so the server can understand it.
CGI programs can return a myriad of document types. They can send back an image to the client, and HTML document, a plaintext document, or perhaps even an audio clip. They can also return references to other documents. The client must know what kind of document you're sending it so it can present it accordingly. In order for the client to know this, your CGI program must tell the server what type of document it is returning.
In order to tell the server what kind of document you are sending back, whether it be a full document or a reference to one, CGI requires you to place a short header on your output. This header is ASCII text, consisting of lines separated by either linefeeds or carriage returns (or both) followed by a single blank line. The output body then follows in whatever native format.
In this case, you must tell the server what kind of document you will be outputting via a MIME type. Common MIME types are things such as text/html for HTML, and text/plain for straight ASCII text.
For example, to send back HTML to the client, your output should read:
Content-type: text/html
<HTML><HEAD>
<TITLE>output of HTML from CGI script</TITLE>
</HEAD><BODY>
<H1>Sample output</H1>
What do you think of <STRONG>this?</STRONG>
</BODY></HTML>
Instead of outputting the document, you can just tell the browser where to get the new one, or have the server automatically output the new one for you.
For example, say you want to reference a file on your Gopher server. In this case, you should know the full URL of what you want to reference and output something like:
Content-type: text/html
Location: gopher://httprules.foobar.org/0
<HTML><HEAD>
<TITLE>Sorry...it moved</TITLE>
</HEAD><BODY>
<H1>Go to gopher instead</H1>
Now available at
<A HREF="gopher://httprules.foobar.org/0">a new location</A>
on our gopher server.
</BODY></HTML>
However, today's browsers are smart enough to automatically throw you to the new document, without ever seeing the above since. If you get lazy and don't want to output the above HTML, NCSA HTTPd will output a default one for you to support older browsers.
If you want to reference another file (not protected by access authentication) on your own server, you don't have to do nearly as much work. Just output a partial (virtual) URL, such as the following:
Location: /dir1/dir2/myfile.html
The server will act as if the client had not requested your script, but instead requested http://yourserver/dir1/dir2/myfile.html. It will take care of most everything, such as looking up the file type and sending the appropriate headers. Just be sure that you output the second blank line.
If you do want to reference a document that is protected by access authentication, you will need to have a full URL in the Location:, since the client and the server need to re-transact to establish that you access to the referenced document.
Advanced usage: If you would like to output headers such as Expires or Content-encoding, you can if your server is compatible with CGI/1.1. Just output them along with Location or Content-type and they will be sent back to the client.
Decoding FORMs with CGI
If you are unfamiliar with forms or how to write them, we suggest you look at this guide to fill-out forms. They're just plain HTML, and pretty easy to do.
Where do I get the form data from?
As you now know, there are two methods which can be used to access your forms. These methods are GET and POST. Depending on which method you used, you will receive the encoded results of the form in a different way.
If your form has METHOD="GET" in its FORM tag, your CGI program will receive the encoded form input in the environment variable QUERY_STRING.
If your form has METHOD="POST" in its FORM tag, your CGI program will receive the encoded form input on stdin. The server will NOT send you an EOF on the end of the data, instead you should use the environment variable CONTENT_LENGTH to determine how much data you should read from stdin. \\
How do I decode the form data?
When you write a form, each of your input items has a NAME tag. When the user places data in these items in the form, that information is encoded into the form data. The value each of the input items is given by the user is called the value.
Form data is a stream of name=value pairs separated by the & character. Each name=value pair is URL encoded, i.e. spaces are changed into plusses and some characters are encoded into hexadecimal.
Because others have been presented with this problem as well, there are already a number of programs which will do this decoding for you. The following are links into the CGI archive, clicking on them will retrieve the software package being referred to.
The basic procedure is to split the data by the ampersands. Then, for each name=value pair you get for this, you should URL decode the name, and then the value, and then do what you like with them.
Writing Secure CGI Scripts
Any time that a program is interacting with a networked client, there is the possibility of that client attacking the program to gain unauthorized access. Even the most innocent looking script can be very dangerous to the integrity of your system.
With that in mind, we would like to present a few guidelines to making sure your program does not come under attack.
Languages like PERL and the Bourne shell provide an eval command which allow you to construct a string and have the interpreter execute that string. This can be very dangerous. Observe the following statement in the Bourne shell:
eval `echo $QUERY_STRING | awk 'BEGIN{RS="&"} {printf "QS_%s\n",$1}' `
This clever little snippet takes the query string, and convents it into a set of variable set commands. Unfortunately, this script can be attacked by sending it a query string which starts with a ;. See what I mean about innocent-looking scripts being dangerous?
A well-behaved client will escape any characters which have special meaning to the Bourne shell in a query string and thus avoid problems with your script misinterpreting the characters. A mischevious client may use special characters to confuse your script and gain unauthorized access.
If you use any data from the client to construct a command line for a call to popen() or system(), be sure to place backslashes before any characters that have special meaning to the Bourne shell before calling the function. This can be achieved easily with a short C function.
If your server is unfortunate enough to support server-side includes, turn them off for your script directories!!!. The server-side includes can be abused by clients which prey on scripts which directly output things they have been sent.
For a more comprehensive summary of security and the World-Wide Web, see the WWW Security FAQ.
Copyright © 1996 Omnicron Technologies Corporation