<modulelist>
<module>mod_alias</module>
<module>mod_cgi</module>
+ <module>mod_cgid</module>
</modulelist>
<directivelist>
<p>The CGI (Common Gateway Interface) defines a way for a web
server to interact with external content-generating programs,
which are often referred to as CGI programs or CGI scripts. It
- is the simplest, and most common, way to put dynamic content on
- your web site. This document will be an introduction to setting
+ is a simple way to put dynamic content on
+ your web site, using whatever programming language you're most
+ familiar with. This document will be an introduction to setting
up CGI on your Apache web server, and getting started writing
CGI programs.</p>
</section>
directive has not been commented out. A correctly configured directive
may look like this:
- <example>
+ <highlight language="config">
+ LoadModule cgid_module modules/mod_cgid.so
+ </highlight>
+
+
+ On Windows, or using a non-threaded MPM like prefork, A correctly
+ configured directive may look like this:
+
+ <highlight language="config">
LoadModule cgi_module modules/mod_cgi.so
- </example></note>
+ </highlight></note>
+
<section id="scriptalias">
<title>ScriptAlias</title>
- <p>The
+ <p>The
<directive module="mod_alias">ScriptAlias</directive>
directive tells Apache that a particular directory is set
<p>The <directive module="mod_alias">ScriptAlias</directive>
directive looks like:</p>
- <example>
- ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
- </example>
+ <highlight language="config">
+ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"
+ </highlight>
<p>The example shown is from your default <code>httpd.conf</code>
configuration file, if you installed Apache in the default
<p>For example, if the URL
<code>http://www.example.com/cgi-bin/test.pl</code>
- is requested, Apache will attempt to execute the file
+ is requested, Apache will attempt to execute the file
<code>/usr/local/apache2/cgi-bin/test.pl</code>
and return the output. Of course, the file will have to
exist, and be executable, and return output in a particular
use CGI programs. However, if the proper security precautions are
taken, there is no reason why CGI programs cannot be run from
arbitrary directories. For example, you may wish to let users
- have web content in their home directories with the
+ have web content in their home directories with the
<directive module="mod_userdir">UserDir</directive> directive.
If they want to have their own CGI programs, but don't have access to
the main <code>cgi-bin</code> directory, they will need to be able to
module="mod_mime">AddHandler</directive> or <directive
module="core">SetHandler</directive> directive. Second,
<code>ExecCGI</code> must be specified in the <directive
- module="core">Options</directive> directive.</p>
+ module="core">Options</directive> directive.</p>
</section>
<section id="options">
file, to specify that CGI execution was permitted in a particular
directory:</p>
- <example>
- <Directory /usr/local/apache2/htdocs/somedir><br />
- <indent>
- Options +ExecCGI<br />
- </indent>
- </Directory>
- </example>
+ <highlight language="config">
+<Directory "/usr/local/apache2/htdocs/somedir">
+ Options +ExecCGI
+</Directory>
+ </highlight>
<p>The above directive tells Apache to permit the execution
of CGI files. You will also need to tell the server what
files with the <code>cgi</code> or <code>pl</code> extension as CGI
programs:</p>
- <example>
+ <highlight language="config">
AddHandler cgi-script .cgi .pl
- </example>
+ </highlight>
</section>
<section id="htaccess">
<code>.cgi</code> in users' directories, you can use the
following configuration.</p>
- <example>
- <Directory /home/*/public_html><br/>
- <indent>
- Options +ExecCGI<br/>
- AddHandler cgi-script .cgi<br/>
- </indent>
- </Directory>
- </example>
+ <highlight language="config">
+<Directory "/home/*/public_html">
+ Options +ExecCGI
+ AddHandler cgi-script .cgi
+</Directory>
+ </highlight>
<p>If you wish designate a <code>cgi-bin</code> subdirectory of
a user's directory where everything will be treated as a CGI
program, you can use the following.</p>
- <example>
- <Directory /home/*/public_html/cgi-bin><br/>
- <indent>
- Options ExecCGI<br/>
- SetHandler cgi-script<br/>
- </indent>
- </Directory>
- </example>
+ <highlight language="config">
+<Directory "/home/*/public_html/cgi-bin">
+ Options ExecCGI
+ SetHandler cgi-script
+</Directory>
+ </highlight>
</section>
<p>The following is an example CGI program that prints one
line to your browser. Type in the following, save it to a
- file called <code>first.pl</code>, and put it in your
+ file called <code>first.pl</code>, and put it in your
<code>cgi-bin</code> directory.</p>
- <example>
- #!/usr/bin/perl<br />
- print "Content-type: text/html\n\n";<br />
- print "Hello, World.";
- </example>
+ <highlight language="perl">
+#!/usr/bin/perl
+print "Content-type: text/html\n\n";
+print "Hello, World.";
+ </highlight>
<p>Even if you are not familiar with Perl, you should be able
to see what is happening here. The first line tells Apache
http://www.example.com/cgi-bin/first.pl
</example>
- <p>or wherever you put your file, you will see the one line
+ <p>or wherever you put your file, you will see the one line
<code>Hello, World.</code> appear in your browser window.
It's not very exciting, but once you get that working, you'll
have a good chance of getting just about anything working.</p>
<dt>The source code of your CGI program or a "POST Method Not
Allowed" message</dt>
<dd>That means that you have not properly configured Apache
- to process your CGI program. Reread the section on
+ to process your CGI program. Reread the section on
<a href="#configuring">configuring
Apache</a> and try to find what you missed.</dd>
<a href="#permissions">file permissions</a>.</dd>
<dt>A message saying "Internal Server Error"</dt>
- <dd>If you check the
+ <dd>If you check the
<a href="#errorlogs">Apache error log</a>, you will probably
find that it says "Premature end of
script headers", possibly along with an error message
interpreter (often <code>perl</code>) indicated in the first
line of your CGI program, which will look something like:</p>
- <example>
+ <highlight language="perl">
#!/usr/bin/perl
- </example>
+ </highlight>
<p>Make sure that this is in fact the path to the
interpreter.</p>
+ <note type="warning">
+ When editing CGI scripts on Windows, end-of-line characters may be
+ appended to the interpreter path. Ensure that files are then
+ transferred to the server in ASCII mode. Failure to do so may
+ result in "Command not found" warnings from the OS, due to the
+ unrecognized end-of-line character being interpreted as a part of
+ the interpreter filename.
+ </note>
+ </section>
- <p>In addition, if your CGI program depends on other <a
+ <section id="missingenv">
+ <title>Missing environment variables</title>
+
+ <p>If your CGI program depends on non-standard <a
href="#env">environment variables</a>, you will need to
assure that those variables are passed by Apache.</p>
+ <p>When you miss HTTP headers from the environment, make
+ sure they are formatted according to
+ <a href="http://tools.ietf.org/html/rfc2616">RFC 2616</a>,
+ section 4.2: Header names must start with a letter,
+ followed only by letters, numbers or hyphen. Any header
+ violating this rule will be dropped silently.</p>
+
</section>
<section id="syntaxerrors">
(where the computer searches for the actual file
implementing a command when you type it), your username, your
terminal type, and so on. For a full list of your normal,
- every day environment variables, type
+ every day environment variables, type
<code>env</code> at a command prompt.</p>
<p>During the CGI transaction, the server and the browser
<p>These variables are available to the CGI programmer, and
are half of the story of the client-server communication. The
- complete list of required variables is at
- <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html"
- >http://hoohoo.ncsa.uiuc.edu/cgi/env.html</a>.</p>
+ complete list of required variables is at
+ <a href="http://www.ietf.org/rfc/rfc3875">Common Gateway
+ Interface RFC</a>.</p>
<p>This simple Perl CGI program will display all of the
environment variables that are being passed around. Two
- similar programs are included in the
+ similar programs are included in the
<code>cgi-bin</code>
directory of the Apache distribution. Note that some
variables are required, while others are optional, so you may
see some variables listed that were not in the official list.
- In addition, Apache provides many different ways for you to
+ In addition, Apache provides many different ways for you to
<a href="../env.html">add your own environment variables</a>
to the basic ones provided by default.</p>
- <example>
- #!/usr/bin/perl<br />
- print "Content-type: text/html\n\n";<br />
- foreach $key (keys %ENV) {<br />
- <indent>
- print "$key --> $ENV{$key}<br>";<br />
- </indent>
- }
- </example>
+ <highlight language="perl">
+#!/usr/bin/perl
+use strict;
+use warnings;
+
+print "Content-type: text/html\n\n";
+foreach my $key (keys %ENV) {
+ print "$key --> $ENV{$key}<br>";
+}
+ </highlight>
</section>
<section id="stdin">
<p>Other communication between the server and the client
happens over standard input (<code>STDIN</code>) and standard
- output (<code>STDOUT</code>). In normal everyday context,
- <code>STDIN</code> means the keyboard, or a file that a
+ output (<code>STDOUT</code>). In normal everyday context,
+ <code>STDIN</code> means the keyboard, or a file that a
program is given to act on, and <code>STDOUT</code>
- usually means the console or screen.</p>
+ usually means the console or screen.</p>
<p>When you <code>POST</code> a web form to a CGI program,
the data in that form is bundled up into a special format
<p>You'll sometimes also see this type of string appended to
a URL. When that is done, the server puts that string
- into the environment variable called
+ into the environment variable called
<code>QUERY_STRING</code>. That's called a <code>GET</code>
request. Your HTML form specifies whether a <code>GET</code>
- or a <code>POST</code> is used to deliver the data, by setting the
+ or a <code>POST</code> is used to deliver the data, by setting the
<code>METHOD</code> attribute in the <code>FORM</code> tag.</p>
<p>Your program is then responsible for splitting that string
set of functionality, which is all you need in most programs.</p>
<p>If you're writing CGI programs in C, there are a variety of
- options. One of these is the <code>CGIC</code> library, from
+ options. One of these is the <code>CGIC</code> library, from
<a href="http://www.boutell.com/cgic/"
>http://www.boutell.com/cgic/</a>.</p>
</section>
<section id="moreinfo">
<title>For more information</title>
- <p>There are a large number of CGI resources on the web. You
- can discuss CGI problems with other users on the Usenet group
- <a href="news:comp.infosystems.www.authoring.cgi"
- >comp.infosystems.www.authoring.cgi</a>. And the -servers mailing
- list from the HTML Writers Guild is a great source of answers
- to your questions. You can find out more at
- <a href="http://www.hwg.org/lists/hwg-servers/"
- >http://www.hwg.org/lists/hwg-servers/</a>.</p>
-
- <p>And, of course, you should probably read the CGI
- specification, which has all the details on the operation of
- CGI programs. You can find the original version at the
- <a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"
- >NCSA</a> and there is an updated draft at the
- <a href="http://web.golux.com/coar/cgi/">Common Gateway
- Interface RFC project</a>.</p>
+ <p>The current CGI specification is available in the
+ <a href="http://www.ietf.org/rfc/rfc3875">Common Gateway
+ Interface RFC</a>.</p>
<p>When you post a question about a CGI problem that you're
having, whether to a mailing list, or to a newsgroup, make sure
have found a problem in the Apache source code.</p>
</section>
</manualpage>
-
projects / apache / blobdiff