Freigeben über

IIS: Notes on Server-Side Includes (SSI) Syntax (KB 203064 Revisited)

  • Artikel

Many years ago I wrote Microsoft KB article 203064 about using Server-Side-Include (SSI) files with IIS 4 and IIS 5, but that KB has long since vanished from Microsoft's support website because it was never updated for IIS 6 or IIS 7. I eventually turned the information from that KB article into a blog post, but that being said, I still see questions about SSI showing up in the IIS forums every once in a while. There was a great deal of useful information in that KB article about general SSI syntax and several practical examples for SSI directives, so I thought that it would make a good blog post if I updated the information from that KB for later versions of IIS.

SUMMARY

This blog post details some features that are available in the Microsoft implementation of Server-Side Include (SSI) files for Internet Information Server (IIS) and provides general syntax and examples for SSI directives.

APPLIES TO

  • Microsoft Internet Information Services 7.5
  • Microsoft Internet Information Services 7.0
  • Microsoft Internet Information Services 6.0
  • Microsoft Internet Information Services 5.0
  • Microsoft Internet Information Server 4.0

MORE INFORMATION

SSI files are most commonly used with IIS to allow content authors to include the contents of one file inside another file, allowing the easy creation of script libraries or page headers and footers to standardize the look and feel of your web content. SSI consists of very simple commands that are contained within HTML comment tokens, and are limited in functionality. Higher-level programming languages like ASP, ASP.NET, PHP, etc. make the need for SSI considerably less necessary than in previous years. In addition, programming features such as ASP.NET's Master Pages and Dynamic Web Template (DWT) files that are used by Dreamweaver, Expression Web, and FrontPage have replaced much of the need for SSI. Because of this, SSI is an outdated technology by today's standards. With that in mind, web developers are highly encouraged to migrate their SSI content to another technology, such as ASP.NET or PHP.

SSI Implementation Details

SSI files are mapped by file extension to a preprocessor or handler dynamic-link library (DLL), in the same way that file like ASP, ASP.NET, PHP, etc. are mapped to their requisite handlers. In the case of SSI, the specific handler is ssiinc.dll for IIS 4 through IIS 6 and iis_ssi.dll for IIS 7. SSI files on Windows are often named with .stm file extensions, although extensions of .shtm and .shtml are also supported.

Changes Between IIS Versions

  • SSI is not enabled by default on IIS 6. To enable SSI on IIS 6, set the status for the Server Side Includes web service extension to Allowed in the Internet Information Services (IIS) Manager.
  • SSI is not installed by default on IIS 7. To install SSI on IIS 7, see the Server Side Include <serverSideInclude> topic.
  • The cmd directive for #exec is disabled by default in IIS 5 and IIS 6. To enable the cmd directive, see Microsoft KB article 233969.
  • The cmd directive for #exec is now disabled for SSI files in IIS 7; you can only use the cgi directive.

General SSI Syntax

SSI is employed by the use of special preprocessing directives in SSI documents that are contained within HTML comment tokens; these directives are parsed by the SSI DLL and processed into HTML that is returned to a web client. All SSI directives take the following general form:

 <!--#<DIRECTIVE> [<PARAMETER> = <VALUE>]-->

IIS supports a small set of SSI directives, and each directive has different parameters that configure the output for the directive. Other web servers may support a different set of SSI directives and parameters, so SSI files are not 100% compatible across different technologies.

Supported Directives

The following directives are supported in the IIS implementation of SSI:

  • #config - Configures how variables and commands are displayed.

    • The general syntax for the #config directive is as follows:

       <!-- #CONFIG <ERRMSG/TIMEFMT/SIZEFMT>="<format>" -->

    • The following is an example of a simple page that uses the #config directive:

       <html>
