Bug 271360 - Moving the Troubleshooting section into an appendix instead. Also, moved a few items out of the FAQ and into this new appendix.

4 files changed, 332 insertions, 317 deletions

diff --git a/docs/xml/Bugzilla-Guide.xml b/docs/xml/Bugzilla-Guide.xml
index d12f6a817..619f7e95b 100644
--- a/docs/xml/Bugzilla-Guide.xml
+++ b/docs/xml/Bugzilla-Guide.xml
@@ -14,6 +14,7 @@
 <!ENTITY integration SYSTEM "integration.xml">
 <!ENTITY index SYSTEM "index.xml">
 <!ENTITY customization SYSTEM "customization.xml">
+<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
 <!ENTITY patches SYSTEM "patches.xml">
 <!ENTITY introduction SYSTEM "introduction.xml">
 <!ENTITY modules SYSTEM "modules.xml">
@@ -156,6 +157,9 @@
 <!-- Appendix: The Frequently Asked Questions -->
 &faq;
 
+<!-- Appendix: Troubleshooting -->
+&troubleshooting;
+
 <!-- Appendix: Custom Patches -->
 &patches;
 
@@ -193,4 +197,5 @@ sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End:
--->
\ No newline at end of file
+-->
+
diff --git a/docs/xml/faq.xml b/docs/xml/faq.xml
index 59cb330d9..fbab94212 100644
--- a/docs/xml/faq.xml
+++ b/docs/xml/faq.xml
@@ -584,129 +584,6 @@ perl -pi -e 's@#\!/usr/bin/perl@#\!/usr/local/bin/perl@' *cgi *pl
 	</answer>
       </qandaentry>
 
-      <qandaentry>
-        <question id="faq-phb-reloginEveryone">
-          <para>
-            Why do users have to log in every time they access a page? This
-            affects everyone who accesses my Bugzilla. (If this only affects
-            some of your users, see the next FAQ item.)
-          </para>
-        </question>
-        <answer>
-          <para>
-            The most-likely cause is that the "cookiepath" parameter is not set
-            correctly in the Bugzilla configuration.  You can change this (if
-            you're a Bugzilla administrator) from the editparams.cgi page
-            via the web.
-          </para>
-          <para>
-            The value of the cookiepath parameter should be the actual directory
-            containing your Bugzilla installation, <emphasis>as seen by the
-            end-user's web browser</emphasis>. Leading and trailing slashes are
-            mandatory. You can also set the cookiepath to any directory which
-            is a parent of the Bugzilla directory (such as '/', the root
-            directory). But you can't put something that isn't at least
-            a partial match or it won't work. What you're actually doing
-            is restricting the end-user's browser to sending the cookies
-            back only to that directory.
-          </para>
-          <para>
-            How do you know if you want your specific Bugzilla directory or the
-            whole site?
-          </para>
-
-          <para>
-            If you have only one Bugzilla running on the server, and you
-            don't mind having other applications on the same server with it
-            being able to see the cookies (you might be doing this on purpose
-            if you have other things on your site that share authentication with
-            Bugzilla), then you'll want to have the cookiepath set to "/", or to
-            a sufficiently-high enough directory that all of the involved apps
-            can see the cookies.
-          </para>
-          <para>
-            Examples:
-
-            <blockquote>
-              <literallayout>
-        urlbase is <ulink url="http://bugzilla.mozilla.org/"/>
-        cookiepath is /
-
-        urlbase is <ulink url="http://tools.mysite.tld/bugzilla/"/>
-                but you have http://tools.mysite.tld/someotherapp/ which shares
-                authentication with your Bugzilla
-        cookiepath is /
-              </literallayout>
-            </blockquote>
-          </para>
-          
-         <para>
-            On the other hand, if you have more than one Bugzilla
-            running on the server (some people do - we do on landfill)
-            then you need to have the cookiepath restricted enough
-            so that the different Bugzillas don't
-            confuse their cookies with one another.
-          </para>
-          <para>
-            Examples:
-
-            <blockquote>
-              <literallayout>
-        urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-tip/"/>
-        cookiepath is /bugzilla-tip/
-
-        urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-2.16-branch/"/>
-        cookiepath is /bugzilla-2.16-branch/
-              </literallayout>
-            </blockquote>
-          </para>
-
-          <para>
-            If you had cookiepath set to / at any point in the past and
-            need to set it to something more restrictive (i.e. /bugzilla/),
-            you can safely do this without requiring users to delete
-            their Bugzilla-related cookies in their browser (this is
-            true starting with Bugzilla 2.17.7 and Bugzilla 2.16.5).
-          </para>
-        </answer>
-      </qandaentry>
-
-      <qandaentry>
-        <question id="faq-phb-reloginSome">
-          <para>
-            Why do users have to log in every time they access a page? This
-            only seems to affect some of my Bugzilla's users, others stay
-            logged in.
-          </para>
-        </question>
-        <answer>
-          <para>
-            First, make sure cookies are enabled in the user's browser.
-          </para>
-          <para>
-            If that doesn't fix the problem, it may be that
-            the user's ISP implements a rotating proxy server. This causes
-            the user's effective IP address (the address which the Bugzilla server
-            perceives him coming from) to change periodically. Since
-            Bugzilla cookies are tied to a specific IP address, each time
-            the effective address changes, the user will have to log in again.
-          </para>
-          <para>
-            In newer versions of Bugzilla (2.17.1 and later) there is a
-            parameter called "loginnetmask", which you can use to set the
-            number of bits of the user's IP address to require to be matched
-            when authenticating the cookies. If you set this to something less
-            than 32, then the user will be given a checkbox for "Restrict this
-            login to my IP address" on the login screen, which defaults to
-            checked. If they leave the box checked, Bugzilla will behave the
-            same as it did before, requiring an exact match on their IP address
-            to remain logged in. If they uncheck the box, then only the left
-            side of their IP address (up to the number of bits you specified in
-            the parameter) has to match to remain logged in.
-          </para>
-        </answer>  
-      </qandaentry>
-
     </qandadiv>
 
     <qandadiv id="faq-security">
