Gitiles
Code Review Sign In
source.supwisdom.com / portal_platform / tomcat-cms / 07b3087b89f4c23810bb2a7902fe5a06f392b984 / . / webapps / docs / ssi-howto.html
blob: ddf390911613cbde72d98cf2575264bc07c2b643 [file] [log] [blame]
Cheng Tang07b30872014-04-27 16:37:18 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.42) - SSI How To</title><meta name="author" content="Glenn L. Nielsen"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style><style type="text/css">
5 code {background-color:rgb(224,255,255);padding:0 0.1em;}
6 code.attributeName, code.propertyName {background-color:transparent;}
7 </style><style type="text/css">
8 .wrapped-source code { display: block; background-color: transparent; }
9 .wrapped-source div { margin: 0 0 0 1.25em; }
10 .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
11 </style><style type="text/css">
12 p.notice {
13 border: 1px solid rgb(255, 0, 0);
14 background-color: rgb(238, 238, 238);
15 color: rgb(0, 51, 102);
16 padding: 0.5em;
17 margin: 1em 2em 1em 1em;
18 }
19 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
20 The Apache Tomcat Servlet/JSP Container
21 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><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="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</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></ul><p><strong>Reference</strong></p><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 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>SSI How To</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
22<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>
23</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
24
25<p>SSI (Server Side Includes) are directives that are placed in HTML pages,
26and evaluated on the server while the pages are being served. They let you
27add dynamically generated content to an existing HTML page, without having
28to serve the entire page via a CGI program, or other dynamic technology.
29</p>
30
31<p>Within Tomcat SSI support can be added when using Tomcat as your
32HTTP server and you require SSI support. Typically this is done
33during development when you don't want to run a web server like Apache.</p>
34
35<p>Tomcat SSI support implements the same SSI directives as Apache. See the
36<a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
37Apache Introduction to SSI</a> for information on using SSI directives.</p>
38
39<p>SSI support is available as a servlet and as a filter. You should use one
40or the other to provide SSI support but not both.</p>
41
42<p>Servlet based SSI support is implemented using the class
43<code>org.apache.catalina.ssi.SSIServlet</code>. Traditionally, this servlet
44is mapped to the URL pattern "*.shtml".</p>
45
46<p>Filter based SSI support is implemented using the class
47<code>org.apache.catalina.ssi.SSIFilter</code>. Traditionally, this filter
48is mapped to the URL pattern "*.shtml", though it can be mapped to "*" as
49it will selectively enable/disable SSI processing based on mime types. The
50contentType init param allows you to apply SSI processing to JSP pages,
51javascript, or any other content you wish.</p>
52<p>By default SSI support is disabled in Tomcat.</p>
53</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
54
55<p><strong>CAUTION</strong> - SSI directives can be used to execute programs
56external to the Tomcat JVM. If you are using the Java SecurityManager this
57will bypass your security policy configuration in <code>catalina.policy.</code>
58</p>
59
60<p>To use the SSI servlet, remove the XML comments from around the SSI servlet
61and servlet-mapping configuration in
62<code>$CATALINA_BASE/conf/web.xml</code>.</p>
63
64<p>To use the SSI filter, remove the XML comments from around the SSI filter
65and filter-mapping configuration in
66<code>$CATALINA_BASE/conf/web.xml</code>.</p>
67
68<p>Only Contexts which are marked as privileged may use SSI features (see the
69privileged property of the Context element).</p>
70
71</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Servlet Configuration"><!--()--></a><a name="Servlet_Configuration"><strong>Servlet Configuration</strong></a></font></td></tr><tr><td><blockquote>
72
73<p>There are several servlet init parameters which can be used to
74configure the behaviour of the SSI servlet.
75<ul>
76<li><strong>buffered</strong> - Should output from this servlet be buffered?
77(0=false, 1=true) Default 0 (false).</li>
78<li><strong>debug</strong> - Debugging detail level for messages logged
79by this servlet. Default 0.</li>
80<li><strong>expires</strong> - The number of seconds before a page with SSI
81directives will expire. Default behaviour is for all SSI directives to be
82evaluated for every request.</li>
83<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
84paths be interpreted as relative to the context root, instead of the server
85root? Default false.</li>
86<li><strong>inputEncoding</strong> - The encoding to be assumed for SSI
87resources if one cannot be determined from the resource itself. Default is
88the default platform encoding.</li>
89<li><strong>outputEncoding</strong> - The encoding to be used for the result
90of the SSI processing. Default is UTF-8.</li>
91<li><strong>allowExec</strong> - Is the exec command enabled? Default is
92false.</li>
93</ul>
94</p>
95
96</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Filter Configuration"><!--()--></a><a name="Filter_Configuration"><strong>Filter Configuration</strong></a></font></td></tr><tr><td><blockquote>
97
98<p>There are several filter init parameters which can be used to
99configure the behaviour of the SSI filter.
100<ul>
101<li><strong>contentType</strong> - A regex pattern that must be matched before
102SSI processing is applied. When crafting your own pattern, don't forget that a
103mime content type may be followed by an optional character set in the form
104"mime/type; charset=set" that you must take into account. Default is
105"text/x-server-parsed-html(;.*)?".</li>
106<li><strong>debug</strong> - Debugging detail level for messages logged
107by this servlet. Default 0.</li>
108<li><strong>expires</strong> - The number of seconds before a page with SSI
109directives will expire. Default behaviour is for all SSI directives to be
110evaluated for every request.</li>
111<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
112paths be interpreted as relative to the context root, instead of the server
113root? Default false.</li>
114<li><strong>allowExec</strong> - Is the exec command enabled? Default is
115false.</li>
116</ul>
117</p>
118
119</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Directives"><strong>Directives</strong></a></font></td></tr><tr><td><blockquote>
120<p>Server Side Includes are invoked by embedding SSI directives in an HTML document
121 whose type will be processed by the SSI servlet. The directives take the form of an HTML
122 comment. The directive is replaced by the results of interpreting it before sending the
123 page to the client. The general form of a directive is: </p>
124<p> <code>&lt;!--#directive [parm=value] --&gt;</code></p>
125<p>The directives are:
126<ul>
127<li>
128<strong>config</strong> - <code>&lt;!--#config timefmt="%B %Y" --&gt;</code>
129Used to set the format of dates and other items processed by SSI
130</li>
131<li>
132<strong>echo</strong> - <code>&lt;!--#echo var="VARIABLE_NAME" --&gt;</code>
133will be replaced by the value of the variable.
134</li>
135<li>
136<strong>exec</strong> - Used to run commands on the host system.
137</li>
138<li>
139<strong>include</strong> - <code>&lt;!--#include virtual="file-name" --&gt;</code>
140inserts the contents
141</li>
142<li>
143<strong>flastmod</strong> - <code>&lt;!--#flastmod file="filename.shtml" --&gt;</code>
144Returns the time that a file was lost modified.
145</li>
146<li>
147<strong>fsize</strong> - <code>&lt;!--#fsize file="filename.shtml" --&gt;</code>
148Returns the size of a file.
149</li>
150<li>
151<strong>printenv</strong> - <code>&lt;!--#printenv --&gt;</code>
152Returns the list of all the defined variables.
153</li>
154<li>
155<strong>set</strong> - <code>&lt;!--#set var="foo" value="Bar" --&gt;</code>
156is used to assign a value to a user-defind variable.
157</li>
158<li>
159<strong>if elif endif else</strong> - Used to create conditional sections. For example:</li>
160<code>&lt;!--#config timefmt="%A" --&gt;<br>
161 &lt;!--#if expr="$DATE_LOCAL = /Monday/" --&gt;<br>
162 &lt;p&gt;Meeting at 10:00 on Mondays&lt;/p&gt;<br>
163 &lt;!--#elif expr="$DATE_LOCAL = /Friday/" --&gt;<br>
164 &lt;p&gt;Turn in your time card&lt;/p&gt;<br>
165 &lt;!--#else --&gt;<br>
166 &lt;p&gt;Yoga class at noon.&lt;/p&gt;<br>
167 &lt;!--#endif --&gt;</code>
168 </ul>
169</p>
170See the
171<p> <a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
172Apache Introduction to SSI</a> for more information on using SSI directives.</p>
173</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Variables"><strong>Variables</strong></a></font></td></tr><tr><td><blockquote>
174<p>The SSI servlet currently implements the following variables:
175</p>
176<table border="1">
177<tr>
178<th>Variable Name</th>
179<th>Description</th>
180</tr>
181
182<tr>
183<td>AUTH_TYPE</td>
184<td>
185 The type of authentication used for this user: BASIC, FORM, etc.</td>
186</tr>
187
188<tr>
189<td>CONTENT_LENGTH</td>
190<td>
191 The length of the data (in bytes or the number of
192 characters) passed from a form.</td>
193</tr>
194
195<tr>
196<td>CONTENT_TYPE</td>
197<td>
198 The MIME type of the query data, such as "text/html".</td>
199</tr>
200
201<tr>
202<td>DATE_GMT</td>
203<td>
204Current date and time in GMT</td>
205</tr>
206
207<tr>
208<td>DATE_LOCAL</td>
209<td>
210Current date and time in the local time zone</td>
211</tr>
212<tr>
213<td>DOCUMENT_NAME</td>
214<td>
215The current file</td>
216</tr>
217<tr>
218<td>DOCUMENT_URI</td>
219<td>
220Virtual path to the file</td>
221</tr>
222
223<tr>
224<td>GATEWAY_INTERFACE</td>
225<td>
226 The revision of the Common Gateway Interface that the
227 server uses if enabled: "CGI/1.1".</td>
228</tr>
229
230<tr>
231<td>HTTP_ACCEPT</td>
232<td>
233 A list of the MIME types that the client can accept.</td>
234</tr>
235
236<tr>
237<td>HTTP_ACCEPT_ENCODING</td>
238<td>
239 A list of the compression types that the client can accept.</td>
240</tr>
241
242<tr>
243<td>HTTP_ACCEPT_LANGUAGE</td>
244<td>
245 A list of the languages that the client can accept.</td>
246</tr>
247<tr>
248<td>HTTP_CONNECTION</td>
249<td>
250 The way that the connection from the client is being managed:
251 "Close" or "Keep-Alive".</td>
252</tr>
253<tr>
254<td>HTTP_HOST</td>
255<td>
256 The web site that the client requested.</td>
257</tr>
258<tr>
259<td>HTTP_REFERER</td>
260<td>
261 The URL of the document that the client linked from.</td>
262</tr>
263<tr>
264<td>HTTP_USER_AGENT</td>
265<td>
266 The browser the client is using to issue the request.</td>
267</tr>
268<tr>
269<td>LAST_MODIFIED</td>
270<td>
271Last modification date and time for current file</td>
272</tr>
273<tr>
274<td>PATH_INFO</td>
275<td>
276 Extra path information passed to a servlet.</td>
277</tr>
278<tr>
279<td>PATH_TRANSLATED</td>
280<td>
281 The translated version of the path given by the
282 variable PATH_INFO.</td>
283</tr>
284<tr>
285<td>QUERY_STRING</td>
286<td>
287The query string that follows the "?" in the URL.
288</td>
289</tr>
290<tr>
291<td>QUERY_STRING_UNESCAPED</td>
292<td>
293Undecoded query string with all shell metacharacters escaped
294with "\"</td>
295</tr>
296<tr>
297<td>REMOTE_ADDR</td>
298<td>
299 The remote IP address of the user making the request.</td>
300</tr>
301<tr>
302<td>REMOTE_HOST</td>
303<td>
304 The remote hostname of the user making the request.</td>
305</tr>
306<tr>
307<td>REMOTE_PORT</td>
308<td>
309 The port number at remote IP address of the user making the request.</td>
310</tr>
311<tr>
312<td>REMOTE_USER</td>
313<td>
314 The authenticated name of the user.</td>
315</tr>
316<tr>
317<td>REQUEST_METHOD</td>
318<td>
319 The method with which the information request was
320 issued: "GET", "POST" etc.</td>
321</tr>
322<tr>
323<td>REQUEST_URI</td>
324<td>
325 The web page originally requested by the client.</td>
326</tr>
327<tr>
328<td>SCRIPT_FILENAME</td>
329<td>
330 The location of the current web page on the server.</td>
331</tr>
332<tr>
333<td>SCRIPT_NAME</td>
334<td>
335 The name of the web page.</td>
336</tr>
337<tr>
338<td>SERVER_ADDR</td>
339<td>
340 The server's IP address.</td>
341</tr>
342<tr>
343<td>SERVER_NAME</td>
344<td>
345 The server's hostname or IP address.</td>
346</tr>
347<tr>
348<td>SERVER_PORT</td>
349<td>
350 The port on which the server received the request.</td>
351</tr>
352<tr>
353<td>SERVER_PROTOCOL</td>
354<td>
355 The protocol used by the server. E.g. "HTTP/1.1".</td>
356</tr>
357<tr>
358<td>SERVER_SOFTWARE</td>
359<td>
360 The name and version of the server software that is
361 answering the client request.</td>
362</tr>
363<tr>
364<td>UNIQUE_ID</td>
365<td>
366 A token used to identify the current session if one
367 has been established.</td>
368</tr>
369</table>
370</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
371 on improving documentation for Apache Tomcat.<br><br>
372 If you have trouble and need help, read
373 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
374 and ask your question on the tomcat-users
375 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
376 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
377 The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.
378 Comments may be removed by our moderators if they are either
379 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
380 var comments_shortname = 'tomcat';
381 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/ssi-howto.html';
382 (function(w, d) {
383 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
384 d.write('<div id="comments_thread"><\/div>');
385 var s = d.createElement('script');
386 s.type = 'text/javascript';
387 s.async = true;
388 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
389 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
390 }
391 else {
392 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
393 }
394 })(window, document);
395 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
396 Copyright &copy; 1999-2013, Apache Software Foundation
397 </em></font></div></td></tr></table></body></html>