Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - SSI How To</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>SSI How To</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Installation">Installation</a></li><li><a href="#Servlet_Configuration">Servlet Configuration</a></li><li><a href="#Filter_Configuration">Filter Configuration</a></li><li><a href="#Directives">Directives</a></li><li><a href="#Variables">Variables</a></li></ul>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
<p>SSI (Server Side Includes) are directives that are placed in HTML pages,
9 
and evaluated on the server while the pages are being served. They let you
10 
add dynamically generated content to an existing HTML page, without having
11 
to serve the entire page via a CGI program, or other dynamic technology.
12 
</p>
13 
 
14 
<p>Within Tomcat SSI support can be added when using Tomcat as your
15 
HTTP server and you require SSI support.  Typically this is done
16 
during development when you don't want to run a web server like Apache.</p>
17 
 
18 
<p>Tomcat SSI support implements the same SSI directives as Apache.  See the
19 
<a href="https://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
20 
Apache Introduction to SSI</a> for information on using SSI directives.</p>
21 
 
22 
<p>SSI support is available as a servlet and as a filter. You should use one
23 
or the other to provide SSI support but not both.</p>
24 
 
25 
<p>Servlet based SSI support is implemented using the class
26 
<code>org.apache.catalina.ssi.SSIServlet</code>.  Traditionally, this servlet
27 
is mapped to the URL pattern "*.shtml".</p>
28 
 
29 
<p>Filter based SSI support is implemented using the class
30 
<code>org.apache.catalina.ssi.SSIFilter</code>.  Traditionally, this filter
31 
is mapped to the URL pattern "*.shtml", though it can be mapped to "*" as
32 
it will selectively enable/disable SSI processing based on mime types.  The
33 
contentType init param allows you to apply SSI processing to JSP pages,
34 
JavaScript, or any other content you wish.</p>
35 
<p>By default SSI support is disabled in Tomcat.</p>
36 
</div><h3 id="Installation">Installation</h3><div class="text">
37 
 
38 
<p><strong>CAUTION</strong> - SSI directives can be used to execute programs
39 
external to the Tomcat JVM. If you are using the Java SecurityManager this
40 
will bypass your security policy configuration in <code>catalina.policy.</code>
41 
</p>
42 
 
43 
<p>To use the SSI servlet, remove the XML comments from around the SSI servlet
44 
and servlet-mapping configuration in
45 
<code>$CATALINA_BASE/conf/web.xml</code>.</p>
46 
 
47 
<p>To use the SSI filter, remove the XML comments from around the SSI filter
48 
and filter-mapping configuration in
49 
<code>$CATALINA_BASE/conf/web.xml</code>.</p>
50 
 
51 
<p>Only Contexts which are marked as privileged may use SSI features (see the
52 
privileged property of the Context element).</p>
53 
 
54 
</div><h3 id="Servlet_Configuration">Servlet Configuration</h3><div class="text">
55 
 
56 
<p>There are several servlet init parameters which can be used to
57 
configure the behaviour of the SSI servlet.</p>
58 
<ul>
59 
<li><strong>buffered</strong> - Should output from this servlet be buffered?
60 
(0=false, 1=true) Default 0 (false).</li>
61 
<li><strong>debug</strong> - Debugging detail level for messages logged
62 
by this servlet. Default 0.</li>
63 
<li><strong>expires</strong> - The number of seconds before a page with SSI
64 
directives will expire. Default behaviour is for all SSI directives to be
65 
evaluated for every request.</li>
66 
<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
67 
paths be interpreted as relative to the context root, instead of the server
68 
root? Default false.</li>
69 
<li><strong>inputEncoding</strong> - The encoding to be assumed for SSI
70 
resources if one cannot be determined from the resource itself. Default is
71 
the default platform encoding.</li>
72 
<li><strong>outputEncoding</strong> - The encoding to be used for the result
73 
of the SSI processing. Default is UTF-8.</li>
74 
<li><strong>allowExec</strong> - Is the exec command enabled? Default is
75 
false.</li>
76 
</ul>
77 
 
78 
 
79 
</div><h3 id="Filter_Configuration">Filter Configuration</h3><div class="text">
80 
 
