<?xml version="1.0"?>
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="ssi-howto.html">

    &project;

    <properties>
        <author email="glenn@apache.org">Glenn L. Nielsen</author>
        <title>SSI How To</title>
    </properties>

<body>

<section name="Introduction">

<p>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.
</p>

<p>Within Tomcat SSI support can be added when using Tomcat as your
HTTP server and you require SSI support.  Typically this is done
during development when you don't want to run a web server like Apache.</p>

<p>Tomcat SSI support implements the same SSI directives as Apache.  See the
<a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
Apache Introduction to SSI</a> for information on using SSI directives.</p>

<p>SSI support is implemented using the servlet class
<code>org.apache.catalina.ssi.SSIServlet</code>.  Traditionally, this servlet
is mapped to the URL pattern "*.shtml".</p>

<p>By default SSI support is disabled in Tomcat.</p>
</section>

<section name="Installation">

<p><strong>CAUTION</strong> - SSI directives can be used to execute programs
external to the Tomcat JVM. If you are using the Java SecurityManager this
will bypass your security policy configuration in <code>catalina.policy.</code>
</p>

<p>Rename <code>$CATALINA_BASE/server/lib/servlets-ssi.renametojar</code>
to <code>$CATALINA_BASE/server/lib/servlets-ssi.jar</code>.</p>

<p>Remove the XML comments from around the SSI servlet and servlet-mapping
configuration in <code>$CATALINA_BASE/conf/web.xml</code>.</p>
</section>

<section name="Configuration">

<p>There are several servlet init parameters which can be used to
configure the behaviour of the SSI servlet.
<ul>
<li><strong>buffered</strong> - Should output from this servlet be buffered?
(0=false, 1=true) Default 0 (false).</li>
<li><strong>debug</strong> - Debugging detail level for messages logged
by this servlet. Default 0.</li>
<li><strong>expires</strong> - The number of seconds before a page with SSI
directives will expire. Default behaviour is for all SSI directives to be
evaluated for every request.</li>
<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
paths be interpreted as relative to the context root, instead of the server
root? (0=false, 1=true) Default 0 (false).</li>
</ul>
</p>

</section>

</body>

</document>
