ERROR: Why doesn't SSI work in my Apache2
webserver? -PROBLEM SOLVED

Contents:
-Problem description
-Solution Part 1
-Solution Part 2
-Further Thoughts
-Footnotes

Problem description ↑

Following the configuration instructions found on the Apache httpd website "Tutorial: Introduction to server Side Includes" ¹ I configured Apache2 to parse my webpage files for server side includes (SSI), rudimentary script directives that allow simple actions to be performed on the webpage before the final page is served up to a client. After having followed the instructions, Apache2 was still not parsing the pages before serving them.

The process described was as follows:

1. Include the following directive in the httpd.conf file, which for my debian installation this file was (/etc/apache2/apache2.conf):

Options +Includes

2. Add to the same configuration file the following instructions to tell Apache which files to parse (in this case ".shtml" files):

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

or alternatively add:

XBitHack On

...if you want to Apache to parse ".html" files instead by setting the execute bit set on files you want Apache2 on a non-windows server to parse with the following command:

> sudo chmod +x <pagename>.html

3. Restart Apache: in my case:

> sudo service apache2 restart

4. Include a directive in a file.shtml such as

<!--#echo var="DATE_LOCAL" -->

...to test the installation. If all works well, apache should parse the file and replace the SSI directive with the local date, (e.g. Tuesday, 15-Jan-2013 19:28:54 EST).

In my case the directive did NOT seem to be parsed?!"

Solution Part 1 ↑

The tutorial is anything but complete when it comes to telling us how to set up SSI under Apache2. The first thing, which might seem obvious to people familiar with Apache but not to the rest of us mere mortals, is that in order for Apache2 to parse and act on server side includes, an add-on module, unsurprisingly named "includes", must be enabled. This is accomplished by issuing the following command:²

> sudo a2enmod include

which creates a symlink in the mods-enabled directory of the corresponding module config file in the mods-available directory. (N.B. It should go without saying that the module "include" must, as it usually is by default, be found in the mods-available directory.)

Solution Part 2 ↑

Needless to say enabling the "include" module was not sufficient in my setup to get SSI working under Apache2. The last important change, which again was not explained in the Apache tutorial on SSI - How to, was how to add the Options +Includes to the Apache2 configuration file. I naively assumed we just add it in by itself at the end of the config file along with the other two directives and voila ... all would work normally. No such luck. Another user ³ with similar problems found that it had to be encapsulated like this:

<Directory /var/www/*>
    Options +Includes
    AddType text/html .shtml
    AddOutputFilter INCLUDES .shtml
</Directory>

Now everything started working as expected. I suppose one of my mistakes was to just rely on an Apache tutorial and thinking that it would be sufficient. If I had read the "include module" documentation ⁴ it would have pointed out that the configuration directives had to be encapsulated within a specific directory section ⁵ which Apache2 would look to when deciding whether or not to parse a file before sending it to a client.

Further thoughts ↑

I suppose my main complaint is the incomplete nature of essential steps in the Apache tutorial which I had relied upon to get me started.

A bon entendeur ... salut! (A rough translation from french: A word to the wise is hopefully all that will be necessary. ;-)

Michael Wells - 06 May 2013

Footnotes ↑