[i18n-zh] r1439 committed - Move to docs/

7 views

Skip to first unread message

i18...@googlecode.com

unread,

Feb 27, 2011, 3:13:13 AM2/27/11

to l10...@googlegroups.com

Revision: 1439
Author: dongsheng.song
Date: Sun Feb 27 00:09:47 2011
Log: Move to docs/
http://code.google.com/p/i18n-zh/source/detail?r=1439

Added:
/trunk/l10n/apache/trunk/docs
/trunk/l10n/apache/trunk/docs/manual
/trunk/l10n/apache/trunk/docs/manual/LICENSE
/trunk/l10n/apache/trunk/docs/manual/bind.xml
/trunk/l10n/apache/trunk/docs/manual/caching.xml
/trunk/l10n/apache/trunk/docs/manual/configuring.xml
/trunk/l10n/apache/trunk/docs/manual/content-negotiation.xml
/trunk/l10n/apache/trunk/docs/manual/custom-error.xml
/trunk/l10n/apache/trunk/docs/manual/developer
/trunk/l10n/apache/trunk/docs/manual/dns-caveats.xml
/trunk/l10n/apache/trunk/docs/manual/dso.xml
/trunk/l10n/apache/trunk/docs/manual/env.xml
/trunk/l10n/apache/trunk/docs/manual/expr.xml
/trunk/l10n/apache/trunk/docs/manual/faq
/trunk/l10n/apache/trunk/docs/manual/filter.xml
/trunk/l10n/apache/trunk/docs/manual/glossary.xml
/trunk/l10n/apache/trunk/docs/manual/handler.xml
/trunk/l10n/apache/trunk/docs/manual/handler.xml.zh-cn
/trunk/l10n/apache/trunk/docs/manual/howto
/trunk/l10n/apache/trunk/docs/manual/images
/trunk/l10n/apache/trunk/docs/manual/index.xml
/trunk/l10n/apache/trunk/docs/manual/index.xml.zh-cn
/trunk/l10n/apache/trunk/docs/manual/install.xml
/trunk/l10n/apache/trunk/docs/manual/invoking.xml
/trunk/l10n/apache/trunk/docs/manual/license.xml
/trunk/l10n/apache/trunk/docs/manual/logs.xml
/trunk/l10n/apache/trunk/docs/manual/misc
/trunk/l10n/apache/trunk/docs/manual/mod
/trunk/l10n/apache/trunk/docs/manual/mpm.xml
/trunk/l10n/apache/trunk/docs/manual/mpm.xml.zh-cn
/trunk/l10n/apache/trunk/docs/manual/new_features_2_0.xml
/trunk/l10n/apache/trunk/docs/manual/new_features_2_2.xml
/trunk/l10n/apache/trunk/docs/manual/new_features_2_4.xml
/trunk/l10n/apache/trunk/docs/manual/platform
/trunk/l10n/apache/trunk/docs/manual/programs
/trunk/l10n/apache/trunk/docs/manual/rewrite
/trunk/l10n/apache/trunk/docs/manual/sections.xml
/trunk/l10n/apache/trunk/docs/manual/server-wide.xml
/trunk/l10n/apache/trunk/docs/manual/sitemap.xml
/trunk/l10n/apache/trunk/docs/manual/sitemap.xml.zh-cn
/trunk/l10n/apache/trunk/docs/manual/ssl
/trunk/l10n/apache/trunk/docs/manual/stopping.xml
/trunk/l10n/apache/trunk/docs/manual/style
/trunk/l10n/apache/trunk/docs/manual/suexec.xml
/trunk/l10n/apache/trunk/docs/manual/upgrading.xml
/trunk/l10n/apache/trunk/docs/manual/urlmapping.xml
/trunk/l10n/apache/trunk/docs/manual/vhosts
Deleted:
/trunk/l10n/apache/trunk/LICENSE
/trunk/l10n/apache/trunk/bind.xml
/trunk/l10n/apache/trunk/caching.xml
/trunk/l10n/apache/trunk/configuring.xml
/trunk/l10n/apache/trunk/content-negotiation.xml
/trunk/l10n/apache/trunk/custom-error.xml
/trunk/l10n/apache/trunk/developer
/trunk/l10n/apache/trunk/dns-caveats.xml
/trunk/l10n/apache/trunk/dso.xml
/trunk/l10n/apache/trunk/env.xml
/trunk/l10n/apache/trunk/expr.xml
/trunk/l10n/apache/trunk/faq
/trunk/l10n/apache/trunk/filter.xml
/trunk/l10n/apache/trunk/glossary.xml
/trunk/l10n/apache/trunk/handler.xml
/trunk/l10n/apache/trunk/handler.xml.zh-cn
/trunk/l10n/apache/trunk/howto
/trunk/l10n/apache/trunk/images
/trunk/l10n/apache/trunk/index.xml
/trunk/l10n/apache/trunk/index.xml.da
/trunk/l10n/apache/trunk/index.xml.zh-cn
/trunk/l10n/apache/trunk/install.xml
/trunk/l10n/apache/trunk/invoking.xml
/trunk/l10n/apache/trunk/license.xml
/trunk/l10n/apache/trunk/logs.xml
/trunk/l10n/apache/trunk/misc
/trunk/l10n/apache/trunk/mod
/trunk/l10n/apache/trunk/mpm.xml
/trunk/l10n/apache/trunk/mpm.xml.zh-cn
/trunk/l10n/apache/trunk/new_features_2_0.xml
/trunk/l10n/apache/trunk/new_features_2_2.xml
/trunk/l10n/apache/trunk/new_features_2_4.xml
/trunk/l10n/apache/trunk/platform
/trunk/l10n/apache/trunk/programs
/trunk/l10n/apache/trunk/rewrite
/trunk/l10n/apache/trunk/sections.xml
/trunk/l10n/apache/trunk/server-wide.xml
/trunk/l10n/apache/trunk/sitemap.xml
/trunk/l10n/apache/trunk/sitemap.xml.zh-cn
/trunk/l10n/apache/trunk/ssl
/trunk/l10n/apache/trunk/stopping.xml
/trunk/l10n/apache/trunk/style
/trunk/l10n/apache/trunk/suexec.xml
/trunk/l10n/apache/trunk/upgrading.xml
/trunk/l10n/apache/trunk/urlmapping.xml
/trunk/l10n/apache/trunk/vhosts
Modified:
/trunk/l10n/apache/trunk
Replaced:
/trunk/l10n/apache/trunk/docs/manual/mod/core.xml
/trunk/l10n/apache/trunk/docs/manual/mod/directive-dict.xml
/trunk/l10n/apache/trunk/docs/manual/mod/directives.xml
/trunk/l10n/apache/trunk/docs/manual/mod/directives.xml.zh-cn
/trunk/l10n/apache/trunk/docs/manual/mod/event.xml
/trunk/l10n/apache/trunk/docs/manual/mod/index.xml
/trunk/l10n/apache/trunk/docs/manual/mod/index.xml.zh-cn
/trunk/l10n/apache/trunk/docs/manual/mod/mod_access_compat.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_actions.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_alias.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_allowmethods.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_asis.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_auth_basic.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_auth_digest.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_auth_form.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authn_anon.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authn_core.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authn_dbd.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authn_dbm.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authn_file.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authn_socache.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authnz_ldap.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authz_core.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authz_dbd.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authz_dbm.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authz_groupfile.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authz_host.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authz_owner.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_authz_user.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_autoindex.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_buffer.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_cache.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_cache_disk.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_cern_meta.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_cgi.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_cgid.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_charset_lite.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_dav.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_dav_fs.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_dav_lock.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_dbd.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_deflate.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_dialup.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_dir.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_dumpio.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_echo.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_env.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_example.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_expires.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_ext_filter.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_file_cache.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_filter.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_headers.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_heartbeat.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_heartmonitor.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_ident.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_imagemap.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_include.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_info.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_isapi.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_lbmethod_bybusyness.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_lbmethod_byrequests.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_lbmethod_bytraffic.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_lbmethod_heartbeat.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_ldap.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_log_config.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_log_forensic.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_logio.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_lua.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_mime.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_mime_magic.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_negotiation.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_nw_ssl.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_privileges.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy_ajp.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy_balancer.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy_connect.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy_fcgi.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy_fdpass.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy_ftp.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy_http.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_proxy_scgi.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_ratelimit.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_reflector.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_remoteip.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_reqtimeout.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_request.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_rewrite.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_sed.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_session.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_session_cookie.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_session_crypto.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_session_dbd.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_setenvif.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_slotmem_plain.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_slotmem_shm.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_so.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_speling.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_ssl.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_status.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_substitute.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_suexec.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_unique_id.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_unixd.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_userdir.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_usertrack.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_version.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mod_vhost_alias.xml
/trunk/l10n/apache/trunk/docs/manual/mod/module-dict.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mpm_common.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mpm_netware.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mpm_winnt.xml
/trunk/l10n/apache/trunk/docs/manual/mod/mpmt_os2.xml
/trunk/l10n/apache/trunk/docs/manual/mod/prefork.xml
/trunk/l10n/apache/trunk/docs/manual/mod/quickreference.xml
/trunk/l10n/apache/trunk/docs/manual/mod/quickreference.xml.zh-cn
/trunk/l10n/apache/trunk/docs/manual/mod/worker.xml

