041e66b04a
In an effort to maintain CVS history, the raw files were copied on the CVS server to the xml/ directory and renamed to have .xml for the extension; any checkins before this one did have the .sgml extension. git-svn-id: svn://10.0.0.236/trunk@249206 18797224-902f-48f8-a5cc-f745e15eee43
1616 lines
56 KiB
XML
1616 lines
56 KiB
XML
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
|
|
<chapter id="installation" xreflabel="Bugzilla Installation">
|
|
<title>Installation</title>
|
|
|
|
<section id="stepbystep" xreflabel="Bugzilla Installation Step-by-step">
|
|
<title>Step-by-step Install</title>
|
|
|
|
<section id="intstall-into">
|
|
<title>Introduction</title>
|
|
|
|
<para>Bugzilla has been successfully installed under Solaris, Linux,
|
|
and Win32. Win32 is not yet officially supported, but many people
|
|
have got it working fine.
|
|
Please see
|
|
<xref linkend="os-win32" />
|
|
for further advice on getting Bugzilla to work on Microsoft
|
|
Windows.</para>
|
|
|
|
</section>
|
|
|
|
<section id="install-package-list">
|
|
<title>Package List</title>
|
|
|
|
<note>
|
|
<para> If you are running the very most recent
|
|
version of Perl and MySQL (both the executables and development
|
|
libraries) on your system, you can skip these manual installation
|
|
steps for the Perl modules by using Bundle::Bugzilla; see
|
|
<xref linkend="bundlebugzilla" />.
|
|
</para>
|
|
</note>
|
|
|
|
<para>The software packages necessary for the proper running of
|
|
Bugzilla (with download links) are:
|
|
<orderedlist>
|
|
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.mysql.com/">MySQL database server</ulink>
|
|
(&min-mysql-ver; or greater)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.perl.org">Perl</ulink>
|
|
(&min-perl-ver;, 5.6.1 is recommended if you wish to
|
|
use Bundle::Bugzilla)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Perl Modules (minimum version):
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.template-toolkit.org">Template</ulink>
|
|
(v&min-template-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.perldoc.com/perl5.6/lib/File/Temp.html">
|
|
File::Temp</ulink>
|
|
(&min-file-temp-ver;) (Prerequisite for Template)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/modules/by-module/AppConfig/">AppConfig
|
|
</ulink>
|
|
(&min-appconfig-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/authors/id/MUIR/modules/Text-Tabs%2BWrap-2001.0131.tar.gz">Text::Wrap</ulink>
|
|
(&min-text-wrap-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://search.cpan.org/search?dist=File-Spec">File::Spec
|
|
</ulink>
|
|
(&min-file-spec-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/modules/by-module/Data/">Data::Dumper
|
|
</ulink>
|
|
(&min-data-dumper-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/modules/by-module/Mysql/">DBD::mysql
|
|
</ulink>
|
|
(&min-dbd-mysql-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/modules/by-module/DBI/">DBI</ulink>
|
|
(&min-dbi-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/modules/by-module/Date/">Date::Parse
|
|
</ulink>
|
|
(&min-date-format-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/modules/by-module/CGI/">CGI
|
|
</ulink>
|
|
(&min-cgi-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
and, optionally:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/modules/by-module/GD/">GD</ulink>
|
|
(&min-gd-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
GD::Graph
|
|
(&min-gd-graph-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
GD::Text::Align
|
|
(&min-gd-text-align-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.cpan.org/modules/by-module/Chart/">Chart::Base
|
|
</ulink>
|
|
(&min-chart-base-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
XML::Parser
|
|
(&min-xml-parser-ver;) for the XML interface
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
MIME::Parser
|
|
(&min-mime-parser-ver;) for the email interface
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
<para>
|
|
The web server of your choice.
|
|
<ulink url="http://www.apache.org/">Apache</ulink>
|
|
is highly recommended.
|
|
</para>
|
|
</listitem>
|
|
|
|
|
|
</orderedlist>
|
|
|
|
<warning>
|
|
<para>It is a good idea, while installing Bugzilla, to ensure that there
|
|
is some kind of firewall between you and the rest of the Internet,
|
|
because 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>
|
|
</section>
|
|
|
|
<section id="install-mysql">
|
|
<title>MySQL</title>
|
|
|
|
<para>Visit the MySQL homepage at
|
|
<ulink url="http://www.mysql.com">www.mysql.com</ulink>
|
|
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>/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 an RPM or Debian
|
|
package, you will need to add <filename>mysqld</filename>
|
|
to your init scripts so the server daemon will come back up whenever
|
|
your machine reboots. Further discussion of UNIX init sequences are
|
|
beyond the scope of this guide.
|
|
</para>
|
|
|
|
<para>Change your init script to start
|
|
<filename>mysqld</filename>
|
|
with the ability to accept large packets. By default,
|
|
<filename>mysqld</filename>
|
|
only accepts packets up to 64K long. This limits the size of
|
|
attachments you may put on bugs. If you add
|
|
<option>-O max_allowed_packet=1M</option>
|
|
to the command that starts
|
|
<filename>mysqld</filename>
|
|
(or <filename>safe_mysqld</filename>),
|
|
then you will be able to have attachments up to about 1 megabyte.
|
|
There is a Bugzilla parameter for maximum attachment size;
|
|
you should configure it to match the value you choose here.</para>
|
|
|
|
<para>If you plan on running Bugzilla and MySQL on the same machine,
|
|
consider using the
|
|
<option>--skip-networking</option>
|
|
option in the init script. This enhances security by preventing
|
|
network access to MySQL.</para>
|
|
|
|
</section>
|
|
|
|
<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">perl.com</ulink> for the rare
|
|
*nix systems which don't have it.
|
|
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>
|
|
|
|
<tip id="bundlebugzilla"
|
|
xreflabel="Using Bundle::Bugzilla instead of manually installing Perl modules">
|
|
|
|
<para>You can skip the following Perl module installation steps by
|
|
installing
|
|
<productname>Bundle::Bugzilla</productname>
|
|
|
|
from
|
|
<glossterm linkend="gloss-cpan">CPAN</glossterm>,
|
|
which installs all required modules for you.</para>
|
|
|
|
<para>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
|
|
<command>perl -MCPAN -e 'install "Bundle::Bugzilla"'</command>
|
|
</computeroutput>
|
|
</para>
|
|
|
|
<para>Bundle::Bugzilla doesn't include GD, Chart::Base, or
|
|
MIME::Parser, which are not essential to a basic Bugzilla install. If
|
|
installing this bundle fails, you should install each module
|
|
individually to isolate the problem.</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="perl-modules">
|
|
<title>Perl Modules</title>
|
|
|
|
<para>
|
|
All Perl modules can be found on the
|
|
<ulink url="http://www.cpan.org">Comprehensive Perl
|
|
Archive Network</ulink> (CPAN). The
|
|
CPAN servers have a real tendency to bog down, so please use mirrors.
|
|
</para>
|
|
|
|
<para>Quality, general Perl module installation instructions can be
|
|
found on the CPAN website, but the easy thing to do is to just use the
|
|
CPAN shell which does all the hard work for you.
|
|
To use the CPAN shell to install a module:
|
|
</para>
|
|
|
|
<para>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
<command>perl -MCPAN -e 'install "<modulename>"'</command>
|
|
</computeroutput>
|
|
</para>
|
|
|
|
<para>
|
|
To do it the hard way:
|
|
</para>
|
|
|
|
<para>Untar the module tarball -- it should create its own
|
|
directory</para>
|
|
|
|
<para>CD to the directory just created, and enter the following
|
|
commands:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
|
|
<command>perl Makefile.PL</command>
|
|
</computeroutput>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
|
|
<command>make</command>
|
|
</computeroutput>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
|
|
<command>make test</command>
|
|
</computeroutput>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
|
|
<command>make install</command>
|
|
</computeroutput>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<warning>
|
|
<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>
|
|
</warning>
|
|
|
|
|
|
<section>
|
|
<title>DBI</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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Data::Dumper</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>
|
|
</section>
|
|
|
|
<section>
|
|
<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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>TimeDate modules</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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>GD (optional)</title>
|
|
|
|
<para>The GD library was written by Thomas Boutell a long while ago to
|
|
programatically 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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Chart::Base (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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Template Toolkit</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>
|
|
</section>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="sbs-http">
|
|
<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.</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Setting Up the MySQL Database</title>
|
|
|
|
<para>After you've gotten all the software installed and working you're
|
|
ready to start preparing the database for its life as the back end to
|
|
a high quality bug tracker.</para>
|
|
|
|
<para>First, you'll want to fix MySQL permissions to allow access from
|
|
Bugzilla. For the purpose of this Installation section, the Bugzilla
|
|
username will be
|
|
<quote>bugs</quote>, and will have minimal permissions.
|
|
</para>
|
|
|
|
<para>Begin by giving the MySQL root user a password. MySQL passwords are limited
|
|
to 16 characters.
|
|
<simplelist>
|
|
<member>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
|
|
<command>mysql -u root mysql</command>
|
|
</computeroutput>
|
|
</member>
|
|
|
|
<member>
|
|
<computeroutput>
|
|
<prompt>mysql></prompt>
|
|
|
|
<command>UPDATE user SET Password=PASSWORD('<new_password'>)
|
|
WHERE user='root';</command>
|
|
</computeroutput>
|
|
</member>
|
|
|
|
<member>
|
|
<computeroutput>
|
|
<prompt>mysql></prompt>
|
|
|
|
<command>FLUSH PRIVILEGES;</command>
|
|
</computeroutput>
|
|
</member>
|
|
</simplelist>
|
|
|
|
From this point on, if you need to access MySQL as the MySQL root user,
|
|
you will need to use
|
|
<command>mysql -u root -p</command>
|
|
|
|
and enter <new_password>. Remember that MySQL user names have
|
|
nothing to do with Unix user names (login names).</para>
|
|
|
|
<para>Next, we use an SQL <command>GRANT</command> command to create a
|
|
<quote>bugs</quote>
|
|
|
|
user, and grant sufficient permissions for checksetup.pl, which we'll
|
|
use later, to work its magic. This also restricts the
|
|
<quote>bugs</quote>
|
|
user to operations within a database called
|
|
<quote>bugs</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>
|
|
|
|
<para>Remember to set <bugs_password> to some unique password.
|
|
<simplelist>
|
|
<member>
|
|
<computeroutput>
|
|
<prompt>mysql></prompt>
|
|
|
|
<command>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,
|
|
ALTER,CREATE,DROP,REFERENCES ON bugs.* TO bugs@localhost
|
|
IDENTIFIED BY '<bugs_password>';</command>
|
|
</computeroutput>
|
|
</member>
|
|
|
|
<member>
|
|
<computeroutput>
|
|
<prompt>mysql></prompt>
|
|
|
|
<command>FLUSH PRIVILEGES;</command>
|
|
</computeroutput>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
<note>
|
|
<para>If you are using MySQL 4, the bugs user also needs to be granted
|
|
the LOCK TABLES and CREATE TEMPORARY TABLES permissions.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<filename>checksetup.pl</filename>
|
|
</title>
|
|
|
|
<para>Next, run the magic checksetup.pl script. (Many thanks to
|
|
<ulink url="mailto:holgerschurig@nikocity.de">Holger Schurig </ulink>
|
|
for writing this script!)
|
|
This script is designed to make sure 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.
|
|
<simplelist>
|
|
<member>
|
|
<computeroutput>
|
|
<prompt>bash#</prompt>
|
|
|
|
<command>./checksetup.pl</command>
|
|
</computeroutput>
|
|
</member>
|
|
</simplelist>
|
|
|
|
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</quote>
|
|
if you're following these directions</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>MySQL username:
|
|
<quote>bugs</quote>
|
|
if you're following these directions</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Password for the
|
|
<quote>bugs</quote>
|
|
MySQL account; (<bugs_password>) 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="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>
|
|
<warning>
|
|
<para>This information on using the LDAP
|
|
authentication options with Bugzilla is old, and the authors do
|
|
not know of anyone who has tested it. Approach with caution.
|
|
</para>
|
|
</warning>
|
|
</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>
|
|
|
|
<para>Using LDAP for Bugzilla authentication requires the
|
|
Mozilla::LDAP (aka PerLDAP) Perl module. The
|
|
Mozilla::LDAP module in turn requires Netscape's Directory SDK for C.
|
|
After you have installed the SDK, then install the PerLDAP module.
|
|
Mozilla::LDAP and the Directory SDK for C are both
|
|
<ulink url="http://www.mozilla.org/directory/">available for
|
|
download</ulink> from mozilla.org.
|
|
</para>
|
|
|
|
<para>
|
|
Set the Param 'useLDAP' to "On" **only** if you will be using an LDAP
|
|
directory for
|
|
authentication. Be very careful when setting up this parameter; if you
|
|
set LDAP authentication, but do not have a valid LDAP directory set up,
|
|
you will not be able to log back in to Bugzilla once you log out. (If
|
|
this happens, you can get back in by manually editing the data/params
|
|
file, and setting useLDAP back to 0.)
|
|
</para>
|
|
|
|
<para>If using LDAP, you must set the
|
|
three additional parameters: Set LDAPserver to the name (and optionally
|
|
port) of your LDAP server. If no port is specified, it defaults to the
|
|
default port of 389. (e.g "ldap.mycompany.com" or
|
|
"ldap.mycompany.com:1234") Set LDAPBaseDN to the base DN for searching
|
|
for users in your LDAP directory. (e.g. "ou=People,o=MyCompany") uids
|
|
must be unique under the DN specified here. Set LDAPmailattribute to
|
|
the name of the attribute in your LDAP directory which contains the
|
|
primary email address. On most directory servers available, this is
|
|
"mail", but you may need to change this.
|
|
</para>
|
|
|
|
<para>You can also try using <ulink url="http://www.openldap.org/">
|
|
OpenLDAP</ulink> with Bugzilla, using any of a number of administration
|
|
tools. You should apply the patch attached this bug:
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=158630">
|
|
http://bugzilla.mozilla.org/show_bug.cgi?id=158630</ulink>, then set
|
|
the following object classes for your users:
|
|
|
|
<orderedlist>
|
|
<listitem><para>objectClass: person</para></listitem>
|
|
<listitem><para>objectClass: organizationalPerson</para></listitem>
|
|
<listitem><para>objectClass: inetOrgPerson</para></listitem>
|
|
<listitem><para>objectClass: top</para></listitem>
|
|
<listitem><para>objectClass: posixAccount</para></listitem>
|
|
<listitem><para>objectClass: shadowAccount</para></listitem>
|
|
</orderedlist>
|
|
|
|
Please note that this patch <emphasis>has not</emphasis> yet been
|
|
accepted by the Bugzilla team, and so you may need to do some
|
|
manual tweaking. That said, it looks like Net::LDAP is probably
|
|
the way to go in the future.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="content-type"
|
|
xreflabel="Preventing untrusted Bugzilla content from executing malicious Javascript code">
|
|
|
|
<title>Preventing untrusted Bugzilla content from executing malicious
|
|
Javascript code</title>
|
|
|
|
<para>It is possible for a Bugzilla to execute malicious Javascript
|
|
code. Due to internationalization concerns, we are unable to
|
|
incorporate the code changes necessary to fulfill the CERT advisory
|
|
requirements mentioned in
|
|
<ulink
|
|
url="http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3">
|
|
http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3</ulink>.
|
|
Executing the following code snippet from a UNIX command shell will
|
|
rectify the problem if your Bugzilla installation is intended for an
|
|
English-speaking audience. As always, be sure your Bugzilla
|
|
installation has a good backup before making changes, and I recommend
|
|
you understand what the script is doing before executing it.</para>
|
|
|
|
<para>
|
|
<programlisting>
|
|
bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; charset=ISO-8859-1/i" *.cgi *.pl
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>All this one-liner command does is search for all instances of
|
|
<quote>Content-type: text/html</quote>
|
|
|
|
and replaces it with
|
|
<quote>Content-Type: text/html; charset=ISO-8859-1</quote>
|
|
|
|
. This specification prevents possible Javascript attacks on the
|
|
browser, and is suggested for all English-speaking sites. For
|
|
non-English-speaking Bugzilla sites, I suggest changing
|
|
<quote>ISO-8859-1</quote>, above, to
|
|
<quote>UTF-8</quote>.</para>
|
|
|
|
<note>
|
|
<para>Using <meta> tags to set the charset is not
|
|
recommended, as there's a bug in Netscape 4.x which causes pages
|
|
marked up in this way to load twice. See
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=126266">bug
|
|
126266</ulink> for more information including progress toward making
|
|
bugzilla charset aware by default.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="directoryindex" xreflabel="Modifying the Apache
|
|
DirectoryIndex parameter to use index.cgi">
|
|
<title>
|
|
<filename>directoryindex</filename> for the Bugzilla default page.
|
|
</title>
|
|
|
|
<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>
|
|
</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/Throttle/">
|
|
http://www.snert.com/Software/Throttle/</ulink>.
|
|
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/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 very 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/">http://aspn.activestate.com/ASPN/Downloads/ActivePerl/</ulink>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="win32-perl-modules">
|
|
<title>Perl Modules on Win32</title>
|
|
|
|
<para>Bugzilla on Windows requires the same perl modules found in
|
|
<xref linkend="install-package-list"/>. The main difference is that
|
|
windows uses <command>ppm</command> 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">http://www.activestate.com/PPMPackages/5.6plus</ulink>.
|
|
</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="win32-code-changes">
|
|
<title>Code changes required to run on win32</title>
|
|
|
|
<para>Unfortunately, Bugzilla still doesn't run "out of the box" on
|
|
Windows. There is work in progress to make this easier, but until that
|
|
happens code will have to be modified. This section is an attempt to
|
|
list the required changes. It is an attempt to be all inclusive, but
|
|
there may be other changes required. If you find something is missing,
|
|
please file a bug in &bzg-bugs;.
|
|
</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>
|
|
|
|
<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>
|
|
|
|
<!-- TODO: Clean me up... (Mac OS X) -->
|
|
<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 run the following as root:
|
|
<command>fink install gd</command>
|
|
</para>
|
|
|
|
<para>It will prompt you for a number of dependencies, type 'y' and hit
|
|
enter to install all of the dependencies. Then watch it work.</para>
|
|
|
|
<para>To prevent creating conflicts with the software that Apple installs
|
|
by default, Fink creates its own directory tree at /sw where it installs
|
|
most of the software that it installs. This means your libraries and
|
|
headers for libgd will be at /sw/lib and /sw/include instead of /usr/lib
|
|
and /usr/local/include. Because of these changed locations for the
|
|
libraries, the Perl GD module will not install directly via CPAN, because it
|
|
looks for the specific paths instead of getting them from your
|
|
environment. But there's a way around that :-)</para>
|
|
|
|
<para>Instead of typing
|
|
<quote>install GD</quote>
|
|
at the
|
|
<prompt>cpan></prompt>
|
|
prompt, type
|
|
<command>look GD</command>.
|
|
This should go through the motions of downloading the latest version of
|
|
the GD module, then it will open a shell and drop you into the build
|
|
directory. Apply <ulink url="../xml/gd-makefile.patch">this patch</ulink>
|
|
to the Makefile.PL file (save the
|
|
patch into a file and use the command
|
|
<command>patch < patchfile</command>.)
|
|
</para>
|
|
|
|
<para>Then, run these commands to finish the installation of the GD
|
|
module:
|
|
<simplelist>
|
|
<member>
|
|
<command>perl Makefile.PL</command>
|
|
</member>
|
|
|
|
<member>
|
|
<command>make</command>
|
|
</member>
|
|
|
|
<member>
|
|
<command>make test</command>
|
|
</member>
|
|
|
|
<member>
|
|
<command>make install</command>
|
|
</member>
|
|
|
|
<member>And don't forget to run
|
|
<command>exit</command>
|
|
|
|
to get back to CPAN.</member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
</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="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>As mentioned above, the Bugzilla Team recommends Apache for use
|
|
with Bugzilla. 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> (shown in <xref linkend="http-apache-htaccess"/>
|
|
for the curious) are allowed to override Apache's normal access
|
|
permissions or else important password information may be exposed to the
|
|
Internet.
|
|
</para>
|
|
|
|
<para>Many Apache installations are not configured to run scripts
|
|
anywhere but in the <filename class="directory">cgi-bin</filename>
|
|
directory; however, we recommend that Bugzilla not be installed in the
|
|
<filename class="directory">cgi-bin</filename>, otherwise the static
|
|
files such as images and <xref linkend="gloss-javascript"/>
|
|
will not work correctly. To allow scripts to run in the normal
|
|
web space, the following changes should be made to your
|
|
<filename>httpd.conf</filename> file.
|
|
</para>
|
|
|
|
<para>To allow files with a .cgi extension to be run, 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>
|
|
|
|
<note>
|
|
<para>For more information on Apache and its directives, see the
|
|
glossary entry on <xref linkend="gloss-apache"/>.
|
|
</para>
|
|
</note>
|
|
|
|
<example id="http-apache-htaccess">
|
|
<title><filename>.htaccess</filename> files for Apache</title>
|
|
|
|
<para><filename>$BUGZILLA_HOME/.htaccess</filename>
|
|
<programlisting><![CDATA[
|
|
# don't allow people to retrieve non-cgi executable files or our private data
|
|
<FilesMatch ^(.*\.pl|.*localconfig.*|runtests.sh)$>
|
|
deny from all
|
|
</FilesMatch>
|
|
<FilesMatch ^(localconfig.js|localconfig.rdf)$>
|
|
allow from all
|
|
</FilesMatch>
|
|
]]></programlisting>
|
|
</para>
|
|
|
|
<para><filename>$BUGZILLA_HOME/data/.htaccess</filename>
|
|
<programlisting><![CDATA[
|
|
# nothing in this directory is retrievable unless overriden by an .htaccess
|
|
# in a subdirectory; the only exception is duplicates.rdf, which is used by
|
|
# duplicates.xul and must be loadable over the web
|
|
deny from all
|
|
<Files duplicates.rdf>
|
|
allow from all
|
|
</Files>
|
|
]]></programlisting>
|
|
</para>
|
|
|
|
<para><filename>$BUGZILLA_HOME/data/webdot</filename>
|
|
<programlisting><![CDATA[
|
|
# Restrict access to .dot files to the public webdot server at research.att.com
|
|
# if research.att.com ever changed their IP, or if you use a different
|
|
# webdot server, you'll need to edit this
|
|
<FilesMatch ^[0-9]+\.dot$>
|
|
Allow from 192.20.225.10
|
|
Deny from all
|
|
</FilesMatch>
|
|
|
|
# Allow access by a local copy of 'dot' to .png, .gif, .jpg, and
|
|
# .map files
|
|
<FilesMatch ^[0-9]+\.(png|gif|jpg|map)$>
|
|
Allow from all
|
|
</FilesMatch>
|
|
|
|
# And no directory listings, either.
|
|
Deny from all
|
|
]]></programlisting>
|
|
</para>
|
|
|
|
<para><filename>$BUGZILLA_HOME/Bugzilla/.htaccess</filename>
|
|
<programlisting>
|
|
# nothing in this directory is retrievable unless overriden by an .htaccess
|
|
# in a subdirectory
|
|
deny from all
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para><filename>$BUGZILLA_HOME/template/.htaccess</filename>
|
|
<programlisting>
|
|
# nothing in this directory is retrievable unless overriden by an .htaccess
|
|
# in a subdirectory
|
|
deny from all
|
|
</programlisting>
|
|
</para>
|
|
|
|
</example>
|
|
|
|
</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="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:
|
|
-->
|
|
|