SSI

介绍

SSI（服务器端包含）是放置在 HTML 页面中的指令，并在提供页面时在服务器上进行评估。它们允许将动态生成的内容添加到现有 HTML 页面，而不必通过 CGI 程序或其他动态技术提供整个页面。

在 Tomcat 中，当使用 Tomcat 作为 HTTP 服务器时，可以添加 SSI 支持，并且需要 SSI 支持。通常，这是在开发过程中，当不想运行像 Apache 这样的 Web 服务器时完成的。

Tomcat SSI 支持实现与 Apache 相同的 SSI 指令。有关使用 SSI 指令的信息，请参阅 Apache SSI 简介。

SSI 支持以 Servlet 和过滤器的形式提供。应该使用其中一个或另一个来提供 SSI 支持，但不能同时使用两者。

基于 Servlet 的 SSI 支持是使用类 org.apache.catalina.ssi.SSIServlet 实现的。传统上，此 Servlet 映射到 URL 模式 “*.shtml”。

基于过滤器的 SSI 支持是使用类 org.apache.catalina.ssi.SSIFilter 实现的。传统上，此过滤器映射到 URL 模式 “.shtml”，但也可以映射到 “”，因为它将根据 MIME 类型选择性地启用/禁用 SSI 处理。 contentType init 参数允许您将 SSI 处理应用于 JSP 页面、JavaScript 或所需的任何其他内容。

默认情况下，SSI 支持在 Tomcat 中处于禁用状态。

安装

注意 - SSI 指令可用于执行 Tomcat JVM 外部的程序。

要使用 SSI Servlet，请从 $CATALINA_BASE/conf/web.xml 中的 SSI Servlet 和 Servlet 映射配置中删除 XML 注释。

要使用 SSI 过滤器，请从 $CATALINA_BASE/conf/web.xml 中的 SSI 过滤器和过滤器映射配置中删除 XML 注释。

只有标记为特权的上下文才能使用 SSI 功能（请参阅 Context 元素的 privileged 属性）。

Servlet 配置

有几个 servlet init 参数可用于配置 SSI servlet 的行为。

buffered - 这个 servlet 的输出应该缓冲吗？（0=false，1=true）默认值 0 （false）。
debug - 此 Servlet 记录的消息的调试详细信息级别。默认 0。
expires - 具有 SSI 指令的页面过期前的秒数。默认行为是针对每个请求评估所有 SSI 指令。
isVirtualWebappRelative - 是否应该将“虚拟”SSI 指令路径解释为相对于上下文根，而不是服务器根？默认为 false。
inputEncoding - 如果无法从资源本身确定 SSI 资源，则为 SSI 资源假定的编码。Default 是默认的平台编码。
outputEncoding - 用于 SSI 处理结果的编码。默认值为 UTF-8。
allowExec - exec 命令是否已启用？默认值为 false。

过滤器配置

有几个 filter init 参数可用于配置 SSI 过滤器的行为。

contentType - 在应用 SSI 处理之前必须匹配的正则表达式模式。在制作自己的模式时，不要忘记 mime 内容类型后面可以跟一个可选的字符集，格式为 “mime/type;charset=set“，必须考虑该选项。默认值为 “text/x-server-parsed-html（;.*)?".
debug - 此 Servlet 记录的消息的调试详细信息级别。默认 0。
expires - 具有 SSI 指令的页面过期前的秒数。默认行为是针对每个请求评估所有 SSI 指令。
isVirtualWebappRelative - 是否应该将“虚拟”SSI 指令路径解释为相对于上下文根，而不是服务器根？默认为 false。
allowExec - exec 命令是否已启用？默认值为 false。

指令

服务器端包含是通过将 SSI 指令嵌入到 HTML 文档中来调用的，该文档的类型将由 SSI servlet 处理。这些指令采用 HTML 注释的形式。该指令在将页面发送到客户端之前被解释它的结果替换。指令的一般形式是：

<!--#directive [param=value] -→

指令是：

