From c88af85fd2d0627287386f8ed21ad3baa7e93fdc Mon Sep 17 00:00:00 2001
From: "jake%bugzilla.org" <>
Date: Tue, 7 Dec 2004 19:41:59 +0000
Subject: Bug 271360 - Moving the Troubleshooting section into an appendix
instead. Also, moved a few items out of the FAQ and into this new appendix.
---
docs/xml/Bugzilla-Guide.xml | 7 +-
docs/xml/faq.xml | 130 +-----------------
docs/xml/installation.xml | 194 +-------------------------
docs/xml/troubleshooting.xml | 318 +++++++++++++++++++++++++++++++++++++++++++
4 files changed, 332 insertions(+), 317 deletions(-)
create mode 100644 docs/xml/troubleshooting.xml
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 @@
+
@@ -156,6 +157,9 @@
&faq;
+
+&troubleshooting;
+
&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
-
-
-
- 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.)
-
-
-
-
- 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.
-
-
- The value of the cookiepath parameter should be the actual directory
- containing your Bugzilla installation, as seen by the
- end-user's web browser. 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.
-
-
- How do you know if you want your specific Bugzilla directory or the
- whole site?
-
-
-
- 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.
-
-
- Examples:
-
-
-
- urlbase is
- cookiepath is /
-
- urlbase is
- but you have http://tools.mysite.tld/someotherapp/ which shares
- authentication with your Bugzilla
- cookiepath is /
-
-
-
-
-
- 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.
-
-
- Examples:
-
-
-
- urlbase is
- cookiepath is /bugzilla-tip/
-
- urlbase is
- cookiepath is /bugzilla-2.16-branch/
-
-
-
-
-
- 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).
-
-
-
-
-
-
-
- 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.
-
-
-
-
- First, make sure cookies are enabled in the user's browser.
-
-
- 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.
-
-
- 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.
-
-
-
-
@@ -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)?
+
Run MySQL like this: "mysqld --skip-grant-tables". Please remember this
makes MySQL as secure as taping a $100 to the floor of a football stadium
bathroom for safekeeping.
+
+ This can't be stressed enough. Doing this is a bad idea.
+ Please consult of this guide and
+ the MySQL documentation for better solutions.
+
+
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 @@
-
+
Installing Bugzilla
@@ -1738,198 +1738,6 @@ pid-file=/home/foo/mymysql/the.pid
-
- Troubleshooting
-
- This section gives solutions to common Bugzilla installation
- problems. If none of the section headings seems to match your
- problem, read the general advice.
-
-
-
- General Advice
-
- If you can't get checksetup.pl 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
- netscape.public.mozilla.webtools
- newsgroup.
-
-
-
- If you have made it all the way through
- (Installation) and
- (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
- /etc/logs/httpd/error_log. 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.
-
-
-
-
- The Apache webserver is not serving Bugzilla pages
-
- After you have run checksetup.pl twice,
- run testserver.pl http://yoursite.yourdomain/yoururl
- to confirm that your webserver is configured properly for
- Bugzilla.
-
-
-
-
-
- I installed a Perl module, but
- checksetup.pl claims it's not installed!
-
-
- 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 checksetup.pl. This will make sure you
- are installing the modules in the right place.
-
-
-
-
- Bundle::Bugzilla makes me upgrade to Perl 5.6.1
-
-
- Try executing perl -MCPAN -e 'install CPAN'
- and then continuing.
-
-
-
- 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.
-
-
-
-
-
- DBD::Sponge::db prepare failed
-
-
- The following error message may appear due to a bug in DBD::mysql
- (over which the Bugzilla team have no control):
-
-
-
-
-
- To fix this, go to
- <path-to-perl>/lib/DBD/sponge.pm
- in your Perl installation and replace
-
-
-{'NUM_OF_FIELDS'}) {
- $numFields = $attribs->{'NUM_OF_FIELDS'};
- } elsif ($attribs->{'NAME'}) {
- $numFields = @{$attribs->{NAME}};
-]]>
-
-
- by
-
-
-{'NUM_OF_FIELDS'}) {
- $numFields = $attribs->{'NUM_OF_FIELDS'};
- } elsif ($attribs->{'NAMES'}) {
- $numFields = @{$attribs->{NAMES}};
-]]>
-
-
- (note the S added to NAME.)
-
-
-
-
- cannot chdir(/var/spool/mqueue)
-
- If you are installing Bugzilla on SuSE Linux, or some other
- distributions with
- paranoid
- security options, it is possible that the checksetup.pl script may fail
- with the error:
-
-
-
-
- This is because your
- /var/spool/mqueue
- directory has a mode of
- drwx------
. Type
- chmod 755
- /var/spool/mqueue
-
- as root to fix this problem.
-
-
-
-
- Your vendor has not defined Fcntl macro O_NOINHERIT
-
- This is caused by a bug in the version of
- File::Temp that is distributed with perl
- 5.6.0. Many minor variations of this error have been reported:
-
-
- 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.
-
- 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 patch file.
-
-
-
-
-
+
+
+
+Troubleshooting
+
+ This section gives solutions to common Bugzilla installation
+ problems. If none of the section headings seems to match your
+ problem, read the general advice.
+
+
+
+ General Advice
+ If you can't get checksetup.pl 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
+ netscape.public.mozilla.webtools
+ newsgroup.
+
+
+ If you have made it all the way through
+ (Installation) and
+ (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
+ /etc/logs/httpd/error_log. 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.
+
+
+
+
+ The Apache webserver is not serving Bugzilla pages
+ After you have run checksetup.pl twice,
+ run testserver.pl http://yoursite.yourdomain/yoururl
+ to confirm that your webserver is configured properly for
+ Bugzilla.
+
+
+bash$ ./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.
+
+
+
+
+ I installed a Perl module, but
+ checksetup.pl claims it's not installed!
+
+ This could be caused by one of two things:
+
+
+ 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 checksetup.pl. This will make sure you
+ are installing the modules in the right place.
+
+
+
+ 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.
+
+
+
+
+
+
+ Bundle::Bugzilla makes me upgrade to Perl 5.6.1
+
+ Try executing perl -MCPAN -e 'install CPAN'
+ and then continuing.
+
+
+ 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.
+
+
+
+
+
+ DBD::Sponge::db prepare failed
+
+ The following error message may appear due to a bug in DBD::mysql
+ (over which the Bugzilla team have no control):
+
+
+
+
+ To fix this, go to
+ <path-to-perl>/lib/DBD/sponge.pm
+ in your Perl installation and replace
+
+
+{'NUM_OF_FIELDS'}) {
+ $numFields = $attribs->{'NUM_OF_FIELDS'};
+ } elsif ($attribs->{'NAME'}) {
+ $numFields = @{$attribs->{NAME}};
+]]>
+
+ with
+
+{'NUM_OF_FIELDS'}) {
+ $numFields = $attribs->{'NUM_OF_FIELDS'};
+ } elsif ($attribs->{'NAMES'}) {
+ $numFields = @{$attribs->{NAMES}};
+]]>
+
+ (note the S added to NAME.)
+
+
+
+ cannot chdir(/var/spool/mqueue)
+
+ If you are installing Bugzilla on SuSE Linux, or some other
+ distributions with paranoid
security options, it is
+ possible that the checksetup.pl script may fail with the error:
+
+
+
+ This is because your /var/spool/mqueue
+ directory has a mode of drwx------.
+ Type chmod 755 /var/spool/mqueue
+ as root to fix this problem. This will allow any process running on your
+ machine the ability to read the
+ /var/spool/mqueue directory.
+
+
+
+
+ Your vendor has not defined Fcntl macro O_NOINHERIT
+
+ This is caused by a bug in the version of
+ File::Temp that is distributed with perl
+ 5.6.0. Many minor variations of this error have been reported:
+
+
+ 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.
+
+ 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 patch file.
+
+
+
+
+
+
+ Everybody is constantly being forced to relogin
+
+ 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.
+
+
+ The value of the cookiepath parameter should be the actual directory
+ containing your Bugzilla installation, as seen by the end-user's
+ web browser. 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.
+
+
+ How do you know if you want your specific Bugzilla directory or the
+ whole site?
+
+
+ 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.
+
+
+
+ Examples of urlbase/cookiepath pairs for sharing login cookies
+
+
+
+ urlbase is
+ cookiepath is /
+
+ urlbase is
+ but you have http://tools.mysite.tld/someotherapp/ which shares
+ authentication with your Bugzilla
+ cookiepath is /
+
+
+
+
+ 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.
+
+
+
+
+ Examples of urlbase/cookiepath pairs to restrict the login cookie
+
+
+ urlbase is
+ cookiepath is /bugzilla-tip/
+
+ urlbase is
+ cookiepath is /bugzilla-2.16-branch/
+
+
+
+
+ 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.18 and Bugzilla 2.16.5).
+
+
+
+
+ Some users are constantly being forced to relogin
+
+ First, make sure cookies are enabled in the user's browser.
+
+
+ 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.
+
+
+ If you are using 2.18
+ , 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.
+
+
+
+
+
+
+
+
+
--
cgit v1.2.1