asgxa.htm

apache技术手册

<P>You eagle-eyed readers may have noticed that the text area in the previous example had an underscore (_) at the beginning of its name. When Un-CGI sees a form field whose name begins with an underscore, it strips whitespace from the beginning and end of the value and makes sure that all the end-of-line characters in the value are UNIX-style newlines (as opposed to DOS-style CR-LF pairs or Macintosh-style CRs, both of which are sent by some browsers). This makes processing text easier because your program doesn't have to worry about the browser's end-of-line conventions. Note that if a form field is named _xyz, you still get an environment variable called WWW_xyz. The extra underscore doesn't show up in the environment variable name.

<BR>

<P>Un-CGI also modifies variable names containing periods. The major source of which is &lt;input type=image&gt;. Shell scripts have trouble coping with periods in environment variable names, so Un-CGI converts periods to underscores. This is only done to variable names; periods in values will remain untouched.

<BR>

<BR>

<A NAME="E68E178"></A>

<H3 ALIGN=CENTER>

<CENTER>

<FONT SIZE=5 COLOR="#FF0000"><B>Other Features</B></FONT></CENTER></H3>

<BR>

<P>If you compile with -DNO_MAIN, you can use Un-CGI as a library function in a C program of your own. Just call uncgi() at the start of your program. Follow this example.

<BR>

<P>Un-CGI will handle hybrid GET/POST requests. Specify a method of POST in the form, and add a GET-style query string to the action An example of this is as follows:

<BR>

<BR>

<PRE>

<FONT COLOR="#000080">&lt;from method=POST action=&quot;/cgi-bin/uncgi/myscript?form id=feedback&quot;&gt;</FONT></PRE>

