ch2.htm

CGI programming is the hottest stuff to look out for in this book

<P>
<TT><FONT FACE="Courier">REMOTE_ADDR</FONT></TT> is the IP address
of the remote computer that made the request.
<H4><TT><FONT FACE="Courier">REMOTE_HOST</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">REMOTE_HOST</FONT></TT> is the name of
the remote computer that made the request.
<H4><TT><FONT FACE="Courier">REMOTE_IDENT</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">REMOTE_IDENT</FONT></TT> gives the username
as defined in the RFC 931.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
RFC 931 is an Internet official document that describes a means to determine the identity of a user on a TCP connection. You can find the document at</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://sunsite.auc.dk/RFC/rfc/rfc931.html">http://sunsite.auc.dk/RFC/rfc/rfc931.html</A></FONT></TT>
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H4><TT><FONT FACE="Courier">REMOTE_USER</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">REMOTE_USER</FONT></TT> gives the authenticated
username of the client that made the request, if applicable.
<H4><TT><FONT FACE="Courier">REQUEST_METHOD</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">REQUEST_METHOD</FONT></TT> is the method
with which the request of the CGI application was made, either
one of the following: <TT><FONT FACE="Courier">GET</FONT></TT>,
<TT><FONT FACE="Courier">HEAD</FONT></TT>, and <TT><FONT FACE="Courier">POST</FONT></TT>.
<H4><TT><FONT FACE="Courier">SCRIPT_NAME</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">SCRIPT_NAME</FONT></TT> is the virtual
path to the CGI program being executed: for example, <TT><FONT FACE="Courier">/cgi-bin/finger.cgi</FONT></TT>.
<H4><TT><FONT FACE="Courier">SERVER_NAME</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">SERVER_NAME</FONT></TT> is the domain
name or the IP address of the computer running the Web server
software. Example: <TT><FONT FACE="Courier">www.esoterica.com</FONT></TT>.
<H4><TT><FONT FACE="Courier">SERVER_PORT</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">SERVER_PORT</FONT></TT> gives the port
number on which the Web server is waiting for requests, which
is usually <TT><FONT FACE="Courier">80</FONT></TT>, the default
HTTP port number.
<H4><TT><FONT FACE="Courier">SERVER_PROTOCOL</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">SERVER_PROTOCOL</FONT></TT> gives the
name and version of the protocol the Web server is using. Example:
<TT><FONT FACE="Courier">HTTP/1.0</FONT></TT>.
<H4><TT><FONT FACE="Courier">SERVER_SOFTWARE</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">SERVER_SOFTWARE</FONT></TT> gives the
name of the Web server that executes the CGI program. The format
in which it is presented consists of the name followed by a slash
and the version number. Example: <TT><FONT FACE="Courier">ncSA/1.5b5</FONT></TT>.
<P>
Additionally, the client may send HTTP header values to the CGI
program as HTTP variables. These variables have the same name
as the HTTP headers, with hyphen (<TT><FONT FACE="Courier">-</FONT></TT>)
characters replaced by underscore (<TT><FONT FACE="Courier">_</FONT></TT>)
characters, and small letters converted to capital letters.
<H4><TT><FONT FACE="Courier">HTTP_AccEPT</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">HTTP_AccEPT</FONT></TT> is the contents
of the <TT><FONT FACE="Courier">Accept:</FONT></TT> header line
sent by the client, corresponding to the MIME types the client
can handle. Format: <TT><FONT FACE="Courier">type/subtype,type/subtype,...</FONT></TT>.
Example: <TT><FONT FACE="Courier">*/*, image/gif,image/jpeg</FONT></TT>.
<H4><TT><FONT FACE="Courier">HTTP_REFERER</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">HTTP_REFERER</FONT></TT> gives the contents
of the <TT><FONT FACE="Courier">Referer:</FONT></TT> header line,
which contains the URL of the form from which the CGI request
was originated. For example, the value of this variable could
be <TT><FONT FACE="Courier">http://www.your_host.com/comments.form</FONT></TT>
if this form uses a CGI program to send results via mail (a form-by-mail
gateway).
<H4><TT><FONT FACE="Courier">HTTP_USER_AGENT</FONT></TT></H4>
<P>
<TT><FONT FACE="Courier">HTTP_USER_AGENT</FONT></TT> gives the
name of the client program (the browser) that made the request.
<TT><FONT FACE="Courier">Mozilla/1.2N(Windows;I;32bit)</FONT></TT>,
for example.
<P>
You can find an example of the variables available to a CGI program
by looking at the output of a CGI test program, called test-cgi,
presented in Figure 2.2.
<P>
<A HREF="f2-2.gif" ><B>Figure 2.2:</B> <I>The output of the CGI test application.</I></A>
<P>
The HTML that generated this output appears in Figure 2.3.
<P>
<A HREF="f2-3.gif" ><B>Figure 2.3: </B><I>The HTML page that generated the results of Figure 2.2</I></A>
<H3><A NAME="CommandLine">Command Line</A></H3>
<P>
The CGI command line is used only with <TT><FONT FACE="Courier">ISINDEX</FONT></TT>
queries. An <TT><FONT FACE="Courier">ISINDEX</FONT></TT> query
is a special query obtained with the <TT><FONT FACE="Courier">&lt;ISINDEX&gt;</FONT></TT>
tag and the <TT><FONT FACE="Courier">&lt;BASE HREF=&quot;..&quot;&gt;</FONT></TT>
tag (referencing the script). The data entered by the user is
sent to the CGI program via the command line, unless it contains
the equal sign (<TT><FONT FACE="Courier">=</FONT></TT>), in which
case the <TT><FONT FACE="Courier">QUERY_STRING</FONT></TT> is
used instead. More than one parameter can be passed to the CGI
program command line, because the Web server replaces any plus
signs (<TT><FONT FACE="Courier">+</FONT></TT>) received from the
client with spaces.
<H3><A NAME="StandardInput">Standard Input</A></H3>
<P>
The standard input (<TT><FONT FACE="Courier">stdin</FONT></TT>)
is used for the Web server to pass information to the CGI program
when the <TT><FONT FACE="Courier">POST</FONT></TT> method is used.
The Web server is also responsible for sending the <TT><FONT FACE="Courier">CONTENT_TYPE</FONT></TT>
and <TT><FONT FACE="Courier">CONTENT_LENGTH</FONT></TT> values,
so that the CGI program knows what it is receiving and how long
it is. The <TT><FONT FACE="Courier">CONTENT_LENGTH</FONT></TT>
value is a bytes count of the URL encoded data (spaces have been
replaced by plus signs, tilde characters by <TT><FONT FACE="Courier">%7E</FONT></TT>,
and so on).
<H3><A NAME="StandardOutput">Standard Output</A></H3>
<P>
The CGI program sends results to the standard output. It may be
sent directly to the user's browser or can be interpreted by the
Web server in order for an action to be executed (redirection
to another existing URL, for example). The CGI programs may overpass
the server and talk to the browser directly. In order to distinguish
these programs from regular ones, their names must start with
<TT><FONT FACE="Courier">nph-</FONT></TT> (this means No Parse
Header, which results in the server ignoring any information,
even HTTP or MIME headers). It is up to the CGI program to return
valid HTTP headers to the browser.
<P>
But if an <TT><FONT FACE="Courier">nph-</FONT></TT> program is
not used, the server looks for any of three special headers that
the CGI program may return:
<UL>
<LI><TT><FONT FACE="Courier">Content-type:</FONT></TT> This is
the MIME type header. Usually, as CGI programs output HTML text
for a browser to display, it is common to use <TT><FONT FACE="Courier">Content-type:
text/html\n\n</FONT></TT>. Notice the two newline characters by
the end of the line. It is mandatory to put a blank line after
an HTTP header.
<LI><TT><FONT FACE="Courier">Location:</FONT></TT> Tells the server
you are referencing another document. The server may either issue
a Redirect to the client or send the contents of the referenced
document, depending on whether it is a complete URL or a virtual
(relative) path.
<LI><TT><FONT FACE="Courier">Status:</FONT></TT> This is the status
line the server should send to the client. Format: <TT><FONT FACE="Courier">nnn
xxxxx</FONT></TT>, where <TT><FONT FACE="Courier">nnn</FONT></TT>
is a three-digit code, and <TT><FONT FACE="Courier">xxxxx</FONT></TT>
is the corresponding description text.
</UL>
<H2><A NAME="Examples"><FONT SIZE=5 COLOR=#FF0000>Examples</FONT></A>
</H2>
<P>
For a quick example of a CGI program, let's take a look at a finger
gateway that returns information about an e-mail address, using
the finger client available in most UNIX platforms. The query
is made with the <TT><FONT FACE="Courier">ISINDEX</FONT></TT>
tag. The finger CGI program presented here is included with every
Apache server distribution. Be careful because it is not a secure
finger gateway. A malicious user could invoke shell commands through
it. This leads us to an important part of CGI design: security.
See the following section for some pointers concerning this important
issue.
<P>
Notice the e-mail address concatenated with the URL of the CGI
finger gateway. It was sent to the finger client via the command
line, as you can see in Figure 2.4. The HTML page in which you
enter the e-mail address is presented in Figure 2.5. You can see
an example of the finger information for <TT><FONT FACE="Courier">[e-mail]</FONT></TT>
in Figure 2.6.
<P>
<A HREF="f2-4.gif" ><B>Figure 2.4:</B><I> The finger CGI program (Note: the HTML is poor)</I></A>
<P>
<A HREF="f2-5.gif" ><B>Figure 2.5:</B> <I>The finger HTML page.</I></A>
<P>
<A HREF="f2-6.gif" ><B>Figure 2.6:</B> <I>The results page</I></A><I>.</I>
<H2><A NAME="MoreInformation"><FONT SIZE=5 COLOR=#FF0000>More
Information</FONT></A></H2>
<P>
Here you will find pointers to interesting and important information
about the CGI specification.
<P>
The essential CGI site is located at the National Centre for Supercomputing
Applications. This is a must for everyone interested in mastering
CGI:
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">http://hoohoo.ncsa.uiuc.edu/cgi/</A></FONT></TT>
</BLOCKQUOTE>
<P>
M. Hedlund maintains a good FAQ on CGI programming:
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://www.best.com/~hedlund/cgi-faq/">http://www.best.com/~hedlund/cgi-faq/</A></FONT></TT>
</BLOCKQUOTE>
<P>
Alan Richmond maintains a good site about the CGI specification:
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://www.charm.net/~web/Tutorial/CGI/Perl.html">http://www.charm.net/~web/Tutorial/CGI/Perl.html</A></FONT></TT>
</BLOCKQUOTE>
<P>
Lincoln Stein maintains an excellent FAQ about World Wide Web
security, in which we find a chapter dedicated to CGI security:
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html">http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html</A></FONT></TT>
</BLOCKQUOTE>
<P>
You can also find lots of interesting pointers in the CGI section
of Yahoo!, at the following location:
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://www.yahoo.com/Computers/World_Wide_Web/CGI_Common_Gateway_Interface/">http://www.yahoo.com/Computers/World_Wide_Web/CGI_Common_Gateway_Interface/</A></FONT></TT>
</BLOCKQUOTE>
<P>
See Figure 2.7 for the Yahoo! list of CGI references.
<P>
<A HREF="f2-7.gif" ><B>Figure 2.7: </B><I>The Yahoo! CGI section.</I></A>
<P>
The good stuff can be found at <TT><FONT FACE="Courier"><A HREF="http://www.worldwidemart.com/scripts/">http://www.worldwidemart.com/scripts/</A></FONT></TT>.
This is a site where you can find lots of good and useful CGI
programs.
<H2><A NAME="Summary"><FONT SIZE=5 COLOR=#FF0000>Summary</FONT></A>
</H2>
<P>
This chapter has described in detail the Common Gateway Interface
specification. The CGI specification is an accepted standard for
interaction between Web servers and other programs, developed
to perform lots of different tasks. You can use the information
in this chapter as a reference while you develop your own CGI
programs in your preferred computer language.
<P>
<HR WIDTH="100%"></P>

<CENTER><P><A HREF="ch1.htm"><IMG SRC="pc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="#CONTENTS"><IMG SRC="cc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="index.htm"><IMG SRC="hb.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="ch3.htm"><IMG 
SRC="nc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A></P></CENTER>

<P>
<HR WIDTH="100%"></P>

</BODY>
</HTML>