1 files changed, 235 insertions, 0 deletions
diff --git a/docs/en/rst/troubleshooting.rst b/docs/en/rst/troubleshooting.rst
new file mode 100644
index 000000000..26899bc57
--- /dev/null
+++ b/docs/en/rst/troubleshooting.rst
@@ -0,0 +1,235 @@
+
+
+.. _troubleshooting:
+
+===============
+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:
+
+General Advice
+##############
+
+If you can't get :file:`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
+`mozilla.support.bugzilla <news://news.mozilla.org/mozilla.support.bugzilla>`_
+newsgroup.
+
+If you have made it all the way through
+:ref:`installation` (Installation) and
+:ref:`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
+:file:`/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.
+
+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
+:file:`errorlog`, in the Bugzilla :file:`data`
+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
+:file:`errorlog` file.
+
+.. _trbl-testserver:
+
+The Apache web server is not serving Bugzilla pages
+###################################################
+
+After you have run :command:`checksetup.pl` twice,
+run :command:`testserver.pl http://yoursite.yourdomain/yoururl`
+to confirm that your web server 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.
+
+.. _trbl-perlmodule:
+
+I installed a Perl module, but :file:`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 :file:`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 web server user or
+   group. It is recommended that they be world readable.
+
+.. _trbl-dbdSponge:
+
+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):
+
+::
+
+    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)
+
+To fix this, go to
+:file:`<path-to-perl>/lib/DBD/sponge.pm`
+in your Perl installation and replace
+
+::
+
+    my $numFields;
+    if ($attribs->{'NUM_OF_FIELDS'}) {
+    $numFields = $attribs->{'NUM_OF_FIELDS'};
+    } elsif ($attribs->{'NAME'}) {
+    $numFields = @{$attribs->{NAME}};
+
+with
+
+::
+
+    my $numFields;
+    if ($attribs->{'NUM_OF_FIELDS'}) {
+    $numFields = $attribs->{'NUM_OF_FIELDS'};
+    } elsif ($attribs->{'NAMES'}) {
+    $numFields = @{$attribs->{NAMES}};
+
+(note the S added to NAME.)
+
+.. _paranoid-security:
+
+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:
+::
+
+    cannot chdir(/var/spool/mqueue): Permission denied
+
+This is because your :file:`/var/spool/mqueue`
+directory has a mode of ``drwx------``.
+Type :command:`chmod 755 :file:`/var/spool/mqueue``
+as root to fix this problem. This will allow any process running on your
+machine the ability to *read* the
+:file:`/var/spool/mqueue` directory.
+
+.. _trbl-relogin-everyone:
+
+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 interface.
+
+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.
+
+.. _trbl-relogin-everyone-share:
+
+Examples of urlbase/cookiepath pairs for sharing login cookies
+==============================================================
+
+|    urlbase is http://bugzilla.mozilla.org/
+|    cookiepath is /
+
+
+|    urlbase is http://tools.mysite.tld/bugzilla/
+|    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.
+
+.. _trbl-relogin-everyone-restrict:
+
+Examples of urlbase/cookiepath pairs to restrict the login cookie
+=================================================================
+
+|    urlbase is http://landfill.bugzilla.org/bugzilla-tip/
+|    cookiepath is /bugzilla-tip/
+
+|    urlbase is http://landfill.bugzilla.org/bugzilla-4.0-branch/
+|    cookiepath is /bugzilla-4.0-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).
+
+.. _trbl-index:
+
+:file:`index.cgi` doesn't show up unless specified in the URL
+#############################################################
+
+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.
+
+If you are using Apache, you can do this by adding
+:file:`index.cgi` to the end of the
+``DirectoryIndex`` line
+as mentioned in :ref:`http-apache`.
+
+.. _trbl-passwd-encryption:
+
+checksetup.pl reports "Client does not support authentication protocol requested by server..."
+##############################################################################################
+
+This error is occurring because you are using the new password
+encryption that comes with MySQL 4.1, while your
+:file:`DBD::mysql` module was compiled against an
+older version of MySQL. If you recompile :file:`DBD::mysql`
+against the current MySQL libraries (or just obtain a newer version
+of this module) then the error may go away.
+
+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:
+`<http://dev.mysql.com/doc/mysql/en/Old_client.html>`_
+
+