<P>When your script is run, WWW_form_id will be set to feedback. This will only work if your HTTP server supports it (NCSA's does, for now anyway).

<BR>

<P>Un-CGI is freeware. If you want to include it in a commercial product, please send me mail. I'll probably just ask you to include a pointer to this page with your product. If you want to pay me for Un-CGI, send me a picture postcard to help decorate my wall! My address is

<BR>

<P>Steven Grimm

<BR>Hyperion

<BR>173 Sherland Ave.

<BR>Mountain View, CA 94043

<BR>

<BR>

<A NAME="E68E179"></A>

<H3 ALIGN=CENTER>

<CENTER>

<FONT SIZE=5 COLOR="#FF0000"><B>Frequently Asked Questions</B></FONT></CENTER></H3>

<BR>

<P>As with any kind of program, many questions arise regarding its use. What follows is a compilation of the most frequently asked questions about Un-CGI.

<BR>

<BR>

<A NAME="E69E198"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>I Get an Error About </B><B>sys_errlist</B><B> When I Compile</B></FONT></CENTER></H4>

<BR>

<P>Some UNIX variants' standard-include files contain a declaration for the list of system error codes, and some don't. For the latter, I need to include the declaration in uncgi.c. If you get an error about a previous declaration of sys_errlist, edit uncgi.c and remove the line:

<BR>

<BR>

<PRE>

<FONT COLOR="#000080">extern char *sys_errlist[];</FONT></PRE>

<P>Then recompile and everything should work.

<BR>

<BR>

<A NAME="E69E199"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>Where Do I Put Everything?</B></FONT></CENTER></H4>

<BR>

<P>Short answer: Look in the makefile.

<BR>

<P>Long answer: When you edit Un-CGI's makefile, you'll see two macro definitions relating to paths. The first, SCRIPT_DIR, tells Un-CGI where to look for your scripts or programs. It must be set to the name of an existing directory; you can set it to any directory you like.

<BR>

<P>Sometimes it is set to the location of your server's cgi-bin directory, although that's not necessary. The second, DESTDIR, tells the makefile where to install Un-CGI. It must point to your server's cgi-bin directory, if your server has one.

<BR>

<P>Note that you can't just create a directory called cgi-bin in your account and expect it to work. The server has configuration files that tell it where to look for scripts and programs. Talk to your system administrator if you aren't the person in charge of the server on your machine.

<BR>

<P>An additional makefile setting, EXTENSION, should be of help if your server allows you to put CGI programs anywhere on the system. Again, consult your system administrator to see if this is the case.

<BR>

<BR>

<A NAME="E69E200"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>Why Does Un-CGI Tell Me It Can't Run My Script?</B></FONT></CENTER></H4>

<BR>

<P>First, make sure your script is in the right place; see the preceding section. Second, make sure your script can be executed by the server. Remember, Un-CGI is run by the server, which is probably using a system user ID, not your user ID. You need to set the permissions on your script so that it can be run by any user. Usually, you can say &quot;chmod 755 <I>scriptname</I>&quot; (replacing <I>scriptname</I> with the name of your script) to set the permissions properly.

<BR>

<P>If you're still having trouble, edit the makefile, uncomment the DEBUG_PATH line, and rebuild. This will instruct Un-CGI to include the full path to where it thinks your script should be in its error message.

<BR>

<BR>

<A NAME="E69E201"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>What Do I Do in My Forms?</B></FONT></CENTER></H4>

<BR>

<P>The &lt;form&gt; tag has two attributes, METHOD and ACTION. METHOD must be set to either GET or POST. Un-CGI will handle either one, but POST is preferred if you have text area fields or are expecting a lot of information from the client. Note that the attribute name (METHOD) can be upper or lowercase, but the value must be all caps.

<BR>

<P>ACTION should have the following components:

<BR>

<UL>

<LI>The alias for your server's cgi-bin directory (usually just /cgi-bin/).

<BR>

<BR>

<LI>uncgi/ to tell the server which program to execute.

<BR>

<BR>

<LI>The name of your script as it appears in the directory where you told Un-CGI to find your scripts and programs (the CGI_BIN macro in the makefile). Example: myscript.

<BR>

<BR>

<LI>Optionally, a forward slash followed by additional parameters&#151;often the path to another file you want your script to print. This path information will be available to your script in the PATH_INFO and PATH_TRANSLATED environment variables. The latter contains the full path to the document, including the path to the server root directory. Note that you can't use tilde (~) notation. Example: /form_output/acknowledge.html.

<BR>

<BR>

</UL>

<P>So, if you wanted to tell Un-CGI to run sendmemail with no additional parameters, you'd put sendmemail in the directory you specified as the value of CGI_BIN in Un-CGI's makefile, and use the following tag to begin your form:

<BR>

<BR>

<PRE>

<FONT COLOR="#000080">&lt;form method=POST action=&quot;/cgi-bin/uncgi/sendmemail&quot;&gt;</FONT></PRE>

<BR>

<A NAME="E69E202"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>I Get an Error 403 when I Submit My Form</B></FONT></CENTER></H4>

<BR>

<P>The usual cause of this is that your server requires a special filename extension on CGI programs. (Most often it's .cgi.) You need to give Un-CGI a name that will identify it as a CGI program to the Web server. There is nothing special about Un-CGI from the Web server's point of view; it's just another program that gets run like any other, and your installation of it has to obey the same rules as other programs.

<BR>

<BR>

<A NAME="E69E203"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>I Get an Error Code 500 From the Server</B></FONT></CENTER></H4>

<BR>

<P>This usually means your script isn't specifying a content type to the server. The first thing your script needs to output is Content-type: text/html followed by a blank line. Note that the blank line following the header is not optional, and it has to be completely empty&#151;no whitespace. (See <A HREF="asg05.htm" tppabs="http://docs.rinet.ru:8080/Apachu/asg05.htm">Chapter 5</A>, &quot;CGI (Common Gateway Interface) Programming,&quot; for more information.) If you're writing a shell script, for instance, you'll need the following:

<BR>

<PRE>

<FONT COLOR="#000080">echo Content-type: text/html

echo &quot;&quot;</FONT></PRE>

<P>The empty quotes on the second line are necessary; otherwise, echo won't print anything, not even a blank line. Of course, if your script is outputting something other than HTML, adjust the content type accordingly.

<BR>

<BR>

<A NAME="E69E204"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>My Script Doesn't See the Form Variables</B></FONT></CENTER></H4>

<BR>

<P>There are a few common causes for this:

<BR>

<UL>

<LI>Make sure you're actually running Un-CGI. If you install Un-CGI but your form's ACTION attribute still points to something like /cgi-bin/myscript, Un-CGI isn't being executed by the Web server when the user submits the form. See the previous example forms.

<BR>

<BR>

<LI>Environment variables are case sensitive, which means that if you have a field in your form named revision, Un-CGI will create an environment variable named WWW_revision, not WWW_REVISION or WWW_Revision.

<BR>

<BR>

<LI>Most shells restrict the characters you can use in variable names. In particular, spaces and punctuation are usually illegal. Underscores and numbers are fine.

<BR>

<BR>

</UL>

<BR>

<A NAME="E69E205"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>The Browser Just Sits There When I Submit My Form</B></FONT></CENTER></H4>

<BR>

<P>The most common cause of hangs like that is from trying to convert an old CGI-compliant program or script to run under Un-CGI. Your script is detecting that the form was submitted with the POST method and is trying to read form results from the browser. Unfortunately, by the time your script is run, Un-CGI has already read the results, so your program sits there waiting forever for bytes that have already been consumed.

<BR>

<P>Remove the part of your code that reads a query from the standard input. It'll generally be located somewhere around the word POST, which is easy to search for. Replace it with code that fills your program's internal variables via getenv() calls (assuming that your program is in C) on the WWW_ variables defined by Un-CGI.

<BR>

<BR>

<A NAME="E69E206"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>How Do I Parse Check Box Results?</B></FONT></CENTER></H4>

<BR>

<P>Un-CGI puts hash marks (#) between check box selections if there are several of them. How you parse depends entirely on which language you're using. In C, use strtok(). In Python, use string.splitfields(). In Perl, use split(). In Bourne shell, use something like the following:

<BR>

<PRE>

<FONT COLOR="#000080">echo $WWW_whatever | tr \# \\012 | while read result;

 do echo User picked $result

done</FONT></PRE>

<BR>

<A NAME="E69E207"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>Do I Need to Make a Directory Called </B><B>uncgi</B><B>?</B></FONT></CENTER></H4>

<BR>

<P>No. You're probably assuming that because your form has an ACTION like /cgi-bin/uncgi/xyz, there must be an uncgi directory under cgi-bin. That's not how it works.

<BR>

<P>The parts of a URL between the slashes are not directory names. They are symbols that tell the server where to find a particular document. In most cases, the server will look for a directory with the same name as the symbol in question. If there is one, go in that directory and proceed to the next symbol. However, that isn't always what happens. If the server sees that a particular symbol matches the name of a program, it will typically run that program and pass the rest of the URL to the program as an argument. And that's exactly what's happening here.

<BR>

<P>There's no uncgi directory. You can think of /cgi-bin/uncgi/xyz as /cgi-bin/uncgi xyz if that helps. (Strictly speaking, it's not accurate, but that's the concept.) Un-CGI sees the xyz argument and looks in its SCRIPT_BIN directory to find a program by that name.

<BR>

<P>If you're still not sure what all this means, just try it out and see what happens!

<BR>

<BR>

<A NAME="E69E208"></A>

<H4 ALIGN=CENTER>

<CENTER>

<FONT SIZE=4 COLOR="#FF0000"><B>Does Un-CGI Strip Out Special Shell Characters that Might Cause Security </B><B>Problems?</B></FONT></CENTER></H4>

<BR>

<P>No, it doesn't for the simple reason that Un-CGI isn't tied to any one shell or any shell at all, for that matter. Un-CGI sits in front of C programs just as easily as Bourne shell scripts, Perl scripts, or Python scripts. (All of which, incidentally, are used in conjunction with Un-CGI at Hyperion.)

<BR>

<P>In most of those languages, there <I>aren't</I> any special characters that are inherently security problems, so having Un-CGI strip characters that cause problems for a particular shell would just end up pointlessly mangling the input to other kinds of scripts and programs. People using shells with different special characters would still have to specially handle them anyway.

<BR>

<P>On most UNIXes, you can use the tr -d command to strip out characters that your shell processes. For example, to strip out dollar signs from a Bourne shell variable, you would type:

<BR>

<BR>

<PRE>

<FONT COLOR="#000080">WWW_puppycount=&quot;`echo $WWW_puppy | tr -d \$`&quot;</FONT></PRE>

<BR>

<A NAME="E68E180"></A>

<H3 ALIGN=CENTER>

<CENTER>

<FONT SIZE=5 COLOR="#FF0000"><B>Summary</B></FONT></CENTER></H3>

<BR>

<P><A NAME="I2"></A>Un-CGI can be a key piece of software when you are developing quick shell-based CGIs to handle output from forms. However, you should keep in mind that Un-CGI doesn't perform any sort of security checks on the submitted values it processes. For more information on security issues that you should address on your CGI, please refer to <A HREF="asg16.htm" tppabs="http://docs.rinet.ru:8080/Apachu/asg16.htm">Chapter 16</A>, &quot;Web <A NAME="I3"></A>Server Security Issues.&quot;

<BR>

<P ALIGN=LEFT>

<A HREF="asgpt6.htm" tppabs="http://docs.rinet.ru:8080/Apachu/asgpt6.htm" TARGET="_self"><IMG SRC="purprev.gif" tppabs="http://docs.rinet.ru:8080/Apachu/purprev.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Previous Page"></A>

<A HREF="#I0" TARGET="_self"><IMG SRC="purtop.gif" tppabs="http://docs.rinet.ru:8080/Apachu/purtop.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Page Top"></A>

<A HREF="index.htm" tppabs="http://docs.rinet.ru:8080/Apachu/index.htm" TARGET="_self"><IMG SRC="purtoc.gif" tppabs="http://docs.rinet.ru:8080/Apachu/purtoc.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="TOC"></A>

<A HREF="asgxb.htm" tppabs="http://docs.rinet.ru:8080/Apachu/asgxb.htm" TARGET="_self"><IMG SRC="purnext.gif" tppabs="http://docs.rinet.ru:8080/Apachu/purnext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>


</BODY></HTML>