Apache 模块 mod_include

Summary

该模块提供了一个过滤器，该过滤器将在文件发送到 Client 端之前对其进行处理。处理由特殊格式的 SGML Comments(称为元素)控制。这些元素允许条件文本，包含其他文件或程序以及环境变量的设置和打印。

启用服务器端包含

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

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

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

Options +Includes

为了向后兼容，server-parsed handler还激活了 INCLUDES 过滤器。同样，Apache 将为任何类型为text/x-server-parsed-html或text/x-server-parsed-html3的 mime 文件激活 INCLUDES 过滤器(并且结果输出将具有text/html的 mime 类型)。

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

服务器端包含的 PATH_INFO

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

Available Elements

该文档被解析为 HTML 文档，并嵌入了作为 SGML Comments 的特殊命令。命令具有以下语法：

<!--#element attribute=value attribute=value ... -->

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

下表列出了允许的元素：

SSI 元素可以由mod_include以外的模块定义。实际上，exec元素由mod_cgi提供，并且仅在加载此模块后可用。

Comment 元素

此命令不输出任何内容。它的唯一用途是在文件中添加 Comments。这些 Comment 未打印。

此语法在 2.4.21 版和更高版本中可用。

<!--#comment Blah Blah Blah -->

配置元素

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

• echomsg(* Apache 2.1 及更高版本*)

  • 该值是如果echo元素试图回显未定义的变量则发送回 Client 端的消息。这将覆盖所有SSIUndefinedEcho指令。

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

• errmsg

  • 如果在解析文档时发生错误，则该值为发送回 Client 端的消息。这将覆盖所有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"" -->

回声元素

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

Attributes:

• 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属性才能生效。

Example

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

exec 元素

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

• cgi

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

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

Example

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

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

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

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

• cmd

  • 服务器将使用/bin/sh执行给定的字符串。除了通常的 CGI 变量集之外，该命令还可以使用include variables。

几乎总是首选使用#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 脚本本身的大小。

This file is <!--#fsize virtual="/docs/mod/mod_include.html" --> bytes.

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

flastmod 元素

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

包含元素

此命令将另一个文档或文件的文本插入已分析的文件。任何包含的文件都受通常的访问控制。如果包含已解析文件的目录设置为Options IncludesNOEXEC，则仅包含文本为MIME-type(text/plain，text/html等)的文档。否则，将使用命令中提供的完整 URL(包括任何查询字符串)正常调用 CGI 脚本。

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

• file

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

• virtual

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

URL 是根据属性构造的，如果 Client 端访问的 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元素)。没有属性。

Example

<pre> <!--#printenv --> </pre>

设置的元素

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

• var

  • 要设置的变量的名称。

• value

  • 给出变量的值。

• decoding

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

• encoding

  • 指定 Apache 在设置特殊字符之前应如何对其进行编码。默认值为none，不进行任何编码。如果设置为url，urlencoding，base64或entity，则将分别执行 URL 编码，application/x-www-form-urlencoded 编码，base64 编码或 HTML 实体编码。可以使用逗号分隔来指定多个编码。编码设置将一直有效，直到遇到下一个编码属性，或者元素结束。 encoding属性必须先于相应的var属性才有效。去除所有解码后，再应用编码。

Example

<!--#set var="category" value="help" -->

Include Variables

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

• DATE_GMT

  • Greenwich 标准时间的当前日期。

• DATE_LOCAL

  • 本地时区的当前日期。

• DOCUMENT_ARGS

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

• DOCUMENT_NAME

  • 用户请求的文档的文件名(不包括目录)。

• DOCUMENT_PATH_INFO

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

• DOCUMENT_URI

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

• LAST_MODIFIED

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

• QUERY_STRING_UNESCAPED

  • 如果对活动 SSI 文档的请求中存在查询字符串，则此变量包含(％解码)查询字符串，对于 Shell 程序使用会转义(特殊字符，例如&等，后跟反斜杠)。如果不存在查询字符串，则不会设置它。如果不需要 Shell 转义，请使用DOCUMENT_ARGS。

• USER_NAME

  • 文件所有者的用户名。

Variable Substitution

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

<!--#set var="cur" value="\$test" -->

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

<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->

如果REMOTE_HOST是“ X”而REQUEST_METHOD是“ Y”，则将Zed变量设置为“ X_Y”。

流量控制元素

基本的流量控制元素是：

<!--#if expr="test_condition" --> <!--#elif expr="test_condition" --> <!--#else --> <!--#endif -->

if元素的工作方式类似于编程语言中的 if 语句。将评估测试条件，如果结果为 true，则直到下一个elif，else或endif元素的文本都将包含在输出流中。

如果原始的 test_condition 为 false，则elif或else语句用于将文本放入输出流。这些元素是可选的。

