asg05.htm

apache技术手册

<A NAME="E68E38"></A>

<H3 ALIGN=CENTER>

<CENTER>

<FONT SIZE=5 COLOR="#FF0000"><B>Running a CGI Program</B></FONT></CENTER></H3>

<BR>

<P>I have talked about what a CGI is, and you have seen what a simple CGI looks like. At this point, you might be asking yourself how to run a CGI. If you have read this book in sequence, you will probably recall that execution of programs from the HTTP server can be a source of potential security problems, so CGI execution is usually restricted. By default, CGI programs exist in the /usr/local/etc/httpd/cgi-bin directory, or whatever other directory is defined by your ScriptAlias directive in your srm.conf file. The ScriptAlias directive is commented out from the default configuration. If you have not done so, you may want to remove the comment and restart the server. This will enable CGI execution for CGIs located in the cgi-bin directory.

<BR>

<BLOCKQUOTE>

<BLOCKQUOTE>

<HR ALIGN=CENTER>

<BR>

<NOTE>Never, ever put a command interpreter such as Perl or any shell in your cgi-bin directory. Why? Think about it! That would make the executable available to anyone who wants to send it data. Even though the browser encodes data that is sent to the CGI, perverse minds will think of exploiting this security problem in their favor. In short, this is a huge security risk that is best avoided. Put your shells and command interpreters in a directory where the httpd daemon has no execution permission; /usr/local/bin is a very good place.</NOTE>

<BR>

<HR ALIGN=CENTER>

</BLOCKQUOTE></BLOCKQUOTE>

<P>To test these CGI programs , just put them in your cgi-bin directory. Make sure your scripts are executable by setting the file mode to 755. You can do this easily from a command line by typing:

<BR>

<BR>

<PRE>

<FONT COLOR="#000080">chmod 755 <I>myscript</I></FONT></PRE>

<P>Replace <I>myscript</I> with the name of the file you want to make executable.

<BR>

<P>Also remember that the C version needs to be compiled before it is executed. Here's an easy way to compile it:

<BR>

<BR>

<PRE>

<FONT COLOR="#000080">cc <I>sourcefile</I>.c -o <I>binary</I></FONT></PRE>

<P>Replace <I>sourcefile.c</I> with the name of your C source file and <I>binary</I> with the name of the finished program. After a few seconds you should be left with an executable that you can run. If your system returns cc: command not found, you may want to try changing the command from <I>cc</I> to <I>gcc</I>.

<BR>

<P>If you named your CGIs as I suggested in the program comments in the listings, just move them to your cgi-bin directory and test the following URLs on your favorite browser:

<BR>

<PRE>

<FONT COLOR="#000080">http://localhost/cgi-bin/HelloInSh

http://localhost/cgi-bin/HelloInPerl

http://localhost/cgi-bin/HelloInC</FONT></PRE>

<P>You should get a result similar to the screen shown in Figure 5.1.

<BR>

<P><B> <A HREF="javascript:if(confirm('http://docs.rinet.ru:8080/Apachu/05asg01.gif  \n\nThis file was not retrieved by Teleport Pro, because it was redirected to an invalid location.  You should report this problem to the site\'s webmaster.  \n\nDo you want to open it from the server?'))window.location='http://docs.rinet.ru:8080/Apachu/05asg01.gif'" tppabs="http://docs.rinet.ru:8080/Apachu/05asg01.gif">Figure 5.1. The output for the any of the Hello </B><B>World! programs.</A></B>

<BR>

<P>If you are having problems with the programs, see if you can get them to run on a terminal. If it will output the header and some HTML, and it doesn't give you an error, the problem may be with UNIX permissions. Recheck that your program is executable. If the problem is with a script, check that the location of the interpreter program is where I list it (the first line of the script). If it is not, change the first line to the absolute path of your command interpreter and try again (if the program is found anywhere in any of the directories specified by your path, it will be listed by using the whereis command. For more information on how to use the whereis program, please refer to your UNIX documentation). Note that the !# are required symbols that tell the shell that the script should be run by the specified command processor .

<BR>

<BR>

<A NAME="E68E39"></A>

<H3 ALIGN=CENTER>

<CENTER>

<FONT SIZE=5 COLOR="#FF0000"><B>Standard Environment Variables</B></FONT></CENTER></H3>

<BR>

<P>CGI programs run in an environment that is different from most programs. For one thing, most of the time they do not get input from stdin, the standard input stream. Because of this, input needs to be handled differently than in most programs. As I mentioned before, CGI passes values as <I>environment variables</I><I> </I>. Environment variables are used extensively under UNIX as a way of communicating things like the location of your home directory and your mailbox, the capabilities of your terminal, and so on. When you execute a program, UNIX makes all of these settings available in case a program is interested in them.

<BR>

<P>In a similar manner to the UNIX shell, the HTTP server uses the environment mechanism to pass values to a CGI program. The HTTP server sets a number of environment variables prior to executing the CGI program. These variables provide information about the user, his software, and the server.

<BR>

<P>These environment variables can be accessed by name, and if your CGI calls other programs, these variables are inherited by the environment of the programs you call. The standard CGI 1.1 specification defines the variables discussed in the following sections.

<BR>

<BR>

<A NAME="E69E34"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>AUTH_TYPE</B></FONT></CENTER></H4>

<BR>

<P>The AUTH_TYPE variable is set to the type of authentication used to validate a request.

<BR>

<BR>

<A NAME="E69E35"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>CONTENT_LENGTH</B></FONT></CENTER></H4>

<BR>

<P>The CONTENT_LENGTH environment variable is set to the size of the data that was submitted with the request. The size of the data is specified in bytes. HTTP PUT and POST requests use this value to read that amount of bytes from stdin, the standard input stream. You shouldn't attempt to read any more data bytes than specified by this variable.

<BR>

<BR>

<A NAME="E69E36"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>CONTENT_TYPE</B></FONT></CENTER></H4>

<BR>

<P>The CONTENT_TYPE variable is set to the Multipurpose Internet Mail Extensions (MIME) type or format submitted with the request. The format is expressed with a <I>type</I>/<I>subtype</I> syntax. If the data was submitted using the HTTP POST method, the value of this variable is set to application/x-www-form-urlencoded. The amount of data submitted is specified by the CONTENT_LENGTH variable.

<BR>

<BR>

<A NAME="E69E37"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>GATEWAY_INTERFACE</B></FONT></CENTER></H4>

<BR>

<P>The GATEWAY_INTERFACE variable is set to the version of CGI that the server implements. The syntax of the version follows a pattern <I>CGI/version</I>: CGI/1.1. As new variables are added to the CGI standard, the version number is increased. Your program should be aware of this version number to ensure that the variables you use are available in the environment setup by the server you are using. This variable is set for all requests.

<BR>

<BR>

<A NAME="E69E38"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>PATH_INFO</B></FONT></CENTER></H4>

<BR>

<P>The PATH_INFO variable is set to the Uniform Resource Identifier (URI). For practical purposes, a URI is just an URL that follows the string identifying the CGI script, like the following example:

<BR>

<P>http://www.company.com/cgi-bin/mycgi/a/b/c will be set to /a/b/c.

<BR>

<P>Your program can use this information to do whatever it wants, perhaps to pass extra settings (switches) for the program to behave differently depending the situation, such as specifying extra arguments used for CGI configuration. It's up to your CGI program to use the values provided by this variable.

<BR>

<BR>

<A NAME="E69E39"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>PATH_TRANSLATED</B></FONT></CENTER></H4>

<BR>

<P>The PATH_TRANSLATED variable is set to the absolute path to the resource represented by the URL. In the case of http://www.company.com/index.html, PATH_TRANSLATED may hold a value such as /usr/local/etc/httpd/htdocs/index.html. This allows your CGI program to be able to read this file and do something with it if necessary.

<BR>

<BR>

<A NAME="E69E40"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>QUERY_STRING</B></FONT></CENTER></H4>

<BR>

<P>QUERY_STRING is one of the most important of all CGI environment variables. The QUERY_STRING variable is used for passing form information to a CGI. On CGIs that use the GET HTTP method, this variable will contain the query portion of the URL. Requests made to a CGI usually include a ? that is followed by the arguments to the query. In the URL http://www.company.com/cgi-bin/test?yes, the value of QUERY_STRING will be set to yes.

<BR>

<P>It is important to be aware that because QUERY_STRING is an environment variable , there are space limitations imposed by the operating system. Some systems limit the environment space anywhere from 250&#150;8000 bytes. On my system, this limit is much larger&#151;about 40,000 bytes. If your CGI handles a form that could potentially receive a large amount of data, you may want to consider using POST transactions to ensure portability and avoid overflows. POST transactions don't put values on QUERY_STRING; instead, the data comes into the CGI via the standard input stream.

<BR>

<P>Data in the QUERY_STRING is formatted as <I>key</I>=<I>value</I> pairs. <I>key</I> is the name assigned to the form widget using the NAME attribute in the HTML file. <I>value</I><I> </I>is the value that the user assigned to the widget with a browser. Multiple <I>key</I>=<I>value</I> pairs are separated by ampersand (&amp;) characters. In addition to this formatting, the browser will encode any non-alphanumeric character using a percent character plus the character's hexadecimal value. For example, %2C equals a , character. Spaces are encoded with a plus (+) character. The following QUERY_STRING is the result of two form fields, one called Name, the other called Address:

<BR>

<BR>

<PRE>

<FONT COLOR="#000080">QUERY_STRING = Name=My+Name&amp;Address=Some+Street+Rd.%0ACity%2C+State++12345&amp; name=Submit</FONT></PRE>

<P>The Name field contains the data

<BR>

<BR>

<PRE>

<FONT COLOR="#000080">My+Name</FONT></PRE>

<P>The space between My and Name is encoded to a +.

<BR>

<P>The Address field contains

<BR>

<PRE>

<FONT COLOR="#000080">Some Street Rd.

City, State 12345</FONT></PRE>

<P>In the second field, spaces are also converted to + characters. In addition, the newline after Rd. is encoded to %0A. The %2C corresponds to a comma (,).

<BR>

<BR>

<A NAME="E69E41"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>REMOTE_ADDR</B></FONT></CENTER></H4>

<BR>

<P>The REMOTE_ADDR variable contains the IP address of the host making the request. IP addresses currently are written in dotted-decimal notation (four octets or 8-bit values represented in decimal, separated by dots). If you are concerned with security (and who isn't?) it is a good idea to log this variable in a logfile created specially for this form by your CGI program. You can also log REMOTE_HOST, REMOTE_IDENT, HTTP_USER_AGENT, and HTTP_REFERER. Although this takes up disk space, it also allows you to identify people (somewhat) who submit nasty, threatening, or malicious form data. For alternative logging suggestions, please see <A HREF="asg13.htm" tppabs="http://docs.rinet.ru:8080/Apachu/asg13.htm">Chapter 13</A>, &quot;Web Accounting.&quot;

<BR>

<BR>

<A NAME="E69E42"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>REMOTE_HOST</B></FONT></CENTER></H4>

<BR>

<P>The REMOTE_HOST variable contains the hostname of the client making the request. It will be set only if reverse DNS lookups are enabled for your server. Reverse DNS lookups create an extra load on your server and should not be enabled on high-traffic servers. If your CGI needs to determine the hostname, you should be able to determine this information easily enough when you need it with a call to /usr/bin/host (part of the BIND release), with the IP address of the host in question from the REMOTE_ADDR variable.

<BR>

<BR>

<A NAME="E69E43"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>REMOTE_IDENT</B></FONT></CENTER></H4>

<BR>

<P>For clients running identd services, the REMOTE_IDENT variable will be set to the username of the user making the request. Many clients don't run this service and, as should be expected, you should never trust this information.

<BR>

<BR>

<A NAME="E69E44"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>REMOTE_USER</B></FONT></CENTER></H4>

<BR>

<P>Requests that require user authentication will set the REMOTE_USER variable to the name the user entered during the authentication session.

<BR>

<BR>

<A NAME="E69E45"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>REQUEST_METHOD</B></FONT></CENTER></H4>

<BR>

<P>The REQUEST_METHOD variable holds the name of the HTTP method used to make the request. Valid HTTP methods are GET, POST, HEAD, PUT, DELETE, LINK, and UNLINK. The Apache server implements only the first four methods, which specify where a CGI program will find its data. You can implement any of the other methods with CGI programs; however, be aware that those methods implement potential security hole