summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/xml/Bugzilla-Guide.xml7
-rw-r--r--docs/xml/faq.xml130
-rw-r--r--docs/xml/installation.xml194
-rw-r--r--docs/xml/troubleshooting.xml318
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: -->
+
+