Apache模块mod_include

启用服务器端包含

服务器端包含由INCLUDES 过滤器实现 。如果包含服务器端include指令的文档的扩展名为.shtml，则以下指令将使Apache解析它们，并将结果文档分配为mime类型 text/html：

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

必须为包含shtml文件的目录提供以下指令（通常在一个 <Directory>节中，但是.htaccess如果AllowOverride Options 设置了该指令，则在文件中 也有效）：

Options +Includes

为了向后兼容，server-parsed 处理程序还激活INCLUDES过滤器。同样，Apache将为任何MIME类型为text/x-server-parsed-html或的 文档激活INCLUDES过滤器 text/x-server-parsed-html3（并且结果输出将为mime类型text/html）。

有关更多信息，请参见我们的服务器端包含教程。

服务器端包含的PATH_INFO

PATH_INFO默认情况下，为服务器端处理的文件不再包含带有（跟踪路径名信息）的请求。您可以使用AcceptPathInfo指令来配置服务器以接受请求PATH_INFO。

可用元素

该文档被解析为HTML文档，并嵌入了作为SGML注释的特殊命令。命令的语法为：

该值通常用双引号引起来，但也可以使用单引号（'）和反引号（`）。许多命令只允许一个属性-值对。请注意，注释终止符（-->）之前应留有空格，以确保它不被视为SSI令牌的一部分。请注意，前导<!--#是一个 令牌，并且不能包含任何空格。

下表列出了允许的元素：

元件	描述
comment	SSI评论
config	配置输出格式
echo	打印变量
exec	执行外部程序
fsize	文件的打印尺寸
flastmod	打印文件的最后修改时间
include	包括一个文件
printenv	打印所有可用变量
set	设置变量的值

SSI元素可以由之外的其他模块定义 mod_include。实际上，该exec元素是由提供的 mod_cgi，只有在加载了此模块后才可用。

评论元素

该命令不输出任何内容。它的唯一用途是在文件中添加注释。这些评论未打印。

2.4.21版和更高版本中提供了此语法。

配置元素

此命令控制解析的各个方面。有效属性是：

echomsg（Apache 2.1及更高版本）

该值是一条消息，如果echo元素尝试回显未定义的变量，则该消息将发送回客户端。这将覆盖所有SSIUndefinedEcho指令。

<!--#config echomsg="[Value Undefined]" -->

errmsg

该值是如果在解析文档时发生错误则发送回客户端的消息。这将覆盖所有SSIErrorMsg指令。

<!--#config errmsg="[Oops, something broke.]" -->

sizefmt

该值设置显示文件大小时要使用的格式。有效值适用bytes 于以字节为单位的计数，或者abbrev适用于以Kb或Mb为单位的计数，例如，1024字节的大小将被打印为“ 1K”。

<!--#config sizefmt="abbrev" -->

timefmt

该值是strftime(3)打印日期时库例程使用的字符串 。

<!--#config timefmt=""%R, %B %d, %Y"" -->

回声元素

此命令显示以下定义的包含变量之一。如果未设置变量，则结果由SSIUndefinedEcho指令确定。打印的任何日期均受当前配置的限制timefmt。

属性：

var

该值是要打印的变量的名称。

decoding

指定Apache在进一步处理变量之前是否应从变量中删除编码。默认值为none，其中将不执行解码。如果设置为 url，则将执行URL解码（也称为％-encoding；这适用于链接中的URL等）。如果设置为urlencoded，则将剥离application / x-www-form-urlencoded兼容编码（在查询字符串中找到）。如果设置为base64，则base64将被解码，如果设置为entity，HTML实体编码将被剥离。在对该变量进行任何进一步编码之前，先完成解码。通过指定多个逗号分隔的编码，可以剥离多种编码。解码设置将一直有效，直到遇到下一个解码属性，或者元素结束。

该decoding属性必须在相应var属性之前才能生效。

encoding

