1995 lines
75 KiB
XML
1995 lines
75 KiB
XML
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
|
|
<!-- $Id: installation.xml,v 1.56 2004-01-15 22:34:35 gerv%gerv.net Exp $ -->
|
|
<chapter id="installation">
|
|
<title>Installation</title>
|
|
|
|
<section id="stepbystep">
|
|
<title>Step-by-step Install</title>
|
|
|
|
<para>Bugzilla has been successfully installed under many different
|
|
operating systems including almost all Unix clones and
|
|
<productname class="registered">Microsoft Windows</productname>. Many
|
|
operating systems have utilities that make installation easier or quirks
|
|
that make it harder. We have tried to collect that information in
|
|
<xref linkend="os-specific"/>, so be sure to check out that section before
|
|
you start your installation.
|
|
</para>
|
|
|
|
<note>
|
|
<para>Windows is one of those operating systems that has many quirks
|
|
and is not yet officially supported by the Bugzilla team. If you wish
|
|
to install Bugzilla on Windows, be sure to see
|
|
<xref linkend="os-win32"/>.
|
|
</para>
|
|
</note>
|
|
|
|
<warning>
|
|
<para>While installing Bugzilla, it is a good idea to ensure that there
|
|
is some kind of firewall between you and the rest of the Internet
|
|
as your machine may be insecure for periods during the install. Many
|
|
installation steps require an active Internet connection to complete,
|
|
but you must take care to ensure that at no point is your machine
|
|
vulnerable to an attack.</para>
|
|
</warning>
|
|
|
|
<para>This guide assumes that you already have your operating system
|
|
installed, network configured, and have administrative access to the
|
|
shell on the machine you are installing Bugzilla onto. It is possible to
|
|
install and run Bugzilla without administrative access, but you have to
|
|
either make sure all the required software is installed or get somebody
|
|
with administrative access to install it for you.
|
|
</para>
|
|
|
|
<para>
|
|
You are strongly recommended to make a backup of your system
|
|
before installing Bugzilla and at regular intervals thereafter.
|
|
</para>
|
|
|
|
<para>The listing below is a basic step-by-step list. More information
|
|
can be found in the sections below. Minimum versions will be
|
|
included in parenthesis where appropriate.
|
|
</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para><link linkend="install-perl">Install Perl</link>
|
|
(&min-perl-ver;)
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-mysql">Install MySQL</link>
|
|
(&min-mysql-ver;)
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-webserver">Install a Webserver</link>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-bzfiles">Put Bugzilla in the Webspace</link>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-perlmodules">Install Perl Modules</link>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-setupdatabase">Setup the MySQL Database</link>
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<section id="install-perl">
|
|
<title>Perl</title>
|
|
|
|
<para>Any machine that doesn't have Perl on it is a sad machine indeed.
|
|
Perl can be got in source form from <ulink url="http://www.perl.com"/>.
|
|
There are also binary versions available for many platforms, most of which
|
|
are linked to from perl.com.
|
|
Although Bugzilla runs with perl &min-perl-ver;,
|
|
it's a good idea to be up to the very latest version
|
|
if you can when running Bugzilla. As of this writing, that is Perl
|
|
version &newest-perl-ver;.</para>
|
|
</section>
|
|
|
|
<section id="install-mysql">
|
|
<title>MySQL</title>
|
|
|
|
<para>Visit the MySQL homepage at
|
|
<ulink url="http://www.mysql.com"/>
|
|
to grab and install the latest stable release of the server.
|
|
</para>
|
|
|
|
<note>
|
|
<para> Many of the binary
|
|
versions of MySQL store their data files in
|
|
<filename class="directory">/var</filename>.
|
|
On some Unix systems, this is part of a smaller root partition,
|
|
and may not have room for your bug database. You can set the data
|
|
directory as an option to <filename>configure</filename>
|
|
if you build MySQL from source yourself.</para>
|
|
</note>
|
|
|
|
<para>If you install from something other than a packaging/installation
|
|
system (such as .rpm, .dep, .exe, or .msi) you will need to configure
|
|
your system so the MySQL server daemon will come back up whenever
|
|
your machine reboots.
|
|
</para>
|
|
|
|
<para>If you wish to have attachments larger than 64K, you will have to
|
|
configure MySQL to accept large packets. This is done by adding the text
|
|
in <xref linkend="install-mysql-packets"/> to your
|
|
<filename>my.conf</filename> file. There is also a parameter in Bugzilla
|
|
for setting the maximum allowable attachment size.
|
|
<!-- TODO: xref to a param() page for max attachment size -->
|
|
You should set this value to be slightly larger than that parameter.
|
|
</para>
|
|
|
|
<figure id="install-mysql-packets">
|
|
<title>Set Max Packet Size in MySQL</title>
|
|
|
|
<programlisting>
|
|
[mysqld]
|
|
# Allow packets up to 1M
|
|
set-variable = max_allowed_packet=1M
|
|
</programlisting>
|
|
</figure>
|
|
|
|
<para>If you are running Bugzilla and MySQL on the same machine, you may
|
|
also wish to utilize the <option>skip-networking</option> option as
|
|
mentioned in <xref linkend="security-mysql"/> for the added security.
|
|
</para>
|
|
|
|
<section id="install-setupdatabase">
|
|
<title>Configuring MySQL</title>
|
|
|
|
<para>This first thing you'll want to do is make sure you've given the
|
|
<quote>root</quote> user a password as suggested in
|
|
<xref linkend="security-mysql"/>. For clarity, these instructions will
|
|
assume that your MySQL user for Bugzilla will be <quote>bugs_user</quote>,
|
|
the database will be called <quote>bugs_db</quote> and the password for
|
|
the <quote>bugs_user</quote> user is <quote>bugs_password</quote>. You
|
|
should, of course, substitute the values you intend to use for your site.
|
|
</para>
|
|
|
|
<note>
|
|
<para>Most people use <quote>bugs</quote> for both the user and
|
|
database name.
|
|
</para>
|
|
</note>
|
|
|
|
<para>Next, we use an SQL <command>GRANT</command> command to create a
|
|
<quote>bugs_user</quote>
|
|
user, and grant sufficient permissions for checksetup.pl, which we'll
|
|
use later, to work its magic. This also restricts the
|
|
<quote>bugs_user</quote>
|
|
user to operations within a database called
|
|
<quote>bugs_db</quote>, and only allows the account to connect from
|
|
<quote>localhost</quote>.
|
|
Modify it to reflect your setup if you will be connecting from
|
|
another machine or as a different user.</para>
|
|
|
|
<screen>
|
|
<prompt>mysql></prompt> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,
|
|
DROP,REFERENCES ON bugs_db.* TO bugs_user@localhost
|
|
IDENTIFIED BY 'bugs_password';
|
|
<prompt>mysql></prompt> FLUSH PRIVILEGES;
|
|
</screen>
|
|
|
|
<note>
|
|
<para>If you are using MySQL 4, the bugs user also needs to be granted
|
|
the <computeroutput>LOCK TABLES</computeroutput> and
|
|
<computeroutput>CREATE TEMPORARY TABLES</computeroutput> permissions.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="install-webserver">
|
|
<title>HTTP Server</title>
|
|
|
|
<para>You have freedom of choice here, pretty much any web server that
|
|
is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
|
|
scripts will work. <xref linkend="http"/> has more information about
|
|
configuring web servers to work with Bugzilla.
|
|
</para>
|
|
|
|
<note>
|
|
<para>We strongly recommend Apache as the web server to use. The
|
|
Bugzilla Guide installation instructions, in general, assume you are
|
|
using Apache. If you have got Bugzilla working using another webserver,
|
|
please share your experiences with us by filing a bug in &bzg-bugs;.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section id="install-bzfiles">
|
|
<title>Bugzilla</title>
|
|
|
|
<para>You should untar the Bugzilla files into a directory that you're
|
|
willing to make writable by the default web server user (probably
|
|
<quote>nobody</quote>).
|
|
You may decide to put the files in the main web space for your
|
|
web server or perhaps in
|
|
<filename>/usr/local</filename>
|
|
with a symbolic link in the web space that points to the Bugzilla
|
|
directory.</para>
|
|
|
|
<tip>
|
|
<para>If you symlink the bugzilla directory into your Apache's HTML
|
|
hierarchy, you may receive
|
|
<errorname>Forbidden</errorname>
|
|
errors unless you add the
|
|
<quote>FollowSymLinks</quote>
|
|
directive to the <Directory> entry for the HTML root
|
|
in httpd.conf.</para>
|
|
</tip>
|
|
|
|
<para>Once all the files are in a web accessible directory, make that
|
|
directory writable by your webserver's user. This is a temporary step
|
|
until you run the post-install
|
|
<filename>checksetup.pl</filename>
|
|
script, which locks down your installation.</para>
|
|
|
|
<caution>
|
|
<para>The default Bugzilla distribution is not designed to be placed
|
|
in a <filename class="directory">cgi-bin</filename> directory (this
|
|
includes any directory which is configured using the
|
|
<option>ScriptAlias</option> directive of Apache).
|
|
</para>
|
|
</caution>
|
|
</section>
|
|
|
|
<section id="install-perlmodules">
|
|
<title>Perl Modules</title>
|
|
|
|
<para>Perl modules can be found using
|
|
<glossterm linkend="gloss-cpan">CPAN</glossterm> on Unix based systems or
|
|
<glossterm linkend="gloss-ppm">PPM</glossterm> on Win32. The root servers
|
|
have a real tendency to bog down, so please use mirrors.
|
|
</para>
|
|
|
|
<para>Good instuctions can be found for using each of these services on
|
|
their respective websites. The basics can be found in
|
|
<xref linkend="install-perlmodules-cpan"/> for CPAN and
|
|
<xref linkend="win32-perlmodules"/> for PPM.
|
|
</para>
|
|
|
|
<example id="install-perlmodules-cpan">
|
|
<title>Installing perl modules with CPAN</title>
|
|
|
|
<para>The easy way:
|
|
<screen>
|
|
<prompt>bash#</prompt> perl -MCPAN -e 'install "<modulename>"'
|
|
</screen>
|
|
</para>
|
|
|
|
<para>Or the hard way:
|
|
<screen>
|
|
<prompt>bash#</prompt> tar xzvf <module>.tar.gz <co id="cpan-moduletar"/>
|
|
<prompt>bash#</prompt> cd <module> <co id="cpan-moduledir"/>
|
|
<prompt>bash#</prompt> perl Makefile.PL
|
|
<prompt>bash#</prompt> make
|
|
<prompt>bash#</prompt> make test
|
|
<prompt>bash#</prompt> make install
|
|
</screen>
|
|
<calloutlist>
|
|
<callout arearefs="cpan-moduletar">
|
|
<para>This assumes that you've already downloaded the
|
|
<filename><module>.tar.gz</filename> to the current working
|
|
directory.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="cpan-moduledir">
|
|
<para>The process of untarring the module as defined in
|
|
<xref linkend="cpan-moduletar"/> will create the
|
|
<filename class="directory"><module></filename> directory.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
</example>
|
|
|
|
<tip>
|
|
<para>Many people complain that Perl modules will not install for
|
|
them. Most times, the error messages complain that they are missing a
|
|
file in
|
|
<quote>@INC</quote>.
|
|
Virtually every time, this error is due to permissions being set too
|
|
restrictively for you to compile Perl modules or not having the
|
|
necessary Perl development libraries installed on your system.
|
|
Consult your local UNIX systems administrator for help solving these
|
|
permissions issues; if you
|
|
<emphasis>are</emphasis>
|
|
the local UNIX sysadmin, please consult the newsgroup/mailing list
|
|
for further assistance or hire someone to help you out.</para>
|
|
</tip>
|
|
|
|
|
|
<para>Perl Modules (minimum version):
|
|
<orderedlist>
|
|
|
|
<!-- TODO: Don't think we actually care about AppConfig anymore -->
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-bundle-bugzilla">Bundle::Bugzilla</link>
|
|
(Will allow you to skip the rest)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-appconfig">AppConfig</link>
|
|
(&min-appconfig-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-cgi">CGI</link>
|
|
(&min-cgi-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-data-dumper">Data::Dumper</link>
|
|
(&min-data-dumper-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-date-format">Date::Format</link>
|
|
(&min-date-format-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-dbi">DBI</link>
|
|
(&min-dbi-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-dbd-mysql">DBD::mysql</link>
|
|
(&min-dbd-mysql-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-file-spec">File::Spec</link>
|
|
(&min-file-spec-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-file-temp">File::Temp</link>
|
|
(&min-file-temp-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-template">Template Toolkit</link>
|
|
(&min-template-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-text-wrap">Text::Wrap</link>
|
|
(&min-text-wrap-ver;)
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
and, optionally:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-gd">GD</link>
|
|
(&min-gd-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-chart-base">Chart::Base</link>
|
|
(&min-chart-base-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-xml-parser">XML::Parser</link>
|
|
(&min-xml-parser-ver;) for the XML interface
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-gd-graph">GD::Graph</link>
|
|
(&min-gd-graph-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-gd-text-align">GD::Text::Align</link>
|
|
(&min-gd-text-align-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-mime-parser">MIME::Parser</link>
|
|
(&min-mime-parser-ver;) for the email interface
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-patchreader">PatchReader</link>
|
|
(&min-patchreader-ver;) for pretty HTML view of patches
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
|
|
<section id="install-modules-bundle-bugzilla">
|
|
<title>Bundle::Bugzilla</title>
|
|
|
|
<para>If you are running at least perl 5.6.1, you can save yourself a lot
|
|
of time by using Bundle::Bugzilla. This bundle contains every module
|
|
required to get Bugzilla running. It does not include GD and friends, but
|
|
these are not required for a base install and can always be added later
|
|
if the need arises.
|
|
</para>
|
|
|
|
<para>Assuming your perl was installed with CPAN (most unix installations
|
|
are), using Bundle::Bugzilla is really easy. Simply follow along with the
|
|
commands below.
|
|
</para>
|
|
|
|
|
|
<screen>
|
|
<prompt>bash#</prompt> <command>perl -MCPAN -eshell</command> <co id="bundle-cpanconfig"/>
|
|
cpan shell -- CPAN exploration and modules installation (v1.63)
|
|
ReadLine support enabled
|
|
|
|
<prompt>cpan></prompt>
|
|
|
|
</screen>
|
|
|
|
<calloutlist>
|
|
<callout arearefs="bundle-cpanconfig">
|
|
<para>At this point, unless you've used CPAN on this machine before,
|
|
you'll have to go through a series of configuration steps.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</section>
|
|
|
|
<section id="install-modules-appconfig">
|
|
<title>AppConfig (&min-appconfig-ver;)</title>
|
|
|
|
<para>Dependency for Template Toolkit. We probably don't need to
|
|
specifically check for it anymore.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-modules-cgi">
|
|
<title>CGI (&min-cgi-ver;)</title>
|
|
|
|
<para>The CGI module parses form elements and cookies and does many
|
|
other usefule things. It come as a part of recent perl distributions, but
|
|
Bugzilla needs a fairly new version.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/CGI.pm/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/CGI.zip"/>
|
|
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/CGI.html"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-data-dumper">
|
|
<title>Data::Dumper (&min-data-dumper-ver;)</title>
|
|
|
|
<para>The Data::Dumper module provides data structure persistence for
|
|
Perl (similar to Java's serialization). It comes with later
|
|
sub-releases of Perl 5.004, but a re-installation just to be sure it's
|
|
available won't hurt anything.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Data-Dumper/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/Data-Dumper.zip"/>
|
|
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/Data/Dumper.html"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-date-format">
|
|
<title>TimeDate modules (&min-date-format-ver;)</title>
|
|
|
|
<para>Many of the more common date/time/calendar related Perl modules
|
|
have been grouped into a bundle similar to the MySQL modules bundle.
|
|
This bundle is stored on the CPAN under the name TimeDate.
|
|
The component module we're most interested in is the Date::Format
|
|
module, but installing all of them is probably a good idea anyway.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/TimeDate/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/TimeDate.zip"/>
|
|
Documentation: <ulink url="http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-dbi">
|
|
<title>DBI (&min-dbi-ver;)</title>
|
|
|
|
<para>The DBI module is a generic Perl module used the
|
|
MySQL-related modules. As long as your Perl installation was done
|
|
correctly the DBI module should be a breeze. It's a mixed Perl/C
|
|
module, but Perl's MakeMaker system simplifies the C compilation
|
|
greatly.</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBI/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBI.zip"/>
|
|
Documentation: <ulink url="http://dbi.perl.org/doc/"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-dbd-mysql">
|
|
<title>MySQL-related modules</title>
|
|
|
|
<para>The Perl/MySQL interface requires a few mutually-dependent Perl
|
|
modules. These modules are grouped together into the the
|
|
Msql-Mysql-modules package.</para>
|
|
|
|
<para>The MakeMaker process will ask you a few questions about the
|
|
desired compilation target and your MySQL installation. For most of the
|
|
questions the provided default will be adequate, but when asked if your
|
|
desired target is the MySQL or mSQL packages, you should
|
|
select the MySQL related ones. Later you will be asked if you wish to
|
|
provide backwards compatibility with the older MySQL packages; you
|
|
should answer YES to this question. The default is NO.</para>
|
|
|
|
<para>A host of 'localhost' should be fine and a testing user of 'test'
|
|
with a null password should find itself with sufficient access to run
|
|
tests on the 'test' database which MySQL created upon installation.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-mysql/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBD-Mysql.zip"/>
|
|
Documentation: <ulink url="http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pod"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-file-spec">
|
|
<title>File::Spec (&min-file-spec-ver;)</title>
|
|
|
|
<para>File::Spec is a perl module that allows file operations, such as
|
|
generating full path names, to work cross platform.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/>
|
|
PPM Download Page: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/File-Spec.zip"/>
|
|
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Spec.html"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-file-temp">
|
|
<title>File::Temp (&min-file-temp-ver;)</title>
|
|
|
|
<para>File::Temp is used to generate a temporary filename that is
|
|
guaranteed to be unique. It comes as a standard part of perl
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/File-Spec.zip"/>
|
|
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Temp.html"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-template">
|
|
<title>Template Toolkit (&min-template-ver;)</title>
|
|
|
|
<para>When you install Template Toolkit, you'll get asked various
|
|
questions about features to enable. The defaults are fine, except
|
|
that it is recommended you use the high speed XS Stash of the Template
|
|
Toolkit, in order to achieve best performance.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-Toolkit/"/>
|
|
PPM Download Link: <ulink url="http://openinteract.sourceforge.net/ppmpackages/5.6/Template-Toolkit.tar.gz"/>
|
|
Documentation: <ulink url="http://www.template-toolkit.org/docs.html"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-text-wrap">
|
|
<title>Text::Wrap (&min-text-wrap-ver;)</title>
|
|
|
|
<para>Text::Wrap is designed to proved intelligent text wrapping.
|
|
</para>
|
|
|
|
<!-- TODO: Text::Wrap doesn't seem to be available from ActiveState -->
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Text-Tabs+Wrap/"/>
|
|
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/Text/Wrap.html"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
|
|
<section id="install-modules-gd">
|
|
<title>GD (&min-gd-ver;) [optional]</title>
|
|
|
|
<para>The GD library was written by Thomas Boutell a long while ago to
|
|
programmatically generate images in C. Since then it's become the
|
|
defacto standard for programmatic image construction. The Perl bindings
|
|
to it found in the GD library are used on millions of web pages to
|
|
generate graphs on the fly. That's what Bugzilla will be using it for
|
|
so you must install it if you want any of the graphing to work.</para>
|
|
|
|
<note>
|
|
<para>The Perl GD library requires some other libraries that may or
|
|
may not be installed on your system, including
|
|
<classname>libpng</classname>
|
|
and
|
|
<classname>libgd</classname>.
|
|
The full requirements are listed in the Perl GD library README.
|
|
If compiling GD fails, it's probably because you're
|
|
missing a required library.</para>
|
|
</note>
|
|
|
|
<tip>
|
|
<para>The version of the GD perl module you need is very closely tied
|
|
to the <classname>libgd</classname> version installed on your system.
|
|
If you have a version 1.x of <classname>libgd</classname> the 2.x
|
|
versions of the GD perl module won't work for you.
|
|
</para>
|
|
</tip>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GD/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GD.zip"/>
|
|
Documentation: <ulink url="http://stein.cshl.org/WWW/software/GD/"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-chart-base">
|
|
<title>Chart::Base (&min-chart-base-ver;) [optional]</title>
|
|
|
|
<para>The Chart module provides Bugzilla with on-the-fly charting
|
|
abilities. It can be installed in the usual fashion after it has been
|
|
fetched from CPAN.
|
|
Note that earlier versions that 0.99c used GIFs, which are no longer
|
|
supported by the latest versions of GD.</para>
|
|
|
|
<!-- TODO: Chart::Base doesn't seem to have any documentation -->
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/Chart.zip"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-xml-parser">
|
|
<title>XML::Parser (&min-xml-parser-ver;) [Optional]</title>
|
|
|
|
<para>XML::Parser is used by the <filename>importxml.pl</filename>
|
|
script. You only need it if you are going to be importing bugs (such as
|
|
for bug moving). XML::Parser requires that the
|
|
<classname>expat</classname> library is already installed on your machine.
|
|
</para>
|
|
|
|
<!-- TODO: XML::Parser - the only PPM I see is XML-Parser-EasyTree.zip;
|
|
I'm not sure if it's the same thing or not. -->
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Parser/"/>
|
|
Documentation: <ulink url="http://www.perldoc.com/perl5.6.1/lib/XML/Parser.html"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-gd-graph">
|
|
<title>GD::Graph (&min-gd-graph-ver;) [Optional]</title>
|
|
|
|
<para>In addition to GD listed above, the reporting interface of Bugzilla
|
|
needs to have the GD::Graph module installed.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDGraph/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDGraph.zip"/>
|
|
Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-gd-text-align">
|
|
<title>GD::Text::Align (&min-gd-text-align-ver;) [Optional]</title>
|
|
|
|
<para>GD::Text::Align, as the name implies, is used to draw aligned
|
|
strings of text. It is needed by the reporting interface.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDTextUtil/"/>
|
|
PPM Download Page: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDTextUtil.zip"/>
|
|
Documentation: <ulink url="http://search.cpan.org/dist/GDTextUtil/Text/Align.pm"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-mime-parser">
|
|
<title>MIME::Parser (&min-mime-parser-ver;) [Optional]</title>
|
|
|
|
<para>MIME::Parser is only needed if you want to use the e-mail interface
|
|
located in the <filename class="directory">contrib</filename> directory.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/>
|
|
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/MIME-tools.zip"/>
|
|
Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/>
|
|
</literallayout>
|
|
</section>
|
|
|
|
<section id="install-modules-patchreader">
|
|
<title>PatchReader (&min-patchreader-ver;) [Optional]</title>
|
|
|
|
<para>PatchReader is only needed if you want to use Patch Viewer, a
|
|
Bugzilla feature to format patches in a pretty HTML fashion. There are a
|
|
number of optional parameters you can configure Patch Viewer with as well,
|
|
including cvsroot, cvsroot_get, lxr_root, bonsai_url, lxr_url, and
|
|
lxr_root. Patch Viewer also optionally will use cvs, diff and interdiff
|
|
utilities if they exist on the system (interdiff can be found in the
|
|
patchutils package at <ulink url="http://cyberelk.net/tim/patchutils/"/>.
|
|
These programs' locations can be configured in localconfig.
|
|
</para>
|
|
|
|
<literallayout>
|
|
CPAN Download Page: <ulink url="http://search.cpan.org/author/JKEISER/PatchReader/"/>
|
|
Documentation: <ulink url="http://www.johnkeiser.com/mozilla/Patch_Viewer.html"/>
|
|
</literallayout>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>
|
|
<filename>checksetup.pl</filename>
|
|
</title>
|
|
|
|
<para>Next, run the magic checksetup.pl script.
|
|
This is designed to make sure your perl modules are the correct
|
|
version and your MySQL database and other
|
|
configuration options are consistent with the Bugzilla CGI files.
|
|
It will make sure Bugzilla files and directories have reasonable
|
|
permissions, set up the
|
|
<filename>data</filename>
|
|
directory, and create all the MySQL tables.
|
|
</para>
|
|
|
|
<screen>
|
|
<prompt>bash#</prompt> ./checksetup.pl
|
|
</screen>
|
|
|
|
<para>
|
|
The first time you run it, it will create a file called
|
|
<filename>localconfig</filename>.</para>
|
|
|
|
<para>This file contains a variety of settings you may need to tweak
|
|
including how Bugzilla should connect to the MySQL database.</para>
|
|
|
|
<para>The connection settings include:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>server's host: just use
|
|
<quote>localhost</quote>
|
|
if the MySQL server is local</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>database name:
|
|
<quote>bugs_db</quote>
|
|
if you're following these directions</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>MySQL username:
|
|
<quote>bugs_user</quote>
|
|
if you're following these directions</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Password for the
|
|
<quote>bugs_user</quote>
|
|
MySQL account; (<quote>bugs_password</quote> above)</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>Once you are happy with the settings,
|
|
<filename>su</filename> to the user
|
|
your web server runs as, and re-run
|
|
<filename>checksetup.pl</filename>. (Note: on some security-conscious
|
|
systems, you may need to change the login shell for the webserver
|
|
account before you can do this.)
|
|
On this second run, it will create the database and an administrator
|
|
account for which you will be prompted to provide information.</para>
|
|
|
|
<note>
|
|
<para>The checksetup.pl script is designed so that you can run it at
|
|
any time without causing harm. You should run it after any upgrade to
|
|
Bugzilla.</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Configuring Bugzilla</title>
|
|
<para>
|
|
You should run through the parameters on the Edit Parameters page
|
|
(link in the footer) and set them all to appropriate values.
|
|
They key parameters are documented in <xref linkend="parameters" />.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="http">
|
|
<title>HTTP Server Configuration</title>
|
|
|
|
<para>The Bugzilla Team recommends Apache when using Bugzilla, however, any web server
|
|
that can be configured to run <glossterm linkend="gloss-cgi">CGI</glossterm> scripts
|
|
should be able to handle Bugzilla. No matter what web server you choose, but
|
|
especially if you choose something other than Apache, you should be sure to read
|
|
<xref linkend="security-access"/>.
|
|
</para>
|
|
|
|
<para>The plan for this section is to eventually document the specifics of how to lock
|
|
down permissions on individual web servers.
|
|
</para>
|
|
|
|
<section id="http-apache">
|
|
<title>Apache <productname>httpd</productname></title>
|
|
|
|
<para>You will have to make sure that Apache is properly
|
|
configured to run the Bugzilla CGI scripts. You also need to make sure
|
|
that the <filename>.htaccess</filename> files created by
|
|
<command>./checksetup.pl</command> are allowed to override Apache's normal access
|
|
permissions or else important password information may be exposed to the
|
|
Internet.
|
|
</para>
|
|
|
|
<para>You need to configure Apache to run .cgi files outside the
|
|
<filename class="directory">cgi-bin</filename> directory.
|
|
Open your
|
|
<filename>httpd.conf</filename> file and make sure the
|
|
following line exists and is uncommented:</para>
|
|
<programlisting>
|
|
AddHandler cgi-script .cgi
|
|
</programlisting>
|
|
|
|
<para>To allow <filename>.htaccess</filename> files to override
|
|
permissions and .cgi files to run in the Bugzilla directory, make sure
|
|
the following two lines are in a <computeroutput>Directory</computeroutput>
|
|
directive that applies to the Bugzilla directory on your system
|
|
(either the Bugzilla directory or one of its parents).
|
|
</para>
|
|
<programlisting>
|
|
Options +ExecCGI
|
|
AllowOverride Limit
|
|
</programlisting>
|
|
|
|
<para>You should modify the <DirectoryIndex> parameter for
|
|
the Apache virtual host running your Bugzilla installation to
|
|
allow <filename>index.cgi</filename> as the index page for a
|
|
directory, as well as the usual <filename>index.html</filename>,
|
|
<filename>index.htm</filename>, and so forth. </para>
|
|
|
|
<note>
|
|
<para>For more information on Apache and its directives, see the
|
|
glossary entry on <xref linkend="gloss-apache"/>.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="http-iis">
|
|
<title>Microsoft <productname>Internet Information Services</productname></title>
|
|
|
|
<para>If you need, or for some reason even want, to use Microsoft's
|
|
<productname>Internet Information Services</productname> or
|
|
<productname>Personal Web Server</productname> you should be able
|
|
to. You will need to configure them to know how to run CGI scripts,
|
|
however. This is described in Microsoft Knowledge Base article
|
|
<ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225</ulink>
|
|
for <productname>Internet Information Services</productname> and
|
|
<ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink>
|
|
for <productname>Personal Web Server</productname>.
|
|
</para>
|
|
|
|
<para>Also, and this can't be stressed enough, make sure that files such as
|
|
<filename>localconfig</filename> and your <filename class="directory">data</filename>
|
|
directory are secured as described in <xref linkend="security-access"/>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="http-aol">
|
|
<title>AOL Server</title>
|
|
|
|
<para>Ben FrantzDale reported success using AOL Server with Bugzilla. He
|
|
reported his experience and what appears below is based on that.
|
|
</para>
|
|
|
|
<para>AOL Server will have to be configured to run
|
|
<glossterm linkend="gloss-cgi">CGI</glossterm> scripts, please consult
|
|
the documentation that came with your server for more information on
|
|
how to do this.
|
|
</para>
|
|
|
|
<para>Because AOL Server doesn't support <filename>.htaccess</filename>
|
|
files, you'll have to create a <glossterm linkend="gloss-tcl">TCL</glossterm>
|
|
script. You should create an <filename>aolserver/modules/tcl/filter.tcl</filename>
|
|
file (the filename shouldn't matter) with the following contents (change
|
|
<computeroutput>/bugzilla/</computeroutput> to the web-based path to
|
|
your Bugzilla installation):
|
|
</para>
|
|
|
|
<programlisting>
|
|
ns_register_filter preauth GET /bugzilla/localconfig filter_deny
|
|
ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny
|
|
ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny
|
|
ns_register_filter preauth GET /bugzilla/*.pl filter_deny
|
|
ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny
|
|
ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny
|
|
ns_register_filter preauth GET /bugzilla/data/* filter_deny
|
|
ns_register_filter preauth GET /bugzilla/template/* filter_deny
|
|
|
|
proc filter_deny { why } {
|
|
ns_log Notice "filter_deny"
|
|
return "filter_return"
|
|
}
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>This probably doesn't account for all possible editor backup
|
|
files so you may wish to add some additional variations of
|
|
<filename>localconfig</filename>. For more information, see
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">
|
|
bug 186383</ulink> or <ulink
|
|
url="http://online.securityfocus.com/bid/6501">Bugtraq ID 6501</ulink>.
|
|
</para>
|
|
</warning>
|
|
|
|
<note>
|
|
<para>If you are using webdot from research.att.com (the default
|
|
configuration for the <option>webdotbase</option> paramater), you
|
|
will need to allow access to <filename>data/webdot/*.dot</filename>
|
|
for the reasearch.att.com machine.
|
|
</para>
|
|
<para>If you are using a local installation of <ulink
|
|
url="http://www.graphviz.org">GraphViz</ulink>, you will need to allow
|
|
everybody to access <filename>*.png</filename>,
|
|
<filename>*.gif</filename>, <filename>*.jpg</filename>, and
|
|
<filename>*.map</filename> in the
|
|
<filename class="directory">data/webdot</filename> directory.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="extraconfig">
|
|
<title>Optional Additional Configuration</title>
|
|
|
|
<section>
|
|
<title>Dependency Charts</title>
|
|
|
|
<para>As well as the text-based dependency graphs, Bugzilla also
|
|
supports dependency graphing, using a package called 'dot'.
|
|
Exactly how this works is controlled by the 'webdotbase' parameter,
|
|
which can have one of three values:
|
|
</para>
|
|
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
A complete file path to the command 'dot' (part of
|
|
<ulink url="http://www.graphviz.org/">GraphViz</ulink>)
|
|
will generate the graphs locally
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A URL prefix pointing to an installation of the webdot package will
|
|
generate the graphs remotely
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A blank value will disable dependency graphing.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>So, to get this working, install
|
|
<ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you
|
|
do that, you need to
|
|
<ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable
|
|
server-side image maps</ulink> in Apache.
|
|
Alternatively, you could set up a webdot server, or use the AT&T
|
|
public webdot server (the
|
|
default for the webdotbase param). Note that AT&T's server won't work
|
|
if Bugzilla is only accessible using HARTS.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Bug Graphs</title>
|
|
|
|
<para>As long as you installed the GD and Graph::Base Perl modules you
|
|
might as well turn on the nifty Bugzilla bug reporting graphs.</para>
|
|
|
|
<para>Add a cron entry like this to run
|
|
<filename>collectstats.pl</filename>
|
|
daily at 5 after midnight:
|
|
<simplelist>
|
|
<member>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
|
|
<command>crontab -e</command>
|
|
</computeroutput>
|
|
</member>
|
|
|
|
<member>
|
|
<computeroutput>5 0 * * * cd <your-bugzilla-directory> ;
|
|
./collectstats.pl</computeroutput>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
<para>After two days have passed you'll be able to view bug graphs from
|
|
the Bug Reports page.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>The Whining Cron</title>
|
|
|
|
<para>By now you have a fully functional Bugzilla, but what good are
|
|
bugs if they're not annoying? To help make those bugs more annoying you
|
|
can set up Bugzilla's automatic whining system to complain at engineers
|
|
which leave their bugs in the NEW state without triaging them.
|
|
</para>
|
|
<para>
|
|
This can be done by
|
|
adding the following command as a daily crontab entry (for help on that
|
|
see that crontab man page):
|
|
<simplelist>
|
|
<member>
|
|
<computeroutput>
|
|
<command>cd <your-bugzilla-directory> ;
|
|
./whineatnews.pl</command>
|
|
</computeroutput>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
<tip>
|
|
<para>Depending on your system, crontab may have several manpages.
|
|
The following command should lead you to the most useful page for
|
|
this purpose:
|
|
<programlisting>
|
|
man 5 crontab
|
|
</programlisting>
|
|
</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="bzldap">
|
|
<title>LDAP Authentication</title>
|
|
|
|
<para>LDAP authentication is a module for Bugzilla's plugin
|
|
authentication architecture.
|
|
</para>
|
|
|
|
<para>
|
|
The existing authentication
|
|
scheme for Bugzilla uses email addresses as the primary user ID, and a
|
|
password to authenticate that user. All places within Bugzilla where
|
|
you need to deal with user ID (e.g assigning a bug) use the email
|
|
address. The LDAP authentication builds on top of this scheme, rather
|
|
than replacing it. The initial log in is done with a username and
|
|
password for the LDAP directory. This then fetches the email address
|
|
from LDAP and authenticates seamlessly in the standard Bugzilla
|
|
authentication scheme using this email address. If an account for this
|
|
address already exists in your Bugzilla system, it will log in to that
|
|
account. If no account for that email address exists, one is created at
|
|
the time of login. (In this case, Bugzilla will attempt to use the
|
|
"displayName" or "cn" attribute to determine the user's full name.)
|
|
After authentication, all other user-related tasks are still handled by
|
|
email address, not LDAP username. You still assign bugs by email
|
|
address, query on users by email address, etc.
|
|
</para>
|
|
|
|
<caution>
|
|
<para>Because the Bugzilla account is not created until the first time
|
|
a user logs in, a user who has not yet logged is unknown to Bugzilla.
|
|
This means they cannot be used as an assignee or QA contact (default or
|
|
otherwise), added to any cc list, or any other such operation. One
|
|
possible workaround is the <filename>bugzilla_ldapsync.rb</filename>
|
|
script in the
|
|
<glossterm linkend="gloss-contrib"><filename class="directory">contrib</filename></glossterm> directory. Another possible solution is fixing
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug
|
|
201069</ulink>.
|
|
</para>
|
|
</caution>
|
|
|
|
<para>Parameters required to use LDAP Authentication:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="param-loginmethod">
|
|
<term>loginmethod</term>
|
|
<listitem>
|
|
<para>This parameter should be set to <quote>LDAP</quote>
|
|
<emphasis>only</emphasis> if you will be using an LDAP directory
|
|
for authentication. If you set this param to <quote>LDAP</quote> but
|
|
fail to set up the other parameters listed below you will not be
|
|
able to log back in to Bugzilla one you log out. If this happens
|
|
to you, you will need to manually edit
|
|
<filename>data/params</filename> and set loginmethod to
|
|
<quote>DB</quote>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPserver">
|
|
<term>LDAPserver</term>
|
|
<listitem>
|
|
<para>This parameter should be set to the name (and optionally the
|
|
port) of your LDAP server. If no port is specified, it assumes
|
|
the default LDAP port of 389.
|
|
</para>
|
|
<para>Ex. <quote>ldap.company.com</quote>
|
|
or <quote>ldap.company.com:3268</quote>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPbinddn">
|
|
<term>LDAPbinddn [Optional]</term>
|
|
<listitem>
|
|
<para>Some LDAP servers will not allow an anonymous bind to search
|
|
the directory. If this is the case with your configuration you
|
|
should set the LDAPbinddn parameter to the user account Bugzilla
|
|
should use instead of the anonymous bind.
|
|
</para>
|
|
<para>Ex. <quote>cn=default,cn=user:password</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPBaseDN">
|
|
<term>LDAPBaseDN</term>
|
|
<listitem>
|
|
<para>The LDAPBaseDN parameter should be set to the location in
|
|
your LDAP tree that you would like to search for e-mail addresses.
|
|
Your uids should be unique under the DN specified here.
|
|
</para>
|
|
<para>Ex. <quote>ou=People,o=Company</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPuidattribute">
|
|
<term>LDAPuidattribute</term>
|
|
<listitem>
|
|
<para>The LDAPuidattribute parameter should be set to the attribute
|
|
which contains the unique UID of your users. The value retrieved
|
|
from this attribute will be used when attempting to bind as the
|
|
user to confirm their password.
|
|
</para>
|
|
<para>Ex. <quote>uid</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPmailattribute">
|
|
<term>LDAPmailattribute</term>
|
|
<listitem>
|
|
<para>The LDAPmailattribute parameter should be the name of the
|
|
attribute which contains the e-mail address your users will enter
|
|
into the Bugzilla login boxes.
|
|
</para>
|
|
<para>Ex. <quote>mail</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="content-type">
|
|
|
|
<title>Preventing untrusted Bugzilla content from executing malicious
|
|
Javascript code</title>
|
|
|
|
<para>It is possible for a Bugzilla attachment to contain malicious
|
|
Javascript
|
|
code, which would be executed in the domain of your Bugzilla, thereby
|
|
making it possible for the attacker to e.g. steal your login cookies.
|
|
Due to internationalization concerns, we are unable to
|
|
incorporate by default the code changes necessary to fulfill the CERT
|
|
advisory requirements mentioned in
|
|
<ulink
|
|
url="http://www.cert.org/tech_tips/malicious_code_mitigation.html/#3"/>.
|
|
If your installation is for an English speaking audience only, making the
|
|
change below will prevent this problem.
|
|
</para>
|
|
|
|
<para>Simply locate the following line in
|
|
<filename>Bugzilla/CGI.pm</filename>:
|
|
<programlisting>
|
|
$self->charset('');
|
|
</programlisting>
|
|
and change it to:
|
|
<programlisting>
|
|
$self->charset('ISO-8859-1');
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="mod_perl" xreflabel="Bugzilla and mod_perl">
|
|
<title>
|
|
Bugzilla and <filename>mod_perl</filename>
|
|
</title>
|
|
<para>Bugzilla is unsupported under mod_perl. Effort is underway
|
|
to make it work cleanly in a mod_perl environment, but it is
|
|
slow going.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="mod-throttle"
|
|
xreflabel="Using mod_throttle to prevent Denial of Service attacks">
|
|
<title>
|
|
<filename>mod_throttle</filename>
|
|
|
|
and Security</title>
|
|
|
|
<para>It is possible for a user, by mistake or on purpose, to access
|
|
the database many times in a row which can result in very slow access
|
|
speeds for other users. If your Bugzilla installation is experiencing
|
|
this problem , you may install the Apache module
|
|
<filename>mod_throttle</filename>
|
|
|
|
which can limit connections by ip-address. You may download this module
|
|
at
|
|
<ulink url="http://www.snert.com/Software/mod_throttle/"/>.
|
|
Follow the instructions to install into your Apache install.
|
|
<emphasis>This module only functions with the Apache web
|
|
server!</emphasis>
|
|
You may use the
|
|
<command>ThrottleClientIP</command>
|
|
|
|
command provided by this module to accomplish this goal. See the
|
|
<ulink url="http://www.snert.com/Software/mod_throttle/">Module
|
|
Instructions</ulink>
|
|
for more information.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="os-specific">
|
|
<title>OS Specific Installation Notes</title>
|
|
|
|
<para>Many aspects of the Bugzilla installation can be affected by the
|
|
the operating system you choose to install it on. Sometimes it can be made
|
|
easier and others more difficult. This section will attempt to help you
|
|
understand both the difficulties of running on specific operating systems
|
|
and the utilities available to make it easier.
|
|
</para>
|
|
|
|
<para>If you have anything to add or notes for an operating system not
|
|
covered, please file a bug in &bzg-bugs;.
|
|
</para>
|
|
|
|
<section id="os-win32">
|
|
<title>Microsoft Windows</title>
|
|
|
|
<para>Making Bugzilla work on windows is still a painful processes.
|
|
The Bugzilla Team is working to make it easier, but that goal is not
|
|
considered a top priority. If you wish to run Bugzilla, we still
|
|
recommend doing so on a Unix based system such as GNU/Linux. As of this
|
|
writing, all members of the Bugzilla team and all known large installations
|
|
run on Unix based systems.
|
|
</para>
|
|
|
|
<para>If after hearing all that, you have enough pain tolerance to attempt
|
|
installing Bugzilla on Win32, here are some pointers.
|
|
<![%bz-devel;[
|
|
Because this is a development version of the guide, these instructions
|
|
are subject to change without notice. In fact, the Bugzilla Team hopes
|
|
they do as we would like to have Bugzilla resonabally close to "out of
|
|
the box" compatibility by the 2.18 release.
|
|
]]>
|
|
</para>
|
|
|
|
<section id="win32-perl">
|
|
<title>Win32 Perl</title>
|
|
|
|
<para>Perl for Windows can be obtained from <ulink
|
|
url="http://www.activestate.com/">ActiveState</ulink>. You should be
|
|
able to find a compiled binary at <ulink
|
|
url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/"/>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="win32-perlmodules">
|
|
<title>Perl Modules on Win32</title>
|
|
|
|
<para>Bugzilla on Windows requires the same perl modules found in
|
|
<xref linkend="install-perlmodules"/>. The main difference is that
|
|
windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead of
|
|
CPAN.
|
|
</para>
|
|
|
|
<programlisting>
|
|
C:\perl> <command>ppm <module name></command>
|
|
</programlisting>
|
|
|
|
<note>
|
|
<para>The above syntax should work for all modules with the exception
|
|
of Template Toolkit. The <ulink
|
|
url="http://tt2.org/download.html#win32">Template Toolkit website</ulink>
|
|
suggests using the instructions on <ulink
|
|
url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>.
|
|
</para>
|
|
</note>
|
|
|
|
<tip>
|
|
<para>A complete list of modules that can be installed using ppm can
|
|
be found at <ulink url="http://www.activestate.com/PPMPackages/5.6plus"/>.
|
|
</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="win32-code-changes">
|
|
<title>Code changes required to run on win32</title>
|
|
|
|
<para>As Bugzilla still doesn't run "out of the box" on
|
|
Windows, code has to be modified. This section is an attempt to
|
|
list the required changes.
|
|
</para>
|
|
|
|
<section id="win32-code-checksetup">
|
|
<title>Changes to <filename>checksetup.pl</filename></title>
|
|
|
|
<para>In <filename>checksetup.pl</filename>, the line reading:</para>
|
|
|
|
<programlisting>
|
|
my $mysql_binaries = `which mysql`;
|
|
</programlisting>
|
|
<para>to</para>
|
|
<programlisting>
|
|
my $mysql_binaries = "D:\\mysql\\bin\\mysql";
|
|
</programlisting>
|
|
|
|
<para>And you'll also need to change:</para>
|
|
|
|
<programlisting>
|
|
my $webservergid = getgrnam($my_webservergroup)
|
|
</programlisting>
|
|
<para>to</para>
|
|
<programlisting>
|
|
my $webservergid = '8'
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="win32-code-bugmail">
|
|
<title>Changes to <filename>BugMail.pm</filename></title>
|
|
|
|
<para>To make bug e-mail work on Win32 (until
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=84876">bug
|
|
84876</ulink> lands), the
|
|
simplest way is to have the Net::SMTP Perl module installed and
|
|
change this:</para>
|
|
|
|
<programlisting>
|
|
open(SENDMAIL, "|/usr/lib/sendmail $sendmailparam -t -i") ||
|
|
die "Can't open sendmail";
|
|
|
|
print SENDMAIL trim($msg) . "\n";
|
|
close SENDMAIL;
|
|
</programlisting>
|
|
<para>to</para>
|
|
<programlisting>
|
|
use Net::SMTP;
|
|
my $smtp_server = 'smtp.mycompany.com'; # change this
|
|
|
|
# Use die on error, so that the mail will be in the 'unsent mails' and
|
|
# can be sent from the sanity check page.
|
|
my $smtp = Net::SMTP->new($smtp_server) ||
|
|
die 'Cannot connect to server \'$smtp_server\'';
|
|
|
|
$smtp->mail('bugzilla-daemon@mycompany.com'); # change this
|
|
$smtp->to($person);
|
|
$smtp->data();
|
|
$smtp->datasend($msg);
|
|
$smtp->dataend();
|
|
$smtp->quit;
|
|
</programlisting>
|
|
|
|
<para>Don't forget to change the name of your SMTP server and the
|
|
domain of the sending e-mail address (after the '@') in the above
|
|
lines of code.</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="win32-http">
|
|
<title>Serving the web pages</title>
|
|
|
|
<para>As is the case on Unix based systems, any web server should be
|
|
able to handle Bugzilla; however, the Bugzilla Team still recommends
|
|
Apache whenever asked. No matter what web server you choose, be sure
|
|
to pay attention to the security notes in <xref linkend="security-access"/>.
|
|
More information on configuring specific web servers can be found in
|
|
<xref linkend="http"/>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>If using Apache on windows, you can set the <ulink
|
|
url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink>
|
|
directive in your Apache config, if you don't do this, you'll have
|
|
to modify the first line of every script to contain your path to
|
|
perl instead of <filename>/usr/bin/perl</filename>.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="os-macosx">
|
|
<title><productname>Mac OS X</productname></title>
|
|
|
|
<para>There are a lot of common libraries and utilities out there that
|
|
Apple did not include with Mac OS X, but which run perfectly well on it.
|
|
The GD library, which Bugzilla needs to do bug graphs, is one of
|
|
these.</para>
|
|
|
|
<para>The easiest way to get a lot of these is with a program called
|
|
Fink, which is similar in nature to the CPAN installer, but installs
|
|
common GNU utilities. Fink is available from
|
|
<ulink url="http://sourceforge.net/projects/fink/"/>.</para>
|
|
|
|
<para>Follow the instructions for setting up Fink. Once it's installed,
|
|
you'll want to use it to install the gd2 package.
|
|
</para>
|
|
|
|
<para>It will prompt you for a number of dependencies, type 'y' and hit
|
|
enter to install all of the dependencies and then watch it work. You will
|
|
then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to
|
|
install the GD perl module.
|
|
</para>
|
|
|
|
<note>
|
|
<para>To prevent creating conflicts with the software that Apple
|
|
installs by default, Fink creates its own directory tree at
|
|
<filename class="directory">/sw</filename> where it installs most of
|
|
the software that it installs. This means your libraries and headers be
|
|
at <filename class="directory">/sw/lib</filename> and
|
|
<filename class="directory">/sw/include</filename> instead of
|
|
<filename class="directory">/usr/lib</filename> and
|
|
<filename class="directory">/usr/local/include</filename>. When the
|
|
Perl module config script asks where your libgd is, be sure to tell it
|
|
<filename class="directory">/sw/lib</filename>.
|
|
</para>
|
|
</note>
|
|
|
|
<para>Also available via Fink is expat. Once running using fink to
|
|
install the expat package you will be able to install
|
|
XML::Parser using CPAN. There is one caveat. Unlike recent versions of
|
|
the GD module, XML::Parser doesn't prompt for the location of the
|
|
required libraries. When using CPAN, you will need to use the following
|
|
command sequence:
|
|
</para>
|
|
|
|
<screen>
|
|
# perl -MCPAN -e'look XML::Parser' <co id="macosx-look"/>
|
|
# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include
|
|
# make; make test; make install <co id="macosx-make"/>
|
|
# exit <co id="macosx-exit"/>
|
|
</screen>
|
|
<calloutlist>
|
|
<callout arearefs="macosx-look macosx-exit">
|
|
<para>The look command will download the module and spawn a
|
|
new shell with the extracted files as the current working directory.
|
|
The exit command will return you to your original shell.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="macosx-make">
|
|
<para>You should watch the output from these make commands,
|
|
especially <quote>make test</quote> as errors may prevent XML::Parser
|
|
from functioning correctly with Bugzilla.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</section>
|
|
|
|
<section id="os-mandrake">
|
|
<title>Linux-Mandrake 8.0</title>
|
|
|
|
<para>Linux-Mandrake 8.0 includes every required and optional library
|
|
for Bugzilla. The easiest way to install them is by using the
|
|
<command>urpmi</command> utility. If you follow these commands, you
|
|
should have everything you need for Bugzilla, and
|
|
<command>./checksetup.pl</command> should not complain about any
|
|
missing libraries. You may already have some of these installed.
|
|
</para>
|
|
|
|
<screen>
|
|
<prompt>bash#</prompt> <command>urpmi perl-mysql</command>
|
|
<prompt>bash#</prompt> <command>urpmi perl-chart</command>
|
|
<prompt>bash#</prompt> <command>urpmi perl-gd</command>
|
|
<prompt>bash#</prompt> <command>urpmi perl-MailTools</command> <co id="test-mailtools"/>
|
|
<prompt>bash#</prompt> <command>urpmi apache-modules</command>
|
|
</screen>
|
|
<calloutlist>
|
|
<callout arearefs="test-mailtools">
|
|
<para>for Bugzilla e-mail integration</para>
|
|
</callout>
|
|
</calloutlist>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="security">
|
|
<title>Bugzilla Security</title>
|
|
|
|
<warning>
|
|
<para>Poorly-configured MySQL and Bugzilla installations have
|
|
given attackers full access to systems in the past. Please take these
|
|
guidelines seriously, even for Bugzilla machines hidden away behind
|
|
your firewall. 80% of all computer trespassers are insiders, not
|
|
anonymous crackers.</para>
|
|
|
|
<para>This is not meant to be a comprehensive list of every possible
|
|
security issue pertaining to the software mentioned in this section.
|
|
There is
|
|
no subsitute for reading the information written by the authors of any
|
|
software running on your system.
|
|
</para>
|
|
</warning>
|
|
|
|
<section id="security-networking">
|
|
<title>TCP/IP Ports</title>
|
|
|
|
<!-- TODO: Make this make sense (TCP/IP) -->
|
|
<para>TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla
|
|
only needs 1, or 2 if you need to use features that require e-mail such
|
|
as bug moving or the e-mail interface from contrib. You should audit
|
|
your server and make sure that you aren't listening on any ports you
|
|
don't need to be. You may also wish to use some kind of firewall
|
|
software to be sure that trafic can only be recieved on ports you
|
|
specify.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="security-mysql">
|
|
<title>MySQL</title>
|
|
|
|
<para>MySQL ships by default with many settings that should be changed.
|
|
By defaults it allows anybody to connect from localhost without a
|
|
password and have full administrative capabilities. It also defaults to
|
|
not have a root password (this is <emphasis>not</emphasis> the same as
|
|
the system root). Also, many installations default to running
|
|
<application>mysqld</application> as the system root.
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Consult the documentation that came with your system for
|
|
information on making <application>mysqld</application> run as an
|
|
unprivleged user.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You should also be sure to disable the anonymous user account
|
|
and set a password for the root user. This is accomplished using the
|
|
following commands:
|
|
</para>
|
|
<programlisting>
|
|
<prompt>bash$</prompt> mysql mysql
|
|
<prompt>mysql></prompt> DELETE FROM user WHERE user = '';
|
|
<prompt>mysql></prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
|
|
<prompt>mysql></prompt> FLUSH PRIVILEGES;
|
|
</programlisting>
|
|
<para>From this point forward you will need to use
|
|
<command>mysql -u root -p</command> and enter
|
|
<replaceable>new_password</replaceable> when prompted when using the
|
|
mysql client.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you run MySQL on the same machine as your httpd server, you
|
|
should consider disabling networking from within MySQL by adding
|
|
the following to your <filename>/etc/my.conf</filename>:
|
|
</para>
|
|
<programlisting>
|
|
[myslqd]
|
|
# Prevent network access to MySQL.
|
|
skip-networking
|
|
</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You may also consider running MySQL, or even all of Bugzilla
|
|
in a chroot jail; however, instructions for doing that are beyond
|
|
the scope of this document.
|
|
</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section id="security-daemon">
|
|
<title>Daemon Accounts</title>
|
|
|
|
<para>Many daemons, such as Apache's httpd and MySQL's mysqld default to
|
|
running as either <quote>root</quote> or <quote>nobody</quote>. Running
|
|
as <quote>root</quote> introduces obvious security problems, but the
|
|
problems introduced by running everything as <quote>nobody</quote> may
|
|
not be so obvious. Basically, if you're running every daemon as
|
|
<quote>nobody</quote> and one of them gets compromised, they all get
|
|
compromised. For this reason it is recommended that you create a user
|
|
account for each daemon.
|
|
</para>
|
|
|
|
<note>
|
|
<para>You will need to set the <varname>webservergroup</varname> to
|
|
the group you created for your webserver to run as in
|
|
<filename>localconfig</filename>. This will allow
|
|
<command>./checksetup.pl</command> to better adjust the file
|
|
permissions on your Bugzilla install so as to not require making
|
|
anything world-writable.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section id="security-access">
|
|
<title>Web Server Access Controls</title>
|
|
|
|
<para>There are many files that are placed in the Bugzilla directory
|
|
area that should not be accessable from the web. Because of the way
|
|
Bugzilla is currently laid out, the list of what should and should
|
|
not be accessible is rather complicated.
|
|
</para>
|
|
|
|
<para>Users of Apache don't need to worry about this, however, because
|
|
Bugzilla ships with .htaccess files which restrict access to all the
|
|
sensitive files in this section. Users of other webservers, read on.
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>In the main Bugzilla directory, you should:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block:
|
|
<simplelist type="inline">
|
|
<member><filename>*.pl</filename></member>
|
|
<member><filename>*localconfig*</filename></member>
|
|
<member><filename>runtests.sh</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>But allow:
|
|
<simplelist type="inline">
|
|
<member><filename>localconfig.js</filename></member>
|
|
<member><filename>localconfig.rdf</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In <filename class="directory">data</filename>:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>But allow:
|
|
<simplelist type="inline">
|
|
<member><filename>duplicates.rdf</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In <filename class="directory">data/webdot</filename>:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>If you use a remote webdot server:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>But allow
|
|
<simplelist type="inline">
|
|
<member><filename>*.dot</filename></member>
|
|
</simplelist>
|
|
only for the remote webdot server</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Otherwise, if you use a local GraphViz:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>But allow:
|
|
<simplelist type="inline">
|
|
<member><filename>*.png</filename></member>
|
|
<member><filename>*.gif</filename></member>
|
|
<member><filename>*.jpg</filename></member>
|
|
<member><filename>*.map</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>And if you don't use any dot:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In <filename class="directory">Bugzilla</filename>:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In <filename class="directory">template</filename>:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>You should test to make sure that the files mentioned above are
|
|
not accessible from the Internet, especially your
|
|
<filename>localconfig</filename> file which contains your database
|
|
password. To test, simply point your web browser at the file; for
|
|
example, to test mozilla.org's installation, we'd try to access
|
|
<ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should
|
|
get a <errorcode>403</errorcode> <errorname>Forbidden</errorname>
|
|
error.
|
|
</para>
|
|
|
|
<caution>
|
|
<para>Not following the instructions in this section, including
|
|
testing, may result in sensitive information being globally
|
|
accessible.
|
|
</para>
|
|
</caution>
|
|
|
|
<tip>
|
|
<para>You should check <xref linkend="http"/> to see if instructions
|
|
have been included for your web server. You should also compare those
|
|
instructions with this list to make sure everything is properly
|
|
accounted for.
|
|
</para>
|
|
</tip>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="troubleshooting">
|
|
<title>Troubleshooting</title>
|
|
|
|
<para>This section gives solutions to common Bugzilla installation
|
|
problems.
|
|
</para>
|
|
|
|
<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>
|
|
by
|
|
</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
|
|
<quote>drwx------</quote>. Type
|
|
<command>chmod 755
|
|
<filename>/var/spool/mqueue</filename>
|
|
</command>
|
|
as root to fix this problem.
|
|
</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. Examples
|
|
can be found in <xref linkend="trouble-filetemp-errors"/>.
|
|
</para>
|
|
|
|
<figure id="trouble-filetemp-errors">
|
|
<title>Other File::Temp error messages</title>
|
|
|
|
<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>
|
|
</figure>
|
|
|
|
<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 patch in <xref linkend="trouble-filetemp-patch"/>. The patch is also
|
|
available as a <ulink url="../xml/filetemp.patch">patch file</ulink>.
|
|
</para>
|
|
|
|
<figure id="trouble-filetemp-patch">
|
|
<title>Patch for File::Temp in Perl 5.6.0</title>
|
|
|
|
<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>
|
|
</figure>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|
|
<!-- 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:
|
|
-->
|
|
|