<title>Apache httpd Tutorial: Introduction to Server Side Includes</title>
<summary>
-<p>Server-side includes provide a means to add dynamic content to
-existing HTML documents.</p>
+<p>Server Side Includes (SSI) provide a way to add dynamic content to
+existing HTML documents without requiring a full application framework.
+They are particularly useful for inserting common elements — headers,
+footers, navigation, timestamps — into otherwise static pages.</p>
</summary>
<section id="related"><title>Introduction</title>
</directivelist>
</related>
- <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>SSI lets you drop simple directives into your HTML files that
+ the server evaluates before sending the page to the client. This
+ is a lightweight way to keep shared content (like a site-wide
+ footer or a "last modified" timestamp) in one place, without
+ needing a template engine or application server.</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>
+ <p>This document covers configuring httpd to permit SSI, basic
+ SSI directives for common tasks, and some more advanced
+ techniques including variables and conditional expressions.</p>
</section>
<section id="what"><title>What are SSI?</title>
- <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>SSI directives are HTML comments with a specific syntax that
+ <module>mod_include</module> recognizes and evaluates before the
+ page is sent to the client. They look like this:</p>
- <p>For example, you might place a directive into an existing HTML
- page, such as:</p>
-
- <example>
- <!--#echo var="DATE_LOCAL" -->
- </example>
+<example>
+<highlight language="html">
+<!--#echo var="DATE_LOCAL" -->
+</highlight>
+</example>
- <p>And, when the page is served, this fragment will be evaluated and replaced with its value:</p>
+ <p>When the page is served, this fragment is replaced with its
+ value:</p>
<example>
- Tuesday, 15-Jan-2013 19:28:54 EST
+ Thursday, 18-Jun-2026 14:22:07 EDT
</example>
- <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 - shown
- above. 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>
+ <p>Because the directives are embedded in HTML comments, if SSI
+ is not enabled, browsers ignore them (though they remain
+ visible in the page source).</p>
</section>
<section id="configuring">
<title>Configuring your server to permit SSI</title>
- <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>
+ <p>To enable SSI processing, add the following directive to your
+ <code>httpd.conf</code> file or to a <code>.htaccess</code>
+ file:</p>
+
+<example>
<highlight language="config">
Options +Includes
</highlight>
+</example>
+
+ <p>This tells httpd to parse files for SSI directives. Since most
+ configurations contain multiple <directive module="core"
+ >Options</directive> directives that can override each other, apply
+ this to the specific directory where you want SSI enabled.</p>
+
+ <p>You also need to tell httpd which files to parse. There are
+ two common approaches.</p>
+
+ <p>The first is to designate a file extension (typically
+ <code>.shtml</code>) for SSI-enabled pages:</p>
- <p>This tells Apache that you want to permit files to be parsed
- for SSI directives. Note that most configurations contain
- multiple <directive module="core">Options</directive> directives
- that can override each other. You will probably need to apply the
- <code>Options</code> to the specific directory where you want SSI
- enabled in order to assure that it gets evaluated last.</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>
+<example>
<highlight language="config">
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml
</highlight>
+</example>
- <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 disadvantage here is that adding SSI to an existing page
+ requires renaming the file (and updating all links to it) to use
+ the <code>.shtml</code> extension.</p>
- <p>The other method is to use the <directive
+ <p>The second approach uses the <directive
module="mod_include">XBitHack</directive> directive:</p>
+
+<example>
<highlight language="config">
XBitHack on
</highlight>
+</example>
+
+ <p><directive module="mod_include">XBitHack</directive> tells
+ httpd to parse any file that has its execute bit set. To enable
+ SSI on an existing page, make the file executable:</p>
- <p><directive module="mod_include">XBitHack</directive>
- 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>
<example>
- chmod +x pagename.html
+<highlight language="bash">
+chmod +x pagename.html
+</highlight>
</example>
- <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 <directive
- module="mod_include">XBitHack</directive>. 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>
+ <note type="warning"><p>
+ Avoid configuring httpd to parse <em>all</em> <code>.html</code>
+ files for SSI directives. This forces the server to read through
+ every HTML file it serves, even those without any SSI content,
+ which adds unnecessary overhead.
+ </p></note>
+
+ <p>On Windows, there is no execute bit, so the
+ <directive module="mod_include">XBitHack</directive> approach is
+ not available. Use the file-extension method instead.</p>
+
+ <p>By default, httpd does not send the last-modified date or
+ content-length headers on SSI pages, since these values are
+ difficult to calculate for dynamic content. This can prevent
+ caching and result in slower perceived performance. Two
+ approaches can help:</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
- <module>mod_expires</module> to set an explicit expiration
- time on your files, thereby letting browsers and proxies
- know that it is acceptable to cache them.</li>
+ <li>Use <code>XBitHack Full</code>, which tells httpd to
+ determine the last-modified date from the originally requested
+ file, ignoring the modification dates of included files.</li>
+
+ <li>Use <module>mod_expires</module> to set an explicit
+ expiration time, letting browsers and proxies know the content
+ is safe to cache.</li>
</ol>
</section>
<section id="basic"><title>Basic SSI directives</title>
- <p>SSI directives have the following syntax:</p>
+ <p>SSI directives use the following syntax:</p>
<example>
- <!--#function attribute=value attribute=value ... -->
+<highlight language="html">
+<!--#function attribute=value attribute=value ... -->
+</highlight>
</example>
- <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 function 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>
+ <p>If SSI is correctly configured, the directive is replaced with
+ its output. If not, it remains as an HTML comment — invisible to
+ the end user but present in the source.</p>
<section id="todaysdate"><title>Today's date</title>
<example>
- <!--#echo var="DATE_LOCAL" -->
+<highlight language="html">
+<!--#echo var="DATE_LOCAL" -->
+</highlight>
</example>
- <p>The <code>echo</code> function 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> function.</p>
+ <p>The <code>echo</code> function outputs the value of a variable.
+ Standard variables include the full set of environment variables
+ available to CGI programs, plus variables you define with
+ <code>set</code>.</p>
- <p>If you don't like the format in which the date gets printed,
- you can use the <code>config</code> function, with a
- <code>timefmt</code> attribute, to modify that formatting.</p>
+ <p>To customize the date format, use the <code>config</code>
+ function with the <code>timefmt</code> attribute:</p>
<example>
- <!--#config timefmt="%A %B %d, %Y" --><br />
- Today is <!--#echo var="DATE_LOCAL" -->
+<highlight language="html">
+<!--#config timefmt="%A %B %d, %Y" --><br />
+Today is <!--#echo var="DATE_LOCAL" -->
+</highlight>
</example>
</section>
<section id="lastmodified"><title>Modification date of the file</title>
<example>
- This document last modified <!--#flastmod file="index.html" -->
+<highlight language="html">
+This document last modified <!--#flastmod file="index.html" -->
+</highlight>
</example>
- <p>This function is also subject to <code>timefmt</code> format
- configurations.</p>
+ <p>This function is also subject to <code>timefmt</code>
+ configuration.</p>
</section>
<section id="cgi"><title>Including the results of a CGI program</title>
- <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>
+ <p>SSI can include the output of a CGI program directly in the
+ page:</p>
<example>
- <!--#include virtual="/cgi-bin/counter.pl" -->
+<highlight language="html">
+<!--#include virtual="/cgi-bin/counter.pl" -->
+</highlight>
</example>
</section>
<section id="additionalexamples">
<title>Additional examples</title>
- <p>Following are some specific examples of things you can do in
- your HTML documents with SSI.</p>
+ <p>The following are practical examples of common SSI use
+ cases.</p>
-<section id="docmodified"><title>When was this document
-modified?</title>
+<section id="docmodified"><title>When was this document modified?</title>
- <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>
-<example>
- <!--#config timefmt="%A %B %d, %Y" --><br />
- This file last modified <!--#flastmod file="ssi.shtml" -->
-</example>
+ <p>A common use of SSI is to display a "last modified" timestamp
+ on each page. The following code uses the
+ <code>LAST_MODIFIED</code> variable so you can paste the same
+ snippet into any file without changing the filename:</p>
- <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>
<example>
- <!--#config timefmt="%D" --><br />
- This file last modified <!--#echo var="LAST_MODIFIED" -->
+<highlight language="html">
+<!--#config timefmt="%D" --><br />
+This file last modified <!--#echo var="LAST_MODIFIED" -->
+</highlight>
</example>
- <p>For more details on the <code>timefmt</code> format, go to
- your favorite search site and look for <code>strftime</code>. The
- syntax is the same.</p>
+ <p>For details on <code>timefmt</code> format strings, see the
+ documentation for <code>strftime</code> in your system's C
+ library reference.</p>
</section>
<section id="standard-footer">
<title>Including a standard footer</title>
- <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>
- function 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>
+ <p>On a site with more than a few pages, maintaining a
+ consistent header or footer across all pages can be tedious.
+ SSI solves this by letting you keep shared content in a single
+ file and include it everywhere:</p>
+
<example>
- <!--#include virtual="/footer.html" -->
+<highlight language="html">
+<!--#include virtual="/footer.html" -->
+</highlight>
</example>
- <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>
+ <p>The <code>include</code> function accepts two attributes:
+ <code>file</code> specifies a path relative to the current
+ directory (it cannot be an absolute path or contain
+ <code>../</code>), while <code>virtual</code> specifies a URL
+ relative to the document being served (it can start with
+ <code>/</code> but must be on the same server).</p>
+
+ <p>SSI directives inside included files are evaluated normally,
+ and includes can be nested. This means you can put a
+ <code>LAST_MODIFIED</code> timestamp in your footer file, and
+ it will be evaluated in the context of each page that includes
+ it.</p>
</section>
</section>
<section id="config">
-<title>What else can I config?</title>
+<title>Other config options</title>
- <p>In addition to being able to <code>config</code> the time
- format, you can also <code>config</code> two other things.</p>
+ <p>In addition to <code>timefmt</code>, the <code>config</code>
+ function supports two other attributes.</p>
- <p>Usually, when something goes wrong with your SSI directive,
- you get the message</p>
+ <p>The <code>errmsg</code> attribute changes the error message
+ displayed when an SSI directive fails. The default is:</p>
<example>
- [an error occurred while processing this directive]
+[an error occurred while processing this directive]
</example>
- <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> function:</p>
+ <p>You can replace it with something more appropriate for your
+ site:</p>
<example>
- <!--#config errmsg="[It appears that you don't know how to use SSI]" -->
+<highlight language="html">
+<!--#config errmsg="[Content unavailable]" -->
+</highlight>
</example>
- <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>
- </section>
+ <p>The <code>sizefmt</code> attribute controls how file sizes
+ are formatted: <code>bytes</code> for a full byte count, or
+ <code>abbrev</code> for an abbreviated form in KB or MB.</p>
+</section>
<section id="exec">
<title>Executing commands</title>
- <p>Here's something else that you can do with the <code>exec</code>
- function. 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>
-<example>
- <pre><br />
- <!--#exec cmd="ls" --><br />
- </pre>
-</example>
+ <p>The <code>exec</code> function can run a shell command and
+ include its output in the page. On Unix-like systems, the
+ command is executed via <code>/bin/sh</code>; on Windows, via
+ the command shell.</p>
- <p>or, on Windows</p>
<example>
- <pre><br />
- <!--#exec cmd="dir" --><br />
- </pre>
+<highlight language="html">
+<pre>
+<!--#exec cmd="ls" -->
+</pre>
+</highlight>
</example>
- <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>
- </section>
+ <note type="warning"><p>
+ The <code>exec</code> feature is a significant security risk. It
+ executes arbitrary commands with the permissions of the web
+ server process. If users can edit content on your site, ensure
+ this feature is disabled by using <code>IncludesNOEXEC</code>
+ instead of <code>Includes</code> in the <directive module="core"
+ >Options</directive> directive.
+ </p></note>
+</section>
<section id="advanced">
<title>Advanced SSI techniques</title>
- <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>
+ <p>Beyond simple content inclusion, SSI supports variables and
+ conditional expressions, making it possible to generate
+ different content based on the request context.</p>
<section id="variables"><title>Setting variables</title>
- <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>
+ <p>The <code>set</code> directive defines variables for use later
+ in the page:</p>
+
<example>
- <!--#set var="name" value="Rich" -->
+<highlight language="html">
+<!--#set var="name" value="Rich" -->
+</highlight>
</example>
- <p>In addition to merely setting values literally like that, you
- can use any other variable, including <a
- href="../env.html">environment variables</a> or the variables
- discussed above (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>
+ <p>Variables can reference other variables (including
+ <a href="../env.html">environment variables</a>) using the dollar
+ sign (<code>$</code>) prefix:</p>
- <example> <!--#set var="modified" value="$LAST_MODIFIED" -->
- </example>
+<example>
+<highlight language="html">
+<!--#set var="modified" value="$LAST_MODIFIED" -->
+</highlight>
+</example>
+
+ <p>To include a literal dollar sign, escape it with a
+ backslash:</p>
- <p>To put a literal dollar sign into the value of your
- variable, you need to escape the dollar sign with a
- backslash.</p>
<example>
- <!--#set var="cost" value="\$100" -->
+<highlight language="html">
+<!--#set var="cost" value="\$100" -->
+</highlight>
</example>
- <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>
+ <p>When a variable name might be ambiguous within a longer
+ string, use braces to delimit it:</p>
+
<example>
- <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
+<highlight language="html">
+<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
+</highlight>
</example>
</section>
<section id="conditional">
<title>Conditional expressions</title>
- <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.
- <module>mod_include</module> 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><module>mod_include</module> provides <code>if</code>,
+ <code>elif</code>, <code>else</code>, and <code>endif</code>
+ constructs for building conditional logic. This lets you
+ generate different output from a single physical page.</p>
+
+ <p>The structure is:</p>
- <p>The structure of this conditional construct is:</p>
<example>
- <!--#if expr="test_condition" --><br />
- <!--#elif expr="test_condition" --><br />
- <!--#else --><br />
- <!--#endif -->
+<highlight language="html">
+<!--#if expr="test_condition" --><br />
+<!--#elif expr="test_condition" --><br />
+<!--#else --><br />
+<!--#endif -->
+</highlight>
</example>
- <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 <module>mod_include</module>
- documentation.</p>
+ <p>A <em>test_condition</em> can compare values or test whether a
+ variable is non-empty. See the <module>mod_include</module>
+ documentation for the full list of comparison operators.</p>
- <p>For example, if you wish to customize the text on your web page
- based on the time of day, you could use the following recipe, placed
- in the HTML page:</p>
+ <p>For example, to display different greetings based on the time
+ of day:</p>
- <example>
- Good
- <!--#if expr="%{TIME_HOUR} <12" --><br />
- morning!<br />
- <!--#else --><br />
- afternoon!<br />
- <!--#endif --><br />
- </example>
+<example>
+<highlight language="html">
+Good
+<!--#if expr="%{TIME_HOUR} <12" --><br />
+morning!<br />
+<!--#else --><br />
+afternoon!<br />
+<!--#endif --><br />
+</highlight>
+</example>
- <p>Any other variable (either ones that you define, or normal
- environment variables) can be used in conditional statements.
-
See <a href="../expr.html">Expressions in Apache HTTP Server</a> for
- more information on the expression evaluation engine.</p>
+ <p>Any variable — user-defined or from the environment — can be
+ used in conditional expressions. See
+ <a href="../expr.html">Expressions in Apache HTTP Server</a> for
+ full details on the expression evaluation engine.</p>
- <p>With Apache's ability to set environment variables with the
- <code>SetEnvIf</code> directives, and other related directives,
- this functionality can let you do a wide variety of dynamic content
- on the server side without resorting a full web application.</p>
+ <p>Combined with httpd's ability to set environment variables
+ using <directive module="mod_setenvif">SetEnvIf</directive> and
+ related directives, conditional SSI can handle a wide variety of
+ dynamic content scenarios without a full application
+ framework.</p>
</section>
</section>
<section id="conclusion"><title>Conclusion</title>
- <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>
+ <p>For sites that are mostly static but need a few dynamic
+ touches, SSI avoids the overhead of setting up a full
+ application stack. It requires only <module>mod_include</module>
+ and a few lines of configuration to get started.</p>
</section>
-</manualpage>
+</manualpage>
\ No newline at end of file
projects / thirdparty / apache / httpd.git / commitdiff