指定Apache在输出变量之前应如何编码包含在变量中的特殊字符。如果设置为none，则不会进行编码。如果设置为 url，则将执行URL编码（也称为％-encoding；这适用于链接中的URL等）。如果设置为urlencoded，则将改为执行application / x-www-form-urlencoded兼容编码，并且应与查询字符串一起使用。如果设置为base64，将执行base64编码。在echo元素的开头，默认设置为 entity，导致实体编码（这在块级HTML元素的上下文中是适当的， 例如一段文本）。可以通过添加一个encoding属性，该属性将一直有效，直到encoding遇到下一个属性或元素结束（以先到者为准）。

该encoding属性必须在相应var属性之前才能生效。

为了避免跨站点脚本问题，您应该 始终对用户提供的数据进行编码。

例

<!--#echo encoding="entity" var="QUERY_STRING" -->

exec元素

该exec命令执行给定的Shell命令或CGI脚本。它需要mod_cgi存在于服务器中。如果Options IncludesNOEXEC设置为，则完全禁用此命令。有效属性是：

cgi

该值指定CGI脚本的（％编码）URL路径。如果路径不是以斜杠（/）开头，则将其视为相对于当前文档。即使服务器通常无法正常识别此路径，该路径引用的文档也将作为CGI脚本调用。但是，必须为CGI脚本（使用ScriptAlias 或Options ExecCGI）启用包含脚本的目录。

为CGI脚本提供了来自客户端的原始请求的PATH_INFOand查询字符串（QUERY_STRING）；这些不能在URL路径中指定。除标准CGI环境外，脚本还可以使用include变量。

例

<!--#exec cgi="/cgi-bin/example.cgi" -->

如果脚本返回的是Location:标头而不是输出，那么它将被转换为HTML锚。

该include virtual 元素应优先于使用exec cgi。特别是，如果您需要使用查询字符串将其他参数传递给CGI程序，则不能使用来完成此操作exec cgi，而可以使用来完成include virtual，如下所示：

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

cmd

服务器将使用执行指定的字符串 /bin/sh。在包括变量可用来指挥，除了通常的一套CGI变量。

使用#include virtual几乎总是优先于使用任一#exec cgi或#exec cmd。前者（#include virtual）使用标准的Apache子请求机制来包含文件或脚本。它经过了更好的测试和维护。

另外，在某些平台上，例如Win32，以及在使用suexec的 unix上，不能在指令中将参数传递给命令exec，否则不能在命令中包含空格。因此，尽管以下内容将在unix上的非suexec配置下工作，但在Win32或运行suexec时不会产生预期的结果：

<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->

fsize元素

此命令根据sizefmt格式说明打印指定文件的大小。属性：

file

该值是相对于包含正在解析的当前文档的目录的路径。

This file is <!--#fsize file="mod_include.html" --> bytes.

的值file不能以斜杠（/）开头，也不能包含../以引用当前目录上方或文档根目录之外的文件。尝试这样做将导致错误消息： The given path was above the root path。

virtual

该值是一个（％编码）URL路径。如果它不是以斜杠（/）开头，则将其视为相对于当前文档。请注意，这并没有打印任何CGI输出的大小，但CGI脚本本身的大小。

请注意，在许多情况下，这两者是完全相同的。但是，该file属性不考虑URL空间别名。

flastmod元素

该命令根据timefmt格式说明打印指定文件的最后修改日期。这些属性与fsize命令相同 。

包含元素

此命令将另一个文档或文件的文本插入已分析的文件。任何包含的文件都受通常的访问控制。如果包含解析的文件目录中有 选项 IncludesNOEXEC集，则只能用文本文档 的MIME类型（text/plain， text/html等）将被纳入。否则，将使用命令中提供的完整URL（包括任何查询字符串）正常调用CGI脚本。

属性定义文档的位置，并且可以在include元素中多次出现。依次对赋予include命令的每个属性进行一次包含。有效属性是：

file

该值是相对于包含正在解析的当前文档的目录的路径。它不能包含../，也不能是绝对路径。因此，您不能在目录根目录中包含文档根目录之外或当前文档之上的文件。该virtual属性应始终优先于此属性使用。

