summaryrefslogtreecommitdiffstats
path: root/docs/en/xml/troubleshooting.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/en/xml/troubleshooting.xml')
-rw-r--r--docs/en/xml/troubleshooting.xml307
1 files changed, 307 insertions, 0 deletions
diff --git a/docs/en/xml/troubleshooting.xml b/docs/en/xml/troubleshooting.xml
new file mode 100644
index 000000000..13a756a3b
--- /dev/null
+++ b/docs/en/xml/troubleshooting.xml
@@ -0,0 +1,307 @@
+<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
+<!-- $Id: troubleshooting.xml,v 1.1 2008/04/03 19:05:43 lpsolit%gmail.com 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/mozilla.support.bugzilla">mozilla.support.bugzilla</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 web server 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>
+
+ <para>
+ Bugzilla can also log all user-based errors (and many code-based errors)
+ that occur, without polluting the web server's error log. To enable
+ Bugzilla error logging, create a file that Bugzilla can write to, named
+ <filename>errorlog</filename>, in the Bugzilla <filename>data</filename>
+ directory. Errors will be logged as they occur, and will include the type
+ of the error, the IP address and username (if available) of the user who
+ triggered the error, and the values of all environment variables; if a
+ form was being submitted, the data in the form will also be included.
+ To disable error logging, delete or rename the
+ <filename>errorlog</filename> file.
+ </para>
+ </section>
+
+ <section id="trbl-testserver">
+ <title>The Apache web server 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 web server 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 web server user or
+ group. It is recommended that they be world readable.
+ </para>
+ </listitem>
+ </orderedlist>
+ </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>&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="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 interface.
+ </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 Bugzilla 2.18 and Bugzilla 2.16.5).
+ </para>
+ </section>
+
+ <section id="trbl-relogin-some">
+ <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 (or later), 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>
+
+ <section id="trbl-index">
+ <title><filename>index.cgi</filename> doesn't show up unless specified in the URL</title>
+ <para>
+ You probably need to set up your web server in such a way that it
+ will serve the index.cgi page as an index page.
+ </para>
+ <para>
+ If you are using Apache, you can do this by adding
+ <filename>index.cgi</filename> to the end of the
+ <computeroutput>DirectoryIndex</computeroutput> line
+ as mentioned in <xref linkend="http-apache"/>.
+ </para>
+
+ </section>
+
+ <section id="trbl-passwd-encryption">
+ <title>
+ checksetup.pl reports "Client does not support authentication protocol
+ requested by server..."
+ </title>
+
+ <para>
+ This error is occurring because you are using the new password
+ encryption that comes with MySQL 4.1, while your
+ <filename>DBD::mysql</filename> module was compiled against an
+ older version of MySQL. If you recompile <filename>DBD::mysql</filename>
+ against the current MySQL libraries (or just obtain a newer version
+ of this module) then the error may go away.
+ </para>
+
+ <para>
+ If that does not fix the problem, or if you cannot recompile the
+ existing module (e.g. you're running Windows) and/or don't want to
+ replace it (e.g. you want to keep using a packaged version), then a
+ workaround is available from the MySQL docs:
+ <ulink url="http://dev.mysql.com/doc/mysql/en/Old_client.html"/>
+ </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: -->
+
+