Apache - Server Side Includes

This page describes the functionality offered by, and the use of, Apache Server Side Includes (SSI and XSSI) (how to configure Apache to support SSI).

Note: The original of this page was written many, many moons ago when the world was young. We had the unhappy task of re-visiting it recently because of an email question and have corrected a number of errors, ambiguities and explanations which were shaky at best. All the information relates to PHP5 and Apache 2.x (currently 2.4).

Sad Note: Apache 2.4 (actually 2.3.13+) has changed the syntax of conditional expressions. The old behavior can be restored using the SSILegacyExprParser directive. Why do they do this stuff? Apache 1.3 used to be like a rock for backward compatibility.

Happier (Maybe) Note: We recently decided to create an HTML Help Service for LDAPviewer a Java based open source application we are working on. The Help service would be viewable from the web and (if using JRE 1.8) using local files distributed with the application. We are addicted to the use of (X)SSI includes to keep HTML development to a minimum. The question was what to do about local files. The result was this very trivial and limited Java XSSI tool, which will expand (X)SSI include directives in .html, .htm and .shtml files and copy referenced images to a images subdirectory in the output directory (fixing the <img> src reference at the same time). We do all our HTML page development on the web version and simply run the files through this directory based tool to create pure HTML (HTML5 in our case) as output to be distributed with the application or for use with web servers which do not support (X)SSI.

Contents

1. SSI Overview
2. SSI Directives
3. Apache and SSI Environmental Variables
4. Time and Date Formats
5. Example - Use of Apache Variables
6. Example - Page Changed and Copyright Date in Footer
7. Example - Page Source Comment
8. Example - Absolute Page References with SSI
9. Variable Handling from QUERY_STRING

SSI Overview

Server Side Includes are an Apache feature implemented by mod_include (see also this useful Apache article). Files which have the suffix .shtml (or whatever suffix name you use on the AddHandler server-parsed directive and its corresponding AddType text/html directive) are parsed by the server for SSI (or any file if the XBitHack directive is used). SSIs may be used for many purposes as may be seen from the descriptions and examples below. Our own use of SSIs may help illustrate their use:

• A single Page header file (including a page source comment)
• Conditional generation of CSS in-line data (depending on browser variables)
• Conditional generation of in-line Javascript (depending on browser variables)
• News sections on certain pages
• Left hand navigation on certain pages
• Right hand navigation on certain pages
• Standard footers on all pages (including copyright and page modified dates)
• Printer Friendly pages using conditionally generated CSS

NOTE: You cannot include SSI in a file named with a .php suffix (or whatever you have set your AddType values to for PHP) irrespective of the setting of XBitHack, instead use this technique.

Our goal is that with either a few simple changes to the CSS styles page and or the format of SSI included files we can change, more or less, the overall look and feel of the site very rapidly. SSIs offer, as well as the standard Apache environmental variables, additional SSI specific variables. These variables may be displayed at run time using the #printenv SSI element. Display them for our server using #printenv or the tidy PHP version.

Note: You can avoid the need to use .shtml file suffixes by the use of the XBitHack Apache Directive.

The SSI Elements

The generic format of an Apache SSI is:

<!--#element attribute=value attribute=value ... -->

There MUST NOT be a space between the '#element' and the second opening '-' and there MUST BE a space between the last character of the last 'attribute=value pair and the first closing '-'.

The element types are:

config element

Example

<!--#config ermsg="gottcha" timefmt="%c" -->

Changes the standard error message and outputs all date/times in 'locale' format.

include Element

Example

<!--#include virtual="../../styles.shtml" -->

Includes the file styles.shtml (which because it is named .shtml may contain additional SSI statements) in this parsed file.

Conditional Expresssions

SSI enables conditional processing using any of the environmental or user defined variables. SSI provides the following elements to support this feature:

Test Conditions Allowed

Important Note: The following syntax has been available since dinosaurs walked the earth - until Apache 2.3.13. From this release on it croaks and requires that you use this spiffy new format. However fear not, the SSILegacyExprParser on directive will restore the old processing syntax and mean that your decrepit old code (this includes us) will continue to work. The SSILegacyExprParser directive can be placed in either an .htaccess file or a <Directory> clause. So, for example, if you want to use the old conditional processing syntax across all webs (and what idiot is going to rewrite all their SSI just to move to a new version of apache) then you would typically place it in a Directory clause covering the root document (giving it the same scope as your Include parameter) as shown below:

DocumentRoot "/usr/local/www"
<Directory "/usr/local/www">
  ...
  #
  Options Indexes IncludesNOEXEC FollowSymLinks
  #
  SSILegacyExprParser on
  ...
</Directory>

Legacy (pre Apache 2.3.13) SSI test conditions

Notes:

1. If string2 is written /string2/ it is interpreted as a regular expression (see here), for example, /MSIE/ will find MSIE anywhere in string1.

2. Strings are enclosed in quotes thus, expr="${QUERY_STRING} = 'a=b'". Note: The syntax change in 2.3.13+ changes this expression form to expr="%{QUERY_STRING} = 'a=b'".

3. If either string1 or string2 is a variable then the following syntax must be used ${var_name} - using curly brackets or braces. Note: The syntax change in 2.3.13+ changes this expression form to %{var_name}.

4. test_condition1 or test_condition2 above may be substituted for any of the string1 string2 expressions above, thus very complex tests may be built up.

5. Ambiguity. If we want to test something, say a path that has the form /path/name, this would be interpreted as a regular expression (see note above). In order to stop this (to disambiguate in the jargon) we create a string and use an escape sequence to remove it, for example, \"/path/name\".

6. GCI variables. CGI variables contained in a QUERY_STRING are not initialised (unlike PHP etc.) before calling SSI. If you need to test such a variable, for instance, myform.html?a=b&c=d then you need to use the form expr="${QUERY_STRING} = /a=b/". Note: The syntax change in 2.3.13+ changes this expression form to expr="%{QUERY_STRING} = /a=b/".

7. Conditional nesting. Don't. you cannot nest SSI conditional statements.

Examples

<!--#if expr="${isJS}" -->
... code for Javascript ...
....
<!--#if expr="${isW3C}" -->
..... code for W3C DOM here ....
...
<!--#elif expr="${isIE}" -->
... code for MS DHTML DOM ....
....
<!--#else -->
... code for NS4.x DOM here ...
....
<!--#endif

The above implements the psuedo code shown above for processing Browser user defined variables.

set Element

Examples

<!--#set var="platform" value="Windows" -->
<!--#set var="real_mod_date" value="$LAST_MODIFIED" -->

Notes

1. The first example shows an explicit value (Windows) used to set the variable ($ not required).

