mirror of
https://github.com/apache/httpd.git
synced 2025-10-31 19:10:37 +03:00
2761ae7342
1. Add info on how to activate ssi to upgrading.html. 2. Remove mention of the ssi magic mime-types, since they no longer work. 3. Place a warning on xbithack that it doesn't currently work, and reference the bug report. 4. Add a warning about mod_include parsing non-html content. 5. Misc little fixups. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@89655 13f79535-47bb-0310-9956-ffa450edef68
524 lines
18 KiB
Plaintext
524 lines
18 KiB
Plaintext
<!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/core.html.html#setoutputfilter">SetOutputFilter</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
|
|
<FilesMatch "\.shtml(\..+)?$">
|
|
SetOutputFilter INCLUDES
|
|
</FilesMatch>
|
|
</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>
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</body>
|
|
</html>
|
|
|