@@ -719,12 +596,19 @@ perl -pi -e 's@#\!/usr/bin/perl@#\!/usr/local/bin/perl@' *cgi *pl
 	    (I've followed the instructions in the installation section of this guide)?
 	  </para>
 	</question>
+	<!-- Should we really even answer this question? -->
 	<answer>
 	  <para>
 	    Run MySQL like this: "mysqld --skip-grant-tables". Please remember <emphasis>this
 	    makes MySQL as secure as taping a $100 to the floor of a football stadium
 	    bathroom for safekeeping.</emphasis> 
 	  </para>
+	  <warning>
+	    <para>This can't be stressed enough. Doing this is a bad idea.
+	    Please consult <xref linkend="security-mysql"/> of this guide and
+            the MySQL documentation for better solutions.
+	    </para>
+	  </warning>
 	</answer>
       </qandaentry>
 
diff --git a/docs/xml/installation.xml b/docs/xml/installation.xml
index 0f06b4735..4cd5cfc0b 100644
--- a/docs/xml/installation.xml
+++ b/docs/xml/installation.xml
@@ -1,5 +1,5 @@
 <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.82 2004/12/02 04:21:27 jake%bugzilla.org Exp $ -->
+<!-- $Id: installation.xml,v 1.83 2004/12/07 11:41:59 jake%bugzilla.org Exp $ -->
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -1738,198 +1738,6 @@ pid-file=/home/foo/mymysql/the.pid
     </section>
   </section>
 
-  <section id="troubleshooting">
-    <title>Troubleshooting</title>
-    
-    <para>This section gives solutions to common Bugzilla installation
-    problems. If none of the section headings seems to match your
-    problem, read the general advice.
-    </para>
-    
-    <section id="general-advice">
-      <title>General Advice</title>
-      <para>
-        If you can't get <filename>checksetup.pl</filename> to run to 
-        completion, it normally explains what's wrong and how to fix it.
-        If you can't work it out, or if it's being uncommunicative, post 
-        the errors in the 
-        <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">netscape.public.mozilla.webtools</ulink>
-        newsgroup.
-      </para>
-
-      <para>
-        If you have made it all the way through 
-        <xref linkend="installation"/> (Installation) and
-        <xref linkend="configuration"/> (Configuration) but 
-        accessing the Bugzilla URL doesn't work,
-        the first thing to do is to check your webserver error log. For
-        Apache, this is often located at
-        <filename>/etc/logs/httpd/error_log</filename>. The error messages
-        you see may be self-explanatory enough to enable you to diagnose and
-        fix the problem. If not, see below for some commonly-encountered 
-        errors. If that doesn't help, post the errors to the newsgroup.
-      </para>
-    </section>
-        
-    <section>
-      <title>The Apache webserver is not serving Bugzilla pages</title>
-      <para>
-        After you have run <command>checksetup.pl</command> twice,
-        run <command>testserver.pl http://yoursite.yourdomain/yoururl</command>
-        to confirm that your webserver is configured properly for
-        Bugzilla.
-      </para>
-<programlisting><![CDATA[./testserver.pl http://landfill.bugzilla.org/bugzilla-tip
-TEST-OK Webserver is running under group id in $webservergroup.
-TEST-OK Got ant picture.
-TEST-OK Webserver is executing CGIs.
-TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig.
-]]></programlisting>
-    </section>
-
-    <section>
-      <title>I installed a Perl module, but 
-      <filename>checksetup.pl</filename> claims it's not installed!</title>
-      
-      <para>
-        You have two versions of Perl on your machine. You are installing
-        modules into one, and Bugzilla is using the other. Rerun the CPAN
-        commands (or manual compile) using the full path to Perl from the 
-        top of <filename>checksetup.pl</filename>. This will make sure you 
-        are installing the modules in the right place.
-      </para>
-    </section>
-    
-    <section>
-      <title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title>
-
-      <para>
-      Try executing <command>perl -MCPAN -e 'install CPAN'</command>
-      and then continuing.
-      </para>
-      
-      <para>
-      Certain older versions of the CPAN toolset were somewhat naive about how
-      to upgrade Perl modules. When a couple of modules got rolled into the core
-      Perl distribution for 5.6.1, CPAN thought that the best way to get those
-      modules up to date was to haul down the Perl distribution itself and
-      build it. Needless to say, this has caused headaches for just about
-      everybody. Upgrading to a newer version of CPAN with the
-      commandline above should fix things.
-      </para>
-    </section>
-
-
-    <section>
-      <title>DBD::Sponge::db prepare failed</title>
-      
-      <para>
-        The following error message may appear due to a bug in DBD::mysql
-        (over which the Bugzilla team have no control):
-      </para>
-      
-<programlisting><![CDATA[ DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248.
-  SV = NULL(0x0) at 0x20fc444
-  REFCNT = 1
-  FLAGS = (PADBUSY,PADMY)
-]]></programlisting>
-
-      <para>
-        To fix this, go to 
-        <filename>&lt;path-to-perl&gt;/lib/DBD/sponge.pm</filename> 
-        in your Perl installation and replace
-      </para>
-        
-<programlisting><![CDATA[ my $numFields;
- if ($attribs->{'NUM_OF_FIELDS'}) {
-     $numFields = $attribs->{'NUM_OF_FIELDS'};
- } elsif ($attribs->{'NAME'}) {
-     $numFields = @{$attribs->{NAME}};
-]]></programlisting>
-
-      <para>
-        by
-      </para>
-
-<programlisting><![CDATA[ my $numFields;
- if ($attribs->{'NUM_OF_FIELDS'}) {
-     $numFields = $attribs->{'NUM_OF_FIELDS'};
- } elsif ($attribs->{'NAMES'}) {
-     $numFields = @{$attribs->{NAMES}};
-]]></programlisting>
-
-      <para>
-        (note the S added to NAME.)      
-      </para>
-    </section>
-    
-    <section id="paranoid-security">
-      <title>cannot chdir(/var/spool/mqueue)</title>
-
-      <para>If you are installing Bugzilla on SuSE Linux, or some other
-      distributions with 
-      <quote>paranoid</quote>
-      security options, it is possible that the checksetup.pl script may fail
-      with the error: 
-<programlisting><![CDATA[cannot chdir(/var/spool/mqueue): Permission denied
-]]></programlisting>
-      </para>
-      
-      <para>
-      This is because your 
-      <filename>/var/spool/mqueue</filename>
-      directory has a mode of 
-      <quote>drwx------</quote>. Type 
-      <command>chmod 755 
-      <filename>/var/spool/mqueue</filename>
-      </command>
-      as root to fix this problem.
-      </para>
-    </section>    
-
-    <section id="trouble-filetemp">
-      <title>Your vendor has not defined Fcntl macro O_NOINHERIT</title>
-
-      <para>This is caused by a bug in the version of
-      <productname>File::Temp</productname> that is distributed with perl
-      5.6.0. Many minor variations of this error have been reported:
-      </para>
-
-      <programlisting>Your vendor has not defined Fcntl macro O_NOINHERIT, used 
-at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208.
-
-Your vendor has not defined Fcntl macro O_EXLOCK, used 
-at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210.
-
-Your vendor has not defined Fcntl macro O_TEMPORARY, used 
-at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.</programlisting>
-
-      <para>Numerous people have reported that upgrading to version 5.6.1
-      or higher solved the problem for them. A less involved fix is to apply
-      the following patch, which is also
-      available as a <ulink url="../xml/filetemp.patch">patch file</ulink>.
-      </para>
-
-        <programlisting><![CDATA[--- File/Temp.pm.orig   Thu Feb  6 16:26:00 2003
-+++ File/Temp.pm        Thu Feb  6 16:26:23 2003
-@@ -205,6 +205,7 @@
-     # eg CGI::Carp
-     local $SIG{__DIE__} = sub {};
-     local $SIG{__WARN__} = sub {};
-+    local *CORE::GLOBAL::die = sub {};
-     $bit = &$func();
-     1;
-   };
-@@ -226,6 +227,7 @@
-     # eg CGI::Carp
-     local $SIG{__DIE__} = sub {};
-     local $SIG{__WARN__} = sub {};
-+    local *CORE::GLOBAL::die = sub {};
-     $bit = &$func();
-     1;
-   };]]></programlisting>
-    </section>
-  </section>
 </chapter>
 
 <!-- Keep this comment at the end of the file
diff --git a/docs/xml/troubleshooting.xml b/docs/xml/troubleshooting.xml
new file mode 100644
index 000000000..be2155766
--- /dev/null
+++ b/docs/xml/troubleshooting.xml
@@ -0,0 +1,318 @@
+<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
+<!-- $Id: troubleshooting.xml,v 1.1 2004/12/07 11:41:59 jake%bugzilla.org Exp $ -->
+
+<appendix id="troubleshooting">
+<title>Troubleshooting</title>
+
+  <para>This section gives solutions to common Bugzilla installation
+  problems. If none of the section headings seems to match your
+  problem, read the general advice.
+  </para>
+    
+  <section id="general-advice">
+  <title>General Advice</title>
+    <para>If you can't get <filename>checksetup.pl</filename> to run to 
+    completion, it normally explains what's wrong and how to fix it.
+    If you can't work it out, or if it's being uncommunicative, post 
+    the errors in the 
+    <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">netscape.public.mozilla.webtools</ulink>
+    newsgroup.
+    </para>
+
+    <para>If you have made it all the way through
+    <xref linkend="installation"/> (Installation) and
+    <xref linkend="configuration"/> (Configuration) but accessing the Bugzilla
+    URL doesn't work, the first thing to do is to check your webserver error
+    log. For Apache, this is often located at
+    <filename>/etc/logs/httpd/error_log</filename>. The error messages
+    you see may be self-explanatory enough to enable you to diagnose and
+    fix the problem. If not, see below for some commonly-encountered 
+    errors. If that doesn't help, post the errors to the newsgroup.
+    </para>
+  </section>
+        
+  <section>
+  <title>The Apache webserver is not serving Bugzilla pages</title>
+    <para>After you have run <command>checksetup.pl</command> twice,
+    run <command>testserver.pl http://yoursite.yourdomain/yoururl</command>
+    to confirm that your webserver is configured properly for
+    Bugzilla.
+    </para>
+    <programlisting>
+<prompt>bash$</prompt> ./testserver.pl http://landfill.bugzilla.org/bugzilla-tip
+TEST-OK Webserver is running under group id in $webservergroup.
+TEST-OK Got ant picture.
+TEST-OK Webserver is executing CGIs.
+TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig.
+</programlisting>
+  </section>
+
+  <section>
+  <title>I installed a Perl module, but 
+      <filename>checksetup.pl</filename> claims it's not installed!</title>
+      
+    <para>This could be caused by one of two things:</para>
+    <orderedlist>
+      <listitem>
+        <para>You have two versions of Perl on your machine. You are installing
+        modules into one, and Bugzilla is using the other. Rerun the CPAN
+        commands (or manual compile) using the full path to Perl from the 
+        top of <filename>checksetup.pl</filename>. This will make sure you 
+        are installing the modules in the right place.
+        </para>
+      </listitem>
+      <listitem>
+	<para>The permissions on your library directories are set incorrectly.
+	They must, at the very least, be readable by the webserver user or
+	group. It is recommended that they be world readable.
+        </para>
+      </listitem>
+    </orderedlist>
+  </section>
+    
+  <section>
+  <title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title>
+
+    <para>Try executing <command>perl -MCPAN -e 'install CPAN'</command>
+    and then continuing.
+    </para>
+      
+    <para>Certain older versions of the CPAN toolset were somewhat naive about
+    how to upgrade Perl modules. When a couple of modules got rolled into the
+    core Perl distribution for 5.6.1, CPAN thought that the best way to get
+    those modules up to date was to haul down the Perl distribution itself and
+    build it. Needless to say, this has caused headaches for just about
+    everybody. Upgrading to a newer version of CPAN with the
+    commandline above should fix things.
+    </para>
+  </section>
+
+
+  <section>
+  <title>DBD::Sponge::db prepare failed</title>
+      
+    <para>The following error message may appear due to a bug in DBD::mysql
+    (over which the Bugzilla team have no control):
+    </para>
+      
+<programlisting><![CDATA[ DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248.
+  SV = NULL(0x0) at 0x20fc444
+  REFCNT = 1
+  FLAGS = (PADBUSY,PADMY)
+]]></programlisting>
+
+    <para>To fix this, go to 
+    <filename>&lt;path-to-perl&gt;/lib/DBD/sponge.pm</filename> 
+    in your Perl installation and replace
+    </para>
+        
+<programlisting><![CDATA[ my $numFields;
+ if ($attribs->{'NUM_OF_FIELDS'}) {
+     $numFields = $attribs->{'NUM_OF_FIELDS'};
+ } elsif ($attribs->{'NAME'}) {
+     $numFields = @{$attribs->{NAME}};
+]]></programlisting>
+
+    <para>with</para>
+
+<programlisting><![CDATA[ my $numFields;
+ if ($attribs->{'NUM_OF_FIELDS'}) {
+     $numFields = $attribs->{'NUM_OF_FIELDS'};
+ } elsif ($attribs->{'NAMES'}) {
+     $numFields = @{$attribs->{NAMES}};
+]]></programlisting>
+
+     <para>(note the S added to NAME.)</para>
+  </section>
+    
+  <section id="paranoid-security">
+  <title>cannot chdir(/var/spool/mqueue)</title>
+
+    <para>If you are installing Bugzilla on SuSE Linux, or some other
+    distributions with <quote>paranoid</quote> security options, it is
+    possible that the checksetup.pl script may fail with the error: 
+<programlisting><![CDATA[cannot chdir(/var/spool/mqueue): Permission denied
+]]></programlisting>
+    </para>
+      
+    <para>This is because your <filename>/var/spool/mqueue</filename>
+    directory has a mode of <computeroutput>drwx------</computeroutput>.
+    Type <command>chmod 755 <filename>/var/spool/mqueue</filename></command>
+    as root to fix this problem. This will allow any process running on your
+    machine the ability to <emphasis>read</emphasis> the
+    <filename>/var/spool/mqueue</filename> directory.
+    </para>
+  </section>    
+
+  <section id="trouble-filetemp">
+  <title>Your vendor has not defined Fcntl macro O_NOINHERIT</title>
+
+    <para>This is caused by a bug in the version of
+    <productname>File::Temp</productname> that is distributed with perl
+    5.6.0. Many minor variations of this error have been reported:
+    </para>
+
+    <programlisting>Your vendor has not defined Fcntl macro O_NOINHERIT, used 
+at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208.
+
+Your vendor has not defined Fcntl macro O_EXLOCK, used 
+at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210.
+
+Your vendor has not defined Fcntl macro O_TEMPORARY, used 
+at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.</programlisting>
+
+    <para>Numerous people have reported that upgrading to version 5.6.1
+    or higher solved the problem for them. A less involved fix is to apply
+    the following patch, which is also
+    available as a <ulink url="../xml/filetemp.patch">patch file</ulink>.
+    </para>
+
+    <programlisting><![CDATA[--- File/Temp.pm.orig   Thu Feb  6 16:26:00 2003
++++ File/Temp.pm        Thu Feb  6 16:26:23 2003
+@@ -205,6 +205,7 @@
+     # eg CGI::Carp
+     local $SIG{__DIE__} = sub {};
+     local $SIG{__WARN__} = sub {};
++    local *CORE::GLOBAL::die = sub {};
+     $bit = &$func();
+     1;
+   };
+@@ -226,6 +227,7 @@
+     # eg CGI::Carp
+     local $SIG{__DIE__} = sub {};
+     local $SIG{__WARN__} = sub {};
++    local *CORE::GLOBAL::die = sub {};
+     $bit = &$func();
+     1;
+   };]]></programlisting>
+  </section>
+
+  <section id="trbl-relogin-everyone">
+  <title>Everybody is constantly being forced to relogin</title>
+  
+  <para>The most-likely cause is that the <quote>cookiepath</quote> parameter
+  is not set correctly in the Bugzilla configuration.  You can change this (if
+  you're a Bugzilla administrator) from the editparams.cgi page via the web.
+  </para>
+
+  <para>The value of the cookiepath parameter should be the actual directory
+  containing your Bugzilla installation, <emphasis>as seen by the end-user's
+  web browser</emphasis>. Leading and trailing slashes are mandatory. You can
+  also set the cookiepath to any directory which is a parent of the Bugzilla
+  directory (such as '/', the root directory). But you can't put something
+  that isn't at least a partial match or it won't work. What you're actually
+  doing is restricting the end-user's browser to sending the cookies back only
+  to that directory.
+  </para>
+
+  <para>How do you know if you want your specific Bugzilla directory or the
+  whole site?
+  </para>
+
+  <para>If you have only one Bugzilla running on the server, and you don't
+  mind having other applications on the same server with it being able to see
+  the cookies (you might be doing this on purpose if you have other things on
+  your site that share authentication with Bugzilla), then you'll want to have
+  the cookiepath set to "/", or to a sufficiently-high enough directory that
+  all of the involved apps can see the cookies.
+  </para>
+
+  <example id="trbl-relogin-everyone-share">
+  <title>Examples of urlbase/cookiepath pairs for sharing login cookies</title>
+
+    <blockquote>
+      <literallayout>
+        urlbase is <ulink url="http://bugzilla.mozilla.org/"/>
+        cookiepath is /
+
+        urlbase is <ulink url="http://tools.mysite.tld/bugzilla/"/>
+                but you have http://tools.mysite.tld/someotherapp/ which shares
+                authentication with your Bugzilla
+        cookiepath is /
+      </literallayout>
+    </blockquote>
+  </example>
+          
+   <para>On the other hand, if you have more than one Bugzilla running on the
+   server (some people do - we do on landfill) then you need to have the
+   cookiepath restricted enough so that the different Bugzillas don't
+   confuse their cookies with one another.
+   </para>
+
+
+   <example id="trbl-relogin-everyone-restrict">
+   <title>Examples of urlbase/cookiepath pairs to restrict the login cookie</title>
+      <blockquote>
+        <literallayout>
+        urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-tip/"/>
+        cookiepath is /bugzilla-tip/
+
+        urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-2.16-branch/"/>
+        cookiepath is /bugzilla-2.16-branch/
+        </literallayout>
+      </blockquote>
+    </example>
+
+    <para>If you had cookiepath set to <quote>/</quote> at any point in the
+    past and need to set it to something more restrictive
+    (i.e. <quote>/bugzilla/</quote>), you can safely do this without
+    requiring users to delete their Bugzilla-related cookies in their
+    browser (this is true starting with 
+    <!-- Need OR logic here for bz-devel logic here --> 
+    Bugzilla 2.18<![%bz-devel;[, Bugzilla 2.17.7,]]> and Bugzilla 2.16.5).
+    </para>
+  </section>
+
+  <section>
+  <title>Some users are constantly being forced to relogin</title>
+
+    <para>First, make sure cookies are enabled in the user's browser.
+    </para>
+
+    <para>If that doesn't fix the problem, it may be that the user's ISP
+     implements a rotating proxy server. This causes the user's effective IP
+     address (the address which the Bugzilla server perceives him coming from)
+     to change periodically. Since Bugzilla cookies are tied to a specific IP
+     address, each time the effective address changes, the user will have to
+     log in again.
+     </para>
+
+     <para>If you are using 2.18
+     <![%bz-devel[(or 2.17.1 in the development series)]]>, there is a
+     parameter called <quote>loginnetmask</quote>, which you can use to set
+     the number of bits of the user's IP address to require to be matched when
+     authenticating the cookies. If you set this to something less than 32,
+     then the user will be given a checkbox for <quote>Restrict this login to
+     my IP address</quote> on the login screen, which defaults to checked. If
+     they leave the box checked, Bugzilla will behave the same as it did
+     before, requiring an exact match on their IP address to remain logged in.
+     If they uncheck the box, then only the left side of their IP address (up
+     to the number of bits you specified in the parameter) has to match to
+     remain logged in.
+     </para>
+
+   </section>
+
+</appendix> 
+
+<!-- Keep this comment at the end of the file 
+Local variables: 
+mode: sgml 
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t 
+sgml-indent-step:2 
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil 
+sgml-minimize-attributes:nil
+sgml-namecase-general:t 
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t 
+sgml-tag-region-if-active:t 
+End: -->
+
+