oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Apache Web-Serving with Mac OS X: Part 2
Pages: 1, 2

Turning on server-side includes

Server-side includes, better known as SSIs, allow you to include content from other files or scripts into the page currently being served. This is done by Apache before the page is actually shown to the user -- they'll never know what you've included or where.

Commonly, SSIs are used to include things such as headers, footers, and "what's new" features across an entire site. When you need to change the background color of your site, for instance, you can change the header file only, and the color will be reflected immediately wherever you've included that file.

SSIs, by default, are turned off. To turn them on, we're going to use the same "search for the feature" trick we did above. Open your Apache configuration file, and search for "server side." Our only match grants us the following:

# To use server-parsed HTML files
# AddType text/html .shtml
# AddHandler server-parsed .shtml

Happily, this is exactly what we're looking for. Those simple "Add" lines tell us a lot. They establish a pattern based on what we already know about CGI. If you recall above, we could have turned on the CGI feature for files ending in .cgi -- in other words, any file you created with the .cgi extension (whether it was a CGI program or not), would be treated as an executable script.

Likewise, these lines are telling us that we can turn on the server-side include feature for files ending in .shtml. Whether we actually use the SSI feature in these files doesn't matter -- they'd still be treated and processed as if they did.

This is important. You may be thinking "If SSIs are so great, why not enable them for .html filenames?" Ultimately, it's a matter of speed. If you have 3,000 .html files, and only 1,000 of them actually use SSI, Apache will still look for SSI instructions in the other 2,000. That's a waste of resources. Granted, processing SSI incurs very little overhead, but if you're being hit 50,000 times a second, it can certainly add up. This isn't too worrisome for our GatesMcFarlaneCo intranet, but is good to know for your future Apache projects.

For now, uncomment the AddType and AddHandler lines. This will turn on the SSI mojo power. But where? When we were learning about CGI, we saw a configuration setting that said our CGIs lived in /Library/Webserver/CGI-Executables/ -- we now have to tell Apache where we want our SSI capability to take place.

Because we've building an intranet, that's going to live in /Library/Webserver/Documents, that's where we want our SSI capability to be active. Go to the top of your Apache configuration file and search for "/Library/Webserver/Documents/". The second result looks like the following (we've removed the commented lines from this example):

  <Directory "/Library/WebServer/Documents">
        Options Indexes FollowSymLinks MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all

You'll notice that this looks similar to the <Directory> entry we saw when we were looking into CGI. As before, we're going to skip the brunt of it (we'll pay attention to our ignored lines a little bit later in our series). For now, add the word Includes to the Options line. Options is an Apache directive that can turn on or off different features for the <Directory> and all subdirectories beneath it. Subdirectories can override their parent configuration.

Because we've made changes to Apache's configuration file, we now need to restart Apache. The easiest way to do this is via our Sharing preference panel. Much like we started the sharing preference in part one of this series, we can stop and start to enable our changes. Do this now. Chuckle once or twice, if you must.

To test that our SSIs are working properly, rename your index.html file to index.shtml (because .shtml is the only extension we've enabled SSIs for), and edit to match the snippet below:

  <h1>Gleefully Served By Mac OS X</h1>
    <pre><!--#include virtual="/cgi-bin/test-cgi"-->

Here, we're including the test CGI script into the contents of our main index page. When you load into your browser, you'll see our "Gleefully Served" message, as well as the output of the CGI script itself. We could just have easily created a static web page (say, "navigation.html"), and included that within our page instead.

SSI is configured and working, but what can you do with it? What if your marketing department wants to create an image gallery of the newest ads they've planned? That's quite easy using this SSI Image Gallery article, also written by yours truly.

In my next installment, I'll show you how to turn on PHP. Until then, good luck working with CGI. And if you have questions ... comment below and the author will get back to you.

Kevin Hemenway is the coauthor of Mac OS X Hacks, author of Spidering Hacks, and the alter ego of the pervasively strange Morbus Iff, creator of, which bills itself as "content for the discontented."

Return to the Mac DevCenter.