您正在查看: Apache 分类下的文章

Request Processing in Apache 2.0 - Apache 2.2 中文版参考手册

apache > HTTP Server > 文档 > 版本2.2 > 开发者文档
   致谢 | 译者声明 | 本篇译者:<虚位以待> | 本篇译稿完成时间:?年?月?日 | 获取最新版本
Request Processing in apache 2.0
Warning

Warning - this is a first (fast) draft that needs further revision!

Several changes in Apache 2.0 affect the internal request processing mechanics. Module authors need to be aware of these changes so they may take advantage of the optimizations and security enhancements.

The first major change is to the subrequest and redirect mechanisms. There were a number of different code paths in Apache 1.3 to attempt to optimize subrequest or redirect behavior. As patches were introduced to 2.0, these optimizations (and the server behavior) were quickly broken due to this duplication of code. All duplicate code has been folded back into ap_process_request_internal() to prevent the code from falling out of sync again.

This means that much of the existing code was 'unoptimized'. It is the Apache HTTP Project's first goal to create a robust and correct implementation of the HTTP server RFC. Additional goals include security, scalability and optimization. New methods were sought to optimize the server (beyond the performance of Apache 1.3) without introducing fragile or insecure code.

The Request Processing Cycle

All requests pass through ap_process_request_internal() in request.c, including subrequests and redirects. If a module doesn't pass generated requests through this code, the author is cautioned that the module may be broken by future changes to request processing.

To streamline requests, the module author can take advantage of the hooks offered to drop out of the request cycle early, or to bypass core Apache hooks which are irrelevant (and costly in terms of CPU.)

The Request Parsing Phase Unescapes the URL

The request's parsed_uri path is unescaped, once and only once, at the beginning of internal request processing.

This step is bypassed if the proxyreq flag is set, or the parsed_uri.path element is unset. The module has no further control of this one-time unescape operation, either failing to unescape or multiply unescaping the URL leads to security reprecussions.

Strips Parent and This Elements from the
URI

All /../和/./ elements are removed by ap_getparents(). This helps to ensure the path is (nearly) absolute before the request processing continues.

This step cannot be bypassed.

Initial URI Location Walk

Every request is subject to an ap_location_walk() call. This ensures that <Location> sections are consistently enforced for all requests. If the request is an internal redirect or a sub-request, it may borrow some or all of the processing from the previous or parent request's ap_location_walk, so this step is generally very efficient after processing the main request.

translate_name

Modules can determine the file name, or alter the given URI in this step. For example, mod_vhost_alias will translate the URI's path into the configured virtual host, mod_alias will translate the path to an alias path, and if the request falls back on the core, the DocumentRoot is prepended to the request resource.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't translate name" error is logged automatically.

Hook: map_to_storage

After the file or correct URI was determined, the appropriate per-dir configurations are merged together. For example, mod_proxy compares and merges the appropriate <Proxy> sections. If the URI is nothing more than a local (non-proxy) TRACE request, the core handles the request and returns DONE. If no module answers this hook with OK或DONE, the core will run the request filename against the <Directory>和<Files> sections. If the request 'filename' isn't an absolute, legal filename, a note is set for later termination.

URI Location Walk

Every request is hardened by a second ap_location_walk() call. This reassures that a translated request is still subjected to the configured <Location> sections. The request again borrows some or all of the processing from its previous location_walk above, so this step is almost always very efficient unless the translated URI mapped to a substantially different path or Virtual Host.

Hook: header_parser

The main request then parses the client's headers. This prepares the remaining request processing steps to better serve the client's request.

The Security Phase

Needs Documentation. Code is:

