NCSA httpd server side includes

NCSA httpd allows users to create documents which provide simple information to clients on the fly. Such information can include the current date, the file's last modification date, and the size or last modification of other files. In its more advanced usage, it can provide a powerful interface to CGI and /bin/sh programs.


Issues

Having the server parse documents is a double edged sword. It can be costly for heavily loaded servers to perform parsing of files while sending them. Further, it can be considered a security risk to have average users executing commands as the server's User. If you disable the exec option, this danger is mitigated, but the performance issue remains. You should consider these items carefully before activating server-side includes on your server.


Setting Up Includes

First, you should decide which directories you want to allow Includes in. Most likely this will not include users' home directories or directories you do not trust. You should then decide, of the directories you are allowing includes in, which directories are safe enough to use exec in.

For the directories in which you want to fully enable includes, you need to use the Options directive to turn on the option Includes. Similarly for the directories you want crippled (no exec) includes, you should use the option IncludesNOEXEC. In any directory you want to disable includes, use the Options directive without either option.

Next, you need to tell the server what filename extension you are using for the parsed files. These files, while very similar to HTML, are not HTML and are thus not treated the same. Internally, the server uses the magic MIME type text/x-server-parsed-html to identify parsed documents. It will then perform a format conversion to change these files into HTML for the client. To tell the server which extension you want to use for parsed files, use the AddType directive. For instance:

AddType text/x-server-parsed-html .shtml
This makes any file ending with .shtml a parsed file. Alternatively, if you don't care about the performance hit of having all .html files parsed, you could use:

AddType text/x-server-parsed-html .html
This would make the server parse all .html files.


Converting your old INC SRV documents to the new format

You should use the program inc2shtml in the support subdirectory of the httpd distribution to translate your documents from httpd 1.1 and earlier to the new format. Usage is simple: inc2shtml file.html > file.shtml.


The Include 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:

<!--#command tag1="value1" tag2="value2" -->

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


Variables defined for Parsed Documents

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


Return to tutorial index