These installation instructions are presented assuming you are
...
...
@@ -50,6 +50,7 @@
refer to these documents when installing, configuring, and
maintaining your Bugzilla installation.
</member>
</simplelist>
<warning>
...
...
@@ -108,8 +109,7 @@
the CPAN dependencies listed below, and are running the very
most recent version of Perl and MySQL (both the executables
and development libraries) on your system, check out
Bundle::Bugzilla in <xref
linkend="bundlebugzilla"></para>
Bundle::Bugzilla in <xreflinkend="bundlebugzilla"></para>
</note>
<para>
The software packages necessary for the proper running of bugzilla are:
...
...
@@ -185,39 +185,64 @@
attack.
</para>
</warning>
<note>
<para>Linux-Mandrake 8.0, the author's test system, 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>
<sectionid="install-mysql">
<title>Installing MySQL Database</title>
<para>
Visit MySQL homepage at http://www.mysql.com/ and grab the
latest stable release of the server. Both binaries and source
are available and which you get shouldn't matter. Be aware
that many of the binary versions of MySQL store their data
files in /var which on many installations (particularly common
with linux installations) is part of a smaller root partition.
If you decide to build from sources you can easily set the
dataDir as an option to configure.
Visit MySQL homepage at <ulink
url="http://www.mysql.com">www.mysql.com</ulink> and grab the latest stable release of the server. Many of the binary versions of MySQL store their data files in <filename>/var</filename> which is often part of a smaller root partition. If you decide to build from sources you can easily set the dataDir as an option to <filename>configure</filename>.
</para>
<para>
If you've installed from source or non-package (RPM, deb,
etc.) binaries you'll want to make sure to add mysqld to your
If you install from source or non-package (RPM, deb, etc.)
binaries you need to add
<firstterm>mysqld</firstterm> to your
init scripts so the server daemon will come back up whenever
your machine reboots. You also may want to edit those init
scripts, to make sure that mysqld will accept large packets.
By default, mysqld is set up to only accept packets up to 64K
long. This limits the size of attachments you may put on
bugs. If you add something like "-O max_allowed_packet=1M" to
the command that starts mysqld (or safe_mysqld), then you will
be able to have attachments up to about 1 megabyte.
your machine reboots. Further discussion of UNIX init
sequences are beyond the scope of this guide.
<note>
<para>You should have your init script start
<glossterm>mysqld</glossterm> 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.</para>
</note>
</para>
<note>
<para>
If you plan on running Bugzilla and MySQL on the same
machine, consider using the "--skip-networking" option in
the init script. This enhances security by preventing
network access to MySQL.
machine, consider using the <option>--skip-networking</option>
option in the init script. This enhances security by
preventing network access to MySQL.
</para>
</note>
</section>
...
...
@@ -260,9 +285,10 @@
<tipid="bundlebugzilla"xreflabel="Using Bundle::Bugzilla instead of manually installing Perl modules">
<para>
You can skip the following Perl module installation steps by
installing "Bundle::Bugzilla" from CPAN, which includes
them. All Perl module installation steps require you have an
active Internet connection. If you wish to use
installing <productname>Bundle::Bugzilla</productname> from
<glosstermlinkend="gloss_cpan">CPAN</glossterm>, which
includes them. All Perl module installation steps require
you have an active Internet connection. If you wish to use
Bundle::Bugzilla, however, you must be using the latest
version of Perl (at this writing, version &perl-ver;)
</para>
...
...
@@ -293,7 +319,7 @@
Like almost all Perl modules DBI can be found on the Comprehensive Perl
Archive Network (CPAN) at http://www.cpan.org. The CPAN servers have a
real tendency to bog down, so please use mirrors. The current location
at the time of this writing (02/17/99) can be found in Appendix A.
at the time of this writing can be found in <xreflinkend="downloadlinks">.
</para>
<para>
Quality, general Perl module installation instructions can be found on
...
...
@@ -370,9 +396,11 @@
hurt anything.
</para>
<para>
Data::Dumper is used by the MySQL-related Perl modules. It can be
found on CPAN (link in Appendix A) and can be installed by following
the same four step make sequence used for the DBI module.
Data::Dumper is used by the MySQL-related Perl modules. It
can be found on CPAN (see <xreflinkend="downloadlinks">) and
can be
installed by following the same four step make sequence used
for the DBI module.
</para>
</section>
...
...
@@ -414,37 +442,42 @@
<section>
<title>TimeDate Perl Module Collection</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. A link
link may be found in Appendix B, Software Download Links.
The component module we're
most interested in is the Date::Format module, but installing all of them
is probably a good idea anyway. The standard Perl module installation
instructions should work perfectly for this simple package.
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 (see link: <xreflinkend="downloadlinks">). The
component module we're most interested in is the Date::Format
module, but installing all of them is probably a good idea
anyway. The standard Perl module installation instructions
should work perfectly for this simple package.
</para>
</section>
<section>
<title>GD Perl Module (1.8.3)</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 almost a
defacto standard for programatic image construction. The Perl bindings
to it found in the GD library are used on a million web pages to generate
graphs on the fly. That's what bugzilla will be using it for so you'd
better install it if you want any of the graphing to work.
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>
<para>
Actually bugzilla uses the Graph module which relies on GD itself,
but isn't that always the way with OOP. At any rate, you can find the
GD library on CPAN (link in Appendix B, Software Download Links).
Actually bugzilla uses the Graph module which relies on GD
itself. Isn't that always the way with object-oriented
programming? At any rate, you can find the GD library on CPAN
in <xreflinkend="downloadlinks">.
</para>
<note>
<para>
The Perl GD library requires some other libraries that may or may not be
installed on your system, including "libpng" and "libgd". The full requirements
are listed in the Perl GD library README. Just realize that if compiling GD fails,
it's probably because you're missing a required library.
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. Just realize that if
compiling GD fails, it's probably because you're missing a
required library.
</para>
</note>
</section>
...
...
@@ -453,62 +486,78 @@
<title>Chart::Base Perl Module (0.99c)</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 where it is found as the Chart-x.x... tarball in a
directory to be listed in Appendix B, "Software Download Links".
Note that as with the GD perl
module, only the version listed above, or newer, will work.
Earlier
versions used GIF's, which are no longer supported by the latest
versions of GD.
abilities. It can be installed in the usual fashion after it
has been fetched from CPAN where it is found as the
Chart-x.x... tarball, linked in <xreflinkend="downloadlinks">. Note that
as with the GD perl module, only the version listed above, or
newer, will work. Earlier versions used GIF's, which are no
longer supported by the latest versions of GD.
</para>
</section>
<section>
<title>DB_File Perl Module</title>
<para>
DB_File is a module which allows Perl programs to make use of the facilities provided by
Berkeley DB version 1.x. This module is required by collectstats.pl which is used for
bug charting. If you plan to make use of bug charting, you must install this module.
DB_File is a module which allows Perl programs to make use
of the facilities provided by Berkeley DB version 1.x. This
module is required by collectstats.pl which is used for bug
charting. If you plan to make use of bug charting, you must
install this module.
</para>
</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 easily run the web server on a different
machine than MySQL, but need to adjust the MySQL "bugs" user permissions
accordingly.
You have a freedom of choice here - Apache, Netscape or any
other server on UNIX would do. You can easily run the web
server on a different machine than MySQL, but need to adjust
the MySQL <quote>bugs</quote> user permissions accordingly.
<note>
<para>I strongly recommend Apache as the web server to use.
The Bugzilla Guide installation instructions, in general,
assume you are using Apache. As more users use different
webservers and send me information on the peculiarities of
installing using their favorite webserver, I will provide
notes for them.</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 srm.conf file:
</simplelist> replacing XXX with the Bugzilla email address.
</para>
...
...
@@ -1156,33 +1203,74 @@ bash# ./checksetup.pl
<parameter>0</parameter>.
</para>
</section>
<sectionid="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 <ulinkurl="http://www.snert.com/Software/Throttle/">Module Instructions</ulink> for more information. </para>
<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# cd $BUGZILLA_HOME; for i in `ls *.cgi`; \
do cat $i | sed 's/Content-type\: text\/html/Content-Type: text\/html\; charset=ISO-8859-1/' >$i.tmp; \
mv $i.tmp $i; done
</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
This document was heavily modified again Wednesday, March 07 2001 to
reflect changes for Bugzilla 2.12 release by Matthew P. Barnson. The
securing MySQL section should be changed to become standard procedure
for Bugzilla installations.
This document was heavily modified again Wednesday, March 07
2001 to reflect changes for Bugzilla 2.12 release by Matthew
P. Barnson. The securing MySQL section should be changed to
become standard procedure for Bugzilla installations.
</para>
<para>
Finally, the README in its entirety was marked up in SGML and included into
the Guide on April 24, 2001 by Matt Barnson. Since that time, it's undergone
extensive modification as Bugzilla grew.
Finally, the README in its entirety was marked up in SGML and
included into the Guide on April 24, 2001 by Matt Barnson.
Since that time, it's undergone extensive modification as
Bugzilla grew.
</para>
<para>
Comments from people using this Guide for the first time are particularly welcome.
Comments from people using this Guide for the first time are
particularly welcome.
</para>
</section>
</section>
...
...
@@ -1217,27 +1305,33 @@ bash# ./checksetup.pl
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 both strong troubleshooting abilities and
a high tolerance for pain. 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 <xreflinkend="faq">.
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
<xreflinkend="faq">.
</para>
</note>
<procedure>
<step>
<para>
Install <ulinkurl="http://www.apache.org/">Apache Web Server</ulink>
for Windows.
Install <ulinkurl="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 <xreflinkend="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 slightly more
difficult. If ActivePerl doesn't seem to handle your file
associations correctly (for .cgi and .pl files), please
consult <xreflinkend="faq">.
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 <xreflinkend="faq">.
</para>
<para>
If you are going to use IIS, if on Windows NT you must
...
...
@@ -1299,8 +1393,7 @@ bash# ./checksetup.pl
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.
You can download MySQL for Windows NT from <ulinkurl="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>
...
...
@@ -1393,13 +1486,21 @@ bash# ./checksetup.pl
this line:
</para>
<para>
"my $webservergid = getgrnam($my_webservergroup); "
<programlisting>
my $webservergid = getgrnam($my_webservergroup);
</programlisting>
</para>
<para>
to
</para>
<para>
"my $webservergid = $my_webservergroup; "
<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>
...
...
@@ -1412,8 +1513,7 @@ bash# ./checksetup.pl
<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>
<quote>bugs_password</quote> from <xreflinkend="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
...
...
@@ -1455,8 +1555,7 @@ bash# ./checksetup.pl
<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)
Download NTsendmail, available from<ulinkurl="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)
Integration of Perforce with Bugzilla, once patches are applied, is fairly seamless. However,
p4dti is a patch against the Bugzilla 2.10 release, not the current 2.12 release. I anticipate
patches for 2.12 will be out shortly. Check the project page regularly for updates, or
take the given patches and patch it manually. p4dti is designed to support multiple defect
trackers, and maintains its own documentation for it. Please consult the pages linked
above for further information.
You can find the project page for Bugzilla and Teamtrack
Perforce integration (p4dti) at: <ulink
url="http://www.ravenbrook.com/project/p4dti/"> http://www.ravenbrook.com/project/p4dti</ulink> . <quote>p4dti</quote> is now an officially supported product from Perforce, and you can find the "Perforce Public Depot" p4dti page at <ulinkurl="http://public.perforce.com/public/perforce/p4dti/index.html"> http://public.perforce.com/public/perforce/p4dti/index.html</ulink>.
</para>
<para>
Right now, there is no way to synchronize the Bug ID and the Perforce Transaction Number, or
to change the Bug ID to read (PRODUCT).bugID unless you hack it in. Additionally, if you
have synchronization problems, the easiest way to avoid them is to only put the bug
information, comments, etc. into Bugzilla, and not into the Perforce change records.
They will link anyway; merely reference the bug ID fixed in your change description,
and put a comment into Bugzilla
giving the change ID that fixed the Bugzilla bug. It's a process issue, not a technology
question.
Integration of Perforce with Bugzilla, once patches are applied,
is seamless. Perforce replication information will appear below
the comments of each bug. Be certain you have a matching set of
patches for the Bugzilla version you are installing. p4dti is
designed to support multiple defect trackers, and maintains its
own documentation for it. Please consult the pages linked above
for further information.
</para>
</section>
<sectionid="tinderbox">
<title>Tinderbox</title>
<para>We need Tinderbox integration information</para>
<sectionid="tinderbox"xreflabel="Tinderbox, the Mozilla automated build management system">
<title>Tinderbox/Tinderbox2</title>
<para>We need Tinderbox integration information.</para>
<para>Apache's <filename>mod_rewrite</filename> module lets you do some truly amazing things with URL rewriting. Here are a couple of examples of what you can do.</para>
Some people have run into difficulties completing this
tutorial. If you run into problems, please check the
updated online documentation available at <ulink
url="http://www.trilobyte.net/barnsons/">http://www.trilobyte.net/barnsons</ulink>. If you're still stumped, please subscribe to the newsgroup and provide details of exactly what's stumping you! If enough people complain, I'll have to fix it in the next version of this Guide. You can subscribe to the newsgroup at <ulinkurl="news://news.mozilla.org/netscape.public.mozilla.webtools"> news://news.mozilla.org/netscape.public.mozilla.webtools</ulink>
</para>
</note>
Although Landfill serves as a great introduction to Bugzilla, it does not offer
all the options you would have as a user on your own installation of Bugzilla,
nor can it do more than serve as a general introduction to Bugzilla. Additionally,
Landfill often runs cutting-edge versions of Bugzilla for testing, so some things
may work slightly differently than mentioned here.
</note> Although Landfill serves as a great introduction to
Bugzilla, it does not offer all the options you would have as a
user on your own installation of Bugzilla, nor can it do more
than serve as a general introduction to Bugzilla. Additionally,
Landfill often runs cutting-edge versions of Bugzilla for
testing, so some things may work slightly differently than
mentioned here.
</para>
<sectionid="myaccount">
<title>Create a Bugzilla Account</title>
<para>
First things first! If you want to use Bugzilla, first you need to create
an account. Consult with the administrator responsible for your installation
of Bugzilla for the URL you should use to access it.
If you're test-driving the end-user Bugzilla experience, use this URL:
Writing Guidelines</ulink>. While some of the advice is Mozilla-specific, the basic
principles of reporting Reproducible, Specific bugs, isolating the Product you are
using, the Version of the Product, the Component which failed, the Hardware Platform, and
Operating System you were using at the time of the failure go a long way toward ensuring accurate,
responsible fixes for the bug that bit you.
Before we plunge into writing your first bug report, I
encourage you to read some bug-writing guidelines. If you
are reading this document as part of a Bugzilla CVS checkout
or un-tarred Bugzilla distribution, you should be able to
read them by clicking <ulink
url="../../bugwritinghelp.html">here</ulink>. If you are reading this online, check out the Mozilla.org bug-writing guidelines at <ulinkurl="http://www.mozilla.org/quality/bug-writing-guidelines.html">http://www.mozilla.org/quality/bug-writing-guidelines.html</ulink>. While some of the advice is Mozilla-specific, the basic principles of reporting Reproducible, Specific bugs, isolating the Product you are using, the Version of the Product, the Component which failed, the Hardware Platform, and Operating System you were using at the time of the failure go a long way toward ensuring accurate, responsible fixes for the bug that bit you.
</para>
<para>
While you are at it, why not learn how to find previously reported bugs? Mozilla.org
has published a great tutorial on finding duplicate bugs, available at
box of the Query page, you will be presented a form that will describe what all
the components are.
If you click the hyperlink on the <ulink
url="http://bugzilla.mozilla.org/describecomponents.cgi">Component</ulink> box of the Query page, you will be presented a form that will describe what all the components are.
</para>
<para>
Possibly the most powerful feature of the Query page is the
It's a bit confusing to use the first time, but can provide unparalleled
flexibility in your queries,
allowing you to build extremely powerful requests.
Possibly the most powerful feature of the Query page is the
<ulink
url="http://bugzilla.mozilla.org/booleanchart.html">Boolean Chart</ulink> section. It's a bit confusing to use the first time, but can provide unparalleled flexibility in your queries, allowing you to build extremely powerful requests.
using the "Bug Reports" link near the bottom of the query page, and also
available via the "Reports" link
at the footer of each page.
Finally, you can build some nifty <ulink
url="http://bugzilla.mozilla.org/reports.cgi">Reports</ulink> using the "Bug Reports" link near the bottom of the query page, and also available via the "Reports" link at the footer of each page.
</para>
</section>
</section>
...
...
@@ -701,7 +734,7 @@ system against which all others are measured.
</section>
<sectionid="init4me">
<title>What's in it for me?</title>
<title>Where can I find my user preferences?</title>
<epigraph>
<para>
Indiana, it feels like we walking on fortune cookies!
...
...
@@ -711,98 +744,95 @@ system against which all others are measured.
</para>
</epigraph>
<para>
Customized User Preferences offer tremendous versatility to
your individual Bugzilla experience.
Let's plunge into what you can do! The first step is to click
the "Edit prefs" link at the footer of each page once you
mailing list/newsgroup. The mailing list is mirrored to the netscape.public.mozilla.webtools
newsgroup, and the newsgroup is mirrored to mozilla-webtools@mozilla.org
Thank you for reading through this portion of the Bugzilla
Guide. I anticipate it may not yet meet the needs of all
readers. If you have additional comments or corrections to
make, please submit your contributions to the <ulink
url="mailto://mozilla-webtools@mozilla.org">mozilla-webtools</ulink> mailing list/newsgroup. The mailing list is mirrored to the netscape.public.mozilla.webtools newsgroup, and the newsgroup is mirrored to mozilla-webtools@mozilla.org