switch (ap_satisfies(r)) {
case SATISFY_ALL:
case SATISFY_NOSPEC:
if ((access_status = ap_run_access_checker(r)) != 0) {
return decl_die(access_status, "check access", r);
}

if (ap_some_auth_required(r)) {
if (((access_status = ap_run_check_user_id(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check user. No user file?"
: "perform authentication. AuthType not set!",
r);
}

if (((access_status = ap_run_auth_checker(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check access. No groups file?"
: "perform authentication. AuthType not set!",
r);
}
}
break;

case SATISFY_ANY:
if (((access_status = ap_run_access_checker(r)) != 0)) {
if (!ap_some_auth_required(r)) {
return decl_die(access_status, "check access", r);
}

if (((access_status = ap_run_check_user_id(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check user. No user file?"
: "perform authentication. AuthType not set!",
r);
}

if (((access_status = ap_run_auth_checker(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check access. No groups file?"
: "perform authentication. AuthType not set!",
r);
}
}
break;
}

The Preparation Phase Hook: type_checker

The modules have an opportunity to test the URI or filename against the target resource, and set mime information for the request. Both mod_mime和mod_mime_magic use this phase to compare the file name or contents against the administrator's configuration and set the content type, language, character set and request handler. Some modules may set up their filters or other request handling parameters at this time.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't find types" error is logged automatically.

Hook: fixups

Many modules are 'trounced' by some phase above. The fixups phase is used by modules to 'reassert' their ownership or force the request's fields to their appropriate values. It isn't always the cleanest mechanism, but occasionally it's the only option.

The Handler Phase

This phase is not part of the processing in ap_process_request_internal(). Many modules prepare one or more subrequests prior to creating any content at all. After the core, or a module calls ap_process_request_internal() it then calls ap_invoke_handler() to generate the request.

Hook: insert_filter

Modules that transform the content in some way can insert their values and override existing filters, such that if the user configured a more advanced filter out-of-order, then the module can move its order as need be. There is no result code, so actions in this hook better be trusted to always succeed.

Hook: handler

The module finally has a chance to serve the request in its handler hook. Note that not every prepared request is sent to the handler hook. Many modules, such as mod_autoindex, will create subrequests for a given URI, and then never serve the subrequest, but simply lists it for the user. Remember not to put required teardown from the hooks above into this module, but register pool cleanups against the request pool to free resources as required.

How filters work in Apache 2.0 - Apache 2.2 中文版参考手册

apache > HTTP Server > 文档 > 版本2.2 > 开发者文档
   致谢 | 译者声明 | 本篇译者:<虚位以待> | 本篇译稿完成时间:?年?月?日 | 获取最新版本
How filters work in apache 2.0
Warning

This is a cut 'n paste job from an email (<022501c1c529$f63a9550$7f00000a@KOJ>) and only reformatted for better readability. It's not up to date but may be a good start for further research.

Filter Types

There are three basic filter types (each of these is actually broken down into two categories, but that comes later).

CONNECTION
Filters of this type are valid for the lifetime of this connection.
(AP_FTYPE_CONNECTION, AP_FTYPE_NETWORK)

PROTOCOL
Filters of this type are valid for the lifetime of this request from
the point of view of the client, this means that the request is valid
from the time that the request is sent until the time that the response
is received. (AP_FTYPE_PROTOCOL,
AP_FTYPE_TRANSCODE)

RESOURCE
Filters of this type are valid for the time that this content is used
to satisfy a request. For simple requests, this is identical to
PROTOCOL, but internal redirects and sub-requests can change
the content without ending the request. (AP_FTYPE_RESOURCE,
AP_FTYPE_CONTENT_SET)

It is important to make the distinction between a protocol and a resource filter. A resource filter is tied to a specific resource, it may also be tied to header information, but the main binding is to a resource. If you are writing a filter and you want to know if it is resource or protocol, the correct question to ask is: "Can this filter be removed if the request is redirected to a different resource?" If the answer is yes, then it is a resource filter. If it is no, then it is most likely a protocol or connection filter. I won't go into connection filters, because they seem to be well understood. With this definition, a few examples might help:

Byterange
We have coded it to be inserted for all requests, and it is removed
if not used. Because this filter is active at the beginning of all
requests, it can not be removed if it is redirected, so this is a
protocol filter.

http_header
This filter actually writes the headers to the network. This is
obviously a required filter (except in the asis case which is special
and will be dealt with below) and so it is a protocol filter.

Deflate
The administrator configures this filter based on which file has been
requested. If we do an internal redirect from an autoindex page to an
index.html page, the deflate filter may be added or removed based on
config, so this is a resource filter.

The further breakdown of each category into two more filter types is strictly for ordering. We could remove it, and only allow for one filter type, but the order would tend to be wrong, and we would need to hack things to make it work. Currently, the RESOURCE filters only have one filter type, but that should change.

How are filters inserted?

This is actually rather simple in theory, but the code is complex. First of all, it is important that everybody realize that there are three filter lists for each request, but they are all concatenated together. So, the first list is r->output_filters, then r->proto_output_filters, and finally r->connection->output_filters. These correspond to the RESOURCE, PROTOCOL, and CONNECTION filters respectively. The problem previously, was that we used a singly linked list to create the filter stack, and we started from the "correct" location. This means that if I had a RESOURCE filter on the stack, and I added a CONNECTION filter, the CONNECTION filter would be ignored. This should make sense, because we would insert the connection filter at the top of the c->output_filters list, but the end of r->output_filters pointed to the filter that used to be at the front of c->output_filters. This is obviously wrong. The new insertion code uses a doubly linked list. This has the advantage that we never lose a filter that has been inserted. Unfortunately, it comes with a separate set of headaches.

The problem is that we have two different cases were we use subrequests. The first is to insert more data into a response. The second is to replace the existing response with an internal redirect. These are two different cases and need to be treated as such.

In the first case, we are creating the subrequest from within a handler or filter. This means that the next filter should be passed to make_sub_request function, and the last resource filter in the sub-request will point to the next filter in the main request. This makes sense, because the sub-request's data needs to flow through the same set of filters as the main request. A graphical representation might help:

Default_handler --> includes_filter --> byterange --> ...

If the includes filter creates a sub request, then we don't want the data from that sub-request to go through the includes filter, because it might not be SSI data. So, the subrequest adds the following:

Default_handler --> includes_filter -/-> byterange --> ...
/
Default_handler --> sub_request_core

What happens if the subrequest is SSI data? Well, that's easy, the includes_filter is a resource filter, so it will be added to the sub request in between the Default_handler and the sub_request_core filter.

The second case for sub-requests is when one sub-request is going to become the real request. This happens whenever a sub-request is created outside of a handler or filter, and NULL is passed as the next filter to the make_sub_request function.

In this case, the resource filters no longer make sense for the new request, because the resource has changed. So, instead of starting from scratch, we simply point the front of the resource filters for the sub-request to the front of the protocol filters for the old request. This means that we won't lose any of the protocol filters, neither will we try to send this data through a filter that shouldn't see it.

The problem is that we are using a doubly-linked list for our filter stacks now. But, you should notice that it is possible for two lists to intersect in this model. So, you do you handle the previous pointer? This is a very difficult question to answer, because there is no "right" answer, either method is equally valid. I looked at why we use the previous pointer. The only reason for it is to allow for easier addition of new servers. With that being said, the solution I chose was to make the previous pointer always stay on the original request.

This causes some more complex logic, but it works for all cases. My concern in having it move to the sub-request, is that for the more common case (where a sub-request is used to add data to a response), the main filter chain would be wrong. That didn't seem like a good idea to me.

Asis

The final topic. :-) Mod_Asis is a bit of a hack, but the handler needs to remove all filters except for connection filters, and send the data. If you are using mod_asis, all other bets are off.

Explanations

The absolutely last point is that the reason this code was so hard to get right, was because we had hacked so much to force it to work. I wrote most of the hacks originally, so I am very much to blame. However, now that the code is right, I have started to remove some hacks. Most people should have seen that the reset_filters和add_required_filters functions are gone. Those inserted protocol level filters for error conditions, in fact, both functions did the same thing, one after the other, it was really strange. Because we don't lose protocol filters for error cases any more, those hacks went away. The HTTP_HEADER, Content-length, and Byterange filters are all added in the insert_filters phase, because if they were added earlier, we had some interesting interactions. Now, those could all be moved to be inserted with the HTTP_IN, CORE, and CORE_IN filters. That would make the code easier to follow.

词汇表 - Apache 2.2 中文版参考手册

apache > HTTP Server > 文档 > 版本2.2
   致谢 | 译者声明 | 本篇译者:金步国 | 本页最后更新:2006年1月3日 | 获取最新版本
词汇表

此词汇表包含了与apache相关的一些常用术语的详细定义,以及对网络服务的一般说明,并提供了相关的更详细资料的连接。

定义

访问控制(Access Control)
对网络领域访问的限制。对Apache来说,通常是指对某些URL访问的限制。参见:认证、授权、访问控制

算法(Algorithm)

通过有限步骤解决问题的一个明确的公式或者一套规则。用于加密的算法通常称为加密算法(Cipher)。

Apache扩展工具(APache eXtension Tool) (apxs)
一个perl脚本,用于编译模块(module)源代码为动态共享对象(DSO),并帮助安装到Apache web服务器中。

参见:apxs

Apache可移植运行时(Apache Portable Runtime) (APR)
一组在操作系统和服务器之间提供许多基本接口的库。APR是一个与Apache HTTP Server平行的独立项目。

参见:Apache Portable Runtime Project

认证(Authentication)
对诸如服务器、客户端或用户等网络实体的真实性鉴定。

参见:认证、授权、访问控制

证书(Certificate)
用于鉴别诸如服务器或客户端的网络实体的一个数据记录。一个证书包含有:若干其所有者的X.509信息片段(称为主题[subject]),其签发的证书机构(Certification Authority)(称为发行者[issuer]),还有其所有者的公钥(public key)和由证书机构(CA)制作的签名。网络实体将用CA证书校验这些签名。

参见:SSL/TLS 加密

证书签发请求(Certificate Signing Request) (CSR)
一个提交给证书机构(Certification Authority)的用其CA证书的私钥(Private Key)签名的未经签发的证书(certificate)。一旦这个CSR被签发,则成为一个真正的证书。

参见:SSL/TLS 加密

证书机构(Certification Authority) (CA)
一个旨在对已经通过保密方法得到鉴定的网络实体签发证书的可信的第三方团体。其他网络实体可以通过验证签名来确定一个证书的持有人是否通过了CA的鉴定。

参见:SSL/TLS 加密

加密算法(Cipher)
一种用于数据加密的算法或系统。如:DES、IDEA、RC4等等。

参见:SSL/TLS 加密

密文(Ciphertext)
明文(Plaintext)通过加密算法(Cipher)处理后的结果。

参见:SSL/TLS 加密

公共网关接口(Common Gateway Interface) (CGI)
一种允许在web服务器和外部程序之间使用外部程序响应请求的接口的标准定义。此接口最早由(美国)国家计算机安全协会(NCSA)制定,另外还有一个RFC项目。

参见:CGI动态页面

配置指令(Configuration Directive)
参见:指令(Directive)

配置文件(Configuration File)
一个控制Apache配置的含有若干指令(Directives)的文本文件。

参见:配置文件

连接(CONNECT)
一种通过HTTP通道代理原始数据的HTTP方法(method)。可以用于封装其他协议,如SSL协议。

作用域(Context)
指令(Directives)在配置文件中的许可区域。

参见:描述指令的术语

数字签名(Digital Signature)
验证证书或其他文件的一个经过加密的文本块。证书机构(Certification Authority)对公钥(Public Key)生成一个散列并嵌入证书(Certificate),以建立签名,然后用其自身的私钥(Private Key)加密这个散列。只有证书机构(CA)的公钥才能解密此签名,以证实持有此证书的网络实体已经通过了CA的鉴定。

参见:SSL/TLS 加密

指令(Directive)
位于配置文件(Configuration File)中的控制一个或多个Apache行为的配置命令。

参见:指令索引

动态共享对象(Dynamic Shared Object) (DSO)
与Apache httpd二进制映象分开编译的可以在被调用时加载的模块(Modules)。

参见:动态共享对象支持

环境变量(Environment Variable) (env-variable)
由操作系统shell管理的用于存储信息和程序之间通讯的已命名的变量。Apache存储的内部变量有时也称作环境变量,但它们是被存储在Apache内部结构中的,而不是存储在shell环境中的。

参见:Apache的环境变量

出口限制(Export-Crippled)
降低加密强度(和安全度)以符合美国出口监管条例(EAR)的规定。出口限制加密的软件被限制只能使用密钥长度较短的密钥,从而使密文可以被暴力破解。

参见:SSL/TLS 加密

过滤器(Filter)
服务器用来接收和发送数据的过程。输入过滤器处理客户端发送到服务器的数据,而输出过滤器处理服务器发送到客户端的文档。比如,INCLUDES输出过滤器处理服务器端包含(Server Side Includes)文档。

参见:过滤器

全称域名(Fully-Qualified Domain-Name) (FQDN)
网络实体的唯一的名称,由主机名和域名组成,并能够被解析为一个IP地址。比如,www是一个主机名,example.com是一个域名,那么www.example.com就是一个全称域名。

处理器(Handler)
处理器是一个文件被调用时,Apache所执行操作的内部表现。一般来说,文件都有基于其文件类型的隐含处理器。通常,文件都只是被服务器作简单的提交,只有某些文件类型被特殊地"处理"。比如:cgi-script处理器使文件作为CGI脚本被处理。

参见:Apache处理器的使用

散列/哈希(Hash)
一个从变长字符串生成定长字符串的单向算法。不同的输入字符串一般会产生不同的输出散列值(取决于hash函数)。

头(Header)
在实际内容之前发送的HTTP请求和响应的一部分,其中包含描述内容的元信息(meta-information)。

.htaccess
网站目录树结构中的一个配置文件(configuration file),使配置指令(Directive)作用于其所在目录及其所有子目录。此文件可以包含几乎所有类型的指令,而并不仅仅是其文件名所暗示的访问控制指令。

参见:配置文件

httpd.conf
Apache的主配置文件(configuration file),默认值是/usr/local/apache2/conf/httpd.conf ,但可以通过运行时或编译时的配置改变。

参见:配置文件

超文本传输协议(HyperText Transfer Protocol) (HTTP)
在WWW上使用的标准传输协议。Apache实现了此协议的1.1版本,即在RFC 2616中定义的HTTP/1.1 。

HTTPS
安全(Secure)超文本传输协议,在WWW上使用的标准加密通讯机制。实质上,它是SSL基础上的HTTP。

参见:SSL/TLS 加密

方法(Method)
对于HTTP,是由客户端在请求行中指定的对一个资源执行的操作。HTTP中的方法有诸如GET、POST、PUT等等。

消息摘要(Message Digest)
消息的一个散列值,可以用于校验消息内容是否在传输过程中有所改变。

参见:SSL/TLS 加密

MIME类型(MIME-type)
描述被传输文档的类型的一种方法。因其格式借用了多用途网际邮件扩展(MIME)而得名。由以斜杠分隔的一个主类型和一个副类型组成。例如:text/html, image/gif, application/octet-stream 。在HTTP中,MIME类型包含在Content-Type头(header)中被传输。

参见:mod_mime

模块(Module)
程序的一个独立的部分。Apache中的多数功能都包含在模块中以供取舍。被编译进入Apache httpd二进制映象的模块称为静态模块(static module),而单独存储的可以有选择地在运行时被加载的模块称为动态模块(dynamic module)或DSO。默认被包含的模块称为基本模块(base module)。很多Apache可以使用的模块都不是作为Apache HTTP服务器tar包(tarball)的一部分发行的,这些模块被称为第三方模块(third-party module)。

参见:模块索引

模块幻数(Module Magic Number) (MMN)
模块幻数是Apache源代码中定义的与模块二进制映象兼容性相关的常量。当Apache内部结构、函数调用和API的重要部分发生改变,再也不能保证此二进制映象的兼容性的时候,这个值会被改变。一旦MMN被改变,所有的第三方模块必须至少被重新编译,有时候甚至要修改源代码才能在Apache的新版本中运行。

OpenSSL
开源的SSL/TLS工具包

参见:http://www.openssl.org/

通行码(Pass Phrase)
保护私钥文件的一个词或短语,以避免被未授权用户加密。通常,它只是密码算法(Cipher)中保密的用于加密/解密的密钥。

参见:SSL/TLS 加密

明文(Plaintext)
未加密的文本。

私钥(Private Key)
公钥加密系统中保密的密钥,用于对到来的消息解密和对外出的消息签名。

参见:SSL/TLS 加密

代理(Proxy)
处于客户端和原始服务器(origin server)之间的中间服务器。它接收来自客户端的请求,传输到原始服务器,并把原始服务器的响应返回给客户端。如果几个客户端请求的内容相同,代理可以从其缓存中取出此内容,而不必每次都从原始服务器读取,从而缩短了响应时间。

参见:mod_proxy

公钥(Public Key)
公钥加密系统中对公众公开的密钥,用于加密送往其持有者的消息和解密由其持有者制作的签名。

参见:SSL/TLS 加密

公钥加密系统(Public Key Cryptography)
对使用一个加密密钥和一个解密密钥的不对称加密系统的研究和应用。相应的一对这样的密钥组成了密钥对。也称为"非对称加密系统"(Asymmetric Cryptography)

参见:SSL/TLS 加密

正则表达式(Regular Expression) (Regex)
一种对模式的文字表述,比如,"所有以字母A开头的单词","每个10位的电话号码" 还可以是"每个包含两个逗号,而且没有大写字母Q的句子"。正则表达式在Apache中非常有用,可以非常灵活地对一组文件或资源应用某种属性,例如,任何"images"目录下的.gif 和.jpg 文件可以表述为"/images/.*(jpg|gif)$"。Apache使用的是由PCRE库提供的perl兼容的正则表达式。

反向代理(Reverse Proxy)
一个在客户端看来是原始服务器(origin server)的代理(proxy)服务器。出于安全考虑或为了实现均衡负载,借此对客户端隐藏原始服务器。

安全套接字层(Secure Sockets Layer) (SSL)
由Netscape公司建立的,在TCP/IP网络中实现常规通讯认证和加密的协议。它被广泛地用于HTTPS ,即SSL基础上的超文本传输协议。

参见:SSL/TLS 加密

服务器端包含(Server Side Includes) (SSI)
html文件中嵌入处理指令的一种技术。

参见:服务器端包含简介

会话(Session)
一般是指一个通讯的上下文信息。

SSLeay
由Eric A. Young开发的最初的SSL/TLS的实现库

对称密码系统(Symmetric Cryptography)
使用单个密钥执行加密和解密操作的密码算法研究和应用。

参见:SSL/TLS 加密

Tar包(Tarball)
用tar工具收集的文件包。Apache发行版是存储在用tar或pkzip压缩的文件中的。

传输层安全(Transport Layer Security) (TLS)
Internet工程任务组(IETF)建立的SSL的后续协议,在TCP/IP网络中实现常规通讯认证和加密。TLS的版本1和SSL的版本3基本一致。

参见:SSL/TLS 加密

统一资源定位器(Uniform Resource Locator) (URL)
资源在Internet中的名称/地址。它是正式名称为统一资源标识符(Uniform Resource Identifier)的非正式称呼。URL通常由一个类型,比如http或https ,一个主机名和一个路径组成。指向本页面的URL是http://httpd.apache.org/docs/2.2/glossary.html

统一资源标识符(Uniform Resource Identifier) (URI)
识别一个抽象或者物理资源的简洁字符串。由RFC 2396正式定义。互联网上使用的URI通常也被称为URL

虚拟主机(Virtual Hosting)
使用单个Apache实例提供多个网站。基于IP的虚拟主机(IP virtual hosting)基于IP区分各网站,而基于名称的虚拟主机(name-based virtual hosting)按主机名区分,从而在同一个IP地址上宿主多个网站。

参见:Apache虚拟主机文档

X.509
由国际电信联盟(ITU)推荐的用于SSL/TLS认证的一种认证证书类型。

参见:SSL/TLS 加密

APR中内存分配的调试 - Apache 2.2 中文版参考手册

apache > HTTP Server > 文档 > 版本2.2 > 开发者文档
   致谢 | 译者声明 | 本篇译者:<虚位以待> | 本篇译稿完成时间:?年?月?日 | 获取最新版本
Debugging Memory Allocation in APR

The allocation mechanisms within APR have a number of debugging modes that can be used to assist in finding memory problems. This document describes the modes available and gives instructions on activating them.

Available debugging options Allocation Debugging - ALLOC_DEBUG
Debugging support: Define this to enable code which helps detect re-use of free()d memory and other such nonsense.

The theory is simple. The FILL_BYTE (0xa5) is written over all malloc'd memory as we receive it, and is written over everything that we free up during a clear_pool. We check that blocks on the free list always have the FILL_BYTE in them, and we check during palloc() that the bytes still have FILL_BYTE in them. If you ever see garbage URLs or whatnot containing lots of 0xa5s then you know something used data that's been freed or uninitialized.

Malloc Support - ALLOC_USE_MALLOC

If defined all allocations will be done with malloc() and free()d appropriately at the end.

This is intended to be used with something like Electric Fence or Purify to help detect memory problems. Note that if you're using efence then you should also add in ALLOC_DEBUG. But don't add in ALLOC_DEBUG if you're using Purify because ALLOC_DEBUG would hide all the uninitialized read errors that Purify can diagnose.

Pool Debugging - POOL_DEBUG

This is intended to detect cases where the wrong pool is used when assigning data to an object in another pool.

In particular, it causes the table_{set,add,merge}n routines to check that their arguments are safe for the apr_table_t they're being placed in. It currently only works with the unix multiprocess model, but could be extended to others.

Table Debugging - MAKE_TABLE_PROFILE

Provide diagnostic information about make_table() calls which are possibly too small.

This requires a recent gcc which supports __builtin_return_address(). The error_log output will be a message such as:

table_push: apr_table_t created by 0x804d874 hit limit of 10

Use l *0x804d874 to find the source that corresponds to. It indicates that a apr_table_t allocated by a call at that address has possibly too small an initial apr_table_t size guess.

Allocation Statistics - ALLOC_STATS

Provide some statistics on the cost of allocations.

This requires a bit of an understanding of how alloc.c works.

Allowable Combinations

Not all the options outlined above can be activated at the same time. the following table gives more information.

ALLOC DEBUGALLOC USE MALLOCPOOL DEBUGMAKE TABLE PROFILEALLOC STATSALLOC DEBUGALLOC USE MALLOCPOOL DEBUGMAKE TABLE PROFILEALLOC STATS
-NoYesYesYes
No-NoNoNo
YesNo-YesYes
YesNoYes-Yes
YesNoYesYes-

Additionally the debugging options are not suitable for multi-threaded versions of the server. When trying to debug with these options the server should be started in single process mode.

Activating Debugging Options

The various options for debugging memory are now enabled in the apr_general.h header file in APR. The various options are enabled by uncommenting the define for the option you wish to use. The section of the code currently looks like this (contained in srclib/apr/include/apr_pools.h)

/*
#define ALLOC_DEBUG
#define POOL_DEBUG
#define ALLOC_USE_MALLOC
#define MAKE_TABLE_PROFILE
#define ALLOC_STATS
*/

typedef struct ap_pool_t {

union block_hdr *first;

union block_hdr *last;

struct cleanup *cleanups;

struct process_chain *subprocesses;

struct ap_pool_t *sub_pools;

struct ap_pool_t *sub_next;

struct ap_pool_t *sub_prev;

struct ap_pool_t *parent;

char *free_first_avail;

#ifdef ALLOC_USE_MALLOC

void *allocation_list;

#endif

#ifdef POOL_DEBUG

struct ap_pool_t *joined;

#endif

int (*apr_abort)(int retcode);

struct datastruct *prog_data;

} ap_pool_t;

To enable allocation debugging simply move the #define ALLOC_DEBUG above the start of the comments block and rebuild the server.

Note

In order to use the various options the server must be rebuilt after editing the header file.

Documenting Apache 2.0 - Apache 2.2 中文版参考手册

apache > HTTP Server > 文档 > 版本2.2 > 开发者文档
   致谢 | 译者声明 | 本篇译者:<虚位以待> | 本篇译稿完成时间:?年?月?日 | 获取最新版本
Documenting apache 2.0

Apache 2.0 uses Doxygen to document the APIs and global variables in the the code. This will explain the basics of how to document using Doxygen.

Brief Description

To start a documentation block, use /**
To end a documentation block, use */

In the middle of the block, there are multiple tags we can use:

Description of this functions purpose
@param parameter_name description
@return description
@deffunc signature of the function

deffunc is not always necessary. DoxyGen does not have a full parser in it, so any prototype that use a macro in the return type declaration is too complex for scandoc. Those functions require a deffunc. An example (using &gt; rather than >):

/**
 * return the final element of the pathname
 * @param pathname The path to get the final element of
 * @return the final element of the path
 * @tip Examples:
 * <pre>
 *"/foo/bar/gum"-&gt; "gum"
 *"/foo/bar/gum/" -&gt; ""
 *"gum"-&gt; "gum"
 *"wi\\n32\\stuff" -&gt; "stuff"
 * </pre>
 * @deffunc const char * ap_filename_of_pathname(const char *pathname)
 */

At the top of the header file, always include:

/**
 * @package Name of library header
 */

Doxygen uses a new html file for each package. The html files are named {Name_of_library_header}.html, so try to be concise with your names.

For a further discussion of the possibilities please refer to the Doxygen site.