81 
<p>There are several filter init parameters which can be used to
82 
configure the behaviour of the SSI filter.</p>
83 
<ul>
84 
<li><strong>contentType</strong> - A regex pattern that must be matched before
85 
SSI processing is applied. When crafting your own pattern, don't forget that a
86 
mime content type may be followed by an optional character set in the form
87 
"mime/type; charset=set" that you must take into account.  Default is
88 
"text/x-server-parsed-html(;.*)?".</li>
89 
<li><strong>debug</strong> - Debugging detail level for messages logged
90 
by this servlet. Default 0.</li>
91 
<li><strong>expires</strong> - The number of seconds before a page with SSI
92 
directives will expire. Default behaviour is for all SSI directives to be
93 
evaluated for every request.</li>
94 
<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
95 
paths be interpreted as relative to the context root, instead of the server
96 
root? Default false.</li>
97 
<li><strong>allowExec</strong> - Is the exec command enabled? Default is
98 
false.</li>
99 
</ul>
100 
 
101 
 
102 
</div><h3 id="Directives">Directives</h3><div class="text">
103 
<p>Server Side Includes are invoked by embedding SSI directives in an HTML document
104 
 whose type will be processed by the SSI servlet. The directives take the form of an HTML
105 
 comment. The directive is replaced by the results of interpreting it before sending the
106 
 page to the client. The general form of a directive is: </p>
107 
<p> <code>&lt;!--#directive [param=value] --&gt;</code></p>
108 
<p>The directives are:</p>
109 
<ul>
110 
<li>
111 
<strong>config</strong> - <code>&lt;!--#config errmsg="Error occurred" sizefmt="abbrev"
112 
timefmt="%B %Y" --&gt;</code>
113 
Used to set SSI error message, the format of dates and file sizes processed by SSI.<br>
114 
All are optional but at least one must be used. The available options are as follows:
115 
<br>
116 
<strong>errmsg</strong> - error message used for SSI errors<br>
117 
<strong>sizefmt</strong> - format used for sizes in the <strong>fsize</strong> directive<br>
118 
<strong>timefmt</strong> - format used for timestamps in the <strong>flastmod</strong> directive<br>
119 
</li>
120 
<li>
121 
<strong>echo</strong> -   <code>&lt;!--#echo var="VARIABLE_NAME" encoding="entity" --&gt;</code>
122 
will be replaced by the value of the variable.
123 
<br>
124 
The optional <strong>encoding</strong> parameter specifies the type of encoding to use.
125 
Valid values are <strong>entity</strong> (default), <strong>url</strong> or <strong>none</strong>.
126 
NOTE: Using an encoding other than <strong>entity</strong> can lead to security issues.
127 
</li>
128 
<li>
129 
<strong>exec</strong> - <code>&lt;!--#exec cmd="file-name" --&gt;</code>
130 
Used to run commands on the host system.
131 
</li>
132 
<li>
133 
<strong>exec</strong> - <code>&lt;!--#exec cgi="file-name" --&gt;</code>
134 
This acts the same as the <strong>include virtual</strong> directive, and doesn't actually execute any commands.
135 
</li>
136 
<li>
137 
<strong>include</strong> -  <code>&lt;!--#include file="file-name" --&gt;</code>
138 
inserts the contents. The path is interpreted relative to the document where this directive
139 
is being used, and IS NOT a "virtual" path relative to either the context root or the server root.
140 
</li>
141 
<li>
142 
<strong>include</strong> -  <code>&lt;!--#include virtual="file-name" --&gt;</code>
143 
inserts the contents. The path is interpreted as a "virtual" path which is
144 
relative to either the context root or the server root (depending on the <strong>isVirtualWebappRelative</strong>
145 
parameter).
146 
</li>
147 
<li>
148 
<strong>flastmod</strong> - <code>&lt;!--#flastmod file="filename.shtml" --&gt;</code>
149 
Returns the time that a file was last modified. The path is interpreted relative to the document where this directive
150 
is being used, and IS NOT a "virtual" path relative to either the context root or the server root.
151 
</li>
152 
<li>
153 
<strong>flastmod</strong> - <code>&lt;!--#flastmod virtual="filename.shtml" --&gt;</code>
154 
Returns the time that a file was last modified. The path is interpreted as a "virtual" path which is
155 
relative to either the context root or the server root (depending on the <strong>isVirtualWebappRelative</strong>
156 
parameter).
157 
</li>
158 
<li>
159 
<strong>fsize</strong> - <code>&lt;!--#fsize file="filename.shtml" --&gt;</code>
160 
Returns the size of a file. The path is interpreted relative to the document where this directive
161 
is being used, and IS NOT a "virtual" path relative to either the context root or the server root.
162 
</li>
163 
<li>
164 
<strong>fsize</strong> - <code>&lt;!--#fsize virtual="filename.shtml" --&gt;</code>
165 
Returns the size of a file. The path is interpreted as a "virtual" path which is
166 
relative to either the context root or the server root (depending on the <strong>isVirtualWebappRelative</strong>
167 
parameter).
168 
</li>
169 
<li>
170 
<strong>printenv</strong> - <code>&lt;!--#printenv --&gt;</code>
171 
Returns the list of all the defined variables.
172 
</li>
173 
<li>
174 
<strong>set</strong> - <code>&lt;!--#set var="foo" value="Bar" --&gt;</code>
175 
is used to assign a value to a user-defined variable.
176 
</li>
177 
<li>
178 
<strong>if elif endif else</strong> - Used to create conditional sections. For example:
179 
<div class="codeBox"><pre><code>&lt;!--#config timefmt="%A" --&gt;
180 
&lt;!--#if expr="$DATE_LOCAL = /Monday/" --&gt;
181 
&lt;p&gt;Meeting at 10:00 on Mondays&lt;/p&gt;
182 
&lt;!--#elif expr="$DATE_LOCAL = /Friday/" --&gt;
183 
&lt;p&gt;Turn in your time card&lt;/p&gt;
184 
&lt;!--#else --&gt;
185 
&lt;p&gt;Yoga class at noon.&lt;/p&gt;
186 
&lt;!--#endif --&gt;</code></pre></div>
187 
</li>
188 
</ul>
189 
<p>
190 
See the
191 
<a href="https://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
192 
Apache Introduction to SSI</a> for more information on using SSI directives.</p>
193 
</div><h3 id="Variables">Variables</h3><div class="text">
194 
<p>
195 
SSI variables are implemented via request attributes on the <b>javax.servlet.ServletRequest</b> object
196 
and are not limited to the SSI servlet. Variables starting with the names
197 
"java.", "javax.", "sun" or "org.apache.catalina.ssi.SSIMediator." are reserved
198 
and cannot be used.
199 
</p>
200 
<p>The SSI servlet currently implements the following variables:
201 
</p>
202 
<table class="defaultTable">
203 
<tr>
204 
<th>Variable Name</th>
205 
<th>Description</th>
206 
</tr>
207 
 
