Bug 191537 - Improvements to the security section.

6 files changed, 560 insertions, 756 deletions

diff --git a/docs/sgml/administration.sgml b/docs/sgml/administration.sgml
index 3cd55a616..f04e2b5ce 100644
--- a/docs/sgml/administration.sgml
+++ b/docs/sgml/administration.sgml
@@ -764,155 +764,273 @@
     <note>
       <para>These instructions must, of necessity, be somewhat vague since
       Bugzilla runs on so many different platforms. If you have refinements
-      of these directions for specific platforms, please submit them to 
-      <ulink url="mailto://mozilla-webtools@mozilla.org">
-      mozilla-webtools@mozilla.org</ulink>
+      of these directions, please submit a bug to &bzg-bugs;.
       </para>
     </note>
 
-    <para>To secure your installation:
-     
-    <orderedlist>
-      <listitem>
-        <para>
-        <emphasis>There is no substitute for understanding the tools on your
-        system!</emphasis>
+    <warning>
+      <para>This is not meant to be a comprehensive list of every possible
+      security issue regarding the tools mentioned in this section. There is
+      no subsitute for reading the information written by the authors of any
+      software running on your system.
+      </para>
+    </warning>
 
-        Read 
-        <ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html">
-        The MySQL Privilege System</ulink>
-        until you can recite it from memory!</para>
-      </listitem>
+    <section id="security-networking">
+      <title>TCP/IP Ports</title>
+
+      <!-- TODO: Make this make sense (TCP/IP) -->
+      <para>TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla
+      only needs 1... 2 if you need to use features that require e-mail such
+      as bug moving or the e-mail interface from contrib. You should audit
+      your server and make sure that you aren't listening on any ports you
+      don't need to be. You may also wish to use some kind of firewall
+      software to be sure that trafic can only be recieved on ports you
+      specify.
+      </para>
+    </section>
 
-      <listitem>
-        <para>Lock down <filename>/etc/inetd.conf</filename>. Heck, disable
-        inet entirely on this box. It should only listen to port 25 for
-        Sendmail and port 80 for Apache.</para>
-      </listitem>
+    <section id="security-mysql">
+      <title>MySQL</title>
 
-      <listitem>
-        <para>Do not run Apache as 
-        <quote>nobody</quote>
+      <para>MySQL ships by default with many settings that should be changed.
+      By defaults it allows anybody to connect from localhost without a
+      password and have full administrative capabilities. It also defaults to
+      not have a root password (this is <emphasis>not</emphasis> the same as
+      the system root). Also, many installations default to running
+      <application>mysqld</application> as the system root.
+      </para>
 
-        . This will require very lax permissions in your Bugzilla
-        directories. Run it, instead, as a user with a name, set via your
-        httpd.conf file. 
-        <note>
-          <para>
-          <quote>nobody</quote>
+      <orderedlist>
+        <listitem>
+          <para>Consult the documentation that came with your system for
+          information on making <application>mysqld</application> run as an
+          unprivleged user.
+          </para>
+        </listitem>
 
-          is a real user on UNIX systems. Having a process run as user id 
-          <quote>nobody</quote>
+        <listitem>
+          <para>You should also be sure to disable the anonymous user account
+          and set a password for the root user. This is accomplished using the
+          following commands:
+          </para>
+          <programlisting>
+<prompt>bash$</prompt> mysql mysql
+<prompt>mysql&gt;</prompt> DELETE FROM user WHERE user = '';
+<prompt>mysql&gt;</prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
+<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
+          </programlisting>
+          <para>From this point forward you will need to use
+          <command>mysql -u root -p</command> and enter
+          <replaceable>new_password</replaceable> when prompted when using the
+          mysql client.
+          </para>
+        </listitem>
 
-          is absolutely no protection against system crackers versus using
-          any other user account. As a general security measure, I recommend
-          you create unique user ID's for each daemon running on your system
-          and, if possible, use "chroot" to jail that process away from the
-          rest of your system.</para>
-        </note>
-        </para>
-      </listitem>
+        <listitem>
+          <para>If you run MySQL on the same machine as your httpd server, you
+          should consider disabling networking from within MySQL by adding
+          the following to your <filename>/etc/my.conf</filename>:
+          </para>
+          <programlisting>
+[myslqd]
+# Prevent network access to MySQL.
+skip-networking
+          </programlisting>
+        </listitem>
 
-      <listitem>
-        <para>Ensure you have adequate access controls for the
-        <filename>$BUGZILLA_HOME/data/</filename> directory, as well as the
-        <filename>$BUGZILLA_HOME/localconfig</filename> file.
-        The localconfig file stores your "bugs" database account password. 
-        In addition, some
-        files under <filename>$BUGZILLA_HOME/data/</filename> store sensitive
-        information.
-        </para>
+        <listitem>
+          <para>You may also consider running MySQL, or even all of Bugzilla
+          in a chroot jail; however, instructions for doing that are beyond
+          the scope of this document.
+          </para>
+        </listitem>
 
-        <para>Also, beware that some text editors create backup files in the
-        current working directory so you need to also secure files like
-        <filename>localconfig~</filename>.
-        </para>
+      </orderedlist>
 