config - <!--#config errmsg="Error occurred" sizefmt="abbrev" timefmt="%B %Y" -→ 用于设置 SSI 错误消息、SSI 处理的日期格式和文件大小。所有选项都是可选的，但至少必须使用一个。可用选项如下：
- errmsg - 用于 SSI 错误的错误消息
- sizefmt - 用于 fsize 指令中大小的格式
- timefmt - flastmod 指令中用于时间戳的格式
echo - <!--#echo var="VARIABLE_NAME" encoding="entity" -→ 将被变量的值替换。可选的 encoding 参数指定要使用的编码类型。有效值为 entity(default)、url 或 none。注意：使用实体以外的编码可能会导致安全问题。
exec - <!--#exec cmd=“file-name” -→ 用于在主机系统上运行命令。
exec - <!--#exec cgi=“file-name” -→ 这与 include virtual 指令的作用相同，实际上并不执行任何命令。
include - <!--#include file=“file-name” -→ 插入内容。该路径是相对于使用此指令的文档进行解释的，并且不是相对于上下文根或服务器根的“虚拟”路径。
include - <!--#include virtual=“file-name” -→ 插入内容。该路径被解释为相对于上下文根或服务器根的“虚拟”路径（取决于 isVirtualWebappRelative 参数）。
flastmod - <!--#flastmod file=“filename.shtml” -→ 返回上次修改文件的时间。该路径是相对于使用此指令的文档进行解释的，并且不是相对于上下文根或服务器根的“虚拟”路径。
flastmod - <!--#flastmod virtual=“filename.shtml” -→ 返回上次修改文件的时间。该路径被解释为相对于上下文根或服务器根的“虚拟”路径（取决于 isVirtualWebappRelative 参数）。
fsize - <!--#fsize file=“filename.shtml” -→ 返回文件的大小。该路径是相对于使用此指令的文档进行解释的，并且不是相对于上下文根或服务器根的“虚拟”路径。
fsize - <!--#fsize virtual=“filename.shtml” -→ 返回文件的大小。该路径被解释为相对于上下文根或服务器根的“虚拟”路径（取决于 isVirtualWebappRelative 参数）。
printenv - <!--#printenv -→ 返回所有已定义变量的列表。
set - <!--#set var=“foo” value=“Bar” -→ 用于为用户定义的变量赋值。
if elif endif else - 用于创建条件部分。例如：

<!--#config timefmt="%A" -->
<!--#if expr="$DATE_LOCAL = /Monday/" -->
<p>Meeting at 10:00 on Mondays</p>
<!--#elif expr="$DATE_LOCAL = /Friday/" -->
<p>Turn in your time card</p>
<!--#else -->
<p>Yoga class at noon.</p>
<!--#endif -->

有关使用 SSI 指令的更多信息，请参阅 Apache SSI 简介。

变量

SSI 变量是通过 jakarta.servlet.ServletRequest 对象上的请求属性实现的，并且不限于 SSI servlet。以名称 “java.”、“javax.”、“sun” 或 “org.apache.catalina.ssi.SSIMediator.” 开头的变量是保留变量，不能使用。

SSI Servlet 当前实现以下变量：