2. The last example sets a user defined variable ('real_mod_date') to the environmental variable LAST_MODIFIED date of this file, we can now use this variable (using #echo) in, say, a standard footer. In this way we can get the last modified date for the 'real' file whereas if we used LAST_MODIFIED directly in our included footer file it would only change when we changed our footer file.

printenv Element

Prints (displays) a list of all the variables (environmental and user defined) and their values. It has no attributes:

<!--#printenv -->

Primarily used for de-bugging. Click here to display them for our server. Or if you want the tidy PHP version here.

echo Element

Examples

<!--#echo var="really" -->
<a href="<!--#echo var="HTTP_REFERER" -->">Go Back</a>
<a href="http://<!--#echo var="HTTP_HOST" -->/abs/ref.html">Hyperlink</a>

1. The first example displays a user defined variable which was previously set by SSI or Apache's BrowserMatch).

2. The second example illustrates that you can place SSI statements anywhere in your files. In this case using a dynamic back button to return to the calling page (OK so your Back button does the same thing - but with this technique you can save it in say, a mail page, and go back two pages at once (see here).

3. The last example is the trivial way we use to create absolute references without any work (on our part). We use it in all our page headers and it allows us to use a test site or our live site without changing anything, finally because it's absolute it will also work at any level in the directory structure etc. etc.). (example) Note: the 'http://' string is required because the $HTTP_HOST variable does not supply it - where HTTP_REFERER used in the previous example returns a full URL/URI.

exec Element

Example

<!--#exec cmd="ls" -->
<!--#exec cgi="../hitcounter.php" -->

The first line executes a listing of the current directory and displays the results. The second line executes the php script defined (this could also have been done using the #include variable above.

fsize Element

Example

<p>Download size=<!--#fsize file="download.zip" --></p>

Example illustrates use of the element for information.

flastmod Element

'last bath on <!--#flastmod file="mycousin.bath"  -->'

Example

<p>expenses updates <!--#flastmod virtual="../expenses.html" -->.</p>

Time and Date Format Codes

These are parameters to the well known ctime function and may take one or more of the following values:

You can place any number of the above symbols in an expression interspersed with formatting characters:

%A-%B,%Y %T e.g. Monday-July,2001 01:12:23

User Variables and Browser Type

We set global Apache variables that describe the client browser environment. If you want more info about what we do.

The psuedo code to process these variables is:

If isJS not set (FALSE)
   Exit no DHTML, CSS or Javascript support in browser
If isW3C set
   W3C CSS-2 and DOM supported
Else
   If isIE set
      MS DHTML DOM and CSS
   Else
      CSS and DOM are NS Javascript 1.3

We use these variables to generate browser specific javascript and CSS style sheets using SSI conditional elements in included files.

Example - Page Changed and Copyright Date in Footer

The page modified: and Copyright dates at the foot of every page on our site are generated by SSI in a single included footer file.

Each page on our site is laid out as shown below:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Apache - Server Side Includes</title>
<!-- include files covering page source, meta data, javascript, CSS and page banners -->

<body>

<!-- page body text in enclosing div -->
<div class="l-c">

stunning page content

</div>

<!-- include left and right menus -->

<!-- site wide footer -->
<!--#include virtual="../../templates/footer.shtml" -->
</body>
</html>

This is the contents of the included footer.shtml file (we've omitted all the formatting HTML 'cos it does not affect the technique - but use page source in your browser if you are insatiably curious) and it generates the end copyright year to reflect the current date and uses the real_date variable set in the parent page:

<!-- standard footer full width -->
<!-- set time format to 4 digit year  -->
<!--#config timefmt="%Y" -->
Copyright © 1994 - <!--#echo var="DATE_LOCAL" --> ZyTrax, Inc.
<!-- format date -->
<!--#config timefmt="%B %d %Y" -->
Page modified: <!--#echo var="LAST_MODIFIED" -->.

The LAST_MODIFIED variable is set for the page/url/uri requested by the user and is not modified to reflect any included files.

Example - Page Source Comment

We set a page source comment in every page using standard SSI elements and the variable HTTP_HOST and REQUEST_URI as shown in the following fragment. Why do we do it? - because it seemed like a good idea at the time. If you look at page source you will also see that we spell 'originated' incorrectly on almost every page (we fixed it on this page) - so much for a cut and paste technique!

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Apache - Server Side Includes</title>

<!-- page source statement -->
<!-- this page originated from http://<!--#echo var="HTTP_HOST" --><!--#echo var="REQUEST_URI" --> -->

<!-- include files covering meta data javascript, CSS and page banners -->

<body>

<!-- page body text in enclosing div -->
<div class="l-c">

stunning page content

</div>

<!-- include left, right menus and footer -->

</body>
</html>

Example - Absolute Page References with SSI

Relative references in href attributes typically take the form:

<a href="../tech">tech home</a><br>

Which is short but when you are including files requires a different include file for every level in the hierarchy since the relative reference changes.

To keep things simple we maintain single site wide files for menus that use absolute addressing generated by SSI as shown in the fragment below (which is the same as that shown above using relative addressing):

<a href="http://<!--#echo var="HTTP_HOST" -->/tech">tech home</a><br>

This works for any level in the hierarchy and on our test (pre-publish) site.

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.