-        <note>
-          <para>Simply blocking <computeroutput>.*localconfig.*</computeroutput>
-          won't work because the QuickSearch feature requires the web browser
-          to be able to retrieve <filename>localconfig.js</filename> and
-          others may be introduced in the future (see 
-          <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">bug
-          186383</ulink> for more information.
-          </para>
-        </note>
+    </section>
 
-        <para>Bugzilla provides default <filename>.htaccess</filename> files
-        to protect the most common Apache installations. However, you should
-        verify these are adequate according to the site-wide security policy
-        of your web server, and ensure that the <filename>.htaccess</filename>
-        files are allowed to <quote>override</quote> default permissions set
-        in your Apache configuration files. Covering Apache security is beyond
-        the scope of this Guide; please consult the Apache documentation for
-        details.
+    <section id="security-daemon">
+      <title>Daemon Accounts</title>
+
+      <para>Many daemons, such as Apache's httpd and MySQL's mysqld default to
+      running as either <quote>root</quote> or <quote>nobody</quote>. Running
+      as <quote>root</quote> introduces obvious security problems, but the
+      problems introduced by running everything as <quote>nobody</quote> may
+      not be so obvious. Basically, if you're running every daemon as
+      <quote>nobody</quote> and one of them gets comprimised, they all get
+      comprimised. For this reason it is recommended that you create a user
+      account for each daemon.
+      </para>
+
+      <note>
+        <para>You will need to set the <varname>webservergroup</varname> to
+        the group you created for your webserver to run as in
+        <filename>localconfig</filename>. This will allow
+        <command>./checksetup.pl</command> to better adjust the file
+        permissions on your Bugzilla install so as to not require making
+        anything world-writable.
         </para>
+      </note>
 
-        <para>If you are using a web server that does not support the
-        <filename>.htaccess</filename> control method, 
-        <emphasis>you are at risk!</emphasis>
+    </section>
 
-        After installing, check to see if you can view the file
-        <filename>localconfig</filename> in your web browser (e.g.: 
-        <ulink url="http://bugzilla.mozilla.org/localconfig">
-        http://bugzilla.mozilla.org/localconfig</ulink>
+    <section id="security-access">
+      <title>Web Server Access Controls</title>
+
+      <para>There are many files that are placed in the Bugzilla directory
+      area that should not be accessable from the web. Because of the way
+      Bugzilla is currently layed out, the list of what should and should
+      not be accessible is rather complicated. A new installation method
+      is currently in the works which should solve this by allowing files
+      that shouldn't be accessible from the web to be placed in directory
+      outside the webroot. See
+      <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=44659">bug
+      44659</ulink> for more information.
+      </para>
 
-        ). If you can read the contents of this file, your web server has
-        not secured your bugzilla directory properly and you must fix this
-        problem before deploying Bugzilla. If, however, it gives you a
-        "Forbidden" error, then it probably respects the .htaccess
-        conventions and you are good to go.</para>
-      </listitem>
+      <itemizedlist spacing="compact">
+        <listitem>
+          <para>In the main Bugzilla directory, you should:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>Block:
+              <simplelist type="inline">
+                <member><filename>*.pl</filename></member>
+                <member><filename>*localconfig*</filename></member>
+                <member><filename>runtests.sh</filename></member>
+              </simplelist>
+              </para>
+            </listitem>
+            <listitem>
+              <para>But allow:
+              <simplelist type="inline">
+                <member><filename>localconfig.js</filename></member>
+                <member><filename>localconfig.rdf</filename></member>
+              </simplelist>
+              </para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
 
-      <listitem>
-        <para>When you run checksetup.pl, the script will attempt to modify
-        various permissions on files which Bugzilla uses. If you do not have
-        a webservergroup set in the <filename>localconfig</filename> file,
-        then Bugzilla will have to make certain files world readable and/or
-        writable. 
-        <emphasis>THIS IS INSECURE!</emphasis>
+        <listitem>
+          <para>In <filename class="directory">data</filename>:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>Block everything</para>
+            </listitem>
+            <listitem>
+              <para>But allow:
+              <simplelist type="inline">
+                <member><filename>duplicates.rdf</filename></member>
+              </simplelist>
+              </para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
 
-        . This means that anyone who can get access to your system can do
-        whatever they want to your Bugzilla installation.</para>
+        <listitem>
+          <para>In <filename class="directory">data/webdot</filename>:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>If you use a remote webdot server:</para>
+              <itemizedlist spacing="compact">
+                <listitem>
+                  <para>Block everything</para>
+                </listitem>
+                <listitem>
+                  <para>But allow
+                  <simplelist type="inline">
+                    <member><filename>*.dot</filename></member>
+                  </simplelist>
+                  only for the remote webdot server</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para>Otherwise, if you use a local GraphViz:</para>
+              <itemizedlist spacing="compact">
+                <listitem>
+                  <para>Block everything</para>
+                </listitem>
+                <listitem>
+                  <para>But allow:
+                  <simplelist type="inline">
+                    <member><filename>*.png</filename></member>
+                    <member><filename>*.gif</filename></member>
+                    <member><filename>*.jpg</filename></member>
+                    <member><filename>*.map</filename></member>
+                  </simplelist>
+                  </para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para>And if you don't use any dot:</para>
+              <itemizedlist spacing="compact">
+                <listitem>
+                  <para>Block everything</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </itemizedlist>
+        </listitem>
 
-        <note>
-          <para>This also means that if your webserver runs all cgi scripts
-          as the same user/group, anyone on the system who can run cgi
-          scripts will be able to take control of your Bugzilla
-          installation.</para>
-        </note>
+        <listitem>
+          <para>In <filename class="directory">Bugzilla</filename>:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>Block everything</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
 
-        <para>On Apache, you can use <filename>.htaccess</filename> files to
-        protect access to these directories, as outlined in Bugs 
-        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=57161">
-        57161</ulink> and
-        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">
-        186383</ulink>
-
-        for the <filename>localconfig</filename> file, and 
-        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=65572">Bug
-        65572</ulink>
-
-        for adequate protection in your <filename>data/</filename> directory.
-        Also, don't forget about the <filename>template/</filename> and
-        <filename>Bugzilla/</filename> directories and to allow access to the
-        <filename>data/webdot</filename> directory for the
-        <computeroutput>192.20.225.10</computeroutput> IP address if you are
-        using webdot from research.att.com.  The easiest way to
-        accomplish this is to set <function>$create_htaccess</function> to 1
-        in <filename>localconfig</filename>.  However, the information below
-        is provided for those that want to know exactly what is created.
+        <listitem>
+          <para>In <filename class="directory">template</filename>:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>Block everything</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </itemizedlist>
+
+      <tip>
+        <para>Bugzilla ships with the ability to generate
+        <filename>.htaccess</filename> files instructing
+        <glossterm linkend="gloss-apache">Apache</glossterm> which files
+        should and should not be accessible. For more information, see
+        <xref linkend="http-apache"/>.
         </para>
+      </tip>
 
-        <para>FIX ME BEFORE RELEASE!!!!!
-        Note the instructions which follow are Apache-specific. If you
-        use IIS, Netscape, or other non-Apache web servers, please consult
-        your system documentation for how to secure these files from being
-        transmitted to curious users.</para>
+      <para>You should test to make sure that the files mentioned above are
+      not accessible from the Internet, especially your
+      <filename>localconfig</filename> file which contains your database
+      password. To test, simply point your web browser at the file; for
+      example, to test mozilla.org's installation, we'd try to access
+      <ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should
+      get a <errorcode>403</errorcode> <errorname>Forbidden</errorname>
+      error.
+      </para>
+
+      <caution>
+        <para>Not following the instructions in this section, including
+        testing, may result in sensitive information being globally
+        accessible.
+        </para>
+      </caution>
+
+      <tip>
+        <para>You should check <xref linkend="http"/> to see if instructions
+        have been included for your web server. You should also compare those
+        instructions with this list to make sure everything is properly
+        accounted for.
+        </para>
+      </tip>
+
+    </section>
 
-      </listitem>
-    </orderedlist>
-    </para>
   </section>
 
   <section id="cust-templates">
diff --git a/docs/sgml/glossary.sgml b/docs/sgml/glossary.sgml
index 191b3fb39..15b7fe948 100644
--- a/docs/sgml/glossary.sgml
+++ b/docs/sgml/glossary.sgml
@@ -242,17 +242,24 @@
       </glossdef>
     </glossentry>
 
-    <glossentry>
-      <glossterm>mysqld</glossterm>
+    <glossentry id="gloss-mysql">
+      <glossterm>MySQL</glossterm>
 
       <glossdef>
-        <para>mysqld is the name of the 
-        <glossterm>daemon</glossterm>
-
-        for the MySQL database. In general, it is invoked automatically
-        through the use of the System V init scripts on GNU/Linux and
-        AT&amp;T System V-based systems, such as Solaris and HP/UX, or
-        through the RC scripts on BSD-based systems.</para>
+        <para>MySQL is currently the required
+        <glossterm linkend="gloss-rdbms">RDBMS</glossterm> for Bugzilla. MySQL
+        can be downloaded from <ulink url="http://www.mysql.com"/>. While you
+        should familiarize yourself with all of the documentation, some high
+        points are:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para><ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html">MySQL
+            Privilege System</ulink> - Much more detailed information about
+            the suggestions in <xref linkend="security-mysql"/>.
+            </para>
+          </listitem>
+        </itemizedlist>
       </glossdef>
     </glossentry>
   </glossdiv>
@@ -311,6 +318,21 @@
     </glossentry>
   </glossdiv>
 
+  <glossdiv id="gloss-r">
+    <title>R</title>
+
+    <glossentry id="gloss-rdbms">
+      <glossterm>Relational DataBase Managment System</glossterm>
+      <acronym>RDBMS</acronym>
+
+      <glossdef>
+        <para>A relational database management system is a database system
+        that stores information in tables that are related to each other.
+        </para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
   <glossdiv id="gloss-s">
     <title>S</title>
 
diff --git a/docs/sgml/installation.sgml b/docs/sgml/installation.sgml
index 286706126..da32ad5f9 100644
--- a/docs/sgml/installation.sgml
+++ b/docs/sgml/installation.sgml
@@ -764,152 +764,6 @@ perl -pi -e 's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm s
     </section>
 
     <section>
-      <title>Securing MySQL</title>
-
-      <para>If you followed the installation instructions for setting up your
-      "bugs" and "root" user in MySQL, much of this should not apply to you.
-      If you are upgrading an existing installation of Bugzilla, you should
-      pay close attention to this section.</para>
-
-      <para>Most MySQL installs have "interesting" default security
-      parameters: 
-      <simplelist>
-        <member>mysqld defaults to running as root</member>
-
-        <member>it defaults to allowing external network connections</member>
-
-        <member>it has a known port number, and is easy to detect</member>
-
-        <member>it defaults to no passwords whatsoever</member>
-
-        <member>it defaults to allowing "File_Priv"</member>
-      </simplelist>
-      </para>
-
-      <para>This means anyone from anywhere on the Internet can not only drop
-      the database with one SQL command, and they can write as root to the
-      system.</para>
-
-      <para>To see your permissions do: 
-      <simplelist>
-        <member>
-          <computeroutput>
-            <prompt>bash#</prompt>
-
-            <command>mysql -u root -p</command>
-          </computeroutput>
-        </member>
-
-        <member>
-          <computeroutput>
-            <prompt>mysql&gt;</prompt>
-
-            <command>use mysql;</command>
-          </computeroutput>
-        </member>
-
-        <member>
-          <computeroutput>
-            <prompt>mysql&gt;</prompt>
-
-            <command>show tables;</command>
-          </computeroutput>
-        </member>
-
-        <member>
-          <computeroutput>
-            <prompt>mysql&gt;</prompt>
-
-            <command>select * from user;</command>
-          </computeroutput>
-        </member>
-
-        <member>
-          <computeroutput>
-            <prompt>mysql&gt;</prompt>
-
-            <command>select * from db;</command>
-          </computeroutput>
-        </member>
-      </simplelist>
-      </para>
-
-      <para>To fix the gaping holes: 
-      <simplelist>
-        <member>DELETE FROM user WHERE User='';</member>
-
-        <member>UPDATE user SET Password=PASSWORD('new_password') WHERE
-        user='root';</member>
-
-        <member>FLUSH PRIVILEGES;</member>
-      </simplelist>
-      </para>
-
-      <para>If you're not running "mit-pthreads" you can use: 
-      <simplelist>
-        <member>GRANT USAGE ON *.* TO bugs@localhost;</member>
-
-        <member>GRANT ALL ON bugs.* TO bugs@localhost;</member>
-
-        <member>REVOKE DROP ON bugs.* FROM bugs@localhost;</member>
-
-        <member>FLUSH PRIVILEGES;</member>
-      </simplelist>
-      </para>
-
-      <para>With "mit-pthreads" you'll need to modify the "globals.pl"
-      Mysql-&gt;Connect line to specify a specific host name instead of
-      "localhost", and accept external connections: 
-      <simplelist>
-        <member>GRANT USAGE ON *.* TO bugs@bounce.hop.com;</member>
-
-        <member>GRANT ALL ON bugs.* TO bugs@bounce.hop.com;</member>
-
-        <member>REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com;</member>
-
-        <member>FLUSH PRIVILEGES;</member>
-      </simplelist>
-      </para>
-
-      <para>Consider also: 
-      <orderedlist>
-        <listitem>
-          <para>Turning off external networking with "--skip-networking",
-          unless you have "mit-pthreads", in which case you can't. Without
-          networking, MySQL connects with a Unix domain socket.</para>
-        </listitem>
-
-        <listitem>
-          <para>using the --user= option to mysqld to run it as an
-          unprivileged user.</para>
-        </listitem>
-
-        <listitem>
-          <para>running MySQL in a chroot jail</para>
-        </listitem>
-
-        <listitem>
-          <para>running the httpd in a chroot jail</para>
-        </listitem>
-
-        <listitem>
-          <para>making sure the MySQL passwords are different from the OS
-          passwords (MySQL "root" has nothing to do with system
-          "root").</para>
-        </listitem>
-
-        <listitem>
-          <para>running MySQL on a separate untrusted machine</para>
-        </listitem>
-
-        <listitem>
-          <para>making backups ;-)</para>
-        </listitem>
-      </orderedlist>
-      </para>
-    </section>
-    
-    <section>
       <title>Configuring Bugzilla</title>
       <para>
       You should run through the parameters on the Edit Parameters page
