From: Rich Bowen Date: Fri, 19 Jun 2026 14:26:22 +0000 (+0000) Subject: docs: howto/ssi.xml complete rewrite for style and tone X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=49b44f5654eeeb5068681c40a849e43278770b2d;p=thirdparty%2Fapache%2Fhttpd.git docs: howto/ssi.xml complete rewrite for style and tone - Full rewrite for style guide compliance and tone normalization - Remove all first-person ("I'll talk about...") - Remove TeX-style ``quoting'' throughout - Remove dated references (hit counters, guestbooks, Win32) - Reposition as "a practical, lightweight technique" - Remove duplicated content between summary, body, and conclusion - Fix bare "Apache" → "httpd" - Update example date to 2026 - Add wrappers around all blocks git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1935522 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/howto/ssi.xml b/docs/manual/howto/ssi.xml index 0ce9d7d100..78f139705a 100644 --- a/docs/manual/howto/ssi.xml +++ b/docs/manual/howto/ssi.xml @@ -26,8 +26,10 @@ Apache httpd Tutorial: Introduction to Server Side Includes -

Server-side includes provide a means to add dynamic content to -existing HTML documents.

+

Server Side Includes (SSI) provide a way to add dynamic content to +existing HTML documents without requiring a full application framework. +They are particularly useful for inserting common elements — headers, +footers, navigation, timestamps — into otherwise static pages.
What are SSI? -

SSI (Server Side Includes) are directives that are placed in - HTML pages, and evaluated on the server while the pages are - being served. They let you add dynamically generated content to - an existing HTML page, without having to serve the entire page - via a CGI program, or other dynamic technology.

+

SSI directives are HTML comments with a specific syntax that + mod_include recognizes and evaluates before the + page is sent to the client. They look like this:

-

For example, you might place a directive into an existing HTML - page, such as:

- - - <!--#echo var="DATE_LOCAL" --> - + + +<!--#echo var="DATE_LOCAL" --> + + -

And, when the page is served, this fragment will be evaluated and replaced with its value:

+

When the page is served, this fragment is replaced with its + value:

- Tuesday, 15-Jan-2013 19:28:54 EST + Thursday, 18-Jun-2026 14:22:07 EDT -

The decision of when to use SSI, and when to have your page - entirely generated by some program, is usually a matter of how - much of the page is static, and how much needs to be - recalculated every time the page is served. SSI is a great way - to add small pieces of information, such as the current time - shown - above. But if a majority of your page is being generated at the time - that it is served, you need to look for some other solution.

+

Because the directives are embedded in HTML comments, if SSI + is not enabled, browsers ignore them (though they remain + visible in the page source).

Configuring your server to permit SSI -

To permit SSI on your server, you must have the following - directive either in your httpd.conf file, or in a - .htaccess file:

+

To enable SSI processing, add the following directive to your + httpd.conf file or to a .htaccess + file:

+ + Options +Includes + + +

This tells httpd to parse files for SSI directives. Since most + configurations contain multiple Options directives that can override each other, apply + this to the specific directory where you want SSI enabled.

+ +

You also need to tell httpd which files to parse. There are + two common approaches.

+ +

The first is to designate a file extension (typically + .shtml) for SSI-enabled pages:

-

This tells Apache that you want to permit files to be parsed - for SSI directives. Note that 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 in order to assure that it gets evaluated last.

- -

Not just any file is parsed for SSI directives. You have to - 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 + -

One disadvantage to this approach is that if you wanted to - add SSI directives to an existing page, you would have to - change the name of that page, and all links to that page, in - order to give it a .shtml extension, so that those - directives would be executed.

+

The disadvantage here is that adding SSI to an existing page + requires renaming the file (and updating all links to it) to use + the .shtml extension.

-

The other method is to use the The second approach uses the XBitHack directive:

+ + XBitHack on + + +

XBitHack tells + httpd to parse any file that has its execute bit set. To enable + SSI on an existing page, make the file executable:

-

XBitHack - tells Apache to parse files for SSI - directives if they have the execute bit set. So, to add SSI - directives to an existing page, rather than having to change - the file name, you would just need to make the file executable - using chmod.

- chmod +x pagename.html + +chmod +x pagename.html + -

A brief comment about what not to do. You'll occasionally - see people recommending that you just tell Apache to parse all - .html files for SSI, so that you don't have to - mess with .shtml file names. These folks have - perhaps not heard about XBitHack. The thing to - keep in mind is that, by doing this, 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 - can slow things down quite a bit, and is not a good idea.

- -

Of course, on Windows, there is no such thing as an execute - bit to set, so that limits your options a little.

- -

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:

+

+ Avoid configuring httpd to parse all .html + files for SSI directives. This forces the server to read through + every HTML file it serves, even those without any SSI content, + which adds unnecessary overhead. +

+ +

On Windows, there is no execute bit, so the + XBitHack approach is + not available. Use the file-extension method instead.

+ +

By default, httpd does not send the last-modified date or + content-length headers on SSI pages, since these values are + difficult to calculate for dynamic content. This can prevent + caching and result in slower perceived performance. Two + approaches can help:

    -
  1. 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.
    2. - -
  2. 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.
    3. +
  3. Use XBitHack Full, which tells httpd to + determine the last-modified date from the originally requested + file, ignoring the modification dates of included files.
    4. + +
  4. Use mod_expires to set an explicit + expiration time, letting browsers and proxies know the content + is safe to cache.
Basic SSI directives -

SSI directives have the following syntax:

+

SSI directives use the following syntax:

- <!--#function attribute=value attribute=value ... --> + +<!--#function attribute=value attribute=value ... --> + -

It is formatted like an HTML comment, so if you don't have - SSI correctly enabled, the browser will ignore it, but it will - still be visible in the HTML source. If you have SSI correctly - configured, the directive will be replaced with its - results.

- -

The function can be one of a number of things, and we'll talk - some more about most of these in the next installment of this - series. For now, here are some examples of what you can do with - SSI

+

If SSI is correctly configured, the directive is replaced with + its output. If not, it remains as an HTML comment — invisible to + the end user but present in the source.

Today's date - <!--#echo var="DATE_LOCAL" --> + +<!--#echo var="DATE_LOCAL" --> + -

The echo function just spits out the value of a - variable. There are a number of standard variables, which - include the whole set of environment variables that are - available to CGI programs. Also, you can define your own - variables with the set function.

+

The echo function outputs the value of a variable. + Standard variables include the full set of environment variables + available to CGI programs, plus variables you define with + set.

-

If you don't like the format in which the date gets printed, - you can use the config function, with a - timefmt attribute, to modify that formatting.

+

To customize the date format, use the config + function with the timefmt attribute:

- <!--#config timefmt="%A %B %d, %Y" -->
- Today is <!--#echo var="DATE_LOCAL" --> + +<!--#config timefmt="%A %B %d, %Y" -->
+Today is <!--#echo var="DATE_LOCAL" --> +
Modification date of the file - This document last modified <!--#flastmod file="index.html" --> + +This document last modified <!--#flastmod file="index.html" --> + -

This function is also subject to timefmt format - configurations.

+

This function is also subject to timefmt + configuration.

Including the results of a CGI program -

This is one of the more common uses of SSI - to output the - results of a CGI program, such as everybody's favorite, a ``hit - counter.''

+

SSI can include the output of a CGI program directly in the + page:

- <!--#include virtual="/cgi-bin/counter.pl" --> + +<!--#include virtual="/cgi-bin/counter.pl" --> +
@@ -237,243 +233,212 @@ XBitHack on
Additional examples -

Following are some specific examples of things you can do in - your HTML documents with SSI.

+

The following are practical examples of common SSI use + cases.

-
When was this document -modified? +
When was this document modified? -

