[i18n-zh] r1434 committed - Import manual and build files

4 views

Skip to first unread message

i18...@googlecode.com

unread,

Feb 27, 2011, 2:26:38 AM2/27/11

to l10...@googlegroups.com

Revision: 1434
Author: dongsheng.song
Date: Sat Feb 26 23:20:49 2011
Log: Import manual and build files
http://code.google.com/p/i18n-zh/source/detail?r=1434

Added:
/trunk/l10n/apache/trunk/LICENSE
/trunk/l10n/apache/trunk/bind.xml
/trunk/l10n/apache/trunk/bind.xml.meta
/trunk/l10n/apache/trunk/caching.xml
/trunk/l10n/apache/trunk/caching.xml.meta
/trunk/l10n/apache/trunk/configuring.xml
/trunk/l10n/apache/trunk/configuring.xml.meta
/trunk/l10n/apache/trunk/content-negotiation.xml
/trunk/l10n/apache/trunk/content-negotiation.xml.meta
/trunk/l10n/apache/trunk/convenience.map
/trunk/l10n/apache/trunk/custom-error.xml
/trunk/l10n/apache/trunk/custom-error.xml.meta
/trunk/l10n/apache/trunk/developer
/trunk/l10n/apache/trunk/developer/API.xml
/trunk/l10n/apache/trunk/developer/API.xml.meta
/trunk/l10n/apache/trunk/developer/debugging.xml
/trunk/l10n/apache/trunk/developer/debugging.xml.meta
/trunk/l10n/apache/trunk/developer/documenting.xml
/trunk/l10n/apache/trunk/developer/documenting.xml.meta
/trunk/l10n/apache/trunk/developer/documenting.xml.zh-cn
/trunk/l10n/apache/trunk/developer/filters.xml
/trunk/l10n/apache/trunk/developer/filters.xml.meta
/trunk/l10n/apache/trunk/developer/hooks.xml
/trunk/l10n/apache/trunk/developer/hooks.xml.meta
/trunk/l10n/apache/trunk/developer/index.xml
/trunk/l10n/apache/trunk/developer/index.xml.meta
/trunk/l10n/apache/trunk/developer/index.xml.zh-cn
/trunk/l10n/apache/trunk/developer/modules.xml
/trunk/l10n/apache/trunk/developer/modules.xml.meta
/trunk/l10n/apache/trunk/developer/new_api_2_4.xml
/trunk/l10n/apache/trunk/developer/new_api_2_4.xml.meta
/trunk/l10n/apache/trunk/developer/output-filters.xml
/trunk/l10n/apache/trunk/developer/output-filters.xml.meta
/trunk/l10n/apache/trunk/developer/request.xml
/trunk/l10n/apache/trunk/developer/request.xml.meta
/trunk/l10n/apache/trunk/developer/thread_safety.xml
/trunk/l10n/apache/trunk/developer/thread_safety.xml.meta
/trunk/l10n/apache/trunk/dns-caveats.xml
/trunk/l10n/apache/trunk/dns-caveats.xml.meta
/trunk/l10n/apache/trunk/dso.xml
/trunk/l10n/apache/trunk/dso.xml.meta
/trunk/l10n/apache/trunk/env.xml
/trunk/l10n/apache/trunk/env.xml.meta
/trunk/l10n/apache/trunk/expr.xml
/trunk/l10n/apache/trunk/expr.xml.meta
/trunk/l10n/apache/trunk/faq
/trunk/l10n/apache/trunk/faq/index.xml
/trunk/l10n/apache/trunk/faq/index.xml.meta
/trunk/l10n/apache/trunk/faq/index.xml.zh-cn
/trunk/l10n/apache/trunk/filter.xml
/trunk/l10n/apache/trunk/filter.xml.meta
/trunk/l10n/apache/trunk/glossary.xml
/trunk/l10n/apache/trunk/glossary.xml.meta
/trunk/l10n/apache/trunk/handler.xml
/trunk/l10n/apache/trunk/handler.xml.meta
/trunk/l10n/apache/trunk/handler.xml.zh-cn
/trunk/l10n/apache/trunk/howto
/trunk/l10n/apache/trunk/howto/access.xml
/trunk/l10n/apache/trunk/howto/access.xml.meta
/trunk/l10n/apache/trunk/howto/auth.xml
/trunk/l10n/apache/trunk/howto/auth.xml.meta
/trunk/l10n/apache/trunk/howto/cgi.xml
/trunk/l10n/apache/trunk/howto/cgi.xml.meta
/trunk/l10n/apache/trunk/howto/htaccess.xml
/trunk/l10n/apache/trunk/howto/htaccess.xml.meta
/trunk/l10n/apache/trunk/howto/htaccess.xml.pt-br
/trunk/l10n/apache/trunk/howto/index.xml
/trunk/l10n/apache/trunk/howto/index.xml.meta
/trunk/l10n/apache/trunk/howto/index.xml.zh-cn
/trunk/l10n/apache/trunk/howto/public_html.xml
/trunk/l10n/apache/trunk/howto/public_html.xml.meta
/trunk/l10n/apache/trunk/howto/ssi.xml
/trunk/l10n/apache/trunk/howto/ssi.xml.meta
/trunk/l10n/apache/trunk/images
/trunk/l10n/apache/trunk/images/apache_header.gif
/trunk/l10n/apache/trunk/images/caching_fig1.gif
/trunk/l10n/apache/trunk/images/caching_fig1.png
/trunk/l10n/apache/trunk/images/caching_fig1.tr.png
/trunk/l10n/apache/trunk/images/custom_errordocs.png
/trunk/l10n/apache/trunk/images/down.gif
/trunk/l10n/apache/trunk/images/favicon.ico
/trunk/l10n/apache/trunk/images/feather.gif
/trunk/l10n/apache/trunk/images/feather.png
/trunk/l10n/apache/trunk/images/filter_arch.png
/trunk/l10n/apache/trunk/images/filter_arch.tr.png
/trunk/l10n/apache/trunk/images/home.gif
/trunk/l10n/apache/trunk/images/index.gif
/trunk/l10n/apache/trunk/images/left.gif
/trunk/l10n/apache/trunk/images/mod_filter_new.gif
/trunk/l10n/apache/trunk/images/mod_filter_new.png
/trunk/l10n/apache/trunk/images/mod_filter_new.tr.png
/trunk/l10n/apache/trunk/images/mod_filter_old.gif
/trunk/l10n/apache/trunk/images/mod_rewrite_fig1.gif
/trunk/l10n/apache/trunk/images/mod_rewrite_fig1.png
/trunk/l10n/apache/trunk/images/mod_rewrite_fig2.gif
/trunk/l10n/apache/trunk/images/mod_rewrite_fig2.png
/trunk/l10n/apache/trunk/images/pixel.gif
/trunk/l10n/apache/trunk/images/rewrite_rule_flow.png
/trunk/l10n/apache/trunk/images/right.gif
/trunk/l10n/apache/trunk/images/ssl_intro_fig1.gif
/trunk/l10n/apache/trunk/images/ssl_intro_fig1.png
/trunk/l10n/apache/trunk/images/ssl_intro_fig2.gif
/trunk/l10n/apache/trunk/images/ssl_intro_fig2.png
/trunk/l10n/apache/trunk/images/ssl_intro_fig3.gif
/trunk/l10n/apache/trunk/images/ssl_intro_fig3.png
/trunk/l10n/apache/trunk/images/sub.gif
/trunk/l10n/apache/trunk/images/syntax_rewritecond.png
/trunk/l10n/apache/trunk/images/syntax_rewriterule.png
/trunk/l10n/apache/trunk/images/up.gif
/trunk/l10n/apache/trunk/index.xml
/trunk/l10n/apache/trunk/index.xml.da
/trunk/l10n/apache/trunk/index.xml.meta
/trunk/l10n/apache/trunk/index.xml.pt-br
/trunk/l10n/apache/trunk/index.xml.zh-cn
/trunk/l10n/apache/trunk/install.xml
/trunk/l10n/apache/trunk/install.xml.meta
/trunk/l10n/apache/trunk/invoking.xml
/trunk/l10n/apache/trunk/invoking.xml.meta
/trunk/l10n/apache/trunk/license.xml
/trunk/l10n/apache/trunk/license.xml.meta
/trunk/l10n/apache/trunk/logs.xml
/trunk/l10n/apache/trunk/logs.xml.meta
/trunk/l10n/apache/trunk/misc
/trunk/l10n/apache/trunk/misc/index.xml
/trunk/l10n/apache/trunk/misc/index.xml.meta
/trunk/l10n/apache/trunk/misc/index.xml.zh-cn
/trunk/l10n/apache/trunk/misc/password_encryptions.xml
/trunk/l10n/apache/trunk/misc/password_encryptions.xml.meta
/trunk/l10n/apache/trunk/misc/perf-tuning.xml
/trunk/l10n/apache/trunk/misc/perf-tuning.xml.meta
/trunk/l10n/apache/trunk/misc/relevant_standards.xml
/trunk/l10n/apache/trunk/misc/relevant_standards.xml.meta
/trunk/l10n/apache/trunk/misc/security_tips.xml
/trunk/l10n/apache/trunk/misc/security_tips.xml.meta
/trunk/l10n/apache/trunk/mod
/trunk/l10n/apache/trunk/mod/allmodules.xml
/trunk/l10n/apache/trunk/mod/allmodules.xml.zh-cn
/trunk/l10n/apache/trunk/mod/core.xml
/trunk/l10n/apache/trunk/mod/core.xml.meta
/trunk/l10n/apache/trunk/mod/directive-dict.xml
/trunk/l10n/apache/trunk/mod/directive-dict.xml.meta
/trunk/l10n/apache/trunk/mod/directives.xml
/trunk/l10n/apache/trunk/mod/directives.xml.meta
/trunk/l10n/apache/trunk/mod/directives.xml.zh-cn
/trunk/l10n/apache/trunk/mod/event.xml
/trunk/l10n/apache/trunk/mod/event.xml.meta
/trunk/l10n/apache/trunk/mod/index.xml
/trunk/l10n/apache/trunk/mod/index.xml.meta
/trunk/l10n/apache/trunk/mod/index.xml.zh-cn
/trunk/l10n/apache/trunk/mod/mod_access_compat.xml
/trunk/l10n/apache/trunk/mod/mod_access_compat.xml.meta
/trunk/l10n/apache/trunk/mod/mod_actions.xml
/trunk/l10n/apache/trunk/mod/mod_actions.xml.meta
/trunk/l10n/apache/trunk/mod/mod_alias.xml
/trunk/l10n/apache/trunk/mod/mod_alias.xml.meta
/trunk/l10n/apache/trunk/mod/mod_allowmethods.xml
/trunk/l10n/apache/trunk/mod/mod_allowmethods.xml.meta
/trunk/l10n/apache/trunk/mod/mod_asis.xml
/trunk/l10n/apache/trunk/mod/mod_asis.xml.meta
/trunk/l10n/apache/trunk/mod/mod_auth_basic.xml
/trunk/l10n/apache/trunk/mod/mod_auth_basic.xml.meta
/trunk/l10n/apache/trunk/mod/mod_auth_digest.xml
/trunk/l10n/apache/trunk/mod/mod_auth_digest.xml.meta
/trunk/l10n/apache/trunk/mod/mod_auth_form.xml
/trunk/l10n/apache/trunk/mod/mod_auth_form.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authn_anon.xml
/trunk/l10n/apache/trunk/mod/mod_authn_anon.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authn_core.xml
/trunk/l10n/apache/trunk/mod/mod_authn_core.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authn_dbd.xml
/trunk/l10n/apache/trunk/mod/mod_authn_dbd.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authn_dbm.xml
/trunk/l10n/apache/trunk/mod/mod_authn_dbm.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authn_file.xml
/trunk/l10n/apache/trunk/mod/mod_authn_file.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authn_socache.xml
/trunk/l10n/apache/trunk/mod/mod_authn_socache.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authnz_ldap.xml
/trunk/l10n/apache/trunk/mod/mod_authnz_ldap.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authz_core.xml
/trunk/l10n/apache/trunk/mod/mod_authz_core.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authz_dbd.xml
/trunk/l10n/apache/trunk/mod/mod_authz_dbd.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authz_dbm.xml
/trunk/l10n/apache/trunk/mod/mod_authz_dbm.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authz_groupfile.xml
/trunk/l10n/apache/trunk/mod/mod_authz_groupfile.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authz_host.xml
/trunk/l10n/apache/trunk/mod/mod_authz_host.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authz_owner.xml
/trunk/l10n/apache/trunk/mod/mod_authz_owner.xml.meta
/trunk/l10n/apache/trunk/mod/mod_authz_user.xml
/trunk/l10n/apache/trunk/mod/mod_authz_user.xml.meta
/trunk/l10n/apache/trunk/mod/mod_autoindex.xml
/trunk/l10n/apache/trunk/mod/mod_autoindex.xml.meta
/trunk/l10n/apache/trunk/mod/mod_buffer.xml
/trunk/l10n/apache/trunk/mod/mod_buffer.xml.meta
/trunk/l10n/apache/trunk/mod/mod_cache.xml
/trunk/l10n/apache/trunk/mod/mod_cache.xml.meta
/trunk/l10n/apache/trunk/mod/mod_cache_disk.xml
/trunk/l10n/apache/trunk/mod/mod_cache_disk.xml.meta
/trunk/l10n/apache/trunk/mod/mod_cern_meta.xml
/trunk/l10n/apache/trunk/mod/mod_cern_meta.xml.meta
/trunk/l10n/apache/trunk/mod/mod_cgi.xml
/trunk/l10n/apache/trunk/mod/mod_cgi.xml.meta
/trunk/l10n/apache/trunk/mod/mod_cgid.xml
/trunk/l10n/apache/trunk/mod/mod_cgid.xml.meta
/trunk/l10n/apache/trunk/mod/mod_charset_lite.xml
/trunk/l10n/apache/trunk/mod/mod_charset_lite.xml.meta
/trunk/l10n/apache/trunk/mod/mod_dav.xml
/trunk/l10n/apache/trunk/mod/mod_dav.xml.meta
/trunk/l10n/apache/trunk/mod/mod_dav_fs.xml
/trunk/l10n/apache/trunk/mod/mod_dav_fs.xml.meta
/trunk/l10n/apache/trunk/mod/mod_dav_lock.xml
/trunk/l10n/apache/trunk/mod/mod_dav_lock.xml.meta
/trunk/l10n/apache/trunk/mod/mod_dbd.xml
/trunk/l10n/apache/trunk/mod/mod_dbd.xml.meta
/trunk/l10n/apache/trunk/mod/mod_deflate.xml
/trunk/l10n/apache/trunk/mod/mod_deflate.xml.meta
/trunk/l10n/apache/trunk/mod/mod_dialup.xml
/trunk/l10n/apache/trunk/mod/mod_dialup.xml.meta
/trunk/l10n/apache/trunk/mod/mod_dir.xml
/trunk/l10n/apache/trunk/mod/mod_dir.xml.meta
/trunk/l10n/apache/trunk/mod/mod_dumpio.xml
/trunk/l10n/apache/trunk/mod/mod_dumpio.xml.meta
/trunk/l10n/apache/trunk/mod/mod_echo.xml
/trunk/l10n/apache/trunk/mod/mod_echo.xml.meta
/trunk/l10n/apache/trunk/mod/mod_env.xml
/trunk/l10n/apache/trunk/mod/mod_env.xml.meta
/trunk/l10n/apache/trunk/mod/mod_example.xml
/trunk/l10n/apache/trunk/mod/mod_example.xml.meta
/trunk/l10n/apache/trunk/mod/mod_expires.xml
/trunk/l10n/apache/trunk/mod/mod_expires.xml.meta
/trunk/l10n/apache/trunk/mod/mod_ext_filter.xml
/trunk/l10n/apache/trunk/mod/mod_ext_filter.xml.meta
/trunk/l10n/apache/trunk/mod/mod_file_cache.xml
/trunk/l10n/apache/trunk/mod/mod_file_cache.xml.meta
/trunk/l10n/apache/trunk/mod/mod_filter.xml
/trunk/l10n/apache/trunk/mod/mod_filter.xml.meta
/trunk/l10n/apache/trunk/mod/mod_headers.xml
/trunk/l10n/apache/trunk/mod/mod_headers.xml.meta
/trunk/l10n/apache/trunk/mod/mod_heartbeat.xml
/trunk/l10n/apache/trunk/mod/mod_heartbeat.xml.meta
/trunk/l10n/apache/trunk/mod/mod_heartmonitor.xml
/trunk/l10n/apache/trunk/mod/mod_heartmonitor.xml.meta
/trunk/l10n/apache/trunk/mod/mod_ident.xml
/trunk/l10n/apache/trunk/mod/mod_ident.xml.meta
/trunk/l10n/apache/trunk/mod/mod_imagemap.xml
/trunk/l10n/apache/trunk/mod/mod_imagemap.xml.meta
/trunk/l10n/apache/trunk/mod/mod_include.xml
/trunk/l10n/apache/trunk/mod/mod_include.xml.meta
/trunk/l10n/apache/trunk/mod/mod_info.xml
/trunk/l10n/apache/trunk/mod/mod_info.xml.meta
/trunk/l10n/apache/trunk/mod/mod_isapi.xml
/trunk/l10n/apache/trunk/mod/mod_isapi.xml.meta
/trunk/l10n/apache/trunk/mod/mod_lbmethod_bybusyness.xml
/trunk/l10n/apache/trunk/mod/mod_lbmethod_bybusyness.xml.meta
/trunk/l10n/apache/trunk/mod/mod_lbmethod_byrequests.xml
/trunk/l10n/apache/trunk/mod/mod_lbmethod_byrequests.xml.meta
/trunk/l10n/apache/trunk/mod/mod_lbmethod_bytraffic.xml
/trunk/l10n/apache/trunk/mod/mod_lbmethod_bytraffic.xml.meta
/trunk/l10n/apache/trunk/mod/mod_lbmethod_heartbeat.xml
/trunk/l10n/apache/trunk/mod/mod_lbmethod_heartbeat.xml.meta
/trunk/l10n/apache/trunk/mod/mod_ldap.xml
/trunk/l10n/apache/trunk/mod/mod_ldap.xml.meta
/trunk/l10n/apache/trunk/mod/mod_log_config.xml
/trunk/l10n/apache/trunk/mod/mod_log_config.xml.meta
/trunk/l10n/apache/trunk/mod/mod_log_forensic.xml
/trunk/l10n/apache/trunk/mod/mod_log_forensic.xml.meta
/trunk/l10n/apache/trunk/mod/mod_logio.xml
/trunk/l10n/apache/trunk/mod/mod_logio.xml.meta
/trunk/l10n/apache/trunk/mod/mod_lua.xml
/trunk/l10n/apache/trunk/mod/mod_lua.xml.meta
/trunk/l10n/apache/trunk/mod/mod_mime.xml
/trunk/l10n/apache/trunk/mod/mod_mime.xml.meta
/trunk/l10n/apache/trunk/mod/mod_mime_magic.xml
/trunk/l10n/apache/trunk/mod/mod_mime_magic.xml.meta
/trunk/l10n/apache/trunk/mod/mod_negotiation.xml
/trunk/l10n/apache/trunk/mod/mod_negotiation.xml.meta
/trunk/l10n/apache/trunk/mod/mod_nw_ssl.xml
/trunk/l10n/apache/trunk/mod/mod_nw_ssl.xml.meta
/trunk/l10n/apache/trunk/mod/mod_privileges.xml
/trunk/l10n/apache/trunk/mod/mod_privileges.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy.xml
/trunk/l10n/apache/trunk/mod/mod_proxy.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy_ajp.xml
/trunk/l10n/apache/trunk/mod/mod_proxy_ajp.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy_balancer.xml
/trunk/l10n/apache/trunk/mod/mod_proxy_balancer.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy_connect.xml
/trunk/l10n/apache/trunk/mod/mod_proxy_connect.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy_fcgi.xml
/trunk/l10n/apache/trunk/mod/mod_proxy_fcgi.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy_fdpass.xml
/trunk/l10n/apache/trunk/mod/mod_proxy_fdpass.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy_ftp.xml
/trunk/l10n/apache/trunk/mod/mod_proxy_ftp.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy_http.xml
/trunk/l10n/apache/trunk/mod/mod_proxy_http.xml.meta
/trunk/l10n/apache/trunk/mod/mod_proxy_scgi.xml
/trunk/l10n/apache/trunk/mod/mod_proxy_scgi.xml.meta
/trunk/l10n/apache/trunk/mod/mod_ratelimit.xml
/trunk/l10n/apache/trunk/mod/mod_ratelimit.xml.meta
/trunk/l10n/apache/trunk/mod/mod_reflector.xml
/trunk/l10n/apache/trunk/mod/mod_reflector.xml.meta
/trunk/l10n/apache/trunk/mod/mod_remoteip.xml
/trunk/l10n/apache/trunk/mod/mod_remoteip.xml.meta
/trunk/l10n/apache/trunk/mod/mod_reqtimeout.xml
/trunk/l10n/apache/trunk/mod/mod_reqtimeout.xml.meta
/trunk/l10n/apache/trunk/mod/mod_request.xml
/trunk/l10n/apache/trunk/mod/mod_request.xml.meta
/trunk/l10n/apache/trunk/mod/mod_rewrite.xml
/trunk/l10n/apache/trunk/mod/mod_rewrite.xml.meta
/trunk/l10n/apache/trunk/mod/mod_sed.xml
/trunk/l10n/apache/trunk/mod/mod_sed.xml.meta
/trunk/l10n/apache/trunk/mod/mod_session.xml
/trunk/l10n/apache/trunk/mod/mod_session.xml.meta
/trunk/l10n/apache/trunk/mod/mod_session_cookie.xml
/trunk/l10n/apache/trunk/mod/mod_session_cookie.xml.meta
/trunk/l10n/apache/trunk/mod/mod_session_crypto.xml
/trunk/l10n/apache/trunk/mod/mod_session_crypto.xml.meta
/trunk/l10n/apache/trunk/mod/mod_session_dbd.xml
/trunk/l10n/apache/trunk/mod/mod_session_dbd.xml.meta
/trunk/l10n/apache/trunk/mod/mod_setenvif.xml
/trunk/l10n/apache/trunk/mod/mod_setenvif.xml.meta
/trunk/l10n/apache/trunk/mod/mod_slotmem_plain.xml
/trunk/l10n/apache/trunk/mod/mod_slotmem_plain.xml.meta
/trunk/l10n/apache/trunk/mod/mod_slotmem_shm.xml
/trunk/l10n/apache/trunk/mod/mod_slotmem_shm.xml.meta
/trunk/l10n/apache/trunk/mod/mod_so.xml
/trunk/l10n/apache/trunk/mod/mod_so.xml.meta
/trunk/l10n/apache/trunk/mod/mod_speling.xml
/trunk/l10n/apache/trunk/mod/mod_speling.xml.meta
/trunk/l10n/apache/trunk/mod/mod_ssl.xml
/trunk/l10n/apache/trunk/mod/mod_ssl.xml.meta
/trunk/l10n/apache/trunk/mod/mod_status.xml
/trunk/l10n/apache/trunk/mod/mod_status.xml.meta
/trunk/l10n/apache/trunk/mod/mod_substitute.xml
/trunk/l10n/apache/trunk/mod/mod_substitute.xml.meta
/trunk/l10n/apache/trunk/mod/mod_suexec.xml
/trunk/l10n/apache/trunk/mod/mod_suexec.xml.meta
/trunk/l10n/apache/trunk/mod/mod_unique_id.xml
/trunk/l10n/apache/trunk/mod/mod_unique_id.xml.meta
/trunk/l10n/apache/trunk/mod/mod_unixd.xml
/trunk/l10n/apache/trunk/mod/mod_unixd.xml.meta
/trunk/l10n/apache/trunk/mod/mod_userdir.xml
/trunk/l10n/apache/trunk/mod/mod_userdir.xml.meta
/trunk/l10n/apache/trunk/mod/mod_usertrack.xml
/trunk/l10n/apache/trunk/mod/mod_usertrack.xml.meta
/trunk/l10n/apache/trunk/mod/mod_version.xml
/trunk/l10n/apache/trunk/mod/mod_version.xml.meta
/trunk/l10n/apache/trunk/mod/mod_vhost_alias.xml
/trunk/l10n/apache/trunk/mod/mod_vhost_alias.xml.meta
/trunk/l10n/apache/trunk/mod/module-dict.xml
/trunk/l10n/apache/trunk/mod/module-dict.xml.meta
/trunk/l10n/apache/trunk/mod/mpm_common.xml
/trunk/l10n/apache/trunk/mod/mpm_common.xml.meta
/trunk/l10n/apache/trunk/mod/mpm_netware.xml
/trunk/l10n/apache/trunk/mod/mpm_netware.xml.meta
/trunk/l10n/apache/trunk/mod/mpm_winnt.xml
/trunk/l10n/apache/trunk/mod/mpm_winnt.xml.meta
/trunk/l10n/apache/trunk/mod/mpmt_os2.xml
/trunk/l10n/apache/trunk/mod/mpmt_os2.xml.meta
/trunk/l10n/apache/trunk/mod/prefork.xml
/trunk/l10n/apache/trunk/mod/prefork.xml.meta
/trunk/l10n/apache/trunk/mod/quickreference.xml
/trunk/l10n/apache/trunk/mod/quickreference.xml.meta
/trunk/l10n/apache/trunk/mod/quickreference.xml.zh-cn
/trunk/l10n/apache/trunk/mod/worker.xml
/trunk/l10n/apache/trunk/mod/worker.xml.meta
/trunk/l10n/apache/trunk/mpm.xml
/trunk/l10n/apache/trunk/mpm.xml.meta
/trunk/l10n/apache/trunk/mpm.xml.zh-cn
/trunk/l10n/apache/trunk/new_features_2_0.xml
/trunk/l10n/apache/trunk/new_features_2_0.xml.meta
/trunk/l10n/apache/trunk/new_features_2_0.xml.pt-br
/trunk/l10n/apache/trunk/new_features_2_0.xml.ru
/trunk/l10n/apache/trunk/new_features_2_2.xml
/trunk/l10n/apache/trunk/new_features_2_2.xml.meta
/trunk/l10n/apache/trunk/new_features_2_2.xml.pt-br
/trunk/l10n/apache/trunk/new_features_2_4.xml
/trunk/l10n/apache/trunk/new_features_2_4.xml.meta
/trunk/l10n/apache/trunk/platform
/trunk/l10n/apache/trunk/platform/ebcdic.xml
/trunk/l10n/apache/trunk/platform/ebcdic.xml.meta
/trunk/l10n/apache/trunk/platform/index.xml
/trunk/l10n/apache/trunk/platform/index.xml.meta
/trunk/l10n/apache/trunk/platform/index.xml.zh-cn
/trunk/l10n/apache/trunk/platform/netware.xml
/trunk/l10n/apache/trunk/platform/netware.xml.meta
/trunk/l10n/apache/trunk/platform/perf-hp.xml
/trunk/l10n/apache/trunk/platform/perf-hp.xml.meta
/trunk/l10n/apache/trunk/platform/win_compiling.xml
/trunk/l10n/apache/trunk/platform/win_compiling.xml.meta
/trunk/l10n/apache/trunk/platform/windows.xml
/trunk/l10n/apache/trunk/platform/windows.xml.meta
/trunk/l10n/apache/trunk/programs
/trunk/l10n/apache/trunk/programs/ab.xml
/trunk/l10n/apache/trunk/programs/ab.xml.meta
/trunk/l10n/apache/trunk/programs/apachectl.xml
/trunk/l10n/apache/trunk/programs/apachectl.xml.meta
/trunk/l10n/apache/trunk/programs/apxs.xml
/trunk/l10n/apache/trunk/programs/apxs.xml.meta
/trunk/l10n/apache/trunk/programs/configure.xml
/trunk/l10n/apache/trunk/programs/configure.xml.meta
/trunk/l10n/apache/trunk/programs/dbmmanage.xml
/trunk/l10n/apache/trunk/programs/dbmmanage.xml.meta
/trunk/l10n/apache/trunk/programs/fcgistarter.xml
/trunk/l10n/apache/trunk/programs/fcgistarter.xml.meta
/trunk/l10n/apache/trunk/programs/htcacheclean.xml
/trunk/l10n/apache/trunk/programs/htcacheclean.xml.meta
/trunk/l10n/apache/trunk/programs/htdbm.xml
/trunk/l10n/apache/trunk/programs/htdbm.xml.meta
/trunk/l10n/apache/trunk/programs/htdigest.xml
/trunk/l10n/apache/trunk/programs/htdigest.xml.meta
/trunk/l10n/apache/trunk/programs/htpasswd.xml
/trunk/l10n/apache/trunk/programs/htpasswd.xml.meta
/trunk/l10n/apache/trunk/programs/httpd.xml
/trunk/l10n/apache/trunk/programs/httpd.xml.meta
/trunk/l10n/apache/trunk/programs/httxt2dbm.xml
/trunk/l10n/apache/trunk/programs/httxt2dbm.xml.meta
/trunk/l10n/apache/trunk/programs/index.xml
/trunk/l10n/apache/trunk/programs/index.xml.meta
/trunk/l10n/apache/trunk/programs/index.xml.zh-cn
/trunk/l10n/apache/trunk/programs/logresolve.xml
/trunk/l10n/apache/trunk/programs/logresolve.xml.meta
/trunk/l10n/apache/trunk/programs/other.xml
/trunk/l10n/apache/trunk/programs/other.xml.meta
/trunk/l10n/apache/trunk/programs/rotatelogs.xml
/trunk/l10n/apache/trunk/programs/rotatelogs.xml.meta
/trunk/l10n/apache/trunk/programs/suexec.xml
/trunk/l10n/apache/trunk/programs/suexec.xml.meta
/trunk/l10n/apache/trunk/rewrite
/trunk/l10n/apache/trunk/rewrite/access.xml
/trunk/l10n/apache/trunk/rewrite/access.xml.meta
/trunk/l10n/apache/trunk/rewrite/advanced.xml
/trunk/l10n/apache/trunk/rewrite/advanced.xml.meta
/trunk/l10n/apache/trunk/rewrite/avoid.xml
/trunk/l10n/apache/trunk/rewrite/avoid.xml.meta
/trunk/l10n/apache/trunk/rewrite/flags.xml
/trunk/l10n/apache/trunk/rewrite/flags.xml.meta
/trunk/l10n/apache/trunk/rewrite/htaccess.xml
/trunk/l10n/apache/trunk/rewrite/htaccess.xml.meta
/trunk/l10n/apache/trunk/rewrite/index.xml
/trunk/l10n/apache/trunk/rewrite/index.xml.meta
/trunk/l10n/apache/trunk/rewrite/index.xml.zh-cn
/trunk/l10n/apache/trunk/rewrite/intro.xml
/trunk/l10n/apache/trunk/rewrite/intro.xml.meta
/trunk/l10n/apache/trunk/rewrite/proxy.xml
/trunk/l10n/apache/trunk/rewrite/proxy.xml.meta
/trunk/l10n/apache/trunk/rewrite/remapping.xml
/trunk/l10n/apache/trunk/rewrite/remapping.xml.meta
/trunk/l10n/apache/trunk/rewrite/rewritemap.xml
/trunk/l10n/apache/trunk/rewrite/rewritemap.xml.meta
/trunk/l10n/apache/trunk/rewrite/tech.xml
/trunk/l10n/apache/trunk/rewrite/tech.xml.meta
/trunk/l10n/apache/trunk/rewrite/vhosts.xml
/trunk/l10n/apache/trunk/rewrite/vhosts.xml.meta
/trunk/l10n/apache/trunk/sections.xml
/trunk/l10n/apache/trunk/sections.xml.meta
/trunk/l10n/apache/trunk/server-wide.xml
/trunk/l10n/apache/trunk/server-wide.xml.meta
/trunk/l10n/apache/trunk/sitemap.xml
/trunk/l10n/apache/trunk/sitemap.xml.meta
/trunk/l10n/apache/trunk/sitemap.xml.zh-cn
/trunk/l10n/apache/trunk/ssl
/trunk/l10n/apache/trunk/ssl/index.xml
/trunk/l10n/apache/trunk/ssl/index.xml.meta
/trunk/l10n/apache/trunk/ssl/index.xml.zh-cn
/trunk/l10n/apache/trunk/ssl/ssl_compat.xml
/trunk/l10n/apache/trunk/ssl/ssl_compat.xml.meta
/trunk/l10n/apache/trunk/ssl/ssl_faq.xml
/trunk/l10n/apache/trunk/ssl/ssl_faq.xml.meta
/trunk/l10n/apache/trunk/ssl/ssl_howto.xml
/trunk/l10n/apache/trunk/ssl/ssl_howto.xml.meta
/trunk/l10n/apache/trunk/ssl/ssl_intro.xml
/trunk/l10n/apache/trunk/ssl/ssl_intro.xml.meta
/trunk/l10n/apache/trunk/stopping.xml
/trunk/l10n/apache/trunk/stopping.xml.meta
/trunk/l10n/apache/trunk/style
/trunk/l10n/apache/trunk/style/build.properties
/trunk/l10n/apache/trunk/style/common.dtd
/trunk/l10n/apache/trunk/style/css
/trunk/l10n/apache/trunk/style/css/manual-chm.css
/trunk/l10n/apache/trunk/style/css/manual-loose-100pc.css
/trunk/l10n/apache/trunk/style/css/manual-print.css
/trunk/l10n/apache/trunk/style/css/manual-zip-100pc.css
/trunk/l10n/apache/trunk/style/css/manual-zip.css
/trunk/l10n/apache/trunk/style/css/manual.css
/trunk/l10n/apache/trunk/style/description.xml
/trunk/l10n/apache/trunk/style/faq.dtd
/trunk/l10n/apache/trunk/style/lang
/trunk/l10n/apache/trunk/style/lang/da.xml
/trunk/l10n/apache/trunk/style/lang/de.xml
/trunk/l10n/apache/trunk/style/lang/en.xml
/trunk/l10n/apache/trunk/style/lang/es.xml
/trunk/l10n/apache/trunk/style/lang/fr.xml
/trunk/l10n/apache/trunk/style/lang/ja.xml
/trunk/l10n/apache/trunk/style/lang/ko.xml
/trunk/l10n/apache/trunk/style/lang/pt-br.xml
/trunk/l10n/apache/trunk/style/lang/ru.xml
/trunk/l10n/apache/trunk/style/lang/tr.xml
/trunk/l10n/apache/trunk/style/lang/zh-cn.xml
/trunk/l10n/apache/trunk/style/lang-targets.xml
/trunk/l10n/apache/trunk/style/lang.dtd
/trunk/l10n/apache/trunk/style/latex
/trunk/l10n/apache/trunk/style/latex/atbeginend.sty
/trunk/l10n/apache/trunk/style/latex/common.xsl
/trunk/l10n/apache/trunk/style/latex/directiveindex.xsl
/trunk/l10n/apache/trunk/style/latex/faq.xsl
/trunk/l10n/apache/trunk/style/latex/html.xsl
/trunk/l10n/apache/trunk/style/latex/latex.xsl
/trunk/l10n/apache/trunk/style/latex/manualpage.xsl
/trunk/l10n/apache/trunk/style/latex/moduleindex.xsl
/trunk/l10n/apache/trunk/style/latex/quickreference.xsl
/trunk/l10n/apache/trunk/style/latex/synopsis.xsl
/trunk/l10n/apache/trunk/style/manual.da.xsl
/trunk/l10n/apache/trunk/style/manual.de.xsl
/trunk/l10n/apache/trunk/style/manual.en.xsl
/trunk/l10n/apache/trunk/style/manual.es.xsl
/trunk/l10n/apache/trunk/style/manual.fr.xsl
/trunk/l10n/apache/trunk/style/manual.ja.xsl
/trunk/l10n/apache/trunk/style/manual.ko.xsl
/trunk/l10n/apache/trunk/style/manual.pt-br.xsl
/trunk/l10n/apache/trunk/style/manual.ru.xsl
/trunk/l10n/apache/trunk/style/manual.tr.xsl
/trunk/l10n/apache/trunk/style/manual.zh-cn.xsl
/trunk/l10n/apache/trunk/style/manualpage.dtd
/trunk/l10n/apache/trunk/style/modulesynopsis.dtd
/trunk/l10n/apache/trunk/style/sitemap.dtd
/trunk/l10n/apache/trunk/style/version.ent
/trunk/l10n/apache/trunk/style/xsl
/trunk/l10n/apache/trunk/style/xsl/common.xsl
/trunk/l10n/apache/trunk/style/xsl/convmap.xsl
/trunk/l10n/apache/trunk/style/xsl/directiveindex.xsl
/trunk/l10n/apache/trunk/style/xsl/faq.xsl
/trunk/l10n/apache/trunk/style/xsl/hhc.xsl
/trunk/l10n/apache/trunk/style/xsl/hhp.xsl
/trunk/l10n/apache/trunk/style/xsl/indexpage.xsl
/trunk/l10n/apache/trunk/style/xsl/language.xsl
/trunk/l10n/apache/trunk/style/xsl/maf.xsl
/trunk/l10n/apache/trunk/style/xsl/manualpage.xsl
/trunk/l10n/apache/trunk/style/xsl/moduleindex.xsl
/trunk/l10n/apache/trunk/style/xsl/nroff.xsl
/trunk/l10n/apache/trunk/style/xsl/quickreference.xsl
/trunk/l10n/apache/trunk/style/xsl/sitemap.xsl
/trunk/l10n/apache/trunk/style/xsl/synopsis.xsl
/trunk/l10n/apache/trunk/style/xsl/typemap.xsl
/trunk/l10n/apache/trunk/style/xsl/util
/trunk/l10n/apache/trunk/style/xsl/util/allmodules.xml
/trunk/l10n/apache/trunk/style/xsl/util/designations.xml
/trunk/l10n/apache/trunk/style/xsl/util/lf.xml
/trunk/l10n/apache/trunk/style/xsl/util/li-end.xml
/trunk/l10n/apache/trunk/style/xsl/util/li-start.xml
/trunk/l10n/apache/trunk/style/xsl/util/modtrans.xsl
/trunk/l10n/apache/trunk/style/xsl/util/nbsp.xml
/trunk/l10n/apache/trunk/style/xsl/util/tab.xml
/trunk/l10n/apache/trunk/style/xsl/util/ul-end.xml
/trunk/l10n/apache/trunk/style/xsl/util/ul-start.xml
/trunk/l10n/apache/trunk/suexec.xml
/trunk/l10n/apache/trunk/suexec.xml.meta
/trunk/l10n/apache/trunk/upgrading.xml
/trunk/l10n/apache/trunk/upgrading.xml.meta
/trunk/l10n/apache/trunk/urlmapping.xml
/trunk/l10n/apache/trunk/urlmapping.xml.meta
/trunk/l10n/apache/trunk/vhosts
/trunk/l10n/apache/trunk/vhosts/details.xml
/trunk/l10n/apache/trunk/vhosts/details.xml.meta
/trunk/l10n/apache/trunk/vhosts/examples.xml
/trunk/l10n/apache/trunk/vhosts/examples.xml.meta
/trunk/l10n/apache/trunk/vhosts/fd-limits.xml
/trunk/l10n/apache/trunk/vhosts/fd-limits.xml.meta
/trunk/l10n/apache/trunk/vhosts/index.xml
/trunk/l10n/apache/trunk/vhosts/index.xml.meta
/trunk/l10n/apache/trunk/vhosts/index.xml.zh-cn
/trunk/l10n/apache/trunk/vhosts/ip-based.xml
/trunk/l10n/apache/trunk/vhosts/ip-based.xml.meta
/trunk/l10n/apache/trunk/vhosts/mass.xml
/trunk/l10n/apache/trunk/vhosts/mass.xml.meta
/trunk/l10n/apache/trunk/vhosts/name-based.xml
/trunk/l10n/apache/trunk/vhosts/name-based.xml.meta
Modified:
/trunk/l10n/apache/trunk

=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/LICENSE Sat Feb 26 23:20:49 2011
@@ -0,0 +1,202 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other
modifications
+ represent, as a whole, an original work of authorship. For the
purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces
of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright
owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control
systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this
License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/bind.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,193 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="bind.xml.meta">
+
+ <title>Binding to Addresses and Ports</title>
+
+ <summary>
+ <p>Configuring Apache HTTP Server to listen on specific addresses and
ports.</p>
+ </summary>
+
+ <seealso><a href="vhosts/">Virtual Hosts</a></seealso>
+ <seealso><a href="dns-caveats.html">DNS Issues</a></seealso>
+
+ <section id="overview">
+ <title>Overview</title>
+
+ <related>
+ <modulelist>
+ <module>core</module>
+ <module>mpm_common</module>
+ </modulelist>
+ <directivelist>
+ <directive module="core" type="section">VirtualHost</directive>
+ <directive module="mpm_common">Listen</directive>
+ </directivelist>
+ </related>
+
+
+ <p>When httpd starts, it binds to some port and address on
+ the local machine and waits for incoming requests. By default,
+ it listens to all addresses on the machine. However, it may need to
+ be told to listen on specific ports, or only on selected
+ addresses, or a combination of both. This is often combined with the
+ <a href="vhosts.html">Virtual Host</a> feature, which determines how
+ <code>httpd</code> responds to different IP addresses, hostnames and
+ ports.</p>
+
+ <p>The <directive module="mpm_common">Listen</directive>
+ directive tells the server to accept
+ incoming requests only on the specified port(s) or
+ address-and-port combinations. If only a port number is
+ specified in the <directive module="mpm_common">Listen</directive>
+ directive, the server listens to the given port on all interfaces.
+ If an IP address is given as well as a port, the server will listen
+ on the given port and interface. Multiple <directive
+ module="mpm_common">Listen</directive> directives may be used to
+ specify a number of addresses and ports to listen on. The
+ server will respond to requests from any of the listed
+ addresses and ports.</p>
+
+ <p>For example, to make the server accept connections on both
+ port 80 and port 8000, on all interfaces, use:</p>
+
+ <example>
+ Listen 80<br />
+ Listen 8000
+ </example>
+
+ <p>To make the server accept connections on port 80 for one interface,
+ and port 8000 on another, use</p>
+
+ <example>
+ Listen 192.0.2.1:80<br />
+ Listen 192.0.2.5:8000
+ </example>
+
+ <p>IPv6 addresses must be enclosed in square brackets, as in the
+ following example:</p>
+
+ <example>
+ Listen [2001:db8::a00:20ff:fea7:ccea]:80
+ </example>
+
+ <note type="warning"><p>Overlapping <directive
+ module="mpm_common">Listen</directive> directives will result in a
+ fatal error which will prevent the server from starting up.</p>
+
+ <example>
+ (48)Address already in use: make_sock: could not bind to address
[::]:80
+ </example>
+ </note>
+
+ </section>
+
+ <section id="ipv6">
+ <title>Special IPv6 Considerations</title>
+
+ <p>A growing number of platforms implement IPv6, and
+ <glossary>APR</glossary> supports IPv6 on most of these platforms,
+ allowing httpd to allocate IPv6 sockets, and to handle requests sent
+ over IPv6.</p>
+
+ <p>One complicating factor for httpd administrators is whether or
+ not an IPv6 socket can handle both IPv4 connections and IPv6
+ connections. Handling IPv4 connections with an IPv6 socket uses
+ IPv4-mapped IPv6 addresses, which are allowed by default on most
+ platforms, but are disallowed by default on FreeBSD, NetBSD, and
+ OpenBSD, in order to match the system-wide policy on those
+ platforms. On systems where it is disallowed by default, a
+ special <program>configure</program> parameter can change this behavior
+ for httpd.</p>
+
+ <p>On the other hand, on some platforms, such as Linux and Tru64, the
+ <strong>only</strong> way to handle both IPv6 and IPv4 is to use
+ mapped addresses. If you want <code>httpd</code> to handle IPv4 and
IPv6 connections
+ with a minimum of sockets, which requires using IPv4-mapped IPv6
+ addresses, specify the <code>--enable-v4-mapped</code> <program>
+ configure</program> option.</p>
+
+ <p><code>--enable-v4-mapped</code> is the default on all platforms
except
+ FreeBSD, NetBSD, and OpenBSD, so this is probably how your httpd was
+ built.</p>
+
+ <p>If you want httpd to handle IPv4 connections only, regardless of
+ what your platform and APR will support, specify an IPv4 address on all
+ <directive module="mpm_common">Listen</directive> directives, as in the
+ following examples:</p>
+
+ <example>
+ Listen 0.0.0.0:80<br />
+ Listen 192.0.2.1:80
+ </example>
+
+ <p>If your platform supports it and you want httpd to handle IPv4 and
+ IPv6 connections on separate sockets (i.e., to disable IPv4-mapped
+ addresses), specify the <code>--disable-v4-mapped</code> <program>
+ configure</program> option. <code>--disable-v4-mapped</code> is the
+ default on FreeBSD, NetBSD, and OpenBSD.</p>
+ </section>
+
+ <section id="protocol">
+ <title>Specifying the protocol with Listen</title>
+ <p>The optional second <var>protocol</var> argument of
+ <directive module="mpm_common">Listen</directive>
+ is not required for most
+ configurations. If not specified, <code>https</code> is the default
for
+ port 443 and <code>http</code> the default for all other ports. The
+ protocol is used to determine which module should handle a request,
and
+ to apply protocol specific optimizations with the
+ <directive module="core">AcceptFilter</directive> directive.</p>
+
+ <p>You only need to set the protocol if you are running on non-standard
+ ports. For example, running an <code>https</code> site on port
8443:</p>
+
+ <example>
+ Listen 192.170.2.1:8443 https
+ </example>
+ </section>
+
+ <section id="virtualhost">
+ <title>How This Works With Virtual Hosts</title>
+
+ <p> The <directive
+ module="mpm_common">Listen</directive> directive does not implement
+ Virtual Hosts - it only tells the
+ main server what addresses and ports to listen on. If no
+ <directive module="core" type="section">VirtualHost</directive>
+ directives are used, the server will behave
+ in the same way for all accepted requests. However,
+ <directive module="core" type="section">VirtualHost</directive>
+ can be used to specify a different behavior
+ for one or more of the addresses or ports. To implement a
+ VirtualHost, the server must first be told to listen to the
+ address and port to be used. Then a
+ <directive module="core" type="section">VirtualHost</directive> section
+ should be created for the specified address and port to set the
+ behavior of this virtual host. Note that if the
+ <directive module="core" type="section">VirtualHost</directive>
+ is set for an address and port that the
+ server is not listening to, it cannot be accessed.</p>
+ </section>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/bind.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="bind.xml">
+ <basename>bind</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant outdated="yes">de</variant>
+ <variant>en</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">ja</variant>
+ <variant outdated="yes">ko</variant>
+ <variant outdated="yes">tr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/caching.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,671 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="caching.xml.meta">
+
+ <title>Caching Guide</title>
+
+ <summary>
+ <p>This document supplements the <module>mod_cache</module>,
+ <module>mod_cache_disk</module>, <module>mod_file_cache</module> and <a
+ href="programs/htcacheclean.html">htcacheclean</a> reference
documentation.
+ It describes how to use the Apache HTTP Server's caching features to
accelerate web and
+ proxy serving, while avoiding common problems and
misconfigurations.</p>
+ </summary>
+
+ <section id="introduction">
+ <title>Introduction</title>
+
+ <p>As of Apache HTTP server version 2.2 <module>mod_cache</module>
+ and <module>mod_file_cache</module> are no longer marked
+ experimental and are considered suitable for production use. These
+ caching architectures provide a powerful means to accelerate HTTP
+ handling, both as an origin webserver and as a proxy.</p>
+
+ <p><module>mod_cache</module> and its provider modules
+ <module>mod_cache_disk</module>
+ provide intelligent, HTTP-aware caching. The content itself is stored
+ in the cache, and mod_cache aims to honor all of the various HTTP
+ headers and options that control the cachability of content. It can
+ handle both local and proxied content. <module>mod_cache</module>
+ is aimed at both simple and complex caching configurations, where
+ you are dealing with proxied content, dynamic local content or
+ have a need to speed up access to local files which change with
+ time.</p>
+
+ <p><module>mod_file_cache</module> on the other hand presents a more
+ basic, but sometimes useful, form of caching. Rather than maintain
+ the complexity of actively ensuring the cachability of URLs,
+ <module>mod_file_cache</module> offers file-handle and memory-mapping
+ tricks to keep a cache of files as they were when httpd was last
+ started. As such, <module>mod_file_cache</module> is aimed at improving
+ the access time to local static files which do not change very
+ often.</p>
+
+ <p>As <module>mod_file_cache</module> presents a relatively simple
+ caching implementation, apart from the specific sections on <directive
+ module="mod_file_cache">CacheFile</directive> and <directive
+ module="mod_file_cache">MMapFile</directive>, the explanations
+ in this guide cover the <module>mod_cache</module> caching
+ architecture.</p>
+
+ <p>To get the most from this document, you should be familiar with
+ the basics of HTTP, and have read the Users' Guides to
+ <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
+ <a href="content-negotiation.html">Content negotiation</a>.</p>
+
+ </section>
+
+ <section id="overview">
+
+ <title>Caching Overview</title>
+
+ <related>
+ <modulelist>
+ <module>mod_cache</module>
+ <module>mod_cache_disk</module>
+ <module>mod_file_cache</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_cache">CacheEnable</directive>
+ <directive module="mod_cache">CacheDisable</directive>
+ <directive module="mod_file_cache">CacheFile</directive>
+ <directive module="mod_file_cache">MMapFile</directive>
+ <directive module="core">UseCanonicalName</directive>
+ <directive module="mod_negotiation">CacheNegotiatedDocs</directive>
+ </directivelist>
+ </related>
+
+ <p>There are two main stages in <module>mod_cache</module> that can
+ occur in the lifetime of a request. First, <module>mod_cache</module>
+ is a URL mapping module, which means that if a URL has been cached,
+ and the cached version of that URL has not expired, the request will
+ be served directly by <module>mod_cache</module>.</p>
+
+ <p>This means that any other stages that might ordinarily happen
+ in the process of serving a request -- for example being handled
+ by <module>mod_proxy</module>, or <module>mod_rewrite</module> --
+ won't happen. But then this is the point of caching content in
+ the first place.</p>
+
+ <p>If the URL is not found within the cache, <module>mod_cache</module>
+ will add a <a href="filter.html">filter</a> to the request handling.
After
+ httpd has located the content by the usual means, the filter will be
run
+ as the content is served. If the content is determined to be cacheable,
+ the content will be saved to the cache for future serving.</p>
+
+ <p>If the URL is found within the cache, but also found to have
expired,
+ the filter is added anyway, but <module>mod_cache</module> will create
+ a conditional request to the backend, to determine if the cached
version
+ is still current. If the cached version is still current, its
+ meta-information will be updated and the request will be served from
the
+ cache. If the cached version is no longer current, the cached version
+ will be deleted and the filter will save the updated content to the
cache
+ as it is served.</p>
+
+ <section>
+ <title>Improving Cache Hits</title>
+
+ <p>When caching locally generated content, ensuring that
+ <directive module="core">UseCanonicalName</directive> is set to
+ <code>On</code> can dramatically improve the ratio of cache hits.
This
+ is because the hostname of the virtual-host serving the content forms
+ a part of the cache key. With the setting set to <code>On</code>
+ virtual-hosts with multiple server names or aliases will not produce
+ differently cached entities, and instead content will be cached as
+ per the canonical hostname.</p>
+
+ <p>Because caching is performed within the URL to filename
translation
+ phase, cached documents will only be served in response to URL
requests.
+ Ordinarily this is of little consequence, but there is one
circumstance
+ in which it matters: If you are using <a href="howto/ssi.html">Server
+ Side Includes</a>;</p>
+
+ <example>
+<br />
+ <br />
+<br />
+<br />
+
+ </example>
+
+ <p>If you are using Server Side Includes, and want the benefit of
speedy
+ serves from the cache, you should use <code>virtual</code> include
+ types.</p>
+ </section>
+
+ <section>
+ <title>Expiry Periods</title>
+
+ <p>The default expiry period for cached entities is one hour, however
+ this can be easily over-ridden by using the <directive
+ module="mod_cache">CacheDefaultExpire</directive> directive. This
+ default is only used when the original source of the content does not
+ specify an expire time or time of last modification.</p>
+
+ <p>If a response does not include an <code>Expires</code> header but
does
+ include a <code>Last-Modified</code> header,
<module>mod_cache</module>
+ can infer an expiry period based on the use of the <directive
+ module="mod_cache">CacheLastModifiedFactor</directive> directive.</p>
+
+ <p>For local content, <module>mod_expires</module> may be used to
+ fine-tune the expiry period.</p>
+
+ <p>The maximum expiry period may also be controlled by using the
+ <directive module="mod_cache">CacheMaxExpire</directive>.</p>
+
+ </section>
+
+ <section>
+ <title>A Brief Guide to Conditional Requests</title>
+
+ <p>When content expires from the cache and is re-requested from the
+ backend or content provider, rather than pass on the original
request,
+ httpd will use a conditional request instead.</p>
+
+ <p>HTTP offers a number of headers which allow a client, or cache
+ to discern between different versions of the same content. For
+ example if a resource was served with an "Etag:" header, it is
+ possible to make a conditional request with an "If-None-Match:"
+ header. If a resource was served with a "Last-Modified:" header
+ it is possible to make a conditional request with an
+ "If-Modified-Since:" header, and so on.</p>
+
+ <p>When such a conditional request is made, the response differs
+ depending on whether the content matches the conditions. If a
request is
+ made with an "If-Modified-Since:" header, and the content has not
been
+ modified since the time indicated in the request then a terse "304
Not
+ Modified" response is issued.</p>
+
+ <p>If the content has changed, then it is served as if the request
were
+ not conditional to begin with.</p>
+
+ <p>The benefits of conditional requests in relation to caching are
+ twofold. Firstly, when making such a request to the backend, if the
+ content from the backend matches the content in the store, this can
be
+ determined easily and without the overhead of transferring the entire
+ resource.</p>
+
+ <p>Secondly, conditional requests are usually less strenuous on the
+ backend. For static files, typically all that is involved is a call
+ to <code>stat()</code> or similar system call, to see if the file has
+ changed in size or modification time. As such, even if httpd is
+ caching local content, even expired content may still be served
faster
+ from the cache if it has not changed. As long as reading from the
cache
+ store is faster than reading from the backend (e.g. <module
+ >mod_cache_disk</module> with memory disk
+ compared to reading from disk).</p>
+ </section>
+
+ <section>
+ <title>What Can be Cached?</title>
+
+ <p>As mentioned already, the two styles of caching in httpd work
+ differently, <module>mod_file_cache</module> caching maintains file
+ contents as they were when httpd was started. When a request is
+ made for a file that is cached by this module, it is intercepted
+ and the cached file is served.</p>
+
+ <p><module>mod_cache</module> caching on the other hand is more
+ complex. When serving a request, if it has not been cached
+ previously, the caching module will determine if the content
+ is cacheable. The conditions for determining cachability of
+ a response are;</p>
+
+ <ol>
+ <li>Caching must be enabled for this URL. See the <directive
+ module="mod_cache">CacheEnable</directive> and <directive
+ module="mod_cache">CacheDisable</directive> directives.</li>
+
+ <li>The response must have a HTTP status code of 200, 203, 300,
301 or
+ 410.</li>
+
+ <li>The request must be a HTTP GET request.</li>
+
+ <li>If the request contains an "Authorization:" header, the
response
+ will not be cached.</li>
+
+ <li>If the response contains an "Authorization:" header, it must
+ also contain an "s-maxage", "must-revalidate" or "public" option
+ in the "Cache-Control:" header.</li>
+
+ <li>If the URL included a query string (e.g. from a HTML form GET
+ method) it will not be cached unless the response specifies an
+ explicit expiration by including an "Expires:" header or the
max-age
+ or s-maxage directive of the "Cache-Control:" header, as per
RFC2616
+ sections 13.9 and 13.2.1.</li>
+
+ <li>If the response has a status of 200 (OK), the response must
+ also include at least one of the "Etag", "Last-Modified" or
+ the "Expires" headers, or the max-age or s-maxage directive of
+ the "Cache-Control:" header, unless the
+ <directive module="mod_cache">CacheIgnoreNoLastMod</directive>
+ directive has been used to require otherwise.</li>
+
+ <li>If the response includes the "private" option in
a "Cache-Control:"
+ header, it will not be stored unless the
+ <directive module="mod_cache">CacheStorePrivate</directive> has
been
+ used to require otherwise.</li>
+
+ <li>Likewise, if the response includes the "no-store" option in a
+ "Cache-Control:" header, it will not be stored unless the
+ <directive module="mod_cache">CacheStoreNoStore</directive> has
been
+ used.</li>
+
+ <li>A response will not be stored if it includes a "Vary:" header
+ containing the match-all "*".</li>
+ </ol>
+ </section>
+
+ <section>
+ <title>What Should Not be Cached?</title>
+
+ <p>In short, any content which is highly time-sensitive, or which
varies
+ depending on the particulars of the request that are not covered by
+ HTTP negotiation, should not be cached.</p>
+
+ <p>If you have dynamic content which changes depending on the IP
address
+ of the requester, or changes every 5 minutes, it should almost
certainly
+ not be cached.</p>
+
+ <p>If on the other hand, the content served differs depending on the
+ values of various HTTP headers, it might be possible
+ to cache it intelligently through the use of a "Vary" header.</p>
+ </section>
+
+ <section>
+ <title>Variable/Negotiated Content</title>
+
+ <p>If a response with a "Vary" header is received by
+ <module>mod_cache</module> when requesting content by the backend it
+ will attempt to handle it intelligently. If possible,
+ <module>mod_cache</module> will detect the headers attributed in the
+ "Vary" response in future requests and serve the correct cached
+ response.</p>
+
+ <p>If for example, a response is received with a vary header such
as;</p>
+
+ <example>
+Vary: negotiate,accept-language,accept-charset
+ </example>
+
+ <p><module>mod_cache</module> will only serve the cached content to
+ requesters with accept-language and accept-charset headers
+ matching those of the original request.</p>
+ </section>
+ </section>
+
+ <section id="security">
+ <title>Security Considerations</title>
+
+ <section>
+ <title>Authorization and Access Control</title>
+
+ <p>Using <module>mod_cache</module> is very much like having a built
+ in reverse-proxy. Requests will be served by the caching module
unless
+ it determines that the backend should be queried. When caching local
+ resources, this drastically changes the security model of httpd.</p>
+
+ <p>As traversing a filesystem hierarchy to examine potential
+ <code>.htaccess</code> files would be a very expensive operation,
+ partially defeating the point of caching (to speed up requests),
+ <module>mod_cache</module> makes no decision about whether a cached
+ entity is authorised for serving. In other words; if
+ <module>mod_cache</module> has cached some content, it will be served
+ from the cache as long as that content has not expired.</p>
+
+ <p>If, for example, your configuration permits access to a resource
by IP
+ address you should ensure that this content is not cached. You can
do this
+ by using the <directive module="mod_cache">CacheDisable</directive>
+ directive, or <module>mod_expires</module>. Left unchecked,
+ <module>mod_cache</module> - very much like a reverse proxy - would
cache
+ the content when served and then serve it to any client, on any IP
+ address.</p>
+ </section>
+
+ <section>
+ <title>Local exploits</title>
+
+ <p>As requests to end-users can be served from the cache, the cache
+ itself can become a target for those wishing to deface or interfere
with
+ content. It is important to bear in mind that the cache must at all
+ times be writable by the user which httpd is running as. This is in
+ stark contrast to the usually recommended situation of maintaining
+ all content unwritable by the Apache user.</p>
+
+ <p>If the Apache user is compromised, for example through a flaw in
+ a CGI process, it is possible that the cache may be targeted. When
+ using <module>mod_cache_disk</module>, it is relatively easy to
+ insert or modify a cached entity.</p>
+
+ <p>This presents a somewhat elevated risk in comparison to the other
+ types of attack it is possible to make as the Apache user. If you are
+ using <module>mod_cache_disk</module> you should bear this in mind -
+ ensure you upgrade httpd when security upgrades are announced and
+ run CGI processes as a non-Apache user using <a
+ href="suexec.html">suEXEC</a> if possible.</p>
+
+ </section>
+
+ <section>
+ <title>Cache Poisoning</title>
+
+ <p>When running httpd as a caching proxy server, there is also the
+ potential for so-called cache poisoning. Cache Poisoning is a broad
+ term for attacks in which an attacker causes the proxy server to
+ retrieve incorrect (and usually undesirable) content from the
backend.
+ </p>
+
+ <p>For example if the DNS servers used by your system running
+ httpd
+ are vulnerable to DNS cache poisoning, an attacker may be able to
control
+ where httpd connects to when requesting content from the origin
server.
+ Another example is so-called HTTP request-smuggling attacks.</p>
+
+ <p>This document is not the correct place for an in-depth discussion
+ of HTTP request smuggling (instead, try your favourite search engine)
+ however it is important to be aware that it is possible to make
+ a series of requests, and to exploit a vulnerability on an origin
+ webserver such that the attacker can entirely control the content
+ retrieved by the proxy.</p>
+ </section>
+ </section>
+
+ <section id="filehandle">
+ <title>File-Handle Caching</title>
+
+ <related>
+ <modulelist>
+ <module>mod_file_cache</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_file_cache">CacheFile</directive>
+ </directivelist>
+ </related>
+
+ <p>The act of opening a file can itself be a source of delay,
particularly
+ on network filesystems. By maintaining a cache of open file descriptors
+ for commonly served files, httpd can avoid this delay. Currently
+ httpd
+ provides one implementation of File-Handle Caching.</p>
+
+ <section>
+ <title>CacheFile</title>
+
+ <p>The most basic form of caching present in httpd is the file-handle
+ caching provided by <module>mod_file_cache</module>. Rather than
caching
+ file-contents, this cache maintains a table of open file
descriptors. Files
+ to be cached in this manner are specified in the configuration file
using
+ the <directive module="mod_file_cache">CacheFile</directive>
+ directive.</p>
+
+ <p>The
+ <directive module="mod_file_cache">CacheFile</directive> directive
+ instructs httpd to open the file when it is started and to re-use
+ this file-handle for all subsequent access to this file.</p>
+
+ <example>
+ CacheFile /usr/local/apache2/htdocs/index.html
+ </example>
+
+ <p>If you intend to cache a large number of files in this manner, you
+ must ensure that your operating system's limit for the number of open
+ files is set appropriately.</p>
+
+ <p>Although using <directive
module="mod_file_cache">CacheFile</directive>
+ does not cause the file-contents to be cached per-se, it does mean
+ that if the file changes while httpd is running these changes will
+ not be picked up. The file will be consistently served as it was
+ when httpd was started.</p>
+
+ <p>If the file is removed while httpd is running, it will continue
+ to maintain an open file descriptor and serve the file as it was when
+ httpd was started. This usually also means that although the file
+ will have been deleted, and not show up on the filesystem, extra free
+ space will not be recovered until httpd is stopped and the file
+ descriptor closed.</p>
+ </section>
+
+ </section>
+
+ <section id="inmemory">
+ <title>In-Memory Caching</title>
+
+ <related>
+ <modulelist>
+ <module>mod_file_cache</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_cache">CacheEnable</directive>
+ <directive module="mod_cache">CacheDisable</directive>
+ <directive module="mod_file_cache">MMapFile</directive>
+ </directivelist>
+ </related>
+
+ <p>Serving directly from system memory is universally the fastest
method
+ of serving content. Reading files from a disk controller or, even
worse,
+ from a remote network is orders of magnitude slower. Disk controllers
+ usually involve physical processes, and network access is limited by
+ your available bandwidth. Memory access on the other hand can take mere
+ nano-seconds.</p>
+
+ <p>System memory isn't cheap though, byte for byte it's by far the most
+ expensive type of storage and it's important to ensure that it is used
+ efficiently. By caching files in memory you decrease the amount of
+ memory available on the system. As we'll see, in the case of operating
+ system caching, this is not so much of an issue, but when using
+ httpd's own in-memory caching it is important to make sure that you
+ do not allocate too much memory to a cache. Otherwise the system
+ will be forced to swap out memory, which will likely degrade
+ performance.</p>
+
+ <section>
+ <title>Operating System Caching</title>
+
+ <p>Almost all modern operating systems cache file-data in memory
managed
+ directly by the kernel. This is a powerful feature, and for the most
+ part operating systems get it right. For example, on Linux, let's
look at
+ the difference in the time it takes to read a file for the first time
+ and the second time;</p>
+
+ <example><pre>
+colm@coroebus:~$ time cat testfile > /dev/null
+real 0m0.065s
+user 0m0.000s
+sys 0m0.001s
+colm@coroebus:~$ time cat testfile > /dev/null
+real 0m0.003s
+user 0m0.003s
+sys 0m0.000s</pre>
+ </example>
+
+ <p>Even for this small file, there is a huge difference in the amount
+ of time it takes to read the file. This is because the kernel has
cached
+ the file contents in memory.</p>
+
+ <p>By ensuring there is "spare" memory on your system, you can ensure
+ that more and more file-contents will be stored in this cache. This
+ can be a very efficient means of in-memory caching, and involves no
+ extra configuration of httpd at all.</p>
+
+ <p>Additionally, because the operating system knows when files are
+ deleted or modified, it can automatically remove file contents from
the
+ cache when necessary. This is a big advantage over httpd's in-memory
+ caching which has no way of knowing when a file has changed.</p>
+ </section>
+
+ <p>Despite the performance and advantages of automatic operating system
+ caching there are some circumstances in which in-memory caching may be
+ better performed by httpd.</p>
+
+ <section>
+ <title>MMapFile Caching</title>
+
+ <p><module>mod_file_cache</module> provides the
+ <directive module="mod_file_cache">MMapFile</directive> directive,
which
+ allows you to have httpd map a static file's contents into memory at
+ start time (using the mmap system call). httpd will use the in-memory
+ contents for all subsequent accesses to this file.</p>
+
+ <example>
+ MMapFile /usr/local/apache2/htdocs/index.html
+ </example>
+
+ <p>As with the
+ <directive module="mod_file_cache">CacheFile</directive> directive,
any
+ changes in these files will not be picked up by httpd after it has
+ started.</p>
+
+ <p> The <directive module="mod_file_cache">MMapFile</directive>
+ directive does not keep track of how much memory it allocates, so
+ you must ensure not to over-use the directive. Each httpd child
+ process will replicate this memory, so it is critically important
+ to ensure that the files mapped are not so large as to cause the
+ system to swap memory.</p>
+ </section>
+ </section>
+
+ <section id="disk">
+ <title>Disk-based Caching</title>
+
+ <related>
+ <modulelist>
+ <module>mod_cache_disk</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_cache">CacheEnable</directive>
+ <directive module="mod_cache">CacheDisable</directive>
+ </directivelist>
+ </related>
+
+ <p><module>mod_cache_disk</module> provides a disk-based caching
mechanism
+ for <module>mod_cache</module>. This cache is intelligent and content
will
+ be served from the cache only as long as it is considered valid.</p>
+
+ <p>Typically the module will be configured as so;</p>
+
+ <example>
+CacheRoot /var/cache/apache/<br />
+CacheEnable disk /<br />
+CacheDirLevels 2<br />
+CacheDirLength 1
+ </example>
+
+ <p>Importantly, as the cached files are locally stored, operating
system
+ in-memory caching will typically be applied to their access also. So
+ although the files are stored on disk, if they are frequently accessed
+ it is likely the operating system will ensure that they are actually
+ served from memory.</p>
+
+ <section>
+ <title>Understanding the Cache-Store</title>
+
+ <p>To store items in the cache, <module>mod_cache_disk</module>
creates
+ a 22 character hash of the URL being requested. This hash
incorporates
+ the hostname, protocol, port, path and any CGI arguments to the URL,
+ to ensure that multiple URLs do not collide.</p>
+
+ <p>Each character may be any one of 64-different characters, which
mean
+ that overall there are 64^22 possible hashes. For example, a URL
might
+ be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used
+ as a prefix for the naming of the files specific to that URL within
+ the cache, however first it is split up into directories as per
+ the <directive module="mod_cache_disk">CacheDirLevels</directive> and
+ <directive module="mod_cache_disk">CacheDirLength</directive>
+ directives.</p>
+
+ <p><directive module="mod_cache_disk">CacheDirLevels</directive>
+ specifies how many levels of subdirectory there should be, and
+ <directive module="mod_cache_disk">CacheDirLength</directive>
+ specifies how many characters should be in each directory. With
+ the example settings given above, the hash would be turned into
+ a filename prefix as
+ <code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p>
+
+ <p>The overall aim of this technique is to reduce the number of
+ subdirectories or files that may be in a particular directory,
+ as most file-systems slow down as this number increases. With
+ setting of "1" for
+ <directive module="mod_cache_disk">CacheDirLength</directive>
+ there can at most be 64 subdirectories at any particular level.
+ With a setting of 2 there can be 64 * 64 subdirectories, and so on.
+ Unless you have a good reason not to, using a setting of "1"
+ for <directive module="mod_cache_disk">CacheDirLength</directive>
+ is recommended.</p>
+
+ <p>Setting
+ <directive module="mod_cache_disk">CacheDirLevels</directive>
+ depends on how many files you anticipate to store in the cache.
+ With the setting of "2" used in the above example, a grand
+ total of 4096 subdirectories can ultimately be created. With
+ 1 million files cached, this works out at roughly 245 cached
+ URLs per directory.</p>
+
+ <p>Each URL uses at least two files in the cache-store. Typically
+ there is a ".header" file, which includes meta-information about
+ the URL, such as when it is due to expire and a ".data" file
+ which is a verbatim copy of the content to be served.</p>
+
+ <p>In the case of a content negotiated via the "Vary" header, a
+ ".vary" directory will be created for the URL in question. This
+ directory will have multiple ".data" files corresponding to the
+ differently negotiated content.</p>
+ </section>
+
+ <section>
+ <title>Maintaining the Disk Cache</title>
+
+ <p>Although <module>mod_cache_disk</module> will remove cached
content
+ as it is expired, it does not maintain any information on the total
+ size of the cache or how little free space may be left.</p>
+
+ <p>Instead, provided with httpd is the <a
+ href="programs/htcacheclean.html">htcacheclean</a> tool which, as
the name
+ suggests, allows you to clean the cache periodically. Determining
+ how frequently to run <a
+ href="programs/htcacheclean.html">htcacheclean</a> and what target
size to
+ use for the cache is somewhat complex and trial and error may be
needed to
+ select optimal values.</p>
+
+ <p><a href="programs/htcacheclean.html">htcacheclean</a> has two
modes of
+ operation. It can be run as persistent daemon, or periodically from
+ cron. <a
+ href="programs/htcacheclean.html">htcacheclean</a> can take up to an
hour
+ or more to process very large (tens of gigabytes) caches and if you
are
+ running it from cron it is recommended that you determine how long a
typical
+ run takes, to avoid running more than one instance at a time.</p>
+
+ <p class="figure">
+ <img src="images/caching_fig1.gif" alt="" width="600"
+ height="406" /><br />
+ <a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical
+ cache growth / clean sequence.</p>
+
+ <p>Because <module>mod_cache_disk</module> does not itself pay
attention
+ to how much space is used you should ensure that
+ <a href="programs/htcacheclean.html">htcacheclean</a> is configured
to
+ leave enough "grow room" following a clean.</p>
+ </section>
+
+ </section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/caching.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="caching.xml">
+ <basename>caching</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">tr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/configuring.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,227 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="configuring.xml.meta">
+
+ <title>Configuration Files</title>
+
+<summary>
+<p>This document describes the files used to configure Apache HTTP
+Server.</p>
+</summary>
+
+ <section id="main">
+ <title>Main Configuration Files</title>
+ <related>
+ <modulelist>
+ <module>mod_mime</module>
+ </modulelist>
+ <directivelist>
+ <directive module="core" type="section">IfDefine</directive>
+ <directive module="core">Include</directive>
+ <directive module="mod_mime">TypesConfig</directive>
+ </directivelist>
+ </related>
+
+ <p>Apache HTTP Server is configured by placing <a
+ href="mod/directives.html">directives</a> in plain text
+ configuration files. The main configuration file is usually called
+ <code>httpd.conf</code>. The location of this file is set at
+ compile-time, but may be overridden with the <code>-f</code>
+ command line flag. In addition, other configuration files may be
+ added using the <directive module="core">Include</directive>
+ directive, and wildcards can be used to include many configuration
+ files. Any directive may be placed in any of these configuration
+ files. Changes to the main configuration files are only
+ recognized by httpd when it is started or restarted.</p>
+
+ <p>The server also reads a file containing mime document types;
+ the filename is set by the <directive
+ module="mod_mime">TypesConfig</directive> directive,
+ and is <code>mime.types</code> by default.</p>
+ </section>
+
+ <section id="syntax">
+ <title>Syntax of the Configuration Files</title>
+
+ <p>httpd configuration files contain one directive per line.
+ The backslash "\" may be used as the last character on a line
+ to indicate that the directive continues onto the next line.
+ There must be no other characters or white space between the
+ backslash and the end of the line.</p>
+
+ <p>Directives in the configuration files are case-insensitive,
+ but arguments to directives are often case sensitive. Lines
+ that begin with the hash character "#" are considered
+ comments, and are ignored. Comments may <strong>not</strong> be
+ included on a line after a configuration directive. Blank lines
+ and white space occurring before a directive are ignored, so
+ you may indent directives for clarity.</p>
+
+ <p>The values of variables defined with the <directive
+ module="core">Define</directive> of or shell environment variables can
+ be used in configuration file lines using the syntax
<code>${VAR}</code>.
+ If "VAR" is the name of a valid variable, the value of that variable is
+ substituted into that spot in the configuration file line, and
processing
+ continues as if that text were found directly in the configuration
file.
+ Variables defined with <directive module="core">Define</directive> take
+ precedence over shell environment variables.
+ If the "VAR" variable is not found, the characters <code>${VAR}</code>
+ are left unchanged, and a warning is logged.
+ Variable names may not contain colon ":" characters, to avoid clashes
with
+ <directive module="mod_rewrite">RewriteMap</directive>'s syntax.</p>
+
+ <p>Only shell environment variables defined before the server is
started
+ can be used in expansions. Environment variables defined in the
+ configuration file itself, for example with <directive
+ module="mod_env">SetEnv</directive>, take effect too late to be used
for
+ expansions in the configuration file.</p>
+
+ <p>The maximum length of a line in the configuration file, after
+ variable substitution, joining any continued lines and removing leading
+ and trailing white space, is 8192 characters.</p>
+
+ <p>You can check your configuration files for syntax errors
+ without starting the server by using <code>apachectl
+ configtest</code> or the <code>-t</code> command line
+ option.</p>
+ </section>
+
+ <section id="modules">
+ <title>Modules</title>
+
+ <related>
+ <modulelist>
+ <module>mod_so</module>
+ </modulelist>
+ <directivelist>
+ <directive module="core" type="section">IfModule</directive>
+ <directive module="mod_so">LoadModule</directive>
+ </directivelist>
+ </related>
+
+ <p>httpd is a modular server. This implies that only the most
+ basic functionality is included in the core server. Extended
+ features are available through <a
+ href="mod/">modules</a> which can be loaded
+ into httpd. By default, a <a
+ href="mod/module-dict.html#Status">base</a> set of modules is
+ included in the server at compile-time. If the server is
+ compiled to use <a href="dso.html">dynamically loaded</a>
+ modules, then modules can be compiled separately and added at
+ any time using the <directive module="mod_so">LoadModule</directive>
+ directive.
+ Otherwise, httpd must be recompiled to add or remove modules.
+ Configuration directives may be included conditional on a
+ presence of a particular module by enclosing them in an <directive
+ module="core" type="section">IfModule</directive> block. However,
+ <directive type="section">IfModule</directive> blocks are not
+ required, and in some cases may mask the fact that you're missing an
+ important module.</p>
+
+ <p>To see which modules are currently compiled into the server,
+ you can use the <code>-l</code> command line option. You can also
+ see what modules are loaded dynamically using the <code>-M</code>
+ command line option.</p>
+ </section>
+
+ <section id="scope">
+ <title>Scope of Directives</title>
+
+ <related>
+ <directivelist>
+ <directive module="core" type="section">Directory</directive>
+ <directive module="core" type="section">DirectoryMatch</directive>
+ <directive module="core" type="section">Files</directive>
+ <directive module="core" type="section">FilesMatch</directive>
+ <directive module="core" type="section">Location</directive>
+ <directive module="core" type="section">LocationMatch</directive>
+ <directive module="core" type="section">VirtualHost</directive>
+ </directivelist>
+ </related>
+
+ <p>Directives placed in the main configuration files apply to
+ the entire server. If you wish to change the configuration for
+ only a part of the server, you can scope your directives by
+ placing them in <directive module="core"
+ type="section">Directory</directive>, <directive module="core"
+ type="section">DirectoryMatch</directive>, <directive module="core"
+ type="section">Files</directive>, <directive module="core"
+ type="section">FilesMatch</directive>, <directive module="core"
+ type="section">Location</directive>, and <directive module="core"
+ type="section">LocationMatch</directive>
+ sections. These sections limit the application of the
+ directives which they enclose to particular filesystem
+ locations or URLs. They can also be nested, allowing for very
+ fine grained configuration.</p>
+
+ <p>httpd has the capability to serve many different websites
+ simultaneously. This is called <a href="vhosts/">Virtual
+ Hosting</a>. Directives can also be scoped by placing them
+ inside <directive module="core" type="section">VirtualHost</directive>
+ sections, so that they will only apply to requests for a
+ particular website.</p>
+
+ <p>Although most directives can be placed in any of these
+ sections, some directives do not make sense in some contexts.
+ For example, directives controlling process creation can only
+ be placed in the main server context. To find which directives
+ can be placed in which sections, check the <a
+ href="mod/directive-dict.html#Context">Context</a> of the
+ directive. For further information, we provide details on <a
+ href="sections.html">How Directory, Location and Files sections
+ work</a>.</p>
+ </section>
+
+ <section id="htaccess">
+ <title>.htaccess Files</title>
+
+ <related>
+ <directivelist>
+ <directive module="core">AccessFileName</directive>
+ <directive module="core">AllowOverride</directive>
+ </directivelist>
+ </related>
+
+ <p>httpd allows for decentralized management of configuration
+ via special files placed inside the web tree. The special files
+ are usually called <code>.htaccess</code>, but any name can be
+ specified in the <directive module="core">AccessFileName</directive>
+ directive. Directives placed in <code>.htaccess</code> files
+ apply to the directory where you place the file, and all
+ sub-directories. The <code>.htaccess</code> files follow the
+ same syntax as the main configuration files. Since
+ <code>.htaccess</code> files are read on every request, changes
+ made in these files take immediate effect.</p>
+
+ <p>To find which directives can be placed in
+ <code>.htaccess</code> files, check the <a
+ href="mod/directive-dict.html#Context">Context</a> of the
+ directive. The server administrator further controls what
+ directives may be placed in <code>.htaccess</code> files by
+ configuring the <directive module="core">AllowOverride</directive>
+ directive in the main configuration files.</p>
+
+ <p>For more information on <code>.htaccess</code> files, see
+ the <a href="howto/htaccess.html">.htaccess tutorial</a>.</p>
+ </section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/configuring.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="configuring.xml">
+ <basename>configuring</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant outdated="yes">de</variant>
+ <variant>en</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">ja</variant>
+ <variant outdated="yes">ko</variant>
+ <variant outdated="yes">tr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/content-negotiation.xml Sat Feb 26 23:20:49
2011
@@ -0,0 +1,668 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="content-negotiation.xml.meta">
+
+<title>Content Negotiation</title>
+
+<summary>
+
+ <p>Apache HTTPD supports content negotiation as described in
+ the HTTP/1.1 specification. It can choose the best
+ representation of a resource based on the browser-supplied
+ preferences for media type, languages, character set and
+ encoding. It also implements a couple of features to give
+ more intelligent handling of requests from browsers that send
+ incomplete negotiation information.</p>
+
+ <p>Content negotiation is provided by the
+ <module>mod_negotiation</module> module, which is compiled in
+ by default.</p>
+</summary>
+
+<section id="about"><title>About Content Negotiation</title>
+
+ <p>A resource may be available in several different
+ representations. For example, it might be available in
+ different languages or different media types, or a combination.
+ One way of selecting the most appropriate choice is to give the
+ user an index page, and let them select. However it is often
+ possible for the server to choose automatically. This works
+ because browsers can send, as part of each request, information
+ about what representations they prefer. For example, a browser
+ could indicate that it would like to see information in French,
+ if possible, else English will do. Browsers indicate their
+ preferences by headers in the request. To request only French
+ representations, the browser would send</p>
+
+<example>Accept-Language: fr</example>
+
+ <p>Note that this preference will only be applied when there is
+ a choice of representations and they vary by language.</p>
+
+ <p>As an example of a more complex request, this browser has
+ been configured to accept French and English, but prefer
+ French, and to accept various media types, preferring HTML over
+ plain text or other text types, and preferring GIF or JPEG over
+ other media types, but also allowing any other media type as a
+ last resort:</p>
+
+<example>
+ Accept-Language: fr; q=1.0, en; q=0.5<br />
+ Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg;
q=0.6, image/*; q=0.5, */*; q=0.1
+</example>
+
+ <p>httpd supports 'server driven' content negotiation, as
+ defined in the HTTP/1.1 specification. It fully supports the
+ <code>Accept</code>, <code>Accept-Language</code>,
+ <code>Accept-Charset</code> and<code>Accept-Encoding</code>
+ request headers. httpd also supports 'transparent'
+ content negotiation, which is an experimental negotiation
+ protocol defined in RFC 2295 and RFC 2296. It does not offer
+ support for 'feature negotiation' as defined in these RFCs.</p>
+
+ <p>A <strong>resource</strong> is a conceptual entity
+ identified by a URI (RFC 2396). An HTTP server like Apache HTTP Server
+ provides access to <strong>representations</strong> of the
+ resource(s) within its namespace, with each representation in
+ the form of a sequence of bytes with a defined media type,
+ character set, encoding, etc. Each resource may be associated
+ with zero, one, or more than one representation at any given
+ time. If multiple representations are available, the resource
+ is referred to as <strong>negotiable</strong> and each of its
+ representations is termed a <strong>variant</strong>. The ways
+ in which the variants for a negotiable resource vary are called
+ the <strong>dimensions</strong> of negotiation.</p>
+</section>
+
+<section id="negotiation"><title>Negotiation in httpd</title>
+
+ <p>In order to negotiate a resource, the server needs to be
+ given information about each of the variants. This is done in
+ one of two ways:</p>
+
+ <ul>
+ <li>Using a type map (<em>i.e.</em>, a <code>*.var</code>
+ file) which names the files containing the variants
+ explicitly, or</li>
+
+ <li>Using a 'MultiViews' search, where the server does an
+ implicit filename pattern match and chooses from among the
+ results.</li>
+ </ul>
+
+ <section id="type-map"><title>Using a type-map file</title>
+
+ <p>A type map is a document which is associated with the handler
+ named <code>type-map</code> (or, for backwards-compatibility with
+ older httpd configurations, the <glossary>MIME-type</glossary>
+ <code>application/x-type-map</code>). Note that to use this
+ feature, you must have a handler set in the configuration that
+ defines a file suffix as <code>type-map</code>; this is best done
+ with</p>
+
+<example>AddHandler type-map .var</example>
+
+ <p>in the server configuration file.</p>
+
+ <p>Type map files should have the same name as the resource
+ which they are describing, and have an entry for each available
+ variant; these entries consist of contiguous HTTP-format header
+ lines. Entries for different variants are separated by blank
+ lines. Blank lines are illegal within an entry. It is
+ conventional to begin a map file with an entry for the combined
+ entity as a whole (although this is not required, and if
+ present will be ignored). An example map file is shown below.
+ This file would be named <code>foo.var</code>, as it describes
+ a resource named <code>foo</code>.</p>
+
+<example>
+ URI: foo<br />
+<br />
+ URI: foo.en.html<br />
+ Content-type: text/html<br />
+ Content-language: en<br />
+<br />
+ URI: foo.fr.de.html<br />
+ Content-type: text/html;charset=iso-8859-2<br />
+ Content-language: fr, de<br />
+</example>
+ <p>Note also that a typemap file will take precedence over the
+ filename's extension, even when Multiviews is on. If the
+ variants have different source qualities, that may be indicated
+ by the "qs" parameter to the media type, as in this picture
+ (available as JPEG, GIF, or ASCII-art): </p>
+
+<example>
+ URI: foo<br />
+<br />
+ URI: foo.jpeg<br />
+ Content-type: image/jpeg; qs=0.8<br />
+<br />
+ URI: foo.gif<br />
+ Content-type: image/gif; qs=0.5<br />
+<br />
+ URI: foo.txt<br />
+ Content-type: text/plain; qs=0.01<br />
+</example>
+
+ <p>qs values can vary in the range 0.000 to 1.000. Note that
+ any variant with a qs value of 0.000 will never be chosen.
+ Variants with no 'qs' parameter value are given a qs factor of
+ 1.0. The qs parameter indicates the relative 'quality' of this
+ variant compared to the other available variants, independent
+ of the client's capabilities. For example, a JPEG file is
+ usually of higher source quality than an ASCII file if it is
+ attempting to represent a photograph. However, if the resource
+ being represented is an original ASCII art, then an ASCII
+ representation would have a higher source quality than a JPEG
+ representation. A qs value is therefore specific to a given
+ variant depending on the nature of the resource it
+ represents.</p>
+
+ <p>The full list of headers recognized is available in the <a
+ href="mod/mod_negotiation.html#typemaps">mod_negotiation
+ typemap</a> documentation.</p>
+</section>
+
+<section id="multiviews"><title>Multiviews</title>
+
+ <p><code>MultiViews</code> is a per-directory option, meaning it
+ can be set with an <directive module="core">Options</directive>
+ directive within a <directive module="core"
+ type="section">Directory</directive>, <directive module="core"
+ type="section">Location</directive> or <directive module="core"
+ type="section">Files</directive> section in
+ <code>httpd.conf</code>, or (if <directive
+ module="core">AllowOverride</directive> is properly set) in
+ <code>.htaccess</code> files. Note that <code>Options All</code>
+ does not set <code>MultiViews</code>; you have to ask for it by
+ name.</p>
+
+ <p>The effect of <code>MultiViews</code> is as follows: if the
+ server receives a request for <code>/some/dir/foo</code>, if
+ <code>/some/dir</code> has <code>MultiViews</code> enabled, and
+ <code>/some/dir/foo</code> does <em>not</em> exist, then the
+ server reads the directory looking for files named foo.*, and
+ effectively fakes up a type map which names all those files,
+ assigning them the same media types and content-encodings it
+ would have if the client had asked for one of them by name. It
+ then chooses the best match to the client's requirements.</p>
+
+ <p><code>MultiViews</code> may also apply to searches for the file
+ named by the <directive
+ module="mod_dir">DirectoryIndex</directive> directive, if the
+ server is trying to index a directory. If the configuration files
+ specify</p>
+<example>DirectoryIndex index</example>
+ <p>then the server will arbitrate between <code>index.html</code>
+ and <code>index.html3</code> if both are present. If neither
+ are present, and <code>index.cgi</code> is there, the server
+ will run it.</p>
+
+ <p>If one of the files found when reading the directory does not
+ have an extension recognized by <code>mod_mime</code> to designate
+ its Charset, Content-Type, Language, or Encoding, then the result
+ depends on the setting of the <directive
+ module="mod_mime">MultiViewsMatch</directive> directive. This
+ directive determines whether handlers, filters, and other
+ extension types can participate in MultiViews negotiation.</p>
+</section>
+</section>
+
+<section id="methods"><title>The Negotiation Methods</title>
+
+ <p>After httpd has obtained a list of the variants for a given
+ resource, either from a type-map file or from the filenames in
+ the directory, it invokes one of two methods to decide on the
+ 'best' variant to return, if any. It is not necessary to know
+ any of the details of how negotiation actually takes place in
+ order to use httpd's content negotiation features. However the
+ rest of this document explains the methods used for those
+ interested. </p>
+
+ <p>There are two negotiation methods:</p>
+
+ <ol>
+ <li><strong>Server driven negotiation with the httpd
+ algorithm</strong> is used in the normal case. The httpd
+ algorithm is explained in more detail below. When this
+ algorithm is used, httpd can sometimes 'fiddle' the quality
+ factor of a particular dimension to achieve a better result.
+ The ways httpd can fiddle quality factors is explained in
+ more detail below.</li>
+
+ <li><strong>Transparent content negotiation</strong> is used
+ when the browser specifically requests this through the
+ mechanism defined in RFC 2295. This negotiation method gives
+ the browser full control over deciding on the 'best' variant,
+ the result is therefore dependent on the specific algorithms
+ used by the browser. As part of the transparent negotiation
+ process, the browser can ask httpd to run the 'remote
+ variant selection algorithm' defined in RFC 2296.</li>
+ </ol>
+
+<section id="dimensions"><title>Dimensions of Negotiation</title>
+
+ <table>
+ <columnspec><column width=".15"/><column width=".85"/></columnspec>
+ <tr valign="top">
+ <th>Dimension</th>
+
+ <th>Notes</th>
+ </tr>
+
+ <tr valign="top">
+ <td>Media Type</td>
+
+ <td>Browser indicates preferences with the <code>Accept</code>
+ header field. Each item can have an associated quality factor.
+ Variant description can also have a quality factor (the "qs"
+ parameter).</td>
+ </tr>
+
+ <tr valign="top">
+ <td>Language</td>
+
+ <td>Browser indicates preferences with the
+ <code>Accept-Language</code> header field. Each item can have
+ a quality factor. Variants can be associated with none, one or
+ more than one language.</td>
+ </tr>
+
+ <tr valign="top">
+ <td>Encoding</td>
+
+ <td>Browser indicates preference with the
+ <code>Accept-Encoding</code> header field. Each item can have
+ a quality factor.</td>
+ </tr>
+
+ <tr valign="top">
+ <td>Charset</td>
+
+ <td>Browser indicates preference with the
+ <code>Accept-Charset</code> header field. Each item can have a
+ quality factor. Variants can indicate a charset as a parameter
+ of the media type.</td>
+ </tr>
+ </table>
+</section>
+
+<section id="algorithm"><title>httpd Negotiation Algorithm</title>
+
+ <p>httpd can use the following algorithm to select the 'best'
+ variant (if any) to return to the browser. This algorithm is
+ not further configurable. It operates as follows:</p>
+
+ <ol>
+ <li>First, for each dimension of the negotiation, check the
+ appropriate <em>Accept*</em> header field and assign a
+ quality to each variant. If the <em>Accept*</em> header for
+ any dimension implies that this variant is not acceptable,
+ eliminate it. If no variants remain, go to step 4.</li>
+
+ <li>
+ Select the 'best' variant by a process of elimination. Each
+ of the following tests is applied in order. Any variants
+ not selected at each test are eliminated. After each test,
+ if only one variant remains, select it as the best match
+ and proceed to step 3. If more than one variant remains,
+ move on to the next test.
+
+ <ol>
+ <li>Multiply the quality factor from the <code>Accept</code>
+ header with the quality-of-source factor for this variants
+ media type, and select the variants with the highest
+ value.</li>
+
+ <li>Select the variants with the highest language quality
+ factor.</li>
+
+ <li>Select the variants with the best language match,
+ using either the order of languages in the
+ <code>Accept-Language</code> header (if present), or else
+ the order of languages in the <code>LanguagePriority</code>
+ directive (if present).</li>
+
+ <li>Select the variants with the highest 'level' media
+ parameter (used to give the version of text/html media
+ types).</li>
+
+ <li>Select variants with the best charset media
+ parameters, as given on the <code>Accept-Charset</code>
+ header line. Charset ISO-8859-1 is acceptable unless
+ explicitly excluded. Variants with a <code>text/*</code>
+ media type but not explicitly associated with a particular
+ charset are assumed to be in ISO-8859-1.</li>
+
+ <li>Select those variants which have associated charset
+ media parameters that are <em>not</em> ISO-8859-1. If
+ there are no such variants, select all variants
+ instead.</li>
+
+ <li>Select the variants with the best encoding. If there
+ are variants with an encoding that is acceptable to the
+ user-agent, select only these variants. Otherwise if
+ there is a mix of encoded and non-encoded variants,
+ select only the unencoded variants. If either all
+ variants are encoded or all variants are not encoded,
+ select all variants.</li>
+
+ <li>Select the variants with the smallest content
+ length.</li>
+
+ <li>Select the first variant of those remaining. This
+ will be either the first listed in the type-map file, or
+ when variants are read from the directory, the one whose
+ file name comes first when sorted using ASCII code
+ order.</li>
+ </ol>
+ </li>
+
+ <li>The algorithm has now selected one 'best' variant, so
+ return it as the response. The HTTP response header
+ <code>Vary</code> is set to indicate the dimensions of
+ negotiation (browsers and caches can use this information when
+ caching the resource). End.</li>
+
+ <li>To get here means no variant was selected (because none
+ are acceptable to the browser). Return a 406 status (meaning
+ "No acceptable representation") with a response body
+ consisting of an HTML document listing the available
+ variants. Also set the HTTP <code>Vary</code> header to
+ indicate the dimensions of variance.</li>
+ </ol>
+</section>
+</section>
+
+<section id="better"><title>Fiddling with Quality
+ Values</title>
+
+ <p>httpd sometimes changes the quality values from what would
+ be expected by a strict interpretation of the httpd
+ negotiation algorithm above. This is to get a better result
+ from the algorithm for browsers which do not send full or
+ accurate information. Some of the most popular browsers send
+ <code>Accept</code> header information which would otherwise
+ result in the selection of the wrong variant in many cases. If a
+ browser sends full and correct information these fiddles will not
+ be applied.</p>
+
+<section id="wildcards"><title>Media Types and Wildcards</title>
+
+ <p>The <code>Accept:</code> request header indicates preferences
+ for media types. It can also include 'wildcard' media types, such
+ as "image/*" or "*/*" where the * matches any string. So a request
+ including:</p>
+
+<example>Accept: image/*, */*</example>
+
+ <p>would indicate that any type starting "image/" is acceptable,
+ as is any other type.
+ Some browsers routinely send wildcards in addition to explicit
+ types they can handle. For example:</p>
+
+<example>
+ Accept: text/html, text/plain, image/gif, image/jpeg, */*
+</example>
+ <p>The intention of this is to indicate that the explicitly listed
+ types are preferred, but if a different representation is
+ available, that is ok too. Using explicit quality values,
+ what the browser really wants is something like:</p>
+<example>
+ Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
+</example>
+ <p>The explicit types have no quality factor, so they default to a
+ preference of 1.0 (the highest). The wildcard */* is given a
+ low preference of 0.01, so other types will only be returned if
+ no variant matches an explicitly listed type.</p>
+
+ <p>If the <code>Accept:</code> header contains <em>no</em> q
+ factors at all, httpd sets the q value of "*/*", if present, to
+ 0.01 to emulate the desired behavior. It also sets the q value of
+ wildcards of the format "type/*" to 0.02 (so these are preferred
+ over matches against "*/*". If any media type on the
+ <code>Accept:</code> header contains a q factor, these special
+ values are <em>not</em> applied, so requests from browsers which
+ send the explicit information to start with work as expected.</p>
+</section>
+
+<section id="exceptions"><title>Language Negotiation Exceptions</title>
+
+ <p>New in httpd 2.0, some exceptions have been added to the
+ negotiation algorithm to allow graceful fallback when language
+ negotiation fails to find a match.</p>
+
+ <p>When a client requests a page on your server, but the server
+ cannot find a single page that matches the
+ <code>Accept-language</code> sent by
+ the browser, the server will return either a "No Acceptable
+ Variant" or "Multiple Choices" response to the client. To avoid
+ these error messages, it is possible to configure httpd to ignore
+ the <code>Accept-language</code> in these cases and provide a
+ document that does not explicitly match the client's request. The
+ <directive
+ module="mod_negotiation">ForceLanguagePriority</directive>
+ directive can be used to override one or both of these error
+ messages and substitute the servers judgement in the form of the
+ <directive module="mod_negotiation">LanguagePriority</directive>
+ directive.</p>
+
+ <p>The server will also attempt to match language-subsets when no
+ other match can be found. For example, if a client requests
+ documents with the language <code>en-GB</code> for British
+ English, the server is not normally allowed by the HTTP/1.1
+ standard to match that against a document that is marked as simply
+ <code>en</code>. (Note that it is almost surely a configuration
+ error to include <code>en-GB</code> and not <code>en</code> in the
+ <code>Accept-Language</code> header, since it is very unlikely
+ that a reader understands British English, but doesn't understand
+ English in general. Unfortunately, many current clients have
+ default configurations that resemble this.) However, if no other
+ language match is possible and the server is about to return a "No
+ Acceptable Variants" error or fallback to the <directive
+ module="mod_negotiation">LanguagePriority</directive>, the server
+ will ignore the subset specification and match <code>en-GB</code>
+ against <code>en</code> documents. Implicitly, httpd will add
+ the parent language to the client's acceptable language list with
+ a very low quality value. But note that if the client requests
+ "en-GB; q=0.9, fr; q=0.8", and the server has documents
+ designated "en" and "fr", then the "fr" document will be returned.
+ This is necessary to maintain compliance with the HTTP/1.1
+ specification and to work effectively with properly configured
+ clients.</p>
+
+ <p>In order to support advanced techniques (such as cookies or
+ special URL-paths) to determine the user's preferred language,
+ since httpd 2.0.47 <module>mod_negotiation</module> recognizes
+ the <a href="env.html">environment variable</a>
+ <code>prefer-language</code>. If it exists and contains an
+ appropriate language tag, <module>mod_negotiation</module> will
+ try to select a matching variant. If there's no such variant,
+ the normal negotiation process applies.</p>
+
+ <example><title>Example</title>
+ SetEnvIf Cookie "language=(.+)" prefer-language=$1<br />
+ Header append Vary cookie
+ </example>
+</section>
+</section>
+
+<section id="extensions"><title>Extensions to Transparent Content
+Negotiation</title>
+
+<p>httpd extends the transparent content negotiation protocol (RFC
+2295) as follows. A new <code>{encoding ..}</code> element is used in
+variant lists to label variants which are available with a specific
+content-encoding only. The implementation of the RVSA/1.0 algorithm
+(RFC 2296) is extended to recognize encoded variants in the list, and
+to use them as candidate variants whenever their encodings are
+acceptable according to the <code>Accept-Encoding</code> request
+header. The RVSA/1.0 implementation does not round computed quality
+factors to 5 decimal places before choosing the best variant.</p>
+</section>
+
+<section id="naming"><title>Note on hyperlinks and naming
conventions</title>
+
+ <p>If you are using language negotiation you can choose between
+ different naming conventions, because files can have more than
+ one extension, and the order of the extensions is normally
+ irrelevant (see the <a
+ href="mod/mod_mime.html#multipleext">mod_mime</a> documentation
+ for details).</p>
+
+ <p>A typical file has a MIME-type extension (<em>e.g.</em>,
+ <code>html</code>), maybe an encoding extension (<em>e.g.</em>,
+ <code>gz</code>), and of course a language extension
+ (<em>e.g.</em>, <code>en</code>) when we have different
+ language variants of this file.</p>
+
+ <p>Examples:</p>
+
+ <ul>
+ <li>foo.en.html</li>
+
+ <li>foo.html.en</li>
+
+ <li>foo.en.html.gz</li>
+ </ul>
+
+ <p>Here some more examples of filenames together with valid and
+ invalid hyperlinks:</p>
+
+ <table border="1" cellpadding="8" cellspacing="0">
+ <columnspec><column width=".2"/><column width=".2"/>
+ <column width=".2"/></columnspec>
+ <tr>
+ <th>Filename</th>
+
+ <th>Valid hyperlink</th>
+
+ <th>Invalid hyperlink</th>
+ </tr>
+
+ <tr>
+ <td><em>foo.html.en</em></td>
+
+ <td>foo<br />
+ foo.html</td>
+
+ <td>-</td>
+ </tr>
+
+ <tr>
+ <td><em>foo.en.html</em></td>
+
+ <td>foo</td>
+
+ <td>foo.html</td>
+ </tr>
+
+ <tr>
+ <td><em>foo.html.en.gz</em></td>
+
+ <td>foo<br />
+ foo.html</td>
+
+ <td>foo.gz<br />
+ foo.html.gz</td>
+ </tr>
+
+ <tr>
+ <td><em>foo.en.html.gz</em></td>
+
+ <td>foo</td>
+
+ <td>foo.html<br />
+ foo.html.gz<br />
+ foo.gz</td>
+ </tr>
+
+ <tr>
+ <td><em>foo.gz.html.en</em></td>
+
+ <td>foo<br />
+ foo.gz<br />
+ foo.gz.html</td>
+
+ <td>foo.html</td>
+ </tr>
+
+ <tr>
+ <td><em>foo.html.gz.en</em></td>
+
+ <td>foo<br />
+ foo.html<br />
+ foo.html.gz</td>
+
+ <td>foo.gz</td>
+ </tr>
+ </table>
+
+ <p>Looking at the table above, you will notice that it is always
+ possible to use the name without any extensions in a hyperlink
+ (<em>e.g.</em>, <code>foo</code>). The advantage is that you
+ can hide the actual type of a document rsp. file and can change
+ it later, <em>e.g.</em>, from <code>html</code> to
+ <code>shtml</code> or <code>cgi</code> without changing any
+ hyperlink references.</p>
+
+ <p>If you want to continue to use a MIME-type in your
+ hyperlinks (<em>e.g.</em> <code>foo.html</code>) the language
+ extension (including an encoding extension if there is one)
+ must be on the right hand side of the MIME-type extension
+ (<em>e.g.</em>, <code>foo.html.en</code>).</p>
+</section>
+
+<section id="caching"><title>Note on Caching</title>
+
+ <p>When a cache stores a representation, it associates it with
+ the request URL. The next time that URL is requested, the cache
+ can use the stored representation. But, if the resource is
+ negotiable at the server, this might result in only the first
+ requested variant being cached and subsequent cache hits might
+ return the wrong response. To prevent this, httpd normally
+ marks all responses that are returned after content negotiation
+ as non-cacheable by HTTP/1.0 clients. httpd also supports the
+ HTTP/1.1 protocol features to allow caching of negotiated
+ responses.</p>
+
+ <p>For requests which come from a HTTP/1.0 compliant client
+ (either a browser or a cache), the directive <directive
+ module="mod_negotiation">CacheNegotiatedDocs</directive> can be
+ used to allow caching of responses which were subject to
+ negotiation. This directive can be given in the server config or
+ virtual host, and takes no arguments. It has no effect on requests
+ from HTTP/1.1 clients.</p>
+
+ <p>For HTTP/1.1 clients, httpd sends a <code>Vary</code> HTTP
+ response header to indicate the negotiation dimensions for the
+ response. Caches can use this information to determine whether a
+ subsequent request can be served from the local copy. To
+ encourage a cache to use the local copy regardless of the
+ negotiation dimensions, set the <code>force-no-vary</code> <a
+ href="env.html#special">environment variable</a>.</p>
+
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/content-negotiation.xml.meta Sat Feb 26
23:20:49 2011
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="content-negotiation.xml">
+ <basename>content-negotiation</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant outdated="yes">ja</variant>
+ <variant outdated="yes">ko</variant>
+ <variant outdated="yes">tr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/convenience.map Sat Feb 26 23:20:49 2011
@@ -0,0 +1,524 @@
+# Mapping from directive names to URLs
+# GENERATED FROM XML -- DO NOT EDIT
+# You may use it as follows:
+# RewriteEngine On
+# RewriteMap dir2url txt:/path/to/convenience.map
+# RewriteCond ${dir2url:$1} (.+)
+# RewriteRule ^/+([^/]+)$ /manual/%1 [R=301,NE,L]
+
+acceptfilter mod/core.html#acceptfilter
+acceptpathinfo mod/core.html#acceptpathinfo
+accessfilename mod/core.html#accessfilename
+action mod/mod_actions.html#action
+addalt mod/mod_autoindex.html#addalt
+addaltbyencoding mod/mod_autoindex.html#addaltbyencoding
+addaltbytype mod/mod_autoindex.html#addaltbytype
+addcharset mod/mod_mime.html#addcharset
+adddefaultcharset mod/core.html#adddefaultcharset
+adddescription mod/mod_autoindex.html#adddescription
+addencoding mod/mod_mime.html#addencoding
+addhandler mod/mod_mime.html#addhandler
+addicon mod/mod_autoindex.html#addicon
+addiconbyencoding mod/mod_autoindex.html#addiconbyencoding
+addiconbytype mod/mod_autoindex.html#addiconbytype
+addinputfilter mod/mod_mime.html#addinputfilter
+addlanguage mod/mod_mime.html#addlanguage
+addmoduleinfo mod/mod_info.html#addmoduleinfo
+addoutputfilter mod/mod_mime.html#addoutputfilter
+addoutputfilterbytype mod/mod_filter.html#addoutputfilterbytype
+addtype mod/mod_mime.html#addtype
+alias mod/mod_alias.html#alias
+aliasmatch mod/mod_alias.html#aliasmatch
+allow mod/mod_access_compat.html#allow
+allowconnect mod/mod_proxy_connect.html#allowconnect
+allowencodedslashes mod/core.html#allowencodedslashes
+allowmethods mod/mod_allowmethods.html#allowmethods
+allowoverride mod/core.html#allowoverride
+anonymous mod/mod_authn_anon.html#anonymous
+anonymous_logemail mod/mod_authn_anon.html#anonymous_logemail
+anonymous_mustgiveemail mod/mod_authn_anon.html#anonymous_mustgiveemail
+anonymous_nouserid mod/mod_authn_anon.html#anonymous_nouserid
+anonymous_verifyemail mod/mod_authn_anon.html#anonymous_verifyemail
+authbasicauthoritative mod/mod_auth_basic.html#authbasicauthoritative
+authbasicprovider mod/mod_auth_basic.html#authbasicprovider
+authdbduserpwquery mod/mod_authn_dbd.html#authdbduserpwquery
+authdbduserrealmquery mod/mod_authn_dbd.html#authdbduserrealmquery
+authdbmgroupfile mod/mod_authz_dbm.html#authdbmgroupfile
+authdbmtype mod/mod_authn_dbm.html#authdbmtype
+authdbmuserfile mod/mod_authn_dbm.html#authdbmuserfile
+authdigestalgorithm mod/mod_auth_digest.html#authdigestalgorithm
+authdigestdomain mod/mod_auth_digest.html#authdigestdomain
+authdigestnccheck mod/mod_auth_digest.html#authdigestnccheck
+authdigestnonceformat mod/mod_auth_digest.html#authdigestnonceformat
+authdigestnoncelifetime mod/mod_auth_digest.html#authdigestnoncelifetime
+authdigestprovider mod/mod_auth_digest.html#authdigestprovider
+authdigestqop mod/mod_auth_digest.html#authdigestqop
+authdigestshmemsize mod/mod_auth_digest.html#authdigestshmemsize
+authformauthoritative mod/mod_auth_form.html#authformauthoritative
+authformbody mod/mod_auth_form.html#authformbody
+authformdisablenostore mod/mod_auth_form.html#authformdisablenostore
+authformfakebasicauth mod/mod_auth_form.html#authformfakebasicauth
+authformlocation mod/mod_auth_form.html#authformlocation
+authformloginrequiredlocation
mod/mod_auth_form.html#authformloginrequiredlocation
+authformloginsuccesslocation
mod/mod_auth_form.html#authformloginsuccesslocation
+authformlogoutlocation mod/mod_auth_form.html#authformlogoutlocation
+authformmethod mod/mod_auth_form.html#authformmethod
+authformmimetype mod/mod_auth_form.html#authformmimetype
+authformpassword mod/mod_auth_form.html#authformpassword
+authformprovider mod/mod_auth_form.html#authformprovider
+authformsitepassphrase mod/mod_auth_form.html#authformsitepassphrase
+authformsize mod/mod_auth_form.html#authformsize
+authformusername mod/mod_auth_form.html#authformusername
+authgroupfile mod/mod_authz_groupfile.html#authgroupfile
+authldapauthorizeprefix mod/mod_authnz_ldap.html#authldapauthorizeprefix
+authldapbindauthoritative
mod/mod_authnz_ldap.html#authldapbindauthoritative
+authldapbinddn mod/mod_authnz_ldap.html#authldapbinddn
+authldapbindpassword mod/mod_authnz_ldap.html#authldapbindpassword
+authldapcharsetconfig mod/mod_authnz_ldap.html#authldapcharsetconfig
+authldapcompareasuser mod/mod_authnz_ldap.html#authldapcompareasuser
+authldapcomparednonserver
mod/mod_authnz_ldap.html#authldapcomparednonserver
+authldapdereferencealiases
mod/mod_authnz_ldap.html#authldapdereferencealiases
+authldapgroupattribute mod/mod_authnz_ldap.html#authldapgroupattribute
+authldapgroupattributeisdn
mod/mod_authnz_ldap.html#authldapgroupattributeisdn
+authldapinitialbindasuser
mod/mod_authnz_ldap.html#authldapinitialbindasuser
+authldapinitialbindpattern
mod/mod_authnz_ldap.html#authldapinitialbindpattern
+authldapmaxsubgroupdepth mod/mod_authnz_ldap.html#authldapmaxsubgroupdepth
+authldapremoteuserattribute
mod/mod_authnz_ldap.html#authldapremoteuserattribute
+authldapremoteuserisdn mod/mod_authnz_ldap.html#authldapremoteuserisdn
+authldapsearchasuser mod/mod_authnz_ldap.html#authldapsearchasuser
+authldapsubgroupattribute
mod/mod_authnz_ldap.html#authldapsubgroupattribute
+authldapsubgroupclass mod/mod_authnz_ldap.html#authldapsubgroupclass
+authldapurl mod/mod_authnz_ldap.html#authldapurl
+authmerging mod/mod_authz_core.html#authmerging
+authname mod/mod_authn_core.html#authname
+authncachecontext mod/mod_authn_socache.html#authncachecontext
+authncacheprovidefor mod/mod_authn_socache.html#authncacheprovidefor
+authncachesocache mod/mod_authn_socache.html#authncachesocache
+authncachetimeout mod/mod_authn_socache.html#authncachetimeout
+authnprovideralias mod/mod_authn_core.html#authnprovideralias
+authtype mod/mod_authn_core.html#authtype
+authuserfile mod/mod_authn_file.html#authuserfile
+authzdbdlogintoreferer mod/mod_authz_dbd.html#authzdbdlogintoreferer
+authzdbdquery mod/mod_authz_dbd.html#authzdbdquery
+authzdbdredirectquery mod/mod_authz_dbd.html#authzdbdredirectquery
+authzdbmtype mod/mod_authz_dbm.html#authzdbmtype
+authzprovideralias mod/mod_authz_core.html#authzprovideralias
+authzsendforbiddenonfailure
mod/mod_authz_core.html#authzsendforbiddenonfailure
+balancermember mod/mod_proxy.html#balancermember
+browsermatch mod/mod_setenvif.html#browsermatch
+browsermatchnocase mod/mod_setenvif.html#browsermatchnocase
+bufferedlogs mod/mod_log_config.html#bufferedlogs
+buffersize mod/mod_buffer.html#buffersize
+cachedefaultexpire mod/mod_cache.html#cachedefaultexpire
+cachedetailheader mod/mod_cache.html#cachedetailheader
+cachedirlength mod/mod_cache_disk.html#cachedirlength
+cachedirlevels mod/mod_cache_disk.html#cachedirlevels
+cachedisable mod/mod_cache.html#cachedisable
+cacheenable mod/mod_cache.html#cacheenable
+cachefile mod/mod_file_cache.html#cachefile
+cacheheader mod/mod_cache.html#cacheheader
+cacheignorecachecontrol mod/mod_cache.html#cacheignorecachecontrol
+cacheignoreheaders mod/mod_cache.html#cacheignoreheaders
+cacheignorenolastmod mod/mod_cache.html#cacheignorenolastmod
+cacheignorequerystring mod/mod_cache.html#cacheignorequerystring
+cacheignoreurlsessionidentifiers
mod/mod_cache.html#cacheignoreurlsessionidentifiers
+cachekeybaseurl mod/mod_cache.html#cachekeybaseurl
+cachelastmodifiedfactor mod/mod_cache.html#cachelastmodifiedfactor
+cachelock mod/mod_cache.html#cachelock
+cachelockmaxage mod/mod_cache.html#cachelockmaxage
+cachelockpath mod/mod_cache.html#cachelockpath
+cachemaxexpire mod/mod_cache.html#cachemaxexpire
+cachemaxfilesize mod/mod_cache_disk.html#cachemaxfilesize
+cacheminexpire mod/mod_cache.html#cacheminexpire
+cacheminfilesize mod/mod_cache_disk.html#cacheminfilesize
+cachenegotiateddocs mod/mod_negotiation.html#cachenegotiateddocs
+cachequickhandler mod/mod_cache.html#cachequickhandler
+cachereadsize mod/mod_cache_disk.html#cachereadsize
+cachereadtime mod/mod_cache_disk.html#cachereadtime
+cacheroot mod/mod_cache_disk.html#cacheroot
+cachestaleonerror mod/mod_cache.html#cachestaleonerror
+cachestoreexpired mod/mod_cache.html#cachestoreexpired
+cachestorenostore mod/mod_cache.html#cachestorenostore
+cachestoreprivate mod/mod_cache.html#cachestoreprivate
+cgimapextension mod/core.html#cgimapextension
+charsetdefault mod/mod_charset_lite.html#charsetdefault
+charsetoptions mod/mod_charset_lite.html#charsetoptions
+charsetsourceenc mod/mod_charset_lite.html#charsetsourceenc
+checkcaseonly mod/mod_speling.html#checkcaseonly
+checkspelling mod/mod_speling.html#checkspelling
+chrootdir mod/mod_unixd.html#chrootdir
+contentdigest mod/core.html#contentdigest
+cookiedomain mod/mod_usertrack.html#cookiedomain
+cookieexpires mod/mod_usertrack.html#cookieexpires
+cookielog mod/mod_log_config.html#cookielog
+cookiename mod/mod_usertrack.html#cookiename
+cookiestyle mod/mod_usertrack.html#cookiestyle
+cookietracking mod/mod_usertrack.html#cookietracking
+coredumpdirectory mod/mpm_common.html#coredumpdirectory
+customlog mod/mod_log_config.html#customlog
+dav mod/mod_dav.html#dav
+davdepthinfinity mod/mod_dav.html#davdepthinfinity
+davgenericlockdb mod/mod_dav_lock.html#davgenericlockdb
+davlockdb mod/mod_dav_fs.html#davlockdb
+davmintimeout mod/mod_dav.html#davmintimeout
+dbdexptime mod/mod_dbd.html#dbdexptime
+dbdkeep mod/mod_dbd.html#dbdkeep
+dbdmax mod/mod_dbd.html#dbdmax
+dbdmin mod/mod_dbd.html#dbdmin
+dbdparams mod/mod_dbd.html#dbdparams
+dbdpersist mod/mod_dbd.html#dbdpersist
+dbdpreparesql mod/mod_dbd.html#dbdpreparesql
+dbdriver mod/mod_dbd.html#dbdriver
+defaulticon mod/mod_autoindex.html#defaulticon
+defaultlanguage mod/mod_mime.html#defaultlanguage
+defaulttype mod/core.html#defaulttype
+define mod/core.html#define
+deflatebuffersize mod/mod_deflate.html#deflatebuffersize
+deflatecompressionlevel mod/mod_deflate.html#deflatecompressionlevel
+deflatefilternote mod/mod_deflate.html#deflatefilternote
+deflatememlevel mod/mod_deflate.html#deflatememlevel
+deflatewindowsize mod/mod_deflate.html#deflatewindowsize
+deny mod/mod_access_compat.html#deny
+directory mod/core.html#directory
+directoryindex mod/mod_dir.html#directoryindex
+directorymatch mod/core.html#directorymatch
+directoryslash mod/mod_dir.html#directoryslash
+documentroot mod/core.html#documentroot
+dtraceprivileges mod/mod_privileges.html#dtraceprivileges
+dumpioinput mod/mod_dumpio.html#dumpioinput
+dumpiooutput mod/mod_dumpio.html#dumpiooutput
+enableexceptionhook mod/mpm_common.html#enableexceptionhook
+enablemmap mod/core.html#enablemmap
+enablesendfile mod/core.html#enablesendfile
+error mod/core.html#error
+errordocument mod/core.html#errordocument
+errorlog mod/core.html#errorlog
+errorlogformat mod/core.html#errorlogformat
+example mod/mod_example.html#example
+expiresactive mod/mod_expires.html#expiresactive
+expiresbytype mod/mod_expires.html#expiresbytype
+expiresdefault mod/mod_expires.html#expiresdefault
+extendedstatus mod/core.html#extendedstatus
+extfilterdefine mod/mod_ext_filter.html#extfilterdefine
+extfilteroptions mod/mod_ext_filter.html#extfilteroptions
+fallbackresource mod/mod_dir.html#fallbackresource
+fileetag mod/core.html#fileetag
+files mod/core.html#files
+filesmatch mod/core.html#filesmatch
+filterchain mod/mod_filter.html#filterchain
+filterdeclare mod/mod_filter.html#filterdeclare
+filterprotocol mod/mod_filter.html#filterprotocol
+filterprovider mod/mod_filter.html#filterprovider
+filtertrace mod/mod_filter.html#filtertrace
+forcelanguagepriority mod/mod_negotiation.html#forcelanguagepriority
+forcetype mod/core.html#forcetype
+forensiclog mod/mod_log_forensic.html#forensiclog
+gprofdir mod/core.html#gprofdir
+gracefulshutdowntimeout mod/mpm_common.html#gracefulshutdowntimeout
+group mod/mod_unixd.html#group
+header mod/mod_headers.html#header
+headername mod/mod_autoindex.html#headername
+heartbeataddress mod/mod_heartbeat.html#heartbeataddress
+heartbeatlisten mod/mod_heartmonitor.html#heartbeatlisten
+heartbeatstorage mod/mod_lbmethod_heartbeat.html#heartbeatstorage
+heartbeatstorage mod/mod_heartmonitor.html#heartbeatstorage
+hostnamelookups mod/core.html#hostnamelookups
+identitycheck mod/mod_ident.html#identitycheck
+identitychecktimeout mod/mod_ident.html#identitychecktimeout
+if mod/core.html#if
+ifdefine mod/core.html#ifdefine
+ifmodule mod/core.html#ifmodule
+ifversion mod/mod_version.html#ifversion
+imapbase mod/mod_imagemap.html#imapbase
+imapdefault mod/mod_imagemap.html#imapdefault
+imapmenu mod/mod_imagemap.html#imapmenu
+include mod/core.html#include
+indexheadinsert mod/mod_autoindex.html#indexheadinsert
+indexignore mod/mod_autoindex.html#indexignore
+indexignorereset mod/mod_autoindex.html#indexignorereset
+indexoptions mod/mod_autoindex.html#indexoptions
+indexorderdefault mod/mod_autoindex.html#indexorderdefault
+indexstylesheet mod/mod_autoindex.html#indexstylesheet
+inputsed mod/mod_sed.html#inputsed
+isapiappendlogtoerrors mod/mod_isapi.html#isapiappendlogtoerrors
+isapiappendlogtoquery mod/mod_isapi.html#isapiappendlogtoquery
+isapicachefile mod/mod_isapi.html#isapicachefile
+isapifakeasync mod/mod_isapi.html#isapifakeasync
+isapilognotsupported mod/mod_isapi.html#isapilognotsupported
+isapireadaheadbuffer mod/mod_isapi.html#isapireadaheadbuffer
+keepalive mod/core.html#keepalive
+keepalivetimeout mod/core.html#keepalivetimeout
+keptbodysize mod/mod_request.html#keptbodysize
+languagepriority mod/mod_negotiation.html#languagepriority
+ldapcacheentries mod/mod_ldap.html#ldapcacheentries
+ldapcachettl mod/mod_ldap.html#ldapcachettl
+ldapconnectiontimeout mod/mod_ldap.html#ldapconnectiontimeout
+ldaplibrarydebug mod/mod_ldap.html#ldaplibrarydebug
+ldapopcacheentries mod/mod_ldap.html#ldapopcacheentries
+ldapopcachettl mod/mod_ldap.html#ldapopcachettl
+ldapreferralhoplimit mod/mod_ldap.html#ldapreferralhoplimit
+ldapreferrals mod/mod_ldap.html#ldapreferrals
+ldapsharedcachefile mod/mod_ldap.html#ldapsharedcachefile
+ldapsharedcachesize mod/mod_ldap.html#ldapsharedcachesize
+ldaptimeout mod/mod_ldap.html#ldaptimeout
+ldaptrustedclientcert mod/mod_ldap.html#ldaptrustedclientcert
+ldaptrustedglobalcert mod/mod_ldap.html#ldaptrustedglobalcert
+ldaptrustedmode mod/mod_ldap.html#ldaptrustedmode
+ldapverifyservercert mod/mod_ldap.html#ldapverifyservercert
+limit mod/core.html#limit
+limitexcept mod/core.html#limitexcept
+limitinternalrecursion mod/core.html#limitinternalrecursion
+limitrequestbody mod/core.html#limitrequestbody
+limitrequestfields mod/core.html#limitrequestfields
+limitrequestfieldsize mod/core.html#limitrequestfieldsize
+limitrequestline mod/core.html#limitrequestline
+limitxmlrequestbody mod/core.html#limitxmlrequestbody
+listen mod/mpm_common.html#listen
+listenbacklog mod/mpm_common.html#listenbacklog
+loadfile mod/mod_so.html#loadfile
+loadmodule mod/mod_so.html#loadmodule
+location mod/core.html#location
+locationmatch mod/core.html#locationmatch
+logformat mod/mod_log_config.html#logformat
+loglevel mod/core.html#loglevel
+luacodecache mod/mod_lua.html#luacodecache
+luahookaccesschecker mod/mod_lua.html#luahookaccesschecker
+luahookauthchecker mod/mod_lua.html#luahookauthchecker
+luahookcheckuserid mod/mod_lua.html#luahookcheckuserid
+luahookfixups mod/mod_lua.html#luahookfixups
+luahookinsertfilter mod/mod_lua.html#luahookinsertfilter
+luahookmaptostorage mod/mod_lua.html#luahookmaptostorage
+luahooktranslatename mod/mod_lua.html#luahooktranslatename
+luahooktypechecker mod/mod_lua.html#luahooktypechecker
+luamaphandler mod/mod_lua.html#luamaphandler
+luapackagecpath mod/mod_lua.html#luapackagecpath
+luapackagepath mod/mod_lua.html#luapackagepath
+luaquickhandler mod/mod_lua.html#luaquickhandler
+luaroot mod/mod_lua.html#luaroot
+luascope mod/mod_lua.html#luascope
+maxclients mod/mpm_common.html#maxclients
+maxconnectionsperchild mod/mpm_common.html#maxconnectionsperchild
+maxkeepaliverequests mod/core.html#maxkeepaliverequests
+maxmemfree mod/mpm_common.html#maxmemfree
+maxspareservers mod/prefork.html#maxspareservers
+maxsparethreads mod/mpm_common.html#maxsparethreads
+maxthreads mod/mpm_netware.html#maxthreads
+metadir mod/mod_cern_meta.html#metadir
+metafiles mod/mod_cern_meta.html#metafiles
+metasuffix mod/mod_cern_meta.html#metasuffix
+mimemagicfile mod/mod_mime_magic.html#mimemagicfile
+minspareservers mod/prefork.html#minspareservers
+minsparethreads mod/mpm_common.html#minsparethreads
+mmapfile mod/mod_file_cache.html#mmapfile
+modemstandard mod/mod_dialup.html#modemstandard
+modmimeusepathinfo mod/mod_mime.html#modmimeusepathinfo
+multiviewsmatch mod/mod_mime.html#multiviewsmatch
+mutex mod/core.html#mutex
+namevirtualhost mod/core.html#namevirtualhost
+noproxy mod/mod_proxy.html#noproxy
+nwssltrustedcerts mod/mod_nw_ssl.html#nwssltrustedcerts
+nwsslupgradeable mod/mod_nw_ssl.html#nwsslupgradeable
+options mod/core.html#options
+order mod/mod_access_compat.html#order
+outputsed mod/mod_sed.html#outputsed
+passenv mod/mod_env.html#passenv
+pidfile mod/mpm_common.html#pidfile
+privilegesmode mod/mod_privileges.html#privilegesmode
+protocol mod/core.html#protocol
+protocolecho mod/mod_echo.html#protocolecho
+proxy mod/mod_proxy.html#proxy
+proxyaddheaders mod/mod_proxy.html#proxyaddheaders
+proxybadheader mod/mod_proxy.html#proxybadheader
+proxyblock mod/mod_proxy.html#proxyblock
+proxydomain mod/mod_proxy.html#proxydomain
+proxyerroroverride mod/mod_proxy.html#proxyerroroverride
+proxyftpdircharset mod/mod_proxy_ftp.html#proxyftpdircharset
+proxyftpescapewildcards mod/mod_proxy_ftp.html#proxyftpescapewildcards
+proxyftplistonwildcard mod/mod_proxy_ftp.html#proxyftplistonwildcard
+proxyiobuffersize mod/mod_proxy.html#proxyiobuffersize
+proxymatch mod/mod_proxy.html#proxymatch
+proxymaxforwards mod/mod_proxy.html#proxymaxforwards
+proxypass mod/mod_proxy.html#proxypass
+proxypassinterpolateenv mod/mod_proxy.html#proxypassinterpolateenv
+proxypassmatch mod/mod_proxy.html#proxypassmatch
+proxypassreverse mod/mod_proxy.html#proxypassreverse
+proxypassreversecookiedomain
mod/mod_proxy.html#proxypassreversecookiedomain
+proxypassreversecookiepath mod/mod_proxy.html#proxypassreversecookiepath
+proxypreservehost mod/mod_proxy.html#proxypreservehost
+proxyreceivebuffersize mod/mod_proxy.html#proxyreceivebuffersize
+proxyremote mod/mod_proxy.html#proxyremote
+proxyremotematch mod/mod_proxy.html#proxyremotematch
+proxyrequests mod/mod_proxy.html#proxyrequests
+proxyscgiinternalredirect mod/mod_proxy_scgi.html#proxyscgiinternalredirect
+proxyscgisendfile mod/mod_proxy_scgi.html#proxyscgisendfile
+proxyset mod/mod_proxy.html#proxyset
+proxystatus mod/mod_proxy.html#proxystatus
+proxytimeout mod/mod_proxy.html#proxytimeout
+proxyvia mod/mod_proxy.html#proxyvia
+readmename mod/mod_autoindex.html#readmename
+receivebuffersize mod/mpm_common.html#receivebuffersize
+redirect mod/mod_alias.html#redirect
+redirectmatch mod/mod_alias.html#redirectmatch
+redirectpermanent mod/mod_alias.html#redirectpermanent
+redirecttemp mod/mod_alias.html#redirecttemp
+reflectorheader mod/mod_reflector.html#reflectorheader
+remoteipheader mod/mod_remoteip.html#remoteipheader
+remoteipinternalproxy mod/mod_remoteip.html#remoteipinternalproxy
+remoteipinternalproxylist mod/mod_remoteip.html#remoteipinternalproxylist
+remoteipproxiesheader mod/mod_remoteip.html#remoteipproxiesheader
+remoteiptrustedproxy mod/mod_remoteip.html#remoteiptrustedproxy
+remoteiptrustedproxylist mod/mod_remoteip.html#remoteiptrustedproxylist
+removecharset mod/mod_mime.html#removecharset
+removeencoding mod/mod_mime.html#removeencoding
+removehandler mod/mod_mime.html#removehandler
+removeinputfilter mod/mod_mime.html#removeinputfilter
+removelanguage mod/mod_mime.html#removelanguage
+removeoutputfilter mod/mod_mime.html#removeoutputfilter
+removetype mod/mod_mime.html#removetype
+requestheader mod/mod_headers.html#requestheader
+requestreadtimeout mod/mod_reqtimeout.html#requestreadtimeout
+require mod/mod_authz_core.html#require
+requireall mod/mod_authz_core.html#requireall
+requireany mod/mod_authz_core.html#requireany
+requirenone mod/mod_authz_core.html#requirenone
+rewritebase mod/mod_rewrite.html#rewritebase
+rewritecond mod/mod_rewrite.html#rewritecond
+rewriteengine mod/mod_rewrite.html#rewriteengine
+rewritemap mod/mod_rewrite.html#rewritemap
+rewriteoptions mod/mod_rewrite.html#rewriteoptions
+rewriterule mod/mod_rewrite.html#rewriterule
+rlimitcpu mod/core.html#rlimitcpu
+rlimitmem mod/core.html#rlimitmem
+rlimitnproc mod/core.html#rlimitnproc
+satisfy mod/mod_access_compat.html#satisfy
+scoreboardfile mod/mpm_common.html#scoreboardfile
+script mod/mod_actions.html#script
+scriptalias mod/mod_alias.html#scriptalias
+scriptaliasmatch mod/mod_alias.html#scriptaliasmatch
+scriptinterpretersource mod/core.html#scriptinterpretersource
+scriptlog mod/mod_cgi.html#scriptlog
+scriptlogbuffer mod/mod_cgi.html#scriptlogbuffer
+scriptloglength mod/mod_cgi.html#scriptloglength
+scriptsock mod/mod_cgid.html#scriptsock
+securelisten mod/mod_nw_ssl.html#securelisten
+seerequesttail mod/core.html#seerequesttail
+sendbuffersize mod/mpm_common.html#sendbuffersize
+serveradmin mod/core.html#serveradmin
+serveralias mod/core.html#serveralias
+serverlimit mod/mpm_common.html#serverlimit
+servername mod/core.html#servername
+serverpath mod/core.html#serverpath
+serverroot mod/core.html#serverroot
+serversignature mod/core.html#serversignature
+servertokens mod/core.html#servertokens
+session mod/mod_session.html#session
+sessioncookiename mod/mod_session_cookie.html#sessioncookiename
+sessioncookiename2 mod/mod_session_cookie.html#sessioncookiename2
+sessioncookieremove mod/mod_session_cookie.html#sessioncookieremove
+sessioncryptodriver mod/mod_session_crypto.html#sessioncryptodriver
+sessioncryptopassphrase mod/mod_session_crypto.html#sessioncryptopassphrase
+sessiondbdcookiename mod/mod_session_dbd.html#sessiondbdcookiename
+sessiondbdcookiename2 mod/mod_session_dbd.html#sessiondbdcookiename2
+sessiondbdcookieremove mod/mod_session_dbd.html#sessiondbdcookieremove
+sessiondbddeletelabel mod/mod_session_dbd.html#sessiondbddeletelabel
+sessiondbdinsertlabel mod/mod_session_dbd.html#sessiondbdinsertlabel
+sessiondbdperuser mod/mod_session_dbd.html#sessiondbdperuser
+sessiondbdselectlabel mod/mod_session_dbd.html#sessiondbdselectlabel
+sessiondbdupdatelabel mod/mod_session_dbd.html#sessiondbdupdatelabel
+sessionenv mod/mod_session.html#sessionenv
+sessionexclude mod/mod_session.html#sessionexclude
+sessionheader mod/mod_session.html#sessionheader
+sessioninclude mod/mod_session.html#sessioninclude
+sessionmaxage mod/mod_session.html#sessionmaxage
+setenv mod/mod_env.html#setenv
+setenvif mod/mod_setenvif.html#setenvif
+setenvifexpr mod/mod_setenvif.html#setenvifexpr
+setenvifnocase mod/mod_setenvif.html#setenvifnocase
+sethandler mod/core.html#sethandler
+setinputfilter mod/core.html#setinputfilter
+setoutputfilter mod/core.html#setoutputfilter
+ssiaccessenable mod/mod_include.html#ssiaccessenable
+ssiendtag mod/mod_include.html#ssiendtag
+ssierrormsg mod/mod_include.html#ssierrormsg
+ssietag mod/mod_include.html#ssietag
+ssilastmodified mod/mod_include.html#ssilastmodified
+ssistarttag mod/mod_include.html#ssistarttag
+ssitimeformat mod/mod_include.html#ssitimeformat
+ssiundefinedecho mod/mod_include.html#ssiundefinedecho
+sslcacertificatefile mod/mod_ssl.html#sslcacertificatefile
+sslcacertificatepath mod/mod_ssl.html#sslcacertificatepath
+sslcadnrequestfile mod/mod_ssl.html#sslcadnrequestfile
+sslcadnrequestpath mod/mod_ssl.html#sslcadnrequestpath
+sslcarevocationfile mod/mod_ssl.html#sslcarevocationfile
+sslcarevocationpath mod/mod_ssl.html#sslcarevocationpath
+sslcertificatechainfile mod/mod_ssl.html#sslcertificatechainfile
+sslcertificatefile mod/mod_ssl.html#sslcertificatefile
+sslcertificatekeyfile mod/mod_ssl.html#sslcertificatekeyfile
+sslciphersuite mod/mod_ssl.html#sslciphersuite
+sslcryptodevice mod/mod_ssl.html#sslcryptodevice
+sslengine mod/mod_ssl.html#sslengine
+sslfips mod/mod_ssl.html#sslfips
+sslhonorcipherorder mod/mod_ssl.html#sslhonorcipherorder
+sslinsecurerenegotiation mod/mod_ssl.html#sslinsecurerenegotiation
+sslocspdefaultresponder mod/mod_ssl.html#sslocspdefaultresponder
+sslocspenable mod/mod_ssl.html#sslocspenable
+sslocspoverrideresponder mod/mod_ssl.html#sslocspoverrideresponder
+sslocsprespondertimeout mod/mod_ssl.html#sslocsprespondertimeout
+sslocspresponsemaxage mod/mod_ssl.html#sslocspresponsemaxage
+sslocspresponsetimeskew mod/mod_ssl.html#sslocspresponsetimeskew
+ssloptions mod/mod_ssl.html#ssloptions
+sslpassphrasedialog mod/mod_ssl.html#sslpassphrasedialog
+sslprotocol mod/mod_ssl.html#sslprotocol
+sslproxycacertificatefile mod/mod_ssl.html#sslproxycacertificatefile
+sslproxycacertificatepath mod/mod_ssl.html#sslproxycacertificatepath
+sslproxycarevocationfile mod/mod_ssl.html#sslproxycarevocationfile
+sslproxycarevocationpath mod/mod_ssl.html#sslproxycarevocationpath
+sslproxycheckpeercn mod/mod_ssl.html#sslproxycheckpeercn
+sslproxycheckpeerexpire mod/mod_ssl.html#sslproxycheckpeerexpire
+sslproxyciphersuite mod/mod_ssl.html#sslproxyciphersuite
+sslproxyengine mod/mod_ssl.html#sslproxyengine
+sslproxymachinecertificatefile
mod/mod_ssl.html#sslproxymachinecertificatefile
+sslproxymachinecertificatepath
mod/mod_ssl.html#sslproxymachinecertificatepath
+sslproxyprotocol mod/mod_ssl.html#sslproxyprotocol
+sslproxyverify mod/mod_ssl.html#sslproxyverify
+sslproxyverifydepth mod/mod_ssl.html#sslproxyverifydepth
+sslrandomseed mod/mod_ssl.html#sslrandomseed
+sslrenegbuffersize mod/mod_ssl.html#sslrenegbuffersize
+sslrequire mod/mod_ssl.html#sslrequire
+sslrequiressl mod/mod_ssl.html#sslrequiressl
+sslsessioncache mod/mod_ssl.html#sslsessioncache
+sslsessioncachetimeout mod/mod_ssl.html#sslsessioncachetimeout
+sslstrictsnivhostcheck mod/mod_ssl.html#sslstrictsnivhostcheck
+sslusername mod/mod_ssl.html#sslusername
+sslverifyclient mod/mod_ssl.html#sslverifyclient
+sslverifydepth mod/mod_ssl.html#sslverifydepth
+startservers mod/mpm_common.html#startservers
+startthreads mod/mpm_common.html#startthreads
+substitute mod/mod_substitute.html#substitute
+suexec mod/mod_unixd.html#suexec
+suexecusergroup mod/mod_suexec.html#suexecusergroup
+threadlimit mod/mpm_common.html#threadlimit
+threadsperchild mod/mpm_common.html#threadsperchild
+threadstacksize mod/mpm_common.html#threadstacksize
+timeout mod/core.html#timeout
+traceenable mod/core.html#traceenable
+transferlog mod/mod_log_config.html#transferlog
+typesconfig mod/mod_mime.html#typesconfig
+undefine mod/core.html#undefine
+unsetenv mod/mod_env.html#unsetenv
+usecanonicalname mod/core.html#usecanonicalname
+usecanonicalphysicalport mod/core.html#usecanonicalphysicalport
+user mod/mod_unixd.html#user
+userdir mod/mod_userdir.html#userdir
+vhostcgimode mod/mod_privileges.html#vhostcgimode
+vhostcgiprivs mod/mod_privileges.html#vhostcgiprivs
+vhostgroup mod/mod_privileges.html#vhostgroup
+vhostprivs mod/mod_privileges.html#vhostprivs
+vhostsecure mod/mod_privileges.html#vhostsecure
+vhostuser mod/mod_privileges.html#vhostuser
+virtualdocumentroot mod/mod_vhost_alias.html#virtualdocumentroot
+virtualdocumentrootip mod/mod_vhost_alias.html#virtualdocumentrootip
+virtualhost mod/core.html#virtualhost
+virtualscriptalias mod/mod_vhost_alias.html#virtualscriptalias
+virtualscriptaliasip mod/mod_vhost_alias.html#virtualscriptaliasip
+xbithack mod/mod_include.html#xbithack
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/custom-error.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,199 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="custom-error.xml.meta">
+
+ <title>Custom Error Responses</title>
+
+ <summary>
+
+ <p>Although the Apache HTTP Server provides generic error responses
+ in the event of 4xx or 5xx HTTP status codes, these responses are
+ rather stark, uninformative, and can be intimidating to site users.
+ You may wish to provide custom error responses which are either
+ friendlier, or in some language other than English, or perhaps which
+ are styled more in line with your site layout.</p>
+
+ <p>Customized error responses can be defined for any HTTP status
+ code designated as an error condition - that is, any 4xx or 5xx
+ status.</p>
+
+ <p>Additionally, a set of values are provided, so
+ that the error document can be customized further based on the
+ values of these variables, using <a href="howto/ssi.html">Server
+ Side Includes</a>. Or, you can have error conditions handled by a
+ cgi program, or other dynamic handler (PHP, mod_perl, etc) which
+ makes use of these variables.</p>
+
+ </summary>
+
+ <section id="configuration"><title>Configuration</title>
+
+ <p>Custom error documents are configured using the <directive
+ module="core">ErrorDocument</directive> directive,
+ which may be used in global,
+ virtualhost, or directory context. It may be used in .htaccess files
+ if <directive module="core">AllowOverride</directive> is set to
+ FileInfo.</p>
+
+ <example>
+ ErrorDocument 500 "Sorry, our script crashed. Oh dear"<br />
+ ErrorDocument 500 /cgi-bin/crash-recover<br />
+ ErrorDocument 500 http://error.example.com/server_error.html<br />
+ ErrorDocument 404 /errors/not_found.html <br />
+ ErrorDocument 401 /subscription/how_to_subscribe.html
+ </example>
+
+ <p>The syntax of the <code>ErrorDocument</code> directive is:</p>
+
+ <example>
+ ErrorDocument <3-digit-code> <action>
+ </example>
+
+ <p>where the action can be one of:</p>
+
+ <ol>
+ <li>Text to be displayed. Wrap the text with quotes (").</li>
+ <li>A local URL to redirect to.</li>
+ <li>An external URL to redirect to.</li>
+ </ol>
+
+ <p>When redirecting to a local URL, additional environment variables
+ are set so that the response can be further customized. They are not
sent to
+ external URLs.</p>
+
+ </section>
+
+ <section id="variables"><title>Available Variables</title>
+
+ <p>Redirecting to another URL can be useful, but only if some
+ information can be passed which can then be used to explain or log
+ the error condition more clearly.</p>
+
+ <p>To achieve this, when the error redirect is sent, additional
+ environment variables will be set, which will be generated from
+ the headers provided to the original request by prepending
+ 'REDIRECT_' onto the original header name. This provides the error
+ document the context of the original request.</p>
+
+ <p>For example, you might recieve, in addition to more usual
+ environment variables, the following.</p>
+
+ <example>
+ REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png<br />
+ REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12
Firefox/3.5.8<br />
+ REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br />
+ REDIRECT_QUERY_STRING=<br />
+ REDIRECT_REMOTE_ADDR=121.345.78.123<br />
+ REDIRECT_REMOTE_HOST=client.example.com<br />
+ REDIRECT_SERVER_NAME=www.example.edu<br />
+ REDIRECT_SERVER_PORT=80<br />
+ REDIRECT_SERVER_SOFTWARE=Apache/2.2.15<br />
+ REDIRECT_URL=/cgi-bin/buggy.pl
+ </example>
+
+ <p><code>REDIRECT_</code> environment variables are created from
+ the environment variables which existed prior to the
+ redirect. They are renamed with a <code>REDIRECT_</code>
+ prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
+ <code>REDIRECT_HTTP_USER_AGENT</code>.</p>
+
+ <p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and
+ <code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and
+ the other headers will be set only if they existed prior to the
+ error condition.</p>
+
+ <p><strong>None</strong> of these will be
+ set if the <directive module="core">ErrorDocument</directive> target
is an
+ <em>external</em> redirect (anything starting with a
+ scheme name like <code>http:</code>, even if it refers to the same
host
+ as the server).</p>
+ </section>
+
+ <section id="custom"><title>Customizing Error Responses</title>
+
+ <p>If you point your <code>ErrorDocument</code> to some variety of
+ dynamic handler such as a server-side include document, CGI
+ script, or some variety of other handler, you may wish to use the
+ available custom environent variables to customize this
+ response.</p>
+
+ <p>If the ErrorDocument specifies a local redirect to a CGI
+ script, the script should include a "<code>Status:</code>"
+ header field in its output in order to ensure the propagation
+ all the way back to the client of the error condition that
+ caused it to be invoked. For instance, a Perl ErrorDocument
+ script might include the following:</p>
+
+ <example>
+ ... <br />
+ print "Content-type: text/html\n"; <br />
+ printf "Status: %s Condition Intercepted\n",
$ENV{"REDIRECT_STATUS"}; <br />
+ ...
+ </example>
+
+ <p>If the script is dedicated to handling a particular error
+ condition, such as <code>404 Not Found</code>, it can
+ use the specific code and error text instead.</p>
+
+ <p>Note that if the response contains <code>Location:</code>
+ header (in order to issue a client-side redirect), the script
+ <em>must</em> emit an appropriate <code>Status:</code> header
+ (such as <code>302 Found</code>). Otherwise the
+ <code>Location:</code> header may have no effect.</p>
+
+ </section>
+
+ <section id="multi-lang"><title>Multi Language Custom Error
Documents</title>
+
+ <p>Provided with your installation of the Apache HTTP Server is a
+ directory of custom error documents translated into 16 different
+ languages. There's also a configuration file in the
+ <code>conf/extra</code> configuration directory that can be included
+ to enable this feature.</p>
+
+ <p>In your server configuration file, you'll see a line such as:</p>
+
+ <example>
+ # Multi-language error messages<br />
+ #Include conf/extra/httpd-multilang-errordoc.conf
+ </example>
+
+ <p>Uncommenting this <code>Include</code> line will enable this
+ feature, and provide language-negotiated error messages, based on
+ the language preference set in the client browser.</p>
+
+ <p>Additionally, these documents contain various of the
+ <code>REDIRECT_</code> variables, so that additional information can
+ be provided to the end-user about what happened, and what they can
+ do now.</p>
+
+ <p>These documents can be customized to whatever degree you wish to
+ provide more useful information to users about your site, and what
+ they can expect to find there.</p>
+
+ <p><module>mod_include</module> and <module>mod_negotiation</module>
+ must be enabled to use this feature.</p>
+
+ </section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/custom-error.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="custom-error.xml">
+ <basename>custom-error</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant outdated="yes">es</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">ja</variant>
+ <variant outdated="yes">ko</variant>
+ <variant outdated="yes">tr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/API.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,1238 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="API.xml.meta">
+<parentdocument href="./">Developer Documentation</parentdocument>
+
+<title>Apache 1.3 API notes</title>
+
+<summary>
+ <note type="warning"><title>Warning</title>
+ <p>This document has not been updated to take into account changes
made
+ in the 2.0 version of the Apache HTTP Server. Some of the
information may
+ still be relevant, but please use it with care.</p>
+ </note>
+
+ <p>These are some notes on the Apache API and the data structures you
have
+ to deal with, <em>etc.</em> They are not yet nearly complete, but
hopefully,
+ they will help you get your bearings. Keep in mind that the API is
still
+ subject to change as we gain experience with it. (See the TODO file for
+ what <em>might</em> be coming). However, it will be easy to adapt
modules
+ to any changes that are made. (We have more modules to adapt than you
+ do).</p>
+
+ <p>A few notes on general pedagogical style here. In the interest of
+ conciseness, all structure declarations here are incomplete -- the real
+ ones have more slots that I'm not telling you about. For the most part,
+ these are reserved to one component of the server core or another, and
+ should be altered by modules with caution. However, in some cases, they
+ really are things I just haven't gotten around to yet. Welcome to the
+ bleeding edge.</p>
+
+ <p>Finally, here's an outline, to give you some bare idea of what's
coming
+ up, and in what order:</p>
+
+ <ul>
+ <li>
+ <a href="#basics">Basic concepts.</a>
+
+ <ul>
+ <li><a href="#HMR">Handlers, Modules, and
+ Requests</a></li>
+
+ <li><a href="#moduletour">A brief tour of a
+ module</a></li>
+ </ul>
+ </li>
+
+ <li>
+ <a href="#handlers">How handlers work</a>
+
+ <ul>
+ <li><a href="#req_tour">A brief tour of the
+ <code>request_rec</code></a></li>
+
+ <li><a href="#req_orig">Where request_rec structures come
+ from</a></li>
+
+ <li><a href="#req_return">Handling requests, declining,
+ and returning error codes</a></li>
+
+ <li><a href="#resp_handlers">Special considerations for
+ response handlers</a></li>
+
+ <li><a href="#auth_handlers">Special considerations for
+ authentication handlers</a></li>
+
+ <li><a href="#log_handlers">Special considerations for
+ logging handlers</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#pools">Resource allocation and resource
+ pools</a></li>
+
+ <li>
+ <a href="#config">Configuration, commands and the like</a>
+
+ <ul>
+ <li><a href="#per-dir">Per-directory configuration
+ structures</a></li>
+
+ <li><a href="#commands">Command handling</a></li>
+
+ <li><a href="#servconf">Side notes --- per-server
+ configuration, virtual servers, <em>etc</em>.</a></li>
+ </ul>
+ </li>
+ </ul>
+</summary>
+
+<section id="basics"><title>Basic concepts</title>
+ <p>We begin with an overview of the basic concepts behind the API, and
how
+ they are manifested in the code.</p>
+
+ <section id="HMR"><title>Handlers, Modules, and Requests</title>
+ <p>Apache breaks down request handling into a series of steps, more
or
+ less the same way the Netscape server API does (although this API
has a
+ few more stages than NetSite does, as hooks for stuff I thought
might be
+ useful in the future). These are:</p>
+
+ <ul>
+ <li>URI -> Filename translation</li>
+ <li>Auth ID checking [is the user who they say they are?]</li>
+ <li>Auth access checking [is the user authorized <em>here</em>?]</li>
+ <li>Access checking other than auth</li>
+ <li>Determining MIME type of the object requested</li>
+ <li>`Fixups' -- there aren't any of these yet, but the phase is
intended
+ as a hook for possible extensions like <directive module="mod_env"
+ >SetEnv</directive>, which don't really fit well elsewhere.</li>
+ <li>Actually sending a response back to the client.</li>
+ <li>Logging the request</li>
+ </ul>
+
+ <p>These phases are handled by looking at each of a succession of
+ <em>modules</em>, looking to see if each of them has a handler for
the
+ phase, and attempting invoking it if so. The handler can typically
do one
+ of three things:</p>
+
+ <ul>
+ <li><em>Handle</em> the request, and indicate that it has done so by
+ returning the magic constant <code>OK</code>.</li>
+
+ <li><em>Decline</em> to handle the request, by returning the magic
integer
+ constant <code>DECLINED</code>. In this case, the server behaves in
all
+ respects as if the handler simply hadn't been there.</li>
+
+ <li>Signal an error, by returning one of the HTTP error codes. This
+ terminates normal handling of the request, although an ErrorDocument
may
+ be invoked to try to mop up, and it will be logged in any case.</li>
+ </ul>
+
+ <p>Most phases are terminated by the first module that handles them;
+ however, for logging, `fixups', and non-access authentication
checking,
+ all handlers always run (barring an error). Also, the response phase
is
+ unique in that modules may declare multiple handlers for it, via a
+ dispatch table keyed on the MIME type of the requested object.
Modules may
+ declare a response-phase handler which can handle <em>any</em>
request,
+ by giving it the key <code>*/*</code> (<em>i.e.</em>, a wildcard
MIME type
+ specification). However, wildcard handlers are only invoked if the
server
+ has already tried and failed to find a more specific response
handler for
+ the MIME type of the requested object (either none existed, or they
all
+ declined).</p>
+
+ <p>The handlers themselves are functions of one argument (a
+ <code>request_rec</code> structure. vide infra), which returns an
integer,
+ as above.</p>
+ </section>
+
+ <section id="moduletour"><title>A brief tour of a module</title>
+ <p>At this point, we need to explain the structure of a module. Our
+ candidate will be one of the messier ones, the CGI module -- this
handles
+ both CGI scripts and the <directive module="mod_alias"
+ >ScriptAlias</directive> config file command. It's actually a great
deal
+ more complicated than most modules, but if we're going to have only
one
+ example, it might as well be the one with its fingers in every
place.</p>
+
+ <p>Let's begin with handlers. In order to handle the CGI scripts, the
+ module declares a response handler for them. Because of <directive
+ module="mod_alias">ScriptAlias</directive>, it also has handlers for
the
+ name translation phase (to recognize <directive module="mod_alias"
+ >ScriptAlias</directive>ed URIs), the type-checking phase (any
+ <directive module="mod_alias">ScriptAlias</directive>ed request is
typed
+ as a CGI script).</p>
+
+ <p>The module needs to maintain some per (virtual) server
information,
+ namely, the <directive module="mod_alias">ScriptAlias</directive>es
in
+ effect; the module structure therefore contains pointers to a
functions
+ which builds these structures, and to another which combines two of
them
+ (in case the main server and a virtual server both have <directive
+ module="mod_alias">ScriptAlias</directive>es declared).</p>
+
+ <p>Finally, this module contains code to handle the <directive
+ module="mod_alias">ScriptAlias</directive> command itself. This
particular
+ module only declares one command, but there could be more, so
modules have
+ <em>command tables</em> which declare their commands, and describe
where
+ they are permitted, and how they are to be invoked.</p>
+
+ <p>A final note on the declared types of the arguments of some of
these
+ commands: a <code>pool</code> is a pointer to a <em>resource
pool</em>
+ structure; these are used by the server to keep track of the memory
which
+ has been allocated, files opened, <em>etc.</em>, either to service a
+ particular request, or to handle the process of configuring itself.
That
+ way, when the request is over (or, for the configuration pool, when
the
+ server is restarting), the memory can be freed, and the files closed,
+ <em>en masse</em>, without anyone having to write explicit code to
track
+ them all down and dispose of them. Also, a <code>cmd_parms</code>
+ structure contains various information about the config file being
read,
+ and other status information, which is sometimes of use to the
function
+ which processes a config-file command (such as <directive
+ module="mod_alias">ScriptAlias</directive>). With no further ado, the
+ module itself:</p>
+
+ <example>
+ /* Declarations of handlers. */<br />
+ <br />
+ int translate_scriptalias (request_rec *);<br />
+ int type_scriptalias (request_rec *);<br />
+ int cgi_handler (request_rec *);<br />
+ <br />
+ /* Subsidiary dispatch table for response-phase <br />
+  * handlers, by MIME type */<br />
+ <br />
+ handler_rec cgi_handlers[] = {<br />
+ <indent>
+ { "application/x-httpd-cgi", cgi_handler },<br />
+ { NULL }<br />
+ </indent>
+ };<br />
+ <br />
+ /* Declarations of routines to manipulate the <br />
+  * module's configuration info. Note that these are<br />
+  * returned, and passed in, as void *'s; the server<br />
+  * core keeps track of them, but it doesn't, and can't,<br />
+  * know their internal structure.<br />
+  */<br />
+ <br />
+ void *make_cgi_server_config (pool *);<br />
+ void *merge_cgi_server_config (pool *, void *, void *);<br />
+ <br />
+ /* Declarations of routines to handle config-file commands */<br />
+ <br />
+ extern char *script_alias(cmd_parms *, void *per_dir_config, char
*fake,
+ char *real);<br />
+ <br />
+ command_rec cgi_cmds[] = {<br />
+ <indent>
+ { "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,<br />
+ <indent>"a fakename and a realname"},<br /></indent>
+ { NULL }<br />
+ </indent>
+ };<br />
+ <br />
+ module cgi_module = {
+<pre> STANDARD_MODULE_STUFF,
+ NULL, /* initializer */
+ NULL, /* dir config creator */
+ NULL, /* dir merger */
+ make_cgi_server_config, /* server config */
+ merge_cgi_server_config, /* merge server config */
+ cgi_cmds, /* command table */
+ cgi_handlers, /* handlers */
+ translate_scriptalias, /* filename translation */
+ NULL, /* check_user_id */
+ NULL, /* check auth */
+ NULL, /* check access */
+ type_scriptalias, /* type_checker */
+ NULL, /* fixups */
+ NULL, /* logger */
+ NULL /* header parser */
+};</pre>
+ </example>
+ </section>
+</section>
+
+<section id="handlers"><title>How handlers work</title>
+ <p>The sole argument to handlers is a <code>request_rec</code>
structure.
+ This structure describes a particular request which has been made to
the
+ server, on behalf of a client. In most cases, each connection to the
+ client generates only one <code>request_rec</code> structure.</p>
+
+ <section id="req_tour"><title>A brief tour of the request_rec</title>
+ <p>The <code>request_rec</code> contains pointers to a resource pool
+ which will be cleared when the server is finished handling the
request;
+ to structures containing per-server and per-connection information,
and
+ most importantly, information on the request itself.</p>
+
+ <p>The most important such information is a small set of character
strings
+ describing attributes of the object being requested, including its
URI,
+ filename, content-type and content-encoding (these being filled in
by the
+ translation and type-check handlers which handle the request,
+ respectively).</p>
+
+ <p>Other commonly used data items are tables giving the MIME headers
on
+ the client's original request, MIME headers to be sent back with the
+ response (which modules can add to at will), and environment
variables for
+ any subprocesses which are spawned off in the course of servicing the
+ request. These tables are manipulated using the
<code>ap_table_get</code>
+ and <code>ap_table_set</code> routines.</p>
+
+ <note>
+ <p>Note that the <code>Content-type</code> header value
<em>cannot</em>
+ be set by module content-handlers using the
<code>ap_table_*()</code>
+ routines. Rather, it is set by pointing the
<code>content_type</code>
+ field in the <code>request_rec</code> structure to an appropriate
+ string. <em>e.g.</em>,</p>
+ <example>
+ r->content_type = "text/html";
+ </example>
+ </note>
+
+ <p>Finally, there are pointers to two data structures which, in turn,
+ point to per-module configuration structures. Specifically, these
hold
+ pointers to the data structures which the module has built to
describe
+ the way it has been configured to operate in a given directory (via
+ <code>.htaccess</code> files or <directive type="section"
module="core"
+ >Directory</directive> sections), for private data it has built in
the
+ course of servicing the request (so modules' handlers for one phase
can
+ pass `notes' to their handlers for other phases). There is another
such
+ configuration vector in the <code>server_rec</code> data structure
pointed
+ to by the <code>request_rec</code>, which contains per (virtual)
server
+ configuration data.</p>
+
+ <p>Here is an abridged declaration, giving the fields most commonly
+ used:</p>
+
+ <example>
+ struct request_rec {<br />
+ <br />
+ pool *pool;<br />
+ conn_rec *connection;<br />
+ server_rec *server;<br />
+ <br />
+ /* What object is being requested */<br />
+ <br />
+ char *uri;<br />
+ char *filename;<br />
+ char *path_info;
+<pre>char *args; /* QUERY_ARGS, if any */
+struct stat finfo; /* Set by server core;
+ * st_mode set to zero if no such file */</pre>
+ char *content_type;<br />
+ char *content_encoding;<br />
+ <br />
+ /* MIME header environments, in and out. Also, <br />
+  * an array containing environment variables to<br />
+  * be passed to subprocesses, so people can write<br />
+  * modules to add to that environment.<br />
+  *<br />
+  * The difference between headers_out and <br />
+  * err_headers_out is that the latter are printed <br />
+  * even on error, and persist across internal<br />
+  * redirects (so the headers printed for <br />
+  * <directive module="core">ErrorDocument</directive>
handlers will have
+ them).<br />
+  */<br />
+ <br />
+ table *headers_in;<br />
+ table *headers_out;<br />
+ table *err_headers_out;<br />
+ table *subprocess_env;<br />
+ <br />
+ /* Info about the request itself... */<br />
+ <br />
+<pre>int header_only; /* HEAD request, as opposed to GET */
+char *protocol; /* Protocol, as given to us, or HTTP/0.9 */
+char *method; /* GET, HEAD, POST, <em>etc.</em> */
+int method_number; /* M_GET, M_POST, <em>etc.</em> */
+
+</pre>
+ /* Info for logging */<br />
+ <br />
+ char *the_request;<br />
+ int bytes_sent;<br />
+ <br />
+ /* A flag which modules can set, to indicate that<br />
+  * the data being returned is volatile, and clients<br />
+  * should be told not to cache it.<br />
+  */<br />
+ <br />
+ int no_cache;<br />
+ <br />
+ /* Various other config info which may change<br />
+  * with .htaccess files<br />
+  * These are config vectors, with one void*<br />
+  * pointer for each module (the thing pointed<br />
+  * to being the module's business).<br />
+  */<br />
+ <br />
+<pre>void *per_dir_config; /* Options set in config files, <em>etc.</em>
*/
+void *request_config; /* Notes on *this* request */</pre>
+ <br />
+ };
+ </example>
+ </section>
+
+ <section id="req_orig"><title>Where request_rec structures come
from</title>
+ <p>Most <code>request_rec</code> structures are built by reading an
HTTP
+ request from a client, and filling in the fields. However, there are
a
+ few exceptions:</p>
+
+ <ul>
+ <li>If the request is to an imagemap, a type map (<em>i.e.</em>, a
+ <code>*.var</code> file), or a CGI script which returned a local
+ `Location:', then the resource which the user requested is going to
be
+ ultimately located by some URI other than what the client originally
+ supplied. In this case, the server does an <em>internal
redirect</em>,
+ constructing a new <code>request_rec</code> for the new URI, and
+ processing it almost exactly as if the client had requested the new
URI
+ directly.</li>
+
+ <li>If some handler signaled an error, and an
<code>ErrorDocument</code>
+ is in scope, the same internal redirect machinery comes into
play.</li>
+
+ <li><p>Finally, a handler occasionally needs to investigate `what
would
+ happen if' some other request were run. For instance, the directory
+ indexing module needs to know what MIME type would be assigned to a
+ request for each directory entry, in order to figure out what icon to
+ use.</p>
+
+ <p>Such handlers can construct a <em>sub-request</em>, using the
+ functions <code>ap_sub_req_lookup_file</code>,
+ <code>ap_sub_req_lookup_uri</code>, and
<code>ap_sub_req_method_uri</code>;
+ these construct a new <code>request_rec</code> structure and
processes it
+ as you would expect, up to but not including the point of actually
sending
+ a response. (These functions skip over the access checks if the
+ sub-request is for a file in the same directory as the original
+ request).</p>
+
+ <p>(Server-side includes work by building sub-requests and then
actually
+ invoking the response handler for them, via the function
+ <code>ap_run_sub_req</code>).</p>
+ </li>
+ </ul>
+ </section>
+
+ <section id="req_return"><title>Handling requests, declining, and
returning
+ error codes</title>
+ <p>As discussed above, each handler, when invoked to handle a
particular
+ <code>request_rec</code>, has to return an <code>int</code> to
indicate
+ what happened. That can either be</p>
+
+ <ul>
+ <li><code>OK</code> -- the request was handled successfully. This
may or
+ may not terminate the phase.</li>
+
+ <li><code>DECLINED</code> -- no erroneous condition exists, but the
module
+ declines to handle the phase; the server tries to find another.</li>
+
+ <li>an HTTP error code, which aborts handling of the request.</li>
+ </ul>
+
+ <p>Note that if the error code returned is <code>REDIRECT</code>,
then
+ the module should put a <code>Location</code> in the request's
+ <code>headers_out</code>, to indicate where the client should be
+ redirected <em>to</em>.</p>
+ </section>
+
+ <section id="resp_handlers"><title>Special considerations for response
+ handlers</title>
+ <p>Handlers for most phases do their work by simply setting a few
fields
+ in the <code>request_rec</code> structure (or, in the case of access
+ checkers, simply by returning the correct error code). However,
response
+ handlers have to actually send a request back to the client.</p>
+
+ <p>They should begin by sending an HTTP response header, using the
+ function <code>ap_send_http_header</code>. (You don't have to do
anything
+ special to skip sending the header for HTTP/0.9 requests; the
function
+ figures out on its own that it shouldn't do anything). If the
request is
+ marked <code>header_only</code>, that's all they should do; they
should
+ return after that, without attempting any further output.</p>
+
+ <p>Otherwise, they should produce a request body which responds to
the
+ client as appropriate. The primitives for this are
<code>ap_rputc</code>
+ and <code>ap_rprintf</code>, for internally generated output, and
+ <code>ap_send_fd</code>, to copy the contents of some <code>FILE
*</code>
+ straight to the client.</p>
+
+ <p>At this point, you should more or less understand the following
piece
+ of code, which is the handler which handles <code>GET</code> requests
+ which have no more specific handler; it also shows how conditional
+ <code>GET</code>s can be handled, if it's desirable to do so in a
+ particular response handler -- <code>ap_set_last_modified</code>
checks
+ against the <code>If-modified-since</code> value supplied by the
client,
+ if any, and returns an appropriate code (which will, if nonzero, be
+ USE_LOCAL_COPY). No similar considerations apply for
+ <code>ap_set_content_length</code>, but it returns an error code for
+ symmetry.</p>
+
+ <example>
+ int default_handler (request_rec *r)<br />
+ {<br />
+ <indent>
+ int errstatus;<br />
+ FILE *f;<br />
+ <br />
+ if (r->method_number != M_GET) return DECLINED;<br />
+ if (r->finfo.st_mode == 0) return NOT_FOUND;<br />
+ <br />
+ if ((errstatus = ap_set_content_length (r,
r->finfo.st_size))<br />
+     ||
+ (errstatus = ap_set_last_modified (r,
r->finfo.st_mtime)))<br />
+ return errstatus;<br />
+ <br />
+ f = fopen (r->filename, "r");<br />
+ <br />
+ if (f == NULL) {<br />
+ <indent>
+ log_reason("file permissions deny server access",
r->filename, r);<br />
+ return FORBIDDEN;<br />
+ </indent>
+ }<br />
+ <br />
+ register_timeout ("send", r);<br />
+ ap_send_http_header (r);<br />
+ <br />
+ if (!r->header_only) send_fd (f, r);<br />
+ ap_pfclose (r->pool, f);<br />
+ return OK;<br />
+ </indent>
+ }
+ </example>
+
+ <p>Finally, if all of this is too much of a challenge, there are a
few
+ ways out of it. First off, as shown above, a response handler which
has
+ not yet produced any output can simply return an error code, in which
+ case the server will automatically produce an error response.
Secondly,
+ it can punt to some other handler by invoking
+ <code>ap_internal_redirect</code>, which is how the internal
redirection
+ machinery discussed above is invoked. A response handler which has
+ internally redirected should always return <code>OK</code>.</p>
+
+ <p>(Invoking <code>ap_internal_redirect</code> from handlers which
are
+ <em>not</em> response handlers will lead to serious confusion).</p>
+ </section>
+
+ <section id="auth_handlers"><title>Special considerations for
authentication
+ handlers</title>
+ <p>Stuff that should be discussed here in detail:</p>
+
+ <ul>
+ <li>Authentication-phase handlers not invoked unless auth is
+ configured for the directory.</li>
+
+ <li>Common auth configuration stored in the core per-dir
+ configuration; it has accessors <code>ap_auth_type</code>,
+ <code>ap_auth_name</code>, and <code>ap_requires</code>.</li>
+
+ <li>Common routines, to handle the protocol end of things, at
+ least for HTTP basic authentication
+ (<code>ap_get_basic_auth_pw</code>, which sets the
+ <code>connection->user</code> structure field
+ automatically, and <code>ap_note_basic_auth_failure</code>,
+ which arranges for the proper <code>WWW-Authenticate:</code>
+ header to be sent back).</li>
+ </ul>
+ </section>
+
+ <section id="log_handlers"><title>Special considerations for logging
+ handlers</title>
+ <p>When a request has internally redirected, there is the question of
+ what to log. Apache handles this by bundling the entire chain of
redirects
+ into a list of <code>request_rec</code> structures which are threaded
+ through the <code>r->prev</code> and <code>r->next</code>
pointers.
+ The <code>request_rec</code> which is passed to the logging handlers
in
+ such cases is the one which was originally built for the initial
request
+ from the client; note that the <code>bytes_sent</code> field will
only be
+ correct in the last request in the chain (the one for which a
response was
+ actually sent).</p>
+ </section>
+</section>
+
+<section id="pools"><title>Resource allocation and resource pools</title>
+ <p>One of the problems of writing and designing a server-pool server is
+ that of preventing leakage, that is, allocating resources (memory, open
+ files, <em>etc.</em>), without subsequently releasing them. The
resource
+ pool machinery is designed to make it easy to prevent this from
happening,
+ by allowing resource to be allocated in such a way that they are
+ <em>automatically</em> released when the server is done with them.</p>
+
+ <p>The way this works is as follows: the memory which is allocated,
file
+ opened, <em>etc.</em>, to deal with a particular request are tied to a
+ <em>resource pool</em> which is allocated for the request. The pool is
a
+ data structure which itself tracks the resources in question.</p>
+
+ <p>When the request has been processed, the pool is <em>cleared</em>.
At
+ that point, all the memory associated with it is released for reuse,
all
+ files associated with it are closed, and any other clean-up functions
which
+ are associated with the pool are run. When this is over, we can be
confident
+ that all the resource tied to the pool have been released, and that
none of
+ them have leaked.</p>
+
+ <p>Server restarts, and allocation of memory and resources for
per-server
+ configuration, are handled in a similar way. There is a
<em>configuration
+ pool</em>, which keeps track of resources which were allocated while
reading
+ the server configuration files, and handling the commands therein (for
+ instance, the memory that was allocated for per-server module
configuration,
+ log files and other files that were opened, and so forth). When the
server
+ restarts, and has to reread the configuration files, the configuration
pool
+ is cleared, and so the memory and file descriptors which were taken up
by
+ reading them the last time are made available for reuse.</p>
+
+ <p>It should be noted that use of the pool machinery isn't generally
+ obligatory, except for situations like logging handlers, where you
really
+ need to register cleanups to make sure that the log file gets closed
when
+ the server restarts (this is most easily done by using the function
<code><a
+ href="#pool-files">ap_pfopen</a></code>, which also arranges for the
+ underlying file descriptor to be closed before any child processes,
such as
+ for CGI scripts, are <code>exec</code>ed), or in case you are using the
+ timeout machinery (which isn't yet even documented here). However,
there are
+ two benefits to using it: resources allocated to a pool never leak
(even if
+ you allocate a scratch string, and just forget about it); also, for
memory
+ allocation, <code>ap_palloc</code> is generally faster than
+ <code>malloc</code>.</p>
+
+ <p>We begin here by describing how memory is allocated to pools, and
then
+ discuss how other resources are tracked by the resource pool
machinery.</p>
+
+ <section><title>Allocation of memory in pools</title>
+ <p>Memory is allocated to pools by calling the function
+ <code>ap_palloc</code>, which takes two arguments, one being a
pointer to
+ a resource pool structure, and the other being the amount of memory
to
+ allocate (in <code>char</code>s). Within handlers for handling
requests,
+ the most common way of getting a resource pool structure is by
looking at
+ the <code>pool</code> slot of the relevant <code>request_rec</code>;
hence
+ the repeated appearance of the following idiom in module code:</p>
+
+ <example>
+ int my_handler(request_rec *r)<br />
+ {<br />
+ <indent>
+ struct my_structure *foo;<br />
+ ...<br />
+ <br />
+ foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));<br />
+ </indent>
+ }
+ </example>
+
+ <p>Note that <em>there is no <code>ap_pfree</code></em> --
+ <code>ap_palloc</code>ed memory is freed only when the associated
resource
+ pool is cleared. This means that <code>ap_palloc</code> does not
have to
+ do as much accounting as <code>malloc()</code>; all it does in the
typical
+ case is to round up the size, bump a pointer, and do a range
check.</p>
+
+ <p>(It also raises the possibility that heavy use of
+ <code>ap_palloc</code> could cause a server process to grow
excessively
+ large. There are two ways to deal with this, which are dealt with
below;
+ briefly, you can use <code>malloc</code>, and try to be sure that
all of
+ the memory gets explicitly <code>free</code>d, or you can allocate a
+ sub-pool of the main pool, allocate your memory in the sub-pool, and
clear
+ it out periodically. The latter technique is discussed in the section
+ on sub-pools below, and is used in the directory-indexing code, in
order
+ to avoid excessive storage allocation when listing directories with
+ thousands of files).</p>
+ </section>
+
+ <section><title>Allocating initialized memory</title>
+ <p>There are functions which allocate initialized memory, and are
+ frequently useful. The function <code>ap_pcalloc</code> has the same
+ interface as <code>ap_palloc</code>, but clears out the memory it
+ allocates before it returns it. The function <code>ap_pstrdup</code>
+ takes a resource pool and a <code>char *</code> as arguments, and
+ allocates memory for a copy of the string the pointer points to,
returning
+ a pointer to the copy. Finally <code>ap_pstrcat</code> is a
varargs-style
+ function, which takes a pointer to a resource pool, and at least two
+ <code>char *</code> arguments, the last of which must be
+ <code>NULL</code>. It allocates enough memory to fit copies of each
of
+ the strings, as a unit; for instance:</p>
+
+ <example>
+ ap_pstrcat (r->pool, "foo", "/", "bar", NULL);
+ </example>
+
+ <p>returns a pointer to 8 bytes worth of memory, initialized to
+ <code>"foo/bar"</code>.</p>
+ </section>
+
+ <section id="pools-used"><title>Commonly-used pools in the Apache Web
+ server</title>
+ <p>A pool is really defined by its lifetime more than anything else.
+ There are some static pools in http_main which are passed to various
+ non-http_main functions as arguments at opportune times. Here they
+ are:</p>
+
+ <dl>
+ <dt><code>permanent_pool</code></dt>
+ <dd>never passed to anything else, this is the ancestor of all
pools</dd>
+
+ <dt><code>pconf</code></dt>
+ <dd>
+ <ul>
+ <li>subpool of permanent_pool</li>
+
+ <li>created at the beginning of a config "cycle"; exists
+ until the server is terminated or restarts; passed to all
+ config-time routines, either via cmd->pool, or as the
+ "pool *p" argument on those which don't take pools</li>
+
+ <li>passed to the module init() functions</li>
+ </ul>
+ </dd>
+
+ <dt><code>ptemp</code></dt>
+ <dd>
+ <ul>
+ <li>sorry I lie, this pool isn't called this currently in
+ 1.3, I renamed it this in my pthreads development. I'm
+ referring to the use of ptrans in the parent... contrast
+ this with the later definition of ptrans in the
+ child.</li>
+
+ <li>subpool of permanent_pool</li>
+
+ <li>created at the beginning of a config "cycle"; exists
+ until the end of config parsing; passed to config-time
+ routines <em>via</em> cmd->temp_pool. Somewhat of a
+ "bastard child" because it isn't available everywhere.
+ Used for temporary scratch space which may be needed by
+ some config routines but which is deleted at the end of
+ config.</li>
+ </ul>
+ </dd>
+
+ <dt><code>pchild</code></dt>
+ <dd>
+ <ul>
+ <li>subpool of permanent_pool</li>
+
+ <li>created when a child is spawned (or a thread is
+ created); lives until that child (thread) is
+ destroyed</li>
+
+ <li>passed to the module child_init functions</li>
+
+ <li>destruction happens right after the child_exit
+ functions are called... (which may explain why I think
+ child_exit is redundant and unneeded)</li>
+ </ul>
+ </dd>
+
+ <dt><code>ptrans</code></dt>
+ <dd>
+ <ul>
+ <li>should be a subpool of pchild, but currently is a
+ subpool of permanent_pool, see above</li>
+
+ <li>cleared by the child before going into the accept()
+ loop to receive a connection</li>
+
+ <li>used as connection->pool</li>
+ </ul>
+ </dd>
+
+ <dt><code>r->pool</code></dt>
+ <dd>
+ <ul>
+ <li>for the main request this is a subpool of
+ connection->pool; for subrequests it is a subpool of
+ the parent request's pool.</li>
+
+ <li>exists until the end of the request (<em>i.e.</em>,
+ ap_destroy_sub_req, or in child_main after
+ process_request has finished)</li>
+
+ <li>note that r itself is allocated from r->pool;
+ <em>i.e.</em>, r->pool is first created and then r is
+ the first thing palloc()d from it</li>
+ </ul>
+ </dd>
+ </dl>
+
+ <p>For almost everything folks do, <code>r->pool</code> is the
pool to
+ use. But you can see how other lifetimes, such as pchild, are useful
to
+ some modules... such as modules that need to open a database
connection
+ once per child, and wish to clean it up when the child dies.</p>
+
+ <p>You can also see how some bugs have manifested themself, such as
+ setting <code>connection->user</code> to a value from
+ <code>r->pool</code> -- in this case connection exists for the
+ lifetime of <code>ptrans</code>, which is longer than
+ <code>r->pool</code> (especially if <code>r->pool</code> is a
+ subrequest!). So the correct thing to do is to allocate from
+ <code>connection->pool</code>.</p>
+
+ <p>And there was another interesting bug in
<module>mod_include</module>
+ / <module>mod_cgi</module>. You'll see in those that they do this
test
+ to decide if they should use <code>r->pool</code> or
+ <code>r->main->pool</code>. In this case the resource that
they are
+ registering for cleanup is a child process. If it were registered in
+ <code>r->pool</code>, then the code would <code>wait()</code> for
the
+ child when the subrequest finishes. With
<module>mod_include</module> this
+ could be any old <code>#include</code>, and the delay can be up to 3
+ seconds... and happened quite frequently. Instead the subprocess is
+ registered in <code>r->main->pool</code> which causes it to be
+ cleaned up when the entire request is done -- <em>i.e.</em>, after
the
+ output has been sent to the client and logging has happened.</p>
+ </section>
+
+ <section id="pool-files"><title>Tracking open files, etc.</title>
+ <p>As indicated above, resource pools are also used to track other
sorts
+ of resources besides memory. The most common are open files. The
routine
+ which is typically used for this is <code>ap_pfopen</code>, which
takes a
+ resource pool and two strings as arguments; the strings are the same
as
+ the typical arguments to <code>fopen</code>, <em>e.g.</em>,</p>
+
+ <example>
+ ...<br />
+ FILE *f = ap_pfopen (r->pool, r->filename, "r");<br />
+ <br />
+ if (f == NULL) { ... } else { ... }<br />
+ </example>
+
+ <p>There is also a <code>ap_popenf</code> routine, which parallels
the
+ lower-level <code>open</code> system call. Both of these routines
arrange
+ for the file to be closed when the resource pool in question is
+ cleared.</p>
+
+ <p>Unlike the case for memory, there <em>are</em> functions to close
files
+ allocated with <code>ap_pfopen</code>, and <code>ap_popenf</code>,
namely
+ <code>ap_pfclose</code> and <code>ap_pclosef</code>. (This is
because, on
+ many systems, the number of files which a single process can have
open is
+ quite limited). It is important to use these functions to close files
+ allocated with <code>ap_pfopen</code> and <code>ap_popenf</code>,
since to
+ do otherwise could cause fatal errors on systems such as Linux, which
+ react badly if the same <code>FILE*</code> is closed more than
once.</p>
+
+ <p>(Using the <code>close</code> functions is not mandatory, since
the
+ file will eventually be closed regardless, but you should consider
it in
+ cases where your module is opening, or could open, a lot of
files).</p>
+ </section>
+
+ <section><title>Other sorts of resources -- cleanup functions</title>
+ <p>More text goes here. Describe the cleanup primitives in terms of
+ which the file stuff is implemented; also,
<code>spawn_process</code>.</p>
+
+ <p>Pool cleanups live until <code>clear_pool()</code> is called:
+ <code>clear_pool(a)</code> recursively calls
<code>destroy_pool()</code>
+ on all subpools of <code>a</code>; then calls all the cleanups for
+ <code>a</code>; then releases all the memory for <code>a</code>.
+ <code>destroy_pool(a)</code> calls <code>clear_pool(a)</code> and
then
+ releases the pool structure itself. <em>i.e.</em>,
+ <code>clear_pool(a)</code> doesn't delete <code>a</code>, it just
frees
+ up all the resources and you can start using it again
immediately.</p>
+ </section>
+
+ <section><title>Fine control -- creating and dealing with sub-pools,
with
+ a note on sub-requests</title>
+ <p>On rare occasions, too-free use of <code>ap_palloc()</code> and
the
+ associated primitives may result in undesirably profligate resource
+ allocation. You can deal with such a case by creating a
<em>sub-pool</em>,
+ allocating within the sub-pool rather than the main pool, and
clearing or
+ destroying the sub-pool, which releases the resources which were
+ associated with it. (This really <em>is</em> a rare situation; the
only
+ case in which it comes up in the standard module set is in case of
listing
+ directories, and then only with <em>very</em> large directories.
+ Unnecessary use of the primitives discussed here can hair up your
code
+ quite a bit, with very little gain).</p>
+
+ <p>The primitive for creating a sub-pool is
<code>ap_make_sub_pool</code>,
+ which takes another pool (the parent pool) as an argument. When the
main
+ pool is cleared, the sub-pool will be destroyed. The sub-pool may
also be
+ cleared or destroyed at any time, by calling the functions
+ <code>ap_clear_pool</code> and <code>ap_destroy_pool</code>,
respectively.
+ (The difference is that <code>ap_clear_pool</code> frees resources
+ associated with the pool, while <code>ap_destroy_pool</code> also
+ deallocates the pool itself. In the former case, you can allocate new
+ resources within the pool, and clear it again, and so forth; in the
+ latter case, it is simply gone).</p>
+
+ <p>One final note -- sub-requests have their own resource pools,
which are
+ sub-pools of the resource pool for the main request. The polite way
to
+ reclaim the resources associated with a sub request which you have
+ allocated (using the <code>ap_sub_req_...</code> functions) is
+ <code>ap_destroy_sub_req</code>, which frees the resource pool.
Before
+ calling this function, be sure to copy anything that you care about
which
+ might be allocated in the sub-request's resource pool into someplace
a
+ little less volatile (for instance, the filename in its
+ <code>request_rec</code> structure).</p>
+
+ <p>(Again, under most circumstances, you shouldn't feel obliged to
call
+ this function; only 2K of memory or so are allocated for a typical
sub
+ request, and it will be freed anyway when the main request pool is
+ cleared. It is only when you are allocating many, many sub-requests
for a
+ single main request that you should seriously consider the
+ <code>ap_destroy_...</code> functions).</p>
+ </section>
+</section>
+
+<section id="config"><title>Configuration, commands and the like</title>
+ <p>One of the design goals for this server was to maintain external
+ compatibility with the NCSA 1.3 server --- that is, to read the same
+ configuration files, to process all the directives therein correctly,
and
+ in general to be a drop-in replacement for NCSA. On the other hand,
another
+ design goal was to move as much of the server's functionality into
modules
+ which have as little as possible to do with the monolithic server
core. The
+ only way to reconcile these goals is to move the handling of most
commands
+ from the central server into the modules.</p>
+
+ <p>However, just giving the modules command tables is not enough to
divorce
+ them completely from the server core. The server has to remember the
+ commands in order to act on them later. That involves maintaining data
which
+ is private to the modules, and which can be either per-server, or
+ per-directory. Most things are per-directory, including in particular
access
+ control and authorization information, but also information on how to
+ determine file types from suffixes, which can be modified by
+ <directive module="mod_mime">AddType</directive> and <directive
+ module="core">ForceType</directive> directives, and so forth. In
general,
+ the governing philosophy is that anything which <em>can</em> be made
+ configurable by directory should be; per-server information is
generally
+ used in the standard set of modules for information like
+ <directive module="mod_alias">Alias</directive>es and <directive
+ module="mod_alias">Redirect</directive>s which come into play before
the
+ request is tied to a particular place in the underlying file
system.</p>
+
+ <p>Another requirement for emulating the NCSA server is being able to
handle
+ the per-directory configuration files, generally called
+ <code>.htaccess</code> files, though even in the NCSA server they can
+ contain directives which have nothing at all to do with access control.
+ Accordingly, after URI -> filename translation, but before
performing any
+ other phase, the server walks down the directory hierarchy of the
underlying
+ filesystem, following the translated pathname, to read any
+ <code>.htaccess</code> files which might be present. The information
which
+ is read in then has to be <em>merged</em> with the applicable
information
+ from the server's own config files (either from the <directive
+ type="section" module="core">Directory</directive> sections in
+ <code>access.conf</code>, or from defaults in <code>srm.conf</code>,
which
+ actually behaves for most purposes almost exactly like
<code><Directory
+ /></code>).</p>
+
+ <p>Finally, after having served a request which involved reading
+ <code>.htaccess</code> files, we need to discard the storage allocated
for
+ handling them. That is solved the same way it is solved wherever else
+ similar problems come up, by tying those structures to the
per-transaction
+ resource pool.</p>
+
+ <section id="per-dir"><title>Per-directory configuration
structures</title>
+ <p>Let's look out how all of this plays out in
<code>mod_mime.c</code>,
+ which defines the file typing handler which emulates the NCSA
server's
+ behavior of determining file types from suffixes. What we'll be
looking
+ at, here, is the code which implements the <directive
module="mod_mime"
+ >AddType</directive> and <directive module="mod_mime"
+ >AddEncoding</directive> commands. These commands can appear in
+ <code>.htaccess</code> files, so they must be handled in the module's
+ private per-directory data, which in fact, consists of two separate
+ tables for MIME types and encoding information, and is declared as
+ follows:</p>
+
+ <example>
+<pre>typedef struct {
+ table *forced_types; /* Additional AddTyped stuff */
+ table *encoding_types; /* Added with AddEncoding... */
+} mime_dir_config;</pre>
+ </example>
+
+ <p>When the server is reading a configuration file, or <directive
+ type="section" module="core">Directory</directive> section, which
includes
+ one of the MIME module's commands, it needs to create a
+ <code>mime_dir_config</code> structure, so those commands have
something
+ to act on. It does this by invoking the function it finds in the
module's
+ `create per-dir config slot', with two arguments: the name of the
+ directory to which this configuration information applies (or
+ <code>NULL</code> for <code>srm.conf</code>), and a pointer to a
+ resource pool in which the allocation should happen.</p>
+
+ <p>(If we are reading a <code>.htaccess</code> file, that resource
pool
+ is the per-request resource pool for the request; otherwise it is a
+ resource pool which is used for configuration data, and cleared on
+ restarts. Either way, it is important for the structure being
created to
+ vanish when the pool is cleared, by registering a cleanup on the
pool if
+ necessary).</p>
+
+ <p>For the MIME module, the per-dir config creation function just
+ <code>ap_palloc</code>s the structure above, and a creates a couple
of
+ tables to fill it. That looks like this:</p>
+
+ <example>
+ void *create_mime_dir_config (pool *p, char *dummy)<br />
+ {<br />
+ <indent>
+ mime_dir_config *new =<br />
+ <indent>
+ (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));<br
/>
+ </indent>
+ <br />
+ new->forced_types = ap_make_table (p, 4);<br />
+ new->encoding_types = ap_make_table (p, 4);<br />
+ <br />
+ return new;<br />
+ </indent>
+ }
+ </example>
+
+ <p>Now, suppose we've just read in a <code>.htaccess</code> file. We
+ already have the per-directory configuration structure for the next
+ directory up in the hierarchy. If the <code>.htaccess</code> file we
just
+ read in didn't have any <directive
module="mod_mime">AddType</directive>
+ or <directive module="mod_mime">AddEncoding</directive> commands, its
+ per-directory config structure for the MIME module is still valid,
and we
+ can just use it. Otherwise, we need to merge the two structures
***The diff for this file has been truncated for email.***
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/API.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="API.xml">
+ <basename>API</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/debugging.xml Sat Feb 26 23:20:49
2011
@@ -0,0 +1,194 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="debugging.xml.meta">
+<parentdocument href="./">Developer Documentation</parentdocument>
+
+<title>Debugging Memory Allocation in APR</title>
+
+<summary>
+ <p>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.</p>
+</summary>
+
+<section id="options"><title>Available debugging options</title>
+ <section id="alloc_debug">
+ <title>Allocation Debugging - ALLOC_DEBUG</title>
+
+ <note>Debugging support: Define this to enable code which
+ helps detect re-use of <code>free()</code>d memory and other such
+ nonsense.</note>
+
+ <p>The theory is simple. The <code>FILL_BYTE</code>
(<code>0xa5</code>)
+ is written over all <code>malloc</code>'d memory as we receive it,
and
+ is written over everything that we free up during a
+ <code>clear_pool</code>. We check that blocks on the free list always
+ have the <code>FILL_BYTE</code> in them, and we check during
+ <code>palloc()</code> that the bytes still have
<code>FILL_BYTE</code>
+ in them. If you ever see garbage URLs or whatnot containing lots
+ of <code>0xa5</code>s then you know something used data that's been
+ freed or uninitialized.</p>
+ </section>
+
+ <section id="alloc_use_malloc">
+ <title>Malloc Support - ALLOC_USE_MALLOC</title>
+
+ <note>If defined all allocations will be done with
+ <code>malloc()</code> and <code>free()</code>d appropriately at the
+ end.</note>
+
+ <p>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
<code>ALLOC_DEBUG</code>.
+ But don't add in <code>ALLOC_DEBUG</code> if you're using Purify
because
+ <code>ALLOC_DEBUG</code> would hide all the uninitialized read errors
+ that Purify can diagnose.</p>
+ </section>
+
+ <section id="pool_debug"><title>Pool Debugging - POOL_DEBUG</title>
+ <note>This is intended to detect cases where the wrong pool is
+ used when assigning data to an object in another pool.</note>
+
+ <p>In particular, it causes the <code>table_{set,add,merge}n</code>
+ routines to check that their arguments are safe for the
+ <code>apr_table_t</code> they're being placed in. It currently only
works
+ with the unix multiprocess model, but could be extended to
others.</p>
+ </section>
+
+ <section id="make_table_profile">
+ <title>Table Debugging - MAKE_TABLE_PROFILE</title>
+
+ <note>Provide diagnostic information about make_table() calls
+ which are possibly too small.</note>
+
+ <p>This requires a recent gcc which supports
+ <code>__builtin_return_address()</code>. The error_log output will
be a
+ message such as:</p>
+ <example>
+ table_push: apr_table_t created by 0x804d874 hit limit of 10
+ </example>
+
+ <p>Use <code>l *0x804d874</code> to find the
+ source that corresponds to. It indicates that a
<code>apr_table_t</code>
+ allocated by a call at that address has possibly too small an
+ initial <code>apr_table_t</code> size guess.</p>
+ </section>
+
+ <section id="alloc_stats">
+ <title>Allocation Statistics - ALLOC_STATS</title>
+
+ <note>Provide some statistics on the cost of allocations.</note>
+
+ <p>This requires a bit of an understanding of how
<code>alloc.c</code>
+ works.</p>
+ </section>
+</section>
+
+<section id="combo"><title>Allowable Combinations</title>
+
+ <p>Not all the options outlined above can be activated at the
+ same time. the following table gives more information.</p>
+
+ <table border="1" style="zebra">
+ <tr><th></th>
+ <th>ALLOC DEBUG</th>
+ <th>ALLOC USE MALLOC</th>
+ <th>POOL DEBUG</th>
+ <th>MAKE TABLE PROFILE</th>
+ <th>ALLOC STATS</th></tr>
+ <tr><th>ALLOC DEBUG</th>
+ <td>-</td><td>No</td><td>Yes</td><td>Yes</td><td>Yes</td></tr>
+ <tr><th>ALLOC USE MALLOC</th>
+ <td>No</td><td>-</td><td>No</td><td>No</td><td>No</td></tr>
+ <tr><th>POOL DEBUG</th>
+ <td>Yes</td><td>No</td><td>-</td><td>Yes</td><td>Yes</td></tr>
+ <tr><th>MAKE TABLE PROFILE</th>
+ <td>Yes</td><td>No</td><td>Yes</td><td>-</td><td>Yes</td></tr>
+ <tr><th>ALLOC STATS</th>
+ <td>Yes</td><td>No</td><td>Yes</td><td>Yes</td><td>-</td></tr>
+ </table>
+
+ <p>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.</p>
+</section>
+
+<section id="howto"><title>Activating Debugging Options</title>
+
+ <p>The various options for debugging memory are now enabled in
+ the <code>apr_general.h</code> 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
+ (<em>contained in srclib/apr/include/apr_pools.h</em>)</p>
+
+ <example>
+ /*<br />
+ #define ALLOC_DEBUG<br />
+ #define POOL_DEBUG<br />
+ #define ALLOC_USE_MALLOC<br />
+ #define MAKE_TABLE_PROFILE<br />
+ #define ALLOC_STATS<br />
+ */<br />
+ <br />
+ typedef struct ap_pool_t {<br />
+ <indent>
+ union block_hdr *first;<br />
+ union block_hdr *last;<br />
+ struct cleanup *cleanups;<br />
+ struct process_chain *subprocesses;<br />
+ struct ap_pool_t *sub_pools;<br />
+ struct ap_pool_t *sub_next;<br />
+ struct ap_pool_t *sub_prev;<br />
+ struct ap_pool_t *parent;<br />
+ char *free_first_avail;<br />
+ </indent>
+ #ifdef ALLOC_USE_MALLOC<br />
+ <indent>
+ void *allocation_list;<br />
+ </indent>
+ #endif<br />
+ #ifdef POOL_DEBUG<br />
+ <indent>
+ struct ap_pool_t *joined;<br />
+ </indent>
+ #endif<br />
+ <indent>
+ int (*apr_abort)(int retcode);<br />
+ struct datastruct *prog_data;<br />
+ </indent>
+ } ap_pool_t;
+ </example>
+
+ <p>To enable allocation debugging simply move the <code>#define
+ ALLOC_DEBUG</code> above the start of the comments block and rebuild
+ the server.</p>
+
+ <note><title>Note</title>
+ <p>In order to use the various options the server <strong>must</strong>
+ be rebuilt after editing the header file.</p>
+ </note>
+</section>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/debugging.xml.meta Sat Feb 26
23:20:49 2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="debugging.xml">
+ <basename>debugging</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/documenting.xml Sat Feb 26 23:20:49
2011
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="documenting.xml.meta">
+<parentdocument href="./">Developer Documentation</parentdocument>
+
+<title>Documenting Apache 2.0</title>
+
+<summary>
+ <p>Apache 2.0 uses <a href="http://www.doxygen.org/">Doxygen</a> to
+ document the APIs and global variables in the code. This will explain
+ the basics of how to document using Doxygen.</p>
+</summary>
+
+<section id="brief"><title>Brief Description</title>
+ <p>To start a documentation block, use <code>/**</code><br />
+ To end a documentation block, use <code>*/</code></p>
+
+ <p>In the middle of the block, there are multiple tags we can
+ use:</p>
+
+ <example>
+ Description of this functions purpose<br />
+ @param parameter_name description<br />
+ @return description<br />
+ @deffunc signature of the function<br />
+ </example>
+
+ <p>The <code>deffunc</code> 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 <code>deffunc</code>. An example (using &gt; rather
+ than >):</p>
+
+ <example>
+ /**<br />
+  * return the final element of the pathname<br />
+  * @param pathname The path to get the final element of<br />
+  * @return the final element of the path<br />
+  * @tip Examples:<br />
+  * <pre><br />
+  * "/foo/bar/gum" -&gt; "gum"<br />
+  * "/foo/bar/gum/" -&gt; ""<br />
+  * "gum" -&gt; "gum"<br />
+  * "wi\\n32\\stuff" -&gt; "stuff"<br />
+  * </pre><br />
+  * @deffunc const char * ap_filename_of_pathname(const char
*pathname)<br />
+  */
+ </example>
+
+ <p>At the top of the header file, always include:</p>
+ <example>
+ /**<br />
+  * @package Name of library header<br />
+  */
+ </example>
+
+ <p>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.</p>
+
+ <p>For a further discussion of the possibilities please refer to
+ <a href="http://www.doxygen.org/">the Doxygen site</a>.</p>
+</section>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/documenting.xml.meta Sat Feb 26
23:20:49 2011
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="documenting.xml">
+ <basename>documenting</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>zh-cn</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/documenting.xml.zh-cn Sat Feb 26
23:20:49 2011
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.zh-cn.xsl"?>
+
+
+
+
+<manualpage metafile="documenting.xml.meta">
+<parentdocument href="./">开发者文档</parentdocument>
+
+<title>Apache 2.0 文档</title>
+
+<summary>
+ <p>Apache 2.0 使用 <a href="http://www.doxygen.org/">Doxygen</a> 从代码
中
+ 生成 API 和全局变量的文档。下面是对使用 Doxygen 生成文档的简介。</p>
+</summary>
+
+<section id="brief"><title>简要说明</title>
+ <p>使用 <code>/**</code> 开始文档块<br />
+ 使用 <code>*/</code> 结束文档块</p>
+
+ <p>在文档块中，我们可以使用多个标签:</p>
+
+ <example>
+ Description of this functions purpose<br />
+ @param parameter_name description<br />
+ @return description<br />
+ @deffunc signature of the function<br />
+ </example>
+
+ <p>一般不需要 <code>deffunc</code> 。DoxyGen 没有完整的解析器，所以任何
+ 在返回类型声明中使用宏的原型，都是太复杂了。这些函数就需要使用
<code>deffunc</code>。
+ 例如 (使用 &gt; 而不是 >):</p>
+
+ <example>
+ /**<br />
+  * return the final element of the pathname<br />
+  * @param pathname The path to get the final element of<br />
+  * @return the final element of the path<br />
+  * @tip Examples:<br />
+  * <pre><br />
+  * "/foo/bar/gum" -&gt; "gum"<br />
+  * "/foo/bar/gum/" -&gt; ""<br />
+  * "gum" -&gt; "gum"<br />
+  * "wi\\n32\\stuff" -&gt; "stuff"<br />
+  * </pre><br />
+  * @deffunc const char * ap_filename_of_pathname(const char
*pathname)<br />
+  */
+ </example>
+
+ <p>总是在头文件开始包含:</p>
+ <example>
+ /**<br />
+  * @package Name of library header<br />
+  */
+ </example>
+
+ <p>Doxygen 为每个包生成一个新的 HTML 文件，名字是
+ {Name_of_library_header}.html，所以请简化名称。</p>
+
+ <p>更深入的讨论，请参见
+ <a href="http://www.doxygen.org/">Doxygen 站点</a>。</p>
+</section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/filters.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,209 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="filters.xml.meta">
+<parentdocument href="./">Developer Documentation</parentdocument>
+
+<title>How filters work in Apache 2.0</title>
+
+<summary>
+ <note type="warning"><title>Warning</title>
+ <p>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.</p>
+ </note>
+</summary>
+
+<section id="types"><title>Filter Types</title>
+ <p>There are three basic filter types (each of these is actually broken
+ down into two categories, but that comes later).</p>
+
+ <dl>
+ <dt><code>CONNECTION</code></dt>
+ <dd>Filters of this type are valid for the lifetime of this connection.
+ (<code>AP_FTYPE_CONNECTION</code>, <code>AP_FTYPE_NETWORK</code>)</dd>
+
+ <dt><code>PROTOCOL</code></dt>
+ <dd>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. (<code>AP_FTYPE_PROTOCOL</code>,
+ <code>AP_FTYPE_TRANSCODE</code>)</dd>
+
+ <dt><code>RESOURCE</code></dt>
+ <dd>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
+ <code>PROTOCOL</code>, but internal redirects and sub-requests can
change
+ the content without ending the request.
(<code>AP_FTYPE_RESOURCE</code>,
+ <code>AP_FTYPE_CONTENT_SET</code>)</dd>
+ </dl>
+
+ <p>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:</p>
+
+ <dl>
+ <dt>Byterange</dt>
+ <dd>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.</dd>
+
+ <dt>http_header</dt>
+ <dd>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.</dd>
+
+ <dt>Deflate</dt>
+ <dd>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.</dd>
+ </dl>
+
+ <p>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 <code>RESOURCE</code>
filters
+ only have one filter type, but that should change.</p>
+</section>
+
+<section id="howinserted"><title>How are filters inserted?</title>
+ <p>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
+ <code>r->output_filters</code>, then
<code>r->proto_output_filters</code>,
+ and finally <code>r->connection->output_filters</code>. These
correspond
+ to the <code>RESOURCE</code>, <code>PROTOCOL</code>, and
+ <code>CONNECTION</code> 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
+ <code>RESOURCE</code> filter on the stack, and I added a
+ <code>CONNECTION</code> filter, the <code>CONNECTION</code> filter
would
+ be ignored. This should make sense, because we would insert the
connection
+ filter at the top of the <code>c->output_filters</code> list, but the
end
+ of <code>r->output_filters</code> pointed to the filter that used to be
+ at the front of <code>c->output_filters</code>. 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.</p>
+
+ <p>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.</p>
+
+ <p>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
+ <code>make_sub_request</code> 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:</p>
+
+<example>
+<pre>
+Default_handler --> includes_filter --> byterange --> ...
+</pre>
+</example>
+
+ <p>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:</p>
+
+<example>
+<pre>
+Default_handler --> includes_filter -/-> byterange --> ...
+ /
+Default_handler --> sub_request_core
+</pre>
+</example>
+
+ <p>What happens if the subrequest is SSI data? Well, that's easy, the
+ <code>includes_filter</code> is a resource filter, so it will be added
to
+ the sub request in between the <code>Default_handler</code> and the
+ <code>sub_request_core</code> filter.</p>
+
+ <p>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 <code>make_sub_request</code> function.</p>
+
+ <p>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.</p>
+
+ <p>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.</p>
+
+ <p>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.</p>
+</section>
+
+<section id="asis"><title>Asis</title>
+ <p>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 <module>mod_asis</module>, all other
+ bets are off.</p>
+</section>
+
+<section id="conclusion"><title>Explanations</title>
+ <p>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
<code>reset_filters</code>
+ and <code>add_required_filters</code> 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 <code>HTTP_HEADER</code>, <code>Content-length</code>, and
+ <code>Byterange</code> filters are all added in the
+ <code>insert_filters</code> phase, because if they were added earlier,
we
+ had some interesting interactions. Now, those could all be moved to be
+ inserted with the <code>HTTP_IN</code>, <code>CORE</code>, and
+ <code>CORE_IN</code> filters. That would make the code easier to
+ follow.</p>
+</section>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/filters.xml.meta Sat Feb 26 23:20:49
2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="filters.xml">
+ <basename>filters</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/hooks.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,236 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="hooks.xml.meta">
+<parentdocument href="./">Developer Documentation</parentdocument>
+
+<title>Apache 2.0 Hook Functions</title>
+
+<summary>
+ <note type="warning"><title>Warning</title>
+ <p>This document is still in development and may be partially out of
+ date.</p>
+ </note>
+
+ <p>In general, a hook function is one that Apache will call at
+ some point during the processing of a request. Modules can
+ provide functions that are called, and specify when they get
+ called in comparison to other modules.</p>
+</summary>
+
+<section id="create"><title>Creating a hook function</title>
+ <p>In order to create a new hook, four things need to be
+ done:</p>
+
+ <section id="create-declare"><title>Declare the hook function</title>
+ <p>Use the <code>AP_DECLARE_HOOK</code> macro, which needs to be
given
+ the return type of the hook function, the name of the hook, and the
+ arguments. For example, if the hook returns an <code>int</code> and
+ takes a <code>request_rec *</code> and an <code>int</code> and is
+ called <code>do_something</code>, then declare it like this:</p>
+ <example>
+ AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n))
+ </example>
+
+ <p>This should go in a header which modules will include if
+ they want to use the hook.</p>
+ </section>
+
+ <section id="create-create"><title>Create the hook structure</title>
+ <p>Each source file that exports a hook has a private structure
+ which is used to record the module functions that use the hook.
+ This is declared as follows:</p>
+
+ <example>
+ APR_HOOK_STRUCT(<br />
+ <indent>
+ APR_HOOK_LINK(do_something)<br />
+ ...<br />
+ </indent>
+ )
+ </example>
+ </section>
+
+ <section id="create-implement"><title>Implement the hook caller</title>
+ <p>The source file that exports the hook has to implement a
+ function that will call the hook. There are currently three
+ possible ways to do this. In all cases, the calling function is
+ called <code>ap_run_<var>hookname</var>()</code>.</p>
+
+ <section><title>Void hooks</title>
+ <p>If the return value of a hook is <code>void</code>, then all the
+ hooks are called, and the caller is implemented like this:</p>
+
+ <example>
+ AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n),
(r, n))
+ </example>
+
+ <p>The second and third arguments are the dummy argument
+ declaration and the dummy arguments as they will be used when
+ calling the hook. In other words, this macro expands to
+ something like this:</p>
+
+ <example>
+ void ap_run_do_something(request_rec *r, int n)<br />
+ {<br />
+ <indent>
+ ...<br />
+ do_something(r, n);<br />
+ </indent>
+ }
+ </example>
+ </section>
+
+ <section><title>Hooks that return a value</title>
+ <p>If the hook returns a value, then it can either be run until
+ the first hook that does something interesting, like so:</p>
+
+ <example>
+ AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r,
int n), (r, n), DECLINED)
+ </example>
+
+ <p>The first hook that does <em>not</em> return
<code>DECLINED</code>
+ stops the loop and its return value is returned from the hook
+ caller. Note that <code>DECLINED</code> is the tradition Apache
+ hook return meaning "I didn't do anything", but it can be
+ whatever suits you.</p>
+
+ <p>Alternatively, all hooks can be run until an error occurs.
+ This boils down to permitting <em>two</em> return values, one of
+ which means "I did something, and it was OK" and the other
+ meaning "I did nothing". The first function that returns a
+ value other than one of those two stops the loop, and its
+ return is the return value. Declare these like so:</p>
+
+ <example>
+ AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r,
int n), (r, n), OK, DECLINED)
+ </example>
+
+ <p>Again, <code>OK</code> and <code>DECLINED</code> are the
traditional
+ values. You can use what you want.</p>
+ </section>
+ </section>
+
+ <section id="create-call"><title>Call the hook callers</title>
+ <p>At appropriate moments in the code, call the hook caller,
+ like so:</p>
+
+ <example>
+ int n, ret;<br />
+ request_rec *r;<br />
+ <br />
+ ret=ap_run_do_something(r, n);
+ </example>
+ </section>
+</section>
+
+<section id="hooking"><title>Hooking the hook</title>
+ <p>A module that wants a hook to be called needs to do two
+ things.</p>
+
+ <section id="hooking-implement"><title>Implement the hook
function</title>
+ <p>Include the appropriate header, and define a static function
+ of the correct type:</p>
+
+ <example>
+ static int my_something_doer(request_rec *r, int n)<br />
+ {<br />
+ <indent>
+ ...<br />
+ return OK;<br />
+ </indent>
+ }
+ </example>
+ </section>
+
+ <section id="hooking-add"><title>Add a hook registering
function</title>
+ <p>During initialisation, Apache will call each modules hook
+ registering function, which is included in the module
+ structure:</p>
+
+ <example>
+ static void my_register_hooks()<br />
+ {<br />
+ <indent>
+ ap_hook_do_something(my_something_doer, NULL, NULL,
APR_HOOK_MIDDLE);<br />
+ </indent>
+ }<br />
+ <br />
+ mode MODULE_VAR_EXPORT my_module =<br />
+ {<br />
+ <indent>
+ ...<br />
+ my_register_hooks /* register hooks */<br />
+ </indent>
+ };
+ </example>
+ </section>
+
+ <section id="hooking-order"><title>Controlling hook calling
order</title>
+ <p>In the example above, we didn't use the three arguments in
+ the hook registration function that control calling order.
+ There are two mechanisms for doing this. The first, rather
+ crude, method, allows us to specify roughly where the hook is
+ run relative to other modules. The final argument control this.
+ There are three possible values: <code>APR_HOOK_FIRST</code>,
+ <code>APR_HOOK_MIDDLE</code> and <code>APR_HOOK_LAST</code>.</p>
+
+ <p>All modules using any particular value may be run in any
+ order relative to each other, but, of course, all modules using
+ <code>APR_HOOK_FIRST</code> will be run before
<code>APR_HOOK_MIDDLE</code>
+ which are before <code>APR_HOOK_LAST</code>. Modules that don't care
+ when they are run should use <code>APR_HOOK_MIDDLE</code>. <em>(I
spaced
+ these out so people could do stuff like <code>APR_HOOK_FIRST-2</code>
+ to get in slightly earlier, but is this wise? - Ben)</em></p>
+
+ <p>Note that there are two more values,
+ <code>APR_HOOK_REALLY_FIRST</code> and
<code>APR_HOOK_REALLY_LAST</code>. These
+ should only be used by the hook exporter.</p>
+
+ <p>The other method allows finer control. When a module knows
+ that it must be run before (or after) some other modules, it
+ can specify them by name. The second (third) argument is a
+ NULL-terminated array of strings consisting of the names of
+ modules that must be run before (after) the current module. For
+ example, suppose we want "mod_xyz.c" and "mod_abc.c" to run
+ before we do, then we'd hook as follows:</p>
+
+ <example>
+ static void register_hooks()<br />
+ {<br />
+ <indent>
+ static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c",
NULL };<br />
+ <br />
+ ap_hook_do_something(my_something_doer, aszPre, NULL,
APR_HOOK_MIDDLE);<br />
+ </indent>
+ }
+ </example>
+
+ <p>Note that the sort used to achieve this is stable, so
+ ordering set by <code>APR_HOOK_<var>ORDER</var></code> is preserved,
as far
+ as is possible.</p>
+
+ <p class="cite"><cite>Ben Laurie</cite>, 15th August 1999</p>
+ </section>
+</section>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/hooks.xml.meta Sat Feb 26 23:20:49
2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="hooks.xml">
+ <basename>hooks</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/index.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="index.xml.meta">
+<parentdocument href="../" />
+
+<title>Developer Documentation for Apache 2.0</title>
+
+<summary>
+ <p>Many of the documents on these Developer pages are lifted
+ from Apache 1.3's documentation. While they are all being
+ updated to Apache 2, they are in different stages of
+ progress. Please be patient, and point out any discrepancies or
+ errors on the developer/ pages directly to the
+ <a href="http://httpd.apache.org/lists.html#http-dev"
+ >d...@httpd.apache.org</a> mailing list.</p>
+</summary>
+
+<section id="topics"><title>Topics</title>
+ <ul>
+ <li><a href="API.html">Apache 1.3 API Notes</a></li>
+ <li><a href="new_api_2_4.html">API changes in Apache 2.3/2.4</a></li>
+ <li><a href="hooks.html">Apache 2.x Hook Functions</a></li>
+ <li><a href="request.html">Request Processing in Apache 2.x</a></li>
+ <li><a href="filters.html">How filters work in Apache 2.x</a></li>
+ <li><a href="output-filters.html">Guidelines for output filters in
Apache 2.x</a></li>
+ <li><a href="modules.html">Converting Modules from Apache 1.3 to
Apache 2.x</a></li>
+ <li><a href="debugging.html">Debugging Memory Allocation in
APR</a></li>
+ <li><a href="documenting.html">Documenting Apache 2.x</a></li>
+ <li><a href="thread_safety.html">Apache 2.x Thread Safety
Issues</a></li>
+ </ul>
+</section>
+
+<section id="external"><title>External Resources</title>
+ <ul>
+ <li><a
+ href="http://ci.apache.org/projects/httpd/trunk/doxygen/"
+ >Autogenerated Apache HTTP Server (trunk) code
documentation</a></li>
+
+ <li>Module Development Tutorials by Kevin O'Donnell
+ <ul>
+ <li><a
+
href="http://threebit.net/tutorials/apache2_modules/tut1/tutorial1.html"
+ >Integrating a module into the Apache build system</a></li>
+
+ <li><a
+
href="http://threebit.net/tutorials/apache2_modules/tut2/tutorial2.html"
+ >Handling configuration directives</a></li>
+ </ul></li>
+
+ <li><a href="http://www.onlamp.com/pub/ct/38">Some notes on
+ Apache module development by Ryan Bloom</a></li>
+
+ <li>Developer articles at <a
href="http://www.apachetutor.org/">apachetutor</a> include:
+ <ul>
+ <li><a href="http://www.apachetutor.org/dev/request">Request
Processing in Apache</a></li>
+ <li><a href="http://www.apachetutor.org/dev/config">Configuration
for Modules</a></li>
+ <li><a href="http://www.apachetutor.org/dev/pools">Resource
Management in Apache</a></li>
+ <li><a href="http://www.apachetutor.org/dev/reslist">Connection
Pooling in Apache</a></li>
+ <li><a href="http://www.apachetutor.org/dev/brigades">Introduction
to Buckets and Brigades</a></li>
+ </ul></li>
+ </ul>
+</section>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/index.xml.meta Sat Feb 26 23:20:49
2011
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="index.xml">
+ <basename>index</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>zh-cn</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/index.xml.zh-cn Sat Feb 26 23:20:49
2011
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.zh-cn.xsl"?>
+
+
+
+
+<manualpage metafile="index.xml.meta">
+<parentdocument href="../" />
+
+<title>Apache 2.0 开发者文档</title>
+
+<summary>
+ <p>开发者页面的许多文档都来自于 Apache 1.3。当更新到 Apache 2
+ 时，它们可能位于不同的阶段。请耐心等待，或者直接向
+ <a href="http://httpd.apache.org/lists.html#http-dev"
+ >d...@httpd.apache.org</a> 邮件列表报告开发者页面的差异或错误。</p>
+</summary>
+
+<section id="topics"><title>主题</title>
+ <ul>
+ <li><a href="API.html">Apache 1.3 API 说明</a></li>
+ <li><a href="new_api_2_4.html">在 Apache 2.3/2.4 中的 API 改变
</a></li>
+ <li><a href="hooks.html">Apache 2.x 钩子函数</a></li>
+ <li><a href="request.html">Apache 2.x 中的请求处理</a></li>
+ <li><a href="filters.html">Apache 2.x 中的过滤器</a></li>
+ <li><a href="output-filters.html">Apache 2.x 中的输出过滤器指南
</a></li>
+ <li><a href="modules.html">将模块从 Apache 1.3 移植到 Apache
2.x</a></li>
+ <li><a href="debugging.html">在 APR 中调试内存分配</a></li>
+ <li><a href="documenting.html">Apache 2.x 文档</a></li>
+ <li><a href="thread_safety.html">Apache 2.x 的线程安全问题</a></li>
+ </ul>
+</section>
+
+<section id="external"><title>外部资源</title>
+ <ul>
+ <li><a
+ href="http://ci.apache.org/projects/httpd/trunk/doxygen/"
+ >自动生成的 Apache HTTP 服务器 (trunk) 代码文档</a></li>
+
+ <li>Kevin O'Donnell 的模块开发教程
+ <ul>
+ <li><a
+
href="http://threebit.net/tutorials/apache2_modules/tut1/tutorial1.html"
+ >集成模块到 Apache 构建系统</a></li>
+
+ <li><a
+
href="http://threebit.net/tutorials/apache2_modules/tut2/tutorial2.html"
+ >处理配置指令</a></li>
+ </ul></li>
+
+ <li><a href="http://www.onlamp.com/pub/ct/38">Ryan Bloom 对 Apache 模
块开发的说明</a></li>
+
+ <li>位于 <a href="http://www.apachetutor.org/">apachetutor</a> 的开发
者文章:
+ <ul>
+ <li><a href="http://www.apachetutor.org/dev/request">Apache 中的请
求处理</a></li>
+ <li><a href="http://www.apachetutor.org/dev/config">模块的配置
</a></li>
+ <li><a href="http://www.apachetutor.org/dev/pools">Apache 中的资源
管理</a></li>
+ <li><a href="http://www.apachetutor.org/dev/reslist">Apache 中的连
接池</a></li>
+ <li><a href="http://www.apachetutor.org/dev/brigades">桶与队列简介
</a></li>
+ </ul></li>
+ </ul>
+</section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/modules.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,282 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="modules.xml.meta">
+<parentdocument href="./">Developer Documentation</parentdocument>
+
+<title>Converting Modules from Apache 1.3 to Apache 2.0</title>
+
+<summary>
+ <p>This is a first attempt at writing the lessons I learned
+ when trying to convert the <code>mod_mmap_static</code> module to
Apache
+ 2.0. It's by no means definitive and probably won't even be
+ correct in some ways, but it's a start.</p>
+</summary>
+
+<section id="easy"><title>The easier changes ...</title>
+
+ <section id="cleanup"><title>Cleanup Routines</title>
+ <p>These now need to be of type <code>apr_status_t</code> and return
a
+ value of that type. Normally the return value will be
+ <code>APR_SUCCESS</code> unless there is some need to signal an
error in
+ the cleanup. Be aware that even though you signal an error not all
code
+ yet checks and acts upon the error.</p>
+ </section>
+
+ <section id="init"><title>Initialisation Routines</title>
+ <p>These should now be renamed to better signify where they sit
+ in the overall process. So the name gets a small change from
+ <code>mmap_init</code> to <code>mmap_post_config</code>. The
arguments
+ passed have undergone a radical change and now look like</p>
+
+ <ul>
+ <li><code>apr_pool_t *p</code></li>
+ <li><code>apr_pool_t *plog</code></li>
+ <li><code>apr_pool_t *ptemp</code></li>
+ <li><code>server_rec *s</code></li>
+ </ul>
+ </section>
+
+ <section id="datatypes"><title>Data Types</title>
+ <p>A lot of the data types have been moved into the <a
+ href="http://apr.apache.org/">APR</a>. This means that some have had
+ a name change, such as the one shown above. The following is a brief
+ list of some of the changes that you are likely to have to make.</p>
+
+ <ul>
+ <li><code>pool</code> becomes <code>apr_pool_t</code></li>
+ <li><code>table</code> becomes <code>apr_table_t</code></li>
+ </ul>
+ </section>
+</section>
+
+<section id="messy"><title>The messier changes...</title>
+
+ <section id="register-hooks"><title>Register Hooks</title>
+ <p>The new architecture uses a series of hooks to provide for
+ calling your functions. These you'll need to add to your module
+ by way of a new function, <code>static void
register_hooks(void)</code>.
+ The function is really reasonably straightforward once you
+ understand what needs to be done. Each function that needs
+ calling at some stage in the processing of a request needs to
+ be registered, handlers do not. There are a number of phases
+ where functions can be added, and for each you can specify with
+ a high degree of control the relative order that the function
+ will be called in.</p>
+
+ <p>This is the code that was added to
<code>mod_mmap_static</code>:</p>
+ <example><pre>
+static void register_hooks(void)
+{
+ static const char * const aszPre[]={ "http_core.c",NULL };
+ ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
+ ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
+};</pre>
+ </example>
+
+ <p>This registers 2 functions that need to be called, one in
+ the <code>post_config</code> stage (virtually every module will need
this
+ one) and one for the <code>translate_name</code> phase. note that
while
+ there are different function names the format of each is
+ identical. So what is the format?</p>
+
+ <example>
+ ap_hook_<var>phase_name</var>(<var>function_name</var>,
+ <var>predecessors</var>, <var>successors</var>,
<var>position</var>);
+ </example>
+
+ <p>There are 3 hook positions defined...</p>
+
+ <ul>
+ <li><code>HOOK_FIRST</code></li>
+ <li><code>HOOK_MIDDLE</code></li>
+ <li><code>HOOK_LAST</code></li>
+ </ul>
+
+ <p>To define the position you use the position and then modify
+ it with the predecessors and successors. Each of the modifiers
+ can be a list of functions that should be called, either before
+ the function is run (predecessors) or after the function has
+ run (successors).</p>
+
+ <p>In the <code>mod_mmap_static</code> case I didn't care about the
+ <code>post_config</code> stage, but the <code>mmap_static_xlat</code>
+ <strong>must</strong> be called after the core module had done it's
name
+ translation, hence the use of the aszPre to define a modifier to the
+ position <code>HOOK_LAST</code>.</p>
+ </section>
+
+ <section id="moddef"><title>Module Definition</title>
+ <p>There are now a lot fewer stages to worry about when
+ creating your module definition. The old defintion looked
+ like</p>
+
+ <example><pre>
+module MODULE_VAR_EXPORT <var>module_name</var>_module =
+{
+ STANDARD_MODULE_STUFF,
+ /* initializer */
+ /* dir config creater */
+ /* dir merger --- default is to override */
+ /* server config */
+ /* merge server config */
+ /* command handlers */
+ /* handlers */
+ /* filename translation */
+ /* check_user_id */
+ /* check auth */
+ /* check access */
+ /* type_checker */
+ /* fixups */
+ /* logger */
+ /* header parser */
+ /* child_init */
+ /* child_exit */
+ /* post read-request */
+};</pre>
+ </example>
+
+ <p>The new structure is a great deal simpler...</p>
+ <example><pre>
+module MODULE_VAR_EXPORT <var>module_name</var>_module =
+{
+ STANDARD20_MODULE_STUFF,
+ /* create per-directory config structures */
+ /* merge per-directory config structures */
+ /* create per-server config structures */
+ /* merge per-server config structures */
+ /* command handlers */
+ /* handlers */
+ /* register hooks */
+};</pre>
+ </example>
+
+ <p>Some of these read directly across, some don't. I'll try to
+ summarise what should be done below.</p>
+
+ <p>The stages that read directly across :</p>
+
+ <dl>
+ <dt><code>/* dir config creater */</code></dt>
+ <dd><code>/* create per-directory config structures */</code></dd>
+
+ <dt><code>/* server config */</code></dt>
+ <dd><code>/* create per-server config structures */</code></dd>
+
+ <dt><code>/* dir merger */</code></dt>
+ <dd><code>/* merge per-directory config structures */</code></dd>
+
+ <dt><code>/* merge server config */</code></dt>
+ <dd><code>/* merge per-server config structures */</code></dd>
+
+ <dt><code>/* command table */</code></dt>
+ <dd><code>/* command apr_table_t */</code></dd>
+
+ <dt><code>/* handlers */</code></dt>
+ <dd><code>/* handlers */</code></dd>
+ </dl>
+
+ <p>The remainder of the old functions should be registered as
+ hooks. There are the following hook stages defined so
+ far...</p>
+
+ <dl>
+ <dt><code>ap_hook_pre_config</code></dt>
+ <dd>do any setup required prior to processing configuration
+ directives</dd>
+
+ <dt><code>ap_hook_check_config</code></dt>
+ <dd>review configuration directive interdependencies</dd>
+
+ <dt><code>ap_hook_test_config</code></dt>
+ <dd>executes only with <code>-t</code> option</dd>
+
+ <dt><code>ap_hook_open_logs</code></dt>
+ <dd>open any specified logs</dd>
+
+ <dt><code>ap_hook_post_config</code></dt>
+ <dd>this is where the old <code>_init</code> routines get
+ registered</dd>
+
+ <dt><code>ap_hook_http_method</code></dt>
+ <dd>retrieve the http method from a request. (legacy)</dd>
+
+ <dt><code>ap_hook_auth_checker</code></dt>
+ <dd>check if the resource requires authorization</dd>
+
+ <dt><code>ap_hook_access_checker</code></dt>
+ <dd>check for module-specific restrictions</dd>
+
+ <dt><code>ap_hook_check_user_id</code></dt>
+ <dd>check the user-id and password</dd>
+
+ <dt><code>ap_hook_default_port</code></dt>
+ <dd>retrieve the default port for the server</dd>
+
+ <dt><code>ap_hook_pre_connection</code></dt>
+ <dd>do any setup required just before processing, but after
+ accepting</dd>
+
+ <dt><code>ap_hook_process_connection</code></dt>
+ <dd>run the correct protocol</dd>
+
+ <dt><code>ap_hook_child_init</code></dt>
+ <dd>call as soon as the child is started</dd>
+
+ <dt><code>ap_hook_create_request</code></dt>
+ <dd>??</dd>
+
+ <dt><code>ap_hook_fixups</code></dt>
+ <dd>last chance to modify things before generating content</dd>
+
+ <dt><code>ap_hook_handler</code></dt>
+ <dd>generate the content</dd>
+
+ <dt><code>ap_hook_header_parser</code></dt>
+ <dd>lets modules look at the headers, not used by most modules,
because
+ they use <code>post_read_request</code> for this</dd>
+
+ <dt><code>ap_hook_insert_filter</code></dt>
+ <dd>to insert filters into the filter chain</dd>
+
+ <dt><code>ap_hook_log_transaction</code></dt>
+ <dd>log information about the request</dd>
+
+ <dt><code>ap_hook_optional_fn_retrieve</code></dt>
+ <dd>retrieve any functions registered as optional</dd>
+
+ <dt><code>ap_hook_post_read_request</code></dt>
+ <dd>called after reading the request, before any other phase</dd>
+
+ <dt><code>ap_hook_quick_handler</code></dt>
+ <dd>called before any request processing, used by cache
modules.</dd>
+
+ <dt><code>ap_hook_translate_name</code></dt>
+ <dd>translate the URI into a filename</dd>
+
+ <dt><code>ap_hook_type_checker</code></dt>
+ <dd>determine and/or set the doc type</dd>
+ </dl>
+ </section>
+</section>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/modules.xml.meta Sat Feb 26 23:20:49
2011
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="modules.xml">
+ <basename>modules</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant outdated="yes">ja</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/new_api_2_4.xml Sat Feb 26 23:20:49
2011
@@ -0,0 +1,292 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+<manualpage metafile="new_api_2_4.xml.meta">
+
+<title>API Changes in Apache HTTP Server 2.4 since 2.2</title>
+
+<summary>
+ <p>This document describes changes to the Apache HTTPD API from
+ version 2.2 to 2.4, that may be of interest to module/application
+ developers and core hacks. At the time of writing, the 2.4 API
+ is not finalised, and this document may serve to highlight
+ points that call for further review.</p>
+ <p>API changes fall into two categories: APIs that are altogether new,
+ and existing APIs that are expanded or changed. The latter are
+ further divided into those where all changes are back-compatible
+ (so existing modules can ignore them), and those that might
+ require attention by maintainers. As with the transition from
+ HTTPD 2.0 to 2.2, existing modules and applications will require
+ recompiling and may call for some attention, but most should not
+ require any substantial updating (although some may be able to
+ take advantage of API changes to offer significant improvements).</p>
+ <p>For the purpose of this document, the API is split according
+ to the public header files. These headers are themselves the
+ reference documentation, and can be used to generate a browsable
+ HTML reference with <code>make docs</code>.</p>
+</summary>
+
+<section id="api_changes">
+ <title>Changed APIs</title>
+
+ <section id="ap_expr">
+ <title>ap_expr (NEW!)</title>
+ <p>Introduces a new API to parse and evaluate boolean and algebraic
+ expressions, including provision for a standard syntax and
+ customised variants.</p>
+ </section>
+
+ <section id="ap_listen">
+ <title>ap_listen (changed; back-compatible)</title>
+ <p>Introduces new API to enable apache child processes to serve
different purposes.</p>
+ </section>
+
+ <section id="ap_mpm">
+ <title>ap_mpm (changed)</title>
+ <p><code>ap_mpm_run</code> is replaced by a new <code>mpm</code> hook.
+ Also <code>ap_graceful_stop_signalled</code> is lost, and
+ <code>ap_mpm_register_timed_callback</code> is new.</p>
+ </section>
+
+ <section id="ap_regex">
+ <title>ap_regex (changed)</title>
+ <p>In addition to the existing regexp wrapper, a new higher-level API
+ <code>ap_rxplus</code> is now provided. This provides the capability to
+ compile Perl-style expressions like
<code>s/regexp/replacement/flags</code>
+ and to execute them against arbitrary strings. Support for regexp
+ backreference.</p>
+ </section>
+
+ <section id="ap_slotmem">
+ <title>ap_slotmem (NEW!)</title>
+ <p>Introduces an API for modules to allocate and manage memory slots
+ (normally) for shared memory.</p>
+ </section>
+
+ <section id="ap_socache">
+ <title>ap_socache (NEW!)</title>
+ <p>API to manage a shared object cache.</p>
+ </section>
+
+ <section id="heartbeat">
+ <title>heartbeat (NEW!)</title>
+ <p>common structures for heartbeat modules (should this be public
API?)</p>
+ </section>
+
+ <section id="http_config">
+ <title>http_config (changed)</title>
+ <ul>
+ <li>Introduces per-module, per-directory loglevels, including macro
wrappers.</li>
+ <li>New AP_DECLARE_MODULE macro to declare all modules.</li>
+ <li>New APLOG_USE_MODULE macro necessary for per-module loglevels in
+ multi-file modules.</li>
+ <li>New API to retain data across module unload/load</li>
+ <li>New check_config hook</li>
+ <li>New ap_process_fnmatch_configs() to process wildcards</li>
+ </ul>
+ </section>
+
+ <section id="http_core">
+ <title>http_core (changed)</title>
+ <ul>
+ <li>REMOVED ap_default_type, ap_requires, all 2.2 authnz API</li>
+ <li>Introduces Optional Functions for logio and authnz</li>
+ <li>New function ap_get_server_name_for_url to support ipv6
literals.</li>
+ <li>New function ap_register_errorlog_handler to register errorlog
+ format string handlers.</li>
+ <li>New function ap_state_query to determine if the server is in the
+ initial configuration preflight phase or not. This is both
easier to
+ use and more correct than the old method of creating a pool
userdata
+ entry in the process pool.</li>
+ </ul>
+ </section>
+
+ <section id="httpd">
+ <title>httpd (changed)</title>
+ <ul>
+ <li>Introduce per-directory, per-module loglevel</li>
+ <li>New loglevels APLOG_TRACEn</li>
+ <li>Introduce errorlog ids for requests and connections</li>
+ <li>Support for mod_request kept_body</li>
+ <li>Support buffering filter data for async requests</li>
+ <li>New CONN_STATE values</li>
+ <li>Function changes: ap_escape_html updated; ap_unescape_all,
ap_escape_path_segment_buffer</li>
+ </ul>
+ </section>
+
+ <section id="http_log">
+ <title>http_log (changed)</title>
+ <ul>
+ <li>Introduce per-directory, per-module loglevel</li>
+ <li>New loglevels APLOG_TRACEn</li>
+ <li>ap_log_*error become macro wrappers (fully back-compatible if
+ APLOG_MARK macro is used)</li>
+ <li>piped logging revamped</li>
+ <li>module_index added to error_log hook</li>
+ <li>new function: ap_log_command_line</li>
+ </ul>
+ </section>
+
+ <section id="http_request">
+ <title>http_request (changed)</title>
+ <ul>
+ <li>New auth_internal API and auth_provider API</li>
+ <li>New EOR bucket type</li>
+ <li>New function ap_process_async_request</li>
+ <li>New flags AP_AUTH_INTERNAL_PER_CONF and
AP_AUTH_INTERNAL_PER_URI</li>
+ <li>New access_checker_ex hook to apply additional access control
and/or
+ bypass authentication.</li>
+ <li>New functions ap_hook_check_access_ex, ap_hook_check_access,
+ ap_hook_check_authn, ap_hook_check_authz which accept
+ AP_AUTH_INTERNAL_PER_* flags</li>
+ <li>DEPRECATED direct use of ap_hook_access_checker,
access_checker_ex,
+ ap_hook_check_user_id, ap_hook_auth_checker</li>
+ </ul>
+ <p>When possible, registering all access control hooks (including
+ authentication and authorization hooks) using
AP_AUTH_INTERNAL_PER_CONF
+ is recommended. If all modules' access control hooks are registered
+ with this flag, then whenever the server handles an internal
+ sub-request that matches the same set of access control
configuration
+ directives as the initial request (which is the common case), it can
+ avoid invoking the access control hooks another time.</p>
+ <p>If your module requires the old behavior and must perform access
+ control checks on every sub-request with a different URI from the
+ initial request, even if that URI matches the same set of access
+ control configuration directives, then use
AP_AUTH_INTERNAL_PER_URI.</p>
+ </section>
+
+ <section id="mod_auth">
+ <title>mod_auth (NEW!)</title>
+ <p>Introduces the new provider framework for authn and authz</p>
+ </section>
+
+ <section id="mod_cache">
+ <title>mod_cache (changed)</title>
+ <p>Introduces a commit_entity() function to the cache provider
interface,
+ allowing atomic writes to cache. Add a cache_status() hook to report
+ the cache decision. Remove all private structures and functions from
the
+ public mod_cache.h header file.</p>
+ </section>
+
+ <section id="mod_core">
+ <title>mod_core (NEW!)</title>
+ <p>This introduces low-level APIs to send arbitrary headers,
+ and exposes functions to handle HTTP OPTIONS and TRACE.</p>
+ </section>
+
+ <section id="mod_cache_disk">
+ <title>mod_cache_disk (changed)</title>
+ <p>Changes the disk format of the disk cache to support atomic cache
+ updates without locking. The device/inode pair of the body file is
+ embedded in the header file, allowing confirmation that the header
+ and body belong to one another.</p>
+ </section>
+
+ <section id="mod_disk_cache">
+ <title>mod_disk_cache (renamed)</title>
+ <p>The mod_disk_cache module has been renamed to mod_cache_disk in
+ order to be consistent with the naming of other modules within the
+ server.</p>
+ </section>
+
+ <section id="mod_request">
+ <title>mod_request (NEW!)</title>
+ <p>The API for <module>mod_request</module>, to make input data
+ available to multiple application/handler modules where required,
+ and to parse HTML form data.</p>
+ </section>
+
+ <section id="mpm_common">
+ <title>mpm_common (changed)</title>
+ <ul>
+ <li>REMOVES: accept, lockfile, lock_mech, set_scoreboard (locking
uses the new ap_mutex API)</li>
+ <li>NEW API to drop privileges (delegates this platform-dependent
+ function to modules)</li>
+ <li>NEW Hooks: mpm_query, mpm_note_child_killed, timed_callback,
get_name, and function ap_mpm_note_child_killed</li>
+ </ul>
+ </section>
+
+ <section id="scoreboard">
+ <title>scoreboard (changed)</title>
+ <p>ap_get_scoreboard_worker is gratuitously made non-back-compatible
+ as an alternative version is introduced. Additional proxy_balancer
+ support. Child status stuff revamped.</p>
+ </section>
+
+ <section id="util_cookies">
+ <title>util_cookies (NEW!)</title>
+ <p>Introduces a new API for managing HTTP Cookies.</p>
+ </section>
+
+ <section id="util_ldap">
+ <title>util_ldap (changed)</title>
+ <p>I have yet to get a handle on this update.</p>
+ </section>
+
+ <section id="util_mutex">
+ <title>util_mutex (NEW!)</title>
+ <p>A wrapper for APR proc and global mutexes in httpd.</p>
+ </section>
+
+ <section id="util_script">
+ <title>util_script (changed)</title>
+ <p>NEW: ap_args_to_table</p>
+ </section>
+
+ <section id="util_time">
+ <title>util_time (changed)</title>
+ <p>NEW: ap_recent_ctime_ex</p>
+ </section>
+
+</section>
+
+<section id="upgrading">
+ <title>Specific information on upgrading modules from 2.2</title>
+
+ <section id="upgrading_logging">
+ <title>Logging</title>
+ <p>In order to take advantage of per-module loglevel configuration, any
+ source file that calls the <code>ap_log_*</code> functions should
declare
+ which module it belongs to. If the module's module_struct is called
+ <code>foo_module</code>, the following code can be used to remain
+ backward compatible with HTTPD 2.0 and 2.2:</p>
+ <example>
+ #include <http_log.h><br/>
+ <br/>
+ #ifdef APLOG_USE_MODULE<br/>
+ APLOG_USE_MODULE(foo);<br/>
+ #endif
+ </example>
+ <p>The number of parameters of the <code>ap_log_*</code> functions and
the
+ definition of <code>APLOG_MARK</code> has changed. Normally, the
change
+ is completely transparent. However, if a module implements wrapper
+ functions for <code>ap_log_*</code> and uses <code>APLOG_MARK</code>
+ when calling these wrappers, some adjustments are necessary.
+ The easiest way is for the module to define and use a different
macro
+ that expands to the parameters required by the log wrapper
functions.
+ <code>APLOG_MARK</code> should only be used when calling
+ <code>ap_log_*</code> without additional wrappers. In this way, the
+ code will remain compatible with HTTPD 2.0 and 2.2.</p>
+ </section>
+
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/new_api_2_4.xml.meta Sat Feb 26
23:20:49 2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="new_api_2_4.xml">
+ <basename>new_api_2_4</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/output-filters.xml Sat Feb 26
23:20:49 2011
@@ -0,0 +1,504 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="output-filters.xml.meta">
+ <parentdocument href="./">Developer Documentation</parentdocument>
+
+ <title>Guide to writing output filters</title>
+
+ <summary>
+ <p>There are a number of common pitfalls encountered when writing
+ output filters; this page aims to document best practice for
+ authors of new or existing filters.</p>
+
+ <p>This document is applicable to both version 2.0 and version 2.2
+ of the Apache HTTP Server; it specifically targets
+ <code>RESOURCE</code>-level or <code>CONTENT_SET</code>-level
+ filters though some advice is generic to all types of filter.</p>
+ </summary>
+
+ <section id="basics">
+ <title>Filters and bucket brigades</title>
+
+ <p>Each time a filter is invoked, it is passed a <em>bucket
+ brigade</em>, containing a sequence of <em>buckets</em> which
+ represent both data content and metadata. Every bucket has a
+ <em>bucket type</em>; a number of bucket types are defined and
+ used by the <code>httpd</code> core modules (and the
+ <code>apr-util</code> library which provides the bucket brigade
+ interface), but modules are free to define their own types.</p>
+
+ <note type="hint">Output filters must be prepared to process
+ buckets of non-standard types; with a few exceptions, a filter
+ need not care about the types of buckets being filtered.</note>
+
+ <p>A filter can tell whether a bucket represents either data or
+ metadata using the <code>APR_BUCKET_IS_METADATA</code> macro.
+ Generally, all metadata buckets should be passed down the filter
+ chain by an output filter. Filters may transform, delete, and
+ insert data buckets as appropriate.</p>
+
+ <p>There are two metadata bucket types which all filters must pay
+ attention to: the <code>EOS</code> bucket type, and the
+ <code>FLUSH</code> bucket type. An <code>EOS</code> bucket
+ indicates that the end of the response has been reached and no
+ further buckets need be processed. A <code>FLUSH</code> bucket
+ indicates that the filter should flush any buffered buckets (if
+ applicable) down the filter chain immediately.</p>
+
+ <note type="hint"><code>FLUSH</code> buckets are sent when the
+ content generator (or an upstream filter) knows that there may be
+ a delay before more content can be sent. By passing
+ <code>FLUSH</code> buckets down the filter chain immediately,
+ filters ensure that the client is not kept waiting for pending
+ data longer than necessary.</note>
+
+ <p>Filters can create <code>FLUSH</code> buckets and pass these
+ down the filter chain if desired. Generating <code>FLUSH</code>
+ buckets unnecessarily, or too frequently, can harm network
+ utilisation since it may force large numbers of small packets to
+ be sent, rather than a small number of larger packets. The
+ section on <a href="#nonblock">Non-blocking bucket reads</a>
+ covers a case where filters are encouraged to generate
+ <code>FLUSH</code> buckets.</p>
+
+ <example><title>Example bucket brigade</title>
+ HEAP FLUSH FILE EOS</example>
+
+ <p>This shows a bucket brigade which may be passed to a filter; it
+ contains two metadata buckets (<code>FLUSH</code> and
+ <code>EOS</code>), and two data buckets (<code>HEAP</code> and
+ <code>FILE</code>).</p>
+
+ </section>
+
+ <section id="invocation">
+ <title>Filter invocation</title>
+
+ <p>For any given request, an output filter might be invoked only
+ once and be given a single brigade representing the entire response.
+ It is also possible that the number of times a filter is invoked
+ for a single response is proportional to the size of the content
+ being filtered, with the filter being passed a brigade containing
+ a single bucket each time. Filters must operate correctly in
+ either case.</p>
+
+ <note type="warning">An output filter which allocates long-lived
+ memory every time it is invoked may consume memory proportional to
+ response size. Output filters which need to allocate memory
+ should do so once per response; see <a href="#state">Maintaining
+ state</a> below.</note>
+
+ <p>An output filter can distinguish the final invocation for a
+ given response by the presence of an <code>EOS</code> bucket in
+ the brigade. Any buckets in the brigade after an EOS should be
+ ignored.</p>
+
+ <p>An output filter should never pass an empty brigade down the
+ filter chain. To be defensive, filters should be prepared to
+ accept an empty brigade, and should return success without passing
+ this brigade on down the filter chain. The handling of an empty
+ brigade should have no side effects (such as changing any state
+ private to the filter).</p>
+
+ <example><title>How to handle an empty brigade</title>
+ apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)<br />
+ {<br />
+ <indent>
+ if (APR_BRIGADE_EMPTY(bb)) {<br />
+ <indent>
+ return APR_SUCCESS;<br />
+ </indent>
+ }<br />
+ ....<br />
+ </indent>
+ </example>
+
+ </section>
+
+ <section id="brigade">
+ <title>Brigade structure</title>
+
+ <p>A bucket brigade is a doubly-linked list of buckets. The list
+ is terminated (at both ends) by a <em>sentinel</em> which can be
+ distinguished from a normal bucket by comparing it with the
+ pointer returned by <code>APR_BRIGADE_SENTINEL</code>. The list
+ sentinel is in fact not a valid bucket structure; any attempt to
+ call normal bucket functions (such as
+ <code>apr_bucket_read</code>) on the sentinel will have undefined
+ behaviour (i.e. will crash the process).</p>
+
+ <p>There are a variety of functions and macros for traversing and
+ manipulating bucket brigades; see the <a
+
href="http://apr.apache.org/docs/apr-util/trunk/group___a_p_r___util___bucket___brigades.html">apr_bucket.h</a>
+ header for complete coverage. Commonly used macros include:</p>
+
+ <dl>
+ <dt><code>APR_BRIGADE_FIRST(bb)</code></dt>
+ <dd>returns the first bucket in brigade bb</dd>
+
+ <dt><code>APR_BRIGADE_LAST(bb)</code></dt>
+ <dd>returns the last bucket in brigade bb</dd>
+
+ <dt><code>APR_BUCKET_NEXT(e)</code></dt>
+ <dd>gives the next bucket after bucket e</dd>
+
+ <dt><code>APR_BUCKET_PREV(e)</code></dt>
+ <dd>gives the bucket before bucket e</dd>
+
+ </dl>
+
+ <p>The <code>apr_bucket_brigade</code> structure itself is
+ allocated out of a pool, so if a filter creates a new brigade, it
+ must ensure that memory use is correctly bounded. A filter which
+ allocates a new brigade out of the request pool
+ (<code>r->pool</code>) on every invocation, for example, will fall
+ foul of the <a href="#invocation">warning above</a> concerning
+ memory use. Such a filter should instead create a brigade on the
+ first invocation per request, and store that brigade in its <a
+ href="#state">state structure</a>.</p>
+
+ <note type="warning"><p>It is generally never advisable to use
+ <code>apr_brigade_destroy</code> to "destroy" a brigade unless
+ you know for certain that the brigade will never be used
+ again, even then, it should be used rarely. The
+ memory used by the brigade structure will not be released by
+ calling this function (since it comes from a pool), but the
+ associated pool cleanup is unregistered. Using
+ <code>apr_brigade_destroy</code> can in fact cause memory leaks;
+ if a "destroyed" brigade contains buckets when its
+ containing pool is destroyed, those buckets will <em>not</em> be
+ immediately destroyed.</p>
+
+ <p>In general, filters should use <code>apr_brigade_cleanup</code>
+ in preference to <code>apr_brigade_destroy</code>.</p></note>
+
+ </section>
+
+ <section id="buckets">
+
+ <title>Processing buckets</title>
+
+ <p>When dealing with non-metadata buckets, it is important to
+ understand that the "<code>apr_bucket *</code>" object is an
+ abstract <em>representation</em> of data:</p>
+
+ <ol>
+ <li>The amount of data represented by the bucket may or may not
+ have a determinate length; for a bucket which represents data of
+ indeterminate length, the <code>->length</code> field is set to
+ the value <code>(apr_size_t)-1</code>. For example, buckets of
+ the <code>PIPE</code> bucket type have an indeterminate length;
+ they represent the output from a pipe.</li>
+
+ <li>The data represented by a bucket may or may not be mapped
+ into memory. The <code>FILE</code> bucket type, for example,
+ represents data stored in a file on disk.</li>
+ </ol>
+
+ <p>Filters read the data from a bucket using the
+ <code>apr_bucket_read</code> function. When this function is
+ invoked, the bucket may <em>morph</em> into a different bucket
+ type, and may also insert a new bucket into the bucket brigade.
+ This must happen for buckets which represent data not mapped into
+ memory.</p>
+
+ <p>To give an example; consider a bucket brigade containing a
+ single <code>FILE</code> bucket representing an entire file, 24
+ kilobytes in size:</p>
+
+ <example>FILE(0K-24K)</example>
+
+ <p>When this bucket is read, it will read a block of data from the
+ file, morph into a <code>HEAP</code> bucket to represent that
+ data, and return the data to the caller. It also inserts a new
+ <code>FILE</code> bucket representing the remainder of the file;
+ after the <code>apr_bucket_read</code> call, the brigade looks
+ like:</p>
+
+ <example>HEAP(8K) FILE(8K-24K)</example>
+
+ </section>
+
+ <section id="filtering">
+ <title>Filtering brigades</title>
+
+ <p>The basic function of any output filter will be to iterate
+ through the passed-in brigade and transform (or simply examine)
+ the content in some manner. The implementation of the iteration
+ loop is critical to producing a well-behaved output filter.</p>
+
+ <p>Taking an example which loops through the entire brigade as
+ follows:</p>
+
+ <example><title>Bad output filter -- do not imitate!</title>
+ apr_bucket *e = APR_BRIGADE_FIRST(bb);<br />
+const char *data;<br />
+apr_size_t len;<br />
+<br />
+while (e != APR_BRIGADE_SENTINEL(bb)) {<br />
+<indent>
+ apr_bucket_read(e, &data, &length, APR_BLOCK_READ);<br />
+ e = APR_BUCKET_NEXT(e);<br />
+</indent>
+}<br />
+<br />
+return ap_pass_brigade(bb);
+ </example>
+
+ <p>The above implementation would consume memory proportional to
+ content size. If passed a <code>FILE</code> bucket, for example,
+ the entire file contents would be read into memory as each
+ <code>apr_bucket_read</code> call morphed a <code>FILE</code>
+ bucket into a <code>HEAP</code> bucket.</p>
+
+ <p>In contrast, the implementation below will consume a fixed
+ amount of memory to filter any brigade; a temporary brigade is
+ needed and must be allocated only once per response, see the <a
+ href="#state">Maintaining state</a> section.</p>
+
+ <example><title>Better output filter</title>
+apr_bucket *e;<br />
+const char *data;<br />
+apr_size_t len;<br />
+<br />
+while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {<br />
+<indent>
+ rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ);<br />
+ if (rv) ...;<br />
+ /* Remove bucket e from bb. */<br />
+ APR_BUCKET_REMOVE(e);<br />
+ /* Insert it into temporary brigade. */<br />
+ APR_BRIGADE_INSERT_HEAD(tmpbb, e);<br />
+ /* Pass brigade downstream. */<br />
+ rv = ap_pass_brigade(f->next, tmpbb);<br />
+ if (rv) ...;<br />
+ apr_brigade_cleanup(tmpbb);<br />
+</indent>
+}
+ </example>
+
+ </section>
+
+ <section id="state">
+
+ <title>Maintaining state</title>
+
+ <p>A filter which needs to maintain state over multiple
+ invocations per response can use the <code>->ctx</code> field of
+ its <code>ap_filter_t</code> structure. It is typical to store a
+ temporary brigade in such a structure, to avoid having to allocate
+ a new brigade per invocation as described in the <a
+ href="#brigade">Brigade structure</a> section.</p>
+
+ <example><title>Example code to maintain filter state</title>
+struct dummy_state {<br />
+<indent>
+ apr_bucket_brigade *tmpbb;<br />
+ int filter_state;<br />
+ ....<br />
+</indent>
+};<br />
+<br />
+apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)<br />
+{<br />
+<indent>
+ struct dummy_state *state;<br />
+<br />
+ state = f->ctx;<br />
+ if (state == NULL) {<br />
+ <indent>
+ /* First invocation for this response: initialise state structure.
+ */<br />
+ f->ctx = state = apr_palloc(sizeof *state, f->r->pool);<br />
+<br />
+ state->tmpbb = apr_brigade_create(f->r->pool,
f->c->bucket_alloc);<br />
+ state->filter_state = ...;<br />
+ </indent>
+ }<br />
+ ...
+</indent>
+ </example>
+
+ </section>
+
+ <section id="buffer">
+ <title>Buffering buckets</title>
+
+ <p>If a filter decides to store buckets beyond the duration of a
+ single filter function invocation (for example storing them in its
+ <code>->ctx</code> state structure), those buckets must be <em>set
+ aside</em>. This is necessary because some bucket types provide
+ buckets which represent temporary resources (such as stack memory)
+ which will fall out of scope as soon as the filter chain completes
+ processing the brigade.</p>
+
+ <p>To setaside a bucket, the <code>apr_bucket_setaside</code>
+ function can be called. Not all bucket types can be setaside, but
+ if successful, the bucket will have morphed to ensure it has a
+ lifetime at least as long as the pool given as an argument to the
+ <code>apr_bucket_setaside</code> function.</p>
+
+ <p>Alternatively, the <code>ap_save_brigade</code> function can be
+ used, which will move all the buckets into a separate brigade
+ containing buckets with a lifetime as long as the given pool
+ argument. This function must be used with care, taking into
+ account the following points:</p>
+
+ <ol>
+ <li>On return, <code>ap_save_brigade</code> guarantees that all
+ the buckets in the returned brigade will represent data mapped
+ into memory. If given an input brigade containing, for example,
+ a <code>PIPE</code> bucket, <code>ap_save_brigade</code> will
+ consume an arbitrary amount of memory to store the entire output
+ of the pipe.</li>
+
+ <li>When <code>ap_save_brigade</code> reads from buckets which
+ cannot be setaside, it will always perform blocking reads,
+ removing the opportunity to use <a href="#nonblock">Non-blocking
+ bucket reads</a>.</li>
+
+ <li>If <code>ap_save_brigade</code> is used without passing a
+ non-NULL "<code>saveto</code>" (destination) brigade parameter,
+ the function will create a new brigade, which may cause memory
+ use to be proportional to content size as described in the <a
+ href="#brigade">Brigade structure</a> section.</li>
+ </ol>
+
+ <note type="warning">Filters must ensure that any buffered data is
+ processed and passed down the filter chain during the last
+ invocation for a given response (a brigade containing an EOS
+ bucket). Otherwise such data will be lost.</note>
+
+ </section>
+
+ <section id="nonblock">
+ <title>Non-blocking bucket reads</title>
+
+ <p>The <code>apr_bucket_read</code> function takes an
+ <code>apr_read_type_e</code> argument which determines whether a
+ <em>blocking</em> or <em>non-blocking</em> read will be performed
+ from the data source. A good filter will first attempt to read
+ from every data bucket using a non-blocking read; if that fails
+ with <code>APR_EAGAIN</code>, then send a <code>FLUSH</code>
+ bucket down the filter chain, and retry using a blocking read.</p>
+
+ <p>This mode of operation ensures that any filters further down the
+ filter chain will flush any buffered buckets if a slow content
+ source is being used.</p>
+
+ <p>A CGI script is an example of a slow content source which is
+ implemented as a bucket type. <module>mod_cgi</module> will send
+ <code>PIPE</code> buckets which represent the output from a CGI
+ script; reading from such a bucket will block when waiting for the
+ CGI script to produce more output.</p>
+
+ <example>
+ <title>Example code using non-blocking bucket reads</title>
+apr_bucket *e;<br />
+apr_read_type_e mode = APR_NONBLOCK_READ;<br />
+<br />
+while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {<br />
+<indent>
+ apr_status_t rv;<br />
+<br />
+ rv = apr_bucket_read(e, &data, &length, mode);<br />
+ if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) {<br />
+ <indent>
+ /* Pass down a brigade containing a flush bucket: */<br />
+ APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...));<br />
+ rv = ap_pass_brigade(f->next, tmpbb);<br />
+ apr_brigade_cleanup(tmpbb);<br />
+ if (rv != APR_SUCCESS) return rv;<br />
+<br />
+ /* Retry, using a blocking read. */<br />
+ mode = APR_BLOCK_READ;<br />
+ continue;<br />
+ </indent>
+ } else if (rv != APR_SUCCESS) {<br />
+ <indent>
+ /* handle errors */<br />
+ </indent>
+ }<br />
+<br />
+ /* Next time, try a non-blocking read first. */<br />
+ mode = APR_NONBLOCK_READ;<br />
+ ...<br />
+</indent>
+}
+ </example>
+
+ </section>
+
+ <section id="rules">
+ <title>Ten rules for output filters</title>
+
+ <p>In summary, here is a set of rules for all output filters to
+ follow:</p>
+
+ <ol>
+ <li>Output filters should not pass empty brigades down the filter
+ chain, but should be tolerant of being passed empty
+ brigades.</li>
+
+ <li>Output filters must pass all metadata buckets down the filter
+ chain; <code>FLUSH</code> buckets should be respected by passing
+ any pending or buffered buckets down the filter chain.</li>
+
+ <li>Output filters should ignore any buckets following an
+ <code>EOS</code> bucket.</li>
+
+ <li>Output filters must process a fixed amount of data at a
+ time, to ensure that memory consumption is not proportional to
+ the size of the content being filtered.</li>
+
+ <li>Output filters should be agnostic with respect to bucket
+ types, and must be able to process buckets of unfamiliar
+ type.</li>
+
+ <li>After calling <code>ap_pass_brigade</code> to pass a brigade
+ down the filter chain, output filters should call
+ <code>apr_brigade_cleanup</code> to ensure the brigade is empty
+ before reusing that brigade structure; output filters should
+ never use <code>apr_brigade_destroy</code> to "destroy"
+ brigades.</li>
+
+ <li>Output filters must <em>setaside</em> any buckets which are
+ preserved beyond the duration of the filter function.</li>
+
+ <li>Output filters must not ignore the return value of
+ <code>ap_pass_brigade</code>, and must return appropriate errors
+ back up the filter chain.</li>
+
+ <li>Output filters must only create a fixed number of bucket
+ brigades for each response, rather than one per invocation.</li>
+
+ <li>Output filters should first attempt non-blocking reads from
+ each data bucket, and send a <code>FLUSH</code> bucket down the
+ filter chain if the read blocks, before retrying with a blocking
+ read.</li>
+
+ </ol>
+
+ </section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/output-filters.xml.meta Sat Feb 26
23:20:49 2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="output-filters.xml">
+ <basename>output-filters</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/request.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,220 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="request.xml.meta">
+<parentdocument href="./">Developer Documentation</parentdocument>
+
+<title>Request Processing in Apache 2.0</title>
+
+<summary>
+ <note type="warning"><title>Warning</title>
+ <p>Warning - this is a first (fast) draft that needs further
+ revision!</p>
+ </note>
+
+ <p>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.</p>
+
+ <p>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 <code>ap_process_request_internal()</code> to prevent
+ the code from falling out of sync again.</p>
+
+ <p>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.</p>
+</summary>
+
+<section id="processing"><title>The Request Processing Cycle</title>
+ <p>All requests pass through <code>ap_process_request_internal()</code>
+ in <code>request.c</code>, 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.</p>
+
+ <p>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.)</p>
+</section>
+
+<section id="parsing"><title>The Request Parsing Phase</title>
+ <section id="unescape"><title>Unescapes the URL</title>
+ <p>The request's <code>parsed_uri</code> path is unescaped, once and
only
+ once, at the beginning of internal request processing.</p>
+
+ <p>This step is bypassed if the proxyreq flag is set, or the
+ <code>parsed_uri.path</code> 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.</p>
+ </section>
+
+ <section id="strip"><title>Strips Parent and This Elements from the
+ URI</title>
+ <p>All <code>/../</code> and <code>/./</code> elements are
+ removed by <code>ap_getparents()</code>. This helps to ensure
+ the path is (nearly) absolute before the request processing
+ continues.</p>
+
+ <p>This step cannot be bypassed.</p>
+ </section>
+
+ <section id="inital-location-walk"><title>Initial URI Location
Walk</title>
+ <p>Every request is subject to an
+ <code>ap_location_walk()</code> call. This ensures that
+ <directive type="section" module="core">Location</directive> 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.</p>
+ </section>
+
+ <section id="translate_name"><title>translate_name</title>
+ <p>Modules can determine the file name, or alter the given URI
+ in this step. For example, <module>mod_vhost_alias</module> will
+ translate the URI's path into the configured virtual host,
+ <module>mod_alias</module> will translate the path to an alias path,
+ and if the request falls back on the core, the <directive
module="core"
+ >DocumentRoot</directive> is prepended to the request resource.</p>
+
+ <p>If all modules <code>DECLINE</code> this phase, an error 500 is
+ returned to the browser, and a "couldn't translate name" error is
logged
+ automatically.</p>
+ </section>
+
+ <section id="map_to_storage"><title>Hook: map_to_storage</title>
+ <p>After the file or correct URI was determined, the
+ appropriate per-dir configurations are merged together. For
+ example, <module>mod_proxy</module> compares and merges the
appropriate
+ <directive module="mod_proxy" type="section">Proxy</directive>
sections.
+ If the URI is nothing more than a local (non-proxy)
<code>TRACE</code>
+ request, the core handles the request and returns <code>DONE</code>.
+ If no module answers this hook with <code>OK</code> or
<code>DONE</code>,
+ the core will run the request filename against the <directive
+ module="core" type="section">Directory</directive> and <directive
+ module="core" type="section">Files</directive> sections. If the
request
+ 'filename' isn't an absolute, legal filename, a note is set for
+ later termination.</p>
+ </section>
+
+ <section id="location-walk"><title>URI Location Walk</title>
+ <p>Every request is hardened by a second
+ <code>ap_location_walk()</code> call. This reassures that a
+ translated request is still subjected to the configured
+ <directive module="core" type="section">Location</directive>
sections.
+ The request again borrows some or all of the processing from its
previous
+ <code>location_walk</code> above, so this step is almost always very
+ efficient unless the translated URI mapped to a substantially
different
+ path or Virtual Host.</p>
+ </section>
+
+ <section id="header_parser"><title>Hook: header_parser</title>
+ <p>The main request then parses the client's headers. This
+ prepares the remaining request processing steps to better serve
+ the client's request.</p>
+ </section>
+</section>
+
+<section id="security"><title>The Security Phase</title>
+ <p>Needs Documentation. Code is:</p>
+
+ <example><pre>
+ if ((access_status = ap_run_access_checker(r)) != 0) {
+ return decl_die(access_status, "check access", r);
+ }
+
+ if ((access_status = ap_run_check_user_id(r)) != 0) {
+ return decl_die(access_status, "check user", r);
+ }
+
+ if ((access_status = ap_run_auth_checker(r)) != 0) {
+ return decl_die(access_status, "check authorization", r);
+ }
+ </pre>
+ </example>
+</section>
+
+<section id="preparation"><title>The Preparation Phase</title>
+ <section id="type_checker"><title>Hook: type_checker</title>
+ <p>The modules have an opportunity to test the URI or filename
+ against the target resource, and set mime information for the
+ request. Both <module>mod_mime</module> and
+ <module>mod_mime_magic</module> 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.</p>
+
+ <p>If all modules <code>DECLINE</code> this phase, an error 500 is
+ returned to the browser, and a "couldn't find types" error is logged
+ automatically.</p>
+ </section>
+
+ <section id="fixups"><title>Hook: fixups</title>
+ <p>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.</p>
+ </section>
+</section>
+
+<section id="handler"><title>The Handler Phase</title>
+ <p>This phase is <strong>not</strong> part of the processing in
+ <code>ap_process_request_internal()</code>. Many
+ modules prepare one or more subrequests prior to creating any
+ content at all. After the core, or a module calls
+ <code>ap_process_request_internal()</code> it then calls
+ <code>ap_invoke_handler()</code> to generate the request.</p>
+
+ <section id="insert_filter"><title>Hook: insert_filter</title>
+ <p>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.</p>
+ </section>
+
+ <section id="hook_handler"><title>Hook: handler</title>
+ <p>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
<module>mod_autoindex</module>,
+ 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.</p>
+ </section>
+</section>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/request.xml.meta Sat Feb 26 23:20:49
2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="request.xml">
+ <basename>request</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/thread_safety.xml Sat Feb 26
23:20:49 2011
@@ -0,0 +1,287 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="thread_safety.xml.meta">
+<parentdocument href="./">Developer Documentation</parentdocument>
+
+<title>Apache 2.0 Thread Safety Issues</title>
+
+<summary>
+ <p>When using any of the threaded mpms in Apache 2.0 it is important
+ that every function called from Apache be thread safe. When linking
in 3rd
+ party extensions it can be difficult to determine whether the resulting
+ server will be thread safe. Casual testing generally won't tell you
this
+ either as thread safety problems can lead to subtle race conditons that
+ may only show up in certain conditions under heavy load.</p>
+</summary>
+
+<section id="variables"><title>Global and static variables</title>
+ <p>When writing your module or when trying to determine if a module or
+ 3rd party library is thread safe there are some common things to keep
in
+ mind.</p>
+
+ <p>First, you need to recognize that in a threaded model each
individual
+ thread has its own program counter, stack and registers. Local
variables
+ live on the stack, so those are fine. You need to watch out for any
+ static or global variables. This doesn't mean that you are absolutely
not
+ allowed to use static or global variables. There are times when you
+ actually want something to affect all threads, but generally you need
to
+ avoid using them if you want your code to be thread safe.</p>
+
+ <p>In the case where you have a global variable that needs to be
global and
+ accessed by all threads, be very careful when you update it. If, for
+ example, it is an incrementing counter, you need to atomically
increment
+ it to avoid race conditions with other threads. You do this using a
mutex
+ (mutual exclusion). Lock the mutex, read the current value, increment
it
+ and write it back and then unlock the mutex. Any other thread that
wants
+ to modify the value has to first check the mutex and block until it is
+ cleared.</p>
+
+ <p>If you are using <a href="http://apr.apache.org/">APR</a>, have a
look
+ at the <code>apr_atomic_<var>*</var></code> functions and the
+ <code>apr_thread_mutex_<var>*</var></code> functions.</p>
+ 
+</section>
+
+<section id="errno"><title>errno</title>
+ <p>This is a common global variable that holds the error number of the
+ last error that occurred. If one thread calls a low-level function that
+ sets errno and then another thread checks it, we are bleeding error
+ numbers from one thread into another. To solve this, make sure your
+ module or library defines <code>_REENTRANT</code> or is compiled with
+ <code>-D_REENTRANT</code>. This will make errno a per-thread variable
+ and should hopefully be transparent to the code. It does this by doing
+ something like this:</p>
+
+ <example>
+ #define errno (*(__errno_location()))
+ </example>
+
+ <p>which means that accessing errno will call
+ <code>__errno_location()</code> which is provided by the libc. Setting
+ <code>_REENTRANT</code> also forces redefinition of some other
functions
+ to their <code><var>*</var>_r</code> equivalents and sometimes changes
+ the common <code>getc</code>/<code>putc</code> macros into safer
function
+ calls. Check your libc documentation for specifics. Instead of, or in
+ addition to <code>_REENTRANT</code> the symbols that may affect this
are
+ <code>_POSIX_C_SOURCE</code>, <code>_THREAD_SAFE</code>,
+ <code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p>
+</section>
+
+<section id="functions"><title>Common standard troublesome
functions</title>
+ <p>Not only do things have to be thread safe, but they also have to be
+ reentrant. <code>strtok()</code> is an obvious one. You call it the
first
+ time with your delimiter which it then remembers and on each subsequent
+ call it returns the next token. Obviously if multiple threads are
+ calling it you will have a problem. Most systems have a reentrant
version
+ of of the function called <code>strtok_r()</code> where you pass in an
+ extra argument which contains an allocated <code>char *</code> which
the
+ function will use instead of its own static storage for maintaining
+ the tokenizing state. If you are using <a href="http://apr.apache.org/"
+ >APR</a> you can use <code>apr_strtok()</code>.</p>
+
+ <p><code>crypt()</code> is another function that tends to not be
reentrant,
+ so if you run across calls to that function in a library, watch out. On
+ some systems it is reentrant though, so it is not always a problem. If
+ your system has <code>crypt_r()</code> chances are you should be using
+ that, or if possible simply avoid the whole mess by using md5
instead.</p>
+ 
+</section>
+
+<section id="commonlibs"><title>Common 3rd Party Libraries</title>
+ <p>The following is a list of common libraries that are used by 3rd
party
+ Apache modules. You can check to see if your module is using a
potentially
+ unsafe library by using tools such as <code>ldd(1)</code> and
+ <code>nm(1)</code>. For <a href="http://www.php.net/">PHP</a>, for
example,
+ try this:</p>
+
+ <example>
+ % ldd libphp4.so<br />
+ libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)<br />
+ libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)<br />
+ libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)<br />
+ libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)<br />
+ libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)<br />
+ libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)<br />
+ libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11
(0x40411000)<br />
+ libming.so => /usr/lib/libming.so (0x40449000)<br />
+ libm.so.6 => /lib/libm.so.6 (0x40487000)<br />
+ libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)<br />
+ libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)<br />
+ libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)<br />
+ libssl.so.2 => /lib/libssl.so.2 (0x40532000)<br />
+ libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)<br />
+ libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)<br />
+ libdl.so.2 => /lib/libdl.so.2 (0x40634000)<br />
+ libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)<br />
+ libc.so.6 => /lib/libc.so.6 (0x4064b000)<br />
+ /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)
+ </example>
+
+ <p>In addition to these libraries you will need to have a look at any
+ libraries linked statically into the module. You can use
<code>nm(1)</code>
+ to look for individual symbols in the module.</p>
+</section>
+
+<section id="liblist"><title>Library List</title>
+ <p>Please drop a note to <a
+
href="http://httpd.apache.org/lists.html#http-dev">d...@httpd.apache.org</a>
+ if you have additions or corrections to this list.</p>
+
+ <table style="zebra" border="1">
+ <tr><th>Library</th><th>Version</th><th>Thread
Safe?</th><th>Notes</th></tr>
+ <tr><td><a href="http://aspell.sourceforge.net/">ASpell/PSpell</a></td>
+ <td> </td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://www.sleepycat.com/">Berkeley DB</a></td>
+ <td>3.x, 4.x</td>
+ <td>Yes</td>
+ <td>Be careful about sharing a connection across threads.</td></tr>
+ <tr><td><a
href="http://sources.redhat.com/bzip2/index.html">bzip2</a></td>
+ <td> </td>
+ <td>Yes</td>
+ <td>Both low-level and high-level APIs are thread-safe. However,
+ high-level API requires thread-safe access to errno.</td></tr>
+ <tr><td><a href="http://cr.yp.to/cdb.html">cdb</a></td>
+ <td> </td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://www.washington.edu/imap/">C-Client</a></td>
+ <td> </td>
+ <td>Perhaps</td>
+ <td>c-client uses <code>strtok()</code> and
+ <code>gethostbyname()</code> which are not thread-safe on most C
+ library implementations. c-client's static data is meant to be
shared
+ across threads. If <code>strtok()</code> and
+ <code>gethostbyname()</code> are thread-safe on your OS, c-client
+ <em>may</em> be thread-safe.</td></tr>
+ <tr><td><a href="http://www.ijg.org/files/">libcrypt</a></td>
+ <td> </td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://expat.sourceforge.net/">Expat</a></td>
+ <td> </td>
+ <td>Yes</td>
+ <td>Need a separate parser instance per thread</td></tr>
+ <tr><td><a href="http://www.freetds.org/">FreeTDS</a></td>
+ <td> </td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://www.freetype.org/">FreeType</a></td>
+ <td> </td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://www.boutell.com/gd/">GD 1.8.x</a></td>
+ <td> </td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://www.boutell.com/gd/">GD 2.0.x</a></td>
+ <td> </td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a
href="http://www.gnu.org/software/gdbm/gdbm.html">gdbm</a></td>
+ <td> </td>
+ <td>No</td>
+ <td>Errors returned via a static <code>gdbm_error</code>
+ variable</td></tr>
+ <tr><td><a href="http://www.imagemagick.org/">ImageMagick</a></td>
+ <td>5.2.2</td>
+ <td>Yes</td>
+ <td>ImageMagick docs claim it is thread safe since version 5.2.2
(see <a
+ href="http://www.imagemagick.com/www/changelog.html"
+ >Change log</a>).
+ </td></tr>
+ <tr><td><a
href="http://www.enlightenment.org/p.php?p=about/efl&l=en"
+ >Imlib2</a></td>
+ <td> </td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://www.ijg.org/files/">libjpeg</a></td>
+ <td>v6b</td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://mysql.com">libmysqlclient</a></td>
+ <td> </td>
+ <td>Yes</td>
+ <td>Use mysqlclient_r library variant to ensure thread-safety. For
+ more information, please read <a
+ href="http://dev.mysql.com/doc/mysql/en/Threaded_clients.html"
+
>http://dev.mysql.com/doc/mysql/en/Threaded_clients.html</a>.</td></tr>
+ <tr><td><a href="http://www.opaque.net/ming/">Ming</a></td>
+ <td>0.2a</td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://net-snmp.sourceforge.net/">Net-SNMP</a></td>
+ <td>5.0.x</td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://www.openldap.org/">OpenLDAP</a></td>
+ <td>2.1.x</td>
+ <td>Yes</td>
+ <td>Use <code>ldap_r</code> library variant to ensure
+ thread-safety.</td></tr>
+ <tr><td><a href="http://www.openssl.org/">OpenSSL</a></td>
+ <td>0.9.6g</td>
+ <td>Yes</td>
+ <td>Requires proper usage of <code>CRYPTO_num_locks</code>,
+ <code>CRYPTO_set_locking_callback</code>,
+ <code>CRYPTO_set_id_callback</code></td></tr>
+ <tr><td><a href="http://www.oracle.com/">liboci8 (Oracle 8+)</a></td>
+ <td>8.x,9.x</td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a href="http://pdflib.com/">pdflib</a></td>
+ <td>5.0.x</td>
+ <td>Yes</td>
+ <td>PDFLib docs claim it is thread safe; changes.txt indicates it
+ has been partially thread-safe since V1.91: <a
+ href="http://www.pdflib.com/products/pdflib-family/pdflib/"
+
>http://www.pdflib.com/products/pdflib-family/pdflib/</a>.</td></tr>
+ <tr><td><a
href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
+ <td>1.0.x</td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a
href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
+ <td>1.2.x</td>
+ <td>?</td>
+ <td> </td></tr>
+ <tr><td><a
+
href="http://www.postgresql.org/docs/8.4/static/libpq-threading.html"
+ >libpq (PostgreSQL)</a></td>
+ <td>8.x</td>
+ <td>Yes</td>
+ <td>Don't share connections across threads and watch out for
+ <code>crypt()</code> calls</td></tr>
+ <tr><td><a href="http://www.gingerall.com/charlie/ga/xml/p_sab.xml"
+ >Sablotron</a></td>
+ <td>0.95</td>
+ <td>?</td>
+ <td></td></tr>
+ <tr><td><a href="http://www.gzip.org/zlib/">zlib</a></td>
+ <td>1.1.4</td>
+ <td>Yes</td>
+ <td>Relies upon thread-safe zalloc and zfree functions Default is
to
+ use libc's calloc/free which are thread-safe.</td></tr>
+ </table>
+</section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/developer/thread_safety.xml.meta Sat Feb 26
23:20:49 2011
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="thread_safety.xml">
+ <basename>thread_safety</basename>
+ <path>/developer/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/dns-caveats.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="dns-caveats.xml.meta">
+
+ <title>Issues Regarding DNS and Apache HTTP Server</title>
+
+ <summary>
+ <p>This page could be summarized with the statement: don't
+ configure Apache HTTP Server in such a way that it relies on DNS
resolution
+ for parsing of the configuration files. If httpd requires DNS
+ resolution to parse the configuration files then your server
+ may be subject to reliability problems (ie. it might not start up),
+ or denial and theft of service attacks (including virtual hosts able
+ to steal hits from other virtual hosts).</p>
+ </summary>
+
+ <section id="example">
+ <title>A Simple Example</title>
+
+ <example>
+ # This is a misconfiguration example, do not use on your server <br
/>
+ <VirtualHost www.example.dom> <br />
+ ServerAdmin web...@example.dom <br />
+ DocumentRoot /www/example <br />
+ </VirtualHost>
+ </example>
+
+ <p>In order for the server to function properly, it absolutely needs
+ to have two pieces of information about each virtual host: the
+ <directive module="core">ServerName</directive> and at least one
+ IP address that the server will bind and respond to. The above
+ example does not include the IP address, so httpd must use DNS
+ to find the address of <code>www.example.dom</code>. If for some
+ reason DNS is not available at the time your server is parsing
+ its config file, then this virtual host <strong>will not be
+ configured</strong>. It won't be able to respond to any hits
+ to this virtual host.</p>
+
+ <p>Suppose that <code>www.example.dom</code> has address 192.0.2.1.
+ Then consider this configuration snippet:</p>
+
+ <example>
+ # This is a misconfiguration example, do not use on your server <br
/>
+ <VirtualHost 192.0.2.1> <br />
+ ServerAdmin web...@example.dom <br />
+ DocumentRoot /www/example <br />
+ </VirtualHost>
+ </example>
+
+ <p>This time httpd needs to use reverse DNS to find the
+ <code>ServerName</code> for this virtualhost. If that reverse
+ lookup fails then it will partially disable the virtualhost.
+ If the virtual host is name-based then it will effectively be
+ totally disabled, but if it is IP-based then it will mostly
+ work. However, if httpd should ever have to generate a full
+ URL for the server which includes the server name (such as when a
+ Redirect is issued), then it will fail to generate a valid URL.</p>
+
+ <p>Here is a snippet that avoids both of these problems:</p>
+
+ <example>
+ <VirtualHost 192.0.2.1> <br />
+ ServerName www.example.dom <br />
+ ServerAdmin web...@example.dom <br />
+ DocumentRoot /www/example <br />
+ </VirtualHost>
+ </example>
+ </section>
+
+ <section id="denial">
+ <title>Denial of Service</title>
+
+ <p>Consider this configuration snippet:</p>
+
+ <example>
+ <VirtualHost www.example1.dom><br />
+ <indent>
+ ServerAdmin web...@example1.dom<br />
+ DocumentRoot /www/example1<br />
+ </indent>
+ </VirtualHost><br />
+ <br />
+ <VirtualHost www.example2.dom><br />
+ <indent>
+ ServerAdmin web...@example2.dom<br />
+ DocumentRoot /www/example2<br />
+ </indent>
+ </VirtualHost>
+ </example>
+
+ <p>Suppose that you've assigned 192.0.2.1 to
+ <code>www.example1.dom</code> and 192.0.2.2 to
+ <code>www.example2.dom</code>. Furthermore, suppose that
+ <code>example1.dom</code> has control of their own DNS. With this
+ config you have put <code>example1.dom</code> into a position where
+ they can steal all traffic destined to <code>example2.dom</code>. To
+ do so, all they have to do is set <code>www.example1.dom</code> to
+ 192.0.2.2. Since they control their own DNS you can't stop them
+ from pointing the <code>www.example1.dom</code> record wherever they
+ wish.</p>
+
+ <p>Requests coming in to 192.0.2.2 (including all those where
+ users typed in URLs of the form
+ <code>http://www.example2.dom/whatever</code>) will all be served by
+ the <code>example1.dom</code> virtual host. To better understand why
+ this happens requires a more in-depth discussion of how httpd
+ matches up incoming requests with the virtual host that will
+ serve it. A rough document describing this <a
+ href="vhosts/details.html">is available</a>.</p>
+ </section>
+
+ <section id="main">
+ <title>The "main server" Address</title>
+
+ <p><a href="vhosts/name-based.html">Name-based
+ virtual host support</a> requires httpd to know
+ the IP address(es) of the host that <program>httpd</program>
+ is running on. To get this address it uses either the global
+ <directive module="core">ServerName</directive>
+ (if present) or calls the C function <code>gethostname</code>
+ (which should return the same as typing "hostname" at the
+ command prompt). Then it performs a DNS lookup on this address.
+ At present there is no way to avoid this lookup.</p>
+
+ <p>If you fear that this lookup might fail because your DNS
+ server is down then you can insert the hostname in
+ <code>/etc/hosts</code> (where you probably already have it so
+ that the machine can boot properly). Then ensure that your
+ machine is configured to use <code>/etc/hosts</code> in the
+ event that DNS fails. Depending on what OS you are using this
+ might be accomplished by editing <code>/etc/resolv.conf</code>,
+ or maybe <code>/etc/nsswitch.conf</code>.</p>
+
+ <p>If your server doesn't have to perform DNS for any other
+ reason then you might be able to get away with running httpd
+ with the <code>HOSTRESORDER</code> environment variable set to
+ "local". This all depends on what OS and resolver libraries you
+ are using. It also affects CGIs unless you use
+ <module>mod_env</module> to control the environment. It's best
+ to consult the man pages or FAQs for your OS.</p>
+ </section>
+
+ <section id="tips">
+ <title>Tips to Avoid These Problems</title>
+
+ <ul>
+ <li>
+ use IP addresses in
+ <directive module="core">VirtualHost</directive>
+ </li>
+
+ <li>
+ use IP addresses in
+ <directive module="mpm_common">Listen</directive>
+ </li>
+
+ <li>
+ ensure all virtual hosts have an explicit
+ <directive module="core">ServerName</directive>
+ </li>
+
+ <li>create a <code><VirtualHost _default_:*></code>
+ server that has no pages to serve</li>
+ </ul>
+ </section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/dns-caveats.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="dns-caveats.xml">
+ <basename>dns-caveats</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">ja</variant>
+ <variant outdated="yes">ko</variant>
+ <variant outdated="yes">tr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/dso.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,288 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="dso.xml.meta">
+
+ <title>Dynamic Shared Object (DSO) Support</title>
+
+ <summary>
+ <p>The Apache HTTP Server is a modular program where the
+ administrator can choose the functionality to include in the
+ server by selecting a set of modules.
+ Modules will be compiled as Dynamic Shared Objects (DSOs)
+ that exist separately from the main <program>httpd</program>
+ binary file. DSO modules may be compiled at the time the server
+ is built, or they may be compiled and added at a later time
+ using the Apache Extension Tool (<program>apxs</program>).</p>
+ <p>Alternatively, the modules can be statically compiled into
+ the <program>httpd</program> binary when the server is built.</p>
+
+ <p>This document describes how to use DSO modules as well as
+ the theory behind their use.</p>
+ </summary>
+
+
+<section id="implementation"><title>Implementation</title>
+
+<related>
+<modulelist>
+<module>mod_so</module>
+</modulelist>
+<directivelist>
+<directive module="mod_so">LoadModule</directive>
+</directivelist>
+</related>
+
+ <p>The DSO support for loading individual Apache httpd modules is based
+ on a module named <module>mod_so</module> which must be statically
+ compiled into the Apache httpd core. It is the only module besides
+ <module>core</module> which cannot be put into a DSO
+ itself. Practically all other distributed Apache httpd modules will
then
+ be placed into a DSO. After a module is compiled into a DSO named
+ <code>mod_foo.so</code> you can use <module>mod_so</module>'s
<directive
+ module="mod_so">LoadModule</directive> directive in your
+ <code>httpd.conf</code> file to load this module at server startup
+ or restart.</p>
+ <p>The DSO builds for individual modules can be disabled via
+ <program>configure</program>'s <code>--enable-mods-static</code>
+ option as discussed in the <a href="install.html">install
+ documentation</a>.</p>
+
+ <p>To simplify this creation of DSO files for Apache httpd modules
+ (especially for third-party modules) a support program
+ named <program>apxs</program> (<dfn>APache
+ eXtenSion</dfn>) is available. It can be used to build DSO based
+ modules <em>outside of</em> the Apache httpd source tree. The idea is
+ simple: When installing Apache HTTP Server the
<program>configure</program>'s
+ <code>make install</code> procedure installs the Apache httpd C
+ header files and puts the platform-dependent compiler and
+ linker flags for building DSO files into the <program>apxs</program>
+ program. This way the user can use <program>apxs</program> to compile
+ his Apache httpd module sources without the Apache httpd distribution
+ source tree and without having to fiddle with the
+ platform-dependent compiler and linker flags for DSO
+ support.</p>
+</section>
+
+<section id="usage"><title>Usage Summary</title>
+
+ <p>To give you an overview of the DSO features of Apache HTTP Server
2.x,
+ here is a short and concise summary:</p>
+
+ <ol>
+ <li>
+ <p>Build and install a <em>distributed</em> Apache httpd module,
say
+ <code>mod_foo.c</code>, into its own DSO
+ <code>mod_foo.so</code>:</p>
+
+<example>
+$ ./configure --prefix=/path/to/install --enable-foo<br />
+$ make install
+</example>
+ </li>
+
+ <li>
+ <p>Configure Apache HTTP Server with all modules enabled, and loaded
+ as shared objects. You can then remove individual ones by
+ commenting out the <directive
+ module="mod_so">LoadModule</directive> directives in
+ <code>httpd.conf</code>.</p>
+
+<example>
+$ ./configure --enable-mods-shared=all<br />
+$ make install
+</example>
+ </li>
+
+ <li>
+ Build and install a <em>third-party</em> Apache httpd module, say
+ <code>mod_foo.c</code>, into its own DSO
+ <code>mod_foo.so</code> <em>outside of</em> the Apache httpd
+ source tree using <program>apxs</program>:
+
+<example>
+$ cd /path/to/3rdparty<br />
+$ apxs -cia mod_foo.c
+</example>
+ </li>
+ </ol>
+
+ <p>In all cases, once the shared module is compiled, you must
+ use a <directive module="mod_so">LoadModule</directive>
+ directive in <code>httpd.conf</code> to tell Apache httpd to activate
+ the module.</p>
+
+ <p>See the <a href="programs/apxs.html">apxs documentation</a> for
more details.</p>
+</section>
+
+<section id="background"><title>Background</title>
+
+ <p>On modern Unix derivatives there exists a mechanism
+ called dynamic linking/loading of <em>Dynamic Shared
+ Objects</em> (DSO) which provides a way to build a piece of
+ program code in a special format for loading it at run-time
+ into the address space of an executable program.</p>
+
+ <p>This loading can usually be done in two ways: automatically
+ by a system program called <code>ld.so</code> when an
+ executable program is started or manually from within the
+ executing program via a programmatic system interface to the
+ Unix loader through the system calls
+ <code>dlopen()/dlsym()</code>.</p>
+
+ <p>In the first way the DSO's are usually called <em>shared
+ libraries</em> or <em>DSO libraries</em> and named
+ <code>libfoo.so</code> or <code>libfoo.so.1.2</code>. They
+ reside in a system directory (usually <code>/usr/lib</code>)
+ and the link to the executable program is established at
+ build-time by specifying <code>-lfoo</code> to the linker
+ command. This hard-codes library references into the executable
+ program file so that at start-time the Unix loader is able to
+ locate <code>libfoo.so</code> in <code>/usr/lib</code>, in
+ paths hard-coded via linker-options like <code>-R</code> or in
+ paths configured via the environment variable
+ <code>LD_LIBRARY_PATH</code>. It then resolves any (yet
+ unresolved) symbols in the executable program which are
+ available in the DSO.</p>
+
+ <p>Symbols in the executable program are usually not referenced
+ by the DSO (because it's a reusable library of general code)
+ and hence no further resolving has to be done. The executable
+ program has no need to do anything on its own to use the
+ symbols from the DSO because the complete resolving is done by
+ the Unix loader. (In fact, the code to invoke
+ <code>ld.so</code> is part of the run-time startup code which
+ is linked into every executable program which has been bound
+ non-static). The advantage of dynamic loading of common library
+ code is obvious: the library code needs to be stored only once,
+ in a system library like <code>libc.so</code>, saving disk
+ space for every program.</p>
+
+ <p>In the second way the DSO's are usually called <em>shared
+ objects</em> or <em>DSO files</em> and can be named with an
+ arbitrary extension (although the canonical name is
+ <code>foo.so</code>). These files usually stay inside a
+ program-specific directory and there is no automatically
+ established link to the executable program where they are used.
+ Instead the executable program manually loads the DSO at
+ run-time into its address space via <code>dlopen()</code>. At
+ this time no resolving of symbols from the DSO for the
+ executable program is done. But instead the Unix loader
+ automatically resolves any (yet unresolved) symbols in the DSO
+ from the set of symbols exported by the executable program and
+ its already loaded DSO libraries (especially all symbols from
+ the ubiquitous <code>libc.so</code>). This way the DSO gets
+ knowledge of the executable program's symbol set as if it had
+ been statically linked with it in the first place.</p>
+
+ <p>Finally, to take advantage of the DSO's API the executable
+ program has to resolve particular symbols from the DSO via
+ <code>dlsym()</code> for later use inside dispatch tables
+ <em>etc.</em> In other words: The executable program has to
+ manually resolve every symbol it needs to be able to use it.
+ The advantage of such a mechanism is that optional program
+ parts need not be loaded (and thus do not spend memory) until
+ they are needed by the program in question. When required,
+ these program parts can be loaded dynamically to extend the
+ base program's functionality.</p>
+
+ <p>Although this DSO mechanism sounds straightforward there is
+ at least one difficult step here: The resolving of symbols from
+ the executable program for the DSO when using a DSO to extend a
+ program (the second way). Why? Because "reverse resolving" DSO
+ symbols from the executable program's symbol set is against the
+ library design (where the library has no knowledge about the
+ programs it is used by) and is neither available under all
+ platforms nor standardized. In practice the executable
+ program's global symbols are often not re-exported and thus not
+ available for use in a DSO. Finding a way to force the linker
+ to export all global symbols is the main problem one has to
+ solve when using DSO for extending a program at run-time.</p>
+
+ <p>The shared library approach is the typical one, because it
+ is what the DSO mechanism was designed for, hence it is used
+ for nearly all types of libraries the operating system
+ provides.</p>
+
+</section>
+
+<section id="advantages"><title>Advantages and Disadvantages</title>
+
+ <p>The above DSO based features have the following
+ advantages:</p>
+
+ <ul>
+ <li>The server package is more flexible at run-time because
+ the server process can be assembled at run-time via
+ <directive module="mod_so">LoadModule</directive>
+ <code>httpd.conf</code> configuration directives instead of
+ <program>configure</program> options at build-time. For instance,
+ this way one is able to run different server instances
+ (standard & SSL version, minimalistic & dynamic
+ version [mod_perl, mod_php], <em>etc.</em>) with only one Apache
httpd
+ installation.</li>
+
+ <li>The server package can be easily extended with
+ third-party modules even after installation. This is
+ a great benefit for vendor package maintainers, who can create
+ an Apache httpd core package and additional packages containing
+ extensions like PHP, mod_perl, mod_security, <em>etc.</em></li>
+
+ <li>Easier Apache httpd module prototyping, because with the
+ DSO/<program>apxs</program> pair you can both work outside the
+ Apache httpd source tree and only need an <code>apxs -i</code>
+ command followed by an <code>apachectl restart</code> to
+ bring a new version of your currently developed module into
+ the running Apache HTTP Server.</li>
+ </ul>
+
+ <p>DSO has the following disadvantages:</p>
+
+ <ul>
+ <li>The server is approximately 20% slower at startup time
+ because of the symbol resolving overhead the Unix loader now
+ has to do.</li>
+
+ <li>The server is approximately 5% slower at execution time
+ under some platforms, because position independent code (PIC)
+ sometimes needs complicated assembler tricks for relative
+ addressing, which are not necessarily as fast as absolute
+ addressing.</li>
+
+ <li>Because DSO modules cannot be linked against other
+ DSO-based libraries (<code>ld -lfoo</code>) on all platforms
+ (for instance a.out-based platforms usually don't provide
+ this functionality while ELF-based platforms do) you cannot
+ use the DSO mechanism for all types of modules. Or in other
+ words, modules compiled as DSO files are restricted to only
+ use symbols from the Apache httpd core, from the C library
+ (<code>libc</code>) and all other dynamic or static libraries
+ used by the Apache httpd core, or from static library archives
+ (<code>libfoo.a</code>) containing position independent code.
+ The only chances to use other code is to either make sure the
+ httpd core itself already contains a reference to it or
+ loading the code yourself via <code>dlopen()</code>.</li>
+ </ul>
+
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/dso.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="dso.xml">
+ <basename>dso</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">ja</variant>
+ <variant outdated="yes">ko</variant>
+ <variant outdated="yes">tr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/env.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,534 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="env.xml.meta">
+
+ <title>Environment Variables in Apache</title>
+
+ <summary>
+ <p>There are two kinds of environment variables that affect
+ the Apache HTTP Server.</p>
+
+ <p>First, there are the environment variables controlled by
+ the underlying operating system. These are set before the
+ server starts. They can be used in expansions in configuration
+ files, and can optionally be passed to CGI scripts and SSI
+ using the PassEnv directive.</p>
+
+ <p>Second, the Apache HTTP Server provides a mechanism for storing
+ information in named variables that are also called <em>environment
+ variables</em>. This information can be used to control various
+ operations such as logging or access control. The variables are
+ also used as a mechanism to communicate with external programs
+ such as CGI scripts. This document discusses different ways to
+ manipulate and use these variables.</p>
+
+ <p>Although these variables are referred to as <em>environment
+ variables</em>, they are not the same as the environment
+ variables controlled by the underlying operating system.
+ Instead, these variables are stored and manipulated in an
+ internal Apache structure. They only become actual operating
+ system environment variables when they are provided to CGI
+ scripts and Server Side Include scripts. If you wish to
+ manipulate the operating system environment under which the
+ server itself runs, you must use the standard environment
+ manipulation mechanisms provided by your operating system
+ shell.</p>
+ </summary>
+
+ <section id="setting">
+ <title>Setting Environment Variables</title>
+ <related>
+ <modulelist>
+ <module>mod_cache</module>
+ <module>mod_env</module>
+ <module>mod_rewrite</module>
+ <module>mod_setenvif</module>
+ <module>mod_unique_id</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_setenvif">BrowserMatch</directive>
+ <directive module="mod_setenvif">BrowserMatchNoCase</directive>
+ <directive module="mod_env">PassEnv</directive>
+ <directive module="mod_rewrite">RewriteRule</directive>
+ <directive module="mod_env">SetEnv</directive>
+ <directive module="mod_setenvif">SetEnvIf</directive>
+ <directive module="mod_setenvif">SetEnvIfNoCase</directive>
+ <directive module="mod_env">UnsetEnv</directive>
+ </directivelist>
+ </related>
+
+ <section id="basic-manipulation">
+ <title>Basic Environment Manipulation</title>
+
+ <p>The most basic way to set an environment variable in Apache
+ is using the unconditional <directive module="mod_env"
+ >SetEnv</directive> directive. Variables may also be passed from
+ the environment of the shell which started the server using the
+ <directive module="mod_env">PassEnv</directive> directive.</p>
+
+ </section>
+ <section id="conditional">
+ <title>Conditional Per-Request Settings</title>
+
+ <p>For additional flexibility, the directives provided by
+ <module>mod_setenvif</module> allow environment variables to be set
+ on a per-request basis, conditional on characteristics of
particular
+ requests. For example, a variable could be set only when a
+ specific browser (User-Agent) is making a request, or only when
+ a specific Referer [sic] header is found. Even more flexibility
+ is available through the <module>mod_rewrite</module>'s <directive
+ module="mod_rewrite">RewriteRule</directive> which uses the
+ <code>[E=...]</code> option to set environment variables.</p>
+
+ </section>
+ <section id="unique-identifiers">
+ <title>Unique Identifiers</title>
+
+ <p>Finally, <module>mod_unique_id</module> sets the environment
+ variable <code>UNIQUE_ID</code> for each request to a value which
is
+ guaranteed to be unique across "all" requests under very
+ specific conditions.</p>
+
+ </section>
+ <section id="standard-cgi">
+ <title>Standard CGI Variables</title>
+
+ <p>In addition to all environment variables set within the
+ Apache configuration and passed from the shell, CGI scripts and
+ SSI pages are provided with a set of environment variables
+ containing meta-information about the request as required by
+ the <a href="http://www.ietf.org/rfc/rfc3875">CGI
+ specification</a>.</p>
+
+ </section>
+ <section id="caveats">
+ <title>Some Caveats</title>
+
+ <ul>
+ <li>It is not possible to override or change the standard CGI
+ variables using the environment manipulation directives.</li>
+
+ <li>When <program>suexec</program> is used to launch
+ CGI scripts, the environment will be cleaned down to a set of
+ <em>safe</em> variables before CGI scripts are launched. The
+ list of <em>safe</em> variables is defined at compile-time in
+ <code>suexec.c</code>.</li>
+
+ <li>For portability reasons, the names of environment
+ variables may contain only letters, numbers, and the
+ underscore character. In addition, the first character may
+ not be a number. Characters which do not match this
+ restriction will be replaced by an underscore when passed to
+ CGI scripts and SSI pages.</li>
+
+ <li>A special case are HTTP headers which are passed to CGI
+ scripts and the like via environment variables (see below).
+ They are converted to uppercase and only dashes are replaced with
+ underscores; if the header contains any other (invalid)
character,
+ the whole header is silently dropped. See <a href="#fixheader">
+ below</a> for a workaround.</li>
+
+ <li>The <directive module="mod_env">SetEnv</directive> directive
runs
+ late during request processing meaning that directives such as
+ <directive module="mod_setenvif">SetEnvIf</directive> and
<directive
+ module="mod_rewrite">RewriteCond</directive> will not see the
+ variables set with it.</li>
+ </ul>
+ </section>
+ </section>
+ <section id="using">
+ <title>Using Environment Variables</title>
+
+ <related>
+ <modulelist>
+ <module>mod_authz_host</module>
+ <module>mod_cgi</module>
+ <module>mod_ext_filter</module>
+ <module>mod_headers</module>
+ <module>mod_include</module>
+ <module>mod_log_config</module>
+ <module>mod_rewrite</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_authz_host">Allow</directive>
+ <directive module="mod_log_config">CustomLog</directive>
+ <directive module="mod_authz_host">Deny</directive>
+ <directive module="mod_ext_filter">ExtFilterDefine</directive>
+ <directive module="mod_headers">Header</directive>
+ <directive module="mod_log_config">LogFormat</directive>
+ <directive module="mod_rewrite">RewriteCond</directive>
+ <directive module="mod_rewrite">RewriteRule</directive>
+ </directivelist>
+ </related>
+
+ <section id="cgi-scripts">
+ <title>CGI Scripts</title>
+
+ <p>One of the primary uses of environment variables is to
+ communicate information to CGI scripts. As discussed above, the
+ environment passed to CGI scripts includes standard
+ meta-information about the request in addition to any variables
+ set within the Apache configuration. For more details, see the
+ <a href="howto/cgi.html">CGI tutorial</a>.</p>
+
+ </section>
+ <section id="ssi-pages">
+ <title>SSI Pages</title>
+
+ <p>Server-parsed (SSI) documents processed by
+ <module>mod_include</module>'s
+ <code>INCLUDES</code> filter can print environment variables
+ using the <code>echo</code> element, and can use environment
+ variables in flow control elements to makes parts of a page
+ conditional on characteristics of a request. Apache also
+ provides SSI pages with the standard CGI environment variables
+ as discussed above. For more details, see the <a
+ href="howto/ssi.html">SSI tutorial</a>.</p>
+
+ </section>
+ <section id="access-control">
+ <title>Access Control</title>
+
+ <p>Access to the server can be controlled based on the value of
+ environment variables using the <code>allow from env=</code>
+ and <code>deny from env=</code> directives. In combination with
+ <directive module="mod_setenvif">SetEnvIf</directive>, this
+ allows for flexible control of access to the server based on
+ characteristics of the client. For example, you can use these
+ directives to deny access to a particular browser (User-Agent).
+ </p>
+
+ </section>
+ <section id="logging">
+ <title>Conditional Logging</title>
+
+ <p>Environment variables can be logged in the access log using
+ the <directive module="mod_log_config">LogFormat</directive>
+ option <code>%e</code>. In addition, the decision on whether
+ or not to log requests can be made based on the status of
+ environment variables using the conditional form of the
+ <directive module="mod_log_config">CustomLog</directive>
+ directive. In combination with <directive module="mod_setenvif"
+ >SetEnvIf</directive> this allows for flexible control of which
+ requests are logged. For example, you can choose not to log
+ requests for filenames ending in <code>gif</code>, or you can
+ choose to only log requests from clients which are outside your
+ subnet.</p>
+
+ </section>
+ <section id="response-headers">
+ <title>Conditional Response Headers</title>
+
+ <p>The <directive module="mod_headers">Header</directive>
+ directive can use the presence or
+ absence of an environment variable to determine whether or not
+ a certain HTTP header will be placed in the response to the
+ client. This allows, for example, a certain response header to
+ be sent only if a corresponding header is received in the
+ request from the client.</p>
+
+ </section>
+
+ <section id="external-filter">
+ <title>External Filter Activation</title>
+
+ <p>External filters configured by <module>mod_ext_filter</module>
+ using the <directive
+ module="mod_ext_filter">ExtFilterDefine</directive> directive can
+ by activated conditional on an environment variable using the
+ <code>disableenv=</code> and <code>enableenv=</code> options.</p>
+ </section>
+
+ <section id="url-rewriting">
+ <title>URL Rewriting</title>
+
+ <p>The <code>%{ENV:<em>variable</em>}</code> form of
+ <em>TestString</em> in the <directive module="mod_rewrite"
+ >RewriteCond</directive> allows <module>mod_rewrite</module>'s
rewrite
+ engine to make decisions conditional on environment variables.
+ Note that the variables accessible in <module>mod_rewrite</module>
+ without the <code>ENV:</code> prefix are not actually environment
+ variables. Rather, they are variables special to
+ <module>mod_rewrite</module> which cannot be accessed from other
+ modules.</p>
+ </section>
+ </section>
+
+ <section id="special">
+ <title>Special Purpose Environment Variables</title>
+
+ <p>Interoperability problems have led to the introduction of
+ mechanisms to modify the way Apache behaves when talking to
+ particular clients. To make these mechanisms as flexible as
+ possible, they are invoked by defining environment variables,
+ typically with <directive module="mod_setenvif"
+ >BrowserMatch</directive>, though <directive module="mod_env"
+ >SetEnv</directive> and <directive module="mod_env"
+ >PassEnv</directive> could also be used, for example.</p>
+
+ <section id="downgrade">
+ <title>downgrade-1.0</title>
+
+ <p>This forces the request to be treated as a HTTP/1.0 request
+ even if it was in a later dialect.</p>
+
+ </section>
+ <section id="force-gzip">
+ <title>force-gzip</title>
+ <p>If you have the <code>DEFLATE</code> filter activated, this
+ environment variable will ignore the accept-encoding setting of
+ your browser and will send compressed output unconditionally.</p>
+ </section>
+ <section id="force-no-vary">
+ <title>force-no-vary</title>
+
+ <p>This causes any <code>Vary</code> fields to be removed from
+ the response header before it is sent back to the client. Some
+ clients don't interpret this field correctly; setting this
+ variable can work around this problem. Setting this variable
+ also implies <strong>force-response-1.0</strong>.</p>
+
+ </section>
+ <section id="force-response">
+ <title>force-response-1.0</title>
+
+ <p>This forces an HTTP/1.0 response to clients making an HTTP/1.0
+ request. It was originally
+ implemented as a result of a problem with AOL's proxies. Some
+ HTTP/1.0 clients may not behave correctly when given an HTTP/1.1
+ response, and this can be used to interoperate with them.</p>
+
+ </section>
+
+ <section id="gzip-only-text-html">
+ <title>gzip-only-text/html</title>
+
+ <p>When set to a value of "1", this variable disables the
+ <code>DEFLATE</code> output filter provided by
+ <module>mod_deflate</module> for content-types other than
+ <code>text/html</code>. If you'd rather
+ use statically compressed files, <module>mod_negotiation</module>
+ evaluates the variable as well (not only for gzip, but for all
+ encodings that differ from "identity").</p>
+ </section>
+
+ <section id="no-gzip"><title>no-gzip</title>
+
+ <p>When set, the <code>DEFLATE</code> filter of
+ <module>mod_deflate</module> will be turned off and
+ <module>mod_negotiation</module> will refuse to deliver encoded
+ resources.</p>
+
+ </section>
+
+ <section id="no-cache"><title>no-cache</title>
+ <p><em>Available in versions 2.2.12 and later</em></p>
+
+ <p>When set, <module>mod_cache</module> will not save an otherwise
+ cacheable response. This environment variable does not influence
+ whether a response already in the cache will be served for the
current
+ request.</p>
+
+ </section>
+
+ <section id="nokeepalive">
+ <title>nokeepalive</title>
+
+ <p>This disables <directive module="core">KeepAlive</directive>
+ when set.</p>
+
+ </section>
+
+ <section id="prefer-language"><title>prefer-language</title>
+
+ <p>This influences <module>mod_negotiation</module>'s behaviour. If
+ it contains a language tag (such as <code>en</code>,
<code>ja</code>
+ or <code>x-klingon</code>), <module>mod_negotiation</module> tries
+ to deliver a variant with that language. If there's no such
variant,
+ the normal <a href="content-negotiation.html">negotiation</a>
process
+ applies.</p>
+
+ </section>
+
+ <section id="redirect-carefully">
+ <title>redirect-carefully</title>
+
+ <p>This forces the server to be more careful when sending a
redirect
+ to the client. This is typically used when a client has a known
+ problem handling redirects. This was originally implemented as a
+ result of a problem with Microsoft's WebFolders software which has
+ a problem handling redirects on directory resources via DAV
+ methods.</p>
+
+ </section>
+
+ <section id="suppress-error-charset">
+ <title>suppress-error-charset</title>
+
+ <p><em>Available in versions after 2.0.54</em></p>
+
+ <p>When Apache issues a redirect in response to a client request,
+ the response includes some actual text to be displayed in case
+ the client can't (or doesn't) automatically follow the redirection.
+ Apache ordinarily labels this text according to the character set
+ which it uses, which is ISO-8859-1.</p>
+
+ <p> However, if the redirection is to a page that uses a different
+ character set, some broken browser versions will try to use the
+ character set from the redirection text rather than the actual page.
+ This can result in Greek, for instance, being incorrectly rendered.</p>
+
+ <p>Setting this environment variable causes Apache to omit the
character
+ set for the redirection text, and these broken browsers will then
correctly
+ use that of the destination page.</p>
+
+ <note type="warning">
+ <title>Security note</title>
+
+ <p>Sending error pages without a specified character set may
+ allow a cross-site-scripting attack for existing browsers (MSIE)
+ which do not follow the HTTP/1.1 specification and attempt to
+ "guess" the character set from the content. Such browsers can
+ be easily fooled into using the UTF-7 character set, and UTF-7
+ content from input data (such as the request-URI) will not be
+ escaped by the usual escaping mechanisms designed to prevent
+ cross-site-scripting attacks.</p>
+ </note>
+
+ </section>
+
+ <section id="proxy"><title>force-proxy-request-1.0, proxy-nokeepalive,
proxy-sendchunked,
+ proxy-sendcl, proxy-chain-auth, proxy-interim-response,
proxy-initial-not-pooled</title>
+
+ <p>These directives alter the protocol behavior of
+ <module>mod_proxy</module>. See the <module>mod_proxy</module> and
<module>mod_proxy_http</module>
+ documentation for more details.</p>
+ </section>
+
+ </section>
+
+ <section id="examples">
+ <title>Examples</title>
+
+ <section id="fixheader">
+ <title>Passing broken headers to CGI scripts</title>
+
+ <p>Starting with version 2.4, Apache is more strict about how HTTP
+ headers are converted to environment variables in <module>mod_cgi
+ </module> and other modules: Previously any invalid characters
+ in header names were simply translated to underscores. This allowed
+ for some potential cross-site-scripting attacks via header injection
+ (see <a
href="http://events.ccc.de/congress/2007/Fahrplan/events/2212.en.html">
+ Unusual Web Bugs</a>, slide 19/20).</p>
+
+ <p>If you have to support a client which sends broken headers and
+ which can't be fixed, a simple workaround involving
<module>mod_setenvif
+ </module> and <module>mod_header</module> allows you to still accept
+ these headers:</p>
+
+<example>
+# <br />
+# The following works around a client sending a broken Accept_Encoding<br
/>
+# header.<br />
+#<br />
+SetEnvIfNoCase ^Accept.Encoding$ ^(.*)$ fix_accept_encoding=$1<br />
+RequestHeader set Accept-Encoding %{fix_accept_encoding}e
env=fix_accept_encoding
+</example>
+
+ </section>
+
+ <section id="misbehaving">
+ <title>Changing protocol behavior with misbehaving clients</title>
+
+ <p>Earlier versions recommended that the following lines be
included in
+ httpd.conf to deal with known client problems. Since the affected
clients
+ are no longer seen in the wild, this configuration is likely
no-longer
+ necessary.</p>
+<example>
+#<br />
+# The following directives modify normal HTTP response behavior.<br />
+# The first directive disables keepalive for Netscape 2.x and browsers
that<br />
+# spoof it. There are known problems with these browser
implementations.<br />
+# The second directive is for Microsoft Internet Explorer 4.0b2<br />
+# which has a broken HTTP/1.1 implementation and does not properly<br />
+# support keepalive when it is used on 301 or 302 (redirect) responses.<br
/>
+#<br />
+BrowserMatch "Mozilla/2" nokeepalive<br />
+BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0
force-response-1.0<br />
+<br />
+#<br />
+# The following directive disables HTTP/1.1 responses to browsers which<br
/>
+# are in violation of the HTTP/1.0 spec by not being able to understand
a<br />
+# basic 1.1 response.<br />
+#<br />
+BrowserMatch "RealPlayer 4\.0" force-response-1.0<br />
+BrowserMatch "Java/1\.0" force-response-1.0<br />
+BrowserMatch "JDK/1\.0" force-response-1.0
+</example>
+
+ </section>
+ <section id="no-img-log">
+ <title>Do not log requests for images in the access log</title>
+
+ <p>This example keeps requests for images from appearing in the
+ access log. It can be easily modified to prevent logging of
+ particular directories, or to prevent logging of requests
+ coming from particular hosts.</p>
+
+ <example>
+ SetEnvIf Request_URI \.gif image-request<br />
+ SetEnvIf Request_URI \.jpg image-request<br />
+ SetEnvIf Request_URI \.png image-request<br />
+ CustomLog logs/access_log common env=!image-request
+ </example>
+
+ </section>
+ <section id="image-theft">
+ <title>Prevent "Image Theft"</title>
+
+ <p>This example shows how to keep people not on your server
+ from using images on your server as inline-images on their
+ pages. This is not a recommended configuration, but it can work
+ in limited circumstances. We assume that all your images are in
+ a directory called <code>/web/images</code>.</p>
+
+ <example>
+ SetEnvIf Referer "^http://www\.example\.com/" local_referal<br />
+ # Allow browsers that do not send Referer info<br />
+ SetEnvIf Referer "^$" local_referal<br />
+ <Directory /web/images><br />
+ <indent>
+ Order Deny,Allow<br />
+ Deny from all<br />
+ Allow from env=local_referal
+ </indent>
+ </Directory>
+ </example>
+
+ <p>For more information about this technique, see the
+ "<a href="http://www.serverwatch.com/tutorials/article.php/1132731"
+ >Keeping Your Images from Adorning Other Sites</a>"
+ tutorial on ServerWatch.</p>
+ </section>
+ </section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/env.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="env.xml">
+ <basename>env</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">ja</variant>
+ <variant outdated="yes">ko</variant>
+ <variant outdated="yes">tr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/expr.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,447 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="expr.xml.meta">
+
+ <title>Expressions in Apache HTTP Server</title>
+
+ <summary>
+ <p>Historically, there are several syntax variants for expressions
used to express
+ a condition in the different modules of the Apache HTTP Server.
+ There is some ongoing effort to only use a single variant, called
<em>ap_expr</em>,
+ for all configuration directives.
+ This document describes the <em>ap_expr</em> expression parser.
+ </p>
+ <p>The <em>ap_expr</em> expression is intended to replace most other
+ expression variants in HTTPD. For example, the deprecated
+ <directive module="mod_ssl">SSLRequire</directive> expressions can
be
+ replaced by <a href="mod/mod_authz_core.html#reqexpr">Require
expr</a>.
+ </p>
+ </summary>
+
+<seealso><directive module="core">If</directive></seealso>
+<seealso><directive module="mod_rewrite">RewriteCond</directive></seealso>
+<seealso><directive
module="mod_setenvif">SetEnvIfExpr</directive></seealso>
+<seealso><directive
module="mod_filter">FilterProvider</directive></seealso>
+<seealso><a href="mod/mod_authz_core.html#reqexpr">Require
expr</a></seealso>
+<seealso><directive module="mod_ssl">SSLRequire</directive></seealso>
+<seealso><module>mod_include</module></seealso>
+
+ <section id="grammar">
+ <title>Grammar in Backus–Naur Form notation</title>
+ <p><a
href="http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form">Backus–Naur
Form</a> (BNF) is a notation
+ technique for context-free grammars, often used to describe the
syntax of languages used in computing.
+ </p>
+<blockquote>
+<pre>
+expr ::= "<strong>true</strong>" | "<strong>false</strong>"
+ | "<strong>!</strong>" expr
+ | expr "<strong>&&</strong>" expr
+ | expr "<strong>||</strong>" expr
+ | "<strong>(</strong>" expr "<strong>)</strong>"
+ | comp
+
+comp ::= stringcomp
+ | integercomp
+ | unaryop word
+ | word binaryop word
+ | word "<strong>in</strong>" "<strong>{</strong>"
wordlist "<strong>}</strong>"
+ | word "<strong>in</strong>" listfunction
+ | word "<strong>=~</strong>" regex
+ | word "<strong>!~</strong>" regex
+
+
+stringcomp ::= word "<strong>==</strong>" word
+ | word "<strong>!=</strong>" word
+ | word "<strong><</strong>" word
+ | word "<strong><=</strong>" word
+ | word "<strong>></strong>" word
+ | word "<strong>>=</strong>" word
+
+integercomp ::= word "<strong>-eq</strong>" word |
word "<strong>eq</strong>" word
+ | word "<strong>-ne</strong>" word |
word "<strong>ne</strong>" word
+ | word "<strong>-lt</strong>" word |
word "<strong>lt</strong>" word
+ | word "<strong>-le</strong>" word |
word "<strong>le</strong>" word
+ | word "<strong>-gt</strong>" word |
word "<strong>gt</strong>" word
+ | word "<strong>-ge</strong>" word |
word "<strong>ge</strong>" word
+
+wordlist ::= word
+ | wordlist "<strong>,</strong>" word
+
+word ::= word "<strong>.</strong>" word
+ | digit
+ | "<strong>'</strong>" string "<strong>'</strong>"
+ | "<strong>"</strong>" string "<strong>"</strong>"
+ | variable
+ | rebackref
+ | function
+
+string ::= stringpart
+ | string stringpart
+
+stringpart ::= cstring
+ | variable
+ | rebackref
+
+cstring ::= ...
+digit ::= [0-9]+
+
+variable ::= "<strong>%{</strong>" varname "<strong>}</strong>"
+ | "<strong>%{</strong>" funcname "<strong>:</strong>"
funcargs "<strong>}</strong>"
+
+rebackref ::= "<strong>$</strong>" [0-9]
+
+function ::= funcname "<strong>(</strong>" word "<strong>)</strong>"
+
+listfunction ::= listfuncname "<strong>(</strong>"
word "<strong>)</strong>"
+</pre>
+</blockquote>
+
+</section>
+
+<section id="vars">
+ <title>Variables</title>
+
+ <p>The expression parser provides a number of variables of the form
+ <code>%{HTTP_HOST}</code>. Note that the value of a variable may depend
+ on the phase of the request processing in which it is evaluated. For
+ example, an expression used in an <directive><If ></directive>
+ directive is evaluated before authentication is done. Therefore,
+ <code>%{REMOTE_USER}</code> will not be set in this case.</p>
+
+ <p>The following variables provide the values of the named HTTP request
+ headers. The values of other headers can be obtained witht the
+ <code>req</code> <a href="#functions">function</a>.</p>
+
+ <table border="1" style="zebra">
+ <columnspec><column width="1"/></columnspec>
+
+ <tr><th>Name</th></tr>
+ <tr><td><code>HTTP_ACCEPT</code></td></tr>
+ <tr><td><code>HTTP_FORWARDED</code></td></tr>
+ <tr><td><code>HTTP_HOST</code></td></tr>
+ <tr><td><code>HTTP_PROXY_CONNECTION</code></td></tr>
+ <tr><td><code>HTTP_REFERER</code></td></tr>
+ <tr><td><code>HTTP_USER_AGENT</code></td></tr>
+
+ </table>
+
+ <p>Other request related variables</p>
+
+ <table border="1" style="zebra">
+ <columnspec><column width=".4"/><column width=".6"/></columnspec>
+
+ <tr><th>Name</th><th>Description</th></tr>
+ <tr><td><code>REQUEST_METHOD</code></td>
+ <td>The HTTP method of the incoming request (e.g.
+ <code>GET</code>)</td></tr>
+ <tr><td><code>REQUEST_SCHEME</code></td>
+ <td>The scheme part of the request's URI</td></tr>
+ <tr><td><code>REQUEST_URI</code></td>
+ <td>The URI of the request</td></tr>
+ <tr><td><code>REQUEST_FILENAME</code></td>
+ <td>The full local filesystem path to the file or script matching
the
+ request, if this has already been determined by the server at
the
+ time <code>REQUEST_FILENAME</code> is referenced. Otherwise,
such
+ as when used in virtual host context, the same value as
+ <code>REQUEST_URI</code> </td></tr>
+ <tr><td><code>SCRIPT_FILENAME</code></td>
+ <td>Same as <code>REQUEST_FILENAME</code></td></tr>
+ <tr><td><code>SCRIPT_USER</code></td>
+ <td>The user name of the owner of the script.</td></tr>
+ <tr><td><code>SCRIPT_GROUP</code></td>
+ <td>The group name of the group of the script.</td></tr>
+ <tr><td><code>PATH_INFO</code></td>
+ <td>The trailing path name information, see
+ <directive module="core">AcceptPathInfo</directive></td></tr>
+ <tr><td><code>QUERY_STRING</code></td>
+ <td>The query string of the current request</td></tr>
+ <tr><td><code>IS_SUBREQ</code></td>
+ <td>"<code>true</code>" if the current request is a subrequest,
+ "<code>false</code>" otherwise</td></tr>
+ <tr><td><code>THE_REQUEST</code></td>
+ <td>The complete request line (e.g.,
+ "<code>GET /index.html HTTP/1.1</code>")</td></tr>
+ <tr><td><code>REMOTE_ADDR</code></td>
+ <td>The IP address of the remote host</td></tr>
+ <tr><td><code>REMOTE_HOST</code></td>
+ <td>The host name of the remote host</td></tr>
+ <tr><td><code>REMOTE_USER</code></td>
+ <td>The name of the authenticated user (if any)</td></tr>
+ <tr><td><code>REMOTE_IDENT</code></td>
+ <td>The user name set by <module>mod_ident</module></td></tr>
+ <tr><td><code>SERVER_NAME</code></td>
+ <td>The <directive module="core">ServerName</directive> of
+ the current vhost</td></tr>
+ <tr><td><code>SERVER_PORT</code></td>
+ <td>The server port of the current vhost, see
+ <directive module="core">ServerName</directive></td></tr>
+ <tr><td><code>SERVER_ADMIN</code></td>
+ <td>The <directive module="core">ServerAdmin</directive> of
+ the current vhost</td></tr>
+ <tr><td><code>SERVER_PROTOCOL</code></td>
+ <td>The protocol used by the request</td></tr>
+ <tr><td><code>DOCUMENT_ROOT</code></td>
+ <td>The <directive module="core">DocumentRoot</directive> of
+ the current vhost</td></tr>
+ <tr><td><code>AUTH_TYPE</code></td>
+ <td>The configured <directive
module="mod_authn_core">AuthType</directive>
+ (e.g. "<code>basic</code>")</td></tr>
+ <tr><td><code>CONTENT_TYPE</code></td>
+ <td>The content type of the response</td></tr>
+ <tr><td><code>HANDLER</code></td>
+ <td>The name of the <a href="handler.html">handler</a> creating
+ the response</td></tr>
+ <tr><td><code>HTTPS</code></td>
+ <td>"<code>on</code>" if the request uses https,
+ "<code>off</code>" otherwise</td></tr>
+ <tr><td><code>IPV6</code></td>
+ <td>"<code>on</code>" if the connection uses IPv6,
+ "<code>off</code>" otherwise</td></tr>
+ <tr><td><code>REQUEST_LOG_ID</code></td>
+ <td>The error log id of the request (see
+ <directive module="core">ErrorLogFormat</directive>)</td></tr>
+ <tr><td><code>CONN_LOG_ID</code></td>
+ <td>The error log id of the connection (see
+ <directive module="core">ErrorLogFormat</directive>)</td></tr>
+
+ </table>
+
+ <p>Misc variables</p>
+
+ <table border="1" style="zebra">
+ <columnspec><column width=".4"/><column width=".6"/></columnspec>
+
+ <tr><th>Name</th><th>Description</th></tr>
+ <tr><td><code>TIME_YEAR</code></td>
+ <td>The current year (e.g. <code>2010</code>)</td></tr>
+ <tr><td><code>TIME_MON</code></td>
+ <td>The current month (<code>1</code>, ...,
<code>12</code>)</td></tr>
+ <tr><td><code>TIME_DAY</code></td>
+ <td>The current day of the month</td></tr>
+ <tr><td><code>TIME_HOUR</code></td>
+ <td>The hour part of the current time
+ (<code>0</code>, ..., <code>23</code>)</td></tr>
+ <tr><td><code>TIME_MIN</code></td>
+ <td>The minute part of the current time </td></tr>
+ <tr><td><code>TIME_SEC</code></td>
+ <td>The second part of the current time </td></tr>
+ <tr><td><code>TIME_WDAY</code></td>
+ <td>The day of the week (starting with <code>0</code>
+ for Sunday)</td></tr>
+ <tr><td><code>TIME</code></td>
+ <td>The date and time in the format
<code>20101231235959</code></td></tr>
+ <tr><td><code>SERVER_SOFTWARE</code></td>
+ <td>The server version string</td></tr>
+ <tr><td><code>API_VERSION</code></td>
+ <td>The date of the API version (module magic number)</td></tr>
+ </table>
+
+ <p>Some modules register additional variables, see e.g.
<module>mod_ssl</module>.</p>
+
+</section>
+
+<section id="binop">
+ <title>Binary operators</title>
+
+ <p>With the exception of some built-in comparison operators, binary
+ operators have the form "<code>-[a-zA-Z][a-zA-Z0-9_]+</code>", i.e. a
+ minus and at least two characters. The name is not case sensitive.
+ Modules may register additional binary operators.</p>
+
+ <section id="comp">
+ <title>Comparison operators</title>
+
+ <table border="1" style="zebra">
+ <columnspec><column width=".2"/><column width=".2"/><column
width=".6"/></columnspec>
+
+ <tr><th>Name</th><th>Alternative</th> <th>Description</th></tr>
+ <tr><td><code>==</code></td>
+ <td><code>=</code></td>
+ <td>String equality</td></tr>
+ <tr><td><code>!=</code></td>
+ <td></td>
+ <td>String inequality</td></tr>
+ <tr><td><code><</code></td>
+ <td></td>
+ <td>String less than</td></tr>
+ <tr><td><code><=</code></td>
+ <td></td>
+ <td>String less than or equal</td></tr>
+ <tr><td><code>></code></td>
+ <td></td>
+ <td>String greater than</td></tr>
+ <tr><td><code>>=</code></td>
+ <td></td>
+ <td>String greater than or equal</td></tr>
+ <tr><td><code>-eq</code></td>
+ <td><code>eq</code></td>
+ <td>Integer equality</td></tr>
+ <tr><td><code>-ne</code></td>
+ <td><code>ne</code></td>
+ <td>Integer inequality</td></tr>
+ <tr><td><code>-lt</code></td>
+ <td><code>lt</code></td>
+ <td>Integer less than</td></tr>
+ <tr><td><code>-le</code></td>
+ <td><code>le</code></td>
+ <td>Integer less than or equal</td></tr>
+ <tr><td><code>-gt</code></td>
+ <td><code>gt</code></td>
+ <td>Integer greater than</td></tr>
+ <tr><td><code>-ge</code></td>
+ <td><code>ge</code></td>
+ <td>Integer greater than or equal</td></tr>
+ </table>
+ </section>
+
+ <section id="binaryother">
+ <title>Other binary operators</title>
+
+ <table border="1" style="zebra">
+ <columnspec><column width=".2"/><column width=".8"/></columnspec>
+
+ <tr><th>Name</th><th>Description</th></tr>
+ <tr><td><code>-ipmatch</code></td>
+ <td>IP address matches address/netmask</td></tr>
+ <tr><td><code>-strmatch</code></td>
+ <td>left string matches pattern given by right string (containing
+ wildcards *, ?, [])</td></tr>
+ <tr><td><code>-strcmatch</code></td>
+ <td>same as <code>-strmatch</code>, but case insensitive</td></tr>
+ <tr><td><code>-fnmatch</code></td>
+ <td>same as <code>-strmatch</code>, but slashes are not matched by
+ wildcards</td></tr>
+ </table>
+ </section>
+
+</section>
+
+<section id="unnop">
+ <title>Unary operators</title>
+
+ <p>Unary operators have the form "<code>-[a-zA-Z]</code>", i.e. a
+ minus and one character. The name <em>is</em> case sensitive.
+ Modules may register additional unary operators.</p>
+
+ <table border="1" style="zebra">
+ <columnspec><column width=".2"/><column width=".2"/><column
width=".6"/></columnspec>
+
+ <tr><th>Name</th><th>Description</th></tr>
+ <tr><td><code>-n</code></td>
+ <td>True if string is not empty</td></tr>
+ <tr><td><code>-z</code></td>
+ <td>True if string is empty</td></tr>
+ <tr><td><code>-T</code></td>
+ <td>False if string is empty, "<code>0</code>", "<code>off</code>",
+ "<code>false</code>", or "<code>no</code>" (case insensitive).
+ True otherwise.</td></tr>
+ <tr><td><code>-R</code></td>
+ <td>Same as "<code>%{REMOTE_ADDR} -ipmatch ...</code>", but more
efficient
+ </td></tr>
+ </table>
+
+</section>
+
+<section id="functions">
+ <title>Functions</title>
+
+ <p>Normal string-valued functions take one string as argument and
return
+ a string. Functions names are not case sensitive.
+ Modules may register additional functions.</p>
+
+ <table border="1" style="zebra">
+ <columnspec><column width=".2"/><column width=".8"/></columnspec>
+
+ <tr><th>Name</th><th>Description</th></tr>
+ <tr><td><code>req</code>, <code>http</code></td>
+ <td>Get HTTP request header</td></tr>
+ <tr><td><code>resp</code></td>
+ <td>Get HTTP response header</td></tr>
+ <tr><td><code>reqenv</code></td>
+ <td>Lookup request environment variable</td></tr>
+ <tr><td><code>osenv</code></td>
+ <td>Lookup operating system environment variable</td></tr>
+ <tr><td><code>note</code></td>
+ <td>Lookup request note</td></tr>
+ <tr><td><code>env</code></td>
+ <td>Return first match of <code>note</code>, <code>reqenv</code>,
+ <code>osenv</code></td></tr>
+ <tr><td><code>tolower</code></td>
+ <td>Convert string to lower case</td></tr>
+ <tr><td><code>toupper</code></td>
+ <td>Convert string to uppser case</td></tr>
+ <tr><td><code>escape</code></td>
+ <td>Escape special characters in %hex encoding</td></tr>
+ <tr><td><code>unescape</code></td>
+ <td>Unescape %hex encoded string, leaving URL-special characters
encoded (XXX: describe better)</td></tr>
+ <tr><td><code>file</code></td>
+ <td>Read contents from a file</td></tr>
+ </table>
+
+ <p>In addition to string-valued functions, there are also list-valued
functions which
+ take one string as argument and return a wordlist, i.e. a list of
strings. The wordlist
+ can be used with the special <code>-in</code> operator.
+ Functions names are not case sensitive.
+ Modules may register additional functions.</p>
+
+ <p>There are no built-in list-valued functions.
<module>mod_ssl</module>
+ provides <code>PeerExtList</code>. See the description of
+ <directive module="mod_ssl">SSLRequire</directive> for details
+ (but <code>PeerExtList</code> is also usable outside
+ of <directive module="mod_ssl">SSLRequire</directive>).</p>
+
+</section>
+
+<section id="other">
+ <title>Other</title>
+
+ <table border="1" style="zebra">
+ <columnspec><column width=".2"/><column width=".2"/><column
width=".6"/></columnspec>
+
+ <tr><th>Name</th><th>Alternative</th> <th>Description</th></tr>
+ <tr><td><code>-in</code></td>
+ <td><code>in</code></td>
+ <td>string contained in string list</td></tr>
+ <tr><td><code>/regexp/</code></td>
+ <td><code>m#regexp#</code></td>
+ <td>Regular expression (the second form allows different
delimiters than /)</td></tr>
+ <tr><td><code>/regexp/i</code></td>
+ <td><code>m#regexp#i</code></td>
+ <td>Case insensitive regular expression</td></tr>
+ <tr><td><code>$0 ... $9</code></td>
+ <td></td>
+ <td>Regular expression backreferences</td></tr>
+ </table>
+
+ <section id="rebackref">
+ <title>Regular expression backreferences</title>
+ <p>The strings <code>$0</code> ... <code>$9</code> allow to
reference
+ the capture groups from a previously executed, successfully
+ matching regular expressions. They can normally only be used in the
+ same expression as the matching regex, but some modules allow
special
+ uses.</p>
+ </section>
+
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/expr.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="expr.xml">
+ <basename>expr</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/faq/index.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,34 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="index.xml.meta">
+<parentdocument href="../"/>
+
+<title>Frequently Asked Questions</title>
+
+<summary>
+
+ <p>The FAQ has been moved to the <a
+ href="http://wiki.apache.org/httpd/FAQ">HTTP Server Wiki</a>.</p>
+</summary>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/faq/index.xml.meta Sat Feb 26 23:20:49 2011
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+
+<metafile reference="index.xml">
+ <basename>index</basename>
+ <path>/faq/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ <variant>fr</variant>
+ <variant outdated="yes">tr</variant>
+ <variant>zh-cn</variant>
+ </variants>
+</metafile>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/faq/index.xml.zh-cn Sat Feb 26 23:20:49 2011
@@ -0,0 +1,33 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.zh-cn.xsl"?>
+
+
+
+
+<manualpage metafile="index.xml.meta">
+<parentdocument href="../"/>
+
+<title>常见问题</title>
+
+<summary>
+ <p>常见问题已经移到 <a
+ href="http://wiki.apache.org/httpd/FAQ">HTTP 服务器维基</a>。</p>
+</summary>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/filter.xml Sat Feb 26 23:20:49 2011
@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<manualpage metafile="filter.xml.meta">
+
+ <title>Filters</title>
+
+ <summary>
+ <p>This document describes the use of filters in Apache.</p>
+ </summary>
+
+ <section id="intro">
+ <title>Filtering in Apache 2</title>
+ <related>
+ <modulelist>
+ <module>mod_filter</module>
+ <module>mod_deflate</module>
+ <module>mod_ext_filter</module>
+ <module>mod_include</module>
+ <module>mod_charset_lite</module>
+ <module>mod_reflector</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_filter">FilterChain</directive>
+ <directive module="mod_filter">FilterDeclare</directive>
+ <directive module="mod_filter">FilterProtocol</directive>
+ <directive module="mod_filter">FilterProvider</directive>
+ <directive module="mod_mime">AddInputFilter</directive>
+ <directive module="mod_mime">AddOutputFilter</directive>
+ <directive module="mod_mime">RemoveInputFilter</directive>
+ <directive module="mod_mime">RemoveOutputFilter</directive>
+ <directive module="mod_reflector">ReflectorHeader</directive>
+ <directive module="mod_ext_filter">ExtFilterDefine</directive>
+ <directive module="mod_ext_filter">ExtFilterOptions</directive>
+ <directive module="core">SetInputFilter</directive>
+ <directive module="core">SetOutputFilter</directive>
+ </directivelist>
+ </related>
+
+<p>The Filter Chain is available in Apache 2.0 and higher,
+and enables applications to process incoming and outgoing data
+in a highly flexible and configurable manner, regardless of
+where the data comes from. We can pre-process incoming data,
+and post-process outgoing data, at will. This is basically
+independent of the traditional request processing phases.</p>
+<p class="figure">
+<img src="images/filter_arch.png" width="569" height="392" alt=
+"Filters can be chained, in a Data Axis orthogonal to request processing"
+/>
+</p>
+<p>Some examples of filtering in the standard Apache distribution are:</p>
+<ul>
+<li><module>mod_include</module>, implements server-side includes.</li>
+<li><module>mod_ssl</module>, implements SSL encryption (https).</li>
+<li><module>mod_deflate</module>, implements compression/decompression on
the fly.</li>
+<li><module>mod_charset_lite</module>, transcodes between different
character sets.</li>
+<li><module>mod_ext_filter</module>, runs an external program as a
filter.</li>
+</ul>
+<p>Apache also uses a number of filters internally to perform
+functions like chunking and byte-range handling.</p>
+
+<p>A wider range of applications are implemented by third-party filter
+modules available from <a
+href="http://modules.apache.org/">modules.apache.org</a> and
+elsewhere. A few of these are:</p>
+
+<ul>
+<li>HTML and XML processing and rewriting</li>
+<li>XSLT transforms and XIncludes</li>
+<li>XML Namespace support</li>
+<li>File Upload handling and decoding of HTML Forms</li>
+<li>Image processing</li>
+<li>Protection of vulnerable applications such as PHP scripts</li>
+<li>Text search-and-replace editing</li>
+</ul>
+</section>
+
+<section id="smart">
+<title>Smart Filtering</title>
+<p class="figure">
+<img src="images/mod_filter_new.png" width="423" height="331"
+alt="Smart filtering applies different filter providers according to the
state of request processing"/>
+</p>
+<p><module>mod_filter</module>, included in Apache 2.1 and later,
+enables the filter chain to be configured dynamically at run time.
+So for example you can set up a proxy to rewrite
+HTML with an HTML filter and JPEG images with a completely
+separate filter, despite the proxy having no prior information
+about what the origin server will send. This works by using a
+filter harness, that dispatches to different providers according
+to the actual contents at runtime. Any filter may be either
+inserted directly in the chain and run unconditionally, or
+used as a provider and inserted dynamically. For example,</p>
+<ul>
+<li>an HTML processing filter will only run if the content is
+text/html or application/xhtml+xml</li>
+<li>A compression filter will only run if the input is a
+compressible type and not already compressed</li>
+<li>A charset conversion filter will be inserted if a text
+document is not already in the desired charset</li>
+</ul>
+</section>
+
+<section id="service">
+
+<title>Exposing Filters as an HTTP Service</title>
+<p>Filters can be used to process content originating from the client in
+addition to processing content originating on the server using the
+<module>mod_reflector</module> module.</p>
+
+<p><module>mod_reflector</module> accepts POST requests from clients, and
reflects
+the content request body received within the POST request back in the
response,
+passing through the output filter stack on the way back to the client.</p>
+
+<p>This technique can be used as an alternative to a web service running
within
+an application server stack, where an output filter provides the
transformation
+required on the request body. For example, the <module>mod_deflate</module>
+module might be used to provide a general compression service, or an image
+transformation filter might be turned into an image transformation
service.</p>
+
+</section>
+
+<section id="using">
+<title>Using Filters</title>
+<p>There are two ways to use filtering: Simple and Dynamic.
+In general, you should use one or the other; mixing them can
+have unexpected consequences (although simple Input filtering
+can be mixed freely with either simple or dynamic Output filtering).</p>
+<p>The Simple Way is the only way to configure input filters, and is
+sufficient for output filters where you need a static filter chain.
+Relevant directives are
+ <directive module="core">SetInputFilter</directive>,
+ <directive module="core">SetOutputFilter</directive>,
+ <directive module="mod_mime">AddInputFilter</directive>,
+ <directive module="mod_mime">AddOutputFilter</directive>,
+ <directive module="mod_mime">RemoveInputFilter</directive>, and
+ <directive module="mod_mime">RemoveOutputFilter</directive>.</p>
+
+<p>The Dynamic Way enables both static and flexible, dynamic configuration
+of output filters, as discussed in the <module>mod_filter</module> page.
+Relevant directives are
+ <directive module="mod_filter">FilterChain</directive>,
+ <directive module="mod_filter">FilterDeclare</directive>, and
+ <directive module="mod_filter">FilterProvider</directive>.</p>
+
+<p>One further directive <directive
+module="mod_filter">AddOutputFilterByType</directive> is still supported,
+but deprecated. Use dynamic configuration instead.</p>
+
+ </section>
+</manualpage>
=======================================
***Additional files exist in this changeset.***

Reply all

Reply to author

Forward

0 new messages