208 
<tr>
209 
<td>AUTH_TYPE</td>
210 
<td>
211 
  The type of authentication used for this user: BASIC, FORM, etc.</td>
212 
</tr>
213 
 
214 
<tr>
215 
<td>CONTENT_LENGTH</td>
216 
<td>
217 
  The length of the data (in bytes or the number of
218 
  characters) passed from a form.</td>
219 
</tr>
220 
 
221 
<tr>
222 
<td>CONTENT_TYPE</td>
223 
<td>
224 
  The MIME type of the query data, such as "text/html".</td>
225 
</tr>
226 
 
227 
<tr>
228 
<td>DATE_GMT</td>
229 
<td>
230 
Current date and time in GMT</td>
231 
</tr>
232 
 
233 
<tr>
234 
<td>DATE_LOCAL</td>
235 
<td>
236 
Current date and time in the local time zone</td>
237 
</tr>
238 
<tr>
239 
<td>DOCUMENT_NAME</td>
240 
<td>
241 
The current file</td>
242 
</tr>
243 
<tr>
244 
<td>DOCUMENT_URI</td>
245 
<td>
246 
Virtual path to the file</td>
247 
</tr>
248 
 
249 
<tr>
250 
<td>GATEWAY_INTERFACE</td>
251 
<td>
252 
  The revision of the Common Gateway Interface that the
253 
  server uses if enabled: "CGI/1.1".</td>
254 
</tr>
255 
 
256 
<tr>
257 
<td>HTTP_ACCEPT</td>
258 
<td>
259 
  A list of the MIME types that the client can accept.</td>
260 
</tr>
261 
 
262 
<tr>
263 
<td>HTTP_ACCEPT_ENCODING</td>
264 
<td>
265 
  A list of the compression types that the client can accept.</td>
266 
</tr>
267 
 
