ssi.xml revision dc643bc37eec0af989b9623deaa81fb9499b6c8e
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd<manualpage>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd<title>Apache Tutorial: Introduction to Server Side Includes</title>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd<p>Server-side includes provide a means to add dynamic content to
0853e1e2522c1ac17f697221758bcbd4781a7ff9ndexisting HTML documents.</p>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd <modulelist>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd </modulelist>
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <directivelist>
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi <directive module="mod_setenvif">BrowserMatchNoCase</directive>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd </directivelist>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd <p>This article deals with Server Side Includes, usually called
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd simply SSI. In this article, I'll talk about configuring your
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd server to permit SSI, and introduce some basic SSI techniques
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd for adding dynamic content to your existing HTML pages.</p>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd <p>In the latter part of the article, we'll talk about some of
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd the somewhat more advanced things that can be done with SSI,
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd such as conditional statements in your SSI directives.</p>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd <p>SSI (Server Side Includes) are directives that are placed in
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd HTML pages, and evaluated on the server while the pages are
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd being served. They let you add dynamically generated content to
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd an existing HTML page, without having to serve the entire page
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd via a CGI program, or other dynamic technology.</p>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd <p>The decision of when to use SSI, and when to have your page
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd entirely generated by some program, is usually a matter of how
80eed96ee3d8cfa0b66d9fb1cfe63fd83254d38bnilgun much of the page is static, and how much needs to be
80eed96ee3d8cfa0b66d9fb1cfe63fd83254d38bnilgun recalculated every time the page is served. SSI is a great way
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd to add small pieces of information, such as the current time.
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd But if a majority of your page is being generated at the time
316f02e3836836c82e19019ff23f90a7ebc65289nilgun that it is served, you need to look for some other
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd solution.</p>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd <p>To permit SSI on your server, you must have the following
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd directive either in your <code>httpd.conf</code> file, or in a
22d5d84393d960a2027f472036f3fee15d7dbce9nd Options +Includes
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>This tells Apache that you want to permit files to be parsed
a78048ccbdb6256da15e6b0e7e95355e480c2301nd for SSI directives. Note that most configurations contain
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd multiple <directive module="core">Options</directive> directives
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd that can override each other. You will probably need to apply the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <code>Options</code> to the specific directory where you want SSI
623eebe956d9c2d6d073ed3eae855b56030b40e9noodl enabled in order to assure that it gets evaluated last.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>Not just any file is parsed for SSI directives. You have to
ffb88a4885747797937e30a5ac8b1606da3cb4adnd tell Apache which files should be parsed. There are two ways to
909ce17e2bd0faef7b1c294f2307f009793fd493nd do this. You can tell Apache to parse any file with a
a78048ccbdb6256da15e6b0e7e95355e480c2301nd particular file extension, such as <code>.shtml</code>, with
a78048ccbdb6256da15e6b0e7e95355e480c2301nd the following directives:</p>
ffb88a4885747797937e30a5ac8b1606da3cb4adnd AddOutputFilter INCLUDES .shtml
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>One disadvantage to this approach is that if you wanted to
9649d29bb7801e0698e6a845e1a8a61534df58b3noodl add SSI directives to an existing page, you would have to
9649d29bb7801e0698e6a845e1a8a61534df58b3noodl change the name of that page, and all links to that page, in
a78048ccbdb6256da15e6b0e7e95355e480c2301nd order to give it a <code>.shtml</code> extension, so that those
a78048ccbdb6256da15e6b0e7e95355e480c2301nd directives would be executed.</p>
08cf4a15275e4cb65a424b3a1db5410bfb51085cjim module="mod_includes">XBitHack</directive> directive:</p>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd XBitHack on
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd tells Apache to parse files for SSI
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd directives if they have the execute bit set. So, to add SSI
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd directives to an existing page, rather than having to change
05ede5110427cb9dc071cc671d5aaba5d3b88c79nd the file name, you would just need to make the file executable
611049e38bfbaeb173d2d7fab2e44a48753436a1nd <p>A brief comment about what not to do. You'll occasionally
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd see people recommending that you just tell Apache to parse all
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd <code>.html</code> files for SSI, so that you don't have to
8574d86b9ec3be36b7f54ed0547a0ee5d60dbd6bnd mess with <code>.shtml</code> file names. These folks have
a78048ccbdb6256da15e6b0e7e95355e480c2301nd perhaps not heard about <directive
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak module="mod_includes">XBitHack</directive>. The thing to
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak keep in mind is that, by doing this, you're requiring that
a78048ccbdb6256da15e6b0e7e95355e480c2301nd Apache read through every single file that it sends out to
a78048ccbdb6256da15e6b0e7e95355e480c2301nd clients, even if they don't contain any SSI directives. This
a78048ccbdb6256da15e6b0e7e95355e480c2301nd can slow things down quite a bit, and is not a good idea.</p>
f21bea4c0f58e17aa1d9a0fac2c219852f89944amaczniak <p>Of course, on Windows, there is no such thing as an execute
d0828c8a321dc5e9ea60550f052294669c08cf93jim bit to set, so that limits your options a little.</p>
f21bea4c0f58e17aa1d9a0fac2c219852f89944amaczniak <p>In its default configuration, Apache does not send the last
4b5981e276e93df97c34e4da05ca5cf8bbd937dand modified date or content length HTTP headers on SSI pages,
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd because these values are difficult to calculate for dynamic
f21bea4c0f58e17aa1d9a0fac2c219852f89944amaczniak content. This can prevent your document from being cached, and
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak result in slower perceived client performance. There are two
2704de98885368683621b01c8f8f4e4b01557611takashi ways to solve this:</p>
d0828c8a321dc5e9ea60550f052294669c08cf93jim <li>Use the <code>XBitHack Full</code> configuration. This
2704de98885368683621b01c8f8f4e4b01557611takashi tells Apache to determine the last modified date by looking
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd only at the date of the originally requested file, ignoring
6aadbc6fd703e73d1d419e9f06b84a4338c898f1maczniak the modification date of any included files.</li>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <li>Use the directives provided by
cd6c8de3bedcc401ee230159b0439fa20f44488etakashi <module>mod_expires</module> to set an explicit expiration
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd time on your files, thereby letting browsers and proxies
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd know that it is acceptable to cache them.</li>
27d778df0b517e1578f907d2e51eb961cd8ee5fbjim <!--#element attribute=value attribute=value ... -->
28c9d384aa958b321280b4ac886941dcad25396bnd <p>It is formatted like an HTML comment, so if you don't have
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd SSI correctly enabled, the browser will ignore it, but it will
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd still be visible in the HTML source. If you have SSI correctly
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi configured, the directive will be replaced with its
e5ce3ac0e9b720c0fa23782e29168a0810697fdetakashi results.</p>
50cb7e2b30597f481fee57bac945190f06ebcc58jorton <p>The element can be one of a number of things, and we'll talk
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd some more about most of these in the next installment of this
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd series. For now, here are some examples of what you can do with
5f4e50966b2b9b58436a1651cbe588d1b595657ewrowe <!--#echo var="DATE_LOCAL" -->
11495c9f0bd33e51a25b4d532beadfbcf9b944a3nilgun <p>The <code>echo</code> element just spits out the value of a
11495c9f0bd33e51a25b4d532beadfbcf9b944a3nilgun variable. There are a number of standard variables, which
5f4e50966b2b9b58436a1651cbe588d1b595657ewrowe include the whole set of environment variables that are
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi available to CGI programs. Also, you can define your own
79b024b81f6bb3c44dce77a7552191daf8b522d2jim <p>If you don't like the format in which the date gets printed,
f772e8f448c223e5ea306f1bf92d97d968f972d5jim <code>timefmt</code> attribute, to modify that formatting.</p>
1de1266f0ea387d6373be8415745dfd2ab876341jim <!--#config timefmt="%A %B %d, %Y" --><br />
1de1266f0ea387d6373be8415745dfd2ab876341jim Today is <!--#echo var="DATE_LOCAL" -->
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<section id="lastmodified"><title>Modification date of the file</title>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd This document last modified <!--#flastmod file="index.html" -->
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>This element is also subject to <code>timefmt</code> format
a78048ccbdb6256da15e6b0e7e95355e480c2301nd configurations.</p>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd<section id="cgi"><title>Including the results of a CGI program</title>
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd <p>This is one of the more common uses of SSI - to output the
8e31885fc494b603e0650113dde9e29d1b1d2602maczniak results of a CGI program, such as everybody's favorite, a ``hit
03c25fb6f628ac81f2ecb637d1e7502dcee783f3nd counter.''</p>
50039065d571fe01fd458a3f031c995a1fd53c22rbowen <p>Following are some specific examples of things you can do in
0853e1e2522c1ac17f697221758bcbd4781a7ff9nd your HTML documents with SSI.</p>
This file last modified <!--#flastmod file="ssi.shtml" -->
<!--#include virtual="/footer.html" -->