5789N/A<?
xml version="1.0" encoding="ISO-8859-1"?>
5789N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5789N/A This file is generated from xml source: DO NOT EDIT 5789N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5789N/A<
title>Apache Tutorial: Dynamic Content with CGI - Apache HTTP Server</
title>
5789N/A<
body id="manual-page"><
div id="page-header">
5789N/A<
p class="apache">Apache HTTP Server Version 2.3</
p>
5789N/A<
div id="quickview"><
ul id="toc"><
li><
img alt="" src="/images/down.gif" /> <
a href="#intro">Introduction</
a></
li>
5789N/A<
li><
img alt="" src="/images/down.gif" /> <
a href="#configuring">Configuring Apache to permit CGI</
a></
li>
5789N/A<
li><
img alt="" src="/images/down.gif" /> <
a href="#troubleshoot">But it's still not working!</
a></
li>
5789N/A<
li><
img alt="" src="/images/down.gif" /> <
a href="#behindscenes">What's going on behind the scenes?</
a></
li>
5789N/A<
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
5789N/A<
h2><
a name="intro" id="intro">Introduction</
a></
h2>
5789N/A <
table class="related"><
tr><
th>Related Modules</
th><
th>Related Directives</
th></
tr><
tr><
td><
ul><
li><
code class="module"><
a href="/mod/mod_alias.html">mod_alias</
a></
code></
li><
li><
code class="module"><
a href="/mod/mod_cgi.html">mod_cgi</
a></
code></
li></
ul></
td><
td><
ul><
li><
code class="directive"><
a href="/mod/mod_mime.html#addhandler">AddHandler</
a></
code></
li><
li><
code class="directive"><
a href="/mod/core.html#options">Options</
a></
code></
li><
li><
code class="directive"><
a href="/mod/mod_alias.html#scriptalias">ScriptAlias</
a></
code></
li></
ul></
td></
tr></
table>
5789N/A <
p>The CGI (Common Gateway Interface) defines a way for a web
5789N/A server to interact with external content-generating programs,
5789N/A which are often referred to as CGI programs or CGI scripts. It
5789N/A is the simplest, and most common, way to put dynamic content on
5789N/A your web site. This document will be an introduction to setting
5789N/A up CGI on your Apache web server, and getting started writing
5789N/A </
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
5789N/A<
h2><
a name="configuring" id="configuring">Configuring Apache to permit CGI</
a></
h2>
5789N/A <
p>In order to get your CGI programs to work properly, you'll
5789N/A need to have Apache configured to permit CGI execution. There
5789N/A are several ways to do this.</
p>
5789N/A <
div class="warning">Note: If Apache has been built with shared module
5789N/A support you need to ensure that the module is loaded; in your
5789N/A directive has not been commented out. A correctly configured directive
5789N/A <
div class="example"><
p><
code>
5789N/A <
h3><
a name="scriptalias" id="scriptalias">ScriptAlias</
a></
h3>
5789N/A directive tells Apache that a particular directory is set
5789N/A aside for CGI programs. Apache will assume that every file in
5789N/A this directory is a CGI program, and will attempt to execute
5789N/A it, when that particular resource is requested by a
5789N/A <
div class="example"><
p><
code>
5789N/A configuration file, if you installed Apache in the default
5789N/A directive is much like the <
code class="directive"><
a href="/mod/mod_alias.html#alias">Alias</
a></
code> directive, which defines a URL prefix that
5789N/A is to mapped to a particular directory. <
code class="directive">Alias</
code>
5789N/A and <
code class="directive">ScriptAlias</
code> are usually used for
5789N/A directories that are outside of the <
code class="directive"><
a href="/mod/core.html#documentroot">DocumentRoot</
a></
code> directory. The difference between
5789N/A <
code class="directive">Alias</
code> and <
code class="directive">ScriptAlias</
code>
5789N/A is that <
code class="directive">ScriptAlias</
code> has the added meaning
5789N/A that everything under that URL prefix will be considered a CGI
5789N/A program. So, the example above tells Apache that any request for a
5789N/A resource beginning with <
code>/cgi-bin/</
code> should be served from
5789N/A treated as a CGI program.</
p>
5789N/A is requested, Apache will attempt to execute the file
5789N/A and return the output. Of course, the file will have to
5789N/A exist, and be executable, and return output in a particular
5789N/A way, or Apache will return an error message.</
p>
5789N/A <
h3><
a name="nonscriptalias" id="nonscriptalias">CGI outside of ScriptAlias directories</
a></
h3>
5789N/A <
p>CGI programs are often restricted to <
code class="directive"><
a href="/mod/mod_alias.html#scriptalias">ScriptAlias</
a></
code>'ed directories for security reasons.
5789N/A In this way, administrators can tightly control who is allowed to
5789N/A use CGI programs. However, if the proper security precautions are
5789N/A taken, there is no reason why CGI programs cannot be run from
5789N/A arbitrary directories. For example, you may wish to let users
5789N/A have web content in their home directories with the
5789N/A If they want to have their own CGI programs, but don't have access to
5789N/A the main <
code>cgi-bin</
code> directory, they will need to be able to
5789N/A run CGI programs elsewhere.</
p>
5789N/A <
p>There are two steps to allowing CGI execution in an arbitrary
5789N/A directory. First, the <
code>cgi-script</
code> handler must be
5789N/A activated using the <
code class="directive"><
a href="/mod/mod_mime.html#addhandler">AddHandler</
a></
code> or <
code class="directive"><
a href="/mod/core.html#sethandler">SetHandler</
a></
code> directive. Second,
5789N/A <
code>ExecCGI</
code> must be specified in the <
code class="directive"><
a href="/mod/core.html#options">Options</
a></
code> directive.</
p>
5789N/A <
h3><
a name="options" id="options">Explicitly using Options to permit CGI execution</
a></
h3>
5789N/A <
p>You could explicitly use the <
code class="directive"><
a href="/mod/core.html#options">Options</
a></
code> directive, inside your main server configuration
5789N/A file, to specify that CGI execution was permitted in a particular
5789N/A <
div class="example"><
p><
code>
5789N/A <
p>The above directive tells Apache to permit the execution
5789N/A of CGI files. You will also need to tell the server what
5789N/A files are CGI files. The following <
code class="directive"><
a href="/mod/mod_mime.html#addhandler">AddHandler</
a></
code> directive tells the server to treat all
5789N/A files with the <
code>cgi</
code> or <
code>pl</
code> extension as CGI
5789N/A <
div class="example"><
p><
code>
5789N/A AddHandler cgi-script .cgi .pl
5789N/A <
h3><
a name="htaccess" id="htaccess">.htaccess files</
a></
h3>
5789N/A shows how to activate CGI programs if you do not have
5789N/A <
h3><
a name="userdir" id="userdir">User Directories</
a></
h3>
5789N/A <
p>To allow CGI program execution for any file ending in
5789N/A <
code>.cgi</
code> in users' directories, you can use the
5789N/A following configuration.</
p>
5789N/A <
div class="example"><
p><
code>
5789N/A <Directory /home/*/public_html><
br />
5789N/A AddHandler cgi-script .cgi<
br />
5789N/A <
p>If you wish designate a <
code>cgi-bin</
code> subdirectory of
5789N/A a user's directory where everything will be treated as a CGI
5789N/A program, you can use the following.</
p>
5789N/A <
div class="example"><
p><
code>
5789N/A SetHandler cgi-script<
br />
5789N/A </
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
5789N/A<
h2><
a name="writing" id="writing">Writing a CGI program</
a></
h2>
5789N/A <
p>There are two main differences between ``regular''
5789N/A programming, and CGI programming.</
p>
5789N/A <
p>First, all output from your CGI program must be preceded by
5789N/A a <
a class="glossarylink" href="/glossary.html#mime-type" title="see glossary">MIME-type</
a> header. This is HTTP header that tells the client
5789N/A what sort of content it is receiving. Most of the time, this
5789N/A <
div class="example"><
p><
code>
5789N/A <
p>Secondly, your output needs to be in HTML, or some other
5789N/A format that a browser will be able to display. Most of the
5789N/A time, this will be HTML, but occasionally you might write a CGI
5789N/A program that outputs a gif image, or other non-HTML
5789N/A <
p>Apart from those two things, writing a CGI program will look
5789N/A a lot like any other program that you might write.</
p>
5789N/A <
h3><
a name="firstcgi" id="firstcgi">Your first CGI program</
a></
h3>
5789N/A <
p>The following is an example CGI program that prints one
5789N/A line to your browser. Type in the following, save it to a
5789N/A <
code>cgi-bin</
code> directory.</
p>
5789N/A <
div class="example"><
p><
code>
5789N/A <
p>Even if you are not familiar with Perl, you should be able
5789N/A to see what is happening here. The first line tells Apache
5789N/A (or whatever shell you happen to be running under) that this
5789N/A program can be executed by feeding the file to the
5789N/A The second line prints the content-type declaration we
5789N/A talked about, followed by two carriage-return newline pairs.
5789N/A This puts a blank line after the header, to indicate the end
5789N/A of the HTTP headers, and the beginning of the body. The third
5789N/A line prints the string "Hello, World.". And that's the end
5789N/A <
p>If you open your favorite browser and tell it to get the
5789N/A <
div class="example"><
p><
code>
5789N/A <
p>or wherever you put your file, you will see the one line
5789N/A <
code>Hello, World.</
code> appear in your browser window.
5789N/A It's not very exciting, but once you get that working, you'll
5789N/A have a good chance of getting just about anything working.</
p>
5789N/A </
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
5789N/A<
h2><
a name="troubleshoot" id="troubleshoot">But it's still not working!</
a></
h2>
5789N/A <
p>There are four basic things that you may see in your browser
5789N/A when you try to access your CGI program from the web:</
p>
5789N/A <
dt>The output of your CGI program</
dt>
5789N/A <
dd>Great! That means everything worked fine. If the output is correct,
5789N/A but the browser is not processing it correctly, make sure you have the
5789N/A correct <
code>Content-Type</
code> set in your CGI program.</
dd>
5789N/A <
dt>The source code of your CGI program or a "POST Method Not
5789N/A <
dd>That means that you have not properly configured Apache
5789N/A to process your CGI program. Reread the section on
5789N/A <
a href="#configuring">configuring
5789N/A Apache</
a> and try to find what you missed.</
dd>
5789N/A <
dt>A message starting with "Forbidden"</
dt>
5789N/A <
dd>That means that there is a permissions problem. Check the
5789N/A <
a href="#errorlogs">Apache error log</
a> and the section below on
5789N/A <
a href="#permissions">file permissions</
a>.</
dd>
5789N/A <
dt>A message saying "Internal Server Error"</
dt>
5789N/A <
a href="#errorlogs">Apache error log</
a>, you will probably
5789N/A find that it says "Premature end of
5789N/A script headers", possibly along with an error message
5789N/A generated by your CGI program. In this case, you will want to
5789N/A check each of the below sections to see what might be
5789N/A preventing your CGI program from emitting the proper HTTP
5789N/A <
h3><
a name="permissions" id="permissions">File permissions</
a></
h3>
5789N/A <
p>Remember that the server does not run as you. That is,
5789N/A when the server starts up, it is running with the permissions
5789N/A of an unprivileged user - usually <
code>nobody</
code>, or
5789N/A <
code>www</
code> - and so it will need extra permissions to
5789N/A execute files that are owned by you. Usually, the way to give
5789N/A a file sufficient permissions to be executed by <
code>nobody</
code>
5789N/A is to give everyone execute permission on the file:</
p>
5789N/A <
div class="example"><
p><
code>
5789N/A <
p>Also, if your program reads from, or writes to, any other
5789N/A files, those files will need to have the correct permissions
5789N/A <
h3><
a name="pathinformation" id="pathinformation">Path information and environment</
a></
h3>
5789N/A <
p>When you run a program from your command line, you have
5789N/A certain information that is passed to the shell without you
5789N/A thinking about it. For example, you have a <
code>PATH</
code>,
5789N/A which tells the shell where it can look for files that you
5789N/A <
p>When a program runs through the web server as a CGI program,
5789N/A it may not have the same <
code>PATH</
code>. Any programs that you
5789N/A invoke in your CGI program (like <
code>sendmail</
code>, for
5789N/A example) will need to be specified by a full path, so that the
5789N/A shell can find them when it attempts to execute your CGI
5789N/A <
p>A common manifestation of this is the path to the script
5789N/A interpreter (often <
code>perl</
code>) indicated in the first
5789N/A line of your CGI program, which will look something like:</
p>
5789N/A <
div class="example"><
p><
code>
5789N/A <
p>Make sure that this is in fact the path to the
5789N/A When editing CGI scripts on Windows, end-of-line characters may be
5789N/A appended to the interpreter path. Ensure that files are then
5789N/A transferred to the server in ASCII mode. Failure to do so may
5789N/A result in "Command not found" warnings from the OS, due to the
5789N/A unrecognized end-of-line character being interpreted as a part of
5789N/A <
h3><
a name="missingenv" id="missingenv">Missing environment variables</
a></
h3>
5789N/A <
p>If your CGI program depends on non-standard <
a href="#env">environment variables</
a>, you will need to
5789N/A assure that those variables are passed by Apache.</
p>
5789N/A <
p>When you miss HTTP headers from the environment, make
5789N/A sure they are formatted according to
5789N/A section 4.2: Header names must start with a letter,
5789N/A followed only by letters, numbers or hyphen. Any header
5789N/A violating this rule will be dropped silently.</
p>
5789N/A <
h3><
a name="syntaxerrors" id="syntaxerrors">Program errors</
a></
h3>
5789N/A <
p>Most of the time when a CGI program fails, it's because of
5789N/A a problem with the program itself. This is particularly true
5789N/A once you get the hang of this CGI stuff, and no longer make
5789N/A the above two mistakes. The first thing to do is to make
5789N/A sure that your program runs from the command line before
5789N/A testing it via the web server. For example, try:</
p>
5789N/A <
div class="example"><
p><
code>
5789N/A <
p>(Do not call the <
code>perl</
code> interpreter. The shell
5789N/A and Apache should find the interpreter using the <
a href="#pathinformation">path information</
a> on the first line of
5789N/A <
p>The first thing you see written by your program should be
5789N/A a set of HTTP headers, including the <
code>Content-Type</
code>,
5789N/A followed by a blank line. If you see anything else, Apache will
5789N/A return the <
code>Premature end of script headers</
code> error if
5789N/A you try to run it through the server. See <
a href="#writing">Writing a CGI program</
a> above for more
5789N/A <
h3><
a name="errorlogs" id="errorlogs">Error logs</
a></
h3>
5789N/A <
p>The error logs are your friend. Anything that goes wrong
5789N/A generates message in the error log. You should always look
5789N/A there first. If the place where you are hosting your web site
5789N/A does not permit you access to the error log, you should
5789N/A probably host your site somewhere else. Learn to read the
5789N/A error logs, and you'll find that almost all of your problems
5789N/A are quickly identified, and quickly solved.</
p>
5789N/A <
h3><
a name="suexec" id="suexec">Suexec</
a></
h3>
5789N/A allows CGI programs to be run under different user permissions,
5789N/A depending on which virtual host or user home directory they are
5789N/A located in. Suexec has very strict permission checking, and any
5789N/A failure in that checking will result in your CGI programs
5789N/A failing with <
code>Premature end of script headers</
code>.</
p>
5789N/A <
p>To check if you are using suexec, run <
code>apachectl
5789N/A -V</
code> and check for the location of <
code>SUEXEC_BIN</
code>.
5789N/A suexec will be activated.</
p>
5789N/A <
p>Unless you fully understand suexec, you should not be using it.
5789N/A binary pointed to by <
code>SUEXEC_BIN</
code> and then restart the
5789N/A you still wish to use it, then run <
code>suexec -V</
code> to find
5789N/A the location of the suexec log file, and use that log file to
5789N/A find what policy you are violating.</
p>
5789N/A </
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
5789N/A<
h2><
a name="behindscenes" id="behindscenes">What's going on behind the scenes?</
a></
h2>
5789N/A <
p>As you become more advanced in CGI programming, it will
5789N/A become useful to understand more about what's happening behind
5789N/A the scenes. Specifically, how the browser and server
5789N/A communicate with one another. Because although it's all very
5789N/A well to write a program that prints "Hello, World.", it's not
5789N/A <
h3><
a name="env" id="env">Environment variables</
a></
h3>
5789N/A <
p>Environment variables are values that float around you as
5789N/A you use your computer. They are useful things like your path
5789N/A (where the computer searches for the actual file
5789N/A implementing a command when you type it), your username, your
5789N/A terminal type, and so on. For a full list of your normal,
5789N/A every day environment variables, type
5789N/A <
code>env</
code> at a command prompt.</
p>
5789N/A <
p>During the CGI transaction, the server and the browser
5789N/A also set environment variables, so that they can communicate
5789N/A with one another. These are things like the browser type
5789N/A (Netscape, IE, Lynx), the server type (Apache, IIS, WebSite),
5789N/A the name of the CGI program that is being run, and so on.</
p>
5789N/A <
p>These variables are available to the CGI programmer, and
5789N/A are half of the story of the client-server communication. The
5789N/A complete list of required variables is at
5789N/A <
p>This simple Perl CGI program will display all of the
5789N/A environment variables that are being passed around. Two
5789N/A similar programs are included in the
5789N/A directory of the Apache distribution. Note that some
5789N/A variables are required, while others are optional, so you may
5789N/A see some variables listed that were not in the official list.
5789N/A In addition, Apache provides many different ways for you to
5789N/A to the basic ones provided by default.</
p>
5789N/A <
div class="example"><
p><
code>
5789N/A foreach $key (keys %ENV) {<
br />
5789N/A print "$key --> $ENV{$key}<br>";<
br />
5789N/A <
h3><
a name="stdin" id="stdin">STDIN and STDOUT</
a></
h3>
5789N/A <
p>Other communication between the server and the client
5789N/A happens over standard input (<
code>STDIN</
code>) and standard
5789N/A output (<
code>STDOUT</
code>). In normal everyday context,
5789N/A <
code>STDIN</
code> means the keyboard, or a file that a
5789N/A program is given to act on, and <
code>STDOUT</
code>
5789N/A usually means the console or screen.</
p>
5789N/A <
p>When you <
code>POST</
code> a web form to a CGI program,
5789N/A the data in that form is bundled up into a special format
5789N/A and gets delivered to your CGI program over <
code>STDIN</
code>.
5789N/A The program then can process that data as though it was
5789N/A coming in from the keyboard, or from a file</
p>
5789N/A <
p>The "special format" is very simple. A field name and
5789N/A its value are joined together with an equals (=) sign, and
5789N/A pairs of values are joined together with an ampersand
5789N/A (&). Inconvenient characters like spaces, ampersands, and
5789N/A equals signs, are converted into their hex equivalent so that
5789N/A they don't gum up the works. The whole data string might look
5789N/A <
div class="example"><
p><
code>
5789N/A name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
5789N/A <
p>You'll sometimes also see this type of string appended to
5789N/A a URL. When that is done, the server puts that string
5789N/A into the environment variable called
5789N/A <
code>QUERY_STRING</
code>. That's called a <
code>GET</
code>
5789N/A request. Your HTML form specifies whether a <
code>GET</
code>
5789N/A or a <
code>POST</
code> is used to deliver the data, by setting the
5789N/A <
code>METHOD</
code> attribute in the <
code>FORM</
code> tag.</
p>
5789N/A <
p>Your program is then responsible for splitting that string
5789N/A up into useful information. Fortunately, there are libraries
5789N/A and modules available to help you process this data, as well
5789N/A as handle other of the aspects of your CGI program.</
p>
5789N/A </
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
5789N/A <
p>When you write CGI programs, you should consider using a
5789N/A code library, or module, to do most of the grunt work for you.
5789N/A This leads to fewer errors, and faster development.</
p>
5789N/A <
p>If you're writing CGI programs in Perl, modules are
5789N/A popular module for this purpose is <
code>
CGI.pm</
code>. You might
5789N/A also consider <
code>CGI::Lite</
code>, which implements a minimal
5789N/A set of functionality, which is all you need in most programs.</
p>
5789N/A <
p>If you're writing CGI programs in C, there are a variety of
5789N/A options. One of these is the <
code>CGIC</
code> library, from
5789N/A </
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
5789N/A<
h2><
a name="moreinfo" id="moreinfo">For more information</
a></
h2>
5789N/A <
p>There are a large number of CGI resources on the web.
5789N/A The list from the HTML Writers Guild is a great source of answers
5789N/A to your questions. You can find out more at
5789N/A <
p>The current CGI specification is available in the
5789N/A <
p>When you post a question about a CGI problem that you're
5789N/A having, whether to a mailing list, or to a newsgroup, make sure
5789N/A you provide enough information about what happened, what you
5789N/A expected to happen, and how what actually happened was
5789N/A different, what server you're running, what language your CGI
5789N/A program was in, and, if possible, the offending code. This will
5789N/A make finding your problem much simpler.</
p>
5789N/A <
p>Note that questions about CGI problems should <
strong>never</
strong>
5789N/A be posted to the Apache bug database unless you are sure you
5789N/A have found a problem in the Apache source code.</
p>
