mod_headers

摘要

该模块提供了控制和修改 HTTP 请求和响应 headers 的指令。 Headers 可以合并，替换或删除。

处理订单

mod_headers提供的指令几乎可以出现在服务器 configuration 中的任何位置，并且可以通过将它们包含在configuration 部分中来限制范围。

Order 处理很重要，并且受 configuration 文件中的 order 和configuration 部分中的放置影响。如果颠倒，这两个指令会产生不同的影响：

RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID

这样，未设置MirrorID标头。如果反转，则 MirrorID 标头设置为“镜像 12”。

早期和晚期处理

mod_headers可以在请求的早期或晚期应用。正常模式是迟到的，当 running 内容 generator 和响应 Headers 之前立即设置 Request Headers 就像响应从线路发送一样。始终在操作服务器中使用延迟模式。

早期模式被设计为开发人员的 test/debugging 辅助。使用early关键字定义的指令在处理请求开始时设置。这意味着它们可以用于模拟不同的请求并设置测试用例，但这也意味着在生成响应之前，其他模块可以在任何 time 更改 headers。

因为早期指令是在遍历请求路径的 configuration 之前处理的，所以早期的 headers 只能在主服务器或虚拟 host context 中设置。早期指令不能依赖于请求路径，因此它们将在<Directory>或<Location>等上下文中失败。

例子

• 将所有以“TS”开头的请求_header 复制到响应 headers：

Header echo ^TS

• 向响应添加标头MyHeader，包括收到请求的时间戳以及开始提供请求所需的时间长度。 client 可以使用此标头来直接加载服务器或隔离 client 和服务器之间的瓶颈。

Header set MyHeader "%D %t"

导致此标头添加到响应中：

MyHeader: D=3775428 t=991424704447256

• 跟乔问好

Header set MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."

导致此标头添加到响应中：

MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.

• 当且仅当请求中存在头MyRequestHeader时，有条件地在响应上发送MyHeader。这对于构造 headers 以响应某些 client 刺激非常有用。请注意，此 example 需要mod_setenvif模块的服务。

SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader
Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader

如果 HTTP 请求中存在标头MyRequestHeader: myvalue，则响应将包含以下标头：

MyHeader: D=3775428 t=991424704447256 mytext

• 通过在目标标头中替换 https：http：来启用 DAV 以使用 Apache running HTTP 通过 SSL 硬件(问题描述)：

RequestHeader edit Destination ^https: http: early

• 在多个非排他性条件下设置相同的标头 value，但不要在最终标头中复制 value。如果以下所有条件都应用于请求(i.e.，如果请求中存在CGI，NO_CACHE和NO_STORE环境变量)：

Header merge Cache-Control no-cache env=CGI
Header merge Cache-Control no-cache env=NO_CACHE
Header merge Cache-Control no-store env=NO_STORE

然后响应将包含以下标头：

Cache-Control: no-cache, no-store

如果使用append而不是merge，则响应将包含以下标头：

Cache-Control: no-cache, no-cache, no-store

• 当且仅当 client 没有向我们发送 cookie 时，设置一个测试 cookie

Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"

• 为 HTTP 状态 code 为 200 的响应附加缓存标头

Header append Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200"

标题指令

该指令可以替换，合并或删除 HTTP 响应 headers。在内容处理程序和输出过滤器为 run 之后修改标头，允许修改传出的 headers。

可选的条件参数确定此指令将对哪些响应_header 进行操作：onsuccess(默认，可以省略)或always。两个 lists 之间的区别在于，即使出现错误，后者中包含的 headers 也会添加到响应中，并且会在内部重定向中保留(对于 example，ErrorDocument 处理程序)。另请注意，在某些情况下重复使用这两个条件的指令是有意义的，因为对于现有的 headers，always不是onsuccess的超集：

• 您正在为本地生成的 non-success(non-2xx)响应添加标头，例如重定向，在这种情况下，在最终响应中仅使用与always对应的 table。
• 您正在修改或删除由 CGI 脚本或mod_proxy_fcgi生成的标头，在这种情况下，CGI 脚本的_header 位于 table 中，对应于always而不是默认 table。
• 您正在修改或删除由某个服务器生成的标头，但默认的onsuccess条件未找到该标头。