变量名Variable Name	说明Description
AUTH_TYPE	用于此用户的身份验证类型：BASIC、FORM 等。
CONTENT_LENGTH	从表单传递的数据长度（以字节或字符数为单位）。
CONTENT_TYPE	查询数据的 MIME 类型，例如 “text/html”。
DATE_GMT	当前日期和时间（GMT）
DATE_LOCAL	本地时区的当前日期和时间
DOCUMENT_NAME	当前文件
DOCUMENT_URI	文件的虚拟路径
GATEWAY_INTERFACE	服务器使用的通用网关接口（如果启用）的修订版：“CGI/1.1”。
HTTP_ACCEPT	客户端可以接受的 MIME 类型的列表。
HTTP_ACCEPT_ENCODING	客户端可以接受的压缩类型的列表。
HTTP_ACCEPT_LANGUAGE	客户端可以接受的语言列表。
HTTP_CONNECTION	管理来自客户端的连接的方式：“Close” 或 “Keep-Alive”。
HTTP_HOST	客户端请求的网站。
HTTP_REFERER	客户端链接的文档的 URL。
HTTP_USER_AGENT	客户端用于发出请求的浏览器。
LAST_MODIFIED	当前文件的上次修改日期和时间
PATH_INFO	传递给 Servlet 的额外路径信息。
PATH_TRANSLATED	变量 PATH_INFO 给出的 path 的翻译版本。
QUERY_STRING	URL 中 “？” 后面的查询字符串。
QUERY_STRING_UNESCAPED	所有 shell 元字符均以 “” 转义的未解码查询字符串
REMOTE_ADDR	发出请求的用户的远程 IP 地址。
REMOTE_HOST	发出请求的用户的远程主机名。
REMOTE_PORT	发出请求的用户的远程 IP 地址的端口号。
REMOTE_USER	经过身份验证的用户名称。
REQUEST_METHOD	发出信息请求的方法：“GET”、“POST”等。
REQUEST_URI	客户端最初请求的网页。
SCRIPT_FILENAME	当前网页在服务器上的位置。
SCRIPT_NAME	网页的名称。
SERVER_ADDR	服务器的 IP 地址。
SERVER_NAME	服务器的主机名或 IP 地址。
SERVER_PORT	服务器接收请求的端口。
SERVER_PROTOCOL	服务器使用的协议。例如“HTTP/1.1”。
SERVER_SOFTWARE	响应客户端请求的服务器软件的名称和版本。
UNIQUE_ID	用于标识当前会话的令牌（如果已建立）。

变量名Variable Name

说明Description

AUTH_TYPE

用于此用户的身份验证类型：BASIC、FORM 等。

CONTENT_LENGTH

从表单传递的数据长度（以字节或字符数为单位）。

CONTENT_TYPE

查询数据的 MIME 类型，例如 “text/html”。

DATE_GMT

当前日期和时间（GMT）

DATE_LOCAL

本地时区的当前日期和时间

DOCUMENT_NAME

当前文件

DOCUMENT_URI

文件的虚拟路径

GATEWAY_INTERFACE

服务器使用的通用网关接口（如果启用）的修订版：“CGI/1.1”。

HTTP_ACCEPT

客户端可以接受的 MIME 类型的列表。

HTTP_ACCEPT_ENCODING

客户端可以接受的压缩类型的列表。

HTTP_ACCEPT_LANGUAGE

客户端可以接受的语言列表。

HTTP_CONNECTION

管理来自客户端的连接的方式：“Close” 或 “Keep-Alive”。

HTTP_HOST

客户端请求的网站。

HTTP_REFERER

客户端链接的文档的 URL。

HTTP_USER_AGENT

客户端用于发出请求的浏览器。

LAST_MODIFIED

当前文件的上次修改日期和时间

PATH_INFO

传递给 Servlet 的额外路径信息。

PATH_TRANSLATED

变量 PATH_INFO 给出的 path 的翻译版本。

QUERY_STRING

URL 中 “？” 后面的查询字符串。

QUERY_STRING_UNESCAPED

所有 shell 元字符均以 “” 转义的未解码查询字符串

REMOTE_ADDR

发出请求的用户的远程 IP 地址。

REMOTE_HOST

发出请求的用户的远程主机名。

REMOTE_PORT

发出请求的用户的远程 IP 地址的端口号。

REMOTE_USER

经过身份验证的用户名称。

REQUEST_METHOD

发出信息请求的方法：“GET”、“POST”等。

REQUEST_URI

客户端最初请求的网页。

SCRIPT_FILENAME

当前网页在服务器上的位置。

SCRIPT_NAME

网页的名称。

SERVER_ADDR

服务器的 IP 地址。

SERVER_NAME

服务器的主机名或 IP 地址。

SERVER_PORT

服务器接收请求的端口。

SERVER_PROTOCOL

服务器使用的协议。例如“HTTP/1.1”。

SERVER_SOFTWARE

响应客户端请求的服务器软件的名称和版本。

UNIQUE_ID

用于标识当前会话的令牌（如果已建立）。