Server-Side Includes (SSIs)

Introduction

Server-Side Includes (SSIs) are a very useful way to make your site easier to manage, and for providing extra information. SSI are directives you can place into an HTML document to execute other programs or to output data, such as file statistics or the contents of environment variables. SSI directives can save you the trouble of writing complete CGI programs to output documents containing a small amount of dynamic information.

To summarize, instead of writing code to perform dynamic and useful tasks, you can use commands called Server-Side Includes (SSIs). Server-Side Includes are little comments in an HTML document. The server parses the specified document looking for SSI directives before passing the document to a browser. The browser only sees the end result and never sees the SSI call.

While Server Side Includes technically are not CGI, they can become an important tool for incorporating CGI-like information as well as output from CGI programs.

SSIs probably were started to handle the desire to include a common file inside a bunch of different files. Someone said, "I want to include another file in my HTML and I don't want to have to cut and paste every time I need to include it in my file." The most common use for SSIs is providing a signature file or company logo or copyright notices that you want to add to every file you create. The include file resides on the server is included whenever any HTML file that contains the include command is requested, which is were the term Server-Side Include comes from.

There are five basic types of SSIs we can use. We can:

Include text files in our pages, as they are loaded
Retrieve the size and last modification date of a file
Define how variables and messages are displayed
Insert the values of the HTTP variables in the page sent back to the browser
Execute other programs or scripts, such as CGI and ISAPI applications

Overall the include command can make your task as a Web page builder much easier. Used properly, the include command can dramatically decrease the amount of HTML that you have to write and modify.

Using SSIs Negatives

As with every other neat and cool thing you can do, SSIs are somewhat of a two-edged sword. The server has to do a lot more work to process these includes. When the server returns an HTML file, it generates the appropriate response headers and sends the HTML file back to the client. No fuss and very little work.

When the server executes the CGI program, a compiler or interpreter executes your program. Your CGI program should generate some HTTP response headers, and then the HTML file server's job is to generate any additional required HTTP response headers and pass the CGI-generated HTML back to client/browser.

When the server returns a file with SSI commands in it, however, it must read each line of the file looking for the special SSI command syntax. This is called parsing a file. SSI commands can appear anywhere in your HTML file. This means that your server must make a special effort to find the commands in your HTML file.

This parsing of files puts an extra burden on your server. That also means that the SSI files are slower when returned to your Web client than regular HTML files. The more SSI files your server has to handle, the more processing load on your server, and, as consequence, the slower your server operates. Do not let this stop you form using SSIs; just be aware of the cost and benefits of using SSI files.

Your local Internet provider wants to give you all the freedom it can on your server. Because of the extra burden placed on the server, however, limitations are placed on the types of files that can have SSI commands. This limitation is based on the ending characters of each filename, called filename extension. Usually, it's something like .shtml. So any file that ends in .shtml is handled as an SSI file by the server. On the NT server the extension is .stm.

In order for SSIs to work, the server has to read every line of SSI file looking for the special SSI commands. A significant extra computing and disk-access burden is placed on any server that has to parse its files before sending them back to the client.

And additionally, enabling SSI creates a security risk. For example, an unwise user might embed directives to execute system commands that output confidential information.

So, SSI can be very handy, but it must be used efficiently and cautiously.

Setting up your server for SSI

If SSI is not currently turned on your UNIX server, then you need to add to your server configuration file (srm.conf). Add the following line to that file:

addType text/x-server-parsed-html .shtml

That will force the server to look for SSI calls in all .shtml files. You could add another line ending in ".html" and it will also parse all .html files. But remember that unless most .html files have SSI calls, it will be less efficient because every single .html file will be parsed before it is sent off to the browser. So it is recommended you just have your server parse .shtml files.

For Windows NT you need to edit the Registry => HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters =>
- ServerSideIncludesEnabled - 1
- ServerSideIncludesExtension - .stm

Using the virtual Command Argument

Including Text Files in a Page with #include is one of the most useful techniques with SSI is to insert pre-built blocks of text into a page.

'virtual path

the server begins its search for the file from the document root directory (/).

Using the file Command Argument

the file command argument should be used when including files that are in the same directory of the SSI file is in (the current directory) or a subdirectory of the current directory.

When using the file command, you cannot include a pathname that begins above the current directory. In other words, any pathname that begins with ../ is illegal.

'physical path

Executing Commands Using SSIs

Using this directive, you can execute a CGI script, a shell command, or an executable or dll (ie, NT). After the command, app, and so forth has executed, the output is inserted into the HTML stream.

For Windows NT:

For UNIX

To execute a CGI script:

To execute a command on the server (the browser sees the results of the command):

Executing a command is the only way to pass arguments to a CGI script. For instance:

won't work, but this line will: