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