onsuccess和always之间的这种差异是一种 feature，其结果是 httpd 内部 stores headers 对 HTTP 响应的结果，因为它不提供任何“规范化”的单个_header 列表。如果在编写 configuration 时不记住以下概念，可能会出现的主要问题是某些 HTTP 响应可能最终会重复相同的标头(使用户感到困惑，有时甚至是 HTTP 客户端)。例如，假设您使用mod_proxy_fcgi进行简单的 PHP 代理设置，并且后端 PHP 脚本将X-Foo: bar标头添加到每个 HTTP 响应中。如上所述，mod_proxy_fcgi使用always table 来 store headers，因此像下面这样的 configuration 会导致错误的结果，即标题与两个值都重复：

# X-Foo's value is set in the 'onsuccess' headers table
Header set X-Foo: baz

为了避免这种限制，有一些已知的 configuration 模式可以提供帮助，如下所示：

# 'onsuccess' can be omitted since it is the default
Header onsuccess unset X-Foo
Header always set X-Foo "baz"

与上述条件参数分开，您可以根据 e.g 的 HTTP 状态代码限制操作。代理或 CGI 请求。请参阅使用％{的 example。 97}在上面的部分。

它执行的操作由第一个参数确定(如果指定了条件，则为第二个参数)。这可以是以下值之一：

在开始阅读动作列表之前，请阅读上述always和onsuccess headers 列表之间的区别，因为这个重要概念仍然适用。事实上，每个操作都按照描述的方式工作，但仅限于目标 headers 列表。

• add
  即使此标头已存在，响应标头也会添加到现有的_header 集合中。这可能导致两个(或更多)_header 具有相同的 name。这可能会导致无法预料的后果，并且通常应该使用附加或合并。
• append
  响应标头将附加到同一 name 的任何现有标头。当新的 value 合并到现有标头时，它将使用逗号与现有标头分隔。这是为标题赋予多个值的 HTTP 标准方法。
• echo
  具有此 name 的请求 headers 将在响应 headers 中回显。标头可以是正则表达式。必须省略 value。
• edit
• edit*
  如果此响应头存在，则根据正则表达式 search-and-replace 转换其 value。 value 参数是一个正则表达式，替换是替换 string，它可能包含反向引用或格式说明符。编辑表单将在标题 value 中匹配和替换一次，而 edit *表单将替换搜索 pattern 的每个实例(如果它出现多次)。
• merge
  响应标头将附加到同一 name 的任何现有标头，除非要附加的 value 已出现在标头的 comma-delimited 值列表中。当新的 value 合并到现有标头时，它将使用逗号与现有标头分隔。这是为标题赋予多个值的 HTTP 标准方法。以区分大小写的方式比较值，并且在处理完所有格式说明符之后。 double 引号中的值被视为与其他相同的未引用值不同。
• set
  设置响应标头，用此 name 替换任何先前的标头。 value 可以是 string 格式。
• setifempty
  设置了请求标头，但前提是此 name 没有前一个标头。 Content-Type 标头是一个特殊用例，因为可能有可能确定其 value 但是在评估 setifempty 时标头不是响应的一部分。对于此用例使用 set 更安全，如下例所示：标题集 Content-Type“text/plain”“expr=-z％{。108}”
• unset
  如果存在，则删除此 name 的响应头。如果有多个相同 name 的_header，则将删除所有_header。必须省略 value。
• note
  命名响应头的 value 被复制到一个内部注释中，其 name 由 value 给出。如果由 CGI 或代理资源发送的标头配置为未设置但也应记录，则此选项很有用。可在 2.4.7 及更高版本中使用。

该参数后跟一个头 name，它可以包含最后的冒号，但不是必需的。对于set，append，merge，add，unset和edit，将忽略大小写。echo的标头 name 区分大小写，可能是正则表达式。

对于set，append，merge和add，value 被指定为下一个参数。如果 value 包含空格，则应该用 double 引号括起来。 value 可以是字符 string，包含mod_headers特定格式说明符的 string(和字符 literals)，或者以 expr =为前缀的ap_expr表达式

value 支持以下格式说明符：

注意

%s格式说明符仅在 Apache 2.1 及更高版本中可用；它可以代替%e来避免启用SSLOptions +StdEnvVars的开销。如果由于其他原因必须启用SSLOptions +StdEnvVars，%e将比%s更有效。

