Server-side Includes (ssi)

I have used SSI in the past on our servers for a couple of sites I designed. In both cases I followed the standards for SSI and had no problems. DO NOT set it up for all HTML files to be parsed - you will impact the server load and if your site has a large volume of users you will end up needing a semi-dedicated server. It is not an effective or standard way of using SSI.

Also make sure the directories & files you want included using SSI are chmoded to 755 or they will not work.

When you use SSI, you're putting your site's security at risk. If you decide to use them, understand the risks involved and guard against them.

The vulnerability lies primarily in using SSI to execute programs on the server with the "virtual" and "exec" directives. Once you open the door to allow the server to execute files, you've opened it enough for visitors to potentially direct the server to disclose private information or issue commands that could destroy your system.

Set file permissions conservatively. The server will parse HTML files in directories with permissions set to "read/write" for the User (the server is designated User to be able to carry out commands) and read for all others. In UNIX this is permission level 644.

Any programs you wish to execute using SSI statements should be isolated to executable directories only, such as CGI-BIN. File permissions for these directories must be set to "read/write/execute" for the User, all others "read/execute" (UNIX permission level 755) or the program will not run.

By default, the server does not bother looking in HTML files for the SSI commands. This would slow down every access to a HTML file. To use SSI you need to tell Apache which documents contain the SSI commands.

One way to do this is to use a special file extension. .shtml is often used, and this can be configured with this directive:

AddHandler server-parsed .shtml
AddType text/html shtml

The AddHandler directive tells Apache to treat every .shtml file as one that can include SSI commands. The AddType directive makes such that the resulting content is marked as HTML so that the browser displays it properly.

The SSI Format
All directives to the server are formatted as SGML comments within the document. This is in case the document should ever find itself in the client's hands unparsed. Each directive has the following format:



Each command takes different arguments, most only accept one tag at a time. Here is a breakdown of the commands and their associated tags:

* config

The config directive controls various aspects of the file parsing. There are two valid tags:

o errmsg controls what message is sent back to the client if an error includes while parsing the document. When an error occurs, it is logged in the server's error log.

o timefmt gives the server a new format to use when providing dates. This is a string compatible with the strftime library call under most versions of UNIX.

o sizefmt determines the formatting to be used when displaying the size of a file. Valid choices are bytes, for a formatted byte count (formatted as 1,234,567), or abbrev for an abbreviated version displaying the number of kilobytes or megabytes the file occupies.

* include

include will insert the text of a document into the parsed document. Any included file is subject to the usual access control. This command accepts two tags:

o virtual gives a virtual path to a document on the server. You must access a normal file this way, you cannot access a CGI script in this fashion. You can, however, access another parsed document.

o file gives a pathname relative to the current directory. ../ cannot be used in this pathname, nor can absolute paths be used. As above, you can send other parsed documents, but you cannot send CGI scripts.

* echo prints the value of one of the include variables (defined below). Any dates are printed subject to the currently configured timefmt. The only valid tag to this command is var, whose value is the name of the variable you wish to echo.

* fsize prints the size of the specified file. Valid tags are the same as with the include command. The resulting format of this command is subject to the sizefmt parameter to the config command.

* flastmod prints the last modification date of the specified file, subject to the formatting preference given by the timefmt parameter to config. Valid tags are the same as with the include command.

* exec executes a given shell command or CGI script. It must be activated to be used. Valid tags are:

o cmd will execute the given string using /bin/sh. All of the variables defined below are defined, and can be used in the command.

o cgi will execute the given virtual path to a CGI script and include its output. The server does not perform error checking to make sure your script didn't output horrible things like a GIF, so be careful. It will, however, interpret any URL Location: header and translate it into an HTML anchor.

SSI Environment Variables
A number of variables are made available to parsed documents. In addition to the CGI variable set, the following variables are made available:

* DOCUMENT_NAME: The current filename.

* DOCUMENT_URI: The virtual path to this document (such as /docs/tutorials/foo.shtml).

* QUERY_STRING_UNESCAPED: The unescaped version of any search query the client sent, with all shell-special characters escaped with \.

* DATE_LOCAL: The current date, local time zone. Subject to the timefmt parameter to the config command.

* DATE_GMT: Same as DATE_LOCAL but in Greenwich mean time.

* LAST_MODIFIED: The last modification date of the current document. Subject to timefmt like the others