Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 67d615191938bb60e9b73af6701f5339749950ca / . / tomcat-uid / webapps / docs / ssi-howto.html
blob: e0d5a75f01257f36b9cc7d13cf848884c7867cec [file] [log] [blame]
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 (6.0.41) - SSI How To</title><meta name="author" content="Glenn L. Nielsen"><style type="text/css" media="print">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </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="
5 The Apache Tomcat Servlet/JSP Container
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]6 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.41, May 19 2014</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="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="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></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></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">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></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat 6.0</h1><h2>SSI How To</h2><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>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]7<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>
8</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>
9
10<p>SSI (Server Side Includes) are directives that are placed in HTML pages,
11and evaluated on the server while the pages are being served. They let you
12add dynamically generated content to an existing HTML page, without having
13to serve the entire page via a CGI program, or other dynamic technology.
14</p>
15
16<p>Within Tomcat SSI support can be added when using Tomcat as your
17HTTP server and you require SSI support. Typically this is done
18during development when you don't want to run a web server like Apache.</p>
19
20<p>Tomcat SSI support implements the same SSI directives as Apache. See the
21<a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
22Apache Introduction to SSI</a> for information on using SSI directives.</p>
23
24<p>SSI support is available as a servlet and as a filter. You should use one
25or the other to provide SSI support but not both.</p>
26
27<p>Servlet based SSI support is implemented using the class
28<code>org.apache.catalina.ssi.SSIServlet</code>. Traditionally, this servlet
29is mapped to the URL pattern "*.shtml".</p>
30
31<p>Filter based SSI support is implemented using the class
32<code>org.apache.catalina.ssi.SSIFilter</code>. Traditionally, this filter
33is mapped to the URL pattern "*.shtml", though it can be mapped to "*" as
34it will selectively enable/disable SSI processing based on mime types. The
35contentType init param allows you to apply SSI processing to JSP pages,
36javascript, or any other content you wish.</p>
37<p>By default SSI support is disabled in Tomcat.</p>
38</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>
39
40<p><strong>CAUTION</strong> - SSI directives can be used to execute programs
41external to the Tomcat JVM. If you are using the Java SecurityManager this
42will bypass your security policy configuration in <code>catalina.policy.</code>
43</p>
44
45<p>To use the SSI servlet, remove the XML comments from around the SSI servlet
46and servlet-mapping configuration in
47<code>$CATALINA_BASE/conf/web.xml</code>.</p>
48
49<p>To use the SSI filter, remove the XML comments from around the SSI filter
50and filter-mapping configuration in
51<code>$CATALINA_BASE/conf/web.xml</code>.</p>
52
53<p>Only Contexts which are marked as privileged may use SSI features (see the
54privileged property of the Context element).</p>
55
56</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>
57
58<p>There are several servlet init parameters which can be used to
59configure the behaviour of the SSI servlet.
60<ul>
61<li><strong>buffered</strong> - Should output from this servlet be buffered?
62(0=false, 1=true) Default 0 (false).</li>
63<li><strong>debug</strong> - Debugging detail level for messages logged
64by this servlet. Default 0.</li>
65<li><strong>expires</strong> - The number of seconds before a page with SSI
66directives will expire. Default behaviour is for all SSI directives to be
67evaluated for every request.</li>
68<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
69paths be interpreted as relative to the context root, instead of the server
70root? Default false.</li>
71<li><strong>inputEncoding</strong> - The encoding to be assumed for SSI
72resources if one cannot be determined from the resource itself. Default is
73the default platform encoding.</li>
74<li><strong>outputEncoding</strong> - The encoding to be used for the result
75of the SSI processing. Default is UTF-8.</li>
76<li><strong>allowExec</strong> - Is the exec command enabled? Default is
77false.</li>
78</ul>
79</p>
80
81</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>
82
83<p>There are several filter init parameters which can be used to
84configure the behaviour of the SSI filter.
85<ul>
86<li><strong>contentType</strong> - A regex pattern that must be matched before
87SSI processing is applied. When crafting your own pattern, don't forget that a
88mime content type may be followed by an optional character set in the form
89"mime/type; charset=set" that you must take into account. Default is
90"text/x-server-parsed-html(;.*)?".</li>
91<li><strong>debug</strong> - Debugging detail level for messages logged
92by this servlet. Default 0.</li>
93<li><strong>expires</strong> - The number of seconds before a page with SSI
94directives will expire. Default behaviour is for all SSI directives to be
95evaluated for every request.</li>
96<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
97paths be interpreted as relative to the context root, instead of the server
98root? Default false.</li>
99<li><strong>allowExec</strong> - Is the exec command enabled? Default is
100false.</li>
101</ul>
102</p>
103
104</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>
105<p>Server Side Includes are invoked by embedding SSI directives in an HTML document
106 whose type will be processed by the SSI servlet. The directives take the form of an HTML
107 comment. The directive is replaced by the results of interpreting it before sending the
108 page to the client. The general form of a directive is: </p>
109<p> <code>&lt;!--#directive [parm=value] --&gt;</code></p>
110<p>The directives are:
111<ul>
112<li>
113<strong>config</strong> - <code>&lt;!--#config timefmt="%B %Y" --&gt;</code>
114Used to set the format of dates and other items processed by SSI
115</li>
116<li>
117<strong>echo</strong> - <code>&lt;!--#echo var="VARIABLE_NAME" --&gt;</code>
118will be replaced by the value of the variable.
119</li>
120<li>
121<strong>exec</strong> - Used to run commands on the host system.
122</li>
123<li>
124<strong>include</strong> - <code>&lt;!--#include virtual="file-name" --&gt;</code>
125inserts the contents
126</li>
127<li>
128<strong>flastmod</strong> - <code>&lt;!--#flastmod file="filename.shtml" --&gt;</code>
129Returns the time that a file was lost modified.
130</li>
131<li>
132<strong>fsize</strong> - <code>&lt;!--#fsize file="filename.shtml" --&gt;</code>
133Returns the size of a file.
134</li>
135<li>
136<strong>printenv</strong> - <code>&lt;!--#printenv --&gt;</code>
137Returns the list of all the defined variables.
138</li>
139<li>
140<strong>set</strong> - <code>&lt;!--#set var="foo" value="Bar" --&gt;</code>
141is used to assign a value to a user-defind variable.
142</li>
143<li>
144<strong>if elif endif else</strong> - Used to create conditional sections. For example:</li>
145<code>&lt;!--#config timefmt="%A" --&gt;<br>
146 &lt;!--#if expr="$DATE_LOCAL = /Monday/" --&gt;<br>
147 &lt;p&gt;Meeting at 10:00 on Mondays&lt;/p&gt;<br>
148 &lt;!--#elif expr="$DATE_LOCAL = /Friday/" --&gt;<br>
149 &lt;p&gt;Turn in your time card&lt;/p&gt;<br>
150 &lt;!--#else --&gt;<br>
151 &lt;p&gt;Yoga class at noon.&lt;/p&gt;<br>
152 &lt;!--#endif --&gt;</code>
153 </ul>
154</p>
155See the
156<p> <a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
157Apache Introduction to SSI</a> for more information on using SSI directives.</p>
158</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>
159<p>The SSI servlet currently implements the following variables:
160</p>
161<table border="1">
162<tr>
163<th>Variable Name</th>
164<th>Description</th>
165</tr>
166
167<tr>
168<td>AUTH_TYPE</td>
169<td>
170 The type of authentication used for this user: BASIC, FORM, etc.</td>
171</tr>
172
173<tr>
174<td>CONTENT_LENGTH</td>
175<td>
176 The length of the data (in bytes or the number of
177 characters) passed from a form.</td>
178</tr>
179
180<tr>
181<td>CONTENT_TYPE</td>
182<td>
183 The MIME type of the query data, such as "text/html".</td>
184</tr>
185
186<tr>
187<td>DATE_GMT</td>
188<td>
189Current date and time in GMT</td>
190</tr>
191
192<tr>
193<td>DATE_LOCAL</td>
194<td>
195Current date and time in the local time zone</td>
196</tr>
197<tr>
198<td>DOCUMENT_NAME</td>
199<td>
200The current file</td>
201</tr>
202<tr>
203<td>DOCUMENT_URI</td>
204<td>
205Virtual path to the file</td>
206</tr>
207
208<tr>
209<td>GATEWAY_INTERFACE</td>
210<td>
211 The revision of the Common Gateway Interface that the
212 server uses if enabled: "CGI/1.1".</td>
213</tr>
214
215<tr>
216<td>HTTP_ACCEPT</td>
217<td>
218 A list of the MIME types that the client can accept.</td>
219</tr>
220
221<tr>
222<td>HTTP_ACCEPT_ENCODING</td>
223<td>
224 A list of the compression types that the client can accept.</td>
225</tr>
226
227<tr>
228<td>HTTP_ACCEPT_LANGUAGE</td>
229<td>
230 A list of the languages that the client can accept.</td>
231</tr>
232<tr>
233<td>HTTP_CONNECTION</td>
234<td>
235 The way that the connection from the client is being managed:
236 "Close" or "Keep-Alive".</td>
237</tr>
238<tr>
239<td>HTTP_HOST</td>
240<td>
241 The web site that the client requested.</td>
242</tr>
243<tr>
244<td>HTTP_REFERER</td>
245<td>
246 The URL of the document that the client linked from.</td>
247</tr>
248<tr>
249<td>HTTP_USER_AGENT</td>
250<td>
251 The browser the client is using to issue the request.</td>
252</tr>
253<tr>
254<td>LAST_MODIFIED</td>
255<td>
256Last modification date and time for current file</td>
257</tr>
258<tr>
259<td>PATH_INFO</td>
260<td>
261 Extra path information passed to a servlet.</td>
262</tr>
263<tr>
264<td>PATH_TRANSLATED</td>
265<td>
266 The translated version of the path given by the
267 variable PATH_INFO.</td>
268</tr>
269<tr>
270<td>QUERY_STRING</td>
271<td>
272The query string that follows the "?" in the URL.
273</td>
274</tr>
275<tr>
276<td>QUERY_STRING_UNESCAPED</td>
277<td>
278Undecoded query string with all shell metacharacters escaped
279with "\"</td>
280</tr>
281<tr>
282<td>REMOTE_ADDR</td>
283<td>
284 The remote IP address of the user making the request.</td>
285</tr>
286<tr>
287<td>REMOTE_HOST</td>
288<td>
289 The remote hostname of the user making the request.</td>
290</tr>
291<tr>
292<td>REMOTE_PORT</td>
293<td>
294 The port number at remote IP address of the user making the request.</td>
295</tr>
296<tr>
297<td>REMOTE_USER</td>
298<td>
299 The authenticated name of the user.</td>
300</tr>
301<tr>
302<td>REQUEST_METHOD</td>
303<td>
304 The method with which the information request was
305 issued: "GET", "POST" etc.</td>
306</tr>
307<tr>
308<td>REQUEST_URI</td>
309<td>
310 The web page originally requested by the client.</td>
311</tr>
312<tr>
313<td>SCRIPT_FILENAME</td>
314<td>
315 The location of the current web page on the server.</td>
316</tr>
317<tr>
318<td>SCRIPT_NAME</td>
319<td>
320 The name of the web page.</td>
321</tr>
322<tr>
323<td>SERVER_ADDR</td>
324<td>
325 The server's IP address.</td>
326</tr>
327<tr>
328<td>SERVER_NAME</td>
329<td>
330 The server's hostname or IP address.</td>
331</tr>
332<tr>
333<td>SERVER_PORT</td>
334<td>
335 The port on which the server received the request.</td>
336</tr>
337<tr>
338<td>SERVER_PROTOCOL</td>
339<td>
340 The protocol used by the server. E.g. "HTTP/1.1".</td>
341</tr>
342<tr>
343<td>SERVER_SOFTWARE</td>
344<td>
345 The name and version of the server software that is
346 answering the client request.</td>
347</tr>
348<tr>
349<td>UNIQUE_ID</td>
350<td>
351 A token used to identify the current session if one
352 has been established.</td>
353</tr>
354</table>
355</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
356 Copyright &copy; 1999-2014, Apache Software Foundation
357 </em></font></div></td></tr></table></body></html>