You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by jo...@apache.org on 2012/05/07 00:53:20 UTC
svn commit: r1334814 [1/3] - /httpd/site/trunk/content/dev/
Author: joes
Date: Sun May 6 22:53:19 2012
New Revision: 1334814
URL: http://svn.apache.org/viewvc?rev=1334814&view=rev
Log:
xforms
Added:
httpd/site/trunk/content/dev/debugging.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/debugging.xml
httpd/site/trunk/content/dev/devnotes.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/devnotes.xml
httpd/site/trunk/content/dev/guidelines.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/guidelines.xml
httpd/site/trunk/content/dev/how-to-release.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/how-to-release.xml
httpd/site/trunk/content/dev/index.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/index.xml
httpd/site/trunk/content/dev/patches.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/patches.xml
httpd/site/trunk/content/dev/release.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/release.xml
httpd/site/trunk/content/dev/styleguide.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/styleguide.xml
httpd/site/trunk/content/dev/verification.mdtext
- copied, changed from r1334802, httpd/site/trunk/content/dev/verification.xml
Removed:
httpd/site/trunk/content/dev/debugging.xml
httpd/site/trunk/content/dev/devnotes.xml
httpd/site/trunk/content/dev/guidelines.xml
httpd/site/trunk/content/dev/how-to-release.xml
httpd/site/trunk/content/dev/index.xml
httpd/site/trunk/content/dev/patches.xml
httpd/site/trunk/content/dev/release.xml
httpd/site/trunk/content/dev/styleguide.xml
httpd/site/trunk/content/dev/verification.xml
Copied: httpd/site/trunk/content/dev/debugging.mdtext (from r1334802, httpd/site/trunk/content/dev/debugging.xml)
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/debugging.mdtext?p2=httpd/site/trunk/content/dev/debugging.mdtext&p1=httpd/site/trunk/content/dev/debugging.xml&r1=1334802&r2=1334814&rev=1334814&view=diff
==============================================================================
--- httpd/site/trunk/content/dev/debugging.xml (original)
+++ httpd/site/trunk/content/dev/debugging.mdtext Sun May 6 22:53:19 2012
@@ -1,188 +1,193 @@
-<?xml version="1.0"?>
-<document>
- <properties>
- <author email="docs@httpd.apache.org">Documentation Group</author>
- <title>Apache HTTPD Debugging Guide</title>
- </properties>
-<body>
-
-<section id="id">
-<title>Apache Debugging Guide</title>
-
-<p>This document is a collection of notes regarding tools and techniques
-for debugging Apache httpd and its modules.</p>
-
-<p>Got more tips? Send 'em to
-<a href="mailto:docs@httpd.apache.org">docs@httpd.apache.org</a>. Thanks!</p>
-
-<ol>
-<li><a href="#gdb">Using <code>gdb</code></a></li>
-<li><a href="#backtrace">Getting a live backtrace on unix</a></li>
-<li><a href="#backtrace-win">Getting a live backtrace on Windows</a></li>
-<li><a href="#crashes">Debugging intermittent crashes</a></li>
-<li><a href="#truss">Using '<code>truss/trace/strace</code>' to
- trace system calls and signals</a></li>
-<li><a href="#gcore">Getting the server to dump core</a></li>
-<li><a href="#sol27">Solaris and coredumps</a></li>
-<li><a href="#tcpdump">Getting and analyzing a TCP packet trace</a></li>
-</ol>
-</section>
-
-<section id="gdb">
-<title>Using gdb</title>
-
-<p>If you use the gcc compiler, it is likely that the best
-debugger for your system is gdb. This is only a brief summary of how
-to run gdb on Apache -- you should look at the info and man files for
-gdb to get more information on gdb commands and common debugging techniques.
-Before running gdb, be sure that the server is compiled with the
-<code>-g</code> option in <code>CFLAGS</code> to include the
-symbol information in the object files.</p>
-
-<p>The only tricky part of running gdb on Apache is forcing the server
-into a single-process mode so that the parent process being debugged
-does the request-handling work instead of forking child processes.
-We have provided the <code>-X</code> option for that purpose, which will
-work fine for most cases. However, some modules don't like starting
-up with <code>-X</code>, but are happy if you force only one child to run
-(using "<code>MaxClients 1</code>"); you can then use gdb's attach command
-to debug the child server.</p>
+Title: Apache HTTPD Debugging Guide
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+This document is a collection of notes regarding tools and techniques for
+debugging Apache httpd and its modules.
+
+Got more tips? Send 'em to
+[docs@httpd.apache.org](mailto:docs@httpd.apache.org). Thanks!
+
+1. [Using](#gdb)
+
+1. [Getting a live backtrace on unix](#backtrace)
+
+1. [Getting a live backtrace on Windows](#backtrace-win)
+
+1. [Debugging intermittent crashes](#crashes)
+
+1. [Using '](#truss)
+
+1. [Getting the server to dump core](#gcore)
+
+1. [Solaris and coredumps](#sol27)
+
+1. [Getting and analyzing a TCP packet trace](#tcpdump)
+
+# Using gdb # {#gdb}
+
+If you use the gcc compiler, it is likely that the best debugger for your
+system is gdb. This is only a brief summary of how to run gdb on Apache --
+you should look at the info and man files for gdb to get more information
+on gdb commands and common debugging techniques. Before running gdb, be
+sure that the server is compiled with the `-g` option in `CFLAGS` to
+include the symbol information in the object files.
+
+The only tricky part of running gdb on Apache is forcing the server into a
+single-process mode so that the parent process being debugged does the
+request-handling work instead of forking child processes. We have provided
+the `-X` option for that purpose, which will work fine for most cases.
+However, some modules don't like starting up with `-X` , but are happy if
+you force only one child to run (using " `MaxClients 1` "); you can then
+use gdb's attach command to debug the child server.
-<p>The following example, with <font color="green">user input in green</font>,
+The following example, with<font color="green">user input in green</font>,
shows the output of gdb run on a server executable (httpd) in the current
-working directory and using the server root of
-<code>/usr/local/apache</code>:</p>
-
+working directory and using the server root of `/usr/local/apache` :
<pre>
- % <font color="green">gdb httpd</font>
+ % gdb httpd
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
- There is absolutely no warranty for GDB; type "show warranty" for details.
+ There is absolutely no warranty for GDB; type "show warranty" for
+ details.
GDB 4.16.gnat.1.13 (sparc-sun-solaris2.5),
Copyright 1996 Free Software Foundation, Inc...
- (gdb) <font color="green">b ap_process_request</font>
+ (gdb) b ap_process_request
Breakpoint 1 at 0x49fb4: file http_request.c, line 1164.
- (gdb) <font color="green">run -X -d /usr/local/apache</font>
+ (gdb) run -X -d /usr/local/apache
Starting program: /usr/local/apache/src/httpd -X -d /usr/local/apache
-
+
[at this point I make a request from another window]
Breakpoint 1, ap_process_request (r=0x95250) at http_request.c:1164
- 1164 if (ap_extended_status)
- (gdb) <font color="green">s</font>
- 1165 ap_time_process_request(r->connection->child_num, ...
- (gdb) <font color="green">n</font>
- 1167 process_request_internal(r);
- (gdb) <font color="green">s</font>
+ 1164 if (ap_extended_status)
+ (gdb) s
+ 1165
+ ap_time_process_request(r->connection->child_num,...
+ (gdb) n
+ 1167 process_request_internal(r);
+ (gdb) s
process_request_internal (r=0x95250) at http_request.c:1028
- 1028 if (!r->proxyreq && r->parsed_uri.path) {
- (gdb) <font color="green">s</font>
- 1029 access_status = ap_unescape_url(r->parsed_uri.path);
- (gdb) <font color="green">n</font>
- 1030 if (access_status) {
- (gdb) <font color="green">s</font>
- 1036 ap_getparents(r->uri); /* OK ...
- (gdb) <font color="green">n</font>
- 1038 if ((access_status = location_walk(r))) {
- (gdb) <font color="green">n</font>
- 1043 if ((access_status = ap_translate_name(r))) {
- (gdb) <font color="green">n</font>
- 1048 if (!r->proxyreq) {
- (gdb) <font color="green">n</font>
- 1053 if (r->method_number == M_TRACE) {
- (gdb) <font color="green">n</font>
- 1062 if (r->proto_num > HTTP_VERSION(1,0) && ap_ ...
- (gdb) <font color="green">n</font>
- 1071 if ((access_status = directory_walk(r))) {
- (gdb) <font color="green">s</font>
+ 1028 if (!r->proxyreq && r->parsed_uri.path) {
+ (gdb) s
+ 1029 access_status = ap_unescape_url(r->parsed_uri.path);
+ (gdb) n
+ 1030 if (access_status) {
+ (gdb) s
+ 1036 ap_getparents(r->uri); /* OK...
+ (gdb) n
+ 1038 if ((access_status = location_walk(r))) {
+ (gdb) n
+ 1043 if ((access_status = ap_translate_name(r))) {
+ (gdb) n
+ 1048 if (!r->proxyreq) {
+ (gdb) n
+ 1053 if (r->method_number == M_TRACE) {
+ (gdb) n
+ 1062 if (r->proto_num > HTTP_VERSION(1,0) &&
+ ap_...
+ (gdb) n
+ 1071 if ((access_status = directory_walk(r))) {
+ (gdb) s
directory_walk (r=0x95250) at http_request.c:288
- 288 core_server_config *sconf = ap_get_module_ ...
- (gdb) <font color="green">b ap_send_error_response</font>
+ 288 core_server_config *sconf = ap_get_module_...
+ (gdb) b ap_send_error_response
Breakpoint 2 at 0x47dcc: file http_protocol.c, line 2090.
- (gdb) <font color="green">c</font>
+ (gdb) c
Continuing.
-
+
Breakpoint 2, ap_send_error_response (r=0x95250, recursive_error=0)
- at http_protocol.c:2090
- 2090 BUFF *fd = r->connection->client;
- (gdb) <font color="green">where</font>
- #0 ap_send_error_response (r=0x95250, recursive_error=0)
- at http_protocol.c:2090
- #1 0x49b10 in ap_die (type=403, r=0x95250) at http_request.c:989
- #2 0x49b60 in decl_die (status=403, phase=0x62db8 "check access", r=0x95250)
- at http_request.c:1000
- #3 0x49f68 in process_request_internal (r=0x95250) at http_request.c:1141
- #4 0x49fe0 in ap_process_request (r=0x95250) at http_request.c:1167
- #5 0x439d8 in child_main (child_num_arg=550608) at http_main.c:3826
- #6 0x43b5c in make_child (s=0x7c3e8, slot=0, now=907958743)
- at http_main.c:3898
- #7 0x43ca8 in startup_children (number_to_start=6) at http_main.c:3972
- #8 0x44260 in standalone_main (argc=392552, argv=0x75800) at http_main.c:4250
- #9 0x449fc in main (argc=4, argv=0xefffee8c) at http_main.c:4534
- (gdb) <font color="green">s</font>
- 2091 int status = r->status;
- (gdb) <font color="green">p status</font>
+ at http_protocol.c:2090
+ 2090 BUFF *fd = r->connection->client;
+ (gdb) where
+ #0 ap_send_error_response (r=0x95250, recursive_error=0)
+ at http_protocol.c:2090
+ #1 0x49b10 in ap_die (type=403, r=0x95250) at http_request.c:989
+ #2 0x49b60 in decl_die (status=403, phase=0x62db8 "check access",
+ r=0x95250)
+ at http_request.c:1000
+ #3 0x49f68 in process_request_internal (r=0x95250) at
+ http_request.c:1141
+ #4 0x49fe0 in ap_process_request (r=0x95250) at http_request.c:1167
+ #5 0x439d8 in child_main (child_num_arg=550608) at http_main.c:3826
+ #6 0x43b5c in make_child (s=0x7c3e8, slot=0, now=907958743)
+ at http_main.c:3898
+ #7 0x43ca8 in startup_children (number_to_start=6) at http_main.c:3972
+ #8 0x44260 in standalone_main (argc=392552, argv=0x75800) at
+ http_main.c:4250
+ #9 0x449fc in main (argc=4, argv=0xefffee8c) at http_main.c:4534
+ (gdb) s
+ 2091 int status = r->status;
+ (gdb) p status
$1 = 403
(gdb)
</pre>
+There are a few things to note about the above example:
+
+1. the " `gdb httpd` " command does not include any command-line options
+for httpd: those are provided when the " `run` " command is done within
+gdb;
+
+1. I set a breakpoint before starting the run so that execution would stop
+at the top of ap_process_request();
+
+1. the " `s` " command steps through the code and into called procedures,
+whereas the " `n` " (next) command steps through the code but not into
+called procedures.
-<p>There are a few things to note about the above example:</p>
+1. additional breakpoints can be set with the " `b` " command, and the run
+continued with the " `c` " command.
-<ol>
-<li>the "<code>gdb httpd</code>" command does not include any command-line
- options for httpd: those are provided when the "<code>run</code>" command
- is done within gdb;</li>
-<li>I set a breakpoint before starting the run so that execution would stop
- at the top of ap_process_request();</li>
-<li>the "<code>s</code>" command steps through the code and into called
- procedures, whereas the "<code>n</code>" (next) command steps through
- the code but not into called procedures.</li>
-<li>additional breakpoints can be set with the "<code>b</code>" command,
- and the run continued with the "<code>c</code>" command.</li>
-<li>use the "<code>where</code>" command (a.k.a. "<code>bt</code>") to see
- a stack backtrace that shows the order of called procedures and their
- parameter values.</li>
-<li>use the "<code>p</code>" command to print the value of a variable.</li>
-</ol>
-
-<p>A file in the the root directory called <code>.gdbinit</code> provides
-useful macros for printing out various internal structures of httpd like tables
-(<code>dump_table</code>), brigades (<code>dump_brigade</code>) and filter chains
-(<code>dump_filters</code>).</p>
-
-<p>If you are debugging a repeatable crash, simply run gdb as above
-and make the request -- gdb should capture the crash and provide a
-prompt where it occurs.</p>
-
-<p>If you are debugging an apparent infinite loop, simply run gdb as above
-and type a Control-C -- gdb will interrupt the process and provide a
-prompt where it was stopped.</p>
+1. use the " `where` " command (a.k.a. " `bt` ") to see a stack backtrace
+that shows the order of called procedures and their parameter values.
-<p>If you are debugging a system crash and you have a core file from
-the crash, then do the following:</p>
+1. use the " `p` " command to print the value of a variable.
+A file in the the root directory called `.gdbinit` provides useful macros
+for printing out various internal structures of httpd like tables (
+`dump_table` ), brigades ( `dump_brigade` ) and filter chains (
+`dump_filters` ).
+
+If you are debugging a repeatable crash, simply run gdb as above and make
+the request -- gdb should capture the crash and provide a prompt where it
+occurs.
+
+If you are debugging an apparent infinite loop, simply run gdb as above and
+type a Control-C -- gdb will interrupt the process and provide a prompt
+where it was stopped.
+
+If you are debugging a system crash and you have a core file from the
+crash, then do the following:
<pre>
- % <font color="green">gdb httpd -c core</font>
- (gdb) <font color="green">where</font>
-</pre>
+ % gdb httpd -c core
+ (gdb) where</pre>
+and it will (hopefully) print a stack backtrace of where the core dump
+occurred during processing.
+
+# Getting a live backtrace on unix # {#backtrace}
-<p>and it will (hopefully) print a stack backtrace of where the core dump
-occurred during processing.</p>
-</section>
-
-<section id="backtrace">
-<title>Getting a live backtrace on unix</title>
-
-<p>A backtrace will let you know the hierarchy of procedures that
-were called to get to a particular point in the process. On some platforms
-you can get a live backtrace of any process.</p>
-
-<p>For SVR4-based variants of Unix, the <code>pstack</code> command for proc can
-be used to display a a live backtrace. For example, on Solaris it looks
-like</p>
+A backtrace will let you know the hierarchy of procedures that were called
+to get to a particular point in the process. On some platforms you can get
+a live backtrace of any process.
+For SVR4-based variants of Unix, the `pstack` command for proc can be used
+to display a a live backtrace. For example, on Solaris it looks like
<pre>
- % <font color="green">/usr/proc/bin/pstack 10623</font>
+ % /usr/proc/bin/pstack 10623
10623: httpd -d /usr/local/apache
ef5b68d8 poll (efffcd08, 0, 3e8)
ef5d21e0 select (0, ef612c28, 0, 0, 3e8, efffcd08) + 288
@@ -191,18 +196,17 @@ like</p>
000449f4 main (3, efffeee4, efffeef4, 75fe4, 1, 0) + 374
000162fc _start (0, 0, 0, 0, 0, 0) + 5c
</pre>
-
-<p>Another technique is to use gdb to attach to the running process
-and then using "where" to print the backtrace, as in</p>
-
+Another technique is to use gdb to attach to the running process and then
+using "where" to print the backtrace, as in
<pre>
- % <font color="green">gdb httpd 10623</font>
+ % gdb httpd 10623
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
- There is absolutely no warranty for GDB; type "show warranty" for details.
+ There is absolutely no warranty for GDB; type "show warranty" for
+ details.
GDB 4.16.gnat.1.13 (sparc-sun-solaris2.5),
Copyright 1996 Free Software Foundation, Inc...
-
+
/usr/local/apache/src/10623: No such file or directory.
Attaching to program `/usr/local/apache/src/httpd', process 10623
Reading symbols from /usr/lib/libsocket.so.1...done.
@@ -212,290 +216,222 @@ and then using "where" to print the back
Reading symbols from /usr/lib/libintl.so.1...done.
Reading symbols from /usr/lib/libmp.so.1...done.
Reading symbols from /usr/lib/libw.so.1...done.
- Reading symbols from /usr/platform/SUNW,Ultra-1/lib/libc_psr.so.1...done.
+ Reading symbols from
+ /usr/platform/SUNW,Ultra-1/lib/libc_psr.so.1...done.
0xef5b68d8 in ()
- (gdb) <font color="green">where</font>
- #0 0xef5b68d8 in ()
- #1 0xef5d21e8 in select ()
- #2 0x4257c in wait_or_timeout (status=0x0) at http_main.c:2357
- #3 0x44318 in standalone_main (argc=392552, argv=0x75800) at ...
- #4 0x449fc in main (argc=3, argv=0xefffeee4) at http_main.c:4534
+ (gdb) where
+ #0 0xef5b68d8 in ()
+ #1 0xef5d21e8 in select ()
+ #2 0x4257c in wait_or_timeout (status=0x0) at http_main.c:2357
+ #3 0x44318 in standalone_main (argc=392552, argv=0x75800) at...
+ #4 0x449fc in main (argc=3, argv=0xefffeee4) at http_main.c:4534
(gdb)
</pre>
-</section>
-
-<section id="backtrace-win">
-<title>Getting a live backtrace on Windows</title>
-<ol>
-<li> Unzip the <code>-symbols.zip</code> files (obtained from the
- Apache download site) in the root Apache2 directory tree (where
- bin\, htdocs\, modules\ etc. are usually found.) These .pdb files
- should unpack alongside the .exe, .dll, .so binary files they
- represent, e.g., mod_usertrack.pdb will unpack alongside
- mod_usertrack.so.</li>
-
-<li> Invoke <code>drwtsn32</code> and ensure you are creating a crash
- dump file, you are dumping all thread contexts, your log and crash
- dump paths make sense, and (depending on the nature of the bug) you
- pick an appropriate crash dump type. (Full is quite large, but
- necessary sometimes for a programmer-type to load your crash dump
- into a debugger and begin unwinding exactly what has happened.
- Mini is sufficient for your first pass through the process.)</li>
-
-<li> Note that if you previously installed and then uninstalled other debugging
- software, you may need to invoke <code>drwtsn32 -i</code> in order to make
- Dr Watson your default crash dump tool. This will replace the 'report
- problem to MS' dialogs. (Don't do this if you have a full debugger such
- as Visual Studio or windbg installed on the machine, unless you back up the
- registry value for <code>Debugger</code> under the
- <code>HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug</code>
- registry tree. Developers using multiple tools might want to keep copies
- of their different tools Debugger entries there, for fast switching.)</li>
-
-<li> Invoke the Task Manager, Choose 'show processes from all users',
- and modify the <code>View -> Select Columns</code> to include
- <strong>at least</strong> the <code>PID</code> and <code>Thread
- Count</code>. You can change this just once and Task Manager
- should keep your preference.</li>
-
-<li> Now, track down the errant Apache that is hanging. The parent
- process has about three threads, we don't care about that one. The
- child worker process we want has many more threads (a few more than
- you configured with the ThreadsPerChild directive.) The process
- name is Apache (for 1.3 and 2.0) or httpd (for 2.2 and 2.4). Make note of
- the child worker's PID.</li>
-
-<li> Using the {pid} number you noted above, invoke the command
- <blockquote><code>drwtsn32 -p {pid}</code></blockquote></li>
-</ol>
-
-<p>Voila, you will find in your 'log file path' a
-<code>drwtsn32.log</code> file, and if you choose to 'append to
-existing log file', jump through the 'App:' sections until you find
-the one for the process you just killed. Now you can identify
-about where 'Stack Back Trace' points to help identify what the server
-is doing.</p>
-
-<p>You will note that many threads look identical, almost all of them
-polling for the next connection, and you don't care about those. You will
-want to see the ones that are deep inside of a request at the time you
-kill them, and only the stack back trace entries for those. This can
-give folks a clue of where that request is hanging, which handler
-module picked up the request, and what filter it might be stuck in.</p>
-</section>
-
-
-<section id="crashes">
-<title>Debugging intermittent crashes</title>
-
-<p>For situations where a child process is crashing intermittently,
-the server must be configured and started such that it produces core
-dumps which can be analyzed further.</p>
-
-<p>To ensure that a core dump is written to a directory which is
-writable by the user which child processes run as (such as
-<code>apache</code>), the <a
-href="http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory"><code>CoreDumpDirectory</code></a>
-directive must be added to <code>httpd.conf</code>; for example:</p>
+# Getting a live backtrace on Windows # {#backtrace-win}
-<pre>
+1. Unzip the `-symbols.zip` files (obtained from the Apache download site)
+in the root Apache2 directory tree (where bin\, htdocs\, modules\ etc. are
+usually found.) These.pdb files should unpack alongside the.exe,.dll,.so
+binary files they represent, e.g., mod_usertrack.pdb will unpack alongside
+mod_usertrack.so.
+
+1. Invoke `drwtsn32` and ensure you are creating a crash dump file, you are
+dumping all thread contexts, your log and crash dump paths make sense, and
+(depending on the nature of the bug) you pick an appropriate crash dump
+type. (Full is quite large, but necessary sometimes for a programmer-type
+to load your crash dump into a debugger and begin unwinding exactly what
+has happened. Mini is sufficient for your first pass through the process.)
+
+1. Note that if you previously installed and then uninstalled other
+debugging software, you may need to invoke `drwtsn32 -i` in order to make
+Dr Watson your default crash dump tool. This will replace the 'report
+problem to MS' dialogs. (Don't do this if you have a full debugger such as
+Visual Studio or windbg installed on the machine, unless you back up the
+registry value for `Debugger` under the `HKLM\SOFTWARE\Microsoft\Windows
+NT\CurrentVersion\AeDebug` registry tree. Developers using multiple tools
+might want to keep copies of their different tools Debugger entries there,
+for fast switching.)
+
+1. Invoke the Task Manager, Choose 'show processes from all users', and
+modify the `View -> Select Columns` to include **at least** the `PID`
+and `Thread
+ Count`. You can change this just once and Task Manager should keep your
+ preference.
+
+1. Now, track down the errant Apache that is hanging. The parent process
+has about three threads, we don't care about that one. The child worker
+process we want has many more threads (a few more than you configured with
+the ThreadsPerChild directive.) The process name is Apache (for 1.3 and
+2.0) or httpd (for 2.2 and 2.4). Make note of the child worker's PID.
+
+1. Using the {pid} number you noted above, invoke the command
+> `drwtsn32 -p {pid}`
+
+Voila, you will find in your 'log file path' a `drwtsn32.log` file, and if
+you choose to 'append to existing log file', jump through the 'App:'
+sections until you find the one for the process you just killed. Now you
+can identify about where 'Stack Back Trace' points to help identify what
+the server is doing.
+
+You will note that many threads look identical, almost all of them polling
+for the next connection, and you don't care about those. You will want to
+see the ones that are deep inside of a request at the time you kill them,
+and only the stack back trace entries for those. This can give folks a clue
+of where that request is hanging, which handler module picked up the
+request, and what filter it might be stuck in.
+
+# Debugging intermittent crashes # {#crashes}
+
+For situations where a child process is crashing intermittently, the server
+must be configured and started such that it produces core dumps which can
+be analyzed further.
+
+To ensure that a core dump is written to a directory which is writable by
+the user which child processes run as (such as `apache` ), the
+[](http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory)
+directive must be added to `httpd.conf` ; for example:
+`
CoreDumpDirectory /tmp
-</pre>
-
-<p>Before starting up the server, any process limits on core dump file
-size must be lifted; for example:</p>
-
-<pre>
+`
+Before starting up the server, any process limits on core dump file size
+must be lifted; for example:
+`
# ulimit -c unlimited
# apachectl start
-</pre>
-
-<p>On some platforms, further steps might be needed to enable core
-dumps - see <a href="#sol27">Solaris and coredumps</a> below.</p>
-
-<p>When a child process crashes, a message like the following will be
-logged to the error_log:</p>
-
-<blockquote><code>
-[Mon Sep 05 13:35:39 2005] [notice] child pid 2027 exit signal Segmentation fault (11), possible coredump in /tmp
-</code></blockquote>
-
-<p>If the text "possible coredump in /tmp" does not appear in the
-error line, check that the ulimit was set correctly, that the
-permissions on the configured <code>CoreDumpDirectory</code> are
-suitable and that platform specific steps
-(<a href="#sol27">Solaris and coredumps</a>) have been done if needed.</p>
-
-<p>To analyse the core dump, pass the core dump filename on the gdb
-command-line, and enter the command <code>bt full</code> at the gdb
-prompt:</p>
+`
+On some platforms, further steps might be needed to enable core dumps - see
+[Solaris and coredumps](#sol27) below.
+
+When a child process crashes, a message like the following will be logged
+to the error_log:
+
+> `
+[Mon Sep 05 13:35:39 2005] [notice] child pid 2027 exit signal Segmentation
+fault (11), possible coredump in /tmp
+`
+
+If the text "possible coredump in /tmp" does not appear in the error line,
+check that the ulimit was set correctly, that the permissions on the
+configured `CoreDumpDirectory` are suitable and that platform specific
+steps ( [Solaris and coredumps](#sol27) ) have been done if needed.
+To analyse the core dump, pass the core dump filename on the gdb
+command-line, and enter the command `bt full` at the gdb prompt:
<pre>
- % <b>gdb /usr/local/apache2/bin/httpd /tmp/core.2027</b>
- ...
+ % gdb /usr/local/apache2/bin/httpd /tmp/core.2027
+...
Core was generated by `/usr/local/apache2/bin/httpd -k start'
- ...
- (gdb) <b>bt full</b>
-</pre>
-
-<p>If attempting to debug a threaded server, for example when using
-the <code>worker</code> MPM, use the following gdb command:</p>
-
+...
+ (gdb) bt full</pre>
+If attempting to debug a threaded server, for example when using the
+`worker` MPM, use the following gdb command:
<pre>
- (gdb) <b>thread apply all bt full</b>
-</pre>
+ (gdb) thread apply all bt full</pre>
-</section>
+# Using 'truss/trace/strace' to trace system calls and signals # {#truss}
-<section id="truss">
-<title>Using 'truss/trace/strace' to trace system calls and
-signals</title>
-
-<p>Most Unix-based systems have at least one command for displaying
-a trace of system calls and signals as they are accessed by a running
-process. This command is called <code>truss</code> on most SVR4-based
-systems and either <code>trace</code> or <code>strace</code> on many
-other systems.</p>
-
-<p>A useful tip for using the <code>truss</code> command on Solaris is
-the <code>-f</code> option (often also works with <code>strace</code>); it tells
-truss to follow and continue tracing any child processes forked by the main
-process. The easiest way to get a full trace of a server is to do something
-like:</p>
+Most Unix-based systems have at least one command for displaying a trace of
+system calls and signals as they are accessed by a running process. This
+command is called `truss` on most SVR4-based systems and either `trace` or
+`strace` on many other systems.
+A useful tip for using the `truss` command on Solaris is the `-f` option
+(often also works with `strace` ); it tells truss to follow and continue
+tracing any child processes forked by the main process. The easiest way to
+get a full trace of a server is to do something like:
<pre>
- % <font color="green">truss -f httpd -d /usr/local/apache >& outfile</font>
-</pre>
-and let it run through a few requests before killing the parent. You can
-then view the entire trace in outfile, or use something like
+ % truss -f httpd -d /usr/local/apache >& outfile</pre><pre>
+ % egrep '^10698:' outfile</pre>
+to view just the trace of the process id 10698.
+
+If attempting to truss a threaded server, for example when using the
+`worker` MPM, the `truss` option `-l` is very useful as it prints also the
+LWP id after the process id. You can use something like
<pre>
- % <font color="green">egrep '^10698:' outfile</font>
-</pre>
+ % egrep '^10698/1:' outfile</pre>
+to view just the trace of the process id 10698 and LWP id 1.
-<p>to view just the trace of the process id 10698.</p>
+Other useful options for truss are
-<p>If attempting to truss a threaded server, for example when using
-the <code>worker</code> MPM, the <code>truss</code> option <code>-l</code>
-is very useful as it prints also the LWP id after the process id. You can use
-something like</p>
+- `-a` to print all command line parameters used for this executable.
-<pre>
- % <font color="green">egrep '^10698/1:' outfile</font>
-</pre>
+- `-e` to print all environment variables used for this executable.
-<p>to view just the trace of the process id 10698 and LWP id 1.</p>
+- `-d` to print timestamps.
-<p>Other useful options for truss are</p>
+# Getting the server to dump core # {#gcore}
-<ul>
-<li>
-<code>-a</code> to print all command line parameters used for this executable.
-</li>
-<li>
-<code>-e</code> to print all environment variables used for this executable.
-</li>
-<li>
-<code>-d</code> to print timestamps.
-</li>
-</ul>
-
-</section>
-
-<section id="gcore">
-<title>Getting the server to dump core</title>
-
-<p>Strangely enough, sometimes you actually want to force the server
-to crash so that you can get a look at some nutty behavior. Normally
-this can be done simply by using the <code>gcore</code> command.
-However, for security reasons, most Unix systems do not allow a setuid
-process to dump core, since the file contents might reveal something
-that is supposed to be protected in memory.</p>
-
-<p>Here is one way to get a core file from a setuid Apache httpd process
-on Solaris, without knowing which httpd child might be the one to die
-[note: it is probably easier to use the MaxClients trick in the first
-section above].</p>
+Strangely enough, sometimes you actually want to force the server to crash
+so that you can get a look at some nutty behavior. Normally this can be
+done simply by using the `gcore` command. However, for security reasons,
+most Unix systems do not allow a setuid process to dump core, since the
+file contents might reveal something that is supposed to be protected in
+memory.
-<pre>
+Here is one way to get a core file from a setuid Apache httpd process on
+Solaris, without knowing which httpd child might be the one to die [note:
+it is probably easier to use the MaxClients trick in the first section
+above].
+`
# for pid in `ps -eaf | fgrep httpd | cut -d' ' -f4`
do
- truss -f -l -t\!all -S SIGSEGV -p $pid 2>&1 | egrep SIGSEGV &
+ truss -f -l -t\!all -S SIGSEGV -p $pid 2>&1 | egrep SIGSEGV
+ &
done
-</pre>
-
-<p>The <a href="http://www.dejanews.com/=zzz_maf/getdoc.xp?AN=352257973">
-undocumented '-S' flag</a> to truss will halt the process in place
-upon receipt of a given signal (SIGSEGV in this case).
-At this point you can use:</p>
-
-<pre>
- # gcore <i>PID</i>
-</pre>
-
-<p>and then look at the backtrace as discussed above for
-<a href="#gdb">gdb</a>.</p>
-</section>
-
-<section id="sol27">
-<title>Solaris and coredumps</title>
-
-<p>On Solaris use <a href="http://docs.sun.com/app/docs/doc/816-5166/coreadm-1m"
-><code>coreadm(1M)</code></a> to make
-<code>setuid()</code> processes actually dump core. By default a setuid()
-process does not dump core. This is the reason why httpd servers started as
-root with child processes running as a different user (such as
-<code>apache</code>) do not coredump even when the
-<a href="http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory">
-<code>CoreDumpDirectory</code></a>
-directive had been set to an appropriate and writable directory and
-<b><code>ulimit -c</code></b> has a sufficient size. See also
-<a href="#crashes">Debugging intermittent crashes</a> above.
-</p>
+`
+The [undocumented '-S'
+flag](http://www.dejanews.com/=zzz_maf/getdoc.xp?AN=352257973) to truss
+will halt the process in place upon receipt of a given signal (SIGSEGV in
+this case). At this point you can use:
+<pre>
+ # gcore PID</pre>
+and then look at the backtrace as discussed above for [gdb](#gdb).
+
+# Solaris and coredumps # {#sol27}
+
+On Solaris use [](http://docs.sun.com/app/docs/doc/816-5166/coreadm-1m) to
+make `setuid()` processes actually dump core. By default a setuid() process
+does not dump core. This is the reason why httpd servers started as root
+with child processes running as a different user (such as `apache` ) do not
+coredump even when the
+[](http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory)
+directive had been set to an appropriate and writable directory and **
+`ulimit -c` ** has a sufficient size. See also [Debugging intermittent
+crashes](#crashes) above.
-<p>Example:</p>
-<pre>
+Example:
+`
-bash-3.00# coreadm
global core file pattern: /var/core/core.%f.%p.u%u
global core file content: default
init core file pattern: core
init core file content: default
- global core dumps: disabled
+ global core dumps: disabled
per-process core dumps: enabled
global setid core dumps: enabled
- per-process setid core dumps: enabled
+per-process setid core dumps: enabled
global core dump logging: disabled
-</pre>
-</section>
+`
+
+# Getting and analyzing a TCP packet trace # {#tcpdump}
+
+This is too deep a subject to fully describe in this documentation. Here
+are some pointers to useful discussions and tools:
+
+- `snoop` is a packet sniffer that is part of Solaris.
-<section id="tcpdump">
-<title>Getting and analyzing a TCP packet trace</title>
+- [tcpdump](http://www.tcpdump.org/) is a packet sniffer that is available
+for Unix-based systems and Windows (
+[windump](http://www.winpcap.org/windump/) ). It is part of many free
+Unix-based distributions.
-<p>This is too deep a subject to fully describe in this documentation.
-Here are some pointers to useful discussions and tools:</p>
+- [Wireshark](http://www.wireshark.org/) is another packet sniffer that is
+available for Unix-based systems and Windows. It has a nice GUI and allows
+the analysis of the sniffed data.
-<ul>
-<li>
-<code>snoop</code> is a packet sniffer that is part of Solaris.
-</li>
-<li>
-<a href="http://www.tcpdump.org/">tcpdump</a> is a packet sniffer that is
-available for Unix-based systems and Windows
-(<a href="http://www.winpcap.org/windump/">windump</a>).
-It is part of many free Unix-based distributions.
-</li>
-<li>
-<a href="http://www.wireshark.org/">Wireshark</a> is another packet sniffer
-that is available for Unix-based systems and Windows. It has a nice GUI and
-allows the analysis of the sniffed data.
-</li>
-<li><a href="http://jarok.cs.ohiou.edu/software/tcptrace/">
- tcptrace</a> is a TCP dump file analysis tool.</li>
-<li><a href="http://www.tcpshow.org/">tcpshow</a> is
- another one.</li>
-</ul>
+- [tcptrace](http://jarok.cs.ohiou.edu/software/tcptrace/) is a TCP dump
+file analysis tool.
-</section>
+- [tcpshow](http://www.tcpshow.org/) is another one.
-</body>
-</document>
Copied: httpd/site/trunk/content/dev/devnotes.mdtext (from r1334802, httpd/site/trunk/content/dev/devnotes.xml)
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/devnotes.mdtext?p2=httpd/site/trunk/content/dev/devnotes.mdtext&p1=httpd/site/trunk/content/dev/devnotes.xml&r1=1334802&r2=1334814&rev=1334814&view=diff
==============================================================================
--- httpd/site/trunk/content/dev/devnotes.xml (original)
+++ httpd/site/trunk/content/dev/devnotes.mdtext Sun May 6 22:53:19 2012
@@ -1,207 +1,177 @@
-<?xml version="1.0"?>
-<document>
- <properties>
- <author email="docs@httpd.apache.org">Documentation Group</author>
- <title>Apache Development Notes</title>
- </properties>
-<body>
-<section>
-<title>Apache Development Notes</title>
-
-<p>This page is intended to provide some basic background about
-development nits and the maintenance of the developer site.</p>
-</section>
-
-<section>
-<title>Overview</title>
-
-<p>The Apache HTTP Server Project has switched to
-<a href="http://subversion.apache.org/">Subversion</a> for hosting its source
-code.</p>
-
-<p>To check out the 2.4.x branch:</p>
-<blockquote>
-<code>
-svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x httpd-2.4.x
-</code>
-</blockquote>
+Title: Apache Development Notes
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+This page is intended to provide some basic background about development
+nits and the maintenance of the developer site.
+
+# Overview #
+
+The Apache HTTP Server Project has switched to
+[Subversion](http://subversion.apache.org/) for hosting its source code.
+
+To check out the 2.4.x branch:
+
+> `
+svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x
+httpd-2.4.x
+`
-<p>To check out the current development version (as of this writing, 2.5.x),
-use:</p>
+To check out the current development version (as of this writing, 2.5.x),
+use:
-<blockquote>
-<code>
+> `
svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk httpd-trunk
-</code>
-</blockquote>
+`
-<p>Committers should check out via https instead of http (so that they can
-commit their changes). For more info about Subversion, please read <a
-href="http://www.apache.org/dev/version-control.html"
->the ASF version control FAQ</a>.</p>
+Committers should check out via https instead of http (so that they can
+commit their changes). For more info about Subversion, please read [the ASF
+version control FAQ](http://www.apache.org/dev/version-control.html).
-<p>The developers continue to seek to maintain module compatibility between
+The developers continue to seek to maintain module compatibility between
2.4.1 and future 2.4 releases for administrators and end users, while
-continuing the forward progress that has made the 2.2 server faster and more
-scalable.</p>
-</section>
-
-<section>
-<title>Maintaining the Sources</title>
-
-<p>Almost all files relating to Apache, both the actual sources and the
-files that aren't part of the distribution, are now maintained in an
-<a href="http://subversion.apache.org/">SVN</a> repository. Here is the way
-in which changes are applied:</p>
-
- <ol>
- <li>Developer checks out a copy of the files on which he wants to
- work (in this case, the trunk), into a private working directory
- called <samp>httpd-trunk</samp>:
- <p>
- <dl>
- <dd><samp>% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk
- httpd-trunk</samp>
- </dd>
- </dl>
- </p>
- <p>
- This step only needs to be performed once (unless the private working
- directory is tainted or deleted.) Committers should use a URL prefix
- of <samp>https</samp> on the checkout, to save themselves headaches later.
- </p>
- </li>
- <li>Developer keeps his working directory synchronised with changes
- made to the repository:
- <p>
- <dl>
- <dd><samp>% svn update httpd-trunk</samp>
- </dd>
- </dl>
- </p>
- <p>
- This should probably be done daily or even more frequently during
- periods of high activity.
- </p>
- </li>
- <li>Developer makes changes to his working copies, makes sure they
- work, and generates a patch so others can apply the changes to test
- them:
- <p>
- <dl>
- <dd><samp>% svn diff httpd-trunk/modules/http/mod_mime.c > /tmp/foo</samp>
- </dd>
- </dl>
- </p>
- <p>
- The <samp>/tmp/foo</samp> file is mailed to the
- <a href="http://httpd.apache.org/lists.html#http-dev">developers list</a> so
- they can consider the value/validity of the patch. It is worth
- making sure your code follows the Apache style, as described in the
- <a href="styleguide.html">style guide</a>.
- </p>
- </li>
- <li>Once other developers have agreed that the change is a Good
- Thing, the developer checks the changes into the repository:
- <p>
- <dl>
- <dd><samp>% svn commit httpd-trunk/modules/http/mod_mime.c</samp>
- </dd>
- </dl>
- </p>
- </li>
- </ol>
-</section>
-
-<section>
-<title>SVN Subtrees</title>
- <p>There are several different branches under the <samp>httpd</samp>
- subtree in the Apache SVN repository that pertain to the different
- releases. The top level can be perused with the
- <a href="http://svn.apache.org/viewcvs.cgi/">SVN ViewCVS</a> pages.
- The main subtrees pertaining to the <samp>httpd</samp> server source
- are:</p>
-
- <section><title>httpd-2.2</title>
- <p>To create a directory tree containing the 2.2 sources,
- and call it <samp>httpd-2.2</samp>, change your current directory
- to the <em>parent</em> of the tree and then check the 2.2 sources
- out as follows:</p>
- <source>
+continuing the forward progress that has made the 2.2 server faster and
+more scalable.
+
+# Maintaining the Sources #
+
+Almost all files relating to Apache, both the actual sources and the files
+that aren't part of the distribution, are now maintained in an
+[SVN](http://subversion.apache.org/) repository. Here is the way in which
+changes are applied:
+
+1. Developer checks out a copy of the files on which he wants to work (in
+this case, the trunk), into a private working directory
+called<samp>httpd-trunk</samp>:
+
+: <samp>% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk
+ httpd-trunk</samp>
+
+This step only needs to be performed once (unless the private working
+directory is tainted or deleted.) Committers should use a URL prefix
+of<samp>https</samp>on the checkout, to save themselves headaches later.
+
+1. Developer keeps his working directory synchronised with changes made to
+the repository:
+
+: <samp>% svn update httpd-trunk</samp>
+
+This should probably be done daily or even more frequently during periods
+of high activity.
+
+1. Developer makes changes to his working copies, makes sure they work, and
+generates a patch so others can apply the changes to test them:
+
+: <samp>% svn diff httpd-trunk/modules/http/mod_mime.c >
+ /tmp/foo</samp>
+
+The<samp>/tmp/foo</samp>file is mailed to the [developers
+list](http://httpd.apache.org/lists.html#http-dev) so they can consider the
+value/validity of the patch. It is worth making sure your code follows the
+Apache style, as described in the [style guide](styleguide.html).
+
+1. Once other developers have agreed that the change is a Good Thing, the
+developer checks the changes into the repository:
+
+: <samp>% svn commit httpd-trunk/modules/http/mod_mime.c</samp>
+
+# SVN Subtrees #
+
+There are several different branches under the<samp>httpd</samp>subtree in
+the Apache SVN repository that pertain to the different releases. The top
+level can be perused with the [SVN
+ViewCVS](http://svn.apache.org/viewcvs.cgi/) pages. The main subtrees
+pertaining to the<samp>httpd</samp>server source are:
+
+## httpd-2.2 ##
+
+To create a directory tree containing the 2.2 sources, and call
+it<samp>httpd-2.2</samp>, change your current directory to the *parent* of
+the tree and then check the 2.2 sources out as follows:
+<pre>
% cd /usr/local/apache
% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x
- httpd-2.2</source>
- </section>
+ httpd-2.2</pre>
+
+## httpd-2.4 ##
- <section><title>httpd-2.4</title>
- <p>To create a directory tree containing the 2.4 sources,
- and call it <samp>httpd-2.4</samp>, change your current directory
- to the <em>parent</em> of the tree and then check the 2.4 sources
- out as follows:</p>
- <source>
+To create a directory tree containing the 2.4 sources, and call
+it<samp>httpd-2.4</samp>, change your current directory to the *parent* of
+the tree and then check the 2.4 sources out as follows:
+<pre>
% cd /usr/local/apache
% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x
- httpd-2.4</source>
- </section>
+ httpd-2.4</pre>
- <section><title>httpd-2.5</title>
- <p>If you want to check out the bleeding edge of development, the
- httpd-2.5 development tree (slated for a release 2.6), and call it
- <samp>httpd-trunk</samp>, checkout as follows:</p>
- <source>
+## httpd-2.5 ##
+
+If you want to check out the bleeding edge of development, the httpd-2.5
+development tree (slated for a release 2.6), and call
+it<samp>httpd-trunk</samp>, checkout as follows:
+<pre>
% cd /usr/local/apache
-% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk httpd-trunk</source>
- </section>
+% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk
+httpd-trunk</pre>
+
+## httpd-site ##
- <section><title>httpd-site</title>
- <p>This subtree contains the files that live at <samp>http://httpd.apache.org/</samp>.
- The directory on the host that maps to that URL is actually a set of
- checked-out working copies of the SVN files.</p>
- <p>The SVN URL is
- <samp>https://svn.apache.org/repos/asf/httpd/site/trunk/docs</samp>.</p>
- <make_note>
- It is important that the files on the Web host not be modified
- directly. If you want or need to change one, check it out into a
- private working copy, modify <strong>that</strong>, commit the
- change into SVN, and then perform a <samp>svn update</samp> to
- bring the host directory into sync with the SVN sources.
- </make_note>
- <p>The Web site <em>directories</em> (as opposed to files) are not
- maintained in synch with the SVN files automatically. They are
- manually updated from SVN by various people as they consider
- appropriate. This is usually not an issue, unless a group of files
- are being updated according to an ongoing group discussion.</p>
- </section>
-
- <section><title>httpd-dist</title>
- <p>Like the <samp>httpd-site</samp> subtree, this one is used to
- maintain the files that comprise a website - in this case,
- <samp>http://www.apache.org/dist/httpd/</samp>. Also like the
- previous subtree, the directory on the server is a checked-out
- working copy of this subtree. However, since this is a distribution
- directory, we only have the surrounding documentation and control
- files checked into this subtree -- the actual tarballs are simply
- copied to www.apache.org.</p>
- <p>The SVN URL is
- <samp>https://svn.apache.org/repos/asf/httpd/httpd/dist</samp>.</p>
- <p>Committers will generally deal with this subtree when "rolling" a
- release. This is a series of steps taken to create a complete new
- release of the Apache httpd software. Amongst other things, the
- key to this subtree is the <samp>tools/</samp> directory, which
- contains the <samp>release.sh</samp> shell script. More information
- on the policies and procedures relating to rolling releases can be
- found on the <a href="release.html">Release Guidelines</a> page.</p>
- </section>
-</section>
-
-<section>
-<title>Setting Up Remote SVN</title>
-
-<p>A brief overview of getting started with SVN committer access can be
-found <a href="http://www.apache.org/dev/version-control.html#https-svn">
-here</a>. One key change to note is that SSH is not used anymore for
-committer access, due to the functional differences with SVN.</p>
-</section>
+This subtree contains the files that live
+at<samp>http://httpd.apache.org/</samp>. The directory on the host that
+maps to that URL is actually a set of checked-out working copies of the SVN
+files.
+
+The SVN URL
+is<samp>https://svn.apache.org/repos/asf/httpd/site/trunk/docs</samp>.
+<make_note>It is important that the files on the Web host not be modified
+directly. If you want or need to change one, check it out into a private
+working copy, modify **that** , commit the change into SVN, and then
+perform a<samp>svn update</samp>to bring the host directory into sync with
+the SVN sources.</make_note>
+The Web site *directories* (as opposed to files) are not maintained in
+synch with the SVN files automatically. They are manually updated from SVN
+by various people as they consider appropriate. This is usually not an
+issue, unless a group of files are being updated according to an ongoing
+group discussion.
+
+## httpd-dist ##
+
+Like the<samp>httpd-site</samp>subtree, this one is used to maintain the
+files that comprise a website - in this
+case,<samp>http://www.apache.org/dist/httpd/</samp>. Also like the previous
+subtree, the directory on the server is a checked-out working copy of this
+subtree. However, since this is a distribution directory, we only have the
+surrounding documentation and control files checked into this subtree --
+the actual tarballs are simply copied to www.apache.org.
+
+The SVN URL
+is<samp>https://svn.apache.org/repos/asf/httpd/httpd/dist</samp>.
+
+Committers will generally deal with this subtree when "rolling" a release.
+This is a series of steps taken to create a complete new release of the
+Apache httpd software. Amongst other things, the key to this subtree is
+the<samp>tools/</samp>directory, which contains
+the<samp>release.sh</samp>shell script. More information on the policies
+and procedures relating to rolling releases can be found on the [Release
+Guidelines](release.html) page.
+
+# Setting Up Remote SVN #
+
+A brief overview of getting started with SVN committer access can be found
+[here](http://www.apache.org/dev/version-control.html#https-svn). One key
+change to note is that SSH is not used anymore for committer access, due to
+the functional differences with SVN.
-</body>
-</document>