View source for Apache 2.2 Server Side Includes

Server Side Includes (SSI) is designed for use as interpreted scripts to generate dynamic content, unlike a static web page.  SSI is often used to include the contents of one or more files into a web page on a web server.   The web file must be parsed by the web server for SSI content to be generated.  SSI programming code script within an HTML document is parsed by Apache dependent on how Apache is configured on the web server.

Apache can be configured to process all html documents for any possible SSI within.  However, this is inefficient and not recommended due to the significant performance hit.  Either the filename should end with a special extension, by default .shtml, .stm, .shtm, or, if the server is configured to allow this, set the execution bit of the file.

== Configure Apache to Permit SSI ==

To permit SSI on your server, you <del>must</del> can have the following directive either in your httpd.conf file, or in a .htaccess file:

 Options +Includes

or there is another option.  The above directive '''IS NOT NECESSARY''' if using something like the following:

 <Directory "/usr/local/www">
    Options Indexes FollowSymLinks MultiViews '''Includes'''
    AllowOverride None
    Order allow,deny
    Allow from all
 </Directory>

If the /usr/local/www is your document root "DocumentRoot" then the above will enable SSI for it and sub directories.  The "Options Includes" is what makes it happen, the rest is included as other example directives. Virtual directories in other paths will not allow SSI.  Most configurations contain multiple Options directives that can override each other. You will probably need to apply the Options to the specific directory where you want SSI enabled.

Tell Apache which files should be parsed. There are two ways to do this. You can tell Apache to parse any file with a particular file extension, such as .shtml, with the following directives:

 AddType text/html .shtml
 AddOutputFilter INCLUDES .shtml

If you wanted to add SSI directives to an existing page that has an .html extension rather than .shtml, you have to change the file extension of that page to .shtml and all links to that page.  

The option of using AddType text/html .html is NOT RECOMMENDED.  It will work, however, it will cause a performance hit.  It you configure Apache to parse all .html files for SSI, you're requiring that Apache read through every single file that it sends out to clients, even if they don't contain any SSI directives.  This will use a lot more CPU cycles and slow down content delivery.  

Rather than require .shtml extension, you can also make it work with .html and avoid the performance impact by utilizing a method called the XBitHack directive:

 XBitHack on

XBitHack tells Apache to parse files for SSI directives only if they have the execute bit set. An existing html page can be made to allow processing by Apache based on the file permissions rather than file extensions.  So, to make an existing html page be parsed, simply add the executable bit using the chmod command.

 chmod +x index.html

Pages that are -x will not be parsed, and in this case, the now executable index.html page will be parsed for SSI content.  This is a UNIX / Linux option that will not work on Apache on Microsoft Windows.  

In its default configuration, Apache does not send the last modified date or content length HTTP headers on SSI pages, because these values are difficult to calculate for dynamic content. This can prevent your document from being cached, and result in slower perceived client performance. There are two ways to solve this:

* Use the XBitHack Full configuration. This tells Apache to determine the last modified date by looking only at the date of the originally requested file, ignoring the modification date of any included files.
* Use the directives provided by mod_expires to set an explicit expiration time on your files, thereby letting browsers and proxies know that it is acceptable to cache them.

== The exec Element ==

You might see the following error in your error_log

 mod_include: Options +Includes (or IncludesNoExec) wasn't set, INCLUDES filter removed

Use "Options IncludesNoExec" to resolve.  The exec command executes a given shell command or CGI script. Options IncludesNOEXEC disables this command completely so the server-side includes module cannot execute commands. It is recommended you do not use the Includes option but instead use IncludesNoExec.  

Example:
 Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec

Security issue: if the system is configured with "AllowOverride Options=IncludesNoEXEC", a local user can place "Options Includes" in a '.htaccess' file to cause Server Side Includes to be enabled with exec privileges.  This is verified on Apache version 2.2.11 as a reported vulnerability.

The exec command could potentially enable an attacker to execute commands on the system.  The exec command requires mod_cgi to be present in the server.

 <nowiki><!--#exec cgi="/cgi-bin/example.cgi" --></nowiki> 

 <nowiki><!--#include virtual="/cgi-bin/example.cgi?argument=value" --></nowiki> 

 <nowiki><!--#exec cmd="perl /path/to/perlscript arg1 arg2" --></nowiki> 

The include virtual element should be used in preference to exec cgi.

[[Category:Computer_Technology]]
[[Category:Linux]]
[[Category:Security]]
[[Category:Apache]]

keywords: Server Side Includes SSI ssi CGI cgi shtml perl c