268 
<tr>
269 
<td>HTTP_ACCEPT_LANGUAGE</td>
270 
<td>
271 
  A list of the languages that the client can accept.</td>
272 
</tr>
273 
<tr>
274 
<td>HTTP_CONNECTION</td>
275 
<td>
276 
  The way that the connection from the client is being managed:
277 
  "Close" or "Keep-Alive".</td>
278 
</tr>
279 
<tr>
280 
<td>HTTP_HOST</td>
281 
<td>
282 
  The web site that the client requested.</td>
283 
</tr>
284 
<tr>
285 
<td>HTTP_REFERER</td>
286 
<td>
287 
  The URL of the document that the client linked from.</td>
288 
</tr>
289 
<tr>
290 
<td>HTTP_USER_AGENT</td>
291 
<td>
292 
  The browser the client is using to issue the request.</td>
293 
</tr>
294 
<tr>
295 
<td>LAST_MODIFIED</td>
296 
<td>
297 
Last modification date and time for current file</td>
298 
</tr>
299 
<tr>
300 
<td>PATH_INFO</td>
301 
<td>
302 
  Extra path information passed to a servlet.</td>
303 
</tr>
304 
<tr>
305 
<td>PATH_TRANSLATED</td>
306 
<td>
307 
  The translated version of the path given by the
308 
  variable PATH_INFO.</td>
309 
</tr>
310 
<tr>
311 
<td>QUERY_STRING</td>
312 
<td>
313 
The query string that follows the "?" in the URL.
314 
</td>
315 
</tr>
316 
<tr>
317 
<td>QUERY_STRING_UNESCAPED</td>
318 
<td>
319 
Undecoded query string with all shell metacharacters escaped
320 
with "\"</td>
321 
</tr>
322 
<tr>
323 
<td>REMOTE_ADDR</td>
324 
<td>
325 
  The remote IP address of the user making the request.</td>
326 
</tr>
327 
<tr>
328 
<td>REMOTE_HOST</td>
329 
<td>
330 
  The remote hostname of the user making the request.</td>
331 
</tr>
332 
<tr>
333 
<td>REMOTE_PORT</td>
334 
<td>
335 
  The port number at remote IP address of the user making the request.</td>
336 
</tr>
337 
<tr>
338 
<td>REMOTE_USER</td>
339 
<td>
340 
  The authenticated name of the user.</td>
341 
</tr>
342 
<tr>
343 
<td>REQUEST_METHOD</td>
344 
<td>
345 
  The method with which the information request was
346 
  issued: "GET", "POST" etc.</td>
347 
</tr>
348 
<tr>
349 
<td>REQUEST_URI</td>
350 
<td>
351 
  The web page originally requested by the client.</td>
352 
</tr>
353 
<tr>
354 
<td>SCRIPT_FILENAME</td>
355 
<td>
356 
  The location of the current web page on the server.</td>
357 
</tr>
358 
<tr>
359 
<td>SCRIPT_NAME</td>
360 
<td>
361 
  The name of the web page.</td>
362 
</tr>
363 
<tr>
364 
<td>SERVER_ADDR</td>
365 
<td>
366 
  The server's IP address.</td>
367 
</tr>
368 
<tr>
369 
<td>SERVER_NAME</td>
370 
<td>
371 
  The server's hostname or IP address.</td>
372 
</tr>
373 
<tr>
374 
<td>SERVER_PORT</td>
375 
<td>
376 
  The port on which the server received the request.</td>
377 
</tr>
378 
<tr>
379 
<td>SERVER_PROTOCOL</td>
380 
<td>
381 
  The protocol used by the server. E.g. "HTTP/1.1".</td>
382 
</tr>
383 
<tr>
384 
<td>SERVER_SOFTWARE</td>
385 
<td>
386 
  The name and version of the server software that is
387 
  answering the client request.</td>
388 
</tr>
389 
<tr>
390 
<td>UNIQUE_ID</td>
391 
<td>
392 
  A token used to identify the current session if one
393 
  has been established.</td>
394 
</tr>
395 
</table>
396 
</div></div></div></div></div><footer><div id="footer">
397 
    Copyright &copy; 1999-2025, The Apache Software Foundation
398 
    <br>
399 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
400 
    are either registered trademarks or trademarks of the Apache Software
401 
    Foundation.
402 
    </div></footer></div></body></html>