Picking through the documentation for the Apache HTTP Server is a bit like wandering around a once-advanced, though now neglected, spaceship. Great capabilities are buried 'neath the dusty control panel, but there is not much fresh guidance on how to make it work. You copy and paste your way to a working runtime, fingers crossed.
"If a majority of your page is being generated at the time that it is served, you need to look for some other solution," the doc dryly suggests.
So, in short, few sites, that I know of anyway, still use SSI. I suspect this from the lack of the documentation and general paucity of troubling-shooting questions about SSI on sites like StackOverflow. Most of the documentation can be found on the web was lifted in large chunks from the Apache documentation itself, which in itself, somewhat obtuse in spots. And the general user forum questions are usually a decade old or more. Add to this how if something doesn't work, Apache just won't start, and hide its errors in a log file you have to go look for.
Nonetheless, in the best wisdom I could muster for 2007, I rebased my Web site on SSI. I used it mostly for Chrome, the headers and footers and indexes on each page. With SSI, I could keep one reference file for the header and footer, rather than replicating that information on each Web page itself. And now, here in 2020, in the process of upgrading my OS ( thanks for the years of service, CentOS), I have to relearn how to set up SSI again on the new machine. I'm nervious about entering this murky territory once again. BUt here is what I learned setting up SSI again...
How SSI Works
Here's the format needed to insert a external file into an HTML document at runtime:
<!--#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 an 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 on the screen. It will just show up in the source code. And if SSI is working correctly, the command won't appear at all in the source code. In its place will be the actual thing you wanted embedded.
Example! The file "sample.html" has this code:
<html> <body> <!--#include virtual="add.txt"--> <p> I'm some text too! </body> </html>
And,in the same directory, a text file called "add.txt" has this content:
Hello World! <p> HELLO!
When requested by a user, "sample.html" will be returned by the Apache server with this code:
<html> <body> Hello World! <p> HELLO! <p> I'm some text too! </body> </html>
SSI can not only insert plain text, but all sorts of things, like the date, when the document was last modified, or even the output of a shell or other program. It can even set variables and evaluate conditional expressions, though the docs does warn that it is "certainly not a replacement for CGI." These capabilities are beyond the scope of this tut, though they are certainly worth exploring.
Nice, right? You have to make a few configuration changes to Apache software to make SSI happen though.
First, you have to have the "include" module in Apache. The Include module does the SSI for Apache.
Include is included by default on many installs, but check if it is there by the command: apachectl -M.
If not, you can run the a2enmod tool from the command line. When it asks which module to enable, type in "include"--then restart Apache ("systemctl reload apache2"). This is for the Debian/Ubuntu servers running Apache. Work out your own fave distro's way of doing these things.
SSI was set up originally to parse '.shtml' files, But no one actually uses .shtml any longer. Still, the entire configuration is built around .shtml, go figure. The documentation sternly warns you against the idea of Apache running SSI against parsing *all* HTML pages by default, cautioning it may take up many resources and slow response time. But again, this documentation is a few decades old, so...
So you have to 'tell' Apache that you want to use the Include module. You can instruct Apache in one of two places, One option is to include a line into an .htaccess file. The file .htaccess is a way to apply a set of rules only for the directory that .htaccess sits on top of. It is kept in the root directory of your web site. Here is what to add, on its own line:
That's one way to do it, but it is a practice discouraged by the Apache folks. Instead, you should put that directive:
... in a configuration file, httpd.conf, perhaps, usually located in the /etc/apache2 directory on your server (In CentOS, it is under /etc/httpd/conf). The documentation totally omits exactly how to include it in the configuration file though. So, maybe this is a good place to discuss how Apache works with configuration instructions.
httpd.conf is a series of cascading configurations, recorded in something called section containers, from the top level web directory on down. They are nested where each subdirectory can get its own set of permissions that override upper-level directives.
So, for the specific directory you want to run SSI on, you would have:
<Directory "var/www"> AllowOverride None Options +Includes </Directory>
After this, you need to add yet another directive. I'm not complaining, you're complaining. To get around the .shtml convention no one uses, add "XBitHack Full" directive. This directive allows Apache to parse files with the execute ("x") bit on.
Again, you could place this in the appropriate .htaccess file, on its own line:
"Options +Includes" XBitHack full
Or, place it is the configuration file, just under the "Options +Includes" line:
<Directory "var/www"> "Options +Includes" XBitHack full </Directory>And when using XBitHack, you need to give execution permissions every Web page that you want to embed with additional content. At the command line, in the directory, type:
chmod +x pagename.html
One more tip: While testing, if your SSI page is not working yet, try emptying the cache on your browser.
All the Art: Robots Will Kill, NYC.