virtual

该值是一个（％编码）URL路径。URL不能包含方案或主机名，只能包含路径和可选的查询字符串。如果它不是以斜杠（/）开头，则将其视为相对于当前文档。

URL是从属性构造的，并且如果客户机访问了URL，则服务器将返回的输出包括在解析的输出中。因此，可以嵌套包含的文件。

如果指定的URL是CGI程序，则将执行该程序并将其输出替换为解析文件中的伪指令。您可以在CGI网址中包含查询字符串：

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

include virtual应该优先使用，以exec cgi将CGI程序的输出包含到HTML文档中。

如果该KeptBodySize 指令已正确配置且对该包含的文件有效，则尝试将POST请求发送到封闭的HTML文档的尝试也将作为POST请求传递给子请求。如果没有该指令，则所有子请求都将作为GET请求处理。

onerror

该值是（％编码）URL路径，如果先前尝试包含文件或虚拟属性的尝试失败，则显示该URL路径。为了有效，必须在覆盖文件或虚拟属性之后指定此属性。如果尝试包括onerror路径失败，或者未指定onerror，则将包含默认错误消息。

# Simple example
<!--#include virtual="/not-exist.html" onerror="/error.html" -->

# Dedicated onerror paths
<!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->

printenv元素

这将打印出所有现有变量及其值的纯文本列表。特殊字符echo在输出之前已经过实体编码（有关详细信息，请参见元素）。没有属性。

设置元素

这将设置变量的值。属性：

var

要设置的变量的名称。

value

给出变量的值。

decoding

指定Apache在进一步处理变量之前是否应从变量中删除编码。默认值为none，其中将不执行解码。如果设置为 url，urlencoded，base64 或entity，URL解码，应用程序/ x-WWW窗体-urlencoded解码，解码的base64或HTML实体解码将被分别执行。通过用逗号分隔可以指定多个解码。解码设置将一直有效，直到遇到下一个解码属性，或者元素结束。该decoding 属性必须在相应 var属性之前才能生效。

encoding

指定Apache在设置特殊字符之前应如何对变量中包含的特殊字符进行编码。默认值为 none，不进行任何编码。如果设置为 url，urlencoding，base64 或entity，URL编码，应用程序/ x-WWW窗体-urlencoded编码，Base64编码或HTML实体编码将被分别执行。可以使用逗号分隔来指定多个编码。编码设置将一直有效，直到遇到下一个编码属性，或者元素结束。该 encoding属性必须在相应var属性之前才能生效。去除所有解码之后，再应用编码。

包含变量

除了标准CGI环境中的变量之外，这些变量还可用于echo命令for if和elif，以及文档调用的任何程序。

DATE_GMT

格林威治标准时间的当前日期。

DATE_LOCAL

本地时区的当前日期。

DOCUMENT_ARGS

此变量包含活动SSI文档的查询字符串，如果不包含查询字符串，则为空字符串。对于通过includeSSI指令调用 QUERY_STRING 的子请求，DOCUMENT_ARGS将代表子请求 的查询字符串，并将代表SSI文档的查询字符串。（在Apache HTTP Server 2.4.19和更高版本中可用。）

DOCUMENT_NAME

用户请求的文档的文件名（不包括目录）。

DOCUMENT_PATH_INFO

尾随路径名信息。有关AcceptPathInfo更多信息，请参见指令PATH_INFO。

DOCUMENT_URI

用户请求的文档的（％解码）URL路径。请注意，在嵌套包含文件的情况下，这 不是当前文档的URL。还要注意，如果在内部修改了URL（例如，通过alias或directoryindex），则会显示修改后的URL。

LAST_MODIFIED

用户请求的文档的最后修改日期。

QUERY_STRING_UNESCAPED

如果对活动SSI文档的请求中存在查询字符串，则此变量包含（％解码）查询字符串，可将其转义以用于shell使用（特殊字符（例如，诸如此类，&以反斜杠开头））。如果不存在查询字符串，则不会设置它。DOCUMENT_ARGS如果不需要外壳转义，请使用。

USER_NAME

文件所有者的用户名。

可变替代

在大多数情况下，变量替换是在带引号的字符串内完成的，在这些情况下，它们可能会合理地作为SSI指令的参数出现。这包括config， exec，flastmod，fsize， include，echo，和set 指令。如果SSILegacyExprParser将设置为on，则条件运算符的参数中也会发生替换。您可以使用反斜杠引号在字符串中插入文字美元符号：

如果需要在一个字符序列中间替换一个变量引用，否则该变量引用本身就可以被视为有效的标识符，可以通过将引用括在括号中来进行歧义消除， 例如：

如果is 和都将Zed变量设置为“ ”。X_YREMOTE_HOSTXREQUEST_METHODY

流量控制元件

基本的流量控制元素是：

该if元件的工作原理就像一个编程语言中的if语句。测试条件被评估，并且如果结果为真，则该文本直到下一个elif， else或endif元件被包括在输出流。

该elif或else语句用于将文本到输出流，如果原来的 test_condition是假的。这些元素是可选的。

该endif元件端if元件和是必需的。

test_condition是遵循ap_expr语法的布尔表达式 。可以使用来更改语法以使其与Apache HTTPD 2.2.x兼容SSILegacyExprParser。

用var元素设置的SSI变量将导出到请求环境中，并且可以使用reqenv函数进行访问 。作为快捷方式，函数名称 v也可以在里面找到mod_include。

如果客户端IP地址属于10.0.0.0/8子网，则下面的示例将打印“来自本地网络”。

如果变量foo设置为值“ bar” ，则下面的示例将显示“ foo is bar”。

传统表达式语法

本部分介绍了#if expr 元素的语法（如果SSILegacyExprParser 设置为）on。

string

如果字符串不为空，则为true

-A string

如果可以通过配置访问由字符串表示的URL，则为true，否则为false。如果要向未授权查看URL的用户隐藏页面上的内容（例如指向该URL的链接），这很有用。请注意，仅测试URL是否会被授予访问权限，而不会测试URL是否存在。

例

<!--#if expr="-A /private" -->
Click <a href="/private">here</a> to access private information.
<!--#endif -->

string1 = string2
string1 == string2
string1 != string2

比较string1和string2。如果 string2具有形式， 则将其视为正则表达式。正则表达式由PCRE引擎实现，并且语法与perl 5中的语法相同。请注意，这只是其别名 ，其行为完全相同。/string2/===

如果您匹配正数（=或==），则可以捕获正则表达式的分组部分。拍摄的部分被保存在特殊变量$1... $9。正则表达式匹配的整个字符串存储在特殊变量中$0

例

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
<!--#endif -->

string1 < string2
string1 <= string2
string1 > string2
string1 >= string2

比较string1和string2。请注意，字符串是按字面值比较的（使用 strcmp(3)）。因此，字符串“ 100”小于“ 20”。

( test_condition )

如果test_condition为true，则为true

! test_condition

如果test_condition为false，则为true

test_condition1 && test_condition2

如果test_condition1和 test_condition2均为true，则为true

test_condition1 || test_condition2

如果test_condition1或 test_condition2为true，则为true

“ =”和“ !=”的绑定比“ &&”和“ ||” 更紧密。“ !”绑定最紧密。因此，以下内容是等效的：

布尔运算符&&和|| 具有相同的优先级。因此，如果您想更紧密地绑定此类运算符，则应使用括号。

任何不被识别为变量或运算符的东西都被视为字符串。字符串也可以用引号引起来 'string'。无引号的字符串不能包含空格（空格和制表符），因为它用于分隔标记（例如变量）。如果在一行中找到多个字符串，则使用空格将它们串联起来。所以，

SSIEndTag "%>"

SSIErrorMsg "<!-- Error -->"

SSIStartTag "<%"
SSIEndTag   "%>"

SSITimeFormat "%R, %B %d, %Y"

SSIUndefinedEcho "<!-- undef -->"