mirror of https://github.com/tLDP/LDP
2084 lines
68 KiB
XML
2084 lines
68 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>
|
||
|
<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 the
|
||
|
<xref linkend="win32" />
|
||
|
for further advice on getting Bugzilla to work on Microsoft
|
||
|
Windows.</para>
|
||
|
|
||
|
</section>
|
||
|
|
||
|
<section>
|
||
|
<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>
|
||
|
(3.22.5 or greater)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.perl.org">Perl</ulink>
|
||
|
(5.005 or greater, 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>
|
||
|
(v2.07)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.cpan.org/modules/by-module/AppConfig/">AppConfig
|
||
|
</ulink>
|
||
|
(v1.52)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.cpan.org/authors/id/MUIR/modules/Text-Tabs%2BWrap-2001.0131.tar.gz">Text::Wrap</ulink>
|
||
|
(v2001.0131)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://search.cpan.org/search?dist=File-Spec">File::Spec
|
||
|
</ulink>
|
||
|
(v0.8.2)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.cpan.org/modules/by-module/Data/">Data::Dumper
|
||
|
</ulink>
|
||
|
(any)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.cpan.org/modules/by-module/Mysql/">DBD::mysql
|
||
|
</ulink>
|
||
|
(v1.2209)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.cpan.org/modules/by-module/DBI/">DBI</ulink>
|
||
|
(v1.13)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.cpan.org/modules/by-module/Date/">Date::Parse
|
||
|
</ulink>
|
||
|
(any)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
CGI::Carp
|
||
|
(any)
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
</orderedlist>
|
||
|
and, optionally:
|
||
|
<orderedlist>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.cpan.org/modules/by-module/GD/">GD</ulink>
|
||
|
(v1.19) for bug charting
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<ulink url="http://www.cpan.org/modules/by-module/Chart/">Chart::Base
|
||
|
</ulink>
|
||
|
(v0.99c) for bug charting
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
XML::Parser
|
||
|
(any) for the XML interface
|
||
|
</para>
|
||
|
</listitem>
|
||
|
|
||
|
<listitem>
|
||
|
<para>
|
||
|
MIME::Parser
|
||
|
(any) 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>
|
||
|
|
||
|
<note>
|
||
|
<para>Linux-Mandrake 8.0 includes every
|
||
|
required and optional library for Bugzilla. The easiest way to
|
||
|
install them is by using the
|
||
|
<filename>urpmi</filename>
|
||
|
|
||
|
utility. If you follow these commands, you should have everything you
|
||
|
need for Bugzilla, and
|
||
|
<filename>checksetup.pl</filename>
|
||
|
|
||
|
should not complain about any missing libraries. You may already have
|
||
|
some of these installed.</para>
|
||
|
|
||
|
<simplelist>
|
||
|
<member>
|
||
|
<prompt>bash#</prompt>
|
||
|
|
||
|
<command>urpmi perl-mysql</command>
|
||
|
</member>
|
||
|
|
||
|
<member>
|
||
|
<prompt>bash#</prompt>
|
||
|
|
||
|
<command>urpmi perl-chart</command>
|
||
|
</member>
|
||
|
|
||
|
<member>
|
||
|
<prompt>bash#</prompt>
|
||
|
|
||
|
<command>urpmi perl-gd</command>
|
||
|
</member>
|
||
|
|
||
|
<member>
|
||
|
<prompt>bash#</prompt>
|
||
|
|
||
|
<command>urpmi perl-MailTools</command>
|
||
|
|
||
|
(for Bugzilla email integration)</member>
|
||
|
|
||
|
<member>
|
||
|
<prompt>bash#</prompt>
|
||
|
|
||
|
<command>urpmi apache-modules</command>
|
||
|
</member>
|
||
|
</simplelist>
|
||
|
</note>
|
||
|
</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 all post-5.005
|
||
|
versions of Perl, 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 &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 programatic 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. However, there are
|
||
|
known problems with XS Stash and Perl 5.005_02 and lower. If you
|
||
|
wish to use these older versions of Perl, please use the regular
|
||
|
stash.</para>
|
||
|
</section>
|
||
|
|
||
|
|
||
|
</section>
|
||
|
|
||
|
<section>
|
||
|
<title>HTTP Server</title>
|
||
|
|
||
|
<para>You have a freedom of choice here - Apache, Netscape or any other
|
||
|
server on UNIX would do. You can run the web server on a
|
||
|
different machine than MySQL, but need to adjust the MySQL
|
||
|
<quote>bugs</quote>
|
||
|
user permissions accordingly.
|
||
|
<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>
|
||
|
</para>
|
||
|
|
||
|
<para>You'll want to make sure that your web server will run any file
|
||
|
with the .cgi extension as a CGI and not just display it. If you're
|
||
|
using Apache that means uncommenting the following line in the httpd.conf
|
||
|
file:
|
||
|
<programlisting>AddHandler cgi-script .cgi</programlisting>
|
||
|
</para>
|
||
|
|
||
|
<para>With Apache you'll also want to make sure that within the
|
||
|
httpd.conf file the line:
|
||
|
<programlisting>
|
||
|
Options ExecCGI
|
||
|
AllowOverride Limit
|
||
|
</programlisting>
|
||
|
|
||
|
is in the stanza that covers the directories into which you intend to
|
||
|
put the bugzilla .html and .cgi files.
|
||
|
|
||
|
<note>
|
||
|
<para>AllowOverride Limit allows the use of a Deny statement in the
|
||
|
.htaccess file generated by checksetup.pl</para>
|
||
|
|
||
|
<para>Users of older versions of Apache may find the above lines
|
||
|
in the srm.conf and access.conf files, respecitvely.</para>
|
||
|
</note>
|
||
|
</para>
|
||
|
|
||
|
<warning>
|
||
|
<para>There are important files and directories that should not be a
|
||
|
served by the HTTP server - most files in the
|
||
|
<quote>data</quote>
|
||
|
and
|
||
|
<quote>shadow</quote>
|
||
|
directories and the
|
||
|
<quote>localconfig</quote>
|
||
|
file. You should configure your HTTP server to not serve
|
||
|
these files. Failure to do so will expose critical passwords and
|
||
|
other data. Please see
|
||
|
<xref linkend="htaccess" />
|
||
|
for details on how to do this for Apache; the checksetup.pl
|
||
|
script should create appropriate .htaccess files for you.</para>
|
||
|
</warning>
|
||
|
</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
|
||
|
heirarchy, 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>
|
||
|
|
||
|
<para>Lastly, you'll need to set up a symbolic link to
|
||
|
<filename>/usr/bonsaitools/bin/perl</filename>
|
||
|
for the correct location of your Perl executable (probably
|
||
|
<filename>/usr/bin/perl</filename>).
|
||
|
Otherwise you must hack all the .cgi files to change where they look
|
||
|
for Perl. This can be done using the following Perl one-liner, but
|
||
|
I suggest using the symlink approach to avoid upgrade hassles.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
<programlisting>perl -pi -e
|
||
|
's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm
|
||
|
processmail syncshadowdb</programlisting>
|
||
|
|
||
|
Change <filename>/usr/bin/perl</filename> to match the location
|
||
|
of Perl on your machine.
|
||
|
</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 HTTPS.
|
||
|
</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>
|
||
|
</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>
|
||
|
|
||
|
<para>Note: 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.</para>
|
||
|
</section>
|
||
|
|
||
|
<section id="htaccess" xreflabel=".htaccess files and security">
|
||
|
<title>
|
||
|
<filename>.htaccess</filename>
|
||
|
files and security</title>
|
||
|
|
||
|
<para>To enhance the security of your Bugzilla installation, Bugzilla's
|
||
|
<filename>checksetup.pl</filename> script will generate
|
||
|
<glossterm>
|
||
|
<filename>.htaccess</filename>
|
||
|
</glossterm>
|
||
|
|
||
|
files which the Apache webserver can use to restrict access to the
|
||
|
bugzilla data files.
|
||
|
These .htaccess files will not work with Apache 1.2.x - but this
|
||
|
has security holes, so you shouldn't be using it anyway.
|
||
|
<note>
|
||
|
<para>If you are using an alternate provider of
|
||
|
<productname>webdot</productname>
|
||
|
|
||
|
services for graphing (as described when viewing
|
||
|
<filename>editparams.cgi</filename>
|
||
|
|
||
|
in your web browser), you will need to change the ip address in
|
||
|
<filename>data/webdot/.htaccess</filename>
|
||
|
|
||
|
to the ip address of the webdot server that you are using.</para>
|
||
|
</note>
|
||
|
</para>
|
||
|
|
||
|
<para>The default .htaccess file may not provide adequate access
|
||
|
restrictions, depending on your web server configuration. Be sure to
|
||
|
check the <Directory> entries for your Bugzilla directory so that
|
||
|
the
|
||
|
<filename>.htaccess</filename>
|
||
|
|
||
|
file is allowed to override web server defaults. For instance, let's
|
||
|
assume your installation of Bugzilla is installed to
|
||
|
<filename>/usr/local/bugzilla</filename>
|
||
|
|
||
|
. You should have this <Directory> entry in your
|
||
|
<filename>httpd.conf</filename>
|
||
|
|
||
|
file:</para>
|
||
|
|
||
|
<para>
|
||
|
|
||
|
<programlisting><![CDATA[
|
||
|
<Directory /usr/local/bugzilla/>
|
||
|
Options +FollowSymLinks +Indexes +Includes +ExecCGI
|
||
|
AllowOverride All
|
||
|
</Directory>
|
||
|
]]></programlisting>
|
||
|
|
||
|
</para>
|
||
|
|
||
|
<para>The important part above is
|
||
|
<quote>AllowOverride All</quote>
|
||
|
|
||
|
. Without that, the
|
||
|
<filename>.htaccess</filename>
|
||
|
|
||
|
file created by
|
||
|
<filename>checksetup.pl</filename>
|
||
|
|
||
|
will not have sufficient permissions to protect your Bugzilla
|
||
|
installation.</para>
|
||
|
|
||
|
<para>If you are using Internet Information Server (IIS) or another
|
||
|
web server which does not observe
|
||
|
<filename>.htaccess</filename>
|
||
|
conventions, you can disable their creation by editing
|
||
|
<filename>localconfig</filename>
|
||
|
and setting the
|
||
|
<varname>$create_htaccess</varname>
|
||
|
variable to
|
||
|
<parameter>0</parameter>.
|
||
|
</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="win32" xreflabel="Win32 Installation Notes">
|
||
|
<title>Win32 Installation Notes</title>
|
||
|
|
||
|
<para>This section covers installation on Microsoft Windows.
|
||
|
Bugzilla has been made to work on Win32 platforms, but the Bugzilla team
|
||
|
wish to emphasise that The easiest way to install Bugzilla on
|
||
|
Intel-archiecture machines
|
||
|
is to install some variant of GNU/Linux, then follow the UNIX
|
||
|
installation instructions in this Guide. If you have any influence in the
|
||
|
platform choice for running this system, please choose GNU/Linux instead
|
||
|
of Microsoft Windows.</para>
|
||
|
|
||
|
<warning>
|
||
|
<para>After that warning, here's the situation for 2.16
|
||
|
and Windows. It doesn't work at all out of the box.
|
||
|
You are almost certainly better off getting
|
||
|
the 2.17 version from CVS (after consultation with the Bugzilla Team to
|
||
|
make sure you are pulling on a stable day) because we'll be doing a load
|
||
|
of work to make the Win32 experience more pleasant than it is now.
|
||
|
</para>
|
||
|
</warning>
|
||
|
|
||
|
<para>
|
||
|
If you still want to try this, to have any hope of getting it to work,
|
||
|
you'll need to apply the
|
||
|
<ulink url="">mail patch</ulink> from
|
||
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=124174">bug 124174</ulink>.
|
||
|
After that, you'll need to read the (outdated) installation
|
||
|
instructions below, some (probably a lot better) <ulink url="http://bugzilla.mozilla.org/attachment.cgi?id=84430&action=view">more
|
||
|
recent ones</ulink> kindly provided by Toms Baugis and Jean-Sebastien
|
||
|
Guay, and also check the
|
||
|
<ulink url="http://www.bugzilla.org/releases/2.16/docs/win32.html">Bugzilla 2.16 Win32 update page
|
||
|
</ulink>. If we get time,
|
||
|
we'll write some better installation instructions for 2.16 and put
|
||
|
them up there. But no promises.
|
||
|
</para>
|
||
|
|
||
|
<section id="wininstall" xreflabel="Win32 Installation: Step-by-step">
|
||
|
<title>Win32 Installation: Step-by-step</title>
|
||
|
|
||
|
<note>
|
||
|
<para>You should be familiar with, and cross-reference, the rest of
|
||
|
the
|
||
|
<xref linkend="installation" />
|
||
|
|
||
|
section while performing your Win32 installation.</para>
|
||
|
|
||
|
<para>Making Bugzilla work on Microsoft Windows is no picnic. Support
|
||
|
for Win32 has improved dramatically in the last few releases, but, if
|
||
|
you choose to proceed, you should be a
|
||
|
<emphasis>very</emphasis>
|
||
|
|
||
|
skilled Windows Systems Administrator with strong troubleshooting
|
||
|
abilities, a high tolerance for pain, and moderate perl skills.
|
||
|
Bugzilla on NT requires hacking source code and implementing some
|
||
|
advanced utilities. What follows is the recommended installation
|
||
|
procedure for Win32; additional suggestions are provided in
|
||
|
<xref linkend="faq" />
|
||
|
|
||
|
.</para>
|
||
|
</note>
|
||
|
|
||
|
<procedure>
|
||
|
<step>
|
||
|
<para>Install
|
||
|
<ulink url="http://www.apache.org/">Apache Web Server</ulink>
|
||
|
|
||
|
for Windows, and copy the Bugzilla files somewhere Apache can serve
|
||
|
them. Please follow all the instructions referenced in
|
||
|
<xref linkend="installation" />
|
||
|
|
||
|
regarding your Apache configuration, particularly instructions
|
||
|
regarding the
|
||
|
<quote>AddHandler</quote>
|
||
|
|
||
|
parameter and
|
||
|
<quote>ExecCGI</quote>
|
||
|
|
||
|
.</para>
|
||
|
|
||
|
<note>
|
||
|
<para>You may also use Internet Information Server or Personal
|
||
|
Web Server for this purpose. However, setup is quite different.
|
||
|
If ActivePerl doesn't seem to handle your file associations
|
||
|
correctly (for .cgi and .pl files), please consult
|
||
|
<xref linkend="faq" />
|
||
|
|
||
|
.</para>
|
||
|
|
||
|
<para>If you are going to use IIS, if on Windows NT you must be
|
||
|
updated to at least Service Pack 4. Windows 2000 ships with a
|
||
|
sufficient version of IIS.</para>
|
||
|
</note>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Install
|
||
|
<ulink url="http://www.activestate.com/">ActivePerl</ulink>
|
||
|
|
||
|
for Windows. Check
|
||
|
<ulink
|
||
|
url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/">
|
||
|
http://aspn.activestate.com/ASPN/Downloads/ActivePerl</ulink>
|
||
|
|
||
|
for a current compiled binary.</para>
|
||
|
|
||
|
<para>Please also check the following links to fully understand the
|
||
|
status of ActivePerl on Win32:
|
||
|
<ulink url="http://language.perl.com/newdocs/pod/perlport.html">
|
||
|
Perl Porting</ulink>
|
||
|
|
||
|
, and
|
||
|
<ulink
|
||
|
url="http://ftp.univie.ac.at/packages/perl/ports/nt/FAQ/perlwin32faq5.html">
|
||
|
Perl on Win32 FAQ</ulink>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Use ppm from your perl\bin directory to install the following
|
||
|
packs: DBI, DBD-Mysql, TimeDate, Chart, Date-Calc, Date-Manip, GD,
|
||
|
AppConfig, and Template. You may need to extract them from .zip
|
||
|
format using Winzip or other unzip program first. Most of these
|
||
|
additional ppm modules can be downloaded from ActiveState, but
|
||
|
AppConfig and Template should be obtained from OpenInteract using
|
||
|
<ulink type="http" url="http://openinteract.sourceforge.net/">the
|
||
|
instructions on the Template Toolkit web site</ulink>
|
||
|
|
||
|
.</para>
|
||
|
|
||
|
<note>
|
||
|
<para>You can find a list of modules at
|
||
|
<ulink
|
||
|
url="http://www.activestate.com/PPMPackages/zips/5xx-builds-only">
|
||
|
http://www.activestate.com/PPMPackages/zips/5xx-builds-only/</ulink>
|
||
|
|
||
|
or
|
||
|
<ulink url="http://www.activestate.com/PPMPackages/5.6plus">
|
||
|
http://www.activestate.com/PPMPackages/5.6plus</ulink>
|
||
|
</para>
|
||
|
</note>
|
||
|
|
||
|
<para>The syntax for ppm is:
|
||
|
<computeroutput>
|
||
|
<prompt>C:></prompt>
|
||
|
|
||
|
<command>ppm <modulename></command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
|
||
|
<example>
|
||
|
<title>Installing ActivePerl ppd Modules on Microsoft
|
||
|
Windows</title>
|
||
|
|
||
|
<para>
|
||
|
<prompt>C:></prompt>
|
||
|
|
||
|
<command>ppm
|
||
|
<option>DBD-Mysql</option>
|
||
|
</command>
|
||
|
</para>
|
||
|
|
||
|
<para>Watch your capitalization!</para>
|
||
|
</example>
|
||
|
|
||
|
<para>ActiveState's 5.6Plus directory also contains an AppConfig
|
||
|
ppm, so you might see the following error when trying to install
|
||
|
the version at OpenInteract:</para>
|
||
|
|
||
|
<para>
|
||
|
<computeroutput>Error installing package 'AppConfig': Read a PPD
|
||
|
for 'AppConfig', but it is not intended for this build of Perl
|
||
|
(MSWin32-x86-multi-thread)</computeroutput>
|
||
|
</para>
|
||
|
|
||
|
<para>If so, download both
|
||
|
<ulink
|
||
|
url="http://openinteract.sourceforge.net/ppmpackages/AppConfig.tar.gz">
|
||
|
the tarball</ulink>
|
||
|
|
||
|
and
|
||
|
<ulink
|
||
|
url="http://openinteract.sourceforge.net/ppmpackages/AppConfig.ppd">
|
||
|
the ppd</ulink>
|
||
|
|
||
|
directly from OpenInteract, then run ppm from within the same
|
||
|
directory to which you downloaded those files and install the
|
||
|
package by referencing the ppd file explicitly via in the install
|
||
|
command, f.e.:
|
||
|
<example>
|
||
|
<title>Installing OpenInteract ppd Modules manually on Microsoft
|
||
|
Windows</title>
|
||
|
|
||
|
<para>
|
||
|
<computeroutput>
|
||
|
<command>install
|
||
|
<filename>C:\AppConfig.ppd</filename>
|
||
|
</command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
</example>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Install MySQL for NT.
|
||
|
<note>
|
||
|
<para>You can download MySQL for Windows NT from
|
||
|
<ulink url="http://www.mysql.com/">MySQL.com</ulink>
|
||
|
|
||
|
. Some find it helpful to use the WinMySqlAdmin utility, included
|
||
|
with the download, to set up the database.</para>
|
||
|
</note>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Setup MySQL</para>
|
||
|
|
||
|
<substeps>
|
||
|
<step>
|
||
|
<para>
|
||
|
<computeroutput>
|
||
|
<prompt>C:></prompt>
|
||
|
|
||
|
<command>C:\mysql\bin\mysql -u root mysql</command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>
|
||
|
<computeroutput>
|
||
|
<prompt>mysql></prompt>
|
||
|
|
||
|
<command>DELETE FROM user WHERE Host='localhost' AND
|
||
|
User='';</command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>
|
||
|
<computeroutput>
|
||
|
<prompt>mysql></prompt>
|
||
|
|
||
|
<command>UPDATE user SET Password=PASSWORD ('new_password')
|
||
|
WHERE user='root';</command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
<quote>new_password</quote>
|
||
|
|
||
|
, above, indicates whatever password you wish to use for your
|
||
|
<quote>root</quote>
|
||
|
|
||
|
user.</para>
|
||
|
</step>
|
||
|
|
||
|
<step id="ntbugs-password">
|
||
|
<para>
|
||
|
<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>
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
<quote>bugs_password</quote>
|
||
|
|
||
|
, above, indicates whatever password you wish to use for your
|
||
|
<quote>bugs</quote>
|
||
|
|
||
|
user.</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>
|
||
|
<computeroutput>
|
||
|
<prompt>mysql></prompt>
|
||
|
|
||
|
<command>FLUSH PRIVILEGES;</command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>
|
||
|
<computeroutput>
|
||
|
<prompt>mysql></prompt>
|
||
|
|
||
|
<command>create database bugs;</command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>
|
||
|
<computeroutput>
|
||
|
<prompt>mysql></prompt>
|
||
|
|
||
|
<command>exit;</command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>
|
||
|
<computeroutput>
|
||
|
<prompt>C:></prompt>
|
||
|
|
||
|
<command>C:\mysql\bin\mysqladmin -u root -p
|
||
|
reload</command>
|
||
|
</computeroutput>
|
||
|
</para>
|
||
|
</step>
|
||
|
</substeps>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Edit
|
||
|
<filename>checksetup.pl</filename>
|
||
|
|
||
|
in your Bugzilla directory. Change this line:</para>
|
||
|
|
||
|
<para>
|
||
|
<programlisting>my $webservergid =
|
||
|
getgrnam($my_webservergroup);</programlisting>
|
||
|
</para>
|
||
|
|
||
|
<para>to</para>
|
||
|
|
||
|
<para>
|
||
|
<programlisting>my $webservergid =
|
||
|
$my_webservergroup;</programlisting>
|
||
|
|
||
|
or the name of the group you wish to own the files explicitly:
|
||
|
<programlisting>my $webservergid =
|
||
|
'Administrators'</programlisting>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Run
|
||
|
<filename>checksetup.pl</filename>
|
||
|
|
||
|
from the Bugzilla directory.</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Edit
|
||
|
<filename>localconfig</filename>
|
||
|
|
||
|
to suit your requirements. Set
|
||
|
<varname>$db_pass</varname>
|
||
|
|
||
|
to your
|
||
|
<quote>bugs_password</quote>
|
||
|
|
||
|
from
|
||
|
<xref linkend="ntbugs-password" />
|
||
|
|
||
|
, and
|
||
|
<varname>$webservergroup</varname>
|
||
|
|
||
|
to
|
||
|
<quote>8</quote>
|
||
|
|
||
|
.</para>
|
||
|
|
||
|
<note>
|
||
|
<para>Not sure on the
|
||
|
<quote>8</quote>
|
||
|
|
||
|
for
|
||
|
<varname>$webservergroup</varname>
|
||
|
|
||
|
above. If it's wrong, please send corrections.</para>
|
||
|
</note>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Edit
|
||
|
<filename>defparams.pl</filename>
|
||
|
|
||
|
to suit your requirements. Particularly, set
|
||
|
<varname>DefParam("maintainer")</varname>
|
||
|
|
||
|
and
|
||
|
<varname>DefParam("urlbase") to match your install.</varname>
|
||
|
</para>
|
||
|
|
||
|
<note>
|
||
|
<para>This is yet another step I'm not sure of, since the
|
||
|
maintainer of this documentation does not maintain Bugzilla on
|
||
|
NT. If you can confirm or deny that this step is required, please
|
||
|
let me know.</para>
|
||
|
</note>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<note>
|
||
|
<para>There are several alternatives to Sendmail that will work
|
||
|
on Win32. The one mentioned here is a
|
||
|
<emphasis>suggestion</emphasis>
|
||
|
|
||
|
, not a requirement. Some other mail packages that can work
|
||
|
include
|
||
|
<ulink url="http://www.blat.net/">BLAT</ulink>
|
||
|
|
||
|
,
|
||
|
<ulink url="http://www.geocel.com/windmail/">Windmail</ulink>
|
||
|
|
||
|
,
|
||
|
<ulink url="http://www.dynamicstate.com/">Mercury
|
||
|
Sendmail</ulink>
|
||
|
|
||
|
, and the CPAN Net::SMTP Perl module (available in .ppm). Every
|
||
|
option requires some hacking of the Perl scripts for Bugzilla to
|
||
|
make it work. The option here simply requires the least.</para>
|
||
|
</note>
|
||
|
|
||
|
<procedure>
|
||
|
<step>
|
||
|
<para>Download NTsendmail, available from
|
||
|
<ulink url="http://www.ntsendmail.com/">
|
||
|
www.ntsendmail.com</ulink>
|
||
|
|
||
|
. You must have a "real" mail server which allows you to relay
|
||
|
off it in your $ENV{"NTsendmail"} (which you should probably
|
||
|
place in globals.pl)</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Put ntsendmail.pm into your .\perl\lib directory.</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Add to globals.pl:</para>
|
||
|
|
||
|
<programlisting># these settings configure the NTsendmail
|
||
|
process use NTsendmail;
|
||
|
$ENV{"NTsendmail"}="your.smtpserver.box";
|
||
|
$ENV{"NTsendmail_debug"}=1;
|
||
|
$ENV{"NTsendmail_max_tries"}=5;</programlisting>
|
||
|
|
||
|
<note>
|
||
|
<para>Some mention to also edit
|
||
|
<varname>$db_pass</varname>
|
||
|
|
||
|
in
|
||
|
<filename>globals.pl</filename>
|
||
|
|
||
|
to be your
|
||
|
<quote>bugs_password</quote>
|
||
|
|
||
|
. Although this may get you around some problem
|
||
|
authenticating to your database, since globals.pl is not
|
||
|
normally restricted by
|
||
|
<filename>.htaccess</filename>
|
||
|
|
||
|
, your database password is exposed to whoever uses your web
|
||
|
server.</para>
|
||
|
</note>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Find and comment out all occurences of
|
||
|
<quote>
|
||
|
<command>open(SENDMAIL</command>
|
||
|
</quote>
|
||
|
|
||
|
in your Bugzilla directory. Then replace them with:
|
||
|
<programlisting># new sendmail functionality my $mail=new
|
||
|
NTsendmail; my $from="bugzilla\@your.machine.name.tld"; my
|
||
|
$to=$login; my $subject=$urlbase;
|
||
|
$mail->send($from,$to,$subject,$msg);</programlisting>
|
||
|
</para>
|
||
|
|
||
|
<note>
|
||
|
<para>Some have found success using the commercial product,
|
||
|
<productname>Windmail</productname>
|
||
|
|
||
|
. You could try replacing your sendmail calls with:
|
||
|
<programlisting>open SENDMAIL,
|
||
|
"|\"C:/General/Web/tools/Windmail 4.0 Beta/windmail\" -t >
|
||
|
mail.log";</programlisting>
|
||
|
|
||
|
or something to that effect.</para>
|
||
|
</note>
|
||
|
</step>
|
||
|
</procedure>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Change all references in all files from
|
||
|
<filename>processmail</filename>
|
||
|
|
||
|
to
|
||
|
<filename>processmail.pl</filename>
|
||
|
|
||
|
, and rename
|
||
|
<filename>processmail</filename>
|
||
|
|
||
|
to
|
||
|
<filename>processmail.pl</filename>
|
||
|
|
||
|
.</para>
|
||
|
|
||
|
<note>
|
||
|
<para>Many think this may be a change we want to make for
|
||
|
main-tree Bugzilla. It's painless for the UNIX folks, and will
|
||
|
make the Win32 people happier.</para>
|
||
|
</note>
|
||
|
|
||
|
<note>
|
||
|
<para>Some people have suggested using the Net::SMTP Perl module
|
||
|
instead of NTsendmail or the other options listed here. You can
|
||
|
change processmail.pl to make this work.
|
||
|
<programlisting>
|
||
|
<![CDATA[
|
||
|
|
||
|
my $smtp = Net::SMTP->new('<Name of your SMTP server>'); #connect to SMTP server
|
||
|
$smtp->mail('<your name>@<you smpt server>');# use the sender's adress here
|
||
|
$smtp->to($tolist); # recipient's address
|
||
|
$smtp->data(); # Start the mail
|
||
|
$smtp->datasend($msg);
|
||
|
$smtp->dataend(); # Finish sending the mail
|
||
|
$smtp->quit; # Close the SMTP connection
|
||
|
$logstr = "$logstr; mail sent to $tolist $cclist";
|
||
|
}
|
||
|
|
||
|
]]>
|
||
|
</programlisting>
|
||
|
|
||
|
here is a test mail program for Net::SMTP:
|
||
|
<programlisting>
|
||
|
<![CDATA[
|
||
|
|
||
|
use Net::SMTP;
|
||
|
my $smtp = Net::SMTP->new('<Name of your SMTP server', Timeout => 30, Debug
|
||
|
=> 1, ); # connect to SMTP server
|
||
|
$smtp->auth;
|
||
|
$smtp->mail('you@yourcompany.com');# use the sender's adress
|
||
|
here
|
||
|
$smtp->to('someotherAddress@someotherdomain.com'); #
|
||
|
recipient's address
|
||
|
$smtp->data(); # Start the mail
|
||
|
$smtp->datasend('test');
|
||
|
$smtp->dataend(); # Finish sending the mail
|
||
|
$smtp->quit; # Close the SMTP connection
|
||
|
exit;
|
||
|
|
||
|
]]>
|
||
|
</programlisting>
|
||
|
</para>
|
||
|
</note>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<note>
|
||
|
<para>This step is optional if you are using IIS or another web
|
||
|
server which only decides on an interpreter based upon the file
|
||
|
extension (.pl), rather than the
|
||
|
<quote>shebang</quote>
|
||
|
|
||
|
line (#/usr/bonsaitools/bin/perl)</para>
|
||
|
</note>
|
||
|
|
||
|
<para>Modify the path to perl on the first line (#!) of all files
|
||
|
to point to your Perl installation, and add
|
||
|
<quote>perl</quote>
|
||
|
|
||
|
to the beginning of all Perl system calls that use a perl script as
|
||
|
an argument. This may take you a while. There is a
|
||
|
<quote>setperl.csh</quote>
|
||
|
|
||
|
utility to speed part of this procedure, available in the
|
||
|
<xref linkend="patches" />
|
||
|
|
||
|
section of The Bugzilla Guide. However, it requires the Cygwin
|
||
|
GNU-compatible environment for Win32 be set up in order to work.
|
||
|
See
|
||
|
<ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>
|
||
|
|
||
|
for details on obtaining Cygwin.</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Modify the invocation of all system() calls in all perl
|
||
|
scripts in your Bugzilla directory. You should specify the full
|
||
|
path to perl for each system() call. For instance, change this line
|
||
|
in processmail:
|
||
|
<programlisting>
|
||
|
<![CDATA[
|
||
|
system ("./processmail",@ARGLIST);
|
||
|
</programlisting> to
|
||
|
<programlisting>
|
||
|
system ("C:\\perl\\bin\\perl", "processmail", @ARGLIST);
|
||
|
]]>
|
||
|
</programlisting>
|
||
|
</para>
|
||
|
</step>
|
||
|
|
||
|
<step>
|
||
|
<para>Add
|
||
|
<function>binmode()</function>
|
||
|
|
||
|
calls so attachments will work (
|
||
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=62000">bug
|
||
|
62000</ulink>
|
||
|
|
||
|
).</para>
|
||
|
|
||
|
<para>Because Microsoft Windows based systems handle binary files
|
||
|
different than Unix based systems, you need to add the following
|
||
|
lines to
|
||
|
<filename>createattachment.cgi</filename>
|
||
|
|
||
|
and
|
||
|
<filename>showattachment.cgi</filename>
|
||
|
|
||
|
before the
|
||
|
<function>require 'CGI.pl';</function>
|
||
|
|
||
|
line.</para>
|
||
|
|
||
|
<para>
|
||
|
<programlisting>
|
||
|
<![CDATA[
|
||
|
binmode(STDIN);
|
||
|
binmode(STDOUT);
|
||
|
]]>
|
||
|
</programlisting>
|
||
|
</para>
|
||
|
|
||
|
<note>
|
||
|
<para>According to
|
||
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=62000">
|
||
|
bug 62000</ulink>
|
||
|
|
||
|
, the perl documentation says that you should always use
|
||
|
<function>binmode()</function>
|
||
|
|
||
|
when dealing with binary files, but never when dealing with text
|
||
|
files. That seems to suggest that rather than arbitrarily putting
|
||
|
|
||
|
<function>binmode()</function>
|
||
|
|
||
|
at the beginning of the attachment files, there should be logic
|
||
|
to determine if
|
||
|
<function>binmode()</function>
|
||
|
|
||
|
is needed or not.</para>
|
||
|
</note>
|
||
|
</step>
|
||
|
</procedure>
|
||
|
|
||
|
<tip>
|
||
|
<para>If you are using IIS or Personal Web Server, you must add cgi
|
||
|
relationships to Properties -> Home directory (tab) ->
|
||
|
Application Settings (section) -> Configuration (button), such
|
||
|
as:</para>
|
||
|
|
||
|
<para>
|
||
|
<programlisting>.cgi to: <perl install directory>\perl.exe %s
|
||
|
%s .pl to: <perl install directory>\perl.exe %s %s
|
||
|
GET,HEAD,POST</programlisting>
|
||
|
|
||
|
Change the path to Perl to match your install, of course.</para>
|
||
|
</tip>
|
||
|
</section>
|
||
|
|
||
|
<section id="addlwintips">
|
||
|
<title>Additional Windows Tips</title>
|
||
|
|
||
|
<tip>
|
||
|
<para>From Andrew Pearson:
|
||
|
<blockquote>
|
||
|
<para>You can make Bugzilla work with Personal Web Server for
|
||
|
Windows 98 and higher, as well as for IIS 4.0. Microsoft has
|
||
|
information available at
|
||
|
<ulink
|
||
|
url=" http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP">
|
||
|
http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP</ulink>
|
||
|
</para>
|
||
|
|
||
|
<para>Basically you need to add two String Keys in the registry at
|
||
|
the following location:</para>
|
||
|
|
||
|
<para>
|
||
|
<programlisting>
|
||
|
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap</programlisting>
|
||
|
</para>
|
||
|
|
||
|
<para>The keys should be called ".pl" and ".cgi", and both should
|
||
|
have a value something like:
|
||
|
<command>c:/perl/bin/perl.exe "%s" "%s"</command>
|
||
|
</para>
|
||
|
|
||
|
<para>The KB article only talks about .pl, but it goes into more
|
||
|
detail and provides a perl test script.</para>
|
||
|
</blockquote>
|
||
|
</para>
|
||
|
</tip>
|
||
|
|
||
|
<tip>
|
||
|
<para>If attempting to run Bugzilla 2.12 or older, you will need to
|
||
|
remove encrypt() calls from the Perl source. This is
|
||
|
<emphasis>not necessary</emphasis>
|
||
|
|
||
|
for Bugzilla 2.13 and later, which includes the current release,
|
||
|
Bugzilla &bz-ver;.
|
||
|
<example>
|
||
|
<title>Removing encrypt() for Windows NT Bugzilla version 2.12 or
|
||
|
earlier</title>
|
||
|
|
||
|
<para>Replace this:
|
||
|
<programlisting>SendSQL("SELECT encrypt(" . SqlQuote($enteredpwd) .
|
||
|
", " . SQLQuote(substr($realcryptpwd, 0, 2)) . ")"); my
|
||
|
$enteredcryptpwd = FetchOneColumn();</programlisting>
|
||
|
|
||
|
with this:
|
||
|
<programlisting>my $enteredcryptpwd = $enteredpwd</programlisting>
|
||
|
|
||
|
in cgi.pl.</para>
|
||
|
</example>
|
||
|
</para>
|
||
|
</tip>
|
||
|
</section>
|
||
|
</section>
|
||
|
|
||
|
<section id="osx">
|
||
|
<title>Mac OS X Installation Notes</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
|
||
|
<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="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:
|
||
|
-->
|
||
|
|