@@ -1160,85 +1014,6 @@ bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; chars
       </note>
     </section>    
     
-    <section id="htaccess" xreflabel=".htaccess files and security">
-      <title>
-      <filename>.htaccess</filename>
-      files and security</title>
-
-      <para>To enhance the security of your Bugzilla installation, Bugzilla's
-      <filename>checksetup.pl</filename> script will generate 
-      <glossterm>
-        <filename>.htaccess</filename>
-      </glossterm>
-
-      files which the Apache webserver can use to restrict access to the
-      bugzilla data files. 
-      These .htaccess files will not work with Apache 1.2.x - but this
-      has security holes, so you shouldn't be using it anyway. 
-      <note>
-        <para>If you are using an alternate provider of 
-        <productname>webdot</productname>
-
-        services for graphing (as described when viewing 
-        <filename>editparams.cgi</filename>
-
-        in your web browser), you will need to change the ip address in 
-        <filename>data/webdot/.htaccess</filename>
-
-        to the ip address of the webdot server that you are using.</para>
-      </note>
-      </para>
-
-      <para>The default .htaccess file may not provide adequate access
-      restrictions, depending on your web server configuration. Be sure to
-      check the &lt;Directory&gt; entries for your Bugzilla directory so that
-      the 
-      <filename>.htaccess</filename>
-
-      file is allowed to override web server defaults. For instance, let's
-      assume your installation of Bugzilla is installed to 
-      <filename>/usr/local/bugzilla</filename>
-
-      . You should have this &lt;Directory&gt; entry in your 
-      <filename>httpd.conf</filename>
-
-      file:</para>
-
-      <para>
-      
-<programlisting><![CDATA[
-<Directory /usr/local/bugzilla/>
-  Options +FollowSymLinks +Indexes +Includes +ExecCGI
-  AllowOverride All
-</Directory>
-]]></programlisting>
-
-      </para>
-
-      <para>The important part above is 
-      <quote>AllowOverride All</quote>
-
-      . Without that, the 
-      <filename>.htaccess</filename>
-
-      file created by 
-      <filename>checksetup.pl</filename>
-
-      will not have sufficient permissions to protect your Bugzilla
-      installation.</para>
-
-      <para>If you are using Internet Information Server (IIS) or another 
-      web server which does not observe 
-      <filename>.htaccess</filename>
-      conventions, you can disable their creation by editing 
-      <filename>localconfig</filename>
-      and setting the 
-      <varname>$create_htaccess</varname>
-      variable to 
-      <parameter>0</parameter>.
-      </para>
-    </section>
-
     <section id="directoryindex" xreflabel="Modifying the Apache
     DirectoryIndex parameter to use index.cgi">
       <title>