endif元素结束if元素并且是必需的。

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

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

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

<!--#if expr='-R "10.0.0.0/8"' --> from local net <!--#else --> from somewhere else <!--#endif -->

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

<!--#if expr='v("foo") = "bar"' --> foo is bar <!--#endif -->

传统表达式语法

本节描述SSILegacyExprParser设置为on时#if expr元素的语法。

• string

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

• -A string

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

Example

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

• string1 = string2 string1 == string2 string1 != string2

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

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

Example

<!--#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

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

<!--#if expr="$a = test1 && $b = test2" --> <!--#if expr="($a = test1) && ($b = test2)" -->

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

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

string1 string2产生string1 string2

and

'string1 string2'产生string1 string2。

SSIEndTag Directive

此伪指令更改mod_include查找以标记 include 元素结尾的字符串。

SSIEndTag "%>"

See also

• SSIStartTag

SSIErrorMsg Directive

mod_include遇到错误时，SSIErrorMsg伪指令更改显示的错误消息。对于生产服务器，您可以考虑将默认错误消息更改为"<!-- Error -->"，以使该消息不会显示给用户。

此伪指令与<!--#config errmsg=message -->元素具有相同的作用。

SSIErrorMsg "<!-- Error -->"

SSIETag Directive

在正常情况下，用mod_include过滤的文件可能包含动态生成的元素，或者可能独立于原始文件而更改的元素。结果，默认情况下，系统要求服务器不要通过在请求 Comments 中添加no-etag来为响应生成ETagHeaders。

SSIETag指令禁止此行为，并允许服务器生成ETagHeaders。这可用于启用输出缓存。请注意，后端服务器或动态内容生成器可能会生成自己的 ETag，而忽略no-etag，并且无论此设置的值如何，此 ETag 都将通过mod_include传递。 SSIETag可以采用以下值：

• off

  • no-etag将添加到请求 Comments 中，并且要求服务器不要生成 ETag。如果服务器忽略no-etag的值并仍然生成 ETag，则将尊重 ETag。

• on

  • 将尊重现有的 ETag，服务器生成的 ETag 将在响应中传递。

SSILastModified Directive

在正常情况下，用mod_include过滤的文件可能包含动态生成的元素，或者可能独立于原始文件而更改的元素。如此一来默认情况下从响应中剥离Last-ModifiedHeaders。

SSILastModified指令将覆盖此行为，并允许Last-ModifiedHeaders(如果已经存在)被尊重，或者被设置(如果 Headers 不存在)。这可用于启用输出缓存。 SSILastModified可以采用以下值：

• off

  • 除非响应中将XBitHack伪指令设置为full，否则将从响应中剥离Last-ModifiedHeaders。

• on

  • 如果响应中已经存在Last-ModifiedHeaders，并且响应为文件且 Headers 丢失，则会将其添加到响应中。 SSILastModified指令优先于XBitHack。

SSILegacyExprParser Directive

从版本 2.3.13 开始，mod_include已针对#if流控制元素中的条件表达式切换到新的ap_expr语法。该伪指令允许切换到与 Apache HTTPD 2.2.x 及更早版本兼容的old syntax。

SSIStartTag Directive

此伪指令更改mod_include寻找的字符串以标记要处理的 include 元素。

如果您有 2 台服务器解析一个文件的输出，每个服务器处理不同的命令(可能在不同的时间)，则可能要使用此选项。

SSIStartTag "<%"
SSIEndTag   "%>"

上面给出的示例还指定了一个匹配的SSIEndTag，将允许您使用 SSI 指令，如下例所示：

具有备用开始和结束标签的 SSI 指令

<%printenv %>

See also

• SSIEndTag

SSITimeFormat Directive

该指令更改在回显DATE环境变量时显示日期字符串的格式。格式字符串与 C 标准库中的strftime(3)相同。

此伪指令与<!--#config timefmt=formatstring -->元素具有相同的作用。

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

上述指令将导致时间以“ 2002 年 6 月 14 日 22:26”的格式显示。

SSIUndefinedEcho Directive

当未设置变量并“回显”变量时，此伪指令更改mod_include显示的字符串。

SSIUndefinedEcho "<!-- undef -->"

XBitHack Directive

XBitHack指令控制普通 html 文档的解析。该指令仅影响与MIME-type text/html关联的文件。 XBitHack可以采用以下值：

• off

  • 对可执行文件没有特殊处理。

• on

  • 设置了用户执行位的任何text/html文件都将被视为服务器解析的 html 文档。

• full

  • 至于on，还要测试组执行位。如果已设置，则将返回文件的Last-modified日期设置为文件的最后修改时间。如果未设置，则不发送最后修改日期。将该位置 1，则 Client 端和代理可以缓存请求结果。