319 lines
12 KiB
XML
319 lines
12 KiB
XML
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
|
|
<!-- $Id: troubleshooting.xml,v 1.2 2008-04-04 06:48:14 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 id="trbl-testserver">
|
|
<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 id="trbl-perlmodule">
|
|
<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 id="trbl-bundleBugzilla">
|
|
<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 id="trbl-dbdSponge">
|
|
<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: -->
|
|
|
|
|