Earlier, we mentioned that you could use SSI to inform the - user when the document was most recently modified. However, the - actual method for doing that was left somewhat in question. The - following code, placed in your HTML document, will put such a - time stamp on your page. Of course, you will have to have SSI - correctly enabled, as discussed above.

- - <!--#config timefmt="%A %B %d, %Y" -->
- This file last modified <!--#flastmod file="ssi.shtml" --> - +

A common use of SSI is to display a "last modified" timestamp + on each page. The following code uses the + LAST_MODIFIED variable so you can paste the same + snippet into any file without changing the filename:

-

Of course, you will need to replace the - ssi.shtml with the actual name of the file that - you're referring to. This can be inconvenient if you're just - looking for a generic piece of code that you can paste into any - file, so you probably want to use the - LAST_MODIFIED variable instead:

- <!--#config timefmt="%D" -->
- This file last modified <!--#echo var="LAST_MODIFIED" --> + +<!--#config timefmt="%D" -->
+This file last modified <!--#echo var="LAST_MODIFIED" --> + -

For more details on the timefmt format, go to - your favorite search site and look for strftime. The - syntax is the same.

+

For details on timefmt format strings, see the + documentation for strftime in your system's C + library reference.

-What else can I config? +Other config options -

In addition to being able to config the time - format, you can also config two other things.

+

In addition to timefmt, the config + function supports two other attributes.

-

Usually, when something goes wrong with your SSI directive, - you get the message

+

The errmsg attribute changes the error message + displayed when an SSI directive fails. The default is:

- [an error occurred while processing this directive] +[an error occurred while processing this directive] -

If you want to change that message to something else, you - can do so with the errmsg attribute to the - config function:

+

You can replace it with something more appropriate for your + site:

- <!--#config errmsg="[It appears that you don't know how to use SSI]" --> + +<!--#config errmsg="[Content unavailable]" --> + -

Hopefully, end users will never see this message, because - you will have resolved all the problems with your SSI - directives before your site goes live. (Right?)

- -

And you can config the format in which file - sizes are returned with the sizefmt attribute. You - can specify bytes for a full count in bytes, or - abbrev for an abbreviated number in Kb or Mb, as - appropriate.

-
+

The sizefmt attribute controls how file sizes + are formatted: bytes for a full byte count, or + abbrev for an abbreviated form in KB or MB.

+
Executing commands -

Here's something else that you can do with the exec - function. You can actually have SSI execute a command using the - shell (/bin/sh, to be precise - or the DOS shell, - if you're on Win32). The following, for example, will give you - a directory listing.

- - <pre>
- <!--#exec cmd="ls" -->
- </pre> - +

The exec function can run a shell command and + include its output in the page. On Unix-like systems, the + command is executed via /bin/sh; on Windows, via + the command shell.

-

or, on Windows

- <pre>
- <!--#exec cmd="dir" -->
- </pre> + +<pre> +<!--#exec cmd="ls" --> +</pre> + -

You might notice some strange formatting with this directive - on Windows, because the output from dir contains - the string ``<dir>'' in it, which confuses - browsers.

- -

Note that this feature is exceedingly dangerous, as it will - execute whatever code happens to be embedded in the - exec tag. If you have any situation where users - can edit content on your web pages, such as with a - ``guestbook'', for example, make sure that you have this - feature disabled. You can allow SSI, but not the - exec feature, with the IncludesNOEXEC - argument to the Options directive.

-
+

+ The exec feature is a significant security risk. It + executes arbitrary commands with the permissions of the web + server process. If users can edit content on your site, ensure + this feature is disabled by using IncludesNOEXEC + instead of Includes in the Options directive. +

+
Advanced SSI techniques -

In addition to spitting out content, Apache SSI gives you - the option of setting variables, and using those variables in - comparisons and conditionals.

+

Beyond simple content inclusion, SSI supports variables and + conditional expressions, making it possible to generate + different content based on the request context.

Setting variables -

Using the set directive, you can set variables - for later use. We'll need this later in the discussion, so - we'll talk about it here. The syntax of this is as follows:

