granicus.if.org Git - apache/blob - docs/manual/howto/cgi.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       --><title>Apache Tutorial: Dynamic Content with CGI - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Apache Tutorial: Dynamic Content with CGI</h1></div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#intro">Introduction</a></li><li><img alt="" src="../images/down.gif" /> <a href="#configuring">Configuring Apache to permit CGI</a></li><li><img alt="" src="../images/down.gif" /> <a href="#writing">Writing a CGI program</a></li><li><img alt="" src="../images/down.gif" /> <a href="#troubleshoot">But it's still not working!</a></li><li><img alt="" src="../images/down.gif" /> <a href="#behindscenes">What's going on behind the scenes?</a></li><li><img alt="" src="../images/down.gif" /> <a href="#libraries">CGI modules/libraries</a></li><li><img alt="" src="../images/down.gif" /> <a href="#moreinfo">For more information</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="intro" id="intro">Introduction</a></h2>
   8
   9
  10     <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>
  11
  12     <p>The CGI (Common Gateway Interface) defines a way for a web
  13     server to interact with external content-generating programs,
  14     which are often referred to as CGI programs or CGI scripts. It
  15     is the simplest, and most common, way to put dynamic content on
  16     your web site. This document will be an introduction to setting
  17     up CGI on your Apache web server, and getting started writing
  18     CGI programs.</p>
  19   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="configuring" id="configuring">Configuring Apache to permit CGI</a></h2>
  20
  21
  22     <p>In order to get your CGI programs to work properly, you'll
  23     need to have Apache configured to permit CGI execution. There
  24     are several ways to do this.</p>
  25
  26     <h3><a name="scriptalias" id="scriptalias">ScriptAlias</a></h3>
  27
  28
  29       <p>The
  30       <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
  31
  32       directive tells Apache that a particular directory is set
  33       aside for CGI programs. Apache will assume that every file in
  34       this directory is a CGI program, and will attempt to execute
  35       it, when that particular resource is requested by a
  36       client.</p>
  37
  38       <p>The
  39       <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
  40
  41       directive looks like:</p>
  42
  43       <div class="example"><p><code>ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/</code></p></div>
  44
  45       <p>The example shown is from your default
  46       <code>httpd.conf</code>
  47
  48       configuration file, if you installed Apache in the default
  49       location. The <code>ScriptAlias</code> directive is much like the
  50       <code>Alias</code> directive, which defines a URL prefix that
  51       is to mapped to a particular directory.  <code>Alias</code>
  52       and <code>ScriptAlias</code> are usually used for directories
  53       that are outside of the <code>DocumentRoot</code> directory.
  54       The difference between <code>Alias</code> and
  55       <code>ScriptAlias</code> is that <code>ScriptAlias</code>
  56       has the added meaning that everything under that URL prefix
  57       will be considered a CGI program. So, the example above tells
  58       Apache that any request for a resource beginning with
  59       <code>/cgi-bin/</code> should be served from the directory
  60       <code>/usr/local/apache/cgi-bin/</code>, and should be treated
  61       as a CGI program.</p>
  62
  63       <p>For example, if the URL
  64       <code>http://www.example.com/cgi-bin/test.pl</code>
  65       is requested, Apache will attempt to execute the file
  66       <code>/usr/local/apache/cgi-bin/test.pl</code>
  67       and return the output. Of course, the file will have to
  68       exist, and be executable, and return output in a particular
  69       way, or Apache will return an error message.</p>
  70
  71
  72     <h3><a name="nonscriptalias" id="nonscriptalias">CGI outside of ScriptAlias directories</a></h3>
  73
  74
  75       <p>CGI programs are often restricted to
  76       <code>ScriptAlias</code>'ed directories for security reasons.
  77       In this way,
  78       administrators can tightly control who is allowed to use CGI
  79       programs. However, if the proper security precautions are
  80       taken, there is no reason why CGI programs cannot be run from
  81       arbitrary directories. For example, you may wish to let users
  82       have web content in their home directories with the
  83       <code>UserDir</code> directive. If they want to have their own
  84       CGI programs, but don't have access to the main
  85       <code>cgi-bin</code> directory, they will need to be able to
  86       run CGI programs elsewhere.</p>
  87
  88
  89     <h3><a name="options" id="options">Explicitly using Options to permit CGI execution</a></h3>
  90
  91
  92       <p>You could explicitly use the <code>Options</code>
  93       directive, inside your main server configuration file, to
  94       specify that CGI execution was permitted in a particular
  95       directory:</p>
  96
  97       <div class="example"><p><code>&lt;Directory /usr/local/apache/htdocs/somedir&gt; <br />
  98       Options +ExecCGI<br />
  99       &lt;/Directory&gt;</code></p></div>
 100
 101       <p>The above directive tells Apache to permit the execution
 102       of CGI files. You will also need to tell the server what
 103       files are CGI files. The following
 104       <code>AddHandler</code>
 105
 106       directive tells the server to treat all files with the
 107       <code>cgi</code> or <code>pl</code> extension as CGI programs:</p>
 108
 109       <div class="example"><p><code>AddHandler cgi-script cgi pl</code></p></div>
 110
 111
 112     <h3><a name="htaccess" id="htaccess">.htaccess files</a></h3>
 113
 114
 115       <p>A <code>.htaccess</code> file is a way to set configuration
 116       directives on a per-directory basis. When Apache serves a
 117       resource, it looks in the directory from which it is serving
 118       a file for a file called <code>.htaccess</code>, and, if it
 119       finds it, it will apply directives found therein.
 120
 121       <code>.htaccess</code> files can be permitted with the
 122       <code>AllowOverride</code> directive, which specifies what
 123       types of directives can
 124       appear in these files, or if they are not allowed at all. To
 125       permit the directive we will need for this purpose, the
 126       following configuration will be needed in your main server
 127       configuration:</p>
 128
 129       <div class="example"><p><code>AllowOverride Options</code></p></div>
 130
 131       <p>In the <code>.htaccess</code> file, you'll need the
 132       following directive:</p>
 133
 134       <div class="example"><p><code>Options +ExecCGI</code></p></div>
 135
 136       <p>which tells Apache that execution of CGI programs is
 137       permitted in this directory.</p>
 138
 139   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="writing" id="writing">Writing a CGI program</a></h2>
 140
 141
 142     <p>There are two main differences between ``regular''
 143     programming, and CGI programming.</p>
 144
 145     <p>First, all output from your CGI program must be preceded by
 146     a MIME-type header. This is HTTP header that tells the client
 147     what sort of content it is receiving. Most of the time, this
 148     will look like:</p>
 149
 150     <div class="example"><p><code>Content-type: text/html</code></p></div>
 151
 152     <p>Secondly, your output needs to be in HTML, or some other
 153     format that a browser will be able to display. Most of the
 154     time, this will be HTML, but occasionally you might write a CGI
 155     program that outputs a gif image, or other non-HTML
 156     content.</p>
 157
 158     <p>Apart from those two things, writing a CGI program will look
 159     a lot like any other program that you might write.</p>
 160
 161     <h3><a name="firstcgi" id="firstcgi">Your first CGI program</a></h3>
 162
 163
 164       <p>The following is an example CGI program that prints one
 165       line to your browser. Type in the following, save it to a
 166       file called <code>first.pl</code>, and put it in your
 167       <code>cgi-bin</code> directory.</p>
 168
 169       <div class="example"><p><code>#!/usr/bin/perl<br />
 170       print "Content-type: text/html\n\n";<br />
 171       print "Hello, World.";
 172       </code></p></div>
 173
 174       <p>Even if you are not familiar with Perl, you should be able
 175       to see what is happening here. The first line tells Apache
 176       (or whatever shell you happen to be running under) that this
 177       program can be executed by feeding the file to the
 178       interpreter found at the location <code>/usr/bin/perl</code>.
 179       The second line prints the content-type declaration we
 180       talked about, followed by two carriage-return newline pairs.
 181       This puts a blank line after the header, to indicate the end
 182       of the HTTP headers, and the beginning of the body. The third
 183       line prints the string ``Hello, World.'' And that's the end
 184       of it.</p>
 185
 186       <p>If you open your favorite browser and tell it to get the
 187       address</p>
 188
 189       <div class="example"><p><code>http://www.example.com/cgi-bin/first.pl</code></p></div>
 190
 191       <p>or wherever you put your file, you will see the one line
 192       <code>Hello, World.</code>
 193
 194       appear in your browser window. It's not very exciting, but
 195       once you get that working, you'll have a good chance of
 196       getting just about anything working.</p>
 197
 198   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="troubleshoot" id="troubleshoot">But it's still not working!</a></h2>
 199
 200
 201     <p>There are four basic things that you may see in your browser
 202     when you try to access your CGI program from the web:</p>
 203
 204     <dl>
 205       <dt>The output of your CGI program</dt>
 206
 207       <dd>Great! That means everything worked fine.
 208       </dd>
 209
 210       <dt>The source code of your CGI program or a "POST Method Not
 211       Allowed" message</dt>
 212
 213       <dd>That means that you have not properly configured Apache
 214       to process your CGI program. Reread the section on
 215       <a href="#configuringapachetopermitcgi">configuring
 216       Apache</a>
 217
 218       and try to find what you missed.
 219       </dd>
 220
 221       <dt>A message starting with "Forbidden"</dt>
 222
 223       <dd>That means that there is a permissions problem. Check the
 224
 225       <a href="#errorlogs">Apache error log</a>
 226
 227       and the section below on
 228       <a href="#permissions">file permissions</a>.
 229
 230       <br />
 231       </dd>
 232
 233       <dt>A message saying "Internal Server Error"</dt>
 234
 235       <dd>If you check the
 236       <a href="#errorlogs">Apache error log</a>, you will probably
 237       find that it says "Premature end of
 238       script headers", possibly along with an error message
 239       generated by your CGI program. In this case, you will want to
 240       check each of the below sections to see what might be
 241       preventing your CGI program from emitting the proper HTTP
 242       headers.</dd>
 243     </dl>
 244
 245     <h3><a name="permissions" id="permissions">File permissions</a></h3>
 246
 247
 248       <p>Remember that the server does not run as you. That is,
 249       when the server starts up, it is running with the permissions
 250       of an unprivileged user - usually ``nobody'', or ``www'' -
 251       and so it will need extra permissions to execute files that
 252       are owned by you. Usually, the way to give a file sufficient
 253       permissions to be executed by ``nobody'' is to give everyone
 254       execute permission on the file:</p>
 255
 256       <div class="example"><p><code>chmod a+x first.pl</code></p></div>
 257
 258       <p>Also, if your program reads from, or writes to, any other
 259       files, those files will need to have the correct permissions
 260       to permit this.</p>
 261
 262       <p>The exception to this is when the server is configured to
 263       use <a href="../suexec.html">suexec</a>.
 264
 265       This program allows CGI programs to be run under different
 266       user permissions, depending on which virtual host or user
 267       home directory they are located in. Suexec has very strict
 268       permission checking, and any failure in that checking will
 269       result in your CGI programs failing with an "Internal Server
 270       Error". In this case, you will need to check the suexec log
 271       file to see what specific security check is failing.</p>
 272
 273
 274     <h3><a name="pathinformation" id="pathinformation">Path information</a></h3>
 275
 276
 277       <p>When you run a program from your command line, you have
 278       certain information that is passed to the shell without you
 279       thinking about it. For example, you have a path, which tells
 280       the shell where it can look for files that you reference.</p>
 281
 282       <p>When a program runs through the web server as a CGI
 283       program, it does not have that path. Any programs that you
 284       invoke in your CGI program (like 'sendmail', for example)
 285       will need to be specified by a full path, so that the shell
 286       can find them when it attempts to execute your CGI
 287       program.</p>
 288
 289       <p>A common manifestation of this is the path to the script
 290       interpreter (often <code>perl</code>) indicated in the first
 291       line of your CGI program, which will look something like:</p>
 292
 293       <div class="example"><p><code>#!/usr/bin/perl</code></p></div>
 294
 295       <p>Make sure that this is in fact the path to the
 296       interpreter.</p>
 297
 298
 299     <h3><a name="syntaxerrors" id="syntaxerrors">Syntax errors</a></h3>
 300
 301
 302       <p>Most of the time when a CGI program fails, it's because of
 303       a problem with the program itself. This is particularly true
 304       once you get the hang of this CGI stuff, and no longer make
 305       the above two mistakes. Always attempt to run your program
 306       from the command line before you test if via a browser. This
 307       will eliminate most of your problems.</p>
 308
 309
 310     <h3><a name="errorlogs" id="errorlogs">Error logs</a></h3>
 311
 312
 313       <p>The error logs are your friend. Anything that goes wrong
 314       generates message in the error log. You should always look
 315       there first. If the place where you are hosting your web site
 316       does not permit you access to the error log, you should
 317       probably host your site somewhere else. Learn to read the
 318       error logs, and you'll find that almost all of your problems
 319       are quickly identified, and quickly solved.</p>
 320
 321   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="behindscenes" id="behindscenes">What's going on behind the scenes?</a></h2>
 322
 323
 324     <p>As you become more advanced in CGI programming, it will
 325     become useful to understand more about what's happening behind
 326     the scenes. Specifically, how the browser and server
 327     communicate with one another. Because although it's all very
 328     well to write a program that prints ``Hello, World.'', it's not
 329     particularly useful.</p>
 330
 331     <h3><a name="env" id="env">Environment variables</a></h3>
 332
 333
 334       <p>Environment variables are values that float around you as
 335       you use your computer. They are useful things like your path
 336       (where the computer searches for a the actual file
 337       implementing a command when you type it), your username, your
 338       terminal type, and so on. For a full list of your normal,
 339       every day environment variables, type
 340       <code>env</code> at a command prompt.</p>
 341
 342       <p>During the CGI transaction, the server and the browser
 343       also set environment variables, so that they can communicate
 344       with one another. These are things like the browser type
 345       (Netscape, IE, Lynx), the server type (Apache, IIS, WebSite),
 346       the name of the CGI program that is being run, and so on.</p>
 347
 348       <p>These variables are available to the CGI programmer, and
 349       are half of the story of the client-server communication. The
 350       complete list of required variables is at
 351       <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html">
 352       http://hoohoo.ncsa.uiuc.edu/cgi/env.html</a>
 353       </p>
 354
 355       <p>This simple Perl CGI program will display all of the
 356       environment variables that are being passed around. Two
 357       similar programs are included in the
 358       <code>cgi-bin</code>
 359
 360       directory of the Apache distribution. Note that some
 361       variables are required, while others are optional, so you may
 362       see some variables listed that were not in the official list.
 363       In addition, Apache provides many different ways for you to
 364       <a href="../env.html">add your own environment variables</a>
 365
 366       to the basic ones provided by default.</p>
 367
 368       <div class="example"><p><code>
 369       #!/usr/bin/perl<br />
 370       print "Content-type: text/html\n\n";<br />
 371       foreach $key (keys %ENV) {<br />
 372         print "$key --&gt; $ENV{$key}&lt;br&gt;";<br />
 373       }</code></p></div>
 374
 375
 376     <h3><a name="stdin" id="stdin">STDIN and STDOUT</a></h3>
 377
 378
 379       <p>Other communication between the server and the client
 380       happens over standard input (<code>STDIN</code>) and standard
 381       output (<code>STDOUT</code>). In normal everyday context,
 382       <code>STDIN</code> means the keyboard, or a file that a
 383       program is given to act on, and <code>STDOUT</code>
 384       usually means the console or screen.</p>
 385
 386       <p>When you <code>POST</code> a web form to a CGI program,
 387       the data in that form is bundled up into a special format
 388       and gets delivered to your CGI program over <code>STDIN</code>.
 389       The program then can process that data as though it was
 390       coming in from the keyboard, or from a file</p>
 391
 392       <p>The ``special format'' is very simple. A field name and
 393       its value are joined together with an equals (=) sign, and
 394       pairs of values are joined together with an ampersand
 395       (&amp;). Inconvenient characters like spaces, ampersands, and
 396       equals signs, are converted into their hex equivalent so that
 397       they don't gum up the works. The whole data string might look
 398       something like:</p>
 399
 400       <div class="example"><p><code>
 401       name=Rich%20Bowen&amp;city=Lexington&amp;state=KY&amp;sidekick=Squirrel%20Monkey
 402       </code></p></div>
 403
 404       <p>You'll sometimes also see this type of string appended to
 405       the a URL. When that is done, the server puts that string
 406       into the environment variable called
 407       <code>QUERY_STRING</code>. That's called a <code>GET</code>
 408       request. Your HTML form specifies whether a <code>GET</code>
 409       or a <code>POST</code> is used to deliver the data, by setting the
 410       <code>METHOD</code> attribute in the <code>FORM</code> tag.</p>
 411
 412       <p>Your program is then responsible for splitting that string
 413       up into useful information. Fortunately, there are libraries
 414       and modules available to help you process this data, as well
 415       as handle other of the aspects of your CGI program.</p>
 416
 417   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="libraries" id="libraries">CGI modules/libraries</a></h2>
 418
 419
 420     <p>When you write CGI programs, you should consider using a
 421     code library, or module, to do most of the grunt work for you.
 422     This leads to fewer errors, and faster development.</p>
 423
 424     <p>If you're writing CGI programs in Perl, modules are
 425     available on <a href="http://www.cpan.org/">CPAN</a>. The most
 426     popular module for this purpose is CGI.pm. You might
 427     also consider CGI::Lite, which implements a minimal set of
 428     functionality, which is all you need in most programs.</p>
 429
 430     <p>If you're writing CGI programs in C, there are a variety of
 431     options. One of these is the CGIC library, from
 432     <a href="http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</a>
 433     </p>
 434   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="moreinfo" id="moreinfo">For more information</a></h2>
 435
 436
 437     <p>There are a large number of CGI resources on the web. You
 438     can discuss CGI problems with other users on the Usenet group
 439     comp.infosystems.www.authoring.cgi. And the -servers mailing
 440     list from the HTML Writers Guild is a great source of answers
 441     to your questions. You can find out more at
 442     <a href="http://www.hwg.org/lists/hwg-servers/">
 443     http://www.hwg.org/lists/hwg-servers/</a>
 444     </p>
 445
 446     <p>And, of course, you should probably read the CGI
 447     specification, which has all the details on the operation of
 448     CGI programs. You can find the original version at the
 449     <a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">
 450     NCSA</a>
 451
 452     and there is an updated draft at the
 453     <a href="http://web.golux.com/coar/cgi/">Common Gateway
 454     Interface RFC project</a>.</p>
 455
 456     <p>When you post a question about a CGI problem that you're
 457     having, whether to a mailing list, or to a newsgroup, make sure
 458     you provide enough information about what happened, what you
 459     expected to happen, and how what actually happened was
 460     different, what server you're running, what language your CGI
 461     program was in, and, if possible, the offending code. This will
 462     make finding your problem much simpler.</p>
 463
 464     <p>Note that questions about CGI problems should <strong>never</strong>
 465     be posted to the Apache bug database unless you are sure you
 466     have found a problem in the Apache source code.</p>
 467   </div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>