<body>
<!-- #CONFIG TIMEFMT="%m/%d/%y" -->
<p>Today's Date = <!--#ECHO VAR = "DATE_LOCAL" --></p>
<!-- #CONFIG TIMEFMT="%A, %B %d, %Y" -->
<p>Today's Date = <!--#ECHO VAR = "DATE_LOCAL" --></p>
</body>
</html>

    • Note: See the Parameter Values for the #config Directive section later in this blog for more information about configuring dates with the #config directive.

  • #echo - Inserts the value of various Common Gateway Interface (CGI) server variables.

    • The general syntax for the #echo directive is as follows:

       <!--#ECHO VAR = "<CGI_VARIABLE_NAME>"-->

    • The following is an example of a simple page that uses the #echo directive:

       <html>
<body>
<p>Server Name = <!--#ECHO VAR = "SERVER_NAME"--></p>
<p>Date = <!--#ECHO VAR = "DATE_LOCAL" --></p>
<p>Page URL = <!--#ECHO VAR = "URL" --></p>
</body>
</html>

    • For a list of  supported CGI server variables, see IIS Server Variables.

  • #exec - Executes CGI or Internet Server API (ISAPI) command scripts and inserts output into an HTML document.

    • The general syntax for the #exec directive is as follows:

       <!-- #EXEC <CGI/CMD>="<command>" -->

    • The following is an example of a simple page that uses the #exec directive:

       <html>
<body>
<p>Root Directory of C:</p>
<pre><!--#EXEC CGI = "/cgi-bin/HelloWorld.exe" --></pre>
</body>
</html>

    • Notes:

      • The CMD command for the #exec directive is disabled by default on IIS 5 and IIS 6. For more information, see the following Microsoft Knowledge Base article:

        233969 SSIEnableCmdDirective is set to FALSE by default

      • The CMD command for the #exec directive is was removed from IIS 7. For more information, see the following Microsoft Knowledge Base article:

        Server Side Include <serverSideInclude>

  • #flastmod - Retrieves the last modification time of a specified file.

    • The general syntax for the #flastmod directive is as follows:

       <!--#FLASTMOD <FILE/VIRTUAL> = "filename.ext"-->

    • The following is an example of a simple page that uses the #flastmod and #config directives:

       <html>
<body>
<!-- #CONFIG TIMEFMT="%m/%d/%y" -->
<p>Modified Date = <!--#FLASTMOD FILE="filename.ext"--></p>
<!-- #CONFIG TIMEFMT="%B %d, %Y" -->
<p>Modified Date = <!--#FLASTMOD FILE="filename.ext"--></p>
</body>
</html>
  • #fsize - Retrieves the size of a specified file.

    • The general syntax for the #fsize directive is as follows:

       <!--#FSIZE <FILE/VIRTUAL> = "filename.ext"-->

    • The following is an example of a simple page that uses the #fsize and #config directives:

       <html>
<body>
<!-- #CONFIG SIZEFMT="BYTES" -->
<p>File Size = <!--#FSIZE FILE="filename.ext"--> bytes</p>
<!-- #CONFIG SIZEFMT="ABBREV" -->
<p>File Size = <!--#FSIZE FILE="filename.ext"--> KB</p>
</body>
</html>
  • #include - Includes the contents of one specified file inside another.

    • The general syntax for the #include directive is as follows:

       <!--#INCLUDE <FILE/VIRTUAL> = "filename.ext"-->

    • The following is an example of a simple page that uses the #include directive:

       <html>
<body>
<!--#INCLUDE FILE = "header.inc"-->
<p>Hello World!</p>
<!--#INCLUDE VIRTUAL = "/includes/footer.inc"-->
</body>
</html>

    • Note: See the More Information on File and Virtual Syntax section later in this blog for more information about using file versus virtual values.

Parameter Values for the #config Directive

The #config directive supports a large array of possible parameter values, which are listed in the following table. Note: All of these values are case-sensitive.

