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 (limited to 'docs') 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 - <filename>checksetup.pl</filename> 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 + <filename>checksetup.pl</filename> 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.3-24-g4f1b