diff options
Diffstat (limited to 'docs/xml/troubleshooting.xml')
| -rw-r--r-- | docs/xml/troubleshooting.xml | 318 |
1 files changed, 318 insertions, 0 deletions
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><path-to-perl>/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: --> + + |