Value Description Example
%A Full Weekday Name Tuesday
%a Short Weekday Name Tue
%B Full Month Name December
%b Short Month Name Dec
%c Full Date & Time 12/28/10 19:52:19
%d Day of Month as a Number 28
%H Hours as a Number on a 24-Hour Clock 19
%I Hours as a Number on a 12-Hour Clock 07
%j Julian Date (Offset from Start of Year) 362
%M Minutes as a Number 52
%m Month as a Number 12
%p AM or PM Indicator PM
%S Seconds as a Number 19
%U Week Number (Offset from Start of Year) 52
%W Week Number (Offset from Start of Year) 52
%w Day of the Week as a Number 2
%X Short Time 19:52:19
%x Short Date 12/28/10
%Y Four-Digit Year as a Number 2010
%y Two-Digit Year as a Number 10
%Z Time Zone Name Pacific Standard Time
%z Time Zone Name Pacific Standard Time

Note: The following Windows Script Host (WSH) code will create a sample SSI page that you can use to test the parameter values for the #config directive:

 Option Explicit
Dim objFSO, objFile, intCount
Set objFSO = WScript.CreateObject("Scripting.Filesystemobject")
Set objFile = objFSO.CreateTextFile("ssitest.stm")
objFile.WriteLine("<html>")
objFile.WriteLine("<body>")
For intCount = Asc("A") To Asc("Z")
    objFile.WriteLine("<!-- #CONFIG TIMEFMT=""%" & _
        UCase(Chr(intCount)) & """ --><p>%" & _
        UCase(Chr(intCount)) & _
        " = <!--#ECHO VAR = ""DATE_LOCAL"" --></p>")
    objFile.WriteLine("<!-- #CONFIG TIMEFMT=""%" & _
        LCase(Chr(intCount)) & """ --><p>%" & _
        LCase(Chr(intCount)) & _
        " = <!--#ECHO VAR = ""DATE_LOCAL"" --></p>")
Next
objFile.WriteLine("</body>")
objFile.WriteLine("</html>")

More Information on File and Virtual Syntax

SSI directives that use file paths can reference files by using a file or virtual path.

  • The file element is used with files that are relative to the folder of the current document. The following example includes a file in the current folder:

     <!--#include file="myfile.txt"-->

  • The virtual element represents paths that are relative to the base folder of the Web server. The following example includes a file in the /scripts virtual folder:

     <!--#include virtual="/scripts/myfile.txt"-->

REFERENCES

For additional information on using SSI with IIS, click the following article numbers to view the articles in the Microsoft Knowledge Base:

  • 169996 To run an ISAPI DLL with #exec, use the CGI statement
  • 172024 INFO: Server Side Include Directives Are Not Processed by ASP
  • 195291 How to disable #exec in Server-Side Include files
  • 289496 Error Messages Appear and Access Violations Occur After You Upload SSI ASPs in IIS 5.0
  • 299982 How to create server-side include files to package ASP scripts
  • 308176 BUG: SSI #EXEC CMD Directive Does Not Work in IIS 5.1
  • 318176 SSI Output Disappears After You Apply Security Patches
  • 954754 Mappings for server-side include (SSI) directives do not work after you upgrade from IIS 6.0 to IIS 7.0

For more Microsoft Knowledge Base articles about using SSI with IIS, click here.

Comments

  • Anonymous
    January 14, 2015
    The time to Linux the problem is less than that required to chase broken links, study workarounds around workarounds, study technically accurate but practically useless information.  Shameful.

  • Anonymous
    March 06, 2016
    I have legacy cgi-bin to manage. Some of them are .exe file written in C and I have a problem with them: I can't seem to find a way to open a file in the LOCAL folder where the .exe file was run from. Let me explain: Say I have this cgi.exe file, built from a cgi.c source file. Cgi.exe opens a cgi.cfg file. Currently, it can open the file in the root folder of the web site. But if I have two cgi-bin folders in that root folder,, cgi-bin1 and cgi-bin2, and a copy of cgi.exe in both cgi -bin folders, they both try to open the same cgi.cfg in the root folder of the web site. What I'd like to be able to do is to have as many cgi-binX folders as I want and have a copy of cgi.exe in each folder, said copy opening its own "local" cgi.cfg file. When I say local, I mean "in the same folder than the .exe file". I modified the cgi.c source to get the current directory it sees, using getcwd() and it returns the root folder of the web site, not the path to the cgi-bin folder it was run from... Any help would be appreciated !