=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/LICENSE Sun Feb 27 00:09:47 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/docs/manual/bind.xml Sun Feb 27 00:09:47 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/docs/manual/caching.xml Sun Feb 27 00:09:47
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/docs/manual/configuring.xml Sun Feb 27
00:09:47 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/docs/manual/content-negotiation.xml Sun Feb 27
00:09:47 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/docs/manual/custom-error.xml Sun Feb 27
00:09:47 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/docs/manual/dns-caveats.xml Sun Feb 27
00:09:47 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/docs/manual/dso.xml Sun Feb 27 00:09:47 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/docs/manual/env.xml Sun Feb 27 00:09:47 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/docs/manual/expr.xml Sun Feb 27 00:09:47 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/docs/manual/filter.xml Sun Feb 27 00:09:47 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>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/glossary.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,492 @@
+<?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="glossary.xml.meta">
+
+ <title>Glossary</title>
+
+ <summary>
+ <p>This glossary defines some of the common terminology related to
Apache in
+ particular, and web serving in general. More information on each
concept
+ is provided in the links.</p>
+ </summary>
+
+<section id="definitions"><title>Definitions</title>
+
+ <dl>
+ <dt><a name="accesscontrol" id="accesscontrol">Access Control</a></dt>
+ <dd>The restriction of access to network realms. In an Apache context
+ usually the restriction of access to certain <em>URLs</em>.<br />
See: <a
+ href="howto/auth.html">Authentication, Authorization, and Access
+ Control</a>
+ </dd>
+
+ <dt><a name="algorithm" id="algorithm">Algorithm</a></dt>
+ <dd>An unambiguous formula or set of rules for solving a problem in a
finite
+ number of steps. Algorithms for encryption are usually called
+ <dfn>Ciphers</dfn>.
+ </dd>
+
+ <dt><a name="apacheextensiontool" id="apacheextensiontool">APache
+ eXtension Tool</a> <a name="apxs" id="apxs">(apxs)</a></dt>
+ <dd>A perl script that aids in compiling <glossary
+ ref="module">module</glossary> sources into Dynamic Shared Objects
+ (<glossary ref="dso">DSO</glossary>s) and helps install them in the
+ Apache Web server.<br />
+ See: Manual Page: <program>apxs</program>
+ </dd>
+
+ <dt><a name="apacheportableruntime"
+ id="apacheportableruntime">Apache Portable Runtime</a> <a
+ name="apr" id="apr">(APR)</a></dt>
+ <dd>A set of libraries providing many of the basic interfaces
+ between the server and the operating system. APR is developed
+ parallel to the Apache HTTP Server as an independent project.<br />
+ See: <a href="http://apr.apache.org/">Apache Portable Runtime
+ Project</a>
+ </dd>
+
+ <dt><a name="authentication"
id="authentication">Authentication</a></dt>
+ <dd>The positive identification of a network entity such as a server, a
+ client, or a user.<br />
+ See: <a href="howto/auth.html">Authentication, Authorization, and
Access
+ Control</a>
+ </dd>
+
+ <dt><a name="certificate" id="certificate">Certificate</a></dt>
+ <dd>A data record used for authenticating network entities such
+ as a server or a client. A certificate contains X.509 information
pieces
+ about its owner (called the subject) and the signing <glossary
+ ref="certificationauthority">Certification Authority</glossary>
(called
+ the issuer), plus the owner's <glossary ref="publickey">public
+ key</glossary> and the
+ signature made by the CA. Network entities verify these signatures
+ using CA certificates.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="certificatsigningrequest"
+ id="certificatsigningrequest">Certificate Signing Request</a>
+ <a name="csr" id="csr">(CSR)</a></dt>
+ <dd>An unsigned <glossary ref="certificate">certificate</glossary> for
+ submission to a <glossary ref="certificationauthority">Certification
+ Authority</glossary>, which signs it with the <glossary
+ ref="privatekey">Private Key</glossary> of their CA
+ <em>Certificate</em>. Once the CSR is signed, it becomes a real
+ certificate.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="certificationauthority"
+ id="certificationauthority">Certification Authority</a>
+ <a name="ca" id="ca">(CA)</a></dt>
+ <dd>A trusted third party whose purpose is to sign certificates for
network
+ entities it has authenticated using secure means. Other network
entities
+ can check the signature to verify that a CA has authenticated the
bearer
+ of a certificate.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="cipher" id="cipher">Cipher</a></dt>
+ <dd>An algorithm or system for data encryption. Examples are DES,
IDEA, RC4,
+ etc.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="ciphertext" id="ciphertext">Ciphertext</a></dt>
+ <dd>The result after <glossary ref="plaintext">Plaintext</glossary> is
+ passed through a <glossary ref="cipher">Cipher</glossary>.<br />
See: <a
+ href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="commongatewayinterface" id="commongatewayinterface">Common
+ Gateway Interface</a> <a name="cgi" id="cgi">(CGI)</a></dt>
+ <dd>A standard definition for an interface between a web server and an
+ external program that allows the external program to service
requests.
+ There is an <a href="http://www.ietf.org/rfc/rfc3875">Informational
+ RFC</a> which covers the specifics.<br />
+ See: <a href="howto/cgi.html">Dynamic Content with CGI</a>
+ </dd>
+
+ <dt><a name="configurationdirective"
+ id="configurationdirective">Configuration Directive</a></dt>
+ <dd>See: <glossary ref="directive">Directive</glossary></dd>
+
+ <dt><a name="configurationfile" id="configurationfile">Configuration
+ File</a></dt>
+ <dd>A text file containing <glossary
ref="directive">Directives</glossary>
+ that control the configuration of Apache.<br />
+ See: <a href="configuring.html">Configuration Files</a>
+ </dd>
+
+ <dt><a name="connect" id="connect">CONNECT</a></dt>
+ <dd>An HTTP <glossary ref="method">method</glossary> for proxying raw
data
+ channels over HTTP. It can be used to encapsulate other protocols,
such as
+ the SSL protocol.
+ </dd>
+
+ <dt><a name="context" id="context">Context</a></dt>
+ <dd>An area in the <glossary ref="configurationfile">configuration
+ files</glossary> where certain types of <glossary
+ ref="directive">directives</glossary> are allowed.<br />
+ See: <a href="mod/directive-dict.html#Context">Terms Used to Describe
+ Apache Directives</a>
+ </dd>
+
+ <dt><a name="digitalsignature" id="digitalsignature">Digital
+ Signature</a></dt>
+ <dd>An encrypted text block that validates a certificate or other
file. A
+ <glossary ref="certificationauthority">Certification
Authority</glossary>
+ creates a signature by generating a hash of the <em>Public Key</em>
+ embedded in a <em>Certificate</em>, then encrypting the hash with
its own
+ <em>Private Key</em>. Only the CA's public key can decrypt the
signature,
+ verifying that the CA has authenticated the network entity that owns
the
+ <em>Certificate</em>.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="directive" id="directive">Directive</a></dt>
+ <dd>A configuration command that controls one or more aspects of
Apache's
+ behavior. Directives are placed in the <glossary
+ ref="configurationfile">Configuration File</glossary><br />
+ See: <a href="mod/directives.html">Directive Index</a>
+ </dd>
+
+ <dt><a name="dynamicsharedobject" id="dynamicsharedobject">Dynamic
+ Shared Object</a> <a name="dso" id="dso">(DSO)</a></dt>
+ <dd><glossary ref="module">Modules</glossary> compiled separately from
the
+ Apache <program>httpd</program> binary that can be loaded
on-demand.<br />
+ See: <a href="dso.html">Dynamic Shared Object Support</a>
+ </dd>
+
+ <dt><a name="environmentvariable" id="environmentvariable">Environment
+ Variable</a> <a name="env-variable"
+ id="env-variable">(env-variable)</a></dt>
+ <dd>Named variables managed by the operating system shell and used to
store
+ information and communicate between programs. Apache also contains
+ internal variables that are referred to as environment variables,
but are
+ stored in internal Apache structures, rather than in the shell
+ environment.<br />
+ See: <a href="env.html">Environment Variables in Apache</a>
+ </dd>
+
+ <dt><a name="export-crippled"
id="export-crippled">Export-Crippled</a></dt>
+ <dd>Diminished in cryptographic strength (and security) in order to
comply
+ with the United States' Export Administration Regulations (EAR).
+ Export-crippled cryptographic software is limited to a small key
size,
+ resulting in <em>Ciphertext</em> which usually can be decrypted by
brute
+ force.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="filter" id="filter">Filter</a></dt>
+ <dd>A process that is applied to data that is sent or received by the
+ server. Input filters process data sent by the client to the server,
+ while output filters process documents on the server before they are
sent
+ to the client. For example, the <code>INCLUDES</code> output filter
+ processes documents for <glossary ref="ssi">Server Side
+ Includes</glossary>.<br />
+ See: <a href="filter.html">Filters</a>
+ </dd>
+
+ <dt><a name="fully-qualifieddomain-name"
+ id="fully-qualifieddomain-name">Fully-Qualified Domain-Name</a>
+ <a name="fqdn" id="fqdn">(FQDN)</a></dt>
+ <dd>The unique name of a network entity, consisting of a hostname and a
+ domain name that can resolve to an IP address. For example,
+ <code>www</code> is a hostname, <code>example.com</code> is a domain
name,
+ and <code>www.example.com</code> is a fully-qualified domain name.
+ </dd>
+
+ <dt><a name="handler" id="handler">Handler</a></dt>
+ <dd>An internal Apache representation of the action to be performed
when a
+ file is called. Generally, files have implicit handlers, based on
the file
+ type. Normally, all files are simply served by the server, but
certain
+ file types are "handled" separately. For example, the
+ <code>cgi-script</code> handler designates files to be processed as
+ <glossary ref="cgi">CGIs</glossary>.<br />
+ See: <a href="handler.html">Apache's Handler Use</a>
+ </dd>
+
+ <dt><a name="hash" id="hash">Hash</a></dt>
+ <dd>A mathematical one-way, irreversible algorithm generating a string
with
+ fixed-length from another string of any length. Different input
strings
+ will usually produce different hashes (depending on the hash
function).
+ </dd>
+
+ <dt><a name="header" id="header">Header</a></dt>
+ <dd>The part of the <glossary ref="http">HTTP</glossary> request and
+ response that is sent before the actual content, and that contains
+ meta-information describing the content.
+ </dd>
+
+ <dt><a name="htaccess" id="htaccess">.htaccess</a></dt>
+ <dd>A <glossary ref="configurationfile">configuration file</glossary>
that
+ is placed inside the web tree and applies configuration <glossary
+ ref="directive">directives</glossary> to the directory where it is
+ placed and all sub-directories. Despite its name, this file can hold
+ almost any type of directive, not just access-control directives.<br
/>
+ See: <a href="configuring.html">Configuration Files</a>
+ </dd>
+
+ <dt><a name="httpd.conf" id="httpd.conf">httpd.conf</a></dt>
+ <dd>The main Apache <glossary ref="configurationfile">configuration
+ file</glossary>. The default location is
+ <code>/usr/local/apache2/conf/httpd.conf</code>, but it may be moved
using
+ run-time or compile-time configuration.<br />
+ See: <a href="configuring.html">Configuration Files</a>
+ </dd>
+
+ <dt><a name="hypertexttransferprotocol"
+ id="hypertexttransferprotocol">HyperText Transfer Protocol</a>
+ <a name="http" id="hhtp">(HTTP)</a></dt>
+ <dd>The standard transmission protocol used on the World Wide Web.
Apache
+ implements version 1.1 of the protocol, referred to as HTTP/1.1 and
+ defined by <a href="http://ietf.org/rfc/rfc2616.txt">RFC 2616</a>.
+ </dd>
+
+ <dt><a name="https" id="https">HTTPS</a></dt>
+ <dd>The HyperText Transfer Protocol (Secure), the standard encrypted
+ communication mechanism on the World Wide Web. This is actually just
HTTP
+ over <glossary ref="ssl">SSL</glossary>.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="method" id="method">Method</a></dt>
+ <dd>In the context of <glossary ref="http">HTTP</glossary>, an action
to
+ perform on a resource, specified on the request line by the client.
Some
+ of the methods available in HTTP are <code>GET</code>,
<code>POST</code>,
+ and <code>PUT</code>.
+ </dd>
+
+ <dt><a name="messagedigest" id="messagedigest">Message Digest</a></dt>
+ <dd>A hash of a message, which can be used to verify that the contents
of
+ the message have not been altered in transit.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="mime-type" id="mime-type">MIME-type</a></dt>
+ <dd>A way to describe the kind of document being transmitted. Its name
+ comes from that fact that its format is borrowed from the
Multipurpose
+ Internet Mail Extensions. It consists of a major type and a minor
type,
+ separated by a slash. Some examples are <code>text/html</code>,
+ <code>image/gif</code>, and <code>application/octet-stream</code>.
In
+ HTTP, the MIME-type is transmitted in the <code>Content-Type</code>
+ <glossary ref="header">header</glossary>.<br />
+ See: <a href="mod/mod_mime.html">mod_mime</a>
+ </dd>
+
+ <dt><a name="module" id="module">Module</a></dt>
+ <dd>An independent part of a program. Much of Apache's functionality
is
+ contained in modules that you can choose to include or exclude.
Modules
+ that are compiled into the Apache <program>httpd</program> binary are
+ called <dfn>static modules</dfn>, while modules that are stored
+ separately and can be optionally loaded at run-time are called
+ <dfn>dynamic modules</dfn> or <glossary ref="dso">DSOs</glossary>.
+ Modules that are included by default
+ are called <dfn>base modules</dfn>. Many modules are available for
Apache
+ that are not distributed as part of the Apache HTTP Server <glossary
+ ref="tarball">tarball</glossary>. These are referred to as
+ <dfn>third-party modules</dfn>.<br />
+ See: <a href="mod/">Module Index</a>
+ </dd>
+
+ <dt><a name="modulemagicnumber" id="modulemagicnumber">Module Magic
+ Number</a> (<a name="mmn" id="mmn">MMN</a>)</dt>
+ <dd>Module Magic Number is a constant defined in the Apache source
code that
+ is associated with binary compatibility of modules. It is changed
when
+ internal Apache structures, function calls and other significant
parts of
+ API change in such a way that binary compatibility cannot be
guaranteed
+ any more. On MMN change, all third party modules have to be at least
+ recompiled, sometimes even slightly changed in order to work with
the new
+ version of Apache.
+ </dd>
+
+ <dt><a name="openssl" id="openssl">OpenSSL</a></dt>
+ <dd>The Open Source toolkit for SSL/TLS<br />
+ See <a href="http://www.openssl.org/">http://www.openssl.org/</a>#
+ </dd>
+
+ <dt><a name="passphrase" id="passphrase">Pass Phrase</a></dt>
+ <dd>The word or phrase that protects private key files. It prevents
+ unauthorized users from encrypting them. Usually it's just the secret
+ encryption/decryption key used for <glossary
+ ref="cipher">Ciphers</glossary>.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="plaintext" id="plaintext">Plaintext</a></dt>
+ <dd>The unencrypted text.</dd>
+
+ <dt><a name="privatekey" id="privatekey">Private Key</a></dt>
+ <dd>The secret key in a <glossary ref="publickeycryptography">Public
Key
+ Cryptography</glossary> system, used to decrypt incoming messages and
+ sign outgoing ones.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="proxy" id="proxy">Proxy</a></dt>
+ <dd>An intermediate server that sits between the client and the
<em>origin
+ server</em>. It accepts requests from clients, transmits those
requests
+ on to the origin server, and then returns the response from the
origin
+ server to the client. If several clients request the same content,
the
+ proxy can deliver that content from its cache, rather than
requesting it
+ from the origin server each time, thereby reducing response time.<br
/>
+ See: <a href="mod/mod_proxy.html">mod_proxy</a>
+ </dd>
+
+ <dt><a name="publickey" id="publickey">Public Key</a></dt>
+ <dd>The publicly available key in a <glossary
+ ref="publickeycryptography">Public Key Cryptography</glossary>
system,
+ used to encrypt messages bound for its owner and to decrypt
signatures
+ made by its owner.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="publickeycryptography"
+ id="publickeycryptography">Public Key Cryptography</a></dt>
+ <dd>The study and application of asymmetric encryption systems, which
use
+ one key for encryption and another for decryption. A corresponding
pair of
+ such keys constitutes a key pair. Also called Asymmetric
Cryptography.
+ <br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="regularexpresion" id="regularexpresion">Regular
Expression</a>
+ <a name="regex" id="regex">(Regex)</a></dt>
+ <dd>A way of describing a pattern in text - for example, "all the
words that
+ begin with the letter A" or "every 10-digit phone number" or
even "Every
+ sentence with two commas in it, and no capital letter Q". Regular
+ expressions are useful in Apache because they let you apply certain
+ attributes against collections of files or resources in very
flexible ways
+ - for example, all .gif and .jpg files under any "images" directory
could
+ be written as "<code>/images/.*(jpg|gif)$</code>". In places where
+ regular expressions are used to replace strings, the special
variables
+ $1 ... $9 contain backreferences to the grouped parts (in
parentheses) of
+ the matched expression. The special variable $0 contains a
backerference
+ to the whole matched expression. To write a literal dollar sign in a
+ replacement string, it can be escaped with a backslash.
Historically, the
+ variable & could be used as alias for $0 in some places. This is
no
+ longer possible since version 2.3.6. Apache uses Perl Compatible
Regular
+ Expressions provided by the <a href="http://www.pcre.org/">PCRE</a>
+ library. You can find more documentation about PCRE's regular
expression
+ syntax at that site, or at
+ <a href="http://en.wikipedia.org/wiki/PCRE">Wikipedia</a>.
+ </dd>
+
+ <dt><a name="reverseproxy" id="reverseproxy">Reverse Proxy</a></dt>
+ <dd>A <glossary ref="proxy">proxy</glossary> server that appears to
the client
+ as if it is an <em>origin server</em>. This is useful to hide the
real
+ origin server from the client for security reasons, or to load
balance.
+ </dd>
+
+ <dt><a name="securesocketslayer" id="securesocketslayer">Secure Sockets
+ Layer</a> <a name="ssl" id="ssl">(SSL)</a></dt>
+ <dd>A protocol created by Netscape Communications Corporation for
general
+ communication authentication and encryption over TCP/IP networks.
The most
+ popular usage is <em>HTTPS</em>, i.e. the HyperText Transfer
Protocol (HTTP)
+ over SSL.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="servernameindication" id="servernameindication">Server
Name
+ Indication</a> <a name="sni" id="sni">(SNI)</a></dt>
+ <dd>An SSL function that allows passing the desired server
+ hostname in the initial SSL handshake message, so that the web
+ server can select the correct virtual host configuration to use
+ in processing the SSL handshake. It was added to SSL starting
+ with the TLS extensions, RFC 3546. <br />
+ See: <a href="ssl/ssl_faq.html">the SSL FAQ</a>
+ and <a href="http://www.ietf.org/rfc/rfc3546.txt">RFC 3546</a>
+ </dd>
+
+ <dt><a name="serversideincludes" id="serversideincludes">Server Side
+ Includes</a> <a name="ssi" id="ssi">(SSI)</a></dt>
+ <dd>A technique for embedding processing directives inside HTML
files.<br />
+ See: <a href="howto/ssi.html">Introduction to Server Side
Includes</a>
+ </dd>
+
+ <dt><a name="session" id="session">Session</a></dt>
+ <dd>The context information of a communication in general.</dd>
+
+ <dt><a name="ssleay" id="ssleay">SSLeay</a></dt>
+ <dd>The original SSL/TLS implementation library developed by Eric A.
+ Young
+ </dd>
+
+ <dt><a name="symmetriccryptophraphy"
id="symmetriccryptophraphy">Symmetric
+ Cryptography</a></dt>
+ <dd>The study and application of <em>Ciphers</em> that use a single
secret key
+ for both encryption and decryption operations.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="tarball" id="tarball">Tarball</a></dt>
+ <dd>A package of files gathered together using the <code>tar</code>
utility.
+ Apache distributions are stored in compressed tar archives or using
+ pkzip.
+ </dd>
+
+ <dt><a name="transportlayersecurity"
id="transportlayersecurity">Transport
+ Layer Security</a> <a name="tls" id="tls">(TLS)</a></dt>
+ <dd>The successor protocol to SSL, created by the Internet Engineering
Task
+ Force (IETF) for general communication authentication and encryption
over
+ TCP/IP networks. TLS version 1 is nearly identical with SSL version
3.<br />
+ See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+
+ <dt><a name="uniformresourcelocator"
id="uniformresourcelocator">Uniform
+ Resource Locator</a> <a name="url" id="url">(URL)</a></dt>
+ <dd>The name/address of a resource on the Internet. This is the common
+ informal term for what is formally called a <glossary
+ ref="uniformresourceidentifier">Uniform Resource
Identifier</glossary>.
+ URLs are usually made up of a scheme, like <code>http</code> or
+ <code>https</code>, a hostname, and a path. A URL for this page
might
+ be
<code>http://httpd.apache.org/docs/&httpd.docs;/glossary.html</code>.
+ </dd>
+
+ <dt><a name="uniformresourceidentifier"
+ id="uniformresourceidentifier">Uniform Resource Identifier</a>
+ <a name="URI" id="URI">(URI)</a></dt>
+ <dd>A compact string of characters for identifying an abstract or
physical
+ resource. It is formally defined by <a
+ href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. URIs
used on the
+ world-wide web are commonly referred to as <glossary
+ ref="url">URLs</glossary>.
+ </dd>
+
+ <dt><a name="virtualhosting" id="virtualhosting">Virtual
Hosting</a></dt>
+ <dd>Serving multiple websites using a single instance of Apache.
<em>IP
+ virtual hosting</em> differentiates between websites based on their
IP
+ address, while <em>name-based virtual hosting</em> uses only the
name of the
+ host and can therefore host many sites on the same IP address.<br />
+ See: <a href="vhosts/">Apache Virtual Host documentation</a>
+ </dd>
+
+ <dt><a name="x.509" id="x.509">X.509</a></dt>
+ <dd>An authentication certificate scheme recommended by the
International
+ Telecommunication Union (ITU-T) which is used for SSL/TLS
authentication.<br
+ /> See: <a href="ssl/">SSL/TLS Encryption</a>
+ </dd>
+ </dl>
+</section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/handler.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,163 @@
+<?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="handler.xml.meta">
+
+ <title>Apache's Handler Use</title>
+
+ <summary>
+ <p>This document describes the use of Apache's Handlers.</p>
+ </summary>
+
+ <section id="definition">
+ <title>What is a Handler</title>
+ <related>
+ <modulelist>
+ <module>mod_actions</module>
+ <module>mod_asis</module>
+ <module>mod_cgi</module>
+ <module>mod_imagemap</module>
+ <module>mod_info</module>
+ <module>mod_mime</module>
+ <module>mod_negotiation</module>
+ <module>mod_status</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_actions">Action</directive>
+ <directive module="mod_mime">AddHandler</directive>
+ <directive module="mod_mime">RemoveHandler</directive>
+ <directive module="core">SetHandler</directive>
+ </directivelist>
+ </related>
+
+
+ <p>A "handler" is an internal Apache representation of the
+ action to be performed when a file is called. Generally, files
+ have implicit handlers, based on the file type. Normally, all
+ files are simply served by the server, but certain file types
+ are "handled" separately.</p>
+
+ <p>Handlers may also be configured explicitly,
+ based on either filename extensions or on location,
+ without relation to file type. This is
+ advantageous both because it is a more elegant solution, and
+ because it also allows for both a type <strong>and</strong> a
+ handler to be associated with a file. (See also <a
+ href="mod/mod_mime.html#multipleext">Files with Multiple
+ Extensions</a>.)</p>
+
+ <p>Handlers can either be built into the server or included in
+ a module, or they can be added with the <directive
+ module="mod_actions">Action</directive> directive. The
+ built-in handlers in the standard distribution are as
+ follows:</p>
+
+ <ul>
+ <li><strong>default-handler</strong>: Send the file using the
+ <code>default_handler()</code>, which is the handler used by
+ default to handle static content. (core)</li>
+
+ <li><strong>send-as-is</strong>: Send file with HTTP headers
+ as is. (<module>mod_asis</module>)</li>
+
+ <li><strong>cgi-script</strong>: Treat the file as a CGI
+ script. (<module>mod_cgi</module>)</li>
+
+ <li><strong>imap-file</strong>: Parse as an imagemap rule
+ file. (<module>mod_imagemap</module>)</li>
+
+ <li><strong>server-info</strong>: Get the server's
+ configuration information. (<module>mod_info</module>)</li>
+
+ <li><strong>server-status</strong>: Get the server's status
+ report. (<module>mod_status</module>)</li>
+
+ <li><strong>type-map</strong>: Parse as a type map file for
+ content negotiation. (<module>mod_negotiation</module>)</li>
+ </ul>
+ </section>
+ <section id="examples">
+ <title>Examples</title>
+
+ <section id="example1">
+ <title>Modifying static content using a CGI script</title>
+
+ <p>The following directives will cause requests for files with
+ the <code>html</code> extension to trigger the launch of the
+ <code>footer.pl</code> CGI script.</p>
+
+ <example>
+ Action add-footer /cgi-bin/footer.pl<br/>
+ AddHandler add-footer .html
+ </example>
+
+ <p>Then the CGI script is responsible for sending the
+ originally requested document (pointed to by the
+ <code>PATH_TRANSLATED</code> environment variable) and making
+ whatever modifications or additions are desired.</p>
+
+ </section>
+ <section id="example2">
+ <title>Files with HTTP headers</title>
+
+ <p>The following directives will enable the
+ <code>send-as-is</code> handler, which is used for files which
+ contain their own HTTP headers. All files in the
+ <code>/web/htdocs/asis/</code> directory will be processed by
+ the <code>send-as-is</code> handler, regardless of their
+ filename extensions.</p>
+
+ <example>
+ <Directory /web/htdocs/asis><br/>
+ SetHandler send-as-is<br/>
+ </Directory>
+ </example>
+
+ </section>
+ </section>
+ <section id="programmer">
+ <title>Programmer's Note</title>
+
+ <p>In order to implement the handler features, an addition has
+ been made to the <a href="developer/API.html">Apache API</a> that
+ you may wish to make use of. Specifically, a new record has
+ been added to the <code>request_rec</code> structure:</p>
+
+ <example>
+ char *handler
+ </example>
+
+ <p>If you wish to have your module engage a handler, you need
+ only to set <code>r->handler</code> to the name of the
+ handler at any time prior to the <code>invoke_handler</code>
+ stage of the request. Handlers are implemented as they were
+ before, albeit using the handler name instead of a content
+ type. While it is not necessary, the naming convention for
+ handlers is to use a dash-separated word, with no slashes, so
+ as to not invade the media type name-space.</p>
+ </section>
+</manualpage>
+
+
+
+
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/handler.xml.zh-cn Sun Feb 27
00:09:47 2011
@@ -0,0 +1,128 @@
+<?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="handler.xml.meta">
+
+ <title>Apache 的处理器</title>
+
+ <summary>
+ <p>本页描述 Apache 处理器的用法。</p>
+ </summary>
+
+ <section id="definition">
+ <title>什么是处理器</title>
+ <related>
+ <modulelist>
+ <module>mod_actions</module>
+ <module>mod_asis</module>
+ <module>mod_cgi</module>
+ <module>mod_imagemap</module>
+ <module>mod_info</module>
+ <module>mod_mime</module>
+ <module>mod_negotiation</module>
+ <module>mod_status</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_actions">Action</directive>
+ <directive module="mod_mime">AddHandler</directive>
+ <directive module="mod_mime">RemoveHandler</directive>
+ <directive module="core">SetHandler</directive>
+ </directivelist>
+ </related>
+
+
+ <p>“处理器”是当文件被调用时，Apache 要执行的动作的内部表示形式。
+ 一般来说，每个文件都有基于其文件类型的隐式处理器。通常的文件会被
+ 服务器简单处理，但是某些文件类型会被分别“处理”。</p>
+
+ <p>处理器也可以被基于扩展名或位置来明确配置。它们都很有用，这不仅
+ 因为它是优雅的方案，而且还允许类型<strong>与</strong>处理器关联到文件
+ (参见<a href="mod/mod_mime.html#multipleext">文件与多个扩展名</a>)。
</p>
+
+ <p>处理器可以编译到服务器中，或者包含在模块中，它们还可以被 <directive
+ module="mod_actions">Action</directive> 指令增加。标准发行版中内置的处
理器有:</p>
+
+ <ul>
+ <li><strong>default-handler</strong>: 使用
+ <code>default_handler()</code> 发送文件，它是用来处理静态内容的处理器
(核心)。</li>
+
+ <li><strong>send-as-is</strong>: 直接发送，不增加 HTTP 头
(<module>mod_asis</module>)。</li>
+
+ <li><strong>cgi-script</strong>: 按 CGI 脚本处理
(<module>mod_cgi</module>)。</li>
+
+ <li><strong>imap-file</strong>: 按 imagemap 规则处理
(<module>mod_imagemap</module>)。</li>
+
+ <li><strong>server-info</strong>: 取得服务器配置信息
(<module>mod_info</module>)。</li>
+
+ <li><strong>server-status</strong>: 取得服务器状态报告
(<module>mod_status</module>)。</li>
+
+ <li><strong>type-map</strong>: 用于内容协商，按类型映射文件处理
(<module>mod_negotiation</module>)。</li>
+ </ul>
+ </section>
+ <section id="examples">
+ <title>例子</title>
+
+ <section id="example1">
+ <title>使用 CGI 脚本修改静态内容</title>
+
+ <p>下面的指令将会使具有<code>html</code>扩展名的文件，触发 CGI 脚本
<code>footer.pl</code>的执行。</p>
+
+ <example>
+ Action add-footer /cgi-bin/footer.pl<br/>
+ AddHandler add-footer .html
+ </example>
+
+ <p>于是 CGI 负责发送请求的文档(<code>PATH_TRANSLATED</code> 环境变量
指向它)，按照需要作出 and making
+ whatever modifications or additions are desired.</p>
+
+ </section>
+ <section id="example2">
+ <title>含有 HTTP 头的文件</title>
+
+ <p>下面的指令会启用
+ <code>send-as-is</code> 处理器，用于包含自己的 HTTP 的文件。不管什么
扩展名，
+ 所有位于 <code>/web/htdocs/asis/</code> 目录的文件会被
+ <code>send-as-is</code> 处理器处理。</p>
+
+ <example>
+ <Directory /web/htdocs/asis><br/>
+ SetHandler send-as-is<br/>
+ </Directory>
+ </example>
+
+ </section>
+ </section>
+ <section id="programmer">
+ <title>对程序员的说明</title>
+
+ <p>为了实现处理器特性，增加了需要使用的 <a
href="developer/API.html">Apache API</a>。
+ 特别的，结构 <code>request_rec</code> 增加了新成员:</p>
+
+ <example>
+ char *handler
+ </example>
+
+ <p>如果你想要模块实现处理器，只需要在在处理请求，调用
<code>invoke_handler</code>
+ 之前，将 <code>r->handler</code> 指向处理器名称。处理器的实现与以前
一样，只是用处理器名称取代了内容类型。
+ 虽然不是必要，处理器的命名约定是使用破折号分割的单词，没有斜杠，从而不
侵入媒体类型名称空间。</p>
+ </section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/index.xml Sun Feb 27 00:09:47 2011
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE indexpage SYSTEM "./style/sitemap.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<indexpage metafile="index.xml.meta">
+<parentdocument href="http://httpd.apache.org/docs-project/" />
+
+<title>Apache HTTP Server Version &httpd.major;.&httpd.minor;
+Documentation</title>
+
+<category id="release"><title>Release Notes</title>
+ <page href="new_features_2_4.html">New features with Apache
2.3/2.4</page>
+ <page href="new_features_2_2.html">New features with Apache
2.1/2.2</page>
+ <page href="new_features_2_0.html">New features with Apache 2.0</page>
+ <page href="upgrading.html">Upgrading to 2.4 from 2.2</page>
+ <page href="license.html">Apache License</page>
+</category>
+
+<category id="manual"><title>Reference Manual</title>
+ <page href="install.html">Compiling and Installing</page>
+ <page href="invoking.html">Starting</page>
+ <page href="stopping.html">Stopping or Restarting</page>
+ <page href="mod/directives.html">Run-time Configuration
Directives</page>
+ <page href="mod/quickreference.html">Directive Quick-Reference</page>
+ <page href="mod/">Modules</page>
+ <page href="mpm.html">Multi-Processing Modules (MPMs)</page>
+ <page href="filter.html">Filters</page>
+ <page href="handler.html">Handlers</page>
+ <page href="expr.html">Expression parser</page>
+ <page href="programs/">Server and Supporting Programs</page>
+ <page href="glossary.html">Glossary</page>
+</category>
+
+<category id="usersguide"><title>Users' Guide</title>
+ <page href="bind.html">Binding to Addresses and Ports</page>
+ <page href="configuring.html">Configuration Files</page>
+ <page href="sections.html">Configuration Sections</page>
+ <page href="caching.html">Content Caching</page>
+ <page href="content-negotiation.html">Content Negotiation</page>
+ <page href="dso.html">Dynamic Shared Objects (DSO)</page>
+ <page href="env.html">Environment Variables</page>
+ <page href="logs.html">Log Files</page>
+ <page href="urlmapping.html">Mapping URLs to the Filesystem</page>
+ <page href="misc/perf-tuning.html">Performance Tuning</page>
+ <page href="misc/security_tips.html">Security Tips</page>
+ <page href="server-wide.html">Server-Wide Configuration</page>
+ <page href="ssl/">SSL/TLS Encryption</page>
+ <page href="suexec.html">Suexec Execution for CGI</page>
+ <page href="rewrite/">URL Rewriting with mod_rewrite</page>
+ <page href="vhosts/">Virtual Hosts</page>
+</category>
+
+<category id="howto"><title>How-To / Tutorials</title>
+ <page href="howto/auth.html">Authentication and Authorization</page>
+ <page href="howto/access.html">Access Control</page>
+ <page href="howto/cgi.html">CGI: Dynamic Content</page>
+ <page href="howto/htaccess.html">.htaccess files</page>
+ <page href="howto/ssi.html">Server Side Includes (SSI)</page>
+ <page href="howto/public_html.html">Per-user Web Directories
+ (public_html)</page>
+</category>
+
+<category id="platform"><title>Platform Specific Notes</title>
+ <page href="platform/windows.html">Microsoft Windows</page>
+ <page href="platform/netware.html">Novell NetWare</page>
+ <page href="platform/ebcdic.html">EBCDIC Port</page>
+</category>
+
+<category id="other"><title>Other Topics</title>
+ <page href="http://wiki.apache.org/httpd/FAQ">Frequently Asked
Questions</page>
+ <page href="sitemap.html">Sitemap</page>
+ <page href="developer/">Documentation for Developers</page>
+ <page href="misc/">Other Notes</page>
+ <page href="http://wiki.apache.org/httpd/">Wiki</page>
+</category>
+
+</indexpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/index.xml.zh-cn Sun Feb 27
00:09:47 2011
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE indexpage SYSTEM "./style/sitemap.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.zh-cn.xsl"?>
+
+
+
+
+<indexpage metafile="index.xml.meta">
+<parentdocument href="http://httpd.apache.org/docs-project/" />
+
+<title>Apache HTTP 服务器 &httpd.major;.&httpd.minor; 文档</title>
+
+<category id="release"><title>发行说明</title>
+ <page href="new_features_2_4.html">Apache 2.3/2.4 的新特性</page>
+ <page href="new_features_2_2.html">Apache 2.1/2.2 的新特性</page>
+ <page href="new_features_2_0.html">Apache 2.0 的新特性</page>
+ <page href="upgrading.html">从 2.2 升级到 2.4</page>
+ <page href="license.html">Apache 许可证</page>
+</category>
+
+<category id="manual"><title>参考手册</title>
+ <page href="install.html">编译与安装</page>
+ <page href="invoking.html">启动</page>
+ <page href="stopping.html">停止与重启</page>
+ <page href="mod/directives.html">配置指令</page>
+ <page href="mod/quickreference.html">指令快速参考</page>
+ <page href="mod/">模块</page>
+ <page href="mpm.html">多处理模块(MPM)</page>
+ <page href="filter.html">过滤器</page>
+ <page href="handler.html">处理器</page>
+ <page href="expr.html">表达式解析器</page>
+ <page href="programs/">服务器与支持程序</page>
+ <page href="glossary.html">术语</page>
+</category>
+
+<category id="usersguide"><title>用户指南</title>
+ <page href="bind.html">绑定指定地址与端口</page>
+ <page href="configuring.html">配置文件</page>
+ <page href="sections.html">配置片段</page>
+ <page href="caching.html">缓存指南</page>
+ <page href="content-negotiation.html">内容协商</page>
+ <page href="dso.html">动态共享对象(DSO)</page>
+ <page href="env.html">环境变量</page>
+ <page href="logs.html">日志文件</page>
+ <page href="urlmapping.html">从 URL 映射到文件系统</page>
+ <page href="misc/perf-tuning.html">性能调谐</page>
+ <page href="misc/security_tips.html">安全技巧</page>
+ <page href="server-wide.html">服务器全局配置</page>
+ <page href="ssl/">SSL/TLS 加密</page>
+ <page href="suexec.html">执行 CGI 前的用户切换(suEXEC)</page>
+ <page href="rewrite/">URL 改写与 mod_rewrite</page>
+ <page href="vhosts/">虚拟主机</page>
+</category>
+
+<category id="howto"><title>指引/教程</title>
+ <page href="howto/auth.html">认证，授权与访问控制</page>
+ <page href="howto/cgi.html">CGI 与动态内容</page>
+ <page href="howto/htaccess.html">.htaccess 文件</page>
+ <page href="howto/ssi.html">服务器端插入(SSI)</page>
+ <page href="howto/public_html.html">用户私人网站目录
(public_html)</page>
+</category>
+
+<category id="platform"><title>平台相关说明</title>
+ <page href="platform/windows.html">Microsoft Windows</page>
+ <page href="platform/netware.html">Novell NetWare</page>
+ <page href="platform/ebcdic.html">EBCDIC 系统</page>
+</category>
+
+<category id="other"><title>其它主题</title>
+ <page href="http://wiki.apache.org/httpd/FAQ">常见问题</page>
+ <page href="sitemap.html">网站导航</page>
+ <page href="developer/">开发文档</page>
+ <page href="misc/">其它说明</page>
+ <page href="http://wiki.apache.org/httpd/">维基</page>
+</category>
+
+</indexpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/install.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,416 @@
+<?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="install.xml.meta">
+
+ <title>Compiling and Installing</title>
+
+<summary>
+
+ <p>This document covers compilation and installation of the Apache
HTTP Server
+ on Unix and Unix-like systems only. For compiling and
+ installation on Windows, see <a
+ href="platform/windows.html">Using Apache HTTP Server with Microsoft
+ Windows</a>. For other platforms, see the <a
+ href="platform/">platform</a> documentation.</p>
+
+ <p>Apache httpd uses <code>libtool</code> and <code>autoconf</code>
+ to create a build environment that looks like many other Open Source
+ projects.</p>
+
+ <p>If you are upgrading from one minor version to the next (for
+ example, 2.2.50 to 2.2.51), please skip down to the <a
+ href="#upgrading">upgrading</a> section.</p>
+
+</summary>
+
+<seealso><a href="programs/configure.html">Configure the source
tree</a></seealso>
+<seealso><a href="invoking.html">Starting Apache httpd</a></seealso>
+<seealso><a href="stopping.html">Stopping and Restarting</a></seealso>
+
+<section id="overview"><title>Overview for the
+ impatient</title>
+
+ <table>
+ <columnspec><column width=".13"/><column width=".80"/></columnspec>
+ <tr>
+ <td><a href="#download">Download</a></td>
+
+ <td><code>$ lynx http://httpd.apache.org/download.cgi</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><a href="#extract">Extract</a></td>
+
+ <td><code>$ gzip -d httpd-<em>NN</em>.tar.gz<br />
+ $ tar xvf httpd-<em>NN</em>.tar<br />
+ $ cd httpd-<em>NN</em></code></td>
+ </tr>
+
+ <tr>
+ <td><a href="#configure">Configure</a></td>
+
+ <td><code>$ ./configure --prefix=<em>PREFIX</em></code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><a href="#compile">Compile</a></td>
+
+ <td><code>$ make</code> </td>
+ </tr>
+
+ <tr>
+ <td><a href="#install">Install</a></td>
+
+ <td><code>$ make install</code> </td>
+ </tr>
+
+ <tr>
+ <td><a href="#customize">Customize</a></td>
+
+ <td><code>$ vi <em>PREFIX</em>/conf/httpd.conf</code> </td>
+ </tr>
+
+ <tr>
+ <td><a href="#test">Test</a></td>
+
+ <td><code>$ <em>PREFIX</em>/bin/apachectl -k start</code>
+ </td>
+ </tr>
+ </table>
+
+ <p><em>NN</em> must be replaced with the current version
+ number, and <em>PREFIX</em> must be replaced with the
+ filesystem path under which the server should be installed. If
+ <em>PREFIX</em> is not specified, it defaults to
+ <code>/usr/local/apache2</code>.</p>
+
+ <p>Each section of the compilation and installation process is
+ described in more detail below, beginning with the requirements
+ for compiling and installing Apache httpd.</p>
+</section>
+
+<section id="requirements"><title>Requirements</title>
+
+ <p>The following requirements exist for building Apache httpd:</p>
+
+ <dl>
+ <dt>Disk Space</dt>
+ <dd>Make sure you have at least 50 MB of temporary free disk
+ space available. After installation the server occupies
+ approximately 10 MB of disk space. The actual disk space
+ requirements will vary considerably based on your chosen
+ configuration options, any third-party modules, and, of course,
+ the size of the web site or sites that you have on the server.</dd>
+
+ <dt>ANSI-C Compiler and Build System</dt>
+ <dd>Make sure you have an ANSI-C compiler installed. The <a
+ href="http://gcc.gnu.org/">GNU C
+ compiler (GCC)</a> from the <a
+ href="http://www.gnu.org/">Free Software Foundation (FSF)</a>
+ is recommended. If you don't have GCC
+ then at least make sure your vendor's compiler is ANSI
+ compliant. In addition, your <code>PATH</code> must contain
+ basic build tools such as <code>make</code>.</dd>
+
+ <dt>Accurate time keeping</dt>
+ <dd>Elements of the HTTP protocol are expressed as the time of
+ day. So, it's time to investigate setting some time
+ synchronization facility on your system. Usually the
+ <code>ntpdate</code> or <code>xntpd</code> programs are used for
+ this purpose which are based on the Network Time Protocol (NTP).
+ See the <a href="http://www.ntp.org">NTP
+ homepage</a> for more details about NTP software and public
+ time servers.</dd>
+
+ <dt><a href="http://www.perl.org/">Perl 5</a>
+ [OPTIONAL]</dt>
+ <dd>For some of the support scripts like <program>
+ apxs</program> or <program>dbmmanage</program> (which are
+ written in Perl) the Perl 5 interpreter is required (versions
+ 5.003 or newer are sufficient). If you have multiple Perl
+ interpreters (for example, a systemwide install of Perl 4, and
+ your own install of Perl 5), you are advised to use the
+ <code>--with-perl</code> option (see below) to make sure the
+ correct one is used by <program>configure</program>.
+ If no Perl 5 interpreter is found by the
+ <program>configure</program> script, you will not be able to use
+ the affected support scripts. Of course, you will still be able to
+ build and use Apache httpd.</dd>
+ </dl>
+</section>
+
+<section id="download"><title>Download</title>
+
+ <p>The Apache HTTP Server can be downloaded from the <a
+ href="http://httpd.apache.org/download.cgi">Apache HTTP Server
+ download site</a>, which lists several mirrors. Most users of
+ Apache on unix-like systems will be better off downloading and
+ compiling a source version. The build process (described below) is
+ easy, and it allows you to customize your server to suit your needs.
+ In addition, binary releases are often not up to date with the latest
+ source releases. If you do download a binary, follow the instructions
+ in the <code>INSTALL.bindist</code> file inside the distribution.</p>
+
+ <p>After downloading, it is important to verify that you have a
+ complete and unmodified version of the Apache HTTP Server. This
+ can be accomplished by testing the downloaded tarball against the
+ PGP signature. Details on how to do this are available on the <a
+ href="http://httpd.apache.org/download.cgi#verify">download
+ page</a> and an extended example is available describing the <a
+ href="http://httpd.apache.org/dev/verification.html">use of
+ PGP</a>.</p>
+
+</section>
+
+<section id="extract"><title>Extract</title>
+
+ <p>Extracting the source from the Apache HTTP Server tarball is a
+ simple matter of uncompressing, and then untarring:</p>
+
+<example>
+$ gzip -d httpd-<em>NN</em>.tar.gz<br />
+$ tar xvf httpd-<em>NN</em>.tar
+</example>
+
+ <p>This will create a new directory under the current directory
+ containing the source code for the distribution. You should
+ <code>cd</code> into that directory before proceeding with
+ compiling the server.</p>
+</section>
+
+<section id="configure"><title>Configuring the source tree</title>
+
+ <p>The next step is to configure the Apache source tree for your
+ particular platform and personal requirements. This is done using
+ the script <program>configure</program> included in
+ the root directory of the distribution. (Developers downloading
+ an unreleased version of the Apache source tree will need to have
+ <code>autoconf</code> and <code>libtool</code> installed and will
+ need to run <code>buildconf</code> before proceeding with the next
+ steps. This is not necessary for official releases.)</p>
+
+ <p>To configure the source tree using all the default options,
+ simply type <code>./configure</code>. To change the default
+ options, <program>configure</program> accepts a variety of variables
+ and command line options.</p>
+
+ <p>The most important option is the location <code>--prefix</code>
+ where Apache is to be installed later, because Apache has to be
+ configured for this location to work correctly. More fine-tuned
+ control of the location of files is possible with additional <a
+ href="programs/configure.html#installationdirectories">configure
+ options</a>.</p>
+
+ <p>Also at this point, you can specify which <a
+ href="programs/configure.html#optionalfeatures">features</a> you
+ want included in Apache by enabling and disabling <a
+ href="mod/">modules</a>. Apache comes with a wide range of modules
+ included by default. They will be compiled as
+ <a href="dso.html">shared objects (DSOs)</a> which can be loaded
+ or unloaded at runtime.
+ You can also choose to compile modules statically by using the option
+ <code>--enable-<var>module</var>=static</code>.</p>
+
+ <p>Additional modules are enabled using the
+ <code>--enable-<var>module</var></code> option, where
+ <var>module</var> is the name of the module with the
+ <code>mod_</code> string removed and with any underscore converted
+ to a dash. Similarly, you can disable modules with the
+ <code>--disable-<var>module</var></code> option. Be careful when
+ using these options, since <program>configure</program> cannot warn you
+ if the module you specify does not exist; it will simply ignore the
+ option.</p>
+
+ <p>In addition, it is sometimes necessary to provide the
+ <program>configure</program> script with extra information about the
+ location of your compiler, libraries, or header files. This is
+ done by passing either environment variables or command line
+ options to <program>configure</program>. For more information, see the
+ <program>configure</program> manual page. Or invoke
+ <program>configure</program> using the <code>--help</code> option.</p>
+
+ <p>For a short impression of what possibilities you have, here
+ is a typical example which compiles Apache for the installation
+ tree <code>/sw/pkg/apache</code> with a particular compiler and flags
+ plus the two additional modules <module>mod_ldap</module> and
+ <module>mod_lua</module>:</p>
+
+<example>
+ $ CC="pgcc" CFLAGS="-O2" \<br />
+ ./configure --prefix=/sw/pkg/apache \<br />
+ --enable-ldap=shared \<br />
+ --enable-lua=shared
+</example>
+
+ <p>When <program>configure</program> is run it will take several
minutes to
+ test for the availability of features on your system and build
+ Makefiles which will later be used to compile the server.</p>
+
+ <p>Details on all the different <program>configure</program> options
are
+ available on the <program>configure</program> manual page.</p>
+</section>
+
+<section id="compile"><title>Build</title>
+
+ <p>Now you can build the various parts which form the Apache
+ package by simply running the command:</p>
+
+<example>$ make</example>
+
+ <p>Please be patient here, since a base configuration takes
+ several minutes to compile and the time will vary widely
+ depending on your hardware and the number of modules that you
+ have enabled.</p>
+</section>
+
+<section id="install"><title>Install</title>
+
+ <p>Now it's time to install the package under the configured
+ installation <em>PREFIX</em> (see <code>--prefix</code> option
+ above) by running:</p>
+
+<example>$ make install</example>
+
+ <p>This step will typically require root privileges, since
+ <em>PREFIX</em> is usually a directory with restricted write
+ permissions.</p>
+
+ <p>If you are upgrading, the installation will not overwrite
+ your configuration files or documents.</p>
+</section>
+
+<section id="customize"><title>Customize</title>
+
+ <p>Next, you can customize your Apache HTTP server by editing
+ the <a href="configuring.html">configuration files</a> under
+ <code><em>PREFIX</em>/conf/</code>.</p>
+
+<example>$ vi <em>PREFIX</em>/conf/httpd.conf</example>
+
+ <p>Have a look at the Apache manual under
+ <code><em>PREFIX</em>/docs/manual/</code> or consult <a
+ href="http://httpd.apache.org/docs/&httpd.docs;/"
+ >http://httpd.apache.org/docs/&httpd.docs;/</a> for the most recent
+ version of this manual and a complete reference of available <a
+ href="mod/directives.html">configuration directives</a>.</p>
+</section>
+
+<section id="test"><title>Test</title>
+
+ <p>Now you can <a href="invoking.html">start</a> your Apache
+ HTTP server by immediately running:</p>
+
+<example>$ <em>PREFIX</em>/bin/apachectl -k start</example>
+
+ <p>You should then be able to request your first document
+ via the URL <code>http://localhost/</code>. The web page you see is
located
+ under the <directive module="core">DocumentRoot</directive>,
+ which will usually be <code><em>PREFIX</em>/htdocs/</code>.
+ Then <a href="stopping.html">stop</a> the server again by
+ running:</p>
+
+<example>$ <em>PREFIX</em>/bin/apachectl -k stop</example>
+</section>
+<section id="upgrading"><title>Upgrading</title>
+
+ <p>The first step in upgrading is to read the release announcement
+ and the file <code>CHANGES</code> in the source distribution to
+ find any changes that may affect your site. When changing between
+ major releases (for example, from 2.0 to 2.2 or from 2.2 to 2.3),
+ there will likely be major differences in the compile-time and
+ run-time configuration that will require manual adjustments. All
+ modules will also need to be upgraded to accomodate changes in the
+ module API.</p>
+
+ <p>Upgrading from one minor version to the next (for example, from
+ 2.2.55 to 2.2.57) is easier. The <code>make install</code>
+ process will not overwrite any of your existing documents, log
+ files, or configuration files. In addition, the developers make
+ every effort to avoid incompatible changes in the
+ <program>configure</program> options, run-time configuration, or the
+ module API between minor versions. In most cases you should be able to
+ use an identical <program>configure</program> command line, an
identical
+ configuration file, and all of your modules should continue to
+ work.</p>
+
+ <p>To upgrade across minor versions, start by finding the file
+ <code>config.nice</code> in the <code>build</code> directory of
+ your installed server or at the root of the source tree for your
+ old install. This will contain the exact
+ <program>configure</program> command line that you used to
+ configure the source tree. Then to upgrade from one version to
+ the next, you need only copy the <code>config.nice</code> file to
+ the source tree of the new version, edit it to make any desired
+ changes, and then run:</p>
+
+ <example>
+ $ ./config.nice<br />
+ $ make<br />
+ $ make install<br />
+ $ <em>PREFIX</em>/bin/apachectl -k graceful-stop<br />
+ $ <em>PREFIX</em>/bin/apachectl -k start<br />
+ </example>
+
+ <note type="warning">You should always test any new version in your
+ environment before putting it into production. For example, you
+ can install and run the new version along side the old one by
+ using a different <code>--prefix</code> and a
+ different port (by adjusting the <directive
+ module="mpm_common">Listen</directive> directive) to test for any
+ incompatibilities before doing the final upgrade.</note>
+
+ <p>You can pass additional arguments to <code>config.nice</code>,
+ which will be appended to your original <program>configure</program>
+ options:</p>
+
+ <example>
+ $ ./config.nice --prefix=/home/test/apache --with-port=90
+ </example>
+</section>
+<section id="thirdp"><title>Third-party packages</title>
+
+ <p>A large number of third parties provide their own packaged
+ distributions of the Apache HTTP Server for installation on
+ particular platforms. This includes the various Linux distributions,
+ various third-party Windows packages, Mac OS X, Solaris, and many
+ more.</p>
+
+ <p>Our software license not only permits, but encourages, this kind
+ of redistribution. However, it does result in a situation where the
+ configuration layout and defaults on your installation of the server
+ may differ from what is stated in the documentation. While
+ unfortunate, this situation is not likely to change any time
+ soon.</p>
+
+ <p>A <a
+ href="http://wiki.apache.org/httpd/DistrosDefaultLayout">description
+ of these third-party distrubutions</a> is maintained in the HTTP
+ Server wiki, and should reflect the current state of these
+ third-party distributions. However, you will need to familiarize
+ yourself with your particular platform's package management and
+ installation procedures.</p>
+
+</section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/invoking.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,142 @@
+<?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="invoking.xml.meta">
+
+ <title>Starting Apache</title>
+
+<summary>
+ <p>On Windows, Apache is normally run as a service on Windows
+ NT, 2000 and XP, or as a console application on Windows 9x and
+ ME. For details, see <a
+ href="platform/windows.html#winsvc">Running Apache as a Service</a>
+ and <a href="platform/windows.html#wincons">Running Apache as a
+ Console Application</a>.</p>
+
+ <p>On Unix, the <program>httpd</program> program
+ is run as a daemon that executes continuously in the
+ background to handle requests. This document describes how
+ to invoke <program>httpd</program>.</p>
+</summary>
+
+<seealso><a href="stopping.html">Stopping and Restarting</a></seealso>
+<seealso><program>httpd</program></seealso>
+<seealso><program>apachectl</program></seealso>
+
+<section id="startup"><title>How Apache Starts</title>
+
+ <p>If the <directive module="mpm_common">Listen</directive>
+ specified in the configuration file is default of 80 (or any other
+ port below 1024), then it is necessary to have root privileges in
+ order to start apache, so that it can bind to this privileged
+ port. Once the server has started and performed a few preliminary
+ activities such as opening its log files, it will launch several
+ <em>child</em> processes which do the work of listening for and
+ answering requests from clients. The main <code>httpd</code>
+ process continues to run as the root user, but the child processes
+ run as a less privileged user. This is controlled by the selected
+ <a href="mpm.html">Multi-Processing Module</a>.</p>
+
+ <p>The recommended method of invoking the <program>httpd</program>
+ executable is to use the <program>apachectl</program> control script.
This
+ script sets certain environment variables that are necessary for
+ <program>httpd</program> to function correctly under some operating
+ systems, and then invokes the <program>httpd</program> binary.
+ <program>apachectl</program> will pass through any command line
+ arguments, so any <program>httpd</program> options may also be used
with
+ <program>apachectl</program>. You may also directly edit the
+ <program>apachectl</program> script by changing the <code>HTTPD</code>
+ variable near the top to specify the correct location of the
+ <program>httpd</program> binary and any command-line arguments that you
+ wish to be <em>always</em> present.</p>
+
+ <p>The first thing that <program>httpd</program> does when it is
+ invoked is to locate and read the <a
+ href="configuring.html">configuration file</a>
+ <code>httpd.conf</code>. The location of this file is set at
+ compile-time, but it is possible to specify its location at run
+ time using the <code>-f</code> command-line option as in</p>
+
+<example>/usr/local/apache2/bin/apachectl -f
+ /usr/local/apache2/conf/httpd.conf</example>
+
+ <p>If all goes well during startup, the server will detach from
+ the terminal and the command prompt will return almost
+ immediately. This indicates that the server is up and running.
+ You can then use your browser to connect to the server and view
+ the test page in the <directive
+ module="core">DocumentRoot</directive> directory.</p>
+</section>
+
+<section id="errors"><title>Errors During Start-up</title>
+
+ <p>If Apache suffers a fatal problem during startup, it will
+ write a message describing the problem either to the console or
+ to the <directive module="core">ErrorLog</directive> before
+ exiting. One of the most common error messages is "<code>Unable
+ to bind to Port ...</code>". This message is usually caused by
+ either:</p>
+
+ <ul>
+ <li>Trying to start the server on a privileged port when not
+ logged in as the root user; or</li>
+
+ <li>Trying to start the server when there is another instance
+ of Apache or some other web server already bound to the same
+ Port.</li>
+ </ul>
+
+ <p>For further trouble-shooting instructions, consult the
+ Apache <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a>.</p>
+</section>
+
+<section id="boot"><title>Starting at Boot-Time</title>
+
+ <p>If you want your server to continue running after a system
+ reboot, you should add a call to <program>apachectl</program> to your
+ system startup files (typically <code>rc.local</code> or a file in
+ an <code>rc.N</code> directory). This will start Apache as
+ root. Before doing this ensure that your server is properly
+ configured for security and access restrictions.</p>
+
+ <p>The <program>apachectl</program> script is designed to act like a
+ standard SysV init script; it can take the arguments
+ <code>start</code>, <code>restart</code>, and <code>stop</code>
+ and translate them into the appropriate signals to
+ <program>httpd</program>. So you can often simply link
+ <program>apachectl</program> into the appropriate init directory. But
be
+ sure to check the exact requirements of your system.</p>
+</section>
+
+<section id="info"><title>Additional Information</title>
+
+ <p>Additional information about the command-line options of <program>
+ httpd</program> and <program>apachectl</program> as well as other
support
+ programs included with the server is available on the
+ <a href="programs/">Server and Supporting Programs</a> page.
+ There is also documentation on all the <a
+ href="mod/">modules</a> included with the Apache distribution
+ and the <a href="mod/directives.html">directives</a> that they
+ provide.</p>
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/license.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,240 @@
+<?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="license.xml.meta">
+
+<title>The Apache License, Version 2.0</title>
+
+<summary>
+ <p class="centered">Apache License<br />
+ Version 2.0, January 2004<br />
+ <a href="http://www.apache.org/licenses/"
+ >http://www.apache.org/licenses/</a><br /><br />
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION</p>
+
+ <ol>
+ <li><strong>Definitions</strong><br />
+
+ <p>"License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this
document.</p>
+
+ <p>"Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.</p>
+
+ <p>"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.</p>
+
+ <p>"You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.</p>
+
+ <p>"Source" form shall mean the preferred form for making
modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.</p>
+
+ <p>"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.</p>
+
+ <p>"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).</p>
+
+ <p>"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.</p>
+
+ <p>"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."</p>
+
+ <p>"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.</p></li>
+
+ <li><strong>Grant of Copyright License.</strong> 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.</li>
+
+ <li><strong>Grant of Patent License.</strong> 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.</li>
+
+ <li><strong>Redistribution.</strong> 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:
+
+ <ol type="a">
+ <li>You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and</li>
+
+ <li>You must cause any modified files to carry prominent notices
+ stating that You changed the files; and</li>
+
+ <li>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</li>
+
+ <li>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.</li>
+ </ol>
+
+ <p>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.</p></li>
+
+ <li><strong>Submission of Contributions.</strong> 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.</li>
+
+ <li><strong>Trademarks.</strong> 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.</li>
+
+ <li><strong>Disclaimer of Warranty.</strong> 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.</li>
+
+ <li><strong>Limitation of Liability.</strong> 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.</li>
+
+ <li><strong>Accepting Warranty or Additional Liability.</strong> 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.</li>
+ </ol>
+
+ <p class="centered">END OF TERMS AND CONDITIONS</p>
+
+ <p class="centered">APPENDIX: How to apply the Apache License to your
+ work.</p>
+
+ <p>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.</p>
+
+ <example>
+ <pre>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.</pre>
+ </example>
+</summary>
+</manualpage>
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/logs.xml Sun Feb 27 00:09:47 2011
@@ -0,0 +1,750 @@
+<?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="logs.xml.meta">
+
+ <title>Log Files</title>
+
+ <summary>
+ <p>In order to effectively manage a web server, it is necessary
+ to get feedback about the activity and performance of the
+ server as well as any problems that may be occurring. The Apache HTTP
Server
+ provides very comprehensive and flexible logging
+ capabilities. This document describes how to configure its
+ logging capabilities, and how to understand what the logs
+ contain.</p>
+ </summary>
+
+ <section id="overview">
+ <title>Overview</title>
+
+ <related>
+ <modulelist>
+ <module>mod_log_config</module>
+ <module>mod_log_forensic</module>
+ <module>mod_logio</module>
+ <module>mod_cgi</module>
+ </modulelist>
+ </related>
+
+ <p>
+ The Apache HTTP Server provides a variety of different mechanisms for
+ logging everything that happens on your server, from the initial
+ request, through the URL mapping process, to the final resolution of
+ the connection, including any errors that may have occurred in the
+ process. In addition to this, third-party modules may provide logging
+ capabilities, or inject entries into the existing log files, and
+ applications such as CGI programs, or PHP scripts, or other handlers,
+ may send messages to the server error log.
+ </p>
+
+ <p>
+ In this document we discuss the logging modules that are a standard
+ part of the http server.
+ </p>
+
+ </section>
+
+ <section id="security">
+ <title>Security Warning</title>
+
+ <p>Anyone who can write to the directory where Apache httpd is
+ writing a log file can almost certainly gain access to the uid
+ that the server is started as, which is normally root. Do
+ <em>NOT</em> give people write access to the directory the logs
+ are stored in without being aware of the consequences; see the
+ <a href="misc/security_tips.html">security tips</a> document
+ for details.</p>
+
+ <p>In addition, log files may contain information supplied
+ directly by the client, without escaping. Therefore, it is
+ possible for malicious clients to insert control-characters in
+ the log files, so care must be taken in dealing with raw
+ logs.</p>
+ </section>
+
+ <section id="errorlog">
+ <title>Error Log</title>
+
+ <related>
+ <modulelist>
+ <module>core</module>
+ </modulelist>
+ <directivelist>
+ <directive module="core">ErrorLog</directive>
+ <directive module="core">ErrorLogFormat</directive>
+ <directive module="core">LogLevel</directive>
+ </directivelist>
+ </related>
+
+ <p>The server error log, whose name and location is set by the
+ <directive module="core">ErrorLog</directive> directive, is the
+ most important log file. This is the place where Apache httpd
+ will send diagnostic information and record any errors that it
+ encounters in processing requests. It is the first place to
+ look when a problem occurs with starting the server or with the
+ operation of the server, since it will often contain details of
+ what went wrong and how to fix it.</p>
+
+ <p>The error log is usually written to a file (typically
+ <code>error_log</code> on Unix systems and
+ <code>error.log</code> on Windows and OS/2). On Unix systems it
+ is also possible to have the server send errors to
+ <code>syslog</code> or <a href="#piped">pipe them to a
+ program</a>.</p>
+
+ <p>The format of the error log is relatively free-form and
+ descriptive. But there is certain information that is contained
+ in most error log entries. For example, here is a typical
+ message.</p>
+
+ <example>
+ [Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1]
+ client denied by server configuration:
+ /export/home/live/ap/htdocs/test
+ </example>
+
+ <p>The first item in the log entry is the date and time of the
+ message. The second item lists the severity of the error being
+ reported. The <directive module="core">LogLevel</directive>
+ directive is used to control the types of errors that are sent
+ to the error log by restricting the severity level. The third
+ item gives the IP address of the client that generated the
+ error. Beyond that is the message itself, which in this case
+ indicates that the server has been configured to deny the
+ client access. The server reports the file-system path (as
+ opposed to the web path) of the requested document.</p>
+
+ <p>A very wide variety of different messages can appear in the
+ error log. Most look similar to the example above. The error
+ log will also contain debugging output from CGI scripts. Any
+ information written to <code>stderr</code> by a CGI script will
+ be copied directly to the error log.</p>
+
+ <p>It is not possible to customize the error log by adding or
+ removing information. However, error log entries dealing with
+ particular requests have corresponding entries in the <a
+ href="#accesslog">access log</a>. For example, the above example
+ entry corresponds to an access log entry with status code 403.
+ Since it is possible to customize the access log, you can
+ obtain more information about error conditions using that log
+ file.</p>
+
+ <p>During testing, it is often useful to continuously monitor
+ the error log for any problems. On Unix systems, you can
+ accomplish this using:</p>
+
+ <example>
+ tail -f error_log
+ </example>
+ </section>
+
+ <section id="permodule">
+ <title>Per-module logging</title>
+
+ <p>The <directive module="core">LogLevel</directive> directive
+ allows you to specify a log severity level on a per-module basis. In
+ this way, if you are troubleshooting a problem with just one
+ particular module, you can turn up its logging volume without also
+ getting the details of other modules that you're not interested in.
+ This is particularly useful for modules such as
+ <module>mod_proxy</module> or <module>mod_rewrite</module> where you
+ want to know details about what it's trying to do.</p>
+
+ <p>Do this by specifying the name of the module in your
+ <directive>LogLevel</directive> directive:</p>
+
+ <example>
+ LogLevel info rewrite:trace5
+ </example>
+
+ <p>This sets the main <directive>LogLevel</directive> to info, but
+ turns it up to <code>trace5</code> for
+ <module>mod_rewrite</module>.</p>
+
+ <note>This replaces the per-module logging directives, such as
+ <code>RewriteLog</code>, that were present in earlier versions of
+ the server.</note>
+ </section>
+
+ <section id="accesslog">
+ <title>Access Log</title>
+
+ <related>
+ <modulelist>
+ <module>mod_log_config</module>
+ <module>mod_setenvif</module>
+ </modulelist>
+ <directivelist>
+ <directive module="mod_log_config">CustomLog</directive>
+ <directive module="mod_log_config">LogFormat</directive>
+ <directive module="mod_setenvif">SetEnvIf</directive>
+ </directivelist>
+ </related>
+
+ <p>The server access log records all requests processed by the
+ server. The location and content of the access log are
+ controlled by the <directive
module="mod_log_config">CustomLog</directive>
+ directive. The <directive module="mod_log_config">LogFormat</directive>
+ directive can be used to simplify the selection of
+ the contents of the logs. This section describes how to configure the
server
+ to record information in the access log.</p>
+
+ <p>Of course, storing the information in the access log is only
+ the start of log management. The next step is to analyze this
+ information to produce useful statistics. Log analysis in
+ general is beyond the scope of this document, and not really
+ part of the job of the web server itself. For more information
+ about this topic, and for applications which perform log
+ analysis, check the <a
+
href="http://dmoz.org/Computers/Software/Internet/Site_Management/Log_analysis/">
+ Open Directory</a> or <a
+
href="http://dir.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Servers/Log_Analysis_Tools/">
+ Yahoo</a>.</p>
+
+ <p>Various versions of Apache httpd have used other modules and
+ directives to control access logging, including
+ mod_log_referer, mod_log_agent, and the
+ <code>TransferLog</code> directive. The <directive
+ module="mod_log_config">CustomLog</directive> directive now subsumes
+ the functionality of all the older directives.</p>
+
+ <p>The format of the access log is highly configurable. The format
+ is specified using a format string that looks much like a C-style
+ printf(1) format string. Some examples are presented in the next
+ sections. For a complete list of the possible contents of the
+ format string, see the <module>mod_log_config</module> <a
+ href="mod/mod_log_config.html#formats">format strings</a>.</p>
+
+ <section id="common">
+ <title>Common Log Format</title>
+
+ <p>A typical configuration for the access log might look as
+ follows.</p>
+
+ <example>
+ LogFormat "%h %l %u %t \"%r\" %>s %b" common<br />
+ CustomLog logs/access_log common
+ </example>
+
+ <p>This defines the <em>nickname</em> <code>common</code> and
+ associates it with a particular log format string. The format
+ string consists of percent directives, each of which tell the
+ server to log a particular piece of information. Literal
+ characters may also be placed in the format string and will be
+ copied directly into the log output. The quote character
+ (<code>"</code>) must be escaped by placing a backslash before
+ it to prevent it from being interpreted as the end of the
+ format string. The format string may also contain the special
+ control characters "<code>\n</code>" for new-line and
+ "<code>\t</code>" for tab.</p>
+
+ <p>The <directive module="mod_log_config">CustomLog</directive>
+ directive sets up a new log file using the defined
+ <em>nickname</em>. The filename for the access log is relative to
+ the <directive module="core">ServerRoot</directive> unless it
+ begins with a slash.</p>
+
+ <p>The above configuration will write log entries in a format
+ known as the Common Log Format (CLF). This standard format can
+ be produced by many different web servers and read by many log
+ analysis programs. The log file entries produced in CLF will
+ look something like this:</p>
+
+ <example>
+ 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET
+ /apache_pb.gif HTTP/1.0" 200 2326
+ </example>
+
+ <p>Each part of this log entry is described below.</p>
+
+ <dl>
+ <dt><code>127.0.0.1</code> (<code>%h</code>)</dt>
+
+ <dd>This is the IP address of the client (remote host) which
+ made the request to the server. If <directive
+ module="core">HostnameLookups</directive> is
+ set to <code>On</code>, then the server will try to determine
+ the hostname and log it in place of the IP address. However,
+ this configuration is not recommended since it can
+ significantly slow the server. Instead, it is best to use a
+ log post-processor such as <program>logresolve</program> to
determine
+ the hostnames. The IP address reported here is not
+ necessarily the address of the machine at which the user is
+ sitting. If a proxy server exists between the user and the
+ server, this address will be the address of the proxy, rather
+ than the originating machine.</dd>
+
+ <dt><code>-</code> (<code>%l</code>)</dt>
+
+ <dd>The "hyphen" in the output indicates that the requested
+ piece of information is not available. In this case, the
+ information that is not available is the RFC 1413 identity of
+ the client determined by <code>identd</code> on the clients
+ machine. This information is highly unreliable and should
+ almost never be used except on tightly controlled internal
+ networks. Apache httpd will not even attempt to determine
+ this information unless <directive
+ module="core">IdentityCheck</directive> is set
+ to <code>On</code>.</dd>
+
+ <dt><code>frank</code> (<code>%u</code>)</dt>
+
+ <dd>This is the userid of the person requesting the document
+ as determined by HTTP authentication. The same value is
+ typically provided to CGI scripts in the
+ <code>REMOTE_USER</code> environment variable. If the status
+ code for the request (see below) is 401, then this value
+ should not be trusted because the user is not yet
+ authenticated. If the document is not password protected,
+ this part will be "<code>-</code>" just like the previous
+ one.</dd>
+
+ <dt><code>[10/Oct/2000:13:55:36 -0700]</code>
+ (<code>%t</code>)</dt>
+
+ <dd>
+ The time that the request was received.
+ The format is:
+
+ <p class="indent">
+ <code>[day/month/year:hour:minute:second zone]<br />
+ day = 2*digit<br />
+ month = 3*letter<br />
+ year = 4*digit<br />
+ hour = 2*digit<br />
+ minute = 2*digit<br />
+ second = 2*digit<br />
+ zone = (`+' | `-') 4*digit</code>
+ </p>
+ <p>It is possible to have the time displayed in another format
+ by specifying <code>%{format}t</code> in the log format
+ string, where <code>format</code> is either as in
+ <code>strftime(3)</code> from the C standard library,
+ or one of the supported special tokens. For details see
+ the <module>mod_log_config</module> <a
+ href="mod/mod_log_config.html#formats">format strings</a>.</p>
+ </dd>
+
+ <dt><code>"GET /apache_pb.gif HTTP/1.0"</code>
+ (<code>\"%r\"</code>)</dt>
+
+ <dd>The request line from the client is given in double
+ quotes. The request line contains a great deal of useful
+ information. First, the method used by the client is
+ <code>GET</code>. Second, the client requested the resource
+ <code>/apache_pb.gif</code>, and third, the client used the
+ protocol <code>HTTP/1.0</code>. It is also possible to log
+ one or more parts of the request line independently. For
+ example, the format string "<code>%m %U%q %H</code>" will log
+ the method, path, query-string, and protocol, resulting in
+ exactly the same output as "<code>%r</code>".</dd>
+
+ <dt><code>200</code> (<code>%>s</code>)</dt>
+
+ <dd>This is the status code that the server sends back to the
+ client. This information is very valuable, because it reveals
+ whether the request resulted in a successful response (codes
+ beginning in 2), a redirection (codes beginning in 3), an
+ error caused by the client (codes beginning in 4), or an
+ error in the server (codes beginning in 5). The full list of
+ possible status codes can be found in the <a
+ href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">HTTP
+ specification</a> (RFC2616 section 10).</dd>
+
+ <dt><code>2326</code> (<code>%b</code>)</dt>
+
+ <dd>The last part indicates the size of the object returned
+ to the client, not including the response headers. If no
+ content was returned to the client, this value will be
+ "<code>-</code>". To log "<code>0</code>" for no content, use
+ <code>%B</code> instead.</dd>
+ </dl>
+ </section>
+
+ <section id="combined">
+ <title>Combined Log Format</title>
+
+ <p>Another commonly used format string is called the Combined
+ Log Format. It can be used as follows.</p>
+
+ <example>
+ LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
+ \"%{User-agent}i\"" combined<br />
+ CustomLog log/access_log combined
+ </example>
+
+ <p>This format is exactly the same as the Common Log Format,
+ with the addition of two more fields. Each of the additional
+ fields uses the percent-directive
+ <code>%{<em>header</em>}i</code>, where <em>header</em> can be
+ any HTTP request header. The access log under this format will
+ look like:</p>
+
+ <example>
+ 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET
+ /apache_pb.gif HTTP/1.0" 200 2326
+ "http://www.example.com/start.html" "Mozilla/4.08 [en]
+ (Win98; I ;Nav)"
+ </example>
+
+ <p>The additional fields are:</p>
+
+ <dl>
+ <dt><code>"http://www.example.com/start.html"</code>
+ (<code>\"%{Referer}i\"</code>)</dt>
+
+ <dd>The "Referer" (sic) HTTP request header. This gives the
+ site that the client reports having been referred from. (This
+ should be the page that links to or includes
+ <code>/apache_pb.gif</code>).</dd>
+
+ <dt><code>"Mozilla/4.08 [en] (Win98; I ;Nav)"</code>
+ (<code>\"%{User-agent}i\"</code>)</dt>
+
+ <dd>The User-Agent HTTP request header. This is the
+ identifying information that the client browser reports about
+ itself.</dd>
+ </dl>
+ </section>
+
+ <section id="multiple">
+ <title>Multiple Access Logs</title>
+
+ <p>Multiple access logs can be created simply by specifying
+ multiple <directive module="mod_log_config">CustomLog</directive>
+ directives in the configuration
+ file. For example, the following directives will create three
+ access logs. The first contains the basic CLF information,
+ while the second and third contain referer and browser
+ information. The last two <directive
+ module="mod_log_config">CustomLog</directive> lines show how
+ to mimic the effects of the <code>ReferLog</code> and <code
+ >AgentLog</code> directives.</p>
+
+ <example>
+ LogFormat "%h %l %u %t \"%r\" %>s %b" common<br />
+ CustomLog logs/access_log common<br />
+ CustomLog logs/referer_log "%{Referer}i -> %U"<br />
+ CustomLog logs/agent_log "%{User-agent}i"
+ </example>
+
+ <p>This example also shows that it is not necessary to define a
+ nickname with the <directive
+ module="mod_log_config">LogFormat</directive> directive. Instead,
+ the log format can be specified directly in the <directive
+ module="mod_log_config">CustomLog</directive> directive.</p>
+ </section>
+
+ <section id="conditional">
+ <title>Conditional Logs</title>
+
+ <p>There are times when it is convenient to exclude certain
+ entries from the access logs based on characteristics of the
+ client request. This is easily accomplished with the help of <a
+ href="env.html">environment variables</a>. First, an
+ environment variable must be set to indicate that the request
+ meets certain conditions. This is usually accomplished with
+ <directive module="mod_setenvif">SetEnvIf</directive>. Then the
+ <code>env=</code> clause of the <directive
+ module="mod_log_config">CustomLog</directive> directive is used to
+ include or exclude requests where the environment variable is
+ set. Some examples:</p>
+
+ <example>
+ # Mark requests from the loop-back interface<br />
+ SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog<br />
+ # Mark requests for the robots.txt file<br />
+ SetEnvIf Request_URI "^/robots\.txt$" dontlog<br />
+ # Log what remains<br />
+ CustomLog logs/access_log common env=!dontlog
+ </example>
+
+ <p>As another example, consider logging requests from
+ english-speakers to one log file, and non-english speakers to a
+ different log file.</p>
+
+ <example>
+ SetEnvIf Accept-Language "en" english<br />
+ CustomLog logs/english_log common env=english<br />
+ CustomLog logs/non_english_log common env=!english
+ </example>
+
+ <p>In a caching scenario one would want to know about
+ the efficiency of the cache. A very simple method to
+ find this out would be:</p>
+
+ <example>
+ SetEnv CACHE_MISS 1<br />
+ LogFormat "%h %l %u %t "%r " %>s %b %{CACHE_MISS}e"
common-cache<br />
+ CustomLog logs/access_log common-cache
+ </example>
+
+ <p><module>mod_cache</module> will run before
+ <module>mod_env</module> and when successfull will deliver the
+ content without it. In that case a cache hit will log
+ <code>-</code>, while a cache miss will log <code>1</code>.</p>
+
+ <p>In addition to the <code>env=</code> syntax, <directive
+ module="mod_log_config">LogFormat</directive> supports logging values
+ conditional upon the HTTP response code:</p>
+
+ <example>
+ LogFormat "%400,501{User-agent}i" browserlog<br />
+ LogFormat "%!200,304,302{Referer}i" refererlog
+ </example>
+
+ <p>In the first example, the <code>User-agent</code> will be
+ logged if the HTTP status code is 400 or 501. In other cases, a
+ literal "-" will be logged instead. Likewise, in the second
+ example, the <code>Referer</code> will be logged if the HTTP
+ status code is <strong>not</strong> 200, 204, or 302. (Note the
+ "!" before the status codes.</p>
+
+ <p>Although we have just shown that conditional logging is very
+ powerful and flexible, it is not the only way to control the
+ contents of the logs. Log files are more useful when they
+ contain a complete record of server activity. It is often
+ easier to simply post-process the log files to remove requests
+ that you do not want to consider.</p>
+ </section>
+ </section>
+
+ <section id="rotation">
+ <title>Log Rotation</title>
+
+ <p>On even a moderately busy server, the quantity of
+ information stored in the log files is very large. The access
+ log file typically grows 1 MB or more per 10,000 requests. It
+ will consequently be necessary to periodically rotate the log
+ files by moving or deleting the existing logs. This cannot be
+ done while the server is running, because Apache httpd will continue
+ writing to the old log file as long as it holds the file open.
+ Instead, the server must be <a
+ href="stopping.html">restarted</a> after the log files are
+ moved or deleted so that it will open new log files.</p>
+
+ <p>By using a <em>graceful</em> restart, the server can be
+ instructed to open new log files without losing any existing or
+ pending connections from clients. However, in order to
+ accomplish this, the server must continue to write to the old
+ log files while it finishes serving old requests. It is
+ therefore necessary to wait for some time after the restart
+ before doing any processing on the log files. A typical
+ scenario that simply rotates the logs and compresses the old
+ logs to save space is:</p>
+
+ <example>
+ mv access_log access_log.old<br />
+ mv error_log error_log.old<br />
+ apachectl graceful<br />
+ sleep 600<br />
+ gzip access_log.old error_log.old
+ </example>
+
+ <p>Another way to perform log rotation is using <a
+ href="#piped">piped logs</a> as discussed in the next
+ section.</p>
+ </section>
+
+ <section id="piped">
+ <title>Piped Logs</title>
+
+ <p>Apache httpd is capable of writing error and access log
+ files through a pipe to another process, rather than directly
+ to a file. This capability dramatically increases the
+ flexibility of logging, without adding code to the main server.
+ In order to write logs to a pipe, simply replace the filename
+ with the pipe character "<code>|</code>", followed by the name
+ of the executable which should accept log entries on its
+ standard input. The server will start the piped-log process when
+ the server starts, and will restart it if it crashes while the
+ server is running. (This last feature is why we can refer to
+ this technique as "reliable piped logging".)</p>
+
+ <p>Piped log processes are spawned by the parent Apache httpd
+ process, and inherit the userid of that process. This means
+ that piped log programs usually run as root. It is therefore
+ very important to keep the programs simple and secure.</p>
+
+ <p>One important use of piped logs is to allow log rotation
+ without having to restart the server. The Apache HTTP Server
+ includes a simple program called <program>rotatelogs</program>
+ for this purpose. For example, to rotate the logs every 24 hours, you
+ can use:</p>
+
+ <example>
+ CustomLog "|/usr/local/apache/bin/rotatelogs
+ /var/log/access_log 86400" common
+ </example>
+
+ <p>Notice that quotes are used to enclose the entire command
+ that will be called for the pipe. Although these examples are
+ for the access log, the same technique can be used for the
+ error log.</p>
+
+ <p>A similar but much more flexible log rotation program
+ called <a href="http://www.cronolog.org/">cronolog</a>
+ is available at an external site.</p>
+
+ <p>As with conditional logging, piped logs are a very powerful
+ tool, but they should not be used where a simpler solution like
+ off-line post-processing is available.</p>
+
+ <p>By default the piped log process is spawned without invoking
+ a shell. Use "<code>|$</code>" instead of "<code>|</code>"
+ to spawn using a shell (usually with <code>/bin/sh -c</code>):</p>
+
+ <example>
+ # Invoke "rotatelogs" using a shell<br />
+ CustomLog "|$/usr/local/apache/bin/rotatelogs
+ /var/log/access_log 86400" common
+ </example>
+
+ <p>This was the default behaviour for Apache 2.2.
+ Depending on the shell specifics this might lead to
+ an additional shell process for the lifetime of the logging
+ pipe program and signal handling problems during restart.
+ For compatibility reasons with Apache 2.2 the notation
+ "<code>||</code>" is also supported and equivalent to using
+ "<code>|</code>".</p>
+ </section>
+
+ <section id="virtualhost">
+ <title>Virtual Hosts</title>
+
+ <p>When running a server with many <a href="vhosts/">virtual
+ hosts</a>, there are several options for dealing with log
+ files. First, it is possible to use logs exactly as in a
+ single-host server. Simply by placing the logging directives
+ outside the <directive module="core"
+ type="section">VirtualHost</directive> sections in the
+ main server context, it is possible to log all requests in the
+ same access log and error log. This technique does not allow
+ for easy collection of statistics on individual virtual
+ hosts.</p>
+
+ <p>If <directive module="mod_log_config">CustomLog</directive>
+ or <directive module="core">ErrorLog</directive>
+ directives are placed inside a
+ <directive module="core" type="section">VirtualHost</directive>
+ section, all requests or errors for that virtual host will be
+ logged only to the specified file. Any virtual host which does
+ not have logging directives will still have its requests sent
+ to the main server logs. This technique is very useful for a
+ small number of virtual hosts, but if the number of hosts is
+ very large, it can be complicated to manage. In addition, it
+ can often create problems with <a
+ href="vhosts/fd-limits.html">insufficient file
+ descriptors</a>.</p>
+
+ <p>For the access log, there is a very good compromise. By
+ adding information on the virtual host to the log format
+ string, it is possible to log all hosts to the same log, and
+ later split the log into individual files. For example,
+ consider the following directives.</p>
+
+ <example>
+ LogFormat "%v %l %u %t \"%r\" %>s %b"
+ comonvhost<br />
+ CustomLog logs/access_log comonvhost
+ </example>
+
+ <p>The <code>%v</code> is used to log the name of the virtual
+ host that is serving the request. Then a program like <a
+ href="programs/other.html">split-logfile</a> can be used to
+ post-process the access log in order to split it into one file
+ per virtual host.</p>
+ </section>
+
+ <section id="other">
+ <title>Other Log Files</title>
+
+ <related>
+ <modulelist>
+ <module>mod_logio</module>
+ <module>mod_log_config</module>
+ <module>mod_log_forensic</module>
+ <module>mod_cgi</module>
+ </modulelist>
+
+ <directivelist>
+ <directive module="mod_log_config">LogFormat</directive>
+ <directive module="mod_log_config">BufferedLogs</directive>
+ <directive module="mod_log_forensic">ForensicLog</directive>
+ <directive module="mpm_common">PidFile</directive>
+ <directive module="mod_cgi">ScriptLog</directive>
+ <directive module="mod_cgi">ScriptLogBuffer</directive>
+ <directive module="mod_cgi">ScriptLogLength</directive>
+ </directivelist>
+ </related>
+
+ <section>
+ <title>Logging actual bytes sent and received</title>
+
+ <p><module>mod_logio</module> adds in two additional
+ <directive module="mod_log_config">LogFormat</directive> fields
+ (%I and %O) that log the actual number of bytes received and sent
+ on the network.</p>
+ </section>
+
+ <section>
+ <title>Forensic Logging</title>
+
+ <p><module>mod_log_forensic</module> provides for forensic logging of
+ client requests. Logging is done before and after processing a
+ request, so the forensic log contains two log lines for each
+ request. The forensic logger is very strict with no
customizations.
+ It can be an invaluable debugging and security tool.</p>
+ </section>
+
+ <section id="pidfile">
+ <title>PID File</title>
+
+ <p>On startup, Apache httpd saves the process id of the parent
+ httpd process to the file <code>logs/httpd.pid</code>. This
+ filename can be changed with the <directive
+ module="mpm_common">PidFile</directive> directive. The
+ process-id is for use by the administrator in restarting and
+ terminating the daemon by sending signals to the parent
+ process; on Windows, use the -k command line option instead.
+ For more information see the <a href="stopping.html">Stopping
+ and Restarting</a> page.</p>
+ </section>
+
+ <section id="scriptlog">
+ <title>Script Log</title>
+
+ <p>In order to aid in debugging, the
+ <directive module="mod_cgi">ScriptLog</directive> directive
+ allows you to record the input to and output from CGI scripts.
+ This should only be used in testing - not for live servers.
+ More information is available in the <a
+ href="mod/mod_cgi.html">mod_cgi</a> documentation.</p>
+ </section>
+
+ </section>
+</manualpage>
+
+
+
+
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/mpm.xml Sun Feb 27 00:09:47 2011
@@ -0,0 +1,134 @@
+<?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="mpm.xml.meta">
+
+ <title>Multi-Processing Modules (MPMs)</title>
+
+<summary>
+<p>This document describes what a Multi-Processing Module is and
+how they are used by the Apache HTTP Server.</p>
+</summary>
+
+<section id="introduction"><title>Introduction</title>
+
+ <p>The Apache HTTP Server is designed to be a powerful and
+ flexible web server that can work on a very wide variety of
+ platforms in a range of different environments. Different
+ platforms and different environments often require different
+ features, or may have different ways of implementing the same
+ feature most efficiently. Apache httpd has always accommodated a wide
+ variety of environments through its modular design. This design
+ allows the webmaster to choose which features will be included
+ in the server by selecting which modules to load either at
+ compile-time or at run-time.</p>
+
+ <p>Apache HTTP Server 2.0 extends this modular design to the most basic
+ functions of a web server. The server ships with a selection of
+ Multi-Processing Modules (MPMs) which are responsible for
+ binding to network ports on the machine, accepting requests,
+ and dispatching children to handle the requests.</p>
+
+ <p>Extending the modular design to this level of the server
+ allows two important benefits:</p>
+
+ <ul>
+ <li>Apache httpd can more cleanly and efficiently support a wide
+ variety of operating systems. In particular, the Windows
+ version of the server is now much more efficient, since
+ <module>mpm_winnt</module> can use native
+ networking features in place of the POSIX layer used in
+ Apache httpd 1.3. This benefit also extends to other operating
+ systems that implement specialized MPMs.</li>
+
+ <li>The server can be better customized for the needs of the
+ particular site. For example, sites that need a great deal of
+ scalability can choose to use a threaded MPM like
+ <module>worker</module> or <module>event</module>, while sites
requiring
+ stability or compatibility with older software can use a
+ <module>prefork</module>.</li>
+ </ul>
+
+ <p>At the user level, MPMs appear much like other Apache httpd
+ modules. The main difference is that one and only one MPM must
+ be loaded into the server at any time. The list of available
+ MPMs appears on the <a href="mod/">module index page</a>.</p>
+
+</section>
+
+<section id="defaults"><title>MPM Defaults</title>
+
+<p>The following table lists the default MPMs for various operating
+systems. This will be the MPM selected if you do not make another
+choice at compile-time.</p>
+
+<table border="1" style="zebra">
+<columnspec><column width=".2"/><column width=".2"/></columnspec>
+<tr><td>Netware</td><td><module>mpm_netware</module></td></tr>
+<tr><td>OS/2</td><td><module>mpmt_os2</module></td></tr>
+<tr><td>Unix</td><td><module>prefork</module>, <module>worker</module>, or
+ <module>event</module>, depending on platform capabilities</td></tr>
+<tr><td>Windows</td><td><module>mpm_winnt</module></td></tr>
+</table>
+</section>
+
+<section id="static"><title>Building an MPM as a static module</title>
+
+ <p>MPMs can be built as static modules on all platforms. A single MPM
+ is chosen at build time and linked into the server. The server must
+ be rebuilt in order to change the MPM.</p>
+
+ <p>To override the default MPM choice, use the
+ <code>--with-mpm=<em>NAME</em></code> option of the
+ <program>configure</program> script. <em>NAME</em> is the name of the
+ desired MPM.</p>
+
+ <p>Once the server has been compiled, it is possible to determine
which MPM
+ was chosen by using <code>./httpd -l</code>. This command will list
every
+ module that is compiled into the server, including the MPM.</p>
+
+</section>
+
+<section id="dynamic"><title>Building an MPM as a DSO module</title>
+
+ <p>On Unix and similar platforms, MPMs can be built as DSO modules and
+ dynamically loaded into the server in the same manner as other DSO
+ modules. Building MPMs as DSO modules allows the MPM to be changed by
+ updating the <directive module="mod_so">LoadModule</directive>
directive
+ for the MPM instead of by rebuilding the server.</p>
+
+ <p>This feature is enabled using the
+ <code>--enable-mpms-shared</code> option of the
<program>configure</program>
+ script.
+ With argument <code><em>all</em></code>, all possible MPMs for the
platform
+ will be installed. Alternately, a list of MPMs can be specified as the
+ argument.</p>
+
+ <p>The default MPM, either selected automatically or specified with the
+ <code>--with-mpm</code> option of the <program>configure</program>
+ script, will be loaded in the generated server configuration file.
Edit the
+ <directive module="mod_so">LoadModule</directive> directive to select a
+ different MPM.</p>
+
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/mpm.xml.zh-cn Sun Feb 27 00:09:47
2011
@@ -0,0 +1,110 @@
+<?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="mpm.xml.meta">
+
+ <title>多处理模块(MPM)</title>
+
+<summary>
+<p>本文档介绍了什么是多处理模块，以及 Apache HTTP 服务器如何使用它们。</p>
+</summary>
+
+<section id="introduction"><title>介绍</title>
+
+ <p>Apache HTTP 服务器被设计为一个功能强大，并且灵活的 web 服务器，
+ 可以在很多平台与环境中工作。不同平台和不同的环境往往需要不同
+ 的特性，或可能以不同的方式实现相同的特性最有效率。Apache httpd
+ 通过模块化的设计来适应各种环境。这种设计允许网站管理员通过在
+ 编译时或运行时，选择哪些模块将会加载在服务器中，来选择服务器特性。</p>
+
+ <p>Apache HTTP 服务器 2.0 扩展此模块化设计到最基本的 web 服务器功能。
+ 它提供了可以选择的多处理模块(MPM)，用来绑定到网络端口上，接受请求，
+ 以及调度子进程处理请求。</p>
+
+ <p>扩展到这一级别的服务器模块化设计，带来两个重要的好处:</p>
+
+ <ul>
+ <li>Apache httpd 能更优雅，更高效率的支持不同的平台。尤其是
+ Apache httpd 的 Windows 版本现在更有效率了，因为
+ <module>mpm_winnt</module> 能使用原生网络特性取代在
+ Apache httpd 1.3 中使用的 POSIX 层。它也可以扩展到其它平台
+ 来使用专用的 MPM。</li>
+
+ <li>Apache httpd 能更好的为有特殊要求的站点定制。例如，要求
+ 更高伸缩性的站点可以选择使用线程的 MPM，即
+ <module>worker</module> 或 <module>event</module>；
+ 需要可靠性或者与旧软件兼容的站点可以使用
+ <module>prefork</module>。</li>
+ </ul>
+
+ <p>在用户看来，MPM 很像其它 Apache httpd 模块。主要是区别是，在任何时
间，
+ 必须有一个，而且只有一个 MPM 加载到服务器中。可用的 MPM 列表位于
+ <a href="mod/">模块索引页面</a>。</p>
+
+</section>
+
+<section id="defaults"><title>默认 MPM</title>
+
+<p>下表列出了不同系统的默认 MPM。如果你不在编译时选择，那么它就是你将要使用
的 MPM。</p>
+
+<table border="1" style="zebra">
+<columnspec><column width=".2"/><column width=".2"/></columnspec>
+<tr><td>Netware</td><td><module>mpm_netware</module></td></tr>
+<tr><td>OS/2</td><td><module>mpmt_os2</module></td></tr>
+<tr><td>Unix</td><td><module>prefork</module>，<module>worker</module> 或
+ <module>event</module>，取决于平台特性</td></tr>
+<tr><td>Windows</td><td><module>mpm_winnt</module></td></tr>
+</table>
+</section>
+
+<section id="static"><title>构建 MPM 为静态模块</title>
+
+ <p>在全部平台中，MPM 都可以构建为静态模块。在构建时选择一种
+ MPM，链接到服务器中。如果要改变 MPM，必须重新构建。</p>
+
+ <p>为了使用指定的 MPM，请在执行 <program>configure</program> 脚本
+ 时，使用参数 <code>--with-mpm=<em>NAME</em></code>。<em>NAME</em>
+ 是指定的 MPM 名称。</p>
+
+ <p>编译完成后，可以使用 <code>./httpd -l</code> 来确定选择的 MPM。
+ 此命令会列出编译到服务器程序中的所有模块，包括 MPM。</p>
+
+</section>
+
+<section id="dynamic"><title>构建 MPM 为动态模块</title>
+
+ <p>在 Unix 或类似平台中，MPM 可以构建为动态模块，与其它动态模块一样在运
行时加载。
+ 构建 MPM 为动态模块允许通过修改 <directive
module="mod_so">LoadModule</directive>
+ 指令内容来改变 MPM，而不用重新构建服务器程序。</p>
+
+ <p>在执行 <program>configure</program> 脚本时，使用
+ <code>--enable-mpms-shared</code> 选项可以启用此特性。
+ 当给出的参数为 <code><em>all</em></code> 时，所有此平台支持的 MPM
+ 模块都会被安装。还可以在参数中给出模块列表。</p>
+
+ <p>默认 MPM，可以自动选择或者在执行 <program>configure</program>
+ 脚本时通过 <code>--with-mpm</code> 选项来指定，然后出现在生成的服务器配
置文件中。
+ 编辑 <directive module="mod_so">LoadModule</directive> 指令内容可以选择
不同的 MPM。</p>
+
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/new_features_2_0.xml Sun Feb 27
00:09:47 2011
@@ -0,0 +1,234 @@
+<?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_features_2_0.xml.meta">
+
+<title>Overview of new features in Apache HTTP Server 2.0</title>
+
+<summary>
+ <p>This document describes some of the major changes between the
+ 1.3 and 2.0 versions of the Apache HTTP Server.</p>
+</summary>
+
+<seealso><a href="upgrading.html">Upgrading to 2.0 from 1.3</a></seealso>
+
+ <section id="core">
+ <title>Core Enhancements</title>
+
+ <dl>
+ <dt>Unix Threading</dt>
+
+ <dd>On Unix systems with POSIX threads support, Apache httpd can
+ now run in a hybrid multiprocess, multithreaded mode. This
+ improves scalability for many, but not all configurations.</dd>
+
+ <dt>New Build System</dt>
+
+ <dd>The build system has been rewritten from scratch to be
+ based on <code>autoconf</code> and <code>libtool</code>.
+ This makes Apache httpd's configuration system more similar to
+ that of other packages.</dd>
+
+ <dt>Multiprotocol Support</dt>
+
+ <dd>Apache HTTP Server now has some of the infrastructure in place to
+ support serving multiple protocols. <module>mod_echo</module> has
+ been written as an example.</dd>
+
+ <dt>Better support for non-Unix
+ platforms</dt>
+
+ <dd>Apache HTTP Server 2.0 is faster and more stable on non-Unix
+ platforms such as BeOS, OS/2, and Windows. With the
+ introduction of platform-specific <a
+ href="mpm.html">multi-processing modules</a> (MPMs) and the
+ Apache Portable Runtime (APR), these platforms are now
+ implemented in their native API, avoiding the often buggy and
+ poorly performing POSIX-emulation layers.</dd>
+
+ <dt>New Apache httpd API</dt>
+
+ <dd>The API for modules has changed significantly for 2.0.
+ Many of the module-ordering/-priority problems from 1.3 should
+ be gone. 2.0 does much of this automatically, and module ordering
+ is now done per-hook to allow more flexibility. Also, new calls
+ have been added that provide additional module capabilities
+ without patching the core Apache HTTP Server.</dd>
+
+ <dt>IPv6 Support</dt>
+
+ <dd>On systems where IPv6 is supported by the underlying
+ Apache Portable Runtime library, Apache httpd gets IPv6 listening
+ sockets by default. Additionally, the <directive
+ module="mpm_common">Listen</directive>, <directive module="core"
+ >NameVirtualHost</directive>, and <directive module="core"
+ >VirtualHost</directive> directives support
+ IPv6 numeric address strings (e.g., "<code>Listen
+ [2001:db8::1]:8080</code>").</dd>
+
+ <dt>Filtering</dt>
+
+ <dd>Apache httpd modules may now be written as filters which act on
+ the stream of content as it is delivered to or from the
+ server. This allows, for example, the output of CGI scripts to
+ be parsed for Server Side Include directives using the
+ <code>INCLUDES</code> filter in <module>mod_include</module>. The
+ module <module>mod_ext_filter</module> allows external programs to
+ act as filters in much the same way that CGI programs can act as
+ handlers.</dd>
+
+ <dt>Multilanguage Error Responses</dt>
+
+ <dd>Error response messages to the browser are now provided in
+ several languages, using SSI documents. They may be customized
+ by the administrator to achieve a consistent look and feel.</dd>
+
+ <dt>Simplified configuration</dt>
+
+ <dd>Many confusing directives have been simplified. The often
+ confusing <code>Port</code> and <code>BindAddress</code> directives
+ are gone; only the <directive module="mpm_common">Listen</directive>
+ directive is used for IP address binding; the <directive
+ module="core">ServerName</directive> directive specifies the
+ server name and port number only for redirection and vhost
+ recognition.</dd>
+
+ <dt>Native Windows NT Unicode Support</dt>
+
+ <dd>Apache httpd 2.0 on Windows NT now uses utf-8 for all filename
+ encodings. These directly translate to the underlying Unicode
+ file system, providing multilanguage support for all Windows
+ NT-based installations, including Windows 2000 and Windows XP.
+ <em>This support does not extend to Windows 95, 98 or ME, which
+ continue to use the machine's local codepage for filesystem
+ access.</em></dd>
+
+ <dt>Regular Expression Library Updated</dt>
+
+ <dd>Apache httpd 2.0 includes the <a href="http://www.pcre.org/">Perl
+ Compatible Regular Expression Library</a> (PCRE). All regular
+ expression evaluation now uses the more powerful Perl 5
+ syntax.</dd>
+
+ </dl>
+ </section>
+
+ <section id="module">
+ <title>Module Enhancements</title>
+
+ <dl>
+ <dt><module>mod_ssl</module></dt>
+
+ <dd>New module in Apache httpd 2.0. This module is an interface
+ to the SSL/TLS encryption protocols provided by
+ OpenSSL.</dd>
+
+ <dt><module>mod_dav</module></dt>
+
+ <dd>New module in Apache httpd 2.0. This module implements the HTTP
+ Distributed Authoring and Versioning (DAV) specification for
+ posting and maintaining web content.</dd>
+
+ <dt><module>mod_deflate</module></dt>
+
+ <dd>New module in Apache httpd 2.0. This module allows supporting
+ browsers to request that content be compressed before delivery,
+ saving network bandwidth.</dd>
+
+ <dt><module>mod_auth_ldap</module></dt>
+
+ <dd>New module in Apache httpd 2.0.41. This module allows an LDAP
+ database to be used to store credentials for HTTP Basic
+ Authentication. A companion module, <module>mod_ldap</module>
+ provides connection pooling and results caching.</dd>
+
+ <dt><module>mod_auth_digest</module></dt>
+
+ <dd>Includes additional support for session caching across
+ processes using shared memory.</dd>
+
+ <dt><module>mod_charset_lite</module></dt>
+
+ <dd>New module in Apache httpd 2.0. This experimental module allows
+ for character set translation or recoding.</dd>
+
+ <dt><module>mod_file_cache</module></dt>
+
+ <dd>New module in Apache httpd 2.0. This module includes the
+ functionality of <code>mod_mmap_static</code> in Apache HTTP
+ Server version 1.3, plus adds further caching abilities.</dd>
+
+ <dt><module>mod_headers</module></dt>
+
+ <dd>This module is much more flexible in Apache httpd 2.0. It can now
+ modify request headers used by <module>mod_proxy</module>, and
+ it can conditionally set response headers.</dd>
+
+ <dt><module>mod_proxy</module></dt>
+
+ <dd>The proxy module has been completely rewritten to take
+ advantage of the new filter infrastructure and to implement a
+ more reliable, HTTP/1.1 compliant proxy. In addition, new
+ <directive module="mod_proxy" type="section">Proxy</directive>
+ configuration sections provide more readable (and internally
+ faster) control of proxied sites; overloaded <code><Directory
+ "proxy:..."></code> configuration are not supported. The module
+ is now divided into specific protocol support modules including
+ <code>proxy_connect</code>, <code>proxy_ftp</code> and
+ <code>proxy_http</code>.</dd>
+
+ <dt><module>mod_negotiation</module></dt>
+
+ <dd>A new <directive module="mod_negotiation"
+ >ForceLanguagePriority</directive> directive can be used to assure
that
+ the client receives a single document in all cases, rather than
+ NOT ACCEPTABLE or MULTIPLE CHOICES responses. In addition, the
+ negotiation and MultiViews algorithms have been cleaned up to
+ provide more consistent results and a new form of type map that
+ can include document content is provided.</dd>
+
+ <dt><module>mod_autoindex</module></dt>
+
+ <dd>Autoindex'ed directory listings can now be configured to
+ use HTML tables for cleaner formatting, and allow finer-grained
+ control of sorting, including version-sorting, and wildcard
+ filtering of the directory listing.</dd>
+
+ <dt><module>mod_include</module></dt>
+
+ <dd>New directives allow the default start and end tags for SSI
elements
+ to be changed and allow for error and time format configuration
+ to take place in the main configuration file rather than in the
+ SSI document. Results from regular expression parsing and grouping
+ (now based on Perl's regular expression syntax) can be retrieved
+ using <module>mod_include</module>'s variables <code>$0</code>
+ .. <code>$9</code>.</dd>
+
+ <dt><module>mod_auth_dbm</module></dt>
+
+ <dd>Now supports multiple types of DBM-like databases using the
+ <directive module="mod_auth_dbm">AuthDBMType</directive>
+ directive.</dd>
+
+ </dl>
+ </section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/new_features_2_2.xml Sun Feb 27
00:09:47 2011
@@ -0,0 +1,266 @@
+<?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_features_2_2.xml.meta">
+
+<title>Overview of new features in Apache HTTP Server 2.2</title>
+
+<summary>
+ <p>This document describes some of the major changes between the
+ 2.0 and 2.2 versions of the Apache HTTP Server. For new features since
+ version 1.3, see the <a href="new_features_2_0.html">2.0 new
features</a>
+ document.</p>
+</summary>
+
+ <section id="core">
+ <title>Core Enhancements</title>
+ <dl>
+
+ <dt>Authn/Authz</dt>
+ <dd>The bundled authentication and authorization modules have
+ been refactored. The new mod_authn_alias(already removed from
2.3/2.4)
+ module can greatly simplify certain authentication
configurations.
+ See <a href="#module">module name changes</a>, and
+ <a href="#developer">the developer changes</a> for more
+ information about how these changes affects users and module
+ writers.</dd>
+
+ <dt>Caching</dt>
+ <dd><module>mod_cache</module>, <module>mod_cache_disk</module>, and
+ mod_mem_cache(already removed from 2.3/2.4) have undergone a lot
of changes, and
+ are now considered production-quality.
<program>htcacheclean</program>
+ has been introduced to clean up <module>mod_cache_disk</module>
+ setups.</dd>
+
+ <dt>Configuration</dt>
+ <dd>The default configuration layout has been simplified and
+ modularised. Configuration snippets which can be used to
+ enable commonly-used features are now bundled with Apache, and
+ can be easily added to the main server config.</dd>
+
+ <dt>Graceful stop</dt>
+ <dd>The <module>prefork</module>, <module>worker</module> and
+ <module>event</module> MPMs now allow <program>httpd</program>
+ to be shutdown gracefully via the
+ <a
href="stopping.html#gracefulstop"><code>graceful-stop</code></a>
+ signal. The <directive
+ module="mpm_common">GracefulShutdownTimeout</directive> directive
+ has been added to specify an optional timeout, after which
+ <program>httpd</program> will terminate regardless of the status
+ of any requests being served.</dd>
+
+ <dt>Proxying</dt>
+ <dd>The new <module>mod_proxy_balancer</module> module provides
+ load balancing services for <module>mod_proxy</module>.
+ The new <module>mod_proxy_ajp</module> module adds support for
the
+ <code>Apache JServ Protocol version 1.3</code> used by
+ <a href="http://jakarta.apache.org/tomcat/">Apache
Tomcat</a>.</dd>
+
+ <dt>Regular Expression Library Updated</dt>
+ <dd>Version 5.0 of the
+ <a href="http://www.pcre.org/">Perl Compatible Regular Expression
+ Library</a> (PCRE) is now included. <program>httpd</program>
can be
+ configured to use a system installation of PCRE by passing the
+ <code>--with-pcre</code> flag to configure.</dd>
+
+ <dt>Smart Filtering</dt>
+ <dd><module>mod_filter</module> introduces dynamic configuration
+ to the output filter chain. It enables filters to be
conditionally
+ inserted, based on any Request or Response header or environment
+ variable, and dispenses with the more problematic dependencies
and
+ ordering problems in the 2.0 architecture.</dd>
+
+ <dt>Large File Support</dt>
+ <dd><program>httpd</program> is now built with support for files
larger
+ than 2GB on modern 32-bit Unix systems. Support for handling
+ >2GB request bodies has also been added.</dd>
+
+ <dt>Event MPM</dt>
+ <dd>The <module>event</module> MPM uses a separate thread to handle
+ Keep Alive requests and accepting connections. Keep Alive
requests
+ have traditionally required httpd to dedicate a worker to handle
it.
+ This dedicated worker could not be used again until the Keep
Alive
+ timeout was reached.</dd>
+
+ <dt>SQL Database Support</dt>
+ <dd><module>mod_dbd</module>, together with the <code>apr_dbd</code>
+ framework, brings direct SQL support to modules that need it.
+ Supports connection pooling in threaded MPMs.</dd>
+
+ </dl>
+ </section>
+
+ <section id="module">
+ <title>Module Enhancements</title>
+ <dl>
+ <dt>Authn/Authz</dt>
+ <dd>Modules in the aaa directory have been renamed and offer
+ better support for digest authentication. For example,
+ <code>mod_auth</code> is now split into
+ <module>mod_auth_basic</module> and
+ <module>mod_authn_file</module>; <code>mod_auth_dbm</code> is now
+ called <module>mod_authn_dbm</module>; <code>mod_access</code>
has
+ been renamed <module>mod_authz_host</module>. There is also a
new
+ mod_authn_alias(already removed from 2.3/2.4) module for
simplifying
+ certain authentication configurations.
+ </dd>
+
+ <dt><module>mod_authnz_ldap</module></dt>
+ <dd>This module is a port of the 2.0
+ <code>mod_auth_ldap</code> module to the 2.2
<code>Authn/Authz</code>
+ framework. New features include using LDAP attribute values and
+ complicated search filters in the
+ <directive module="mod_authz_core">Require</directive>
directive.</dd>
+
+ <dt><module>mod_authz_owner</module></dt>
+ <dd>A new module that authorizes access to files based
+ on the owner of the file on the file system</dd>
+
+ <dt><module>mod_version</module></dt>
+ <dd>A new module that allows configuration blocks to be enabled
based on the
+ version number of the running server.</dd>
+
+ <dt><module>mod_info</module></dt>
+ <dd>Added a new <code>?config</code> argument which will show
+ the configuration directives as parsed by Apache, including
+ their file name and line number. The module also
+ shows the order of all request hooks and additional
+ build information, similar to <code>httpd -V</code>.</dd>
+
+ <dt><module>mod_ssl</module></dt>
+ 
+ <dd>Added a support for
+ <a href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</a>, which
+ allows connections to upgrade from clear text to TLS
encryption.</dd>
+
+ <dt><module>mod_imagemap</module></dt>
+ <dd><code>mod_imap</code> has been renamed to
+ <module>mod_imagemap</module> to avoid user confusion.</dd>
+ </dl>
+
+ </section>
+
+ <section id="programs">
+ <title>Program Enhancements</title>
+ <dl>
+ <dt><program>httpd</program></dt>
+ <dd>A new command line option <code>-M</code> has been added that
+ lists all modules that are loaded based on the current
+ configuration. Unlike the <code>-l</code> option, this list
+ includes DSOs loaded via <module>mod_so</module>.</dd>
+
+ <dt><program>httxt2dbm</program></dt>
+ <dd>A new program used to generate dbm files from text input,
+ for use in <directive module="mod_rewrite">RewriteMap</directive>
+ with the <code>dbm</code> map type.</dd>
+ </dl>
+ </section>
+
+ <section id="developer">
+ <title>Module Developer Changes</title>
+ <dl>
+ <dt><glossary>APR</glossary> 1.0 API</dt>
+
+ <dd>Apache 2.2 uses the APR 1.0 API. All deprecated functions and
+ symbols have been removed from <code>APR</code> and
+ <code>APR-Util</code>. For details, see the
+ <a href="http://apr.apache.org/">APR Website</a>.</dd>
+
+ <dt>Authn/Authz</dt>
+ <dd>The bundled authentication and authorization modules have
+ been renamed along the following lines:
+ <ul>
+ <li><code>mod_auth_*</code> -> Modules that implement an HTTP
+ authentication mechanism</li>
+ <li><code>mod_authn_*</code> -> Modules that provide a backend
+ authentication provider</li>
+ <li><code>mod_authz_*</code> -> Modules that implement
+ authorization (or access)</li>
+ <li><code>mod_authnz_*</code> -> Module that implements both
+ authentication & authorization</li>
+ </ul>
+ There is a new authentication backend provider
+ scheme which greatly eases the construction of new authentication
+ backends.</dd>
+
+ <dt>Connection Error Logging</dt>
+
+ <dd>A new function, <code>ap_log_cerror</code> has been added to log
+ errors that occur with the client's connection. When logged,
+ the message includes the client IP address.</dd>
+
+ <dt>Test Configuration Hook Added</dt>
+
+ <dd>A new hook, <code>test_config</code> has been added to aid
+ modules that want to execute special code only when the user
passes
+ <code>-t</code> to <program>httpd</program>.</dd>
+
+ <dt>Set Threaded MPM's Stacksize</dt>
+
+ <dd>A new directive, <directive module="mpm_common"
+ >ThreadStackSize</directive> has been added to
+ set the stack size on all threaded MPMs. This is required
+ for some third-party modules on platforms with small default
+ thread stack size.</dd>
+
+ <dt>Protocol handling for output filters</dt>
+
+ <dd>In the past, every filter has been responsible for ensuring
+ that it generates the correct response headers where it affects
+ them. Filters can now delegate common protocol management to
+ <module>mod_filter</module>, using the
+ <code>ap_register_output_filter_protocol</code> or
+ <code>ap_filter_protocol</code> calls.</dd>
+
+ <dt>Monitor hook added</dt>
+ <dd>Monitor hook enables modules to run regular/scheduled jobs
+ in the parent (root) process.</dd>
+
+ <dt>Regular expression API changes</dt>
+
+ <dd>The <code>pcreposix.h</code> header is no longer available;
+ it is replaced by the new <code>ap_regex.h</code> header. The
+ POSIX.2 <code>regex.h</code> implementation exposed by the old
+ header is now available under the <code>ap_</code> namespace
+ from <code>ap_regex.h</code>. Calls to <code>regcomp</code>,
+ <code>regexec</code> and so on can be replaced by calls to
+ <code>ap_regcomp</code>, <code>ap_regexec</code>.</dd>
+
+ <dt>DBD Framework (SQL Database API)</dt>
+
+ <dd><p>With Apache 1.x and 2.0, modules requiring an SQL backend
+ had to take responsibility for managing it themselves. Apart
+ from reinventing the wheel, this can be very inefficient, for
+ example when several modules each maintain their own connections.</p>
+
+ <p>Apache 2.1 and later provides the <code>ap_dbd</code> API for
+ managing database connections (including optimised strategies
+ for threaded and unthreaded MPMs), while APR 1.2 and later provides
+ the <code>apr_dbd</code> API for interacting with the database.</p>
+
+ <p>New modules SHOULD now use these APIs for all SQL database
+ operations. Existing applications SHOULD be upgraded to use it
+ where feasible, either transparently or as a recommended option
+ to their users.</p></dd>
+ </dl>
+ </section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/new_features_2_4.xml Sun Feb 27
00:09:47 2011
@@ -0,0 +1,200 @@
+<?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_features_2_4.xml.meta">
+
+<title>Overview of new features in Apache HTTP Server 2.4</title>
+
+<summary>
+ <p>This document describes some of the major changes between the
+ 2.2 and 2.4 versions of the Apache HTTP Server. For new features since
+ version 2.0, see the <a href="new_features_2_2.html">2.2 new
features</a>
+ document.</p>
+</summary>
+
+ <section id="core">
+ <title>Core Enhancements</title>
+ <dl>
+ <dt>KeepAliveTimeout in milliseconds</dt>
+
+ <dd>It is now possible to specify <directive module="core"
+ >KeepAliveTimeout</directive> in milliseconds.
+ </dd>
+
+ <dt>Loadable MPMs</dt>
+ <dd>Multiple MPMs can now be built as loadable modules at compile
time.
+ The MPM of choice can be configured at run time.</dd>
+
+ <dt>Per-module and per-directory LogLevel configuration</dt>
+ <dd>The <directive module="core">LogLevel</directive> can now be
+ configured per module and per directory. New levels
<code>trace1</code>
+ to <code>trace8</code> have been added above the <code>debug</code>
log
+ level.</dd>
+ </dl>
+ </section>
+
+ <section id="module">
+ <title>Module Enhancements</title>
+ <dl>
+ <dt><module>mod_ssl</module></dt>
+
+ <dd><module>mod_ssl</module> can now be configured to use an
+ OCSP server to check the validation status of a client
+ certificate. The default responder is configurable, along with
+ the decision on whether to prefer the responder designated in
+ the client certificate itself.</dd>
+
+ <dd><module>mod_ssl</module> now also supports OCSP stapling, where
the
+ server pro-actively obtains an OCSP verification of its certificate
and
+ transmits that to the client during the handshake. </dd>
+
+ <dd><module>mod_ssl</module> can now be configured to share SSL
Session
+ data between servers through memcached</dd>
+
+ <dt><module>mod_lua</module></dt>
+
+ <dd>Embeds the <a href="http://www.lua.org/">Lua</a> language into
httpd,
+ for configuration and small business logic functions.</dd>
+
+ <dt><module>mod_proxy</module></dt>
+
+ <dd>The <directive module="mod_proxy">ProxyPass</directive> directive
+ is now most optimally configured within a
+ <directive module="core">Location</directive> or
+ <directive module="core">LocationMatch</directive>
+ block, and offers a significant performance advantage over the
traditional
+ two-parameter syntax when present in large numbers.</dd>
+
+ <dt><module>mod_proxy_fcgi</module></dt>
+
+ <dd>FastCGI Protocol backend for <module>mod_proxy</module></dd>
+
+ <dt><module>mod_cache</module></dt>
+
+ <dd><module>mod_cache</module> can now cache HEAD requests.</dd>
+
+ <dd>Where possible, <module>mod_cache</module> directives can now be
set
+ per directory, instead of per server.</dd>
+
+ <dd>The base URL of cached URLs can be customised, so that a cluster
of
+ caches can share the same endpoint URL prefix.</dd>
+
+ <dd><module>mod_cache</module> is now capable of serving stale cached
+ data when a backend is unavailable (error 5xx).</dd>
+
+ <dd><module>mod_cache</module> can now insert HIT/MISS/REVALIDATE
into
+ an X-Cache header.</dd>
+
+ <dt><module>mod_allowmethods</module></dt>
+ <dd>New module to restrict certain HTTP methods without interfering
with
+ authentication or authorization.</dd>
+
+ <dt><module>mod_include</module></dt>
+ <dd>Support for the 'onerror' attribute within an 'include' element,
+ allowing an error document to be served on error instead of the
default
+ error string.</dd>
+
+ <dt><module>mod_cgi</module>, <module>mod_include</module>,
+ <module>mod_isapi</module>, ...</dt>
+ <dd>Translation of headers to environment variables is more strict
than
+ before to mitigate some possible cross-site-scripting attacks via
header
+ injection. Headers containing invalid characters (including
underscores)
+ are now silently dropped. <a href="env.html">Environment Variables
+ in Apache</a> has some pointers on how to work around broken legacy
+ clients which require such headers. (This affects all modules which
+ use these environment variables.)</dd>
+
+ </dl>
+ </section>
+
+ <section id="programs">
+ <title>Program Enhancements</title>
+ <dl>
+ <dt>fcgistarter</dt>
+ <dd>FastCGI deamon starter utility</dd>
+ <dt>htcacheclean</dt>
+ <dd>Current cached URLs can now be listed, with optional metadata
+ included.</dd>
+ <dd>Allow explicit deletion of individual cached URLs from the
+ cache.</dd>
+ <dd>File sizes can now be rounded up to the given block size,
making
+ the size limits map more closely to the real size on disk.</dd>
+ <dd>Cache size can now be limited by the number of inodes, instead
+ of or in addition to being limited by the size of the files on
+ disk.</dd>
+ </dl>
+ </section>
+
+ <section id="developer">
+ <title>Module Developer Changes</title>
+ <dl>
+ <dt>Check Configuration Hook Added</dt>
+
+ <dd>A new hook, <code>check_config</code>, has been added which runs
+ between the <code>pre_config</code> and <code>open_logs</code>
+ hooks. It also runs before the <code>test_config</code> hook
+ when the <code>-t</code> option is passed to
+ <program>httpd</program>. The <code>check_config</code> hook
+ allows modules to review interdependent configuration directive
+ values and adjust them while messages can still be logged to the
+ console. The user can thus be alerted to misconfiguration
problems
+ before the core <code>open_logs</code> hook function redirects
+ console output to the error log.</dd>
+
+ <dt>Expression Parser Added</dt>
+
+ <dd>We now have a general-purpose expression parser, whose API is
+ exposed in <var>ap_expr.h</var>. This is adapted from the
+ expression parser previously implemented in
+ <module>mod_include</module>.</dd>
+
+ <dt>Authorization Logic Containers</dt>
+
+ <dd>Advanced authorization logic may now be specified using the
+ <directive module="mod_authz_core">Require</directive> directive
+ and the related container directives, such as
+ <directive module="mod_authz_core"
+ type="section">RequireAll</directive>, all
+ provided by the <module>mod_authz_core</module> module.</dd>
+
+ <dt>Small-Object Caching Interface</dt>
+
+ <dd>The <var>ap_socache.h</var> header exposes a provider-based
+ interface for caching small data objects, based on the previous
+ implementation of the <module>mod_ssl</module> session cache.
+ Providers using a shared-memory cyclic buffer, disk-based dbm
+ files, and a memcache distributed cache are currently
+ supported.</dd>
+
+ <dt>Cache Status Hook Added</dt>
+
+ <dd>The <module>mod_cache</module> module now includes a new
+ <code>cache_status</code> hook, which is called when the caching
+ decision becomes known. A default implementation is provided
+ which adds an optional <code>X-Cache</code> and
+ <code>X-Cache-Detail</code> header to the response.</dd>
+ </dl>
+
+ <p>The developer documentation contains a
+ <a href="developer/new_api_2_4.html">detailed list of API
changes</a>.</p>
+ </section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/sections.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,577 @@
+<?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="sections.xml.meta">
+
+<title>Configuration Sections</title>
+
+<summary> <p>Directives in the <a
+href="configuring.html">configuration files</a> may apply to the
+entire server, or they may be restricted to apply only to particular
+directories, files, hosts, or URLs. This document describes how to
+use configuration section containers or <code>.htaccess</code> files
+to change the scope of other configuration directives.</p>
+</summary>
+
+<section id="types"><title>Types of Configuration Section
Containers</title>
+
+<related>
+<modulelist>
+<module>core</module>
+<module>mod_version</module>
+<module>mod_proxy</module>
+</modulelist>
+<directivelist>
+<directive type="section" module="core">Directory</directive>
+<directive type="section" module="core">DirectoryMatch</directive>
+<directive type="section" module="core">Files</directive>
+<directive type="section" module="core">FilesMatch</directive>
+<directive type="section" module="core">If</directive>
+<directive type="section" module="core">IfDefine</directive>
+<directive type="section" module="core">IfModule</directive>
+<directive type="section" module="mod_version">IfVersion</directive>
+<directive type="section" module="core">Location</directive>
+<directive type="section" module="core">LocationMatch</directive>
+<directive type="section" module="mod_proxy">Proxy</directive>
+<directive type="section" module="mod_proxy">ProxyMatch</directive>
+<directive type="section" module="core">VirtualHost</directive>
+</directivelist>
+</related>
+
+<p>There are two basic types of containers. Most containers are
+evaluated for each request. The enclosed directives are applied only
+for those requests that match the containers. The <directive
+type="section" module="core">IfDefine</directive>, <directive
+type="section" module="core">IfModule</directive>, and
+<directive type="section" module="mod_version">IfVersion</directive>
+containers, on the other hand, are evaluated only at server startup
+and restart. If their conditions are true at startup, then the
+enclosed directives will apply to all requests. If the conditions are
+not true, the enclosed directives will be ignored.</p>
+
+<p>The <directive type="section" module="core">IfDefine</directive>
directive
+encloses directives that will only be applied if an appropriate
+parameter is defined on the <program>httpd</program> command line. For
example,
+with the following configuration, all requests will be redirected
+to another site only if the server is started using
+<code>httpd -DClosedForNow</code>:</p>
+
+<example>
+<IfDefine ClosedForNow><br />
+Redirect / http://otherserver.example.com/<br />
+</IfDefine>
+</example>
+
+<p>The <directive type="section" module="core">IfModule</directive>
+directive is very similar, except it encloses directives that will
+only be applied if a particular module is available in the server.
+The module must either be statically compiled in the server, or it
+must be dynamically compiled and its <directive
+module="mod_so">LoadModule</directive> line must be earlier in the
+configuration file. This directive should only be used if you need
+your configuration file to work whether or not certain modules are
+installed. It should not be used to enclose directives that you want
+to work all the time, because it can suppress useful error messages
+about missing modules.</p>
+
+<p>In the following example, the <directive
+module="mod_mime_magic">MimeMagicFiles</directive> directive will be
+applied only if <module>mod_mime_magic</module> is available.</p>
+
+<example>
+<IfModule mod_mime_magic.c><br />
+MimeMagicFile conf/magic<br />
+</IfModule>
+</example>
+
+<p>The <directive type="section" module="mod_version">IfVersion</directive>
+directive is very similar to <directive type="section"
+module="core">IfDefine</directive> and <directive type="section"
+module="core">IfModule</directive>, except it encloses directives that will
+only be applied if a particular version of the server is executing. This
+module is designed for the use in test suites and large networks which
have to
+deal with different httpd versions and different configurations.</p>
+
+<example>
+ <IfVersion >= 2.1><br />
+ <indent>
+ # this happens only in versions greater or<br />
+ # equal 2.1.0.<br />
+ </indent>
+ </IfVersion>
+</example>
+
+<p><directive type="section" module="core">IfDefine</directive>,
+<directive type="section" module="core">IfModule</directive>, and the
+<directive type="section" module="mod_version">IfVersion</directive>
+can apply negative conditions by preceding their test with "!".
+Also, these sections can be nested to achieve more complex
+restrictions.</p>
+</section>
+
+<section id="file-and-web"><title>Filesystem, Webspace, and Boolean
Expressions</title>
+
+<p>The most commonly used configuration section containers are the
+ones that change the configuration of particular places in the
+filesystem or webspace. First, it is important to understand the
+difference between the two. The filesystem is the view of your disks
+as seen by your operating system. For example, in a default install,
+Apache httpd resides at <code>/usr/local/apache2</code> in the Unix
+filesystem or <code>"c:/Program Files/Apache Group/Apache2"</code> in
+the Windows filesystem. (Note that forward slashes should always be
+used as the path separator in Apache httpd configuration files, even for
Windows.) In contrast,
+the webspace is the view of your site as delivered by the web server
+and seen by the client. So the path <code>/dir/</code> in the
+webspace corresponds to the path
+<code>/usr/local/apache2/htdocs/dir/</code> in the filesystem of a
+default Apache httpd install on Unix. The webspace need not map directly
to
+the filesystem, since webpages may be generated dynamically
+from databases or other locations.</p>
+
+<section id="filesystem"><title>Filesystem Containers</title>
+
+<p>The <directive type="section" module="core">Directory</directive>
+and <directive type="section" module="core">Files</directive>
+directives, along with their <glossary ref="regex">regex</glossary>
+counterparts, apply directives to
+parts of the filesystem. Directives enclosed in a <directive
+type="section" module="core">Directory</directive> section apply to
+the named filesystem directory and all subdirectories of that
+directory (as well as the files in those directories).
+The same effect can be obtained using <a
+href="howto/htaccess.html">.htaccess files</a>. For example, in the
+following configuration, directory indexes will be enabled for the
+<code>/var/web/dir1</code> directory and all subdirectories.</p>
+
+<example>
+<Directory /var/web/dir1><br />
+Options +Indexes<br />
+</Directory>
+</example>
+
+<p>Directives enclosed in a <directive type="section"
+module="core">Files</directive> section apply to any file with
+the specified name, regardless of what directory it lies in.
+So for example, the following configuration directives will,
+when placed in the main section of the configuration file,
+deny access to any file named <code>private.html</code> regardless
+of where it is found.</p>
+
+<example>
+<Files private.html><br />
+Order allow,deny<br />
+Deny from all<br />
+</Files>
+</example>
+
+<p>To address files found in a particular part of the filesystem, the
+<directive type="section" module="core">Files</directive> and
+<directive type="section" module="core">Directory</directive> sections
+can be combined. For example, the following configuration will deny
+access to <code>/var/web/dir1/private.html</code>,
+<code>/var/web/dir1/subdir2/private.html</code>,
+<code>/var/web/dir1/subdir3/private.html</code>, and any other instance
+of <code>private.html</code> found under the <code>/var/web/dir1/</code>
+directory.</p>
+
+<example>
+<Directory /var/web/dir1><br />
+<Files private.html><br />
+Order allow,deny<br />
+Deny from all<br />
+</Files><br />
+</Directory>
+</example>
+</section>
+
+<section id="webspace"><title>Webspace Containers</title>
+
+<p>The <directive type="section" module="core">Location</directive>
+directive and its <glossary ref="regex">regex</glossary> counterpart, on
+the other hand, change the
+configuration for content in the webspace. For example, the following
+configuration prevents access to any URL-path that begins in /private.
+In particular, it will apply to requests for
+<code>http://yoursite.example.com/private</code>,
+<code>http://yoursite.example.com/private123</code>, and
+<code>http://yoursite.example.com/private/dir/file.html</code> as well
+as any other requests starting with the <code>/private</code> string.</p>
+
+<example>
+<LocationMatch ^/private><br />
+Order Allow,Deny<br />
+Deny from all<br />
+</Location>
+</example>
+
+<p>The <directive type="section" module="core">Location</directive>
+directive need not have anything to do with the filesystem.
+For example, the following example shows how to map a particular
+URL to an internal Apache HTTP Server handler provided by
<module>mod_status</module>.
+No file called <code>server-status</code> needs to exist in the
+filesystem.</p>
+
+<example>
+<Location /server-status><br />
+SetHandler server-status<br />
+</Location>
+</example>
+</section>
+
+<section id="overlapping-webspace"><title>Overlapping Webspace</title>
+<p>In order to have two overlapping URLs one has to consider the order in
which
+certain sections or directives are evaluated. For
+<directive type="section" module="core">Location</directive> this would
be:</p>
+<example>
+<Location /foo><br />
+</Location><br />
+<Location /foo/bar><br />
+</Location>
+</example>
+<p><directive type="section" module="core">Alias</directive>es on the
other hand,
+are mapped vice-versa:</p>
+<example>
+Alias /foo/bar /srv/www/uncommon/bar<br />
+Alias /foo /srv/www/common/foo<br />
+</example>
+<p>The same is true for the <directive
module="mod_proxy">ProxyPass</directive>
+directives:</p>
+<example>
+ProxyPass /special-area http://special.example.com smax=5 max=10<br />
+ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid
nofailover=On
+</example>
+</section>
+
+<section id="wildcards"><title>Wildcards and Regular Expressions</title>
+
+<p>The <directive type="section" module="core">Directory</directive>,
+<directive type="section" module="core">Files</directive>, and
+<directive type="section" module="core">Location</directive>
+directives can each use shell-style wildcard characters as in
+<code>fnmatch</code> from the C standard library. The character "*"
+matches any sequence of characters, "?" matches any single character,
+and "[<em>seq</em>]" matches any character in <em>seq</em>. The "/"
+character will not be matched by any wildcard; it must be specified
+explicitly.</p>
+
+<p>If even more flexible matching is required, each
+container has a regular expression (regex) counterpart <directive
+type="section" module="core">DirectoryMatch</directive>, <directive
+type="section" module="core">FilesMatch</directive>, and <directive
+type="section" module="core">LocationMatch</directive> that allow
+perl-compatible
+<glossary ref="regex">regular expressions</glossary>
+to be used in choosing the matches. But see the section below on
+configuration merging to find out how using regex sections will change
+how directives are applied.</p>
+
+<p>A non-regex wildcard section that changes the configuration of
+all user directories could look as follows:</p>
+
+<example>
+<Directory /home/*/public_html><br />
+Options Indexes<br />
+</Directory>
+</example>
+
+<p>Using regex sections, we can deny access to many types of image files
+at once:</p>
+<example>
+<FilesMatch \.(?i:gif|jpe?g|png)$><br />
+Order allow,deny<br />
+Deny from all<br />
+</FilesMatch>
+</example>
+
+</section>
+
+<section id="expressions"><title>Boolean expressions</title>
+<p>The <directive type="section" module="core">If</directive>
+directive change the configuration depending on a condition which can be
+expressed by a boolean expression. For example, the following configuration
+denies access if the HTTP Referer header does not start with
+"http://www.example.com/".</p>
+<example>
+<If "!(%{HTTP_REFERER} -strmatch 'http://www.example.com/*')"><br />
+Require all denied<br />
+</If>
+</example>
+
+</section>
+
+<section id="whichwhen"><title>What to use When</title>
+
+<p>Choosing between filesystem containers and webspace containers is
+actually quite easy. When applying directives to objects that reside
+in the filesystem always use <directive type="section"
+module="core">Directory</directive> or <directive type="section"
+module="core">Files</directive>. When applying directives to objects
+that do not reside in the filesystem (such as a webpage generated from
+a database), use <directive type="section"
+module="core">Location</directive>.</p>
+
+<p>It is important to never use <directive type="section"
+module="core">Location</directive> when trying to restrict
+access to objects in the filesystem. This is because many
+different webspace locations (URLs) could map to the same filesystem
+location, allowing your restrictions to be circumvented.
+For example, consider the following configuration:</p>
+
+<example>
+<Location /dir/><br />
+Order allow,deny<br />
+Deny from all<br />
+</Location>
+</example>
+
+<p>This works fine if the request is for
+<code>http://yoursite.example.com/dir/</code>. But what if you are on
+a case-insensitive filesystem? Then your restriction could be easily
+circumvented by requesting
+<code>http://yoursite.example.com/DIR/</code>. The <directive
+type="section" module="core">Directory</directive> directive, in
+contrast, will apply to any content served from that location,
+regardless of how it is called. (An exception is filesystem links.
+The same directory can be placed in more than one part of the
+filesystem using symbolic links. The <directive type="section"
+module="core">Directory</directive> directive will follow the symbolic
+link without resetting the pathname. Therefore, for the highest level
+of security, symbolic links should be disabled with the appropriate
+<directive module="core">Options</directive> directive.)</p>
+
+<p>If you are, perhaps, thinking that none of this applies to you
+because you use a case-sensitive filesystem, remember that there are
+many other ways to map multiple webspace locations to the same
+filesystem location. Therefore you should always use the filesystem
+containers when you can. There is, however, one exception to this
+rule. Putting configuration restrictions in a <code><Location
+/></code> section is perfectly safe because this section will apply
+to all requests regardless of the specific URL.</p>
+</section>
+
+<section id="nesting"><title>Nesting of sections</title>
+
+<p>Some section types can be nested inside other section types. One the one
+hand, <directive type="section" module="core">File</directive> can be used
+inside <directive type="section" module="core">Directory</directive>. On
+the other hand, <directive type="section" module="core">If</directive> can
+be used inside <directive type="section"
module="core">Directory</directive>,
+<directive type="section" module="core">Location</directive>, and
<directive
+type="section" module="core">Files</directive> sections. The regex
+counterparts of the named section behave identically.</p>
+
+<p>Nested sections are merged after non-nested sections of the same
type.</p>
+
+</section>
+
+</section>
+
+<section id="virtualhost"><title>Virtual Hosts</title>
+
+<p>The <directive type="section" module="core">VirtualHost</directive>
+container encloses directives that apply to specific hosts.
+This is useful when serving multiple hosts from the same machine
+with a different configuration for each. For more information,
+see the <a href="vhosts/">Virtual Host Documentation</a>.</p>
+</section>
+
+<section id="proxy"><title>Proxy</title>
+
+<p>The <directive type="section" module="mod_proxy">Proxy</directive>
+and <directive type="section" module="mod_proxy">ProxyMatch</directive>
+containers apply enclosed configuration directives only
+to sites accessed through <module>mod_proxy</module>'s proxy server
+that match the specified URL. For example, the following configuration
+will prevent the proxy server from being used to access the
+<code>www.example.com</code> website.</p>
+
+<example>
+<Proxy http://www.example.com/*><br />
+Order allow,deny<br />
+Deny from all<br />
+</Proxy>
+</example>
+</section>
+
+<section id="whatwhere"><title>What Directives are Allowed?</title>
+
+<p>To find out what directives are allowed in what types of
+configuration sections, check the <a
+href="mod/directive-dict.html#Context">Context</a> of the directive.
+Everything that is allowed in
+<directive type="section" module="core">Directory</directive>
+sections is also syntactically allowed in
+<directive type="section" module="core">DirectoryMatch</directive>,
+<directive type="section" module="core">Files</directive>,
+<directive type="section" module="core">FilesMatch</directive>,
+<directive type="section" module="core">Location</directive>,
+<directive type="section" module="core">LocationMatch</directive>,
+<directive type="section" module="mod_proxy">Proxy</directive>,
+and <directive type="section" module="mod_proxy">ProxyMatch</directive>
+sections. There are some exceptions, however:</p>
+
+<ul>
+<li>The <directive module="core">AllowOverride</directive> directive
+works only in <directive type="section" module="core">Directory</directive>
+sections.</li>
+
+<li>The <code>FollowSymLinks</code> and
+<code>SymLinksIfOwnerMatch</code> <directive
+module="core">Options</directive> work only in <directive
+type="section" module="core">Directory</directive> sections or
+<code>.htaccess</code> files.</li>
+
+<li>The <directive module="core">Options</directive> directive cannot
+be used in <directive type="section" module="core">Files</directive>
+and <directive type="section" module="core">FilesMatch</directive>
+sections.</li>
+</ul>
+</section>
+
+<section id="mergin"><title>How the sections are merged</title>
+
+<p>The configuration sections are applied in a very particular order.
+Since this can have important effects on how configuration directives
+are interpreted, it is important to understand how this works.</p>
+
+ <p>The order of merging is:</p>
+
+ <ol>
+ <li> <directive type="section"
+ module="core">Directory</directive> (except regular expressions)
+ and <code>.htaccess</code> done simultaneously (with
+ <code>.htaccess</code>, if allowed, overriding
+ <directive type="section" module="core">Directory</directive>)</li>
+
+ <li><directive type="section"
module="core">DirectoryMatch</directive>
+ (and <code><Directory ~></code>)</li>
+
+ <li><directive type="section"
+ module="core">Files</directive> and <directive
+ type="section" module="core">FilesMatch</directive> done
+ simultaneously</li>
+
+ <li><directive type="section" module="core">Location</directive>
+ and <directive type="section"
+ module="core">LocationMatch</directive> done simultaneously</li>
+
+ <li><directive type="section" module="core">If</directive>
+ </li>
+
+ </ol>
+
+ <p>Apart from <directive type="section"
+ module="core">Directory</directive>, each group is processed in
+ the order that they appear in the configuration files. <directive
+ type="section" module="core">Directory</directive> (group 1 above)
+ is processed in the order shortest directory component to longest.
+ So for example, <code><Directory /var/web/dir></code> will
+ be processed before <code><Directory
+ /var/web/dir/subdir></code>. If multiple <directive
+ type="section" module="core">Directory</directive> sections apply
+ to the same directory they are processed in the configuration file
+ order. Configurations included via the <directive
+ module="core">Include</directive> directive will be treated as if
+ they were inside the including file at the location of the
+ <directive module="core">Include</directive> directive.</p>
+
+ <p>Sections inside <directive type="section"
+ module="core">VirtualHost</directive> sections
+ are applied <em>after</em> the corresponding sections outside
+ the virtual host definition. This allows virtual hosts to
+ override the main server configuration.</p>
+
+ <p>When the request is served by <module>mod_proxy</module>, the
+ <directive module="mod_proxy" type="section">Proxy</directive>
+ container takes the place of the <directive module="core"
+ type="section">Directory</directive> container in the processing
+ order.</p>
+
+ <p>Later sections override earlier ones.</p>
+
+<note><title>Technical Note</title>
+ There is actually a
+ <code><Location></code>/<code><LocationMatch></code>
+ sequence performed just before the name translation phase
+ (where <code>Aliases</code> and <code>DocumentRoots</code>
+ are used to map URLs to filenames). The results of this
+ sequence are completely thrown away after the translation has
+ completed.
+</note>
+
+<section id="merge-examples"><title>Some Examples</title>
+
+<p>Below is an artificial example to show the order of
+merging. Assuming they all apply to the request, the directives in
+this example will be applied in the order A > B > C > D >
+E.</p>
+
+<example>
+<Location /><br />
+E<br />
+</Location><br />
+<br />
+<Files f.html><br />
+D<br />
+</Files><br />
+<br />
+<VirtualHost *><br />
+<Directory /a/b><br />
+B<br />
+</Directory><br />
+</VirtualHost><br />
+<br />
+<DirectoryMatch "^.*b$"><br />
+C<br />
+</DirectoryMatch><br />
+<br />
+<Directory /a/b><br />
+A<br />
+</Directory><br />
+<br />
+</example>
+
+<p>For a more concrete example, consider the following. Regardless of
+any access restrictions placed in <directive module="core"
+type="section">Directory</directive> sections, the <directive
+module="core" type="section">Location</directive> section will be
+evaluated last and will allow unrestricted access to the server. In
+other words, order of merging is important, so be careful!</p>
+
+<example>
+<Location /><br />
+Order deny,allow<br />
+Allow from all<br />
+</Location><br />
+<br />
+# Woops! This <Directory> section will have no effect<br />
+<Directory /><br />
+Order allow,deny<br />
+Allow from all<br />
+Deny from badguy.example.com<br />
+</Directory>
+</example>
+
+</section>
+
+</section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/server-wide.xml Sun Feb 27
00:09:47 2011
@@ -0,0 +1,136 @@
+<?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="server-wide.xml.meta">
+
+ <title>Server-Wide Configuration</title>
+
+<summary>
+<p>This document explains some of the directives provided by
+the <module>core</module> server which are used to configure
+the basic operations of the server.</p>
+</summary>
+
+ <section id="identification">
+ <title>Server Identification</title>
+
+ <related>
+ <directivelist>
+ <directive module="core">ServerName</directive>
+ <directive module="core">ServerAdmin</directive>
+ <directive module="core">ServerSignature</directive>
+ <directive module="core">ServerTokens</directive>
+ <directive module="core">UseCanonicalName</directive>
+ <directive module="core">UseCanonicalPhysicalPort</directive>
+ </directivelist>
+ </related>
+
+ <p>The <directive module="core">ServerAdmin</directive> and
+ <directive module="core">ServerTokens</directive> directives
+ control what information about the server will be presented
+ in server-generated documents such as error messages. The
+ <directive module="core">ServerTokens</directive> directive
+ sets the value of the Server HTTP response header field.</p>
+
+ <p>The <directive module="core">ServerName</directive>,
+ <directive module="core">UseCanonicalName</directive> and
+ <directive module="core">UseCanonicalPhysicalPort</directive>
+ directives are used by the server to determine how to construct
+ self-referential URLs. For example, when a client requests a
+ directory, but does not include the trailing slash in the
+ directory name, httpd must redirect the client to the full
+ name including the trailing slash so that the client will
+ correctly resolve relative references in the document.</p>
+ </section>
+
+ <section id="locations">
+ <title>File Locations</title>
+
+ <related>
+ <directivelist>
+ <directive module="mpm_common">CoreDumpDirectory</directive>
+ <directive module="core">DocumentRoot</directive>
+ <directive module="core">ErrorLog</directive>
+ <directive module="core">Mutex</directive>
+ <directive module="mpm_common">PidFile</directive>
+ <directive module="mpm_common">ScoreBoardFile</directive>
+ <directive module="core">ServerRoot</directive>
+ </directivelist>
+ </related>
+
+ <p>These directives control the locations of the various files
+ that httpd needs for proper operation. When the pathname used
+ does not begin with a slash (/), the files are located relative
+ to the <directive module="core">ServerRoot</directive>. Be careful
+ about locating files in paths which are writable by non-root users.
+ See the <a href="misc/security_tips.html#serverroot">security tips</a>
+ documentation for more details.</p>
+ </section>
+
+ <section id="resource">
+ <title>Limiting Resource Usage</title>
+
+ <related>
+ <directivelist>
+ <directive module="core">LimitRequestBody</directive>
+ <directive module="core">LimitRequestFields</directive>
+ <directive module="core">LimitRequestFieldsize</directive>
+ <directive module="core">LimitRequestLine</directive>
+ <directive module="core">RLimitCPU</directive>
+ <directive module="core">RLimitMEM</directive>
+ <directive module="core">RLimitNPROC</directive>
+ <directive module="mpm_common">ThreadStackSize</directive>
+ </directivelist>
+ </related>
+
+ <p>The <directive>LimitRequest</directive>*
+ directives are used to place limits on the amount of resources
+ httpd will use in reading requests from clients. By limiting
+ these values, some kinds of denial of service attacks can be
+ mitigated.</p>
+
+ <p>The <directive>RLimit</directive>* directives
+ are used to limit the amount of resources which can be used by
+ processes forked off from the httpd children. In particular,
+ this will control resources used by CGI scripts and SSI exec
+ commands.</p>
+
+ <p>The <directive module="mpm_common">ThreadStackSize</directive>
+ directive is used with some platforms to control the stack size.</p>
+ </section>
+
+ <section id="implementation">
+ <title>Implementation Choices</title>
+
+ <related>
+ <directivelist>
+ <directive module="core">Mutex</directive>
+ </directivelist>
+ </related>
+
+ <p>The <directive>Mutex</directive> directive can be used to change
+ the underlying implementation used for mutexes, in order to relieve
+ functional or performance problems with <glossary>APR</glossary>'s
+ default choice.</p>
+ </section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/sitemap.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE sitemap SYSTEM "./style/sitemap.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+
+
+
+
+<sitemap metafile="sitemap.xml.meta">
+
+ <title>Sitemap</title>
+
+<summary>
+<p>This page lists the currently available documents of the
+<a href="./">Apache HTTP Server Version &httpd.major;.&httpd.minor;
+Documentation</a>.</p>
+</summary>
+
+<category id="release">
+<title>Release Notes</title>
+<page href="upgrading.html">Upgrading to 2.4 from 2.2</page>
+<page href="new_features_2_4.html">New features with Apache 2.3/2.4</page>
+<page href="new_features_2_2.html">New features with Apache 2.1/2.2</page>
+<page href="new_features_2_0.html">New features with Apache 2.0</page>
+<page href="license.html">Apache License</page>
+</category>
+
+<category id="using">
+<title>Using the Apache HTTP Server</title>
+<page href="install.html">Compiling and Installing Apache</page>
+<page href="invoking.html">Starting Apache</page>
+<page href="stopping.html">Stopping and Restarting the Server</page>
+<page href="configuring.html">Configuration Files</page>
+<page href="sections.html">How Directory, Location and Files sections
work</page>
+<page href="caching.html">Content Caching</page>
+<page href="server-wide.html">Server-Wide Configuration</page>
+<page href="logs.html">Log Files</page>
+<page href="urlmapping.html">Mapping URLs to Filesystem Locations</page>
+<page href="misc/security_tips.html">Security Tips</page>
+<page href="dso.html">Dynamic Shared Object (DSO) support</page>
+<page href="content-negotiation.html">Content Negotiation</page>
+<page href="custom-error.html">Custom error responses</page>
+<page href="bind.html">Setting which addresses and ports Apache uses</page>
+<page href="mpm.html">Multi-Processing Modules (MPMs)</page>
+<page href="env.html">Environment Variables in Apache</page>
+<page href="handler.html">Apache's Handler Use</page>
+<page href="filter.html">Filters</page>
+<page href="suexec.html">suEXEC Support</page>
+<page href="misc/perf-tuning.html">Performance Hints</page>
+<page href="http://wiki.apache.org/httpd/FAQ">Frequently Asked
Questions</page>
+</category>
+
+<category id="vhosts">
+<title>Apache Virtual Host documentation</title>
+<page separate="yes" href="vhosts/">Overview</page>
+<page href="vhosts/name-based.html">Name-based Virtual Hosts</page>
+<page href="vhosts/ip-based.html">IP-based Virtual Host Support</page>
+<page href="vhosts/mass.html">Dynamically configured mass virtual
hosting</page>
+<page href="vhosts/examples.html">VirtualHost Examples</page>
+<page href="vhosts/details.html">An In-Depth Discussion of Virtual Host
Matching</page>
+<page href="vhosts/fd-limits.html">File descriptor limitations</page>
+<page href="dns-caveats.html">Issues Regarding DNS and Apache</page>
+</category>
+
+<category id="rewrite">
+<title>URL Rewriting Guide</title>
+<page separate="yes" href="rewrite/">Overview</page>
+<page href="mod/mod_rewrite.html">mod_rewrite reference
+documentation</page>
+<page href="rewrite/intro.html">Introduction</page>
+<page href="rewrite/flags.html">Flags</page>
+<page href="rewrite/tech.html">Technical details</page>
+<page href="rewrite/remapping.html">Remapping URLs</page>
+<page href="rewrite/access.html">Access control</page>
+<page href="rewrite/advanced.html">Advanced techniques</page>
+</category>
+
+<category id="ssl">
+<title>Apache SSL/TLS Encryption</title>
+<page separate="yes" href="ssl/">Overview</page>
+<page href="ssl/ssl_intro.html">SSL/TLS Encryption: An Introduction</page>
+<page href="ssl/ssl_compat.html">SSL/TLS Encryption: Compatibility</page>
+<page href="ssl/ssl_howto.html">SSL/TLS Encryption: How-To</page>
+<page href="ssl/ssl_faq.html">SSL/TLS Encryption: FAQ</page>
+</category>
+
+<category id="howto">
+<title>Guides, Tutorials, and HowTos</title>
+<page separate="yes" href="howto/">Overview</page>
+<page href="howto/auth.html">Authentication</page>
+<page href="howto/cgi.html">Dynamic Content with CGI</page>
+<page href="howto/ssi.html">Introduction to Server Side Includes</page>
+<page href="howto/htaccess.html">.htaccess files</page>
+<page href="howto/public_html.html">Per-user web directories</page>
+</category>
+
+<category id="platform">
+<title>Platform-specific Notes</title>
+<page separate="yes" href="platform/">Overview</page>
+<page href="platform/windows.html">Using Apache with Microsoft
+Windows</page>
+<page href="platform/win_compiling.html">Compiling Apache for
+Microsoft Windows</page>
+<page href="platform/netware.html">Using Apache with Novell NetWare</page>
+<page href="platform/perf-hp.html">Running a High-Performance Web
+Server on HPUX</page>
+<page href="platform/ebcdic.html">The Apache EBCDIC Port</page>
+</category>
+
+<category id="programs">
+<title>Apache HTTP Server and Supporting Programs</title>
+<page separate="yes" href="programs/">Overview</page>
+<page href="programs/httpd.html">Manual Page: httpd</page>
+<page href="programs/ab.html">Manual Page: ab</page>
+<page href="programs/apachectl.html">Manual Page: apachectl</page>
+<page href="programs/apxs.html">Manual Page: apxs</page>
+<page href="programs/configure.html">Manual Page: configure</page>
+<page href="programs/dbmmanage.html">Manual Page: dbmmanage</page>
+<page href="programs/htcacheclean.html">Manual Page: htcacheclean</page>
+<page href="programs/htdbm.html">Manual Page: htdbm</page>
+<page href="programs/htdigest.html">Manual Page: htdigest</page>
+<page href="programs/htpasswd.html">Manual Page: htpasswd</page>
+<page href="programs/logresolve.html">Manual Page: logresolve</page>
+<page href="programs/rotatelogs.html">Manual Page: rotatelogs</page>
+<page href="programs/suexec.html">Manual Page: suexec</page>
+<page href="programs/other.html">Other Programs</page>
+</category>
+
+<category id="misc">
+<title>Apache Miscellaneous Documentation</title>
+<page separate="yes" href="misc/">Overview</page>
+<page href="misc/relevant_standards.html">Relevant Standards</page>
+</category>
+
+<category id="modules">
+<title>Apache modules</title>
+<page href="mod/module-dict.html">Definitions of terms used to describe
Apache modules</page>
+<page href="mod/directive-dict.html">Definitions of terms used to describe
Apache directives</page>
+</category>
+
+<category id="developer">
+<title>Developer Documentation</title>
+<page separate="yes" href="developer/">Overview</page>
+<page href="developer/API.html">Apache API notes</page>
+<page href="developer/new_api_2_4.html">API updates in Apache HTTPD
2.4</page>
+<page href="developer/debugging.html">Debugging Memory Allocation in
APR</page>
+<page href="developer/documenting.html">Documenting Apache 2.x</page>
+<page href="developer/hooks.html">Apache 2.x Hook Functions</page>
+<page href="developer/modules.html">Converting Modules from Apache 1.3 to
Apache 2.x</page>
+<page href="developer/request.html">Request Processing in Apache 2.x</page>
+<page href="developer/filters.html">How Filters Work in Apache 2.x</page>
+</category>
+
+<category id="index">
+<title>Glossary and Index</title>
+<page href="glossary.html">Glossary</page>
+<page href="mod/">Module index</page>
+<page href="mod/directives.html">Directive index</page>
+<page href="mod/quickreference.html">Directive Quick-Reference</page>
+</category>
+
+</sitemap>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/sitemap.xml.zh-cn Sun Feb 27
00:09:47 2011
@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE sitemap SYSTEM "./style/sitemap.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.zh-cn.xsl"?>
+
+
+
+
+<sitemap metafile="sitemap.xml.meta">
+
+ <title>站点导航</title>
+
+<summary>
+<p>本页列出了
+<a href="./">Apache HTTP 服务器 &httpd.major;.&httpd.minor;
+的全部文档</a>。</p>
+</summary>
+
+<category id="release">
+<title>发行说明</title>
+<page href="upgrading.html">从 2.2 升级到 2.4</page>
+<page href="new_features_2_4.html">Apache 2.3/2.4 的新特性</page>
+<page href="new_features_2_2.html">Apache 2.1/2.2 的新特性</page>
+<page href="new_features_2_0.html">Apache 2.0 的新特性</page>
+<page href="license.html">Apache 许可证</page>
+</category>
+
+<category id="using">
+<title>使用 Apache HTTP 服务器</title>
+<page href="install.html">编译与安装 Apache</page>
+<page href="invoking.html">启动 Apache</page>
+<page href="stopping.html">停止与重启 Apache</page>
+<page href="configuring.html">配置文件</page>
+<page href="sections.html">配置片段</page>
+<page href="caching.html">缓存指南</page>
+<page href="server-wide.html">服务器全局配置</page>
+<page href="logs.html">日志文件</page>
+<page href="urlmapping.html">从 URL 映射到文件系统</page>
+<page href="misc/security_tips.html">安全技巧</page>
+<page href="dso.html">动态共享对象(DSO)</page>
+<page href="content-negotiation.html">内容协商</page>
+<page href="custom-error.html">定制错误响应</page>
+<page href="bind.html">绑定指定地址与端口</page>
+<page href="mpm.html">多处理模块(MPM)</page>
+<page href="env.html">环境变量</page>
+<page href="handler.html">Apache 的处理器</page>
+<page href="filter.html">过滤器</page>
+<page href="suexec.html">执行 CGI 前的用户切换(suEXEC)</page>
+<page href="misc/perf-tuning.html">性能调谐</page>
+<page href="http://wiki.apache.org/httpd/FAQ">常见问题</page>
+</category>
+
+<category id="vhosts">
+<title>Apache 虚拟主机文档</title>
+<page separate="yes" href="vhosts/">概述</page>
+<page href="vhosts/name-based.html">基于名称的虚拟主机</page>
+<page href="vhosts/ip-based.html">基于 IP 的虚拟主机</page>
+<page href="vhosts/mass.html">动态配置的大规模虚拟主机</page>
+<page href="vhosts/examples.html">虚拟主机样例</page>
+<page href="vhosts/details.html">虚拟主机匹配的深入讨论</page>
+<page href="vhosts/fd-limits.html">文件句柄限制</page>
+<page href="dns-caveats.html">Apache 的 DNS 相关问题</page>
+</category>
+
+<category id="rewrite">
+<title>URL 改写指南</title>
+<page separate="yes" href="rewrite/">概述</page>
+<page href="mod/mod_rewrite.html">mod_rewrite 参考文档</page>
+<page href="rewrite/intro.html">简介</page>
+<page href="rewrite/flags.html">标志</page>
+<page href="rewrite/tech.html">技术细节</page>
+<page href="rewrite/remapping.html">重新映射 URL</page>
+<page href="rewrite/access.html">访问控制</page>
+<page href="rewrite/advanced.html">高级技术</page>
+</category>
+
+<category id="ssl">
+<title>Apache SSL/TLS 加密</title>
+<page separate="yes" href="ssl/">概述</page>
+<page href="ssl/ssl_intro.html">SSL/TLS 加密: 简介</page>
+<page href="ssl/ssl_compat.html">SSL/TLS 加密: 兼容性</page>
+<page href="ssl/ssl_howto.html">SSL/TLS 加密: 常见操作</page>
+<page href="ssl/ssl_faq.html">SSL/TLS 加密: 常见问题</page>
+</category>
+
+<category id="howto">
+<title>指南与教程</title>
+<page separate="yes" href="howto/">概述</page>
+<page href="howto/auth.html">认证，授权与访问控制</page>
+<page href="howto/cgi.html">CGI 与动态内容</page>
+<page href="howto/ssi.html">服务器端插入</page>
+<page href="howto/htaccess.html">.htaccess 文件</page>
+<page href="howto/public_html.html">用户私人网站目录(public_html)</page>
+</category>
+
+<category id="platform">
+<title>平台相关说明</title>
+<page separate="yes" href="platform/">概述</page>
+<page href="platform/windows.html">在 Microsoft Windows 中使用
Apache</page>
+<page href="platform/win_compiling.html">为 Microsoft Windows 编译
Apache</page>
+<page href="platform/netware.html">在 Novell NetWare 中使用 Apache</page>
+<page href="platform/perf-hp.html">在 HPUX 中运行高性能 web 服务器</page>
+<page href="platform/ebcdic.html">Apache 与 EBCDIC 系统</page>
+</category>
+
+<category id="programs">
+<title>Apache HTTP 服务器与支持程序</title>
+<page separate="yes" href="programs/">概述</page>
+<page href="programs/httpd.html">手册: httpd</page>
+<page href="programs/ab.html">手册: ab</page>
+<page href="programs/apachectl.html">手册: apachectl</page>
+<page href="programs/apxs.html">手册: apxs</page>
+<page href="programs/configure.html">手册: configure</page>
+<page href="programs/dbmmanage.html">手册: dbmmanage</page>
+<page href="programs/htcacheclean.html">手册: htcacheclean</page>
+<page href="programs/htdbm.html">手册: htdbm</page>
+<page href="programs/htdigest.html">手册: htdigest</page>
+<page href="programs/htpasswd.html">手册: htpasswd</page>
+<page href="programs/logresolve.html">手册: logresolve</page>
+<page href="programs/rotatelogs.html">手册: rotatelogs</page>
+<page href="programs/suexec.html">手册: suexec</page>
+<page href="programs/other.html">其它程序</page>
+</category>
+
+<category id="misc">
+<title>Apache 杂项文档</title>
+<page separate="yes" href="misc/">概述</page>
+<page href="misc/relevant_standards.html">相关标准</page>
+</category>
+
+<category id="modules">
+<title>Apache 模块</title>
+<page href="mod/module-dict.html">描述模块的术语</page>
+<page href="mod/directive-dict.html">描述指令的术语</page>
+</category>
+
+<category id="developer">
+<title>开发者文档</title>
+<page separate="yes" href="developer/">概述</page>
+<page href="developer/API.html">Apache API 说明</page>
+<page href="developer/debugging.html">在 APR 中调试内存分配</page>
+<page href="developer/documenting.html">Apache 2.x 文档</page>
+<page href="developer/hooks.html">Apache 2.x 钩子函数</page>
+<page href="developer/modules.html">将模块从 Apache 1.3 移植到 Apache
2.x</page>
+<page href="developer/request.html">Apache 2.x 中的请求处理</page>
+<page href="developer/filters.html">Apache 2.x 中的过滤器</page>
+</category>
+
+<category id="index">
+<title>术语与索引</title>
+<page href="glossary.html">术语</page>
+<page href="mod/">模块索引</page>
+<page href="mod/directives.html">指令索引</page>
+<page href="mod/quickreference.html">指令快速参考</page>
+</category>
+
+</sitemap>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/stopping.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,231 @@
+<?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="stopping.xml.meta">
+
+ <title>Stopping and Restarting Apache HTTP Server</title>
+
+<summary>
+ <p>This document covers stopping and restarting Apache HTTP Server on
+ Unix-like systems. Windows NT, 2000 and XP users should see
+ <a href="platform/windows.html#winsvc">Running httpd as a
+ Service</a> and Windows 9x and ME users should see <a
+ href="platform/windows.html#wincons">Running httpd as a
+ Console Application</a> for information on how to control
+ httpd on those platforms.</p>
+</summary>
+
+<seealso><program>httpd</program></seealso>
+<seealso><program>apachectl</program></seealso>
+<seealso><a href="invoking.html">Starting</a></seealso>
+
+<section id="introduction"><title>Introduction</title>
+
+ <p>In order to stop or restart the Apache HTTP Server, you must send a
signal to
+ the running <program>httpd</program> processes. There are two ways to
+ send the signals. First, you can use the unix <code>kill</code>
+ command to directly send signals to the processes. You will
+ notice many <program>httpd</program> executables running on your
system,
+ but you should not send signals to any of them except the parent,
+ whose pid is in the <directive
+ module="mpm_common">PidFile</directive>. That is to say you
+ shouldn't ever need to send signals to any process except the
+ parent. There are four signals that you can send the parent:
+ <code><a href="#term">TERM</a></code>,
+ <code><a href="#graceful">USR1</a></code>,
+ <code><a href="#hup">HUP</a></code>, and
+ <code><a href="#gracefulstop">WINCH</a></code>, which
+ will be described in a moment.</p>
+
+ <p>To send a signal to the parent you should issue a command
+ such as:</p>
+
+<example>kill -TERM `cat /usr/local/apache2/logs/httpd.pid`</example>
+
+ <p>The second method of signaling the <program>httpd</program>
processes
+ is to use the <code>-k</code> command line options: <code>stop</code>,
+ <code>restart</code>, <code>graceful</code> and
<code>graceful-stop</code>,
+ as described below. These are arguments to the <program>
+ httpd</program> binary, but we recommend that
+ you send them using the <program>apachectl</program> control script,
which
+ will pass them through to <program>httpd</program>.</p>
+
+ <p>After you have signaled <program>httpd</program>, you can read about
+ its progress by issuing:</p>
+
+<example>tail -f /usr/local/apache2/logs/error_log</example>
+
+ <p>Modify those examples to match your <directive
+ module="core">ServerRoot</directive> and <directive
+ module="mpm_common">PidFile</directive> settings.</p>
+</section>
+
+<section id="term"><title>Stop Now</title>
+
+<dl><dt>Signal: TERM</dt>
+<dd><code>apachectl -k stop</code></dd>
+</dl>
+
+ <p>Sending the <code>TERM</code> or <code>stop</code> signal to
+ the parent causes it to immediately attempt to kill off all of its
+ children. It may take it several seconds to complete killing off
+ its children. Then the parent itself exits. Any requests in
+ progress are terminated, and no further requests are served.</p>
+</section>
+
+<section id="graceful"><title>Graceful Restart</title>
+
+<dl><dt>Signal: USR1</dt>
+<dd><code>apachectl -k graceful</code></dd>
+</dl>
+
+ <p>The <code>USR1</code> or <code>graceful</code> signal causes
+ the parent process to <em>advise</em> the children to exit after
+ their current request (or to exit immediately if they're not
+ serving anything). The parent re-reads its configuration files and
+ re-opens its log files. As each child dies off the parent replaces
+ it with a child from the new <em>generation</em> of the
+ configuration, which begins serving new requests immediately.</p>
+
+ <p>This code is designed to always respect the process control
+ directive of the MPMs, so the number of processes and threads
+ available to serve clients will be maintained at the appropriate
+ values throughout the restart process. Furthermore, it respects
+ <directive module="mpm_common">StartServers</directive> in the
+ following manner: if after one second at least <directive
+ module="mpm_common">StartServers</directive> new children have not
+ been created, then create enough to pick up the slack. Hence the
+ code tries to maintain both the number of children appropriate for
+ the current load on the server, and respect your wishes with the
+ <directive module="mpm_common">StartServers</directive>
+ parameter.</p>
+
+ <p>Users of <module>mod_status</module>
+ will notice that the server statistics are <strong>not</strong>
+ set to zero when a <code>USR1</code> is sent. The code was
+ written to both minimize the time in which the server is unable
+ to serve new requests (they will be queued up by the operating
+ system, so they're not lost in any event) and to respect your
+ tuning parameters. In order to do this it has to keep the
+ <em>scoreboard</em> used to keep track of all children across
+ generations.</p>
+
+ <p>The status module will also use a <code>G</code> to indicate
+ those children which are still serving requests started before
+ the graceful restart was given.</p>
+
+ <p>At present there is no way for a log rotation script using
+ <code>USR1</code> to know for certain that all children writing
+ the pre-restart log have finished. We suggest that you use a
+ suitable delay after sending the <code>USR1</code> signal
+ before you do anything with the old log. For example if most of
+ your hits take less than 10 minutes to complete for users on
+ low bandwidth links then you could wait 15 minutes before doing
+ anything with the old log.</p>
+
+ <note>
+ <p>When you issue a restart, a syntax check is first run, to
+ ensure that there are no errors in the configuration files.
+ If your configuration file has errors in it, you will get an
+ error message about that syntax error, and the server will refuse to
+ restart. This avoids the situation where the server halts and then
+ cannot restart, leaving you with a non-functioning server.</p>
+
+ <p>This still will not
+ guarantee that the server will restart correctly. To check the
+ semantics of the configuration files as well as the syntax, you
+ can try starting <program>httpd</program> as a non-root user. If there
+ are no errors it will attempt to open its sockets and logs and fail
+ because it's not root (or because the currently running
+ <program>httpd</program> already has those ports bound). If it fails
+ for any other reason then it's probably a config file error and the
error
+ should be fixed before issuing the graceful restart.</p></note>
+</section>
+
+<section id="hup"><title>Restart Now</title>
+
+<dl><dt>Signal: HUP</dt>
+<dd><code>apachectl -k restart</code></dd>
+</dl>
+
+ <p>Sending the <code>HUP</code> or <code>restart</code> signal to
+ the parent causes it to kill off its children like in
+ <code>TERM</code>, but the parent doesn't exit. It re-reads its
+ configuration files, and re-opens any log files. Then it spawns a
+ new set of children and continues serving hits.</p>
+
+ <p>Users of <module>mod_status</module>
+ will notice that the server statistics are set to zero when a
+ <code>HUP</code> is sent.</p>
+
+<note>As with a graceful restart, a syntax check is run before the
+restart is attempted. If your configuration file has errors in it, the
+restart will not be attempted, and you will receive notification of the
+syntax error(s).</note>
+</section>
+
+<section id="gracefulstop"><title>Graceful Stop</title>
+
+<dl><dt>Signal: WINCH</dt>
+<dd><code>apachectl -k graceful-stop</code></dd>
+</dl>
+
+ <p>The <code>WINCH</code> or <code>graceful-stop</code> signal causes
+ the parent process to <em>advise</em> the children to exit after
+ their current request (or to exit immediately if they're not
+ serving anything). The parent will then remove its <directive
+ module="mpm_common">PidFile</directive> and cease listening on
+ all ports. The parent will continue to run, and monitor children
+ which are handling requests. Once all children have finalised
+ and exited or the timeout specified by the <directive
+ module="mpm_common">GracefulShutdownTimeout</directive> has been
+ reached, the parent will also exit. If the timeout is reached,
+ any remaining children will be sent the <code>TERM</code> signal
+ to force them to exit.</p>
+
+ <p>A <code>TERM</code> signal will immediately terminate the
+ parent process and all children when in the "graceful" state. However
+ as the <directive module="mpm_common">PidFile</directive> will
+ have been removed, you will not be able to use
+ <code>apachectl</code> or <code>httpd</code> to send this signal.</p>
+
+ <note><p>The <code>graceful-stop</code> signal allows you to run
multiple
+ identically configured instances of <program>httpd</program> at the
+ same time. This is a powerful feature when performing graceful
+ upgrades of httpd, however it can also cause deadlocks and race
+ conditions with some configurations.</p>
+
+ <p>Care has been taken to ensure that on-disk files such as lock files
+ (<directive module="core">Mutex</directive>) and Unix socket files
+ (<directive module="mod_cgid">ScriptSock</directive>) contain the
server
+ PID, and should coexist without problem. However, if a configuration
+ directive, third-party module or persistent CGI utilises any other
on-disk
+ lock or state files, care should be taken to ensure that multiple
running
+ instances of <program>httpd</program> do not clobber each other's
files.</p>
+
+ <p>You should also be wary of other potential race conditions, such as
+ using <program>rotatelogs</program> style piped logging. Multiple
running
+ instances of <program>rotatelogs</program> attempting to rotate the
same
+ logfiles at the same time may destroy each other's logfiles.</p></note>
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/suexec.xml Sun Feb 27 00:09:47 2011
@@ -0,0 +1,609 @@
+<?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="suexec.xml.meta">
+
+ <title>suEXEC Support</title>
+
+ <summary>
+ <p>The <strong>suEXEC</strong> feature provides users of the Apache
+ HTTP Server the ability
+ to run <strong>CGI</strong> and <strong>SSI</strong> programs
+ under user IDs different from the user ID of the calling
+ web server. Normally, when a CGI or SSI program executes, it
+ runs as the same user who is running the web server.</p>
+
+ <p>Used properly, this feature can reduce
+ considerably the security risks involved with allowing users to
+ develop and run private CGI or SSI programs. However, if suEXEC
+ is improperly configured, it can cause any number of problems
+ and possibly create new holes in your computer's security. If
+ you aren't familiar with managing <em>setuid root</em> programs
+ and the security issues they present, we highly recommend that
+ you not consider using suEXEC.</p>
+ </summary>
+
+<section id="before"><title>Before we begin</title>
+
+ <p>Before jumping head-first into this document,
+ you should be aware that certain assumptions are made about you and
+ the environment in which you will be using suexec.</p>
+
+ <p>First, it is assumed that you are using a UNIX
+ derivative operating system that is capable of
+ <strong>setuid</strong> and <strong>setgid</strong> operations.
+ All command examples are given in this regard. Other platforms,
+ if they are capable of supporting suEXEC, may differ in their
+ configuration.</p>
+
+ <p>Second, it is assumed you are familiar with
+ some basic concepts of your computer's security and its
+ administration. This involves an understanding of
+ <strong>setuid/setgid</strong> operations and the various
+ effects they may have on your system and its level of
+ security.</p>
+
+ <p>Third, it is assumed that you are using an
+ <strong>unmodified</strong> version of suEXEC code. All code
+ for suEXEC has been carefully scrutinized and tested by the
+ developers as well as numerous beta testers. Every precaution
+ has been taken to ensure a simple yet solidly safe base of
+ code. Altering this code can cause unexpected problems and new
+ security risks. It is <strong>highly</strong> recommended you
+ not alter the suEXEC code unless you are well versed in the
+ particulars of security programming and are willing to share
+ your work with the Apache HTTP Server development team for
consideration.</p>
+
+ <p>Fourth, and last, it has been the decision of
+ the Apache HTTP Server development team to <strong>NOT</strong> make
suEXEC part of
+ the default installation of Apache httpd. To this end, suEXEC
+ configuration requires of the administrator careful attention
+ to details. After due consideration has been given to the
+ various settings for suEXEC, the administrator may install
+ suEXEC through normal installation methods. The values for
+ these settings need to be carefully determined and specified by
+ the administrator to properly maintain system security during
+ the use of suEXEC functionality. It is through this detailed
+ process that we hope to limit suEXEC
+ installation only to those who are careful and determined
+ enough to use it.</p>
+
+ <p>Still with us? Yes? Good. Let's move on!</p>
+</section>
+
+<section id="model"><title>suEXEC Security Model</title>
+
+ <p>Before we begin configuring and installing
+ suEXEC, we will first discuss the security model you are about
+ to implement. By doing so, you may better understand what
+ exactly is going on inside suEXEC and what precautions are
+ taken to ensure your system's security.</p>
+
+ <p><strong>suEXEC</strong> is based on a setuid
+ "wrapper" program that is called by the main Apache HTTP Server.
+ This wrapper is called when an HTTP request is made for a CGI
+ or SSI program that the administrator has designated to run as
+ a userid other than that of the main server. When such a
+ request is made, Apache httpd provides the suEXEC wrapper with the
+ program's name and the user and group IDs under which the
+ program is to execute.</p>
+
+ <p>The wrapper then employs the following process
+ to determine success or failure -- if any one of these
+ conditions fail, the program logs the failure and exits with an
+ error, otherwise it will continue:</p>
+
+ <ol>
+ <li>
+ <strong>Is the user executing this wrapper a valid user of
+ this system?</strong>
+
+ <p class="indent">
+ This is to ensure that the user executing the wrapper is
+ truly a user of the system.
+ </p>
+ </li>
+
+ <li>
+ <strong>Was the wrapper called with the proper number of
+ arguments?</strong>
+
+ <p class="indent">
+ The wrapper will only execute if it is given the proper
+ number of arguments. The proper argument format is known
+ to the Apache HTTP Server. If the wrapper is not receiving
+ the proper number of arguments, it is either being
+ hacked, or there is something wrong with the suEXEC
+ portion of your Apache httpd binary.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is this valid user allowed to run the
+ wrapper?</strong>
+
+ <p class="indent">
+ Is this user the user allowed to run this wrapper? Only
+ one user (the Apache user) is allowed to execute this
+ program.
+ </p>
+ </li>
+
+ <li>
+ <strong>Does the target CGI or SSI program have an unsafe
+ hierarchical reference?</strong>
+
+ <p class="indent">
+ Does the target CGI or SSI program's path contain a leading
+ '/' or have a '..' backreference? These are not allowed; the
+ target CGI/SSI program must reside within suEXEC's document
+ root (see <code>--with-suexec-docroot=<em>DIR</em></code>
+ below).
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target user name valid?</strong>
+
+ <p class="indent">
+ Does the target user exist?
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target group name valid?</strong>
+
+ <p class="indent">
+ Does the target group exist?
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target user <em>NOT</em> superuser?</strong>
+
+
+ <p class="indent">
+ suEXEC does not allow <code><em>root</em></code>
+ to execute CGI/SSI programs.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target userid <em>ABOVE</em> the minimum ID
+ number?</strong>
+
+ <p class="indent">
+ The minimum user ID number is specified during
+ configuration. This allows you to set the lowest possible
+ userid that will be allowed to execute CGI/SSI programs.
+ This is useful to block out "system" accounts.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target group <em>NOT</em> the superuser
+ group?</strong>
+
+ <p class="indent">
+ Presently, suEXEC does not allow the <code><em>root</em></code>
+ group to execute CGI/SSI programs.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target groupid <em>ABOVE</em> the minimum ID
+ number?</strong>
+
+ <p class="indent">
+ The minimum group ID number is specified during
+ configuration. This allows you to set the lowest possible
+ groupid that will be allowed to execute CGI/SSI programs.
+ This is useful to block out "system" groups.
+ </p>
+ </li>
+
+ <li>
+ <strong>Can the wrapper successfully become the target user
+ and group?</strong>
+
+ <p class="indent">
+ Here is where the program becomes the target user and
+ group via setuid and setgid calls. The group access list
+ is also initialized with all of the groups of which the
+ user is a member.
+ </p>
+ </li>
+
+ <li>
+ <strong>Can we change directory to the one in which the target
+ CGI/SSI program resides?</strong>
+
+ <p class="indent">
+ If it doesn't exist, it can't very well contain files. If we
+ can't change directory to it, it might aswell not exist.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the directory within the httpd webspace?</strong>
+
+ <p class="indent">
+ If the request is for a regular portion of the server, is
+ the requested directory within suEXEC's document root? If
+ the request is for a <directive module="mod_userdir"
+ >UserDir</directive>, is the requested directory
+ within the directory configured as suEXEC's userdir (see
+ <a href="#install">suEXEC's configuration options</a>)?
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the directory <em>NOT</em> writable by anyone
+ else?</strong>
+
+ <p class="indent">
+ We don't want to open up the directory to others; only
+ the owner user may be able to alter this directories
+ contents.
+ </p>
+ </li>
+
+ <li>
+ <strong>Does the target CGI/SSI program exist?</strong>
+
+ <p class="indent">
+ If it doesn't exists, it can't very well be executed.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target CGI/SSI program <em>NOT</em> writable
+ by anyone else?</strong>
+
+ <p class="indent">
+ We don't want to give anyone other than the owner the
+ ability to change the CGI/SSI program.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target CGI/SSI program <em>NOT</em> setuid or
+ setgid?</strong>
+
+ <p class="indent">
+ We do not want to execute programs that will then change
+ our UID/GID again.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target user/group the same as the program's
+ user/group?</strong>
+
+ <p class="indent">
+ Is the user the owner of the file?
+ </p>
+ </li>
+
+ <li>
+ <strong>Can we successfully clean the process environment
+ to ensure safe operations?</strong>
+
+ <p class="indent">
+ suEXEC cleans the process' environment by establishing a
+ safe execution PATH (defined during configuration), as
+ well as only passing through those variables whose names
+ are listed in the safe environment list (also created
+ during configuration).
+ </p>
+ </li>
+
+ <li>
+ <strong>Can we successfully become the target CGI/SSI program
+ and execute?</strong>
+
+ <p class="indent">
+ Here is where suEXEC ends and the target CGI/SSI program begins.
+ </p>
+ </li>
+ </ol>
+
+ <p>This is the standard operation of the
+ suEXEC wrapper's security model. It is somewhat stringent and
+ can impose new limitations and guidelines for CGI/SSI design,
+ but it was developed carefully step-by-step with security in
+ mind.</p>
+
+ <p>For more information as to how this security
+ model can limit your possibilities in regards to server
+ configuration, as well as what security risks can be avoided
+ with a proper suEXEC setup, see the <a
+ href="#jabberwock">"Beware the Jabberwock"</a> section of this
+ document.</p>
+</section>
+
+<section id="install"><title>Configuring & Installing
+ suEXEC</title>
+
+ <p>Here's where we begin the fun.</p>
+
+ <p><strong>suEXEC configuration
+ options</strong><br />
+ </p>
+
+ <dl>
+ <dt><code>--enable-suexec</code></dt>
+
+ <dd>This option enables the suEXEC feature which is never
+ installed or activated by default. At least one
+ <code>--with-suexec-xxxxx</code> option has to be provided
+ together with the <code>--enable-suexec</code> option to let
+ APACI accept your request for using the suEXEC feature.</dd>
+
+ <dt><code>--with-suexec-bin=<em>PATH</em></code></dt>
+
+ <dd>The path to the <code>suexec</code> binary must be hard-coded
+ in the server for security reasons. Use this option to override
+ the default path. <em>e.g.</em>
+ <code>--with-suexec-bin=/usr/sbin/suexec</code></dd>
+
+ <dt><code>--with-suexec-caller=<em>UID</em></code></dt>
+
+ <dd>The <a href="mod/mpm_common.html#user">username</a> under which
+ httpd normally runs. This is the only user allowed to
+ execute the suEXEC wrapper.</dd>
+
+ <dt><code>--with-suexec-userdir=<em>DIR</em></code></dt>
+
+ <dd>Define to be the subdirectory under users' home
+ directories where suEXEC access should be allowed. All
+ executables under this directory will be executable by suEXEC
+ as the user so they should be "safe" programs. If you are
+ using a "simple" <directive module="mod_userdir">UserDir</directive>
+ directive (ie. one without a "*" in it) this should be set to the
same
+ value. suEXEC will not work properly in cases where the <directive
+ module="mod_userdir">UserDir</directive> directive points to
+ a location that is not the same as the user's home directory
+ as referenced in the <code>passwd</code> file. Default value is
+ "<code>public_html</code>".<br />
+ If you have virtual hosts with a different <directive
+ module="mod_userdir">UserDir</directive> for each,
+ you will need to define them to all reside in one parent
+ directory; then name that parent directory here. <strong>If
+ this is not defined properly, "~userdir" cgi requests will
+ not work!</strong></dd>
+
+ <dt><code>--with-suexec-docroot=<em>DIR</em></code></dt>
+
+ <dd>Define as the DocumentRoot set for httpd. This will be
+ the only hierarchy (aside from <directive module="mod_userdir"
+ >UserDir</directive>s) that can be used for suEXEC behavior. The
+ default directory is the <code>--datadir</code> value with the suffix
+ "<code>/htdocs</code>", <em>e.g.</em> if you configure with
+ "<code>--datadir=/home/apache</code>" the directory
+ "<code>/home/apache/htdocs</code>" is used as document root for the
+ suEXEC wrapper.</dd>
+
+ <dt><code>--with-suexec-uidmin=<em>UID</em></code></dt>
+
+ <dd>Define this as the lowest UID allowed to be a target user
+ for suEXEC. For most systems, 500 or 100 is common. Default
+ value is 100.</dd>
+
+ <dt><code>--with-suexec-gidmin=<em>GID</em></code></dt>
+
+ <dd>Define this as the lowest GID allowed to be a target
+ group for suEXEC. For most systems, 100 is common and
+ therefore used as default value.</dd>
+
+ <dt><code>--with-suexec-logfile=<em>FILE</em></code></dt>
+
+ <dd>This defines the filename to which all suEXEC
+ transactions and errors are logged (useful for auditing and
+ debugging purposes). By default the logfile is named
+ "<code>suexec_log</code>" and located in your standard logfile
+ directory (<code>--logfiledir</code>).</dd>
+
+ <dt><code>--with-suexec-safepath=<em>PATH</em></code></dt>
+
+ <dd>Define a safe PATH environment to pass to CGI
+ executables. Default value is
+ "<code>/usr/local/bin:/usr/bin:/bin</code>".</dd>
+ </dl>
+
+ <section>
+ <title>Compiling and installing the suEXEC wrapper</title>
+
+ <p>If you have enabled the suEXEC feature with the
+ <code>--enable-suexec</code> option the <code>suexec</code> binary
+ (together with httpd itself) is automatically built if you execute
+ the <code>make</code> command.</p>
+
+ <p>After all components have been built you can execute the
+ command <code>make install</code> to install them. The binary image
+ <code>suexec</code> is installed in the directory defined by the
+ <code>--sbindir</code> option. The default location is
+ "/usr/local/apache2/bin/suexec".</p>
+
+ <p>Please note that you need <strong><em>root
+ privileges</em></strong> for the installation step. In order
+ for the wrapper to set the user ID, it must be installed as
+ owner <code><em>root</em></code> and must have the setuserid
+ execution bit set for file modes.</p>
+ </section>
+
+ <section>
+ <title>Setting paranoid permissions</title>
+
+ <p>Although the suEXEC wrapper will check to ensure that its
+ caller is the correct user as specified with the
+ <code>--with-suexec-caller</code> <program>configure</program>
+ option, there is
+ always the possibility that a system or library call suEXEC uses
+ before this check may be exploitable on your system. To counter
+ this, and because it is best-practise in general, you should use
+ filesystem permissions to ensure that only the group httpd
+ runs as may execute suEXEC.</p>
+
+ <p>If for example, your web server is configured to run as:</p>
+
+ <example>
+ User www<br />
+ Group webgroup<br />
+ </example>
+
+ <p>and <program>suexec</program> is installed at
+ "/usr/local/apache2/bin/suexec", you should run:</p>
+
+ <example>
+ chgrp webgroup /usr/local/apache2/bin/suexec<br />
+ chmod 4750 /usr/local/apache2/bin/suexec<br />
+ </example>
+
+ <p>This will ensure that only the group httpd runs as can even
+ execute the suEXEC wrapper.</p>
+ </section>
+</section>
+
+
+<section id="enable"><title>Enabling & Disabling
+ suEXEC</title>
+
+ <p>Upon startup of httpd, it looks for the file
+ <program>suexec</program> in the directory defined by the
+ <code>--sbindir</code> option (default is
+ "/usr/local/apache/sbin/suexec"). If httpd finds a properly
+ configured suEXEC wrapper, it will print the following message
+ to the error log:</p>
+
+<example>
+ [notice] suEXEC mechanism enabled (wrapper: <var>/path/to/suexec</var>)
+</example>
+
+ <p>If you don't see this message at server startup, the server is
+ most likely not finding the wrapper program where it expects
+ it, or the executable is not installed <em>setuid root</em>.</p>
+
+ <p>If you want to enable the suEXEC mechanism for the first time
+ and an Apache HTTP Server is already running you must kill and
+ restart httpd. Restarting it with a simple HUP or USR1 signal
+ will not be enough. </p>
+ <p>If you want to disable suEXEC you should kill and restart
+ httpd after you have removed the <program>suexec</program> file.</p>
+</section>
+
+<section id="usage"><title>Using suEXEC</title>
+
+ <p>Requests for CGI programs will call the suEXEC wrapper only if
+ they are for a virtual host containing a <directive
+ module="mod_suexec">SuexecUserGroup</directive> directive or if
+ they are processed by <module>mod_userdir</module>.</p>
+
+ <p><strong>Virtual Hosts:</strong><br /> One way to use the suEXEC
+ wrapper is through the <directive
+ module="mod_suexec">SuexecUserGroup</directive> directive in
+ <directive module="core">VirtualHost</directive> definitions. By
+ setting this directive to values different from the main server
+ user ID, all requests for CGI resources will be executed as the
+ <em>User</em> and <em>Group</em> defined for that <directive
+ module="core" type="section">VirtualHost</directive>. If this
+ directive is not specified for a <directive module="core"
+ type="section">VirtualHost</directive> then the main server userid
+ is assumed.</p>
+
+ <p><strong>User directories:</strong><br /> Requests that are
+ processed by <module>mod_userdir</module> will call the suEXEC
+ wrapper to execute CGI programs under the userid of the requested
+ user directory. The only requirement needed for this feature to
+ work is for CGI execution to be enabled for the user and that the
+ script must meet the scrutiny of the <a href="#model">security
+ checks</a> above. See also the
+ <code>--with-suexec-userdir</code> <a href="#install">compile
+ time option</a>.</p> </section>
+
+<section id="debug"><title>Debugging suEXEC</title>
+
+ <p>The suEXEC wrapper will write log information
+ to the file defined with the <code>--with-suexec-logfile</code>
+ option as indicated above. If you feel you have configured and
+ installed the wrapper properly, have a look at this log and the
+ error_log for the server to see where you may have gone astray.</p>
+
+</section>
+
+<section id="jabberwock"><title>Beware the Jabberwock:
+ Warnings & Examples</title>
+
+ <p><strong>NOTE!</strong> This section may not be
+ complete. For the latest revision of this section of the
+ documentation, see the <a
+ href="http://httpd.apache.org/docs/&httpd.docs;/suexec.html">Online
+ Documentation</a> version.</p>
+
+ <p>There are a few points of interest regarding
+ the wrapper that can cause limitations on server setup. Please
+ review these before submitting any "bugs" regarding suEXEC.</p>
+
+ <ul>
+ <li><strong>suEXEC Points Of Interest</strong></li>
+
+ <li>
+ Hierarchy limitations
+
+ <p class="indent">
+ For security and efficiency reasons, all suEXEC requests
+ must remain within either a top-level document root for
+ virtual host requests, or one top-level personal document
+ root for userdir requests. For example, if you have four
+ VirtualHosts configured, you would need to structure all
+ of your VHosts' document roots off of one main httpd
+ document hierarchy to take advantage of suEXEC for
+ VirtualHosts. (Example forthcoming.)
+ </p>
+ </li>
+
+ <li>
+ suEXEC's PATH environment variable
+
+ <p class="indent">
+ This can be a dangerous thing to change. Make certain
+ every path you include in this define is a
+ <strong>trusted</strong> directory. You don't want to
+ open people up to having someone from across the world
+ running a trojan horse on them.
+ </p>
+ </li>
+
+ <li>
+ Altering the suEXEC code
+
+ <p class="indent">
+ Again, this can cause <strong>Big Trouble</strong> if you
+ try this without knowing what you are doing. Stay away
+ from it if at all possible.
+ </p>
+ </li>
+ </ul>
+
+</section>
+
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/upgrading.xml Sun Feb 27 00:09:47
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="upgrading.xml.meta">
+
+<title>Upgrading to 2.4 from 2.2</title>
+
+<summary>
+ <p>In order to assist folks upgrading, we maintain a document
+ describing information critical to existing Apache HTTP Server users.
These
+ are intended to be brief notes, and you should be able to find
+ more information in either the <a
+ href="new_features_2_4.html">New Features</a> document, or in
+ the <code>src/CHANGES</code> file. Application and module developers
+ can find a summary of API changes in the <a
href="developer/new_api_2_4.html"
+ >API updates</a> overview.</p>
+
+ <p>This document describes changes in server behavior that might
+ require you to change your configuration or how you use the server
+ in order to continue using 2.4 as you are currently using 2.2.
+ To take advantage of new features in 2.4, see the New Features
+ document.</p>
+
+ <p>This document describes only the changes from 2.2 to 2.4. If you
+ are upgrading from version 2.0, you should also consult the <a
+ href="http://httpd.apache.org/docs/2.2/upgrading.html">2.0 to 2.2
+ upgrading document.</a></p>
+
+</summary>
+<seealso><a href="new_features_2_4.html">Overview of new features in
+ Apache HTTP Server 2.4</a></seealso>
+
+ <section id="compile-time">
+ <title>Compile-Time Configuration Changes</title>
+
+ <p>The compilation process is very similar to the one used in
+ version 2.2. Your old <code>configure</code> command line (as
+ found in <code>build/config.nice</code> in the installed server
+ directory) can be used in most cases. There are some changes in
+ the default settings. Some details of changes:</p>
+
+ <ul>
+ <li>These modules have been removed: mod_authn_default,
+ mod_authz_default, mod_mem_cache. If you were using
+ mod_mem_cache in 2.2, look at <module>mod_cache_disk</module> in
+ 2.4.</li>
+
+ <li>All load balancing implementations have been moved to
+ individual, self-contained mod_proxy submodules, e.g.
+ <module>mod_lbmethod_bybusyness</module>. You might need
+ to build and load any of these that your configuration
+ uses.</li>
+
+ <li>Platform support has been removed for BeOS, TPF, and
+ even older platforms such as A/UX, Next, and Tandem. These were
+ believed to be broken anyway.</li>
+
+ <li>configure: dynamic modules (DSO) are built by default</li>
+
+ <li>configure: the "most" module set gets built by default</li>
+ </ul>
+
+ </section>
+
+ <section id="run-time">
+ <title>Run-Time Configuration Changes</title>
+ <p>There have been significant changes in authorization configuration,
+ and other minor configuration changes, that could require changes to
your 2.2
+ configuration files before using them for 2.4.</p>
+
+ <section id="authz">
+ <title>Authorization</title>
+
+ <p>Any configuration file that uses authorization will likely
+ need changes.</p>
+
+ <p>You should review the <a href="howto/auth.html">Authentication,
+ Authorization and Access Control Howto</a>, especially the section
+ <a href="howto/auth.html#beyond">Beyond just authorization</a>
+ which explains the new mechanisms for controlling the order in
+ which the authorization directives are applied.</p>
+
+ <section id="access">
+ <title>Access control</title>
+
+ <p>In 2.2, access control based on client hostname, IP address,
+ and other characteristics of client requests was done using the
+ directives <directive
+ module="mod_access_compat">Order</directive>, <directive
+ module="mod_access_compat">Allow</directive>, <directive
+ module="mod_access_compat">Deny</directive>, and <directive
+ module="mod_access_compat">Satisfy</directive>.</p>
+
+ <p>In 2.4, such access control is done in the same way as other
+ authorization checks, using the new module
+ <module>mod_authz_host</module>. The old access control idioms
+ should be replaced by the new authentication mechanisms,
+ although for compatibility with old configurations, the new
+ module <module>mod_access_compat</module> is provided.</p>
+
+ <p>Here are some examples of old and new ways to do the same
+ access control.</p>
+
+ <p>In this example, all requests are denied.</p>
+ <example>
+ <title>2.2 configuration:</title>
+ Order deny,allow<br />
+ Deny from all
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ Require all denied
+ </example>
+
+ <p>In this example, all requests are allowed.</p>
+ <example>
+ <title>2.2 configuration:</title>
+ Order allow,deny<br />
+ Allow from all
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ Require all granted
+ </example>
+
+ <p>In the following example, all hosts in the example.org domain
+ are allowed access; all other hosts are denied access.</p>
+
+ <example>
+ <title>2.2 configuration:</title>
+ Order Deny,Allow<br />
+ Deny from all<br />
+ Allow from example.org
+ </example>
+ <example>
+ <title>2.4 configuration:</title>
+ Require host example.org
+ </example>
+ </section>
+
+ </section>
+
+ <section id="config">
+ <title>Other configuration changes</title>
+
+ <p>Some other small adjustments may be necessary for particular
+ configurations as discussed below.</p>
+
+ <ul>
+ <li><directive>MaxRequestsPerChild</directive> has been renamed to
+ <directive module="mpm_common">MaxConnectionsPerChild</directive>,
+ which describes more accurately what it does.</li>
+
+ <li>The <directive module="core">DefaultType</directive>
+ directive no longer has any effect, other than to emit a
+ warning if it's used with any value other than
+ <code>none</code>. You need to use other configuration
+ settings to replace it in 2.4.
+ </li>
+
+ <li><directive module="core">EnableSendfile</directive> now
+ defaults to Off.</li>
+
+ <li><module>mod_log_config</module>: <a
+ href="modules/mod_log_config.html#formats">${cookie}C</a>
+ matches whole cookie names. Previously any substring would
+ match.</li>
+
+ <li><module>mod_dav_fs</module>: The format of the <directive
+ module="dav_fs">DavLockDB</directive> file has changed for
+ systems with inodes. The old <directive
+ module="dav_fs">DavLockDB</directive> file must be deleted on
+ upgrade.
+ </li>
+
+ <li><directive module="core">KeepAlive</directive> only
+ accepts values of <code>On</code> or <code>Off</code>.
+ Previously, any value other than "Off" or "0" was treated as
+ "On".</li>
+
+ <li>Directives AcceptMutex, LockFile, RewriteLock, SSLMutex,
+ SSLStaplingMutex, and WatchdogMutexPath have been replaced
+ with a single <directive module="core">Mutex</directive>
+ directive. You will need to evaluate any use of these removed
+ directives in your 2.2 configuration to determine if they can
+ just be deleted or will need to be replaced using <directive
+ module="core">Mutex</directive>.</li>
+
+ <li><module>mod_cache</module>: <directive
+ module="cache">CacheIgnoreURLSessionIdentifiers</directive>
+ now does an exact match against the query string instead of a
+ partial match. If your configuration was using partial
+ strings, e.g. using <code>sessionid</code> to match
+ <code>/someapplication/image.gif;jsessionid=123456789</code>,
+ then you will need to change to the full string
+ <code>jsessionid</code>.
+ </li>
+
+ <li><module>mod_ldap</module>: <directive
+ module="ldap">LDAPTrustedClientCert</directive> is now
+ consistently a per-directory setting only. If you use this
+ directive, review your configuration to make sure it is
+ present in all the necessary directory contexts.</li>
+
+ <li><module>mod_filter</module>: <directive
+ module="filter">FilterProvider</directive> syntax has changed and
+ now uses a boolean expression to determine if a filter is applied.
+ </li>
+ </ul>
+ </section>
+ </section>
+
+ <section id="misc">
+ <title>Misc Changes</title>
+
+ <ul>
+ <li><module>mod_auto_index</module>: will now extract titles and
+ display descriptions for .xhtml files, which were previously
+ ignored.</li>
+
+ <li><module>mod_ssl</module>: The default format of the
<code>*_DN</code>
+ variables has changed. The old format can still be used with the new
+ <code>LegacyDNStringFormat</code> argument to <directive
+ module="mod_ssl">SSLOptions</directive>.</li>
+
+ <li><program>htpasswd</program> now uses MD5 hash by default on
+ all platforms.</li>
+
+ <li>The <directive module="core">NameVirtualHost</directive>
+ directive no longer has any effect, other than to emit a
+ warning. Any address/port combination appearing in multiple
+ virtual hosts is implicitly treated as a name-based virtual host.
+ </li>
+ </ul>
+
+
+ </section>
+
+ <section id="third-party">
+ <title>Third Party Modules</title>
+ <p>All modules must be recompiled for 2.4 before being loaded.</p>
+
+ <p>Many third-party modules designed for version 2.2 will
+ otherwise work unchanged with the Apache HTTP Server version 2.4.
+ Some will require changes; see the <a
href="developer/new_api_2_4.html">API
+ update</a> overview.</p>
+ </section>
+
+ <section id="commonproblems">
+ <title>Common problems when upgrading</title>
+ <ul><li>Startup errors:
+ <ul>
+ <li><code>Invalid command 'User', perhaps misspelled or defined by a
module not included in the server configuration</code> - load module
<module>mod_unixd</module></li>
+ <li><code>Invalid command 'Require', perhaps misspelled or defined
by a module not included in the server configuration</code>, or
+<code>Invalid command 'Order', perhaps misspelled or defined by a module
not included in the server configuration</code>
+ - load module <module>mod_access_compat</module>, or update configuration
to 2.4 authorization directives.</li>
+ <li><code>Ignoring deprecated use of DefaultType in line NN of
/path/to/httpd.conf</code> - remove <directive
module="core">DefaultType</directive>
+ and replace with other configuration settings.</li>
+ </ul></li>
+ <li>Errors serving requests:
+ <ul>
+ <li><code>configuration error: couldn't check user: /path</code> -
+ load module <module>mod_authn_core</module>.</li>
+ </ul>
+ </li>
+</ul>
+ </section>
+</manualpage>
=======================================
--- /dev/null
+++ /trunk/l10n/apache/trunk/docs/manual/urlmapping.xml Sun Feb 27 00:09:47
2011
@@ -0,0 +1,357 @@
+<?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="urlmapping.xml.meta">
+
+ <title>Mapping URLs to Filesystem Locations</title>
+
+ <summary>
+ <p>This document explains how the Apache HTTP Server uses the URL of a
request
+ to determine the filesystem location from which to serve a
+ file.</p>
+ </summary>
+
+<section id="related"><title>Related Modules and Directives</title>
+
+<related>
+<modulelist>
+<module>mod_actions</module>
+<module>mod_alias</module>
+<module>mod_dir</module>
+<module>mod_imagemap</module>
+<module>mod_negotiation</module>
+<module>mod_proxy</module>
+<module>mod_rewrite</module>
+<module>mod_speling</module>
+<module>mod_userdir</module>
+<module>mod_vhost_alias</module>
+</modulelist>
+<directivelist>
+<directive module="mod_alias">Alias</directive>
+<directive module="mod_alias">AliasMatch</directive>
+<directive module="mod_speling">CheckSpelling</directive>
+<directive module="core">DocumentRoot</directive>
+<directive module="core">ErrorDocument</directive>
+<directive module="core">Options</directive>
+<directive module="mod_proxy">ProxyPass</directive>
+<directive module="mod_proxy">ProxyPassReverse</directive>
+<directive module="mod_proxy">ProxyPassReverseCookieDomain</directive>
+<directive module="mod_proxy">ProxyPassReverseCookiePath</directive>
+<directive module="mod_alias">Redirect</directive>
+<directive module="mod_alias">RedirectMatch</directive>
+<directive module="mod_rewrite">RewriteCond</directive>
+<directive module="mod_rewrite">RewriteRule</directive>
+<directive module="mod_alias">ScriptAlias</directive>
+<directive module="mod_alias">ScriptAliasMatch</directive>
+<directive module="mod_userdir">UserDir</directive>
+</directivelist>
+</related>
+</section>
+
+<section id="documentroot"><title>DocumentRoot</title>
+
+ <p>In deciding what file to serve for a given request, httpd's
+ default behavior is to take the URL-Path for the request (the part
+ of the URL following the hostname and port) and add it to the end
+ of the <directive module="core">DocumentRoot</directive> specified
+ in your configuration files. Therefore, the files and directories
+ underneath the <directive module="core">DocumentRoot</directive>
+ make up the basic document tree which will be visible from the
+ web.</p>
+
+ <p>For example, if <directive module="core">DocumentRoot</directive>
+ were set to <code>/var/www/html</code> then a request for
+ <code>http://www.example.com/fish/guppies.html</code> would result
+ in the file <code>/var/www/html/fish/guppies.html</code> being
+ served to the requesting client.</p>
+
+ <p>httpd is also capable of <a href="vhosts/">Virtual
+ Hosting</a>, where the server receives requests for more than one
+ host. In this case, a different <directive
+ module="core">DocumentRoot</directive> can be specified for each
+ virtual host, or alternatively, the directives provided by the
+ module <module>mod_vhost_alias</module> can
+ be used to dynamically determine the appropriate place from which
+ to serve content based on the requested IP address or
+ hostname.</p>
+
+ <p>The <directive module="core">DocumentRoot</directive> directive
+ is set in your main server configuration file
+ (<code>httpd.conf</code>) and, possibly, once per additional <a
+ href="vhosts/">Virtual Host</a> you create.</p>
+</section>
+
+<section id="outside"><title>Files Outside the DocumentRoot</title>
+
+ <p>There are frequently circumstances where it is necessary to
+ allow web access to parts of the filesystem that are not strictly
+ underneath the <directive
+ module="core">DocumentRoot</directive>. httpd offers several
+ different ways to accomplish this. On Unix systems, symbolic links
+ can bring other parts of the filesystem under the <directive
+ module="core">DocumentRoot</directive>. For security reasons,
+ httpd will follow symbolic links only if the <directive
+ module="core">Options</directive> setting for the relevant
+ directory includes <code>FollowSymLinks</code> or
+ <code>SymLinksIfOwnerMatch</code>.</p>
+
+ <p>Alternatively, the <directive
+ module="mod_alias">Alias</directive> directive will map any part
+ of the filesystem into the web space. For example, with</p>
+
+<example>Alias /docs /var/web</example>
+
+ <p>the URL <code>http://www.example.com/docs/dir/file.html</code>
+ will be served from <code>/var/web/dir/file.html</code>. The
+ <directive module="mod_alias">ScriptAlias</directive> directive
+ works the same way, with the additional effect that all content
+ located at the target path is treated as <glossary ref="cgi"
+ >CGI</glossary> scripts.</p>
+
+ <p>For situations where you require additional flexibility, you
+ can use the <directive module="mod_alias">AliasMatch</directive>
+ and <directive module="mod_alias">ScriptAliasMatch</directive>
+ directives to do powerful <glossary ref="regex">regular
+ expression</glossary> based matching and substitution. For
+ example,</p>
+
+<example>ScriptAliasMatch ^/~([a-zA-Z0-9]+)/cgi-bin/(.+)
+ /home/$1/cgi-bin/$2</example>
+
+ <p>will map a request to
+ <code>http://example.com/~user/cgi-bin/script.cgi</code> to the
+ path <code>/home/user/cgi-bin/script.cgi</code> and will treat
+ the resulting file as a CGI script.</p>
+</section>
+
+<section id="user"><title>User Directories</title>
+
+ <p>Traditionally on Unix systems, the home directory of a
+ particular <em>user</em> can be referred to as
+ <code>~user/</code>. The module <module>mod_userdir</module>
+ extends this idea to the web by allowing files under each user's
+ home directory to be accessed using URLs such as the
+ following.</p>
+
+<example>http://www.example.com/~user/file.html</example>
+
+ <p>For security reasons, it is inappropriate to give direct
+ access to a user's home directory from the web. Therefore, the
+ <directive module="mod_userdir">UserDir</directive> directive
+ specifies a directory underneath the user's home directory
+ where web files are located. Using the default setting of
+ <code>Userdir public_html</code>, the above URL maps to a file
+ at a directory like
+ <code>/home/user/public_html/file.html</code> where
+ <code>/home/user/</code> is the user's home directory as
+ specified in <code>/etc/passwd</code>.</p>
+
+ <p>There are also several other forms of the
+ <code>Userdir</code> directive which you can use on systems
+ where <code>/etc/passwd</code> does not contain the location of
+ the home directory.</p>
+
+ <p>Some people find the "~" symbol (which is often encoded on the
+ web as <code>%7e</code>) to be awkward and prefer to use an
+ alternate string to represent user directories. This functionality
+ is not supported by mod_userdir. However, if users' home
+ directories are structured in a regular way, then it is possible
+ to use the <directive module="mod_alias">AliasMatch</directive>
+ directive to achieve the desired effect. For example, to make
+ <code>http://www.example.com/upages/user/file.html</code> map to
+ <code>/home/user/public_html/file.html</code>, use the following
+ <code>AliasMatch</code> directive:</p>
+
+<example>AliasMatch ^/upages/([a-zA-Z0-9]+)(/(.*))?$
+ /home/$1/public_html/$3</example>
+</section>
+
+<section id="redirect"><title>URL Redirection</title>
+
+ <p>The configuration directives discussed in the above sections
+ tell httpd to get content from a specific place in the filesystem
+ and return it to the client. Sometimes, it is desirable instead to
+ inform the client that the requested content is located at a
+ different URL, and instruct the client to make a new request with
+ the new URL. This is called <em>redirection</em> and is
+ implemented by the <directive
+ module="mod_alias">Redirect</directive> directive. For example, if
+ the contents of the directory <code>/foo/</code> under the
+ <directive module="core">DocumentRoot</directive> are moved
+ to the new directory <code>/bar/</code>, you can instruct clients
+ to request the content at the new location as follows:</p>
+
+<example>Redirect permanent /foo/
+ http://www.example.com/bar/</example>
+
+ <p>This will redirect any URL-Path starting in
+ <code>/foo/</code> to the same URL path on the
+ <code>www.example.com</code> server with <code>/bar/</code>
+ substituted for <code>/foo/</code>. You can redirect clients to
+ any server, not only the origin server.</p>
+
+ <p>httpd also provides a <directive
+ module="mod_alias">RedirectMatch</directive> directive for more
+ complicated rewriting problems. For example, to redirect requests
+ for the site home page to a different site, but leave all other
+ requests alone, use the following configuration:</p>
+
+<example>RedirectMatch permanent ^/$
+ http://www.example.com/startpage.html</example>
+
+ <p>Alternatively, to temporarily redirect all pages on one site
+ to a particular page on another site, use the following:</p>
+
+<example>RedirectMatch temp .*
+ http://othersite.example.com/startpage.html</example>
+</section>
+
+<section id="proxy"><title>Reverse Proxy</title>
+
+<p>httpd also allows you to bring remote documents into the URL space
+of the local server. This technique is called <em>reverse
+proxying</em> because the web server acts like a proxy server by
+fetching the documents from a remote server and returning them to the
+client. It is different from normal (forward) proxying because, to the
client,
+it appears the documents originate at the reverse proxy server.</p>
+
+<p>In the following example, when clients request documents under the
+<code>/foo/</code> directory, the server fetches those documents from
+the <code>/bar/</code> directory on <code>internal.example.com</code>
+and returns them to the client as if they were from the local
+server.</p>
+
+<example>
+ProxyPass /foo/ http://internal.example.com/bar/<br />
+ProxyPassReverse /foo/ http://internal.example.com/bar/<br />
+ProxyPassReverseCookieDomain internal.example.com public.example.com<br />
+ProxyPassReverseCookiePath /foo/ /bar/
+</example>
+
+<p>The <directive module="mod_proxy">ProxyPass</directive> configures
+the server to fetch the appropriate documents, while the
+<directive module="mod_proxy">ProxyPassReverse</directive>
+directive rewrites redirects originating at
+<code>internal.example.com</code> so that they target the appropriate
+directory on the local server. Similarly, the
+<directive module="mod_proxy">ProxyPassReverseCookieDomain</directive>
+and <directive module="mod_proxy">ProxyPassReverseCookiePath</directive>
+rewrite cookies set by the backend server.</p>
+<p>It is important to note, however, that
+links inside the documents will not be rewritten. So any absolute
+links on <code>internal.example.com</code> will result in the client
+breaking out of the proxy server and requesting directly from
+<code>internal.example.com</code>. You can modify these links (and other
+content) in a page as it is being served to the client using
+<module>mod_substitute</module>.</p>
+
+<example>
+Substitute s/internal\.example\.com/www.example.com/i
+</example>
+
+<p>Additionally, a third-party module,
+<a href="http://apache.webthing.com/mod_proxy_html/">mod_proxy_html</a>,
+is available to rewrite links in HTML and XHTML.</p>
+</section>
+
+<section id="rewrite"><title>Rewriting Engine</title>
+
+ <p>When even more powerful substitution is required, the rewriting
+ engine provided by <module>mod_rewrite</module>
+ can be useful. The directives provided by this module can use
+ characteristics of the request such as browser type or source IP
+ address in deciding from where to serve content. In addition,
+ mod_rewrite can use external database files or programs to
+ determine how to handle a request. The rewriting engine is capable
+ of performing all three types of mappings discussed above:
+ internal redirects (aliases), external redirects, and proxying.
+ Many practical examples employing mod_rewrite are discussed in the
+ <a href="rewrite/">detailed mod_rewrite documentation</a>.</p>
+</section>
+
+<section id="notfound"><title>File Not Found</title>
+
+ <p>Inevitably, URLs will be requested for which no matching
+ file can be found in the filesystem. This can happen for
+ several reasons. In some cases, it can be a result of moving
+ documents from one location to another. In this case, it is
+ best to use <a href="#redirect">URL redirection</a> to inform
+ clients of the new location of the resource. In this way, you
+ can assure that old bookmarks and links will continue to work,
+ even though the resource is at a new location.</p>
+
+ <p>Another common cause of "File Not Found" errors is
+ accidental mistyping of URLs, either directly in the browser,
+ or in HTML links. httpd provides the module
+ <module>mod_speling</module> (sic) to help with
+ this problem. When this module is activated, it will intercept
+ "File Not Found" errors and look for a resource with a similar
+ filename. If one such file is found, mod_speling will send an
+ HTTP redirect to the client informing it of the correct
+ location. If several "close" files are found, a list of
+ available alternatives will be presented to the client.</p>
+
+ <p>An especially useful feature of mod_speling, is that it will
+ compare filenames without respect to case. This can help
+ systems where users are unaware of the case-sensitive nature of
+ URLs and the unix filesystem. But using mod_speling for
+ anything more than the occasional URL correction can place
+ additional load on the server, since each "incorrect" request
+ is followed by a URL redirection and a new request from the
+ client.</p>
+
+ <p><module>mod_dir</module> provides <directive module="mod_dir"
+ >FallbackResource</directive>, which can be used to map virtual
+ URIs to a real resource, which then serves them. This is a very
+ useful replace to <module>mod_rewrite</module> when implementing
+ a 'front controler'</p>
+
+ <p>If all attempts to locate the content fail, httpd returns
+ an error page with HTTP status code 404 (file not found). The
+ appearance of this page is controlled with the
+ <directive module="core">ErrorDocument</directive> directive
+ and can be customized in a flexible manner as discussed in the
+ <a href="custom-error.html">Custom error responses</a>
+ document.</p>
+</section>
+
+<section id="other"><title>Other URL Mapping Modules</title>
+
+
+
+ <p>Other modules available for URL mapping include:</p>
+
+ <ul>
+ <li><module>mod_actions</module> - Maps a request to a CGI script
+ based on the request method, or resource MIME type.</li>
+ <li><module>mod_dir</module> - Provides basic mapping of a trailing
+ slash into an index file such as <code>index.html</code>.</li>
+ <li><module>mod_imagemap</module> - Maps a request to a URL based
+ on where a user clicks on an image embedded in a HTML document.</li>
+ <li><module>mod_negotiation</module> - Selects an appropriate
+ document based on client preferences such as language or content
+ compression.</li>
+ </ul>
+
+</section>
+
+</manualpage>
=======================================
--- /trunk/l10n/apache/trunk/LICENSE Sat Feb 26 23:20:49 2011
+++ /dev/null
@@ -1,202 +0,0 @@
- 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.
-
=======================================
--- /trunk/l10n/apache/trunk/bind.xml Sat Feb 26 23:20:49 2011
+++ /dev/null
@@ -1,193 +0,0 @@
-<?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>
-
=======================================
--- /trunk/l10n/apache/trunk/caching.xml Sat Feb 26 23:20:49 2011
+++ /dev/null
@@ -1,671 +0,0 @@
-<?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>
=======================================
***Additional files exist in this changeset.***

Reply all

Reply to author

Forward

0 new messages