+

The set directive defines variables for use later + in the page:

+ - <!--#set var="name" value="Rich" --> + +<!--#set var="name" value="Rich" --> + -

In addition to merely setting values literally like that, you - can use any other variable, including environment variables or the variables - discussed above (like LAST_MODIFIED, for example) to - give values to your variables. You will specify that something is - a variable, rather than a literal string, by using the dollar sign - ($) before the name of the variable.

+

Variables can reference other variables (including + environment variables) using the dollar + sign ($) prefix:

- <!--#set var="modified" value="$LAST_MODIFIED" --> - + + +<!--#set var="modified" value="$LAST_MODIFIED" --> + + + +

To include a literal dollar sign, escape it with a + backslash:

-

To put a literal dollar sign into the value of your - variable, you need to escape the dollar sign with a - backslash.

- <!--#set var="cost" value="\$100" --> + +<!--#set var="cost" value="\$100" --> + -

Finally, if you want to put a variable in the midst of a - longer string, and there's a chance that the name of the - variable will run up against some other characters, and thus be - confused with those characters, you can place the name of the - variable in braces, to remove this confusion. (It's hard to - come up with a really good example of this, but hopefully - you'll get the point.)

+

When a variable name might be ambiguous within a longer + string, use braces to delimit it:

+ - <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --> + +<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --> +
Conditional expressions -

Now that we have variables, and are able to set and compare - their values, we can use them to express conditionals. This - lets SSI be a tiny programming language of sorts. - mod_include provides an if, - elif, else, endif - structure for building conditional statements. This allows you - to effectively generate multiple logical pages out of one - actual page.

+

mod_include provides if, + elif, else, and endif + constructs for building conditional logic. This lets you + generate different output from a single physical page.

+ +

The structure is:

-

The structure of this conditional construct is:

- <!--#if expr="test_condition" -->
- <!--#elif expr="test_condition" -->
- <!--#else -->
- <!--#endif --> + +<!--#if expr="test_condition" -->
+<!--#elif expr="test_condition" -->
+<!--#else -->
+<!--#endif --> + -

A test_condition can be any sort of logical - comparison - either comparing values to one another, or testing - the ``truth'' of a particular value. (A given string is true if - it is nonempty.) For a full list of the comparison operators - available to you, see the mod_include - documentation.

+

A test_condition can compare values or test whether a + variable is non-empty. See the mod_include + documentation for the full list of comparison operators.

-

For example, if you wish to customize the text on your web page - based on the time of day, you could use the following recipe, placed - in the HTML page:

+

For example, to display different greetings based on the time + of day:

- - Good - <!--#if expr="%{TIME_HOUR} <12" -->
- morning!
- <!--#else -->
- afternoon!
- <!--#endif -->
- + + +Good +<!--#if expr="%{TIME_HOUR} <12" -->
+morning!
+<!--#else -->
+afternoon!
+<!--#endif -->
+ + -

Any other variable (either ones that you define, or normal - environment variables) can be used in conditional statements. - See Expressions in Apache HTTP Server for - more information on the expression evaluation engine.

+

Any variable — user-defined or from the environment — can be + used in conditional expressions. See + Expressions in Apache HTTP Server for + full details on the expression evaluation engine.

-

With Apache's ability to set environment variables with the - SetEnvIf directives, and other related directives, - this functionality can let you do a wide variety of dynamic content - on the server side without resorting a full web application.

+

Combined with httpd's ability to set environment variables + using SetEnvIf and + related directives, conditional SSI can handle a wide variety of + dynamic content scenarios without a full application + framework.

Conclusion -

SSI is certainly not a replacement for CGI, or other - technologies used for generating dynamic web pages. But it is a - great way to add small amounts of dynamic content to pages, - without doing a lot of extra work.

+

For sites that are mostly static but need a few dynamic + touches, SSI avoids the overhead of setting up a full + application stack. It requires only mod_include + and a few lines of configuration to get started.

- + \ No newline at end of file