book musings



missle defense



cultcha blog


scripts & programs

on the town



creds (PDF)



Apache: Server-Side Includes

For some time I've been thinking about putting all my Web pages in a standard template, one that would have with links running down one side of the page and a title on the top (This is called chrome, so I understand).

I could embed these elements by hand easily enough on each page, but if I ever needed to make a change to the chrome, I would then have to go back and change each and every page. I figured there must be a way to have a single file somewhere with one the code, which then could be read for each page being served up.

After some surfing about, I found the best way to do this, at least in Apache, is with Server Side Includes (SSI).

In a nutshell, SSI is a server-side scripting language that tells Apache to include a file or set of files into a Web page. (There is actually a whole range of things that can be inserted in a Web page with SSI. For simplicity, I'll just concentrate on including all the contents of another file).

And example of the basic use of the command for including a file in a Web page is:

<!--#include virtual="PageToBeIncluded.txt"-->
You embed this bit of text into the place on your Web page where you want the text to be inserted. Then when the page is called, Apache will insert the text at that point of the document.

Note that the SSI command is included as a *HTML Comment* -- This is done so that if the server doesn't render the page correctly, the user won't see the actual SSI command.

So, at its simplest, here is an example of how SSI works. One file, "sample.html", has this code:

<!--#include virtual="add.txt"-->
I'm some text too!
And, in the same directory, a text file called "add.txt" has this content:
Hello World!
When requested by a user, "sample.html" will be returned by the Apache server with this code:
Hello World!
I'm some text too!
Not only plain text, but HTML markup can be inserted as well. * * * In order to use SSIs, you may have to make a number of changes to your setup of Apache.

The first thing to do is compile the "include" module into Apache, if it isn't already.

For Debian/Ubuntu servers running Apache, you can run the a2enmod tool from the command line. When it asks which module to enable, type in "include"--then restart Apache ("/etc/init.d/apache2 restart").

In addition to adding the include module, you should also make a few changes to your configuration files, as detailed here.

First, you should add a line into either a .htaccess file or the httpd.conf file. The line is "Options +Includes" The httpd.conf file is in the etc/apache2 directory on your server. If you haven't created an .htaccess file before, you can create one in the root directory of your Web site, or whatever subdirectory below that where you want all the SSI action to take place.

Also, you should add another directive into the default config file of the "/etc/apache2/sites-enabled" folder (mine is "000-default"). The directive is "XBitHack Full" -- the (somewhat convoluted) explanation for why you need to do this is here.

Again, within this file, find, or write, an entry for the specific folders where you want the SSI actions to take place, if it isn't for the entire site (in which case you'd use the entry for the document root directory). For the document root entry, for instance, you would add it thusly:

DocumentRoot /var/www/
<Directory />
      Options FollowSymLinks
      AllowOverride All
      XBitHack full
</Directory />
Lastly, the SSI tutorial advises that, if using XBitHack, to add execution permission to the Web page that is being embedded with another file:
chmod +x pagename.html 
One more tip: While testing, if your SSI page is not working yet, try emptying the cache on your browser.