@@ -1358,11 +1133,11 @@ C:\perl&gt; <command>ppm &lt;module name&gt;</command>
           </para>
         </note>
 
-        <note>
+        <tip>
           <para>A complete list of modules that can be installed using ppm can
           be found at <ulink url="http://www.activestate.com/PPMPackages/5.6plus">http://www.activestate.com/PPMPackages/5.6plus</ulink>.
           </para>
-        </note>
+        </tip>
       </section>
 
       <section id="win32-code-changes">
@@ -1400,19 +1175,6 @@ my $webservergid = '8'
           </programlisting>
         </section>
 
-        <section id="win32-code-mail">
-          <title>Making mail work</title>
-
-          <para>The easiest way to get mail working is to use the mail patches
-          on <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=124174">bug
-          124174</ulink>. With any luck, this patch will receive the required
-          reviews and integrated into the main Bugzilla distribution very soon.
-          Until that happens, there's at least one report of this patch working
-          well on Windows.
-          </para>
-
-        </section>
-
         <section>
           <title>System Calls</title>
 
@@ -1459,7 +1221,7 @@ system("C:\\perl\\bin\\perl", "$webdotbase","-Tpng","-o","$pngfilename","$filena
         <para>As is the case on Unix based systems, any web server should be
         able to handle Bugzilla; however, the Bugzilla Team still recommends
         Apache whenever asked. No matter what web server you choose, be sure
-        to pay attention to the security notes in <xref linkend="security"/>.
+        to pay attention to the security notes in <xref linkend="security-access"/>.
         More information on configuring specific web servers can be found in
         <xref linkend="http"/>.
         </para>
@@ -1480,7 +1242,7 @@ system("C:\\perl\\bin\\perl", "$webdotbase","-Tpng","-o","$pngfilename","$filena
     <section id="os-macosx">
       <title><productname>Mac OS X</productname></title>
 
-      <!-- XXX - Clean me up... (Mac OS X) -->
+      <!-- TODO: Clean me up... (Mac OS X) -->
       <para>There are a lot of common libraries and utilities out there that
       Apple did not include with Mac OS X, but which run perfectly well on it.
       The GD library, which Bugzilla needs to do bug graphs, is one of
@@ -1559,7 +1321,7 @@ system("C:\\perl\\bin\\perl", "$webdotbase","-Tpng","-o","$pngfilename","$filena
     that can be configured to run <glossterm linkend="gloss-cgi">CGI</glossterm> scripts
     should be able to handle Bugzilla. No matter what web server you choose, but
     especially if you choose something other than Apache, you should be sure to read
-    <xref linkend="security"/>.
+    <xref linkend="security-access"/>.
     </para>
 
     <para>The plan for this section is to eventually document the specifics of how to lock
@@ -1696,7 +1458,7 @@ deny from all
 
       <para>Also, and this can't be stressed enough, make sure that files such as
       <filename>localconfig</filename> and your <filename class="directory">data</filename>
-      directory are secured as described in <xref linkend="security"/>.
+      directory are secured as described in <xref linkend="security-access"/>.
       </para>
 
     </section>
diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index 3cd55a616..f04e2b5ce 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -764,155 +764,273 @@
     <note>
       <para>These instructions must, of necessity, be somewhat vague since
       Bugzilla runs on so many different platforms. If you have refinements
-      of these directions for specific platforms, please submit them to 
-      <ulink url="mailto://mozilla-webtools@mozilla.org">
-      mozilla-webtools@mozilla.org</ulink>
+      of these directions, please submit a bug to &bzg-bugs;.
       </para>
     </note>
 
-    <para>To secure your installation:
-     
-    <orderedlist>
-      <listitem>
-        <para>
-        <emphasis>There is no substitute for understanding the tools on your
-        system!</emphasis>
+    <warning>
+      <para>This is not meant to be a comprehensive list of every possible
+      security issue regarding the tools mentioned in this section. There is
+      no subsitute for reading the information written by the authors of any
+      software running on your system.
+      </para>
+    </warning>
 
-        Read 
-        <ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html">
-        The MySQL Privilege System</ulink>
-        until you can recite it from memory!</para>
-      </listitem>
+    <section id="security-networking">
+      <title>TCP/IP Ports</title>
+
+      <!-- TODO: Make this make sense (TCP/IP) -->
+      <para>TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla
+      only needs 1... 2 if you need to use features that require e-mail such
+      as bug moving or the e-mail interface from contrib. You should audit
+      your server and make sure that you aren't listening on any ports you
+      don't need to be. You may also wish to use some kind of firewall
+      software to be sure that trafic can only be recieved on ports you
+      specify.
+      </para>
+    </section>
 
-      <listitem>
-        <para>Lock down <filename>/etc/inetd.conf</filename>. Heck, disable
-        inet entirely on this box. It should only listen to port 25 for
-        Sendmail and port 80 for Apache.</para>
-      </listitem>
+    <section id="security-mysql">
+      <title>MySQL</title>
 
-      <listitem>
-        <para>Do not run Apache as 
-        <quote>nobody</quote>
+      <para>MySQL ships by default with many settings that should be changed.
+      By defaults it allows anybody to connect from localhost without a
+      password and have full administrative capabilities. It also defaults to
+      not have a root password (this is <emphasis>not</emphasis> the same as
+      the system root). Also, many installations default to running
+      <application>mysqld</application> as the system root.
+      </para>
 
-        . This will require very lax permissions in your Bugzilla
-        directories. Run it, instead, as a user with a name, set via your
-        httpd.conf file. 
-        <note>
-          <para>
-          <quote>nobody</quote>
+      <orderedlist>
+        <listitem>
+          <para>Consult the documentation that came with your system for
+          information on making <application>mysqld</application> run as an
+          unprivleged user.
+          </para>
+        </listitem>
 
-          is a real user on UNIX systems. Having a process run as user id 
-          <quote>nobody</quote>
+        <listitem>
+          <para>You should also be sure to disable the anonymous user account
+          and set a password for the root user. This is accomplished using the
+          following commands:
+          </para>
+          <programlisting>
+<prompt>bash$</prompt> mysql mysql
+<prompt>mysql&gt;</prompt> DELETE FROM user WHERE user = '';
+<prompt>mysql&gt;</prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
+<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
+          </programlisting>
+          <para>From this point forward you will need to use
+          <command>mysql -u root -p</command> and enter
+          <replaceable>new_password</replaceable> when prompted when using the
+          mysql client.
+          </para>
+        </listitem>
 
-          is absolutely no protection against system crackers versus using
-          any other user account. As a general security measure, I recommend
-          you create unique user ID's for each daemon running on your system
-          and, if possible, use "chroot" to jail that process away from the
-          rest of your system.</para>
-        </note>
-        </para>
-      </listitem>
+        <listitem>
+          <para>If you run MySQL on the same machine as your httpd server, you
+          should consider disabling networking from within MySQL by adding
+          the following to your <filename>/etc/my.conf</filename>:
+          </para>
+          <programlisting>
+[myslqd]
+# Prevent network access to MySQL.
+skip-networking
+          </programlisting>
+        </listitem>
 
-      <listitem>
-        <para>Ensure you have adequate access controls for the
-        <filename>$BUGZILLA_HOME/data/</filename> directory, as well as the
-        <filename>$BUGZILLA_HOME/localconfig</filename> file.
-        The localconfig file stores your "bugs" database account password. 
-        In addition, some
-        files under <filename>$BUGZILLA_HOME/data/</filename> store sensitive
-        information.
-        </para>
+        <listitem>
+          <para>You may also consider running MySQL, or even all of Bugzilla
+          in a chroot jail; however, instructions for doing that are beyond
+          the scope of this document.
+          </para>
+        </listitem>
 
-        <para>Also, beware that some text editors create backup files in the
-        current working directory so you need to also secure files like
-        <filename>localconfig~</filename>.
-        </para>
+      </orderedlist>
 
-        <note>
-          <para>Simply blocking <computeroutput>.*localconfig.*</computeroutput>
-          won't work because the QuickSearch feature requires the web browser
-          to be able to retrieve <filename>localconfig.js</filename> and
-          others may be introduced in the future (see 
-          <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">bug
-          186383</ulink> for more information.
-          </para>
-        </note>
+    </section>
 
-        <para>Bugzilla provides default <filename>.htaccess</filename> files
-        to protect the most common Apache installations. However, you should
-        verify these are adequate according to the site-wide security policy
-        of your web server, and ensure that the <filename>.htaccess</filename>
-        files are allowed to <quote>override</quote> default permissions set
-        in your Apache configuration files. Covering Apache security is beyond
-        the scope of this Guide; please consult the Apache documentation for
-        details.
+    <section id="security-daemon">
+      <title>Daemon Accounts</title>
+
+      <para>Many daemons, such as Apache's httpd and MySQL's mysqld default to
+      running as either <quote>root</quote> or <quote>nobody</quote>. Running
+      as <quote>root</quote> introduces obvious security problems, but the
+      problems introduced by running everything as <quote>nobody</quote> may
+      not be so obvious. Basically, if you're running every daemon as
+      <quote>nobody</quote> and one of them gets comprimised, they all get
+      comprimised. For this reason it is recommended that you create a user
+      account for each daemon.
+      </para>
+
+      <note>
+        <para>You will need to set the <varname>webservergroup</varname> to
+        the group you created for your webserver to run as in
+        <filename>localconfig</filename>. This will allow
+        <command>./checksetup.pl</command> to better adjust the file
+        permissions on your Bugzilla install so as to not require making
+        anything world-writable.
         </para>
+      </note>
 
-        <para>If you are using a web server that does not support the
-        <filename>.htaccess</filename> control method, 
-        <emphasis>you are at risk!</emphasis>
+    </section>
 
-        After installing, check to see if you can view the file
-        <filename>localconfig</filename> in your web browser (e.g.: 
-        <ulink url="http://bugzilla.mozilla.org/localconfig">
-        http://bugzilla.mozilla.org/localconfig</ulink>
+    <section id="security-access">
+      <title>Web Server Access Controls</title>
+
+      <para>There are many files that are placed in the Bugzilla directory
+      area that should not be accessable from the web. Because of the way
+      Bugzilla is currently layed out, the list of what should and should
+      not be accessible is rather complicated. A new installation method
+      is currently in the works which should solve this by allowing files
+      that shouldn't be accessible from the web to be placed in directory
+      outside the webroot. See
+      <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=44659">bug
+      44659</ulink> for more information.
+      </para>
 
-        ). If you can read the contents of this file, your web server has
-        not secured your bugzilla directory properly and you must fix this
-        problem before deploying Bugzilla. If, however, it gives you a
-        "Forbidden" error, then it probably respects the .htaccess
-        conventions and you are good to go.</para>
-      </listitem>
+      <itemizedlist spacing="compact">
+        <listitem>
+          <para>In the main Bugzilla directory, you should:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>Block:
+              <simplelist type="inline">
+                <member><filename>*.pl</filename></member>
+                <member><filename>*localconfig*</filename></member>
+                <member><filename>runtests.sh</filename></member>
+              </simplelist>
+              </para>
+            </listitem>
+            <listitem>
+              <para>But allow:
+              <simplelist type="inline">
+                <member><filename>localconfig.js</filename></member>
+                <member><filename>localconfig.rdf</filename></member>
+              </simplelist>
+              </para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
 
-      <listitem>
-        <para>When you run checksetup.pl, the script will attempt to modify
-        various permissions on files which Bugzilla uses. If you do not have
-        a webservergroup set in the <filename>localconfig</filename> file,
-        then Bugzilla will have to make certain files world readable and/or
-        writable. 
-        <emphasis>THIS IS INSECURE!</emphasis>
+        <listitem>
+          <para>In <filename class="directory">data</filename>:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>Block everything</para>
+            </listitem>
+            <listitem>
+              <para>But allow:
+              <simplelist type="inline">
+                <member><filename>duplicates.rdf</filename></member>
+              </simplelist>
+              </para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
 
-        . This means that anyone who can get access to your system can do
-        whatever they want to your Bugzilla installation.</para>
+        <listitem>
+          <para>In <filename class="directory">data/webdot</filename>:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>If you use a remote webdot server:</para>
+              <itemizedlist spacing="compact">
+                <listitem>
+                  <para>Block everything</para>
+                </listitem>
+                <listitem>
+                  <para>But allow
+                  <simplelist type="inline">
+                    <member><filename>*.dot</filename></member>
+                  </simplelist>
+                  only for the remote webdot server</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para>Otherwise, if you use a local GraphViz:</para>
+              <itemizedlist spacing="compact">
+                <listitem>
+                  <para>Block everything</para>
+                </listitem>
+                <listitem>
+                  <para>But allow:
+                  <simplelist type="inline">
+                    <member><filename>*.png</filename></member>
+                    <member><filename>*.gif</filename></member>
+                    <member><filename>*.jpg</filename></member>
+                    <member><filename>*.map</filename></member>
+                  </simplelist>
+                  </para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para>And if you don't use any dot:</para>
+              <itemizedlist spacing="compact">
+                <listitem>
+                  <para>Block everything</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </itemizedlist>
+        </listitem>
 
-        <note>
-          <para>This also means that if your webserver runs all cgi scripts
-          as the same user/group, anyone on the system who can run cgi
-          scripts will be able to take control of your Bugzilla
-          installation.</para>
-        </note>
+        <listitem>
+          <para>In <filename class="directory">Bugzilla</filename>:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>Block everything</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
 
-        <para>On Apache, you can use <filename>.htaccess</filename> files to
-        protect access to these directories, as outlined in Bugs 
-        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=57161">
-        57161</ulink> and
-        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">
-        186383</ulink>
-
-        for the <filename>localconfig</filename> file, and 
-        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=65572">Bug
-        65572</ulink>
-
-        for adequate protection in your <filename>data/</filename> directory.
-        Also, don't forget about the <filename>template/</filename> and
-        <filename>Bugzilla/</filename> directories and to allow access to the
-        <filename>data/webdot</filename> directory for the
-        <computeroutput>192.20.225.10</computeroutput> IP address if you are
-        using webdot from research.att.com.  The easiest way to
-        accomplish this is to set <function>$create_htaccess</function> to 1
-        in <filename>localconfig</filename>.  However, the information below
-        is provided for those that want to know exactly what is created.
+        <listitem>
+          <para>In <filename class="directory">template</filename>:</para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>Block everything</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </itemizedlist>
+
+      <tip>
+        <para>Bugzilla ships with the ability to generate
+        <filename>.htaccess</filename> files instructing
+        <glossterm linkend="gloss-apache">Apache</glossterm> which files
+        should and should not be accessible. For more information, see
+        <xref linkend="http-apache"/>.
         </para>
+      </tip>
 
-        <para>FIX ME BEFORE RELEASE!!!!!
-        Note the instructions which follow are Apache-specific. If you
-        use IIS, Netscape, or other non-Apache web servers, please consult
-        your system documentation for how to secure these files from being
-        transmitted to curious users.</para>
+      <para>You should test to make sure that the files mentioned above are
+      not accessible from the Internet, especially your
+      <filename>localconfig</filename> file which contains your database
+      password. To test, simply point your web browser at the file; for
+      example, to test mozilla.org's installation, we'd try to access
+      <ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should
+      get a <errorcode>403</errorcode> <errorname>Forbidden</errorname>
+      error.
+      </para>
+
+      <caution>
+        <para>Not following the instructions in this section, including
+        testing, may result in sensitive information being globally
+        accessible.
+        </para>
+      </caution>
+
+      <tip>
+        <para>You should check <xref linkend="http"/> to see if instructions
+        have been included for your web server. You should also compare those
+        instructions with this list to make sure everything is properly
+        accounted for.
+        </para>
+      </tip>
+
+    </section>
 
-      </listitem>
-    </orderedlist>
-    </para>
   </section>
 
   <section id="cust-templates">
diff --git a/docs/xml/glossary.xml b/docs/xml/glossary.xml
index 191b3fb39..15b7fe948 100644
--- a/docs/xml/glossary.xml
+++ b/docs/xml/glossary.xml
@@ -242,17 +242,24 @@
       </glossdef>
     </glossentry>
 
-    <glossentry>
-      <glossterm>mysqld</glossterm>
+    <glossentry id="gloss-mysql">
+      <glossterm>MySQL</glossterm>
 
       <glossdef>
-        <para>mysqld is the name of the 
-        <glossterm>daemon</glossterm>
-
-        for the MySQL database. In general, it is invoked automatically
-        through the use of the System V init scripts on GNU/Linux and
-        AT&amp;T System V-based systems, such as Solaris and HP/UX, or
-        through the RC scripts on BSD-based systems.</para>
+        <para>MySQL is currently the required
+        <glossterm linkend="gloss-rdbms">RDBMS</glossterm> for Bugzilla. MySQL
+        can be downloaded from <ulink url="http://www.mysql.com"/>. While you
+        should familiarize yourself with all of the documentation, some high
+        points are:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para><ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html">MySQL
+            Privilege System</ulink> - Much more detailed information about
+            the suggestions in <xref linkend="security-mysql"/>.
+            </para>
+          </listitem>
+        </itemizedlist>
       </glossdef>
     </glossentry>
   </glossdiv>
@@ -311,6 +318,21 @@
     </glossentry>
   </glossdiv>
 
+  <glossdiv id="gloss-r">
+    <title>R</title>
+
+    <glossentry id="gloss-rdbms">
+      <glossterm>Relational DataBase Managment System</glossterm>
+      <acronym>RDBMS</acronym>
+
+      <glossdef>
+        <para>A relational database management system is a database system
+        that stores information in tables that are related to each other.
+        </para>
+      </glossdef>
+    </glossentry>
+  </glossdiv>
+
   <glossdiv id="gloss-s">
     <title>S</title>
 
diff --git a/docs/xml/installation.xml b/docs/xml/installation.xml
index 286706126..da32ad5f9 100644
--- a/docs/xml/installation.xml
+++ b/docs/xml/installation.xml
@@ -764,152 +764,6 @@ perl -pi -e 's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm s
     </section>
 
     <section>
-      <title>Securing MySQL</title>
-
-      <para>If you followed the installation instructions for setting up your
-      "bugs" and "root" user in MySQL, much of this should not apply to you.
-      If you are upgrading an existing installation of Bugzilla, you should
-      pay close attention to this section.</para>
-
-      <para>Most MySQL installs have "interesting" default security
-      parameters: 
-      <simplelist>
-        <member>mysqld defaults to running as root</member>
-
-        <member>it defaults to allowing external network connections</member>
-
-        <member>it has a known port number, and is easy to detect</member>
-
-        <member>it defaults to no passwords whatsoever</member>
-
-        <member>it defaults to allowing "File_Priv"</member>
-      </simplelist>
-      </para>
-
-      <para>This means anyone from anywhere on the Internet can not only drop
-      the database with one SQL command, and they can write as root to the
-      system.</para>
-
-      <para>To see your permissions do: 
-      <simplelist>
-        <member>
-          <computeroutput>
-            <prompt>bash#</prompt>
-
-            <command>mysql -u root -p</command>
-          </computeroutput>
-        </member>
-
-        <member>
-          <computeroutput>
-            <prompt>mysql&gt;</prompt>
-
-            <command>use mysql;</command>
-          </computeroutput>
-        </member>
-
-        <member>
-          <computeroutput>
-            <prompt>mysql&gt;</prompt>
-
-            <command>show tables;</command>
-          </computeroutput>
-        </member>
-
-        <member>
-          <computeroutput>
-            <prompt>mysql&gt;</prompt>
-
-            <command>select * from user;</command>
-          </computeroutput>
-        </member>
-
-        <member>
-          <computeroutput>
-            <prompt>mysql&gt;</prompt>
-
-            <command>select * from db;</command>
-          </computeroutput>
-        </member>
-      </simplelist>
-      </para>
-
-      <para>To fix the gaping holes: 
-      <simplelist>
-        <member>DELETE FROM user WHERE User='';</member>
-
-        <member>UPDATE user SET Password=PASSWORD('new_password') WHERE
-        user='root';</member>
-
-        <member>FLUSH PRIVILEGES;</member>
-      </simplelist>
-      </para>
-
-      <para>If you're not running "mit-pthreads" you can use: 
-      <simplelist>
-        <member>GRANT USAGE ON *.* TO bugs@localhost;</member>
-
-        <member>GRANT ALL ON bugs.* TO bugs@localhost;</member>
-
-        <member>REVOKE DROP ON bugs.* FROM bugs@localhost;</member>
-
-        <member>FLUSH PRIVILEGES;</member>
-      </simplelist>
-      </para>
-
-      <para>With "mit-pthreads" you'll need to modify the "globals.pl"
-      Mysql-&gt;Connect line to specify a specific host name instead of
-      "localhost", and accept external connections: 
-      <simplelist>
-        <member>GRANT USAGE ON *.* TO bugs@bounce.hop.com;</member>
-
-        <member>GRANT ALL ON bugs.* TO bugs@bounce.hop.com;</member>
-
-        <member>REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com;</member>
-
-        <member>FLUSH PRIVILEGES;</member>
-      </simplelist>
-      </para>
-
-      <para>Consider also: 
-      <orderedlist>
-        <listitem>
-          <para>Turning off external networking with "--skip-networking",
-          unless you have "mit-pthreads", in which case you can't. Without
-          networking, MySQL connects with a Unix domain socket.</para>
-        </listitem>
-
-        <listitem>
-          <para>using the --user= option to mysqld to run it as an
-          unprivileged user.</para>
-        </listitem>
-
-        <listitem>
-          <para>running MySQL in a chroot jail</para>
-        </listitem>
-
-        <listitem>
-          <para>running the httpd in a chroot jail</para>
-        </listitem>
-
-        <listitem>
-          <para>making sure the MySQL passwords are different from the OS
-          passwords (MySQL "root" has nothing to do with system
-          "root").</para>
-        </listitem>
-
-        <listitem>
-          <para>running MySQL on a separate untrusted machine</para>
-        </listitem>
-
-        <listitem>
-          <para>making backups ;-)</para>
-        </listitem>
-      </orderedlist>
-      </para>
-    </section>
-    
-    <section>
       <title>Configuring Bugzilla</title>
       <para>
       You should run through the parameters on the Edit Parameters page
@@ -1160,85 +1014,6 @@ bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; chars
       </note>
     </section>    
     
-    <section id="htaccess" xreflabel=".htaccess files and security">
-      <title>
-      <filename>.htaccess</filename>
-      files and security</title>
-
-      <para>To enhance the security of your Bugzilla installation, Bugzilla's
-      <filename>checksetup.pl</filename> script will generate 
-      <glossterm>
-        <filename>.htaccess</filename>
-      </glossterm>
-
-      files which the Apache webserver can use to restrict access to the
-      bugzilla data files. 
-      These .htaccess files will not work with Apache 1.2.x - but this
-      has security holes, so you shouldn't be using it anyway. 
-      <note>
-        <para>If you are using an alternate provider of 
-        <productname>webdot</productname>
-
-        services for graphing (as described when viewing 
-        <filename>editparams.cgi</filename>
-
-        in your web browser), you will need to change the ip address in 
-        <filename>data/webdot/.htaccess</filename>
-
-        to the ip address of the webdot server that you are using.</para>
-      </note>
-      </para>
-
-      <para>The default .htaccess file may not provide adequate access
-      restrictions, depending on your web server configuration. Be sure to
-      check the &lt;Directory&gt; entries for your Bugzilla directory so that
-      the 
-      <filename>.htaccess</filename>
-
-      file is allowed to override web server defaults. For instance, let's
-      assume your installation of Bugzilla is installed to 
-      <filename>/usr/local/bugzilla</filename>
-
-      . You should have this &lt;Directory&gt; entry in your 
-      <filename>httpd.conf</filename>
-
-      file:</para>
-
-      <para>
-      
-<programlisting><![CDATA[
-<Directory /usr/local/bugzilla/>
-  Options +FollowSymLinks +Indexes +Includes +ExecCGI
-  AllowOverride All
-</Directory>
-]]></programlisting>
-
-      </para>
-
-      <para>The important part above is 
-      <quote>AllowOverride All</quote>
-
-      . Without that, the 
-      <filename>.htaccess</filename>
-
-      file created by 
-      <filename>checksetup.pl</filename>
-
-      will not have sufficient permissions to protect your Bugzilla
-      installation.</para>
-
-      <para>If you are using Internet Information Server (IIS) or another 
-      web server which does not observe 
-      <filename>.htaccess</filename>
-      conventions, you can disable their creation by editing 
-      <filename>localconfig</filename>
-      and setting the 
-      <varname>$create_htaccess</varname>
-      variable to 
-      <parameter>0</parameter>.
-      </para>
-    </section>
-
     <section id="directoryindex" xreflabel="Modifying the Apache
     DirectoryIndex parameter to use index.cgi">
       <title>
@@ -1358,11 +1133,11 @@ C:\perl&gt; <command>ppm &lt;module name&gt;</command>
           </para>
         </note>
 
-        <note>
+        <tip>
           <para>A complete list of modules that can be installed using ppm can
           be found at <ulink url="http://www.activestate.com/PPMPackages/5.6plus">http://www.activestate.com/PPMPackages/5.6plus</ulink>.
           </para>
-        </note>
+        </tip>
       </section>
 
       <section id="win32-code-changes">
@@ -1400,19 +1175,6 @@ my $webservergid = '8'
           </programlisting>
         </section>
 
-        <section id="win32-code-mail">
-          <title>Making mail work</title>
-
-          <para>The easiest way to get mail working is to use the mail patches
-          on <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=124174">bug
-          124174</ulink>. With any luck, this patch will receive the required
-          reviews and integrated into the main Bugzilla distribution very soon.
-          Until that happens, there's at least one report of this patch working
-          well on Windows.
-          </para>
-
-        </section>
-
         <section>
           <title>System Calls</title>
 
@@ -1459,7 +1221,7 @@ system("C:\\perl\\bin\\perl", "$webdotbase","-Tpng","-o","$pngfilename","$filena
         <para>As is the case on Unix based systems, any web server should be
         able to handle Bugzilla; however, the Bugzilla Team still recommends
         Apache whenever asked. No matter what web server you choose, be sure
-        to pay attention to the security notes in <xref linkend="security"/>.
+        to pay attention to the security notes in <xref linkend="security-access"/>.
         More information on configuring specific web servers can be found in
         <xref linkend="http"/>.
         </para>
@@ -1480,7 +1242,7 @@ system("C:\\perl\\bin\\perl", "$webdotbase","-Tpng","-o","$pngfilename","$filena
     <section id="os-macosx">
       <title><productname>Mac OS X</productname></title>
 
-      <!-- XXX - Clean me up... (Mac OS X) -->
+      <!-- TODO: Clean me up... (Mac OS X) -->
       <para>There are a lot of common libraries and utilities out there that
       Apple did not include with Mac OS X, but which run perfectly well on it.
       The GD library, which Bugzilla needs to do bug graphs, is one of
@@ -1559,7 +1321,7 @@ system("C:\\perl\\bin\\perl", "$webdotbase","-Tpng","-o","$pngfilename","$filena
     that can be configured to run <glossterm linkend="gloss-cgi">CGI</glossterm> scripts
     should be able to handle Bugzilla. No matter what web server you choose, but
     especially if you choose something other than Apache, you should be sure to read
-    <xref linkend="security"/>.
+    <xref linkend="security-access"/>.
     </para>
 
     <para>The plan for this section is to eventually document the specifics of how to lock
@@ -1696,7 +1458,7 @@ deny from all
 
       <para>Also, and this can't be stressed enough, make sure that files such as
       <filename>localconfig</filename> and your <filename class="directory">data</filename>
-      directory are secured as described in <xref linkend="security"/>.
+      directory are secured as described in <xref linkend="security-access"/>.
       </para>
 
     </section>