29.9. Setting Up Server-Side Includes
Server-side includes allow you to create simple dynamic web pages without the complexity of writing an entire CGI program in a language like Perl. When active, some of the HTML files served by Apache are checked for special tags starting with <!--. The content of each tag is then replaced by dynamically generated text that depends on the tag's parameters and the resulting page is sent to the web browser.
The most common use of server-side includes is incorporating the contents of one HTML page into another. This can be useful if you have a common header or footer that you want to share among multiple pages without repeating it over and over again. Where a special tag like <!--include file=“something.html” --> appears in the HTML of the page, it is replaced with the contents of the file something.html.
Server-side includes can also be used to access and set environment variables, to conditionally display HTML based on variables, and to run CGI programs or shell commands and have their output included in the page. This section will not cover the tags that are available and their purposes. For more information on tags, read the documentation on the Apache website or a good book on HTML.
Normally, allowing untrusted users to create HTML pages containing server-side include tags is perfectly safe because they cannot be used to perform potentially dangerous operations like editing files on the server. The exception to this is the <!--#exec --> tag, which can be used to run an arbitrary shell command and include its output in the web page. Because the command runs as the UNIX user as whom Apache is running (normally httpd), a user who is not allowed to create CGI programs may be able use this kind of tag to read or modify files that he would not normally be able to access. For this reason, Apache can be configured to enable server-side includes with or without the risky exec tag.
Because checking an HTML file for server-side include tags is CPU-intensive, they are often only activated for files with the .shtml extension. This way you can put static HTML in .html files and dynamic content into .shtml files so the server does not have to waste time looking for tags in files in which they do not exist. You can also check all .html files for server-side includes if you wish.
To turn on includes for a virtual server, follow these steps:
1. | On the module's main page, click on the icon of the virtual server on which you want to enable server-side includes. Or, click on the Default Server icon to enable them for all virtual hosts. |
2. | Click on the icon for the directory under which you want server-side includes to be enabled. Typically, each virtual server will have an options icon for its document root directory. If not, you can create one by following the steps in Section 29.6 “Setting Per-Directory Options”. If you only want to enable server-side includes in a subdirectory of the website, you can create a new directory icon for that as well. |
3. | On the directory options page, click on the Document Options icon and change the Directory options field from Default to Selected below. If you want to enable server-side includes without the exec tag, change the Server-side includes row to Yes. If you want to enable the potentially risky exec tag as well, change Server-side includes and execs row to Yes. Either way, when they have been enabled, click the Save button at the bottom of the page. |
4. | Click on the MIME types icon on the directory options page. If you want to enable includes on all HTML files, find the Content handlers table and select server-parsed from the first empty menu under the Handler column. Enter .html into the field next to it under the Extensions column. This tells Apache that files ending in .html should be checked for server-side include tags. If you want to enable includes for only .shtml files, enter .shtml instead of .html under the Extensions column. In the Extra MIME types table, enter text/html into the first empty field under the Type column and .shtml into the field under Extensions next to it. This tells Apache that .shtml files should be checked for server-side include tags and that they actually contain HTML. |
5. |
Once server-side includes are enabled, you can test them by creating an .html or .shtml file in the chosen directory with some special tags it in. Then, open the page in your web browser to see the result. If for some reason server-side includes were not enabled properly, nothing will show up at all because the <!-- tag indicates an HTML comment. If, however, the tag is replaced by the message an error occurred while processing this directive, then includes are active but there is an error in the tag's parameters. More details will be written to the Apache error log file (described in Section 29.8 “Running CGI Programs”) if an error of this kind occurs.
There is another method of indicating to Apache that certain HTML files should have server-side include processing performed on them. The web server can be configured so that any .html file with the UNIX execute permission set is processed for include, by following these steps (you can set this permission with a command like chmod +x file.html).
1. | Follow Steps 1 through 3 of the preceding instructions to enable server-side includes for some directory. |
2. | On the directory options page, click on the CGI Programs icon. |
3. | On the page that appears, change the Process includes on files with execute bit? field to Yes. You can also set it to Yes and set last-modified date to have Apache read the modification time for each processed HTML file and use that to set the Last-Modified HTTP header. |
4. | Click the Save button at the bottom of the CGI Programs page and then the Apply Changes link on any page. |
You should now be able to set execute permissions on HTML files in the directory, and Apache will parse them for server-side include tags when they are requested. This allows you to selectively turn on include processing, while avoiding the problem of having to rename a file (and break links) just because it now contains include tags.