关于表达式值的注释

当 value 参数使用ap_expr解析器时，某些表达式语法将与评估 boolean 表达式(如<If>)的示例不同：

• 语法的起点是'string'而不是'expr'。
• Function calls 使用％{。语法而不是 funcname(arg)。
• 目前无法从此起点访问 Multi-argument 函数
• 引用整个参数，例如

Header set foo-checksum "expr=%{md5:foo}"

对于edit，有一个 value 参数，它是一个正则表达式，另一个是替换 string。从 version 2.4.7 开始，替换 string 也可能包含格式说明符。

Header指令后面可能跟一个额外的参数，可以是以下任何一个：

• early
  指定早期处理。
• env=[!]varname
  当且仅当存在环境变量 varname 时才应用该指令。一个！在 varname 前面反转测试，因此只有在未设置 varname 时该指令才适用。
• expr=expression
  当且仅当表达式求值为 true 时才应用该指令。表达式语法和 evaluation 的详细信息记录在 ap_expr 文档中。#这延迟了条件子句的 evaluation 与<If>的比较
  标题始终设置 CustomHeader my-value“expr =％{。174}=~m#^/special_path.php $#”

除早模式外，Header指令在响应发送到网络之前处理。这意味着可以设置 and/or 覆盖大多数 headers，除了 HTTP 头过滤器添加的一些 headers 之外。在 2.2.12 之前，无法使用此指令更改 Content-Type 标头。

RequestHeader 指令

该指令可以替换，合并，更改或删除 HTTP 请求 headers。在内容处理程序为 run 之前修改标头，允许修改传入的 headers。它执行的操作由第一个参数决定。这可以是以下值之一：

• add
  请求标头将添加到现有的 headers 集合中，即使此标头已存在。这可能导致两个(或更多)_header 具有相同的 name。这可能会导致无法预料的后果，并且通常应该使用附加或合并。
• append
  请求标头将附加到同一 name 的任何现有标头。当新的 value 合并到现有标头时，它将使用逗号与现有标头分隔。这是为标题赋予多个值的 HTTP 标准方法。
• edit
• edit*
  如果此请求标头存在，则根据正则表达式 search-and-replace 转换其 value。 value 参数是一个正则表达式，替换是替换 string，它可能包含反向引用或格式说明符。编辑表单将在标题 value 中匹配和替换一次，而 edit *表单将替换搜索 pattern 的每个实例(如果它出现多次)。
• merge请求标头将附加到同一 name 的任何现有标头，除非要附加的 value 已出现在现有标头的 comma-delimited 值列表中。当新的 value 合并到现有标头时，它将使用逗号与现有标头分隔。这是为标题赋予多个值的 HTTP 标准方法。以区分大小写的方式比较值，并且在处理完所有格式说明符之后。 double 引号中的值被视为与其他相同的未引用值不同。
• set
  设置了请求标头，用此 name 替换任何先前的标头
• setifempty
  设置了请求标头，但前提是此 name 没有前一个标头。可在 2.4.7 及更高版本中使用。
• unset
  如果存在，则删除此 name 的请求标头。如果有多个相同 name 的_header，则将删除所有_header。必须省略 value。

该参数后跟一个头 name，它可以包含最后的冒号，但不是必需的。案例被忽略。对于set，append，merge和add，value 作为第三个参数给出。如果 value 包含空格，则应该用 double 引号括起来。对于unset，不应给出 value。 value 可以是字符 string，包含格式说明符的 string 或两者的组合。支持的格式说明符与头相同，请查看详细信息。对于edit，需要 value 和替换，并且分别是正则表达式和替换 string。

RequestHeader指令后面可能跟一个额外的参数，可以是以下任何一个：

• early
  指定早期处理。
• env=[!]varname
  当且仅当存在环境变量 varname 时才应用该指令。一个！在 varname 前面反转测试，因此只有在未设置 varname 时该指令才适用。
• expr=expression
  当且仅当表达式求值为 true 时才应用该指令。表达式语法和 evaluation 的详细信息记录在 ap_expr 文档中。

除了早模式之外，RequestHeader指令在修复阶段由处理程序运行请求之前处理。这应该允许覆盖或修改由浏览器生成的 headers 或 Apache 输入过滤器。