diff options
| -rw-r--r-- | docs/manual/howto/cgi.html | 499 | ||||
| -rw-r--r-- | docs/manual/howto/cgi.html.en | 499 | ||||
| -rw-r--r-- | docs/manual/howto/footer.html | 8 | ||||
| -rw-r--r-- | docs/manual/howto/header.html | 6 | ||||
| -rw-r--r-- | docs/manual/howto/ssi.html | 519 | ||||
| -rw-r--r-- | docs/manual/howto/ssi.html.en | 519 |
6 files changed, 2050 insertions, 0 deletions
diff --git a/docs/manual/howto/cgi.html b/docs/manual/howto/cgi.html new file mode 100644 index 0000000000..fadbceb41c --- /dev/null +++ b/docs/manual/howto/cgi.html @@ -0,0 +1,499 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Apache Tutorial: Dynamic Content with CGI</title> +<link rev="made" href="mailto:rbowen@rcbowen.com"> +</head> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080" +alink="#FF0000"> +<!--#include virtual="header.html" --> +<h1 align="CENTER">Dynamic Content with CGI</h1> + +<a name="__index__"></a> <!-- INDEX BEGIN --> + + +<ul> +<li><a href="#dynamiccontentwithcgi">Dynamic Content with +CGI</a></li> + +<li><a href="#configuringapachetopermitcgi">Configuring Apache to +permit CGI</a> + +<ul> +<li><a href="#scriptalias">ScriptAlias</a></li> + +<li><a href="#cgioutsideofscriptaliasdirectories">CGI outside of +ScriptAlias directories</a> + +<ul> +<li><a href="#explicitlyusingoptionstopermitcgiexecution">Explicitly using +Options to permit CGI execution</a></li> + +<li><a href="#htaccessfiles">.htaccess files</a></li> +</ul> +</li> +</ul> +</li> + +<li><a href="#writingacgiprogram">Writing a CGI program</a> + +<ul> +<li><a href="#yourfirstcgiprogram">Your first CGI program</a></li> +</ul> +</li> + +<li><a href="#butitsstillnotworking">But it's still not +working!</a> + +<ul> +<li><a href="#filepermissions">File permissions</a></li> + +<li><a href="#pathinformation">Path information</a></li> + +<li><a href="#syntaxerrors">Syntax errors</a></li> + +<li><a href="#errorlogs">Error logs</a></li> +</ul> +</li> + +<li><a href="#whatsgoingonbehindthescenes">What's going on behind +the scenes?</a> + +<ul> +<li><a href="#environmentvariables">Environment variables</a></li> + +<li><a href="#stdinandstdout">STDIN and STDOUT</a></li> +</ul> +</li> + +<li><a href="#cgimoduleslibraries">CGI modules/libraries</a></li> + +<li><a href="#formoreinformation">For more information</a></li> +</ul> + +<!-- INDEX END --> +<hr> +<h2><a name="dynamiccontentwithcgi">Dynamic Content with +CGI</a></h2> + +<table border="1"> +<tr><td valign="top"> +<strong>Related Modules</strong><br><br> + +<a href="../mod/mod_alias.html">mod_alias</a><br> +<a href="../mod/mod_cgi.html">mod_cgi</a><br> + +</td><td valign="top"> +<strong>Related Directives</strong><br><br> + +<a href="../mod/mod_mime.html#addhandler">AddHandler</a><br> +<A HREF="../mod/core.html#options">Options</a><br> +<a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a><br> + +</td></tr></table> + +<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 up CGI on your Apache web +server, and getting started writing CGI programs.</p> + +<hr> +<h2><a name="configuringapachetopermitcgi">Configuring Apache to +permit CGI</a></h2> + +<p>In order to get your CGI programs to work properly, you'll need to +have Apache configured to permit CGI execution. There are several ways +to do this.</p> + +<h3><a name="scriptalias">ScriptAlias</a></h3> + +<p>The <code>ScriptAlias</code> directive tells Apache that a +particular directory is set aside for CGI programs. Apache will assume +that every file in this directory is a CGI program, and will attempt to +execute it, when that particular resource is requested by a client.</p> + +<p>The <code>ScriptAlias</code> directive looks like:</p> + +<pre> + ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/ +</pre> + +<p>The example shown is from your default <code>httpd.conf</code> +configuration file, if you installed Apache in the default location. +The <code>ScriptAlias</code> directive is much like the +<code>Alias</code> directive, which defines a URL prefix that is to +mapped to a particular directory. <code>Alias</code> and +<code>ScriptAlias</code> are usually used for directories that are +outside of the <code>DocumentRoot</code> directory. The difference +between <code>Alias</code> and <code>ScriptAlias</code> is that +<code>ScriptAlias</code> has the added meaning that everything under +that URL prefix will be considered a CGI program. So, the example above +tells Apache that any request for a resource beginning with +<code>/cgi-bin/</code> should be served from the directory +<code>/usr/local/apache/cgi-bin/</code>, and should be treated as a CGI +program.</p> + +<p>For example, if the URL +<code>http://dev.rcbowen.com/cgi-bin/test.pl</code> is requested, +Apache will attempt to execute the file +<code>/usr/local/apache/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 way, or Apache will return an error message.</p> + +<h3><a name="cgioutsideofscriptaliasdirectories">CGI outside of +ScriptAlias directories</a></h3> + +<p>CGI programs are often restricted to <code>ScriptAlias</code>'ed +directories for security reasons. In this way, administrators can +tightly control who is allowed to 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 <code>UserDir</code> 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 run CGI +programs elsewhere.</p> + +<h3><a name="explicitlyusingoptionstopermitcgiexecution">Explicitly using +Options to permit CGI execution</a></h3> + +<p>You could explicitly use the <code>Options</code> directive, inside +your main server configuration file, to specify that CGI execution was +permitted in a particular directory:</p> + +<pre> + <Directory /usr/local/apache/htdocs/somedir> + Options +ExecCGI + </Directory> +</pre> + +<p>The above directive tells Apache to permit the execution of CGI +files. You will also need to tell the server what files are CGI files. +The following <code>AddHandler</code> directive tells the server +to treat all files with the <code>cgi</code> or <code>pl</code> +extension as CGI programs:</p> + +<pre> + AddHandler cgi-script cgi pl +</pre> + +<h3><a name="htaccessfiles">.htaccess files</a></h3> + +<p>A <code>.htaccess</code> file is a way to set configuration +directives on a per-directory basis. When Apache serves a resource, it +looks in the directory from which it is serving a file for a file +called <code>.htaccess</code>, and, if it finds it, it will apply +directives found therein. <code>.htaccess</code> files can be permitted +with the <code>AllowOverride</code> directive, which specifies what +types of directives can appear in these files, or if they are not +allowed at all. To permit the directive we will need for this purpose, +the following configuration will be needed in your main server +configuration:</p> + +<pre> + AllowOverride Options +</pre> + +<p>In the <code>.htaccess</code> file, you'll need the following +directive:</p> + +<pre> + Options +ExecCGI +</pre> + +<p>which tells Apache that execution of CGI programs is permitted in +this directory.</p> + +<hr> +<h2><a name="writingacgiprogram">Writing a CGI program</a></h2> + +<p>There are two main differences between ``regular'' programming, and +CGI programming.</p> + +<p>First, all output from your CGI program must be preceded by a +MIME-type header. This is HTTP header that tells the client what sort +of content it is receiving. Most of the time, this will look like:</p> + +<pre> + Content-type: text/html +</pre> + +<p>Secondly, your output needs to be in HTML, or some other format that +a browser will be able to display. Most of the time, this will be HTML, +but occasionally you might write a CGI program that outputs a gif +image, or other non-HTML content.</p> + +<p>Apart from those two things, writing a CGI program will look a lot +like any other program that you might write.</p> + +<h3><a name="yourfirstcgiprogram">Your first CGI program</a></h3> + +<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 <code>cgi-bin</code> +directory.</p> + +<pre> + #!/usr/bin/perl + print "Content-type: text/html\r\n\r\n"; + print "Hello, World."; +</pre> + +<p>Even if you are not familiar with Perl, you should be able to see +what is happening here. The first line tells Apache (or whatever shell +you happen to be running under) that this program can be executed by +feeding the file to the interpreter found at the location +<code>/usr/bin/perl</code>. The second line prints the content-type +declaration we talked about, followed by two carriage-return newline +pairs. This puts a blank line after the header, to indicate the end of +the HTTP headers, and the beginning of the body. The third line prints +the string ``Hello, World.'' And that's the end of it.</p> + +<p>If you open your favorite browser and tell it to get the address</p> + +<pre> + http://www.example.com/cgi-bin/first.pl +</pre> + +<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> + +<hr> +<h2><a name="butitsstillnotworking">But it's still not +working!</a></h2> + +<p>There are four basic things that you may see in your browser when +you try to access your CGI program from the web:</p> + +<dl> +<dt>The output of your CGI program</dt> +<dd>Great! That means everything worked fine.<br><br></dd> + +<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 <a +href="#configuringapachetopermitcgi">configuring Apache</a> and try to +find what you missed.<br><br></dd> + +<dt>A message starting with "Forbidden"</dt> <dd>That means that there +is a permissions problem. Check the <a href="#errorlogs">Apache +error log</a> and the section below on <a +href="#filepermissions">file permissions</a>.<br><br></dd> + +<dt>A message saying "Internal Server Error"</dt> <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 generated by your CGI program. In this case, you will +want to check each of the below sections to see what might be preventing +your CGI program from emitting the proper HTTP headers.</dd> +</dl> + + +<h3><a name="filepermissions">File permissions</a></h3> + +<p>Remember that the server does not run as you. That is, when the +server starts up, it is running with the permissions of an unprivileged +user - usually ``nobody'', or ``www'' - and so it will need extra +permissions to execute files that are owned by you. Usually, the way to +give a file sufficient permissions to be executed by ``nobody'' is to +give everyone execute permission on the file:</p> + +<pre> + chmod a+x first.pl +</pre> + +<p>Also, if your program reads from, or writes to, any other files, +those files will need to have the correct permissions to permit +this.</p> + +<p>The exception to this is when the server is configured to use <a +href="../suexec.html">suexec</a>. This program allows CGI programs to +be run under different user permissions, depending on which virtual +host or user home directory they are located in. Suexec has very +strict permission checking, and any failure in that checking will +result in your CGI programs failing with an "Internal Server Error". +In this case, you will need to check the suexec log file to see what +specific security check is failing.</p> + +<h3><a name="pathinformation">Path information</a></h3> + +<p>When you run a program from your command line, you have certain +information that is passed to the shell without you thinking about it. +For example, you have a path, which tells the shell where it can look +for files that you reference.</p> + +<p>When a program runs through the web server as a CGI program, it does +not have that path. Any programs that you invoke in your CGI program +(like 'sendmail', for example) will need to be specified by a full +path, so that the shell can find them when it attempts to execute your +CGI program.</p> + +<p>A common manifestation of this is the path to the script interpreter +(often <code>perl</code>) indicated in the first line of your CGI +program, which will look something like:</p> + +<pre> + #!/usr/bin/perl +</pre> + +<p>Make sure that this is in fact the path to the interpreter.</p> + +<h3><a name="syntaxerrors">Syntax errors</a></h3> + +<p>Most of the time when a CGI program fails, it's because of a problem +with the program itself. This is particularly true once you get the +hang of this CGI stuff, and no longer make the above two mistakes. +Always attempt to run your program from the command line before you +test if via a browser. This will eliminate most of your problems.</p> + +<h3><a name="errorlogs">Error logs</a></h3> + +<p>The error logs are your friend. Anything that goes wrong generates +message in the error log. You should always look there first. If the +place where you are hosting your web site does not permit you access to +the error log, you should probably host your site somewhere else. Learn +to read the error logs, and you'll find that almost all of your +problems are quickly identified, and quickly solved.</p> + +<hr> +<h2><a name="whatsgoingonbehindthescenes">What's going on behind +the scenes?</a></h2> + +<p>As you become more advanced in CGI programming, it will become +useful to understand more about what's happening behind the scenes. +Specifically, how the browser and server communicate with one another. +Because although it's all very well to write a program that prints +``Hello, World.'', it's not particularly useful.</p> + +<h3><a name="environmentvariables">Environment variables</a></h3> + +<p>Environment variables are values that float around you as you use +your computer. They are useful things like your path (where the +computer searches for a 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 <code>env</code> +at a command prompt.</p> + +<p>During the CGI transaction, the server and the browser also set +environment variables, so that they can communicate with one another. +These are things like the browser type (Netscape, IE, Lynx), the server +type (Apache, IIS, WebSite), the name of the CGI program that is being +run, and so on.</p> + +<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> + +<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 <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 <a href="../env.html">add your own environment variables</a> to +the basic ones provided by default.</p> + +<pre> + #!/usr/bin/perl + print "Content-type: text/html\n\n"; + foreach $key (keys %ENV) { + print "$key --> $ENV{$key}<br>"; + } +</pre> + +<h3><a name="stdinandstdout">STDIN and STDOUT</a></h3> + +<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 program is given to act on, and +<code>STDOUT</code> 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 and gets delivered to +your CGI program over <code>STDIN</code>. The program then can process +that data as though it was coming in from the keyboard, or from a +file</p> + +<p>The ``special format'' is very simple. A field name and its value +are joined together with an equals (=) sign, and pairs of values are +joined together with an ampersand (&). Inconvenient characters like +spaces, ampersands, and equals signs, are converted into their hex +equivalent so that they don't gum up the works. The whole data string +might look something like:</p> + +<pre> + name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey +</pre> + +<p>You'll sometimes also see this type of string appended to the a URL. +When that is done, the server puts that string 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 <code>METHOD</code> attribute in the <code>FORM</code> +tag.</p> + +<p>Your program is then responsible for splitting that string up into +useful information. Fortunately, there are libraries and modules +available to help you process this data, as well as handle other of the +aspects of your CGI program.</p> + +<hr> +<h2><a name="cgimoduleslibraries">CGI modules/libraries</a></h2> + +<p>When you write CGI programs, you should consider using a code +library, or module, to do most of the grunt work for you. This leads to +fewer errors, and faster development.</p> + +<p>If you're writing CGI programs in Perl, modules are available on <a +href="http://www.cpan.org/">CPAN</a>. The most popular module for this +purpose is CGI.pm. You might also consider CGI::Lite, which implements +a minimal 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 CGIC library, from <a href= +"http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</a></p> + +<hr> +<h2><a name="formoreinformation">For more information</a></h2> + +<p>There are a large number of CGI resources on the web. You can +discuss CGI problems with other users on the Usenet group +comp.infosystems.www.authoring.cgi. 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>When you post a question about a CGI problem that you're having, +whether to a mailing list, or to a newsgroup, make sure you provide +enough information about what happened, what you expected to happen, +and how what actually happened was different, what server you're +running, what language your CGI program was in, and, if possible, the +offending code. This will make finding your problem much simpler.</p> + +<p>Note that questions about CGI problems should <strong>never</strong> +be posted to the Apache bug database unless you are sure you have found +a problem in the Apache source code.</p> + +<!--#include virtual="footer.html" --> + +</body> +</html> + diff --git a/docs/manual/howto/cgi.html.en b/docs/manual/howto/cgi.html.en new file mode 100644 index 0000000000..fadbceb41c --- /dev/null +++ b/docs/manual/howto/cgi.html.en @@ -0,0 +1,499 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Apache Tutorial: Dynamic Content with CGI</title> +<link rev="made" href="mailto:rbowen@rcbowen.com"> +</head> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080" +alink="#FF0000"> +<!--#include virtual="header.html" --> +<h1 align="CENTER">Dynamic Content with CGI</h1> + +<a name="__index__"></a> <!-- INDEX BEGIN --> + + +<ul> +<li><a href="#dynamiccontentwithcgi">Dynamic Content with +CGI</a></li> + +<li><a href="#configuringapachetopermitcgi">Configuring Apache to +permit CGI</a> + +<ul> +<li><a href="#scriptalias">ScriptAlias</a></li> + +<li><a href="#cgioutsideofscriptaliasdirectories">CGI outside of +ScriptAlias directories</a> + +<ul> +<li><a href="#explicitlyusingoptionstopermitcgiexecution">Explicitly using +Options to permit CGI execution</a></li> + +<li><a href="#htaccessfiles">.htaccess files</a></li> +</ul> +</li> +</ul> +</li> + +<li><a href="#writingacgiprogram">Writing a CGI program</a> + +<ul> +<li><a href="#yourfirstcgiprogram">Your first CGI program</a></li> +</ul> +</li> + +<li><a href="#butitsstillnotworking">But it's still not +working!</a> + +<ul> +<li><a href="#filepermissions">File permissions</a></li> + +<li><a href="#pathinformation">Path information</a></li> + +<li><a href="#syntaxerrors">Syntax errors</a></li> + +<li><a href="#errorlogs">Error logs</a></li> +</ul> +</li> + +<li><a href="#whatsgoingonbehindthescenes">What's going on behind +the scenes?</a> + +<ul> +<li><a href="#environmentvariables">Environment variables</a></li> + +<li><a href="#stdinandstdout">STDIN and STDOUT</a></li> +</ul> +</li> + +<li><a href="#cgimoduleslibraries">CGI modules/libraries</a></li> + +<li><a href="#formoreinformation">For more information</a></li> +</ul> + +<!-- INDEX END --> +<hr> +<h2><a name="dynamiccontentwithcgi">Dynamic Content with +CGI</a></h2> + +<table border="1"> +<tr><td valign="top"> +<strong>Related Modules</strong><br><br> + +<a href="../mod/mod_alias.html">mod_alias</a><br> +<a href="../mod/mod_cgi.html">mod_cgi</a><br> + +</td><td valign="top"> +<strong>Related Directives</strong><br><br> + +<a href="../mod/mod_mime.html#addhandler">AddHandler</a><br> +<A HREF="../mod/core.html#options">Options</a><br> +<a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a><br> + +</td></tr></table> + +<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 up CGI on your Apache web +server, and getting started writing CGI programs.</p> + +<hr> +<h2><a name="configuringapachetopermitcgi">Configuring Apache to +permit CGI</a></h2> + +<p>In order to get your CGI programs to work properly, you'll need to +have Apache configured to permit CGI execution. There are several ways +to do this.</p> + +<h3><a name="scriptalias">ScriptAlias</a></h3> + +<p>The <code>ScriptAlias</code> directive tells Apache that a +particular directory is set aside for CGI programs. Apache will assume +that every file in this directory is a CGI program, and will attempt to +execute it, when that particular resource is requested by a client.</p> + +<p>The <code>ScriptAlias</code> directive looks like:</p> + +<pre> + ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/ +</pre> + +<p>The example shown is from your default <code>httpd.conf</code> +configuration file, if you installed Apache in the default location. +The <code>ScriptAlias</code> directive is much like the +<code>Alias</code> directive, which defines a URL prefix that is to +mapped to a particular directory. <code>Alias</code> and +<code>ScriptAlias</code> are usually used for directories that are +outside of the <code>DocumentRoot</code> directory. The difference +between <code>Alias</code> and <code>ScriptAlias</code> is that +<code>ScriptAlias</code> has the added meaning that everything under +that URL prefix will be considered a CGI program. So, the example above +tells Apache that any request for a resource beginning with +<code>/cgi-bin/</code> should be served from the directory +<code>/usr/local/apache/cgi-bin/</code>, and should be treated as a CGI +program.</p> + +<p>For example, if the URL +<code>http://dev.rcbowen.com/cgi-bin/test.pl</code> is requested, +Apache will attempt to execute the file +<code>/usr/local/apache/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 way, or Apache will return an error message.</p> + +<h3><a name="cgioutsideofscriptaliasdirectories">CGI outside of +ScriptAlias directories</a></h3> + +<p>CGI programs are often restricted to <code>ScriptAlias</code>'ed +directories for security reasons. In this way, administrators can +tightly control who is allowed to 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 <code>UserDir</code> 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 run CGI +programs elsewhere.</p> + +<h3><a name="explicitlyusingoptionstopermitcgiexecution">Explicitly using +Options to permit CGI execution</a></h3> + +<p>You could explicitly use the <code>Options</code> directive, inside +your main server configuration file, to specify that CGI execution was +permitted in a particular directory:</p> + +<pre> + <Directory /usr/local/apache/htdocs/somedir> + Options +ExecCGI + </Directory> +</pre> + +<p>The above directive tells Apache to permit the execution of CGI +files. You will also need to tell the server what files are CGI files. +The following <code>AddHandler</code> directive tells the server +to treat all files with the <code>cgi</code> or <code>pl</code> +extension as CGI programs:</p> + +<pre> + AddHandler cgi-script cgi pl +</pre> + +<h3><a name="htaccessfiles">.htaccess files</a></h3> + +<p>A <code>.htaccess</code> file is a way to set configuration +directives on a per-directory basis. When Apache serves a resource, it +looks in the directory from which it is serving a file for a file +called <code>.htaccess</code>, and, if it finds it, it will apply +directives found therein. <code>.htaccess</code> files can be permitted +with the <code>AllowOverride</code> directive, which specifies what +types of directives can appear in these files, or if they are not +allowed at all. To permit the directive we will need for this purpose, +the following configuration will be needed in your main server +configuration:</p> + +<pre> + AllowOverride Options +</pre> + +<p>In the <code>.htaccess</code> file, you'll need the following +directive:</p> + +<pre> + Options +ExecCGI +</pre> + +<p>which tells Apache that execution of CGI programs is permitted in +this directory.</p> + +<hr> +<h2><a name="writingacgiprogram">Writing a CGI program</a></h2> + +<p>There are two main differences between ``regular'' programming, and +CGI programming.</p> + +<p>First, all output from your CGI program must be preceded by a +MIME-type header. This is HTTP header that tells the client what sort +of content it is receiving. Most of the time, this will look like:</p> + +<pre> + Content-type: text/html +</pre> + +<p>Secondly, your output needs to be in HTML, or some other format that +a browser will be able to display. Most of the time, this will be HTML, +but occasionally you might write a CGI program that outputs a gif +image, or other non-HTML content.</p> + +<p>Apart from those two things, writing a CGI program will look a lot +like any other program that you might write.</p> + +<h3><a name="yourfirstcgiprogram">Your first CGI program</a></h3> + +<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 <code>cgi-bin</code> +directory.</p> + +<pre> + #!/usr/bin/perl + print "Content-type: text/html\r\n\r\n"; + print "Hello, World."; +</pre> + +<p>Even if you are not familiar with Perl, you should be able to see +what is happening here. The first line tells Apache (or whatever shell +you happen to be running under) that this program can be executed by +feeding the file to the interpreter found at the location +<code>/usr/bin/perl</code>. The second line prints the content-type +declaration we talked about, followed by two carriage-return newline +pairs. This puts a blank line after the header, to indicate the end of +the HTTP headers, and the beginning of the body. The third line prints +the string ``Hello, World.'' And that's the end of it.</p> + +<p>If you open your favorite browser and tell it to get the address</p> + +<pre> + http://www.example.com/cgi-bin/first.pl +</pre> + +<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> + +<hr> +<h2><a name="butitsstillnotworking">But it's still not +working!</a></h2> + +<p>There are four basic things that you may see in your browser when +you try to access your CGI program from the web:</p> + +<dl> +<dt>The output of your CGI program</dt> +<dd>Great! That means everything worked fine.<br><br></dd> + +<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 <a +href="#configuringapachetopermitcgi">configuring Apache</a> and try to +find what you missed.<br><br></dd> + +<dt>A message starting with "Forbidden"</dt> <dd>That means that there +is a permissions problem. Check the <a href="#errorlogs">Apache +error log</a> and the section below on <a +href="#filepermissions">file permissions</a>.<br><br></dd> + +<dt>A message saying "Internal Server Error"</dt> <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 generated by your CGI program. In this case, you will +want to check each of the below sections to see what might be preventing +your CGI program from emitting the proper HTTP headers.</dd> +</dl> + + +<h3><a name="filepermissions">File permissions</a></h3> + +<p>Remember that the server does not run as you. That is, when the +server starts up, it is running with the permissions of an unprivileged +user - usually ``nobody'', or ``www'' - and so it will need extra +permissions to execute files that are owned by you. Usually, the way to +give a file sufficient permissions to be executed by ``nobody'' is to +give everyone execute permission on the file:</p> + +<pre> + chmod a+x first.pl +</pre> + +<p>Also, if your program reads from, or writes to, any other files, +those files will need to have the correct permissions to permit +this.</p> + +<p>The exception to this is when the server is configured to use <a +href="../suexec.html">suexec</a>. This program allows CGI programs to +be run under different user permissions, depending on which virtual +host or user home directory they are located in. Suexec has very +strict permission checking, and any failure in that checking will +result in your CGI programs failing with an "Internal Server Error". +In this case, you will need to check the suexec log file to see what +specific security check is failing.</p> + +<h3><a name="pathinformation">Path information</a></h3> + +<p>When you run a program from your command line, you have certain +information that is passed to the shell without you thinking about it. +For example, you have a path, which tells the shell where it can look +for files that you reference.</p> + +<p>When a program runs through the web server as a CGI program, it does +not have that path. Any programs that you invoke in your CGI program +(like 'sendmail', for example) will need to be specified by a full +path, so that the shell can find them when it attempts to execute your +CGI program.</p> + +<p>A common manifestation of this is the path to the script interpreter +(often <code>perl</code>) indicated in the first line of your CGI +program, which will look something like:</p> + +<pre> + #!/usr/bin/perl +</pre> + +<p>Make sure that this is in fact the path to the interpreter.</p> + +<h3><a name="syntaxerrors">Syntax errors</a></h3> + +<p>Most of the time when a CGI program fails, it's because of a problem +with the program itself. This is particularly true once you get the +hang of this CGI stuff, and no longer make the above two mistakes. +Always attempt to run your program from the command line before you +test if via a browser. This will eliminate most of your problems.</p> + +<h3><a name="errorlogs">Error logs</a></h3> + +<p>The error logs are your friend. Anything that goes wrong generates +message in the error log. You should always look there first. If the +place where you are hosting your web site does not permit you access to +the error log, you should probably host your site somewhere else. Learn +to read the error logs, and you'll find that almost all of your +problems are quickly identified, and quickly solved.</p> + +<hr> +<h2><a name="whatsgoingonbehindthescenes">What's going on behind +the scenes?</a></h2> + +<p>As you become more advanced in CGI programming, it will become +useful to understand more about what's happening behind the scenes. +Specifically, how the browser and server communicate with one another. +Because although it's all very well to write a program that prints +``Hello, World.'', it's not particularly useful.</p> + +<h3><a name="environmentvariables">Environment variables</a></h3> + +<p>Environment variables are values that float around you as you use +your computer. They are useful things like your path (where the +computer searches for a 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 <code>env</code> +at a command prompt.</p> + +<p>During the CGI transaction, the server and the browser also set +environment variables, so that they can communicate with one another. +These are things like the browser type (Netscape, IE, Lynx), the server +type (Apache, IIS, WebSite), the name of the CGI program that is being +run, and so on.</p> + +<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> + +<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 <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 <a href="../env.html">add your own environment variables</a> to +the basic ones provided by default.</p> + +<pre> + #!/usr/bin/perl + print "Content-type: text/html\n\n"; + foreach $key (keys %ENV) { + print "$key --> $ENV{$key}<br>"; + } +</pre> + +<h3><a name="stdinandstdout">STDIN and STDOUT</a></h3> + +<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 program is given to act on, and +<code>STDOUT</code> 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 and gets delivered to +your CGI program over <code>STDIN</code>. The program then can process +that data as though it was coming in from the keyboard, or from a +file</p> + +<p>The ``special format'' is very simple. A field name and its value +are joined together with an equals (=) sign, and pairs of values are +joined together with an ampersand (&). Inconvenient characters like +spaces, ampersands, and equals signs, are converted into their hex +equivalent so that they don't gum up the works. The whole data string +might look something like:</p> + +<pre> + name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey +</pre> + +<p>You'll sometimes also see this type of string appended to the a URL. +When that is done, the server puts that string 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 <code>METHOD</code> attribute in the <code>FORM</code> +tag.</p> + +<p>Your program is then responsible for splitting that string up into +useful information. Fortunately, there are libraries and modules +available to help you process this data, as well as handle other of the +aspects of your CGI program.</p> + +<hr> +<h2><a name="cgimoduleslibraries">CGI modules/libraries</a></h2> + +<p>When you write CGI programs, you should consider using a code +library, or module, to do most of the grunt work for you. This leads to +fewer errors, and faster development.</p> + +<p>If you're writing CGI programs in Perl, modules are available on <a +href="http://www.cpan.org/">CPAN</a>. The most popular module for this +purpose is CGI.pm. You might also consider CGI::Lite, which implements +a minimal 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 CGIC library, from <a href= +"http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</a></p> + +<hr> +<h2><a name="formoreinformation">For more information</a></h2> + +<p>There are a large number of CGI resources on the web. You can +discuss CGI problems with other users on the Usenet group +comp.infosystems.www.authoring.cgi. 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>When you post a question about a CGI problem that you're having, +whether to a mailing list, or to a newsgroup, make sure you provide +enough information about what happened, what you expected to happen, +and how what actually happened was different, what server you're +running, what language your CGI program was in, and, if possible, the +offending code. This will make finding your problem much simpler.</p> + +<p>Note that questions about CGI problems should <strong>never</strong> +be posted to the Apache bug database unless you are sure you have found +a problem in the Apache source code.</p> + +<!--#include virtual="footer.html" --> + +</body> +</html> + diff --git a/docs/manual/howto/footer.html b/docs/manual/howto/footer.html new file mode 100644 index 0000000000..4a0991e6fa --- /dev/null +++ b/docs/manual/howto/footer.html @@ -0,0 +1,8 @@ +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 2.0 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> diff --git a/docs/manual/howto/header.html b/docs/manual/howto/header.html new file mode 100644 index 0000000000..9bc11593a3 --- /dev/null +++ b/docs/manual/howto/header.html @@ -0,0 +1,6 @@ +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 2.0 + </H3> +</DIV> diff --git a/docs/manual/howto/ssi.html b/docs/manual/howto/ssi.html new file mode 100644 index 0000000000..0bd2a1f8bc --- /dev/null +++ b/docs/manual/howto/ssi.html @@ -0,0 +1,519 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Apache Tutorial: Introduction to Server Side Includes</title> +<link rev="made" href="mailto:rbowen@rcbowen.com"> +</head> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080" +alink="#FF0000"> +<!--#include virtual="header.html" --> +<h1 align="CENTER">Apache Tutorial: Introduction to Server Side +Includes</h1> + +<a name="__index__"></a> <!-- INDEX BEGIN --> + + +<ul> +<li><a href= +"#apachetutorial:introductiontoserversideincludes">Apache +Tutorial: Introduction to Server Side Includes</a></li> + +<li><a href="#whataressi">What are SSI?</a></li> + +<li><a href="#configuringyourservertopermitssi">Configuring your +server to permit SSI</a></li> + +<li><a href="#basicssidirectives">Basic SSI directives</a> + +<ul> + <li><a href="#today'sdate">Today's date</a></li> + + <li><a href="#modificationdateofthefile">Modification date of the +file</a></li> + + <li><a href="#includingtheresultsofacgiprogram">Including the +results of a CGI program</a></li> +</ul> +</li> + +<li><a href="#additionalexamples">Additional examples</a> + +<ul> +<li><a href="#whenwasthisdocumentmodified">When was this document +modified?</a></li> + +<li><a href="#includingastandardfooter">Including a standard +footer</a></li> + +<li><a href="#whatelsecaniconfig">What else can I config?</a></li> + +<li><a href="#executingcommands">Executing commands</a></li> +</ul> +</li> + +<li><a href="#advancedssitechniques">Advanced SSI techniques</a> + +<ul> +<li><a href="#settingvariables">Setting variables</a></li> + +<li><a href="#conditionalexpressions">Conditional expressions</a></li> +</ul> +</li> + +<li><a href="#conclusion">Conclusion</a></li> +</ul> + +<!-- INDEX END --> +<hr> +<h2><a name= +"apachetutorial:introductiontoserversideincludes">Apache +Tutorial: Introduction to Server Side Includes</a></h2> + +<table border="1"> +<tr> +<td valign="top"><strong>Related Modules</strong><br> +<br> + <a href="../mod/mod_include.html">mod_include</a><br> +<a href="../mod/mod_cgi.html">mod_cgi</a><br> +<a href="../mod/mod_expires.html">mod_expires</a><br> + </td> +<td valign="top"><strong>Related Directives</strong><br> +<br> + <a href="../mod/core.html#options">Options</a><br> +<a href="../mod/mod_include.html#xbithack">XBitHack</a><br> +<a href="../mod/mod_mime.html#addtype">AddType</a><br> +<a href="../mod/mod_mime.html#addhandler">AddHandler</a><br> +<a href= +"../mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</a><br> + + </td> +</tr> +</table> + +<p>This HOWTO first appeared in Apache Today +(http://www.apachetoday.com/) as a series of three articles. They +appear here by arrangement with ApacheToday and Internet.com.</p> + +<p>This article deals with Server Side Includes, usually called simply +SSI. In this article, I'll talk about configuring your server to permit +SSI, and introduce some basic SSI techniques for adding dynamic content +to your existing HTML pages.</p> + +<p>In the latter part of the article, we'll talk about some of the +somewhat more advanced things that can be done with SSI, such as +conditional statements in your SSI directives.</p> + +<hr> +<h2><a name="whataressi">What are SSI?</a></h2> + +<p>SSI (Server Side Includes) are directives that are placed in HTML +pages, and evaluated on the server while the pages are being served. +They let you add dynamically generated content to an existing HTML +page, without having to serve the entire page via a CGI program, or +other dynamic technology.</p> + +<p>The decision of when to use SSI, and when to have your page entirely +generated by some program, is usually a matter of how much of the page +is static, and how much needs to be recalculated every time the page is +served. SSI is a great way to add small pieces of information, such as +the current time. But if a majority of your page is being generated at +the time that it is served, you need to look for some other +solution.</p> + +<hr> +<h2><a name="configuringyourservertopermitssi">Configuring your +server to permit SSI</a></h2> + +<p>To permit SSI on your server, you must have the following directive +either in your <code>httpd.conf</code> file, or in a +<code>.htaccess</code> file:</p> + +<pre> + Options +Includes +</pre> + +<p>This tells Apache that you want to permit files to be parsed for SSI +directives.</p> + +<p>Not just any file is parsed for SSI directives. You have to tell +Apache which files should be parsed. There are two ways to do this. You +can tell Apache to parse any file with a particular file extension, +such as <code>.shtml</code>, with the following directives:</p> + +<pre> + AddType text/html .shtml + AddHandler server-parsed .shtml +</pre> + +<p>One disadvantage to this approach is that if you wanted to add SSI +directives to an existing page, you would have to change the name of +that page, and all links to that page, in order to give it a +<code>.shtml</code> extension, so that those directives would be +executed.</p> + +<p>The other method is to use the <code>XBitHack</code> directive:</p> + +<pre> + XBitHack on +</pre> + +<p><code>XBitHack</code> tells Apache to parse files for SSI directives +if they have the execute bit set. So, to add SSI directives to an +existing page, rather than having to change the file name, you would +just need to make the file executable using <code>chmod</code>.</p> + +<pre> + chmod +x pagename.html +</pre> + +<p>A brief comment about what not to do. You'll occasionally see people +recommending that you just tell Apache to parse all <code>.html</code> +files for SSI, so that you don't have to mess with <code>.shtml</code> +file names. These folks have perhaps not heard about +<code>XBitHack</code>. The thing to keep in mind is that, by doing +this, you're requiring that Apache read through every single file that +it sends out to clients, even if they don't contain any SSI directives. +This can slow things down quite a bit, and is not a good idea.</p> + +<p>Of course, on Windows, there is no such thing as an execute bit to +set, so that limits your options a little.</p> + +<p>In its default configuration, Apache does not send the last modified +date or content length HTTP headers on SSI pages, because these values are +difficult to calculate for dynamic content. This can prevent your +document from being cached, and result in slower perceived client +performance. There are two ways to solve this:</p> + +<ol> + +<li>Use the <code>XBitHack Full</code> configuration. This tells +Apache to determine the last modified date by looking only at the date +of the originally requested file, ignoring the modification date of +any included files. </li> + +<li>Use the directives provided by <a +href="../mod/mod_expires.html">mod_expires</a> to set an explicit +expiration time on your files, thereby letting browsers and proxies +know that it is acceptable to cache them. </li> + +</ol> + + +<hr> +<h2><a name="basicssidirectives">Basic SSI directives</a></h2> + +<p>SSI directives have the following syntax:</p> + +<pre> + <!--#element attribute=value attribute=value ... --> +</pre> + +<p>It is formatted like an HTML comment, so if you don't have SSI +correctly enabled, the browser will ignore it, but it will still be +visible in the HTML source. If you have SSI correctly configured, the +directive will be replaced with its results.</p> + +<p>The element can be one of a number of things, and we'll talk some +more about most of these in the next installment of this series. For +now, here are some examples of what you can do with SSI</p> + +<h3><a name="today'sdate">Today's date</a></h3> + +<pre> + <!--#echo var=DATE_LOCAL --> +</pre> + +<p>The <code>echo</code> element just spits out the value of a +variable. There are a number of standard variables, which include the +whole set of environment variables that are available to CGI programs. +Also, you can define your own variables with the <code>set</code> +element.</p> + +<p>If you don't like the format in which the date gets printed, you can +use the <code>config</code> element, with a <code>timefmt</code> +attribute, to modify that formatting.</p> + +<pre> + <!--#config timefmt="%A %B %d, %Y" --> + Today is <!--#echo var=DATE_LOCAL --> +</pre> + +<h3><a name="modificationdateofthefile">Modification date of the +file</a></h3> + +<pre> + This document last modified <!--#flastmod file="index.html" --> +</pre> + +<p>This element is also subject to <code>timefmt</code> format +configurations.</p> + +<h3><a name="includingtheresultsofacgiprogram">Including the +results of a CGI program</a></h3> + +<p>This is one of the more common uses of SSI - to output the results +of a CGI program, such as everybody's favorite, a ``hit counter.''</p> + +<pre> + <!--#include virtual="/cgi-bin/counter.pl" --> +</pre> + +<hr> +<h2><a name="additionalexamples">Additional examples</a></h2> + +<p>Following are some specific examples of things you can do in your +HTML documents with SSI.</p> + +<hr> +<h2><a name="whenwasthisdocumentmodified">When was this document +modified?</a></h2> + +<p>Earlier, we mentioned that you could use SSI to inform the user when +the document was most recently modified. However, the actual method for +doing that was left somewhat in question. The following code, placed in +your HTML document, will put such a time stamp on your page. Of course, +you will have to have SSI correctly enabled, as discussed above.</p> + +<pre> + <!--#config timefmt="%A %B %d, %Y" --> + This file last modified <!--#flastmod file="ssi.shtml" --> +</pre> + +<p>Of course, you will need to replace the <code>ssi.shtml</code> with +the actual name of the file that you're referring to. This can be +inconvenient if you're just looking for a generic piece of code that +you can paste into any file, so you probably want to use the +<code>LAST_MODIFIED</code> variable instead:</p> + +<pre> + <!--#config timefmt="%D" --> + This file last modified <!--#echo var="LAST_MODIFIED" --> +</pre> + +<p>For more details on the <code>timefmt</code> format, go to your +favorite search site and look for <code>ctime</code>. The syntax is the +same.</p> + +<hr> +<h2><a name="includingastandardfooter">Including a standard +footer</a></h2> + +<p>If you are managing any site that is more than a few pages, you may +find that making changes to all those pages can be a real pain, +particularly if you are trying to maintain some kind of standard look +across all those pages.</p> + +<p>Using an include file for a header and/or a footer can reduce the +burden of these updates. You just have to make one footer file, and +then include it into each page with the <code>include</code> SSI +command. The <code>include</code> element can determine what file to +include with either the <code>file</code> attribute, or the +<code>virtual</code> attribute. The <code>file</code> attribute is a +file path, <em>relative to the current directory</em>. That means that +it cannot be an absolute file path (starting with /), nor can it +contain ../ as part of that path. The <code>virtual</code> attribute is +probably more useful, and should specify a URL relative to the document +being served. It can start with a /, but must be on the same server as +the file being served.</p> + +<pre> + <!--#include virtual="/footer.html" --> +</pre> + +<p>I'll frequently combine the last two things, putting a +<code>LAST_MODIFIED</code> directive inside a footer file to be +included. SSI directives can be contained in the included file, and +includes can be nested - that is, the included file can include another +file, and so on.</p> + +<hr> +<h2><a name="whatelsecaniconfig">What else can I config?</a></h2> + +<p>In addition to being able to <code>config</code> the time format, +you can also <code>config</code> two other things.</p> + +<p>Usually, when something goes wrong with your SSI directive, you get +the message</p> + +<pre> + [an error occurred while processing this directive] +</pre> + +<p>If you want to change that message to something else, you can do so +with the <code>errmsg</code> attribute to the <code>config</code> +element:</p> + +<pre> + <!--#config errmsg="[It appears that you don't know how to use SSI]" --> +</pre> + +<p>Hopefully, end users will never see this message, because you will +have resolved all the problems with your SSI directives before your +site goes live. (Right?)</p> + +<p>And you can <code>config</code> the format in which file sizes are +returned with the <code>sizefmt</code> attribute. You can specify +<code>bytes</code> for a full count in bytes, or <code>abbrev</code> +for an abbreviated number in Kb or Mb, as appropriate.</p> + +<hr> +<h2><a name="executingcommands">Executing commands</a></h2> + +<p>I expect that I'll have an article some time in the coming months +about using SSI with small CGI programs. For now, here's something else +that you can do with the <code>exec</code> element. You can actually +have SSI execute a command using the shell (<code>/bin/sh</code>, to be +precise - or the DOS shell, if you're on Win32). The following, for +example, will give you a directory listing.</p> + +<pre> + <pre> + <!--#exec cmd="ls" --> + </pre> +</pre> + +<p>or, on Windows</p> + +<pre> + <pre> + <!--#exec cmd="dir" --> + </pre> +</pre> + +<p>You might notice some strange formatting with this directive on +Windows, because the output from <code>dir</code> contains the string +``<<code>dir</code>>'' in it, which confuses browsers.</p> + +<p>Note that this feature is exceedingly dangerous, as it will execute +whatever code happens to be embedded in the <code>exec</code> tag. If +you have any situation where users can edit content on your web pages, +such as with a ``guestbook'', for example, make sure that you have this +feature disabled. You can allow SSI, but not the <code>exec</code> +feature, with the <code>IncludesNOEXEC</code> argument to the +<code>Options</code> directive.</p> + +<hr> +<h2><a name="advancedssitechniques">Advanced SSI techniques</a></h2> + +<p>In addition to spitting out content, Apache SSI gives you the option +of setting variables, and using those variables in comparisons and +conditionals.</p> + +<h3><a name="caveat">Caveat</a></h3> + +<p>Most of the features discussed in this article are only available to +you if you are running Apache 1.2 or later. Of course, if you are not +running Apache 1.2 or later, you need to upgrade immediately, if not +sooner. Go on. Do it now. We'll wait.</p> + +<hr> +<h2><a name="settingvariables">Setting variables</a></h2> + +<p>Using the <code>set</code> directive, you can set variables for +later use. We'll need this later in the discussion, so we'll talk about +it here. The syntax of this is as follows:</p> + +<pre> + <!--#set var="name" value="Rich" --> +</pre> + +<p>In addition to merely setting values literally like that, you can +use any other variable, including, for example, environment variables, +or some of the variables we discussed in the last article (like +<code>LAST_MODIFIED</code>, for example) to give values to your +variables. You will specify that something is a variable, rather than a +literal string, by using the dollar sign ($) before the name of the +variable.</p> + +<pre> + <!--#set var="modified" value="$LAST_MODIFIED" --> +</pre> + +<p>To put a literal dollar sign into the value of your variable, you +need to escape the dollar sign with a backslash.</p> + +<pre> + <!--#set var="cost" value="\$100" --> +</pre> + +<p>Finally, if you want to put a variable in the midst of a longer +string, and there's a chance that the name of the variable will run up +against some other characters, and thus be confused with those +characters, you can place the name of the variable in braces, to remove +this confusion. (It's hard to come up with a really good example of +this, but hopefully you'll get the point.)</p> + +<pre> + <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --> +</pre> + +<hr> +<h2><a name="conditionalexpressions">Conditional expressions</a></h2> + +<p>Now that we have variables, and are able to set and compare their +values, we can use them to express conditionals. This lets SSI be a +tiny programming language of sorts. <code>mod_include</code> provides +an <code>if</code>, <code>elif</code>, <code>else</code>, +<code>endif</code> structure for building conditional statements. This +allows you to effectively generate multiple logical pages out of one +actual page.</p> + +<p>The structure of this conditional construct is:</p> + +<pre> + <!--#if expr="test_condition" --> + <!--#elif expr="test_condition" --> + <!--#else --> + <!--#endif --> +</pre> + +<p>A <em>test_condition</em> can be any sort of logical comparison - +either comparing values to one another, or testing the ``truth'' of a +particular value. (A given string is true if it is nonempty.) For a +full list of the comparison operators available to you, see the +<code>mod_include</code> documentation. Here are some examples of how +one might use this construct.</p> + +<p>In your configuration file, you could put the following line:</p> + +<pre> + BrowserMatchNoCase macintosh Mac + BrowserMatchNoCase MSIE InternetExplorer +</pre> + +<p>This will set environment variables ``Mac'' and ``InternetExplorer'' +to true, if the client is running Internet Explorer on a Macintosh.</p> + +<p>Then, in your SSI-enabled document, you might do the following:</p> + +<pre> + <!--#if expr="${Mac} && ${InternetExplorer}" --> + Apologetic text goes here + <!--#else --> + Cool JavaScript code goes here + <!--#endif --> +</pre> + +<p>Not that I have anything against IE on Macs - I just struggled for a +few hours last week trying to get some JavaScript working on IE on a +Mac, when it was working everywhere else. The above was the interim +workaround.</p> + +<p>Any other variable (either ones that you define, or normal +environment variables) can be used in conditional statements. With +Apache's ability to set environment variables with the +<code>SetEnvIf</code> directives, and other related directives, this +functionality can let you do some pretty involved dynamic stuff without +ever resorting to CGI.</p> + +<hr> +<h2><a name="conclusion">Conclusion</a></h2> + +<p>SSI is certainly not a replacement for CGI, or other technologies +used for generating dynamic web pages. But it is a great way to add +small amounts of dynamic content to pages, without doing a lot of extra +work.</p> +</body> +</html> + diff --git a/docs/manual/howto/ssi.html.en b/docs/manual/howto/ssi.html.en new file mode 100644 index 0000000000..0bd2a1f8bc --- /dev/null +++ b/docs/manual/howto/ssi.html.en @@ -0,0 +1,519 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Apache Tutorial: Introduction to Server Side Includes</title> +<link rev="made" href="mailto:rbowen@rcbowen.com"> +</head> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080" +alink="#FF0000"> +<!--#include virtual="header.html" --> +<h1 align="CENTER">Apache Tutorial: Introduction to Server Side +Includes</h1> + +<a name="__index__"></a> <!-- INDEX BEGIN --> + + +<ul> +<li><a href= +"#apachetutorial:introductiontoserversideincludes">Apache +Tutorial: Introduction to Server Side Includes</a></li> + +<li><a href="#whataressi">What are SSI?</a></li> + +<li><a href="#configuringyourservertopermitssi">Configuring your +server to permit SSI</a></li> + +<li><a href="#basicssidirectives">Basic SSI directives</a> + +<ul> + <li><a href="#today'sdate">Today's date</a></li> + + <li><a href="#modificationdateofthefile">Modification date of the +file</a></li> + + <li><a href="#includingtheresultsofacgiprogram">Including the +results of a CGI program</a></li> +</ul> +</li> + +<li><a href="#additionalexamples">Additional examples</a> + +<ul> +<li><a href="#whenwasthisdocumentmodified">When was this document +modified?</a></li> + +<li><a href="#includingastandardfooter">Including a standard +footer</a></li> + +<li><a href="#whatelsecaniconfig">What else can I config?</a></li> + +<li><a href="#executingcommands">Executing commands</a></li> +</ul> +</li> + +<li><a href="#advancedssitechniques">Advanced SSI techniques</a> + +<ul> +<li><a href="#settingvariables">Setting variables</a></li> + +<li><a href="#conditionalexpressions">Conditional expressions</a></li> +</ul> +</li> + +<li><a href="#conclusion">Conclusion</a></li> +</ul> + +<!-- INDEX END --> +<hr> +<h2><a name= +"apachetutorial:introductiontoserversideincludes">Apache +Tutorial: Introduction to Server Side Includes</a></h2> + +<table border="1"> +<tr> +<td valign="top"><strong>Related Modules</strong><br> +<br> + <a href="../mod/mod_include.html">mod_include</a><br> +<a href="../mod/mod_cgi.html">mod_cgi</a><br> +<a href="../mod/mod_expires.html">mod_expires</a><br> + </td> +<td valign="top"><strong>Related Directives</strong><br> +<br> + <a href="../mod/core.html#options">Options</a><br> +<a href="../mod/mod_include.html#xbithack">XBitHack</a><br> +<a href="../mod/mod_mime.html#addtype">AddType</a><br> +<a href="../mod/mod_mime.html#addhandler">AddHandler</a><br> +<a href= +"../mod/mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</a><br> + + </td> +</tr> +</table> + +<p>This HOWTO first appeared in Apache Today +(http://www.apachetoday.com/) as a series of three articles. They +appear here by arrangement with ApacheToday and Internet.com.</p> + +<p>This article deals with Server Side Includes, usually called simply +SSI. In this article, I'll talk about configuring your server to permit +SSI, and introduce some basic SSI techniques for adding dynamic content +to your existing HTML pages.</p> + +<p>In the latter part of the article, we'll talk about some of the +somewhat more advanced things that can be done with SSI, such as +conditional statements in your SSI directives.</p> + +<hr> +<h2><a name="whataressi">What are SSI?</a></h2> + +<p>SSI (Server Side Includes) are directives that are placed in HTML +pages, and evaluated on the server while the pages are being served. +They let you add dynamically generated content to an existing HTML +page, without having to serve the entire page via a CGI program, or +other dynamic technology.</p> + +<p>The decision of when to use SSI, and when to have your page entirely +generated by some program, is usually a matter of how much of the page +is static, and how much needs to be recalculated every time the page is +served. SSI is a great way to add small pieces of information, such as +the current time. But if a majority of your page is being generated at +the time that it is served, you need to look for some other +solution.</p> + +<hr> +<h2><a name="configuringyourservertopermitssi">Configuring your +server to permit SSI</a></h2> + +<p>To permit SSI on your server, you must have the following directive +either in your <code>httpd.conf</code> file, or in a +<code>.htaccess</code> file:</p> + +<pre> + Options +Includes +</pre> + +<p>This tells Apache that you want to permit files to be parsed for SSI +directives.</p> + +<p>Not just any file is parsed for SSI directives. You have to tell +Apache which files should be parsed. There are two ways to do this. You +can tell Apache to parse any file with a particular file extension, +such as <code>.shtml</code>, with the following directives:</p> + +<pre> + AddType text/html .shtml + AddHandler server-parsed .shtml +</pre> + +<p>One disadvantage to this approach is that if you wanted to add SSI +directives to an existing page, you would have to change the name of +that page, and all links to that page, in order to give it a +<code>.shtml</code> extension, so that those directives would be +executed.</p> + +<p>The other method is to use the <code>XBitHack</code> directive:</p> + +<pre> + XBitHack on +</pre> + +<p><code>XBitHack</code> tells Apache to parse files for SSI directives +if they have the execute bit set. So, to add SSI directives to an +existing page, rather than having to change the file name, you would +just need to make the file executable using <code>chmod</code>.</p> + +<pre> + chmod +x pagename.html +</pre> + +<p>A brief comment about what not to do. You'll occasionally see people +recommending that you just tell Apache to parse all <code>.html</code> +files for SSI, so that you don't have to mess with <code>.shtml</code> +file names. These folks have perhaps not heard about +<code>XBitHack</code>. The thing to keep in mind is that, by doing +this, you're requiring that Apache read through every single file that +it sends out to clients, even if they don't contain any SSI directives. +This can slow things down quite a bit, and is not a good idea.</p> + +<p>Of course, on Windows, there is no such thing as an execute bit to +set, so that limits your options a little.</p> + +<p>In its default configuration, Apache does not send the last modified +date or content length HTTP headers on SSI pages, because these values are +difficult to calculate for dynamic content. This can prevent your +document from being cached, and result in slower perceived client +performance. There are two ways to solve this:</p> + +<ol> + +<li>Use the <code>XBitHack Full</code> configuration. This tells +Apache to determine the last modified date by looking only at the date +of the originally requested file, ignoring the modification date of +any included files. </li> + +<li>Use the directives provided by <a +href="../mod/mod_expires.html">mod_expires</a> to set an explicit +expiration time on your files, thereby letting browsers and proxies +know that it is acceptable to cache them. </li> + +</ol> + + +<hr> +<h2><a name="basicssidirectives">Basic SSI directives</a></h2> + +<p>SSI directives have the following syntax:</p> + +<pre> + <!--#element attribute=value attribute=value ... --> +</pre> + +<p>It is formatted like an HTML comment, so if you don't have SSI +correctly enabled, the browser will ignore it, but it will still be +visible in the HTML source. If you have SSI correctly configured, the +directive will be replaced with its results.</p> + +<p>The element can be one of a number of things, and we'll talk some +more about most of these in the next installment of this series. For +now, here are some examples of what you can do with SSI</p> + +<h3><a name="today'sdate">Today's date</a></h3> + +<pre> + <!--#echo var=DATE_LOCAL --> +</pre> + +<p>The <code>echo</code> element just spits out the value of a +variable. There are a number of standard variables, which include the +whole set of environment variables that are available to CGI programs. +Also, you can define your own variables with the <code>set</code> +element.</p> + +<p>If you don't like the format in which the date gets printed, you can +use the <code>config</code> element, with a <code>timefmt</code> +attribute, to modify that formatting.</p> + +<pre> + <!--#config timefmt="%A %B %d, %Y" --> + Today is <!--#echo var=DATE_LOCAL --> +</pre> + +<h3><a name="modificationdateofthefile">Modification date of the +file</a></h3> + +<pre> + This document last modified <!--#flastmod file="index.html" --> +</pre> + +<p>This element is also subject to <code>timefmt</code> format +configurations.</p> + +<h3><a name="includingtheresultsofacgiprogram">Including the +results of a CGI program</a></h3> + +<p>This is one of the more common uses of SSI - to output the results +of a CGI program, such as everybody's favorite, a ``hit counter.''</p> + +<pre> + <!--#include virtual="/cgi-bin/counter.pl" --> +</pre> + +<hr> +<h2><a name="additionalexamples">Additional examples</a></h2> + +<p>Following are some specific examples of things you can do in your +HTML documents with SSI.</p> + +<hr> +<h2><a name="whenwasthisdocumentmodified">When was this document +modified?</a></h2> + +<p>Earlier, we mentioned that you could use SSI to inform the user when +the document was most recently modified. However, the actual method for +doing that was left somewhat in question. The following code, placed in +your HTML document, will put such a time stamp on your page. Of course, +you will have to have SSI correctly enabled, as discussed above.</p> + +<pre> + <!--#config timefmt="%A %B %d, %Y" --> + This file last modified <!--#flastmod file="ssi.shtml" --> +</pre> + +<p>Of course, you will need to replace the <code>ssi.shtml</code> with +the actual name of the file that you're referring to. This can be +inconvenient if you're just looking for a generic piece of code that +you can paste into any file, so you probably want to use the +<code>LAST_MODIFIED</code> variable instead:</p> + +<pre> + <!--#config timefmt="%D" --> + This file last modified <!--#echo var="LAST_MODIFIED" --> +</pre> + +<p>For more details on the <code>timefmt</code> format, go to your +favorite search site and look for <code>ctime</code>. The syntax is the +same.</p> + +<hr> +<h2><a name="includingastandardfooter">Including a standard +footer</a></h2> + +<p>If you are managing any site that is more than a few pages, you may +find that making changes to all those pages can be a real pain, +particularly if you are trying to maintain some kind of standard look +across all those pages.</p> + +<p>Using an include file for a header and/or a footer can reduce the +burden of these updates. You just have to make one footer file, and +then include it into each page with the <code>include</code> SSI +command. The <code>include</code> element can determine what file to +include with either the <code>file</code> attribute, or the +<code>virtual</code> attribute. The <code>file</code> attribute is a +file path, <em>relative to the current directory</em>. That means that +it cannot be an absolute file path (starting with /), nor can it +contain ../ as part of that path. The <code>virtual</code> attribute is +probably more useful, and should specify a URL relative to the document +being served. It can start with a /, but must be on the same server as +the file being served.</p> + +<pre> + <!--#include virtual="/footer.html" --> +</pre> + +<p>I'll frequently combine the last two things, putting a +<code>LAST_MODIFIED</code> directive inside a footer file to be +included. SSI directives can be contained in the included file, and +includes can be nested - that is, the included file can include another +file, and so on.</p> + +<hr> +<h2><a name="whatelsecaniconfig">What else can I config?</a></h2> + +<p>In addition to being able to <code>config</code> the time format, +you can also <code>config</code> two other things.</p> + +<p>Usually, when something goes wrong with your SSI directive, you get +the message</p> + +<pre> + [an error occurred while processing this directive] +</pre> + +<p>If you want to change that message to something else, you can do so +with the <code>errmsg</code> attribute to the <code>config</code> +element:</p> + +<pre> + <!--#config errmsg="[It appears that you don't know how to use SSI]" --> +</pre> + +<p>Hopefully, end users will never see this message, because you will +have resolved all the problems with your SSI directives before your +site goes live. (Right?)</p> + +<p>And you can <code>config</code> the format in which file sizes are +returned with the <code>sizefmt</code> attribute. You can specify +<code>bytes</code> for a full count in bytes, or <code>abbrev</code> +for an abbreviated number in Kb or Mb, as appropriate.</p> + +<hr> +<h2><a name="executingcommands">Executing commands</a></h2> + +<p>I expect that I'll have an article some time in the coming months +about using SSI with small CGI programs. For now, here's something else +that you can do with the <code>exec</code> element. You can actually +have SSI execute a command using the shell (<code>/bin/sh</code>, to be +precise - or the DOS shell, if you're on Win32). The following, for +example, will give you a directory listing.</p> + +<pre> + <pre> + <!--#exec cmd="ls" --> + </pre> +</pre> + +<p>or, on Windows</p> + +<pre> + <pre> + <!--#exec cmd="dir" --> + </pre> +</pre> + +<p>You might notice some strange formatting with this directive on +Windows, because the output from <code>dir</code> contains the string +``<<code>dir</code>>'' in it, which confuses browsers.</p> + +<p>Note that this feature is exceedingly dangerous, as it will execute +whatever code happens to be embedded in the <code>exec</code> tag. If +you have any situation where users can edit content on your web pages, +such as with a ``guestbook'', for example, make sure that you have this +feature disabled. You can allow SSI, but not the <code>exec</code> +feature, with the <code>IncludesNOEXEC</code> argument to the +<code>Options</code> directive.</p> + +<hr> +<h2><a name="advancedssitechniques">Advanced SSI techniques</a></h2> + +<p>In addition to spitting out content, Apache SSI gives you the option +of setting variables, and using those variables in comparisons and +conditionals.</p> + +<h3><a name="caveat">Caveat</a></h3> + +<p>Most of the features discussed in this article are only available to +you if you are running Apache 1.2 or later. Of course, if you are not +running Apache 1.2 or later, you need to upgrade immediately, if not +sooner. Go on. Do it now. We'll wait.</p> + +<hr> +<h2><a name="settingvariables">Setting variables</a></h2> + +<p>Using the <code>set</code> directive, you can set variables for +later use. We'll need this later in the discussion, so we'll talk about +it here. The syntax of this is as follows:</p> + +<pre> + <!--#set var="name" value="Rich" --> +</pre> + +<p>In addition to merely setting values literally like that, you can +use any other variable, including, for example, environment variables, +or some of the variables we discussed in the last article (like +<code>LAST_MODIFIED</code>, for example) to give values to your +variables. You will specify that something is a variable, rather than a +literal string, by using the dollar sign ($) before the name of the +variable.</p> + +<pre> + <!--#set var="modified" value="$LAST_MODIFIED" --> +</pre> + +<p>To put a literal dollar sign into the value of your variable, you +need to escape the dollar sign with a backslash.</p> + +<pre> + <!--#set var="cost" value="\$100" --> +</pre> + +<p>Finally, if you want to put a variable in the midst of a longer +string, and there's a chance that the name of the variable will run up +against some other characters, and thus be confused with those +characters, you can place the name of the variable in braces, to remove +this confusion. (It's hard to come up with a really good example of +this, but hopefully you'll get the point.)</p> + +<pre> + <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --> +</pre> + +<hr> +<h2><a name="conditionalexpressions">Conditional expressions</a></h2> + +<p>Now that we have variables, and are able to set and compare their +values, we can use them to express conditionals. This lets SSI be a +tiny programming language of sorts. <code>mod_include</code> provides +an <code>if</code>, <code>elif</code>, <code>else</code>, +<code>endif</code> structure for building conditional statements. This +allows you to effectively generate multiple logical pages out of one +actual page.</p> + +<p>The structure of this conditional construct is:</p> + +<pre> + <!--#if expr="test_condition" --> + <!--#elif expr="test_condition" --> + <!--#else --> + <!--#endif --> +</pre> + +<p>A <em>test_condition</em> can be any sort of logical comparison - +either comparing values to one another, or testing the ``truth'' of a +particular value. (A given string is true if it is nonempty.) For a +full list of the comparison operators available to you, see the +<code>mod_include</code> documentation. Here are some examples of how +one might use this construct.</p> + +<p>In your configuration file, you could put the following line:</p> + +<pre> + BrowserMatchNoCase macintosh Mac + BrowserMatchNoCase MSIE InternetExplorer +</pre> + +<p>This will set environment variables ``Mac'' and ``InternetExplorer'' +to true, if the client is running Internet Explorer on a Macintosh.</p> + +<p>Then, in your SSI-enabled document, you might do the following:</p> + +<pre> + <!--#if expr="${Mac} && ${InternetExplorer}" --> + Apologetic text goes here + <!--#else --> + Cool JavaScript code goes here + <!--#endif --> +</pre> + +<p>Not that I have anything against IE on Macs - I just struggled for a +few hours last week trying to get some JavaScript working on IE on a +Mac, when it was working everywhere else. The above was the interim +workaround.</p> + +<p>Any other variable (either ones that you define, or normal +environment variables) can be used in conditional statements. With +Apache's ability to set environment variables with the +<code>SetEnvIf</code> directives, and other related directives, this +functionality can let you do some pretty involved dynamic stuff without +ever resorting to CGI.</p> + +<hr> +<h2><a name="conclusion">Conclusion</a></h2> + +<p>SSI is certainly not a replacement for CGI, or other technologies +used for generating dynamic web pages. But it is a great way to add +small amounts of dynamic content to pages, without doing a lot of extra +work.</p> +</body> +</html> + |