2463 lines
94 KiB
XML
2463 lines
94 KiB
XML
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
|
|
<chapter id="installing-bugzilla">
|
|
<title>Installing Bugzilla</title>
|
|
|
|
<section id="installation">
|
|
<title>Installation</title>
|
|
|
|
<note>
|
|
<para>If you just want to <emphasis>use</emphasis> Bugzilla,
|
|
you do not need to install it. None of this chapter is relevant to
|
|
you. Ask your Bugzilla administrator for the URL to access it from
|
|
your web browser.
|
|
</para>
|
|
</note>
|
|
|
|
<para>The Bugzilla server software is usually installed on Linux or
|
|
Solaris.
|
|
If you are installing on another OS, check <xref linkend="os-specific"/>
|
|
before you start your installation to see if there are any special
|
|
instructions.
|
|
</para>
|
|
|
|
<para>This guide assumes that you have administrative access to the
|
|
Bugzilla machine. It not possible to
|
|
install and run Bugzilla itself without administrative access except
|
|
in the very unlikely event that every single prerequisite is
|
|
already installed.
|
|
</para>
|
|
|
|
<warning>
|
|
<para>The installation process may make your machine insecure for
|
|
short periods of time. Make sure there is a firewall between you
|
|
and the Internet.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
You are strongly recommended to make a backup of your system
|
|
before installing Bugzilla (and at regular intervals thereafter :-).
|
|
</para>
|
|
|
|
<para>In outline, the installation proceeds as follows:
|
|
</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para><link linkend="install-perl">Install Perl</link>
|
|
(&min-perl-ver; or above)
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-database">Install a Database Engine</link>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-webserver">Install a Webserver</link>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-bzfiles">Install Bugzilla</link>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para><link linkend="install-perlmodules">Install Perl modules</link>
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
<link linkend="install-MTA">Install a Mail Transfer Agent</link>
|
|
(Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version)
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>Configure all of the above.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<section id="install-perl">
|
|
<title>Perl</title>
|
|
|
|
<para>Installed Version Test: <programlisting>perl -v</programlisting></para>
|
|
|
|
<para>Any machine that doesn't have Perl on it is a sad machine indeed.
|
|
If you don't have it and your OS doesn't provide official packages,
|
|
visit <ulink url="http://www.perl.org"/>.
|
|
Although Bugzilla runs with Perl &min-perl-ver;,
|
|
it's a good idea to be using the latest stable version.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-database">
|
|
<title>Database Engine</title>
|
|
|
|
<para>
|
|
Bugzilla supports MySQL, PostgreSQL and Oracle as database servers.
|
|
You only require one of these systems to make use of Bugzilla.
|
|
</para>
|
|
|
|
<section id="install-mysql">
|
|
<title>MySQL</title>
|
|
<para>Installed Version Test: <programlisting>mysql -V</programlisting></para>
|
|
|
|
<para>
|
|
If you don't have it and your OS doesn't provide official packages,
|
|
visit <ulink url="http://www.mysql.com"/>. You need MySQL version
|
|
&min-mysql-ver; or higher.
|
|
</para>
|
|
|
|
<note>
|
|
<para> Many of the binary
|
|
versions of MySQL store their data files in
|
|
<filename class="directory">/var</filename>.
|
|
On some Unix systems, this is part of a smaller root partition,
|
|
and may not have room for your bug database. To change the data
|
|
directory, you have to build MySQL from source yourself, and
|
|
set it as an option to <filename>configure</filename>.</para>
|
|
</note>
|
|
|
|
<para>If you install from something other than a packaging/installation
|
|
system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
|
|
(Windows Executable), or .msi (Microsoft Installer), make sure the MySQL
|
|
server is started when the machine boots.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-pg">
|
|
<title>PostgreSQL</title>
|
|
<para>Installed Version Test: <programlisting>psql -V</programlisting></para>
|
|
|
|
<para>
|
|
If you don't have it and your OS doesn't provide official packages,
|
|
visit <ulink url="http://www.postgresql.org/"/>. You need PostgreSQL
|
|
version &min-pg-ver; or higher.
|
|
</para>
|
|
|
|
<para>If you install from something other than a packaging/installation
|
|
system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
|
|
(Windows Executable), or .msi (Microsoft Installer), make sure the
|
|
PostgreSQL server is started when the machine boots.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-oracle">
|
|
<title>Oracle</title>
|
|
<para>
|
|
Installed Version Test: <programlisting>select * from v$version</programlisting>
|
|
(you first have to log in into your DB)
|
|
</para>
|
|
|
|
<para>
|
|
If you don't have it and your OS doesn't provide official packages,
|
|
visit <ulink url="http://www.oracle.com/"/>. You need Oracle
|
|
version &min-oracle-ver; or higher.
|
|
</para>
|
|
|
|
<para>
|
|
If you install from something other than a packaging/installation
|
|
system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
|
|
(Windows Executable), or .msi (Microsoft Installer), make sure the
|
|
Oracle server is started when the machine boots.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="install-webserver">
|
|
<title>Web Server</title>
|
|
|
|
<para>Installed Version Test: view the default welcome page at
|
|
http://<your-machine>/</para>
|
|
|
|
<para>You have freedom of choice here, pretty much any web server that
|
|
is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
|
|
scripts will work.
|
|
However, we strongly recommend using the Apache web server
|
|
(either 1.3.x or 2.x), and
|
|
the installation instructions usually assume you are
|
|
using it. If you have got Bugzilla working using another web server,
|
|
please share your experiences with us by filing a bug in &bzg-bugs;.
|
|
</para>
|
|
|
|
<para>
|
|
If you don't have Apache and your OS doesn't provide official packages,
|
|
visit <ulink url="http://httpd.apache.org/"/>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="install-bzfiles">
|
|
<title>Bugzilla</title>
|
|
|
|
<para>
|
|
<ulink url="http://www.bugzilla.org/download/">Download a Bugzilla tarball</ulink>
|
|
(or check it out from CVS) and place
|
|
it in a suitable directory, accessible by the default web server user
|
|
(probably <quote>apache</quote> or <quote>www</quote>).
|
|
Good locations are either directly in the web server's document directories or
|
|
in <filename>/usr/local</filename> with a symbolic link to the web server's
|
|
document directories or an alias in the web server's configuration.
|
|
</para>
|
|
|
|
<caution>
|
|
<para>The default Bugzilla distribution is NOT designed to be placed
|
|
in a <filename class="directory">cgi-bin</filename> directory. This
|
|
includes any directory which is configured using the
|
|
<option>ScriptAlias</option> directive of Apache.
|
|
</para>
|
|
</caution>
|
|
|
|
<para>Once all the files are in a web accessible directory, make that
|
|
directory writable by your web server's user. This is a temporary step
|
|
until you run the
|
|
<filename>checksetup.pl</filename>
|
|
script, which locks down your installation.</para>
|
|
</section>
|
|
|
|
<section id="install-perlmodules">
|
|
<title>Perl Modules</title>
|
|
|
|
<para>Bugzilla's installation process is based
|
|
on a script called <filename>checksetup.pl</filename>.
|
|
The first thing it checks is whether you have appropriate
|
|
versions of all the required
|
|
Perl modules. The aim of this section is to pass this check.
|
|
When it passes, proceed to <xref linkend="configuration"/>.
|
|
</para>
|
|
|
|
<para>
|
|
At this point, you need to <filename>su</filename> to root. You should
|
|
remain as root until the end of the install. To check you have the
|
|
required modules, run:
|
|
</para>
|
|
|
|
<screen><prompt>bash#</prompt> ./checksetup.pl --check-modules</screen>
|
|
|
|
<para>
|
|
<filename>checksetup.pl</filename> will print out a list of the
|
|
required and optional Perl modules, together with the versions
|
|
(if any) installed on your machine.
|
|
The list of required modules is reasonably long; however, you
|
|
may already have several of them installed.
|
|
</para>
|
|
|
|
<para>
|
|
The preferred way to install missing Perl modules is to use the package
|
|
manager provided by your operating system (e.g <quote>rpm</quote> or
|
|
<quote>yum</quote> on Linux distros, or <quote>ppm</quote> on Windows
|
|
if using ActivePerl, see <xref linkend="win32-perl-modules"/>).
|
|
If some Perl modules are still missing or are too old, then we recommend
|
|
using the <filename>install-module.pl</filename> script (doesn't work
|
|
with ActivePerl on Windows). If for some reason you really need to
|
|
install the Perl modules manually, see
|
|
<xref linkend="install-perlmodules-manual"/>. For instance, on Unix,
|
|
you invoke <filename>install-module.pl</filename> as follows:
|
|
</para>
|
|
|
|
<screen><prompt>bash#</prompt> perl install-module.pl <modulename></screen>
|
|
|
|
<tip>
|
|
<para>Many people complain that Perl modules will not install for
|
|
them. Most times, the error messages complain that they are missing a
|
|
file in
|
|
<quote>@INC</quote>.
|
|
Virtually every time, this error is due to permissions being set too
|
|
restrictively for you to compile Perl modules or not having the
|
|
necessary Perl development libraries installed on your system.
|
|
Consult your local UNIX systems administrator for help solving these
|
|
permissions issues; if you
|
|
<emphasis>are</emphasis>
|
|
the local UNIX sysadmin, please consult the newsgroup/mailing list
|
|
for further assistance or hire someone to help you out.</para>
|
|
</tip>
|
|
|
|
<note>
|
|
<para>If you are using a package-based system, and attempting to install the
|
|
Perl modules from CPAN, you may need to install the "development" packages for
|
|
MySQL and GD before attempting to install the related Perl modules. The names of
|
|
these packages will vary depending on the specific distribution you are using,
|
|
but are often called <filename><packagename>-devel</filename>.</para>
|
|
</note>
|
|
|
|
<para>
|
|
Here is a complete list of modules and their minimum versions.
|
|
Some modules have special installation notes, which follow.
|
|
</para>
|
|
|
|
<para>Required Perl modules:
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
<para>
|
|
CGI (&min-cgi-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Date::Format (&min-date-format-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
DateTime (&min-datetime-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
DateTime::TimeZone (&min-datetime-timezone-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
DBI (&min-dbi-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
DBD::mysql (&min-dbd-mysql-ver;) if using MySQL
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
DBD::Pg (&min-dbd-pg-ver;) if using PostgreSQL
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
DBD::Oracle (&min-dbd-oracle-ver;) if using Oracle
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Digest::SHA (&min-digest-sha-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Email::Send (&min-email-send-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Email::MIME (&min-email-mime-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Email::MIME::Encodings (&min-email-mime-encodings-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Email::MIME::Modifier (&min-email-mime-modifier-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Template (&min-template-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
URI (&min-uri-ver;)
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
Optional Perl modules:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
GD (&min-gd-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Template::Plugin::GD::Image
|
|
(&min-template-plugin-gd-image-ver;) for Graphical Reports
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Chart::Lines (&min-chart-lines-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
GD::Graph (&min-gd-graph-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
GD::Text (&min-gd-text-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
XML::Twig (&min-xml-twig-ver;) for bug import/export
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
MIME::Parser (&min-mime-parser-ver;) for bug import/export
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
LWP::UserAgent
|
|
(&min-lwp-useragent-ver;) for Automatic Update Notifications
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
PatchReader (&min-patchreader-ver;) for pretty HTML view of patches
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Net::LDAP
|
|
(&min-net-ldap-ver;) for LDAP Authentication
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Authen::SASL
|
|
(&min-authen-sasl-ver;) for SASL Authentication
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Authen::Radius
|
|
(&min-authen-radius-ver;) for RADIUS Authentication
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
SOAP::Lite (&min-soap-lite-ver;) for the web service interface
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
JSON::RPC
|
|
(&min-json-rpc-ver;) for the JSON-RPC interface
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Test::Taint
|
|
(&min-test-taint-ver;) for the web service interface
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
HTML::Parser
|
|
(&min-html-parser-ver;) for More HTML in Product/Group Descriptions
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
HTML::Scrubber
|
|
(&min-html-scrubber-ver;) for More HTML in Product/Group Descriptions
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Email::MIME::Attachment::Stripper
|
|
(&min-email-mime-attachment-stripper-ver;) for Inbound Email
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Email::Reply
|
|
(&min-email-reply-ver;) for Inbound Email
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
TheSchwartz
|
|
(&min-theschwartz-ver;) for Mail Queueing
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Daemon::Generic
|
|
(&min-daemon-generic-ver;) for Mail Queueing
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
mod_perl2
|
|
(&min-mod_perl2-ver;) for mod_perl
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-MTA">
|
|
<title>Mail Transfer Agent (MTA)</title>
|
|
|
|
<para>
|
|
Bugzilla is dependent on the availability of an e-mail system for its
|
|
user authentication and for other tasks.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
This is not entirely true. It is possible to completely disable
|
|
email sending, or to have Bugzilla store email messages in a
|
|
file instead of sending them. However, this is mainly intended
|
|
for testing, as disabling or diverting email on a production
|
|
machine would mean that users could miss important events (such
|
|
as bug changes or the creation of new accounts).
|
|
</para>
|
|
|
|
<para>
|
|
For more information, see the <quote>mail_delivery_method</quote> parameter
|
|
in <xref linkend="parameters" />.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will
|
|
suffice. Sendmail, Postfix, qmail and Exim are examples of common
|
|
MTAs. Sendmail is the original Unix MTA, but the others are easier to
|
|
configure, and therefore many people replace Sendmail with Postfix or
|
|
Exim. They are drop-in replacements, so Bugzilla will not
|
|
distinguish between them.
|
|
</para>
|
|
|
|
<para>
|
|
If you are using Sendmail, version 8.7 or higher is required.
|
|
If you are using a Sendmail-compatible MTA, it must be congruent with
|
|
at least version 8.7 of Sendmail.
|
|
</para>
|
|
|
|
<para>
|
|
Consult the manual for the specific MTA you choose for detailed
|
|
installation instructions. Each of these programs will have their own
|
|
configuration files where you must configure certain parameters to
|
|
ensure that the mail is delivered properly. They are implemented
|
|
as services, and you should ensure that the MTA is in the auto-start
|
|
list of services for the machine.
|
|
</para>
|
|
|
|
<para>
|
|
If a simple mail sent with the command-line 'mail' program
|
|
succeeds, then Bugzilla should also be fine.
|
|
</para>
|
|
|
|
</section>
|
|
<section id="using-mod_perl-with-bugzilla">
|
|
<title>Installing Bugzilla on mod_perl</title>
|
|
<para>It is now possible to run the Bugzilla software under <literal>mod_perl</literal> on
|
|
Apache. <literal>mod_perl</literal> has some additional requirements to that of running
|
|
Bugzilla under <literal>mod_cgi</literal> (the standard and previous way).</para>
|
|
|
|
<para>Bugzilla requires <literal>mod_perl</literal> to be installed, which can be
|
|
obtained from <ulink url="http://perl.apache.org"/> - Bugzilla requires
|
|
version &min-mod_perl2-ver; (AKA 2.0.0-RC5) to be installed.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="configuration">
|
|
<title>Configuration</title>
|
|
|
|
<warning>
|
|
<para>
|
|
Poorly-configured MySQL and Bugzilla installations have
|
|
given attackers full access to systems in the past. Please take the
|
|
security parts of these guidelines seriously, even for Bugzilla
|
|
machines hidden away behind your firewall. Be certain to read
|
|
<xref linkend="security"/> for some important security tips.
|
|
</para>
|
|
</warning>
|
|
|
|
<section id="localconfig">
|
|
<title>localconfig</title>
|
|
|
|
<para>
|
|
You should now run <filename>checksetup.pl</filename> again, this time
|
|
without the <literal>--check-modules</literal> switch.
|
|
</para>
|
|
<screen><prompt>bash#</prompt> ./checksetup.pl</screen>
|
|
<para>
|
|
This time, <filename>checksetup.pl</filename> should tell you that all
|
|
the correct modules are installed and will display a message about, and
|
|
write out a file called, <filename>localconfig</filename>. This file
|
|
contains the default settings for a number of Bugzilla parameters.
|
|
</para>
|
|
|
|
<para>
|
|
Load this file in your editor. The only two values you
|
|
<emphasis>need</emphasis> to change are $db_driver and $db_pass,
|
|
respectively the type of the database and the password for
|
|
the user you will create for your database. Pick a strong
|
|
password (for simplicity, it should not contain single quote
|
|
characters) and put it here. $db_driver can be either 'mysql',
|
|
'Pg' or 'oracle'.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
In Oracle, <literal>$db_name</literal> should actually be
|
|
the SID name of your database (e.g. "XE" if you are using Oracle XE).
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
You may need to change the value of
|
|
<emphasis>webservergroup</emphasis> if your web server does not
|
|
run in the "apache" group. On Debian, for example, Apache runs in
|
|
the "www-data" group. If you are going to run Bugzilla on a
|
|
machine where you do not have root access (such as on a shared web
|
|
hosting account), you will need to leave
|
|
<emphasis>webservergroup</emphasis> empty, ignoring the warnings
|
|
that <filename>checksetup.pl</filename> will subsequently display
|
|
every time it is run.
|
|
</para>
|
|
|
|
<caution>
|
|
<para>
|
|
If you are using suexec, you should use your own primary group
|
|
for <emphasis>webservergroup</emphasis> rather than leaving it
|
|
empty, and see the additional directions in the suexec section
|
|
<xref linkend="suexec" />.
|
|
</para>
|
|
</caution>
|
|
|
|
<para>
|
|
The other options in the <filename>localconfig</filename> file
|
|
are documented by their accompanying comments. If you have a slightly
|
|
non-standard database setup, you may wish to change one or more of
|
|
the other "$db_*" parameters.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="database-engine">
|
|
<title>Database Server</title>
|
|
<para>
|
|
This section deals with configuring your database server for use
|
|
with Bugzilla. Currently, MySQL (<xref linkend="mysql"/>),
|
|
PostgreSQL (<xref linkend="postgresql"/>) and Oracle (<xref linkend="oracle"/>)
|
|
are available.
|
|
</para>
|
|
|
|
<section id="database-schema">
|
|
<title>Bugzilla Database Schema</title>
|
|
|
|
<para>
|
|
The Bugzilla database schema is available at
|
|
<ulink url="http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/">Ravenbrook</ulink>.
|
|
This very valuable tool can generate a written description of
|
|
the Bugzilla database schema for any version of Bugzilla. It
|
|
can also generate a diff between two versions to help someone
|
|
see what has changed.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="mysql">
|
|
<title>MySQL</title>
|
|
|
|
<caution>
|
|
<para>
|
|
MySQL's default configuration is insecure.
|
|
We highly recommend to run <filename>mysql_secure_installation</filename>
|
|
on Linux or the MySQL installer on Windows, and follow the instructions.
|
|
Important points to note are:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Be sure that the root account has a secure password set.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Do not create an anonymous account, and if it exists, say "yes"
|
|
to remove it.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If your web server and MySQL server are on the same machine,
|
|
you should disable the network access.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</caution>
|
|
|
|
<section id="mysql-max-allowed-packet">
|
|
<title>Allow large attachments and many comments</title>
|
|
|
|
<para>By default, MySQL will only allow you to insert things
|
|
into the database that are smaller than 1MB. Attachments
|
|
may be larger than this. Also, Bugzilla combines all comments
|
|
on a single bug into one field for full-text searching, and the
|
|
combination of all comments on a single bug could in some cases
|
|
be larger than 1MB.</para>
|
|
|
|
<para>To change MySQL's default, you need to edit your MySQL
|
|
configuration file, which is usually <filename>/etc/my.cnf</filename>
|
|
on Linux. We recommend that you allow at least 4MB packets by
|
|
adding the "max_allowed_packet" parameter to your MySQL
|
|
configuration in the "[mysqld]" section, like this:</para>
|
|
|
|
<screen>[mysqld]
|
|
# Allow packets up to 4MB
|
|
max_allowed_packet=4M
|
|
</screen>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Allow small words in full-text indexes</title>
|
|
|
|
<para>By default, words must be at least four characters in length
|
|
in order to be indexed by MySQL's full-text indexes. This causes
|
|
a lot of Bugzilla specific words to be missed, including "cc",
|
|
"ftp" and "uri".</para>
|
|
|
|
<para>MySQL can be configured to index those words by setting the
|
|
ft_min_word_len param to the minimum size of the words to index.
|
|
This can be done by modifying the <filename>/etc/my.cnf</filename>
|
|
according to the example below:</para>
|
|
|
|
<screen> [mysqld]
|
|
# Allow small words in full-text indexes
|
|
ft_min_word_len=2</screen>
|
|
|
|
<para>Rebuilding the indexes can be done based on documentation found at
|
|
<ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-setupdatabase-adduser">
|
|
<title>Add a user to MySQL</title>
|
|
|
|
<para>
|
|
You need to add a new MySQL user for Bugzilla to use.
|
|
(It's not safe to have Bugzilla use the MySQL root account.)
|
|
The following instructions assume the defaults in
|
|
<filename>localconfig</filename>; if you changed those,
|
|
you need to modify the SQL command appropriately. You will
|
|
need the <replaceable>$db_pass</replaceable> password you
|
|
set in <filename>localconfig</filename> in
|
|
<xref linkend="localconfig"/>.
|
|
</para>
|
|
|
|
<para>
|
|
We use an SQL <command>GRANT</command> command to create
|
|
a <quote>bugs</quote> user. 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>
|
|
Run the <filename>mysql</filename> command-line client and enter:
|
|
</para>
|
|
|
|
<screen>
|
|
<prompt>mysql></prompt> GRANT SELECT, INSERT,
|
|
UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
|
|
CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
|
|
TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
|
|
<prompt>mysql></prompt> FLUSH PRIVILEGES;
|
|
</screen>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Permit attachments table to grow beyond 4GB</title>
|
|
|
|
<para>
|
|
By default, MySQL will limit the size of a table to 4GB.
|
|
This limit is present even if the underlying filesystem
|
|
has no such limit. To set a higher limit, follow these
|
|
instructions.
|
|
</para>
|
|
|
|
<para>
|
|
After you have completed the rest of the installation (or at least the
|
|
database setup parts), you should run the <filename>MySQL</filename>
|
|
command-line client and enter the following, replacing <literal>$bugs_db</literal>
|
|
with your Bugzilla database name (<emphasis>bugs</emphasis> by default):
|
|
</para>
|
|
|
|
<screen>
|
|
<prompt>mysql></prompt> use <replaceable>$bugs_db</replaceable>
|
|
<prompt>mysql></prompt> ALTER TABLE attachments
|
|
AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
|
|
</screen>
|
|
|
|
<para>
|
|
The above command will change the limit to 20GB. Mysql will have
|
|
to make a temporary copy of your entire table to do this. Ideally,
|
|
you should do this when your attachments table is still small.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
This does not affect Big Files, attachments that are stored directly
|
|
on disk instead of in the database.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="postgresql">
|
|
<title>PostgreSQL</title>
|
|
<section>
|
|
<title>Add a User to PostgreSQL</title>
|
|
|
|
<para>You need to add a new user to PostgreSQL for the Bugzilla
|
|
application to use when accessing the database. The following instructions
|
|
assume the defaults in <filename>localconfig</filename>; if you
|
|
changed those, you need to modify the commands appropriately. You will
|
|
need the <replaceable>$db_pass</replaceable> password you
|
|
set in <filename>localconfig</filename> in
|
|
<xref linkend="localconfig"/>.</para>
|
|
|
|
<para>On most systems, to create the user in PostgreSQL, you will need to
|
|
login as the root user, and then</para>
|
|
|
|
<screen> <prompt>bash#</prompt> su - postgres</screen>
|
|
|
|
<para>As the postgres user, you then need to create a new user: </para>
|
|
|
|
<screen> <prompt>bash$</prompt> createuser -U postgres -dRSP bugs</screen>
|
|
|
|
<para>When asked for a password, provide the password which will be set as
|
|
<replaceable>$db_pass</replaceable> in <filename>localconfig</filename>.
|
|
The created user will not be a superuser (-S) and will not be able to create
|
|
new users (-R). He will only have the ability to create databases (-d).</para>
|
|
|
|
<note>
|
|
<para>If your are running PostgreSQL 8.0, you must replace -dRSP by -dAP.</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Configure PostgreSQL</title>
|
|
|
|
<para>Now, you will need to edit <filename>pg_hba.conf</filename> which is
|
|
usually located in <filename>/var/lib/pgsql/data/</filename>. In this file,
|
|
you will need to add a new line to it as follows:</para>
|
|
|
|
<para>
|
|
<computeroutput>host all bugs 127.0.0.1 255.255.255.255 md5</computeroutput>
|
|
</para>
|
|
|
|
<para>This means that for TCP/IP (host) connections, allow connections from
|
|
'127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use
|
|
password authentication (md5) for that user.</para>
|
|
|
|
<para>Now, you will need to restart PostgreSQL, but you will need to fully
|
|
stop and start the server rather than just restarting due to the possibility
|
|
of a change to <filename>postgresql.conf</filename>. After the server has
|
|
restarted, you will need to edit <filename>localconfig</filename>, finding
|
|
the <literal>$db_driver</literal> variable and setting it to
|
|
<literal>Pg</literal> and changing the password in <literal>$db_pass</literal>
|
|
to the one you picked previously, while setting up the account.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="oracle">
|
|
<title>Oracle</title>
|
|
<section>
|
|
<title>Create a New Tablespace</title>
|
|
|
|
<para>
|
|
You can use the existing tablespace or create a new one for Bugzilla.
|
|
To create a new tablespace, run the following command:
|
|
</para>
|
|
|
|
<programlisting>
|
|
CREATE TABLESPACE bugs
|
|
DATAFILE '<replaceable>$path_to_datafile</replaceable>' SIZE 500M
|
|
AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
|
|
</programlisting>
|
|
|
|
<para>
|
|
Here, the name of the tablespace is 'bugs', but you can
|
|
choose another name. <replaceable>$path_to_datafile</replaceable> is
|
|
the path to the file containing your database, for instance
|
|
<filename>/u01/oradata/bugzilla.dbf</filename>.
|
|
The initial size of the database file is set in this example to 500 Mb,
|
|
with an increment of 30 Mb everytime we reach the size limit of the file.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Add a User to Oracle</title>
|
|
|
|
<para>
|
|
The user name and password must match what you set in
|
|
<filename>localconfig</filename> (<literal>$db_user</literal>
|
|
and <literal>$db_pass</literal>, respectively). Here, we assume that
|
|
the user name is 'bugs' and the tablespace name is the same
|
|
as above.
|
|
</para>
|
|
|
|
<programlisting>
|
|
CREATE USER bugs
|
|
IDENTIFIED BY "<replaceable>$db_pass</replaceable>"
|
|
DEFAULT TABLESPACE bugs
|
|
TEMPORARY TABLESPACE TEMP
|
|
PROFILE DEFAULT;
|
|
-- GRANT/REVOKE ROLE PRIVILEGES
|
|
GRANT CONNECT TO bugs;
|
|
GRANT RESOURCE TO bugs;
|
|
-- GRANT/REVOKE SYSTEM PRIVILEGES
|
|
GRANT UNLIMITED TABLESPACE TO bugs;
|
|
GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Configure the Web Server</title>
|
|
|
|
<para>
|
|
If you use Apache, append these lines to <filename>httpd.conf</filename>
|
|
to set ORACLE_HOME and LD_LIBRARY_PATH. For instance:
|
|
</para>
|
|
|
|
<programlisting>
|
|
SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/
|
|
SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/
|
|
</programlisting>
|
|
|
|
<para>
|
|
When this is done, restart your web server.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>checksetup.pl</title>
|
|
|
|
<para>
|
|
Next, rerun <filename>checksetup.pl</filename>. It reconfirms
|
|
that all the modules are present, and notices the altered
|
|
localconfig file, which it assumes you have edited to your
|
|
satisfaction. It compiles the UI templates,
|
|
connects to the database using the 'bugs'
|
|
user you created and the password you defined, and creates the
|
|
'bugs' database and the tables therein.
|
|
</para>
|
|
|
|
<para>
|
|
After that, it asks for details of an administrator account. Bugzilla
|
|
can have multiple administrators - you can create more later - but
|
|
it needs one to start off with.
|
|
Enter the email address of an administrator, his or her full name,
|
|
and a suitable Bugzilla password.
|
|
</para>
|
|
|
|
<para>
|
|
<filename>checksetup.pl</filename> will then finish. You may rerun
|
|
<filename>checksetup.pl</filename> at any time if you wish.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="http">
|
|
<title>Web server</title>
|
|
<para>
|
|
Configure your web server according to the instructions in the
|
|
appropriate section. (If it makes a difference in your choice,
|
|
the Bugzilla Team recommends Apache.) To check whether your web server
|
|
is correctly configured, try to access <filename>testagent.cgi</filename>
|
|
from your web server. If "OK" is displayed, then your configuration
|
|
is successful. Regardless of which web server
|
|
you are using, however, ensure that sensitive information is
|
|
not remotely available by properly applying the access controls in
|
|
<xref linkend="security-webserver-access"/>. You can run
|
|
<filename>testserver.pl</filename> to check if your web server serves
|
|
Bugzilla files as expected.
|
|
</para>
|
|
|
|
<section id="http-apache">
|
|
<title>Bugzilla using Apache</title>
|
|
<para>You have two options for running Bugzilla under Apache -
|
|
<link linkend="http-apache-mod_cgi">mod_cgi</link> (the default) and
|
|
<link linkend="http-apache-mod_perl">mod_perl</link> (new in Bugzilla
|
|
2.23)
|
|
</para>
|
|
<section id="http-apache-mod_cgi">
|
|
<title>Apache <productname>httpd</productname> with mod_cgi</title>
|
|
|
|
<para>
|
|
To configure your Apache web server to work with Bugzilla while using
|
|
mod_cgi, do the following:
|
|
</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>
|
|
Load <filename>httpd.conf</filename> in your editor.
|
|
In Fedora and Red Hat Linux, this file is found in
|
|
<filename class="directory">/etc/httpd/conf</filename>.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Apache uses <computeroutput><Directory></computeroutput>
|
|
directives to permit fine-grained permission setting. Add the
|
|
following lines to a directive that applies to the location
|
|
of your Bugzilla installation. (If such a section does not
|
|
exist, you'll want to add one.) In this example, Bugzilla has
|
|
been installed at
|
|
<filename class="directory">/var/www/html/bugzilla</filename>.
|
|
</para>
|
|
|
|
<programlisting>
|
|
<Directory /var/www/html/bugzilla>
|
|
AddHandler cgi-script .cgi
|
|
Options +Indexes +ExecCGI
|
|
DirectoryIndex index.cgi
|
|
AllowOverride Limit
|
|
</Directory>
|
|
</programlisting>
|
|
|
|
<para>
|
|
These instructions: allow apache to run .cgi files found
|
|
within the bugzilla directory; instructs the server to look
|
|
for a file called <filename>index.cgi</filename> if someone
|
|
only types the directory name into the browser; and allows
|
|
Bugzilla's <filename>.htaccess</filename> files to override
|
|
global permissions.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
It is possible to make these changes globally, or to the
|
|
directive controlling Bugzilla's parent directory (e.g.
|
|
<computeroutput><Directory /var/www/html/></computeroutput>).
|
|
Such changes would also apply to the Bugzilla directory...
|
|
but they would also apply to many other places where they
|
|
may or may not be appropriate. In most cases, including
|
|
this one, it is better to be as restrictive as possible
|
|
when granting extra access.
|
|
</para>
|
|
</note>
|
|
|
|
<note>
|
|
<para>
|
|
On Windows, you may have to also add the
|
|
<computeroutput>ScriptInterpreterSource Registry-Strict</computeroutput>
|
|
line, see <link linkend="win32-http">Windows specific notes</link>.
|
|
</para>
|
|
</note>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<filename>checksetup.pl</filename> can set tighter permissions
|
|
on Bugzilla's files and directories if it knows what group the
|
|
web server runs as. Find the <computeroutput>Group</computeroutput>
|
|
line in <filename>httpd.conf</filename>, place the value found
|
|
there in the <replaceable>$webservergroup</replaceable> variable
|
|
in <filename>localconfig</filename>, then rerun
|
|
<filename>checksetup.pl</filename>.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
Optional: If Bugzilla does not actually reside in the webspace
|
|
directory, but instead has been symbolically linked there, you
|
|
will need to add the following to the
|
|
<computeroutput>Options</computeroutput> line of the Bugzilla
|
|
<computeroutput><Directory></computeroutput> directive
|
|
(the same one as in the step above):
|
|
</para>
|
|
|
|
<programlisting>
|
|
+FollowSymLinks
|
|
</programlisting>
|
|
|
|
<para>
|
|
Without this directive, Apache will not follow symbolic links
|
|
to places outside its own directory structure, and you will be
|
|
unable to run Bugzilla.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
<section id="http-apache-mod_perl">
|
|
<title>Apache <productname>httpd</productname> with mod_perl</title>
|
|
|
|
<para>Some configuration is required to make Bugzilla work with Apache
|
|
and mod_perl</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>
|
|
Load <filename>httpd.conf</filename> in your editor.
|
|
In Fedora and Red Hat Linux, this file is found in
|
|
<filename class="directory">/etc/httpd/conf</filename>.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Add the following information to your httpd.conf file, substituting
|
|
where appropriate with your own local paths.</para>
|
|
|
|
<note>
|
|
<para>This should be used instead of the <Directory> block
|
|
shown above. This should also be above any other <literal>mod_perl</literal>
|
|
directives within the <filename>httpd.conf</filename> and must be specified
|
|
in the order as below.</para>
|
|
</note>
|
|
<warning>
|
|
<para>You should also ensure that you have disabled <literal>KeepAlive</literal>
|
|
support in your Apache install when utilizing Bugzilla under mod_perl</para>
|
|
</warning>
|
|
|
|
<programlisting>
|
|
PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T
|
|
PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
|
|
</programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<filename>checksetup.pl</filename> can set tighter permissions
|
|
on Bugzilla's files and directories if it knows what group the
|
|
web server runs as. Find the <computeroutput>Group</computeroutput>
|
|
line in <filename>httpd.conf</filename>, place the value found
|
|
there in the <replaceable>$webservergroup</replaceable> variable
|
|
in <filename>localconfig</filename>, then rerun
|
|
<filename>checksetup.pl</filename>.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>On restarting Apache, Bugzilla should now be running within the
|
|
mod_perl environment. Please ensure you have run checksetup.pl to set
|
|
permissions before you restart Apache.</para>
|
|
|
|
<note>
|
|
<para>Please bear the following points in mind when looking at using
|
|
Bugzilla under mod_perl:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be
|
|
looking at 30MB per httpd child, easily. Basically, you just need a lot of RAM.
|
|
The more RAM you can get, the better. mod_perl is basically trading RAM for
|
|
speed. At least 2GB total system RAM is recommended for running Bugzilla under
|
|
mod_perl.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Under mod_perl, you have to restart Apache if you make any manual change to
|
|
any Bugzilla file. You can't just reload--you have to actually
|
|
<emphasis>restart</emphasis> the server (as in make sure it stops and starts
|
|
again). You <emphasis>can</emphasis> change localconfig and the params file
|
|
manually, if you want, because those are re-read every time you load a page.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
You must run in Apache's Prefork MPM (this is the default). The Worker MPM
|
|
may not work--we haven't tested Bugzilla's mod_perl support under threads.
|
|
(And, in fact, we're fairly sure it <emphasis>won't</emphasis> work.)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Bugzilla generally expects to be the only mod_perl application running on
|
|
your entire server. It may or may not work if there are other applications also
|
|
running under mod_perl. It does try its best to play nice with other mod_perl
|
|
applications, but it still may have conflicts.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It is recommended that you have one Bugzilla instance running under mod_perl
|
|
on your server. Bugzilla has not been tested with more than one instance running.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</note>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="http-iis">
|
|
<title>Microsoft <productname>Internet Information Services</productname></title>
|
|
|
|
<para>
|
|
If you are running Bugzilla on Windows and choose to use
|
|
Microsoft's <productname>Internet Information Services</productname>
|
|
or <productname>Personal Web Server</productname> you will need
|
|
to perform a number of other configuration steps as explained below.
|
|
You may also want to refer to the following Microsoft Knowledge
|
|
Base articles:
|
|
<ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225">245225</ulink>
|
|
<quote>HOW TO: Configure and Test a PERL Script with IIS 4.0,
|
|
5.0, and 5.1</quote> (for <productname>Internet Information
|
|
Services</productname>) and
|
|
<ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998">231998</ulink>
|
|
<quote>HOW TO: FP2000: How to Use Perl with Microsoft Personal Web
|
|
Server on Windows 95/98</quote> (for <productname>Personal Web
|
|
Server</productname>).
|
|
</para>
|
|
|
|
<para>
|
|
You will need to create a virtual directory for the Bugzilla
|
|
install. Put the Bugzilla files in a directory that is named
|
|
something <emphasis>other</emphasis> than what you want your
|
|
end-users accessing. That is, if you want your users to access
|
|
your Bugzilla installation through
|
|
<quote>http://<yourdomainname>/Bugzilla</quote>, then do
|
|
<emphasis>not</emphasis> put your Bugzilla files in a directory
|
|
named <quote>Bugzilla</quote>. Instead, place them in a different
|
|
location, and then use the IIS Administration tool to create a
|
|
Virtual Directory named "Bugzilla" that acts as an alias for the
|
|
actual location of the files. When creating that virtual directory,
|
|
make sure you add the <quote>Execute (such as ISAPI applications or
|
|
CGI)</quote> access permission.
|
|
</para>
|
|
|
|
<para>
|
|
You will also need to tell IIS how to handle Bugzilla's
|
|
.cgi files. Using the IIS Administration tool again, open up
|
|
the properties for the new virtual directory and select the
|
|
Configuration option to access the Script Mappings. Create an
|
|
entry mapping .cgi to:
|
|
</para>
|
|
|
|
<programlisting>
|
|
<full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s
|
|
</programlisting>
|
|
|
|
<para>
|
|
For example:
|
|
</para>
|
|
|
|
<programlisting>
|
|
c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
|
|
</programlisting>
|
|
|
|
<note>
|
|
<para>
|
|
The ActiveState install may have already created an entry for
|
|
.pl files that is limited to <quote>GET,HEAD,POST</quote>. If
|
|
so, this mapping should be <emphasis>removed</emphasis> as
|
|
Bugzilla's .pl files are not designed to be run via a web server.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
IIS will also need to know that the index.cgi should be treated
|
|
as a default document. On the Documents tab page of the virtual
|
|
directory properties, you need to add index.cgi as a default
|
|
document type. If you wish, you may remove the other default
|
|
document types for this particular virtual directory, since Bugzilla
|
|
doesn't use any of them.
|
|
</para>
|
|
|
|
<para>
|
|
Also, and this can't be stressed enough, make sure that files
|
|
such as <filename>localconfig</filename> and your
|
|
<filename class="directory">data</filename> directory are
|
|
secured as described in <xref linkend="security-webserver-access"/>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="install-config-bugzilla">
|
|
<title>Bugzilla</title>
|
|
|
|
<para>
|
|
Your Bugzilla should now be working. Access
|
|
<filename>http://<your-bugzilla-server>/</filename> -
|
|
you should see the Bugzilla
|
|
front page. If not, consult the Troubleshooting section,
|
|
<xref linkend="troubleshooting"/>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
The URL above may be incorrect if you installed Bugzilla into a
|
|
subdirectory or used a symbolic link from your web site root to
|
|
the Bugzilla directory.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
Log in with the administrator account you defined in the last
|
|
<filename>checksetup.pl</filename> run. You should go through
|
|
the Parameters page and see if there are any you wish to change.
|
|
They key parameters are documented in <xref linkend="parameters"/>;
|
|
you should certainly alter
|
|
<command>maintainer</command> and <command>urlbase</command>;
|
|
you may also want to alter
|
|
<command>cookiepath</command> or <command>requirelogin</command>.
|
|
</para>
|
|
|
|
<para>
|
|
Bugzilla has several optional features which require extra
|
|
configuration. You can read about those in
|
|
<xref linkend="extraconfig"/>.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="extraconfig">
|
|
<title>Optional Additional Configuration</title>
|
|
|
|
<para>
|
|
Bugzilla has a number of optional features. This section describes how
|
|
to configure or enable them.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Bug Graphs</title>
|
|
|
|
<para>If you have installed the necessary Perl modules you
|
|
can start collecting statistics for the nifty Bugzilla
|
|
graphs.</para>
|
|
|
|
<screen><prompt>bash#</prompt> <command>crontab -e</command></screen>
|
|
|
|
<para>
|
|
This should bring up the crontab file in your editor.
|
|
Add a cron entry like this to run
|
|
<filename>collectstats.pl</filename>
|
|
daily at 5 after midnight:
|
|
</para>
|
|
|
|
<programlisting>5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl</programlisting>
|
|
|
|
<para>
|
|
After two days have passed you'll be able to view bug graphs from
|
|
the Reports page.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Windows does not have 'cron', but it does have the Task
|
|
Scheduler, which performs the same duties. There are also
|
|
third-party tools that can be used to implement cron, such as
|
|
<ulink url="http://www.nncron.ru/">nncron</ulink>.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="installation-whining-cron">
|
|
<title>The Whining Cron</title>
|
|
|
|
<para>What good are
|
|
bugs if they're not annoying? To help make them more so you
|
|
can set up Bugzilla's automatic whining system to complain at engineers
|
|
which leave their bugs in the NEW or REOPENED state without triaging them.
|
|
</para>
|
|
<para>
|
|
This can be done by adding the following command as a daily
|
|
crontab entry, in the same manner as explained above for bug
|
|
graphs. This example runs it at 12.55am.
|
|
</para>
|
|
|
|
<programlisting>55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl</programlisting>
|
|
|
|
<note>
|
|
<para>
|
|
Windows does not have 'cron', but it does have the Task
|
|
Scheduler, which performs the same duties. There are also
|
|
third-party tools that can be used to implement cron, such as
|
|
<ulink url="http://www.nncron.ru/">nncron</ulink>.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="installation-whining">
|
|
<title>Whining</title>
|
|
|
|
<para>
|
|
As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy
|
|
them at regular intervals, by having Bugzilla execute saved searches
|
|
at certain times and emailing the results to the user. This is known
|
|
as "Whining". The process of configuring Whining is described
|
|
in <xref linkend="whining"/>, but for it to work a Perl script must be
|
|
executed at regular intervals.
|
|
</para>
|
|
|
|
<para>
|
|
This can be done by adding the following command as a daily
|
|
crontab entry, in the same manner as explained above for bug
|
|
graphs. This example runs it every 15 minutes.
|
|
</para>
|
|
|
|
<programlisting>*/15 * * * * cd <your-bugzilla-directory> ; ./whine.pl</programlisting>
|
|
|
|
<note>
|
|
<para>
|
|
Whines can be executed as often as every 15 minutes, so if you specify
|
|
longer intervals between executions of whine.pl, some users may not
|
|
be whined at as often as they would expect. Depending on the person,
|
|
this can either be a very Good Thing or a very Bad Thing.
|
|
</para>
|
|
</note>
|
|
|
|
<note>
|
|
<para>
|
|
Windows does not have 'cron', but it does have the Task
|
|
Scheduler, which performs the same duties. There are also
|
|
third-party tools that can be used to implement cron, such as
|
|
<ulink url="http://www.nncron.ru/">nncron</ulink>.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="apache-addtype">
|
|
<title>Serving Alternate Formats with the right MIME type</title>
|
|
|
|
<para>
|
|
Some Bugzilla pages have alternate formats, other than just plain
|
|
<acronym>HTML</acronym>. In particular, a few Bugzilla pages can
|
|
output their contents as either <acronym>XUL</acronym> (a special
|
|
Mozilla format, that looks like a program <acronym>GUI</acronym>)
|
|
or <acronym>RDF</acronym> (a type of structured <acronym>XML</acronym>
|
|
that can be read by various programs).
|
|
</para>
|
|
<para>
|
|
In order for your users to see these pages correctly, Apache must
|
|
send them with the right <acronym>MIME</acronym> type. To do this,
|
|
add the following lines to your Apache configuration, either in the
|
|
<computeroutput><VirtualHost></computeroutput> section for your
|
|
Bugzilla, or in the <computeroutput><Directory></computeroutput>
|
|
section for your Bugzilla:
|
|
</para>
|
|
<para>
|
|
<screen>AddType application/vnd.mozilla.xul+xml .xul
|
|
AddType application/rdf+xml .rdf</screen>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="multiple-bz-dbs">
|
|
<title>Multiple Bugzilla databases with a single installation</title>
|
|
|
|
<para>The previous instructions referred to a standard installation, with
|
|
one unique Bugzilla database. However, you may want to host several
|
|
distinct installations, without having several copies of the code. This is
|
|
possible by using the PROJECT environment variable. When accessed,
|
|
Bugzilla checks for the existence of this variable, and if present, uses
|
|
its value to check for an alternative configuration file named
|
|
<filename>localconfig.<PROJECT></filename> in the same location as
|
|
the default one (<filename>localconfig</filename>). It also checks for
|
|
customized templates in a directory named
|
|
<filename><PROJECT></filename> in the same location as the
|
|
default one (<filename>template/<langcode></filename>). By default
|
|
this is <filename>template/en/default</filename> so PROJECT's templates
|
|
would be located at <filename>template/en/PROJECT</filename>.</para>
|
|
|
|
<para>To set up an alternate installation, just export PROJECT=foo before
|
|
running <command>checksetup.pl</command> for the first time. It will
|
|
result in a file called <filename>localconfig.foo</filename> instead of
|
|
<filename>localconfig</filename>. Edit this file as described above, with
|
|
reference to a new database, and re-run <command>checksetup.pl</command>
|
|
to populate it. That's all.</para>
|
|
|
|
<para>Now you have to configure the web server to pass this environment
|
|
variable when accessed via an alternate URL, such as virtual host for
|
|
instance. The following is an example of how you could do it in Apache,
|
|
other Webservers may differ.
|
|
<programlisting>
|
|
<VirtualHost 212.85.153.228:80>
|
|
ServerName foo.bar.baz
|
|
SetEnv PROJECT foo
|
|
Alias /bugzilla /var/www/bugzilla
|
|
</VirtualHost>
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>Don't forget to also export this variable before accessing Bugzilla
|
|
by other means, such as cron tasks for instance.</para>
|
|
</section>
|
|
|
|
<section id="os-specific">
|
|
<title>OS-Specific Installation Notes</title>
|
|
|
|
<para>Many aspects of the Bugzilla installation can be affected by the
|
|
operating system you choose to install it on. Sometimes it can be made
|
|
easier and others more difficult. This section will attempt to help you
|
|
understand both the difficulties of running on specific operating systems
|
|
and the utilities available to make it easier.
|
|
</para>
|
|
|
|
<para>If you have anything to add or notes for an operating system not
|
|
covered, please file a bug in &bzg-bugs;.
|
|
</para>
|
|
|
|
<section id="os-win32">
|
|
<title>Microsoft Windows</title>
|
|
<para>
|
|
Making Bugzilla work on Windows is more difficult than making it
|
|
work on Unix. For that reason, we still recommend doing so on a Unix
|
|
based system such as GNU/Linux. That said, if you do want to get
|
|
Bugzilla running on Windows, you will need to make the following
|
|
adjustments. A detailed step-by-step
|
|
<ulink url="https://wiki.mozilla.org/Bugzilla:Win32Install">
|
|
installation guide for Windows</ulink> is also available
|
|
if you need more help with your installation.
|
|
</para>
|
|
|
|
<section id="win32-perl">
|
|
<title>Win32 Perl</title>
|
|
<para>
|
|
Perl for Windows can be obtained from
|
|
<ulink url="http://www.activestate.com/">ActiveState</ulink>.
|
|
You should be able to find a compiled binary at <ulink
|
|
url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/" />.
|
|
The following instructions assume that you are using version
|
|
5.8.1 of ActiveState.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
These instructions are for 32-bit versions of Windows. If you are
|
|
using a 64-bit version of Windows, you will need to install 32-bit
|
|
Perl in order to install the 32-bit modules as described below.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section id="win32-perl-modules">
|
|
<title>Perl Modules on Win32</title>
|
|
|
|
<para>
|
|
Bugzilla on Windows requires the same perl modules found in
|
|
<xref linkend="install-perlmodules"/>. The main difference is that
|
|
windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead
|
|
of CPAN. ActiveState provides a GUI to manage Perl modules. We highly
|
|
recommend that you use it. If you prefer to use ppm from the
|
|
command-line, type:
|
|
</para>
|
|
|
|
<programlisting>
|
|
C:\perl> <command>ppm install <module name></command>
|
|
</programlisting>
|
|
|
|
<para>
|
|
The best source for the Windows PPM modules needed for Bugzilla
|
|
is probably the theory58S website, which you can add to your list
|
|
of repositories as follows (for Perl 5.8.x):
|
|
</para>
|
|
|
|
<programlisting>
|
|
<command>ppm repo add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command>
|
|
</programlisting>
|
|
|
|
<para>
|
|
If you are using Perl 5.10.x, you cannot use the same PPM modules as Perl
|
|
5.8.x as they are incompatible. In this case, you should add the following
|
|
repository:
|
|
</para>
|
|
<programlisting>
|
|
<command>ppm repo add theory58S http://cpan.uwinnipeg.ca/PPMPackages/10xx/</command>
|
|
</programlisting>
|
|
|
|
<note>
|
|
<para>
|
|
In versions prior to 5.8.8 build 819 of PPM the command is
|
|
<programlisting>
|
|
<command>ppm repository add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command>
|
|
</programlisting>
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
The PPM repository stores modules in 'packages' that may have
|
|
a slightly different name than the module. If retrieving these
|
|
modules from there, you will need to pay attention to the information
|
|
provided when you run <command>checksetup.pl</command> as it will
|
|
tell you what package you'll need to install.
|
|
</para>
|
|
</note>
|
|
|
|
<tip>
|
|
<para>
|
|
If you are behind a corporate firewall, you will need to let the
|
|
ActiveState PPM utility know how to get through it to access
|
|
the repositories by setting the HTTP_proxy system environmental
|
|
variable. For more information on setting that variable, see
|
|
the ActiveState documentation.
|
|
</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="win32-http">
|
|
<title>Serving the web pages</title>
|
|
|
|
<para>
|
|
As is the case on Unix based systems, any web server should
|
|
be able to handle Bugzilla; however, the Bugzilla Team still
|
|
recommends Apache whenever asked. No matter what web server
|
|
you choose, be sure to pay attention to the security notes
|
|
in <xref linkend="security-webserver-access"/>. More
|
|
information on configuring specific web servers can be found
|
|
in <xref linkend="http"/>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
The web server looks at <filename>/usr/bin/perl</filename> to
|
|
call Perl. If you are using Apache on windows, you can set the
|
|
<ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink>
|
|
directive in your Apache config file to make it look at the
|
|
right place: insert the line
|
|
<programlisting>ScriptInterpreterSource Registry-Strict</programlisting>
|
|
into your <filename>httpd.conf</filename> file, and create the key
|
|
<programlisting>HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command</programlisting>
|
|
with <option>C:\Perl\bin\perl.exe -T</option> as value (adapt to your
|
|
path if needed) in the registry. When this is done, restart Apache.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section id="win32-email">
|
|
<title>Sending Email</title>
|
|
|
|
<para>
|
|
To enable Bugzilla to send email on Windows, the server running the
|
|
Bugzilla code must be able to connect to, or act as, an SMTP server.
|
|
</para>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id="os-macosx">
|
|
<title><productname>Mac OS X</productname></title>
|
|
|
|
<para>Making Bugzilla work on Mac OS X requires the following
|
|
adjustments.</para>
|
|
|
|
<section id="macosx-sendmail">
|
|
<title>Sendmail</title>
|
|
|
|
<para>In Mac OS X 10.3 and later,
|
|
<ulink url="http://www.postfix.org/">Postfix</ulink>
|
|
is used as the built-in email server. Postfix provides an executable
|
|
that mimics sendmail enough to fool Bugzilla, as long as Bugzilla can
|
|
find it.</para>
|
|
|
|
<para>As of version 2.20, Bugzilla will be able to find the fake
|
|
sendmail executable without any assistance. However, you will have
|
|
to turn on the sendmailnow parameter before you do anything that would
|
|
result in email being sent. For more information, see the description
|
|
of the sendmailnow parameter in <xref linkend="parameters"/>.</para>
|
|
|
|
</section>
|
|
|
|
<section id="macosx-libraries">
|
|
<title>Libraries & Perl Modules on Mac OS X</title>
|
|
|
|
<para>Apple does not include the GD library with Mac OS X. Bugzilla
|
|
needs this for bug graphs.</para>
|
|
|
|
<para>You can use DarwinPorts (<ulink url="http://darwinports.com/"/>)
|
|
or Fink (<ulink url="http://sourceforge.net/projects/fink/"/>), both
|
|
of which are similar in nature to the CPAN installer, but install
|
|
common unix programs.</para>
|
|
|
|
<para>Follow the instructions for setting up DarwinPorts or Fink.
|
|
Once you have one installed, you'll want to use it to install the
|
|
<filename>gd2</filename> package.
|
|
</para>
|
|
|
|
<para>Fink will prompt you for a number of dependencies, type 'y' and hit
|
|
enter to install all of the dependencies and then watch it work. You will
|
|
then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to
|
|
install the GD Perl module.
|
|
</para>
|
|
|
|
<note>
|
|
<para>To prevent creating conflicts with the software that Apple
|
|
installs by default, Fink creates its own directory tree at
|
|
<filename class="directory">/sw</filename> where it installs most of
|
|
the software that it installs. This means your libraries and headers
|
|
will be at <filename class="directory">/sw/lib</filename> and
|
|
<filename class="directory">/sw/include</filename> instead of
|
|
<filename class="directory">/usr/lib</filename> and
|
|
<filename class="directory">/usr/include</filename>. When the
|
|
Perl module config script asks where your <filename>libgd</filename>
|
|
is, be sure to tell it
|
|
<filename class="directory">/sw/lib</filename>.
|
|
</para>
|
|
</note>
|
|
|
|
<para>Also available via DarwinPorts and Fink is
|
|
<filename>expat</filename>. After installing the expat package, you
|
|
will be able to install XML::Parser using CPAN. If you use fink, there
|
|
is one caveat. Unlike recent versions of
|
|
the GD module, XML::Parser doesn't prompt for the location of the
|
|
required libraries. When using CPAN, you will need to use the following
|
|
command sequence:
|
|
</para>
|
|
|
|
<screen>
|
|
# perl -MCPAN -e'look XML::Parser' <co id="macosx-look"/>
|
|
# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include
|
|
# make; make test; make install <co id="macosx-make"/>
|
|
# exit <co id="macosx-exit"/>
|
|
</screen>
|
|
<calloutlist>
|
|
<callout arearefs="macosx-look macosx-exit">
|
|
<para>The look command will download the module and spawn a
|
|
new shell with the extracted files as the current working directory.
|
|
The exit command will return you to your original shell.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="macosx-make">
|
|
<para>You should watch the output from these make commands,
|
|
especially <quote>make test</quote> as errors may prevent
|
|
XML::Parser from functioning correctly with Bugzilla.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="os-linux">
|
|
<title>Linux Distributions</title>
|
|
<para>Many Linux distributions include Bugzilla and its
|
|
dependencies in their native package management systems.
|
|
Installing Bugzilla with root access on any Linux system
|
|
should be as simple as finding the Bugzilla package in the
|
|
package management application and installing it using the
|
|
normal command syntax. Several distributions also perform
|
|
the proper web server configuration automatically on installation.
|
|
</para>
|
|
<para>Please consult the documentation of your Linux
|
|
distribution for instructions on how to install packages,
|
|
or for specific instructions on installing Bugzilla with
|
|
native package management tools. There is also a
|
|
<ulink url="http://wiki.mozilla.org/Bugzilla:Linux_Distro_Installation">
|
|
Bugzilla Wiki Page</ulink> for distro-specific installation
|
|
notes.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
<section id="nonroot">
|
|
<title>UNIX (non-root) Installation Notes</title>
|
|
|
|
<section>
|
|
<title>Introduction</title>
|
|
|
|
<para>If you are running a *NIX OS as non-root, either due
|
|
to lack of access (web hosts, for example) or for security
|
|
reasons, this will detail how to install Bugzilla on such
|
|
a setup. It is recommended that you read through the
|
|
<xref linkend="installation" />
|
|
first to get an idea on the installation steps required.
|
|
(These notes will reference to steps in that guide.)</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>MySQL</title>
|
|
|
|
<para>You may have MySQL installed as root. If you're
|
|
setting up an account with a web host, a MySQL account
|
|
needs to be set up for you. From there, you can create
|
|
the bugs account, or use the account given to you.</para>
|
|
|
|
<warning>
|
|
<para>You may have problems trying to set up
|
|
<command>GRANT</command> permissions to the database.
|
|
If you're using a web host, chances are that you have a
|
|
separate database which is already locked down (or one big
|
|
database with limited/no access to the other areas), but you
|
|
may want to ask your system administrator what the security
|
|
settings are set to, and/or run the <command>GRANT</command>
|
|
command for you.</para>
|
|
|
|
<para>Also, you will probably not be able to change the MySQL
|
|
root user password (for obvious reasons), so skip that
|
|
step.</para>
|
|
</warning>
|
|
|
|
<section>
|
|
<title>Running MySQL as Non-Root</title>
|
|
<section>
|
|
<title>The Custom Configuration Method</title>
|
|
<para>Create a file .my.cnf in your
|
|
home directory (using /home/foo in this example)
|
|
as follows....</para>
|
|
<programlisting>
|
|
[mysqld]
|
|
datadir=/home/foo/mymysql
|
|
socket=/home/foo/mymysql/thesock
|
|
port=8081
|
|
|
|
[mysql]
|
|
socket=/home/foo/mymysql/thesock
|
|
port=8081
|
|
|
|
[mysql.server]
|
|
user=mysql
|
|
basedir=/var/lib
|
|
|
|
[safe_mysqld]
|
|
err-log=/home/foo/mymysql/the.log
|
|
pid-file=/home/foo/mymysql/the.pid
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>The Custom Built Method</title>
|
|
|
|
<para>You can install MySQL as a not-root, if you really need to.
|
|
Build it with PREFIX set to <filename class="directory">/home/foo/mysql</filename>,
|
|
or use pre-installed executables, specifying that you want
|
|
to put all of the data files in <filename class="directory">/home/foo/mysql/data</filename>.
|
|
If there is another MySQL server running on the system that you
|
|
do not own, use the -P option to specify a TCP port that is not
|
|
in use.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Starting the Server</title>
|
|
<para>After your mysqld program is built and any .my.cnf file is
|
|
in place, you must initialize the databases (ONCE).</para>
|
|
<screen>
|
|
<prompt>bash$</prompt>
|
|
<command>mysql_install_db</command>
|
|
</screen>
|
|
<para>Then start the daemon with</para>
|
|
<screen>
|
|
<prompt>bash$</prompt>
|
|
<command>safe_mysql &</command>
|
|
</screen>
|
|
<para>After you start mysqld the first time, you then connect to
|
|
it as "root" and <command>GRANT</command> permissions to other
|
|
users. (Again, the MySQL root account has nothing to do with
|
|
the *NIX root account.)</para>
|
|
|
|
<note>
|
|
<para>You will need to start the daemons yourself. You can either
|
|
ask your system administrator to add them to system startup files, or
|
|
add a crontab entry that runs a script to check on these daemons
|
|
and restart them if needed.</para>
|
|
</note>
|
|
|
|
<warning>
|
|
<para>Do NOT run daemons or other services on a server without first
|
|
consulting your system administrator! Daemons use up system resources
|
|
and running one may be in violation of your terms of service for any
|
|
machine on which you are a user!</para>
|
|
</warning>
|
|
</section>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Perl</title>
|
|
|
|
<para>
|
|
On the extremely rare chance that you don't have Perl on
|
|
the machine, you will have to build the sources
|
|
yourself. The following commands should get your system
|
|
installed with your own personal version of Perl:
|
|
</para>
|
|
|
|
<screen>
|
|
<prompt>bash$</prompt>
|
|
<command>wget http://perl.org/CPAN/src/stable.tar.gz</command>
|
|
<prompt>bash$</prompt>
|
|
<command>tar zvxf stable.tar.gz</command>
|
|
<prompt>bash$</prompt>
|
|
<command>cd perl-5.8.1</command> (or whatever the version of Perl is called)
|
|
<prompt>bash$</prompt>
|
|
<command>sh Configure -de -Dprefix=/home/foo/perl</command>
|
|
<prompt>bash$</prompt>
|
|
<command>make && make test && make install</command>
|
|
</screen>
|
|
|
|
<para>
|
|
Once you have Perl installed into a directory (probably
|
|
in <filename class="directory">~/perl/bin</filename>), you will need to
|
|
install the Perl Modules, described below.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-perlmodules-nonroot">
|
|
<title>Perl Modules</title>
|
|
|
|
<para>
|
|
Installing the Perl modules as a non-root user is accomplished by
|
|
running the <filename>install-module.pl</filename>
|
|
script. For more details on this script, see
|
|
<ulink url="api/install-module.html"><filename>install-module.pl</filename>
|
|
documentation</ulink>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>HTTP Server</title>
|
|
|
|
<para>Ideally, this also needs to be installed as root and
|
|
run under a special web server account. As long as
|
|
the web server will allow the running of *.cgi files outside of a
|
|
cgi-bin, and a way of denying web access to certain files (such as a
|
|
.htaccess file), you should be good in this department.</para>
|
|
|
|
<section>
|
|
<title>Running Apache as Non-Root</title>
|
|
|
|
<para>You can run Apache as a non-root user, but the port will need
|
|
to be set to one above 1024. If you type <command>httpd -V</command>,
|
|
you will get a list of the variables that your system copy of httpd
|
|
uses. One of those, namely HTTPD_ROOT, tells you where that
|
|
installation looks for its config information.</para>
|
|
|
|
<para>From there, you can copy the config files to your own home
|
|
directory to start editing. When you edit those and then use the -d
|
|
option to override the HTTPD_ROOT compiled into the web server, you
|
|
get control of your own customized web server.</para>
|
|
|
|
<note>
|
|
<para>You will need to start the daemons yourself. You can either
|
|
ask your system administrator to add them to system startup files, or
|
|
add a crontab entry that runs a script to check on these daemons
|
|
and restart them if needed.</para>
|
|
</note>
|
|
|
|
<warning>
|
|
<para>Do NOT run daemons or other services on a server without first
|
|
consulting your system administrator! Daemons use up system resources
|
|
and running one may be in violation of your terms of service for any
|
|
machine on which you are a user!</para>
|
|
</warning>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Bugzilla</title>
|
|
|
|
<para>
|
|
When you run <command>./checksetup.pl</command> to create
|
|
the <filename>localconfig</filename> file, it will list the Perl
|
|
modules it finds. If one is missing, go back and double-check the
|
|
module installation from <xref linkend="install-perlmodules-nonroot"/>,
|
|
then delete the <filename>localconfig</filename> file and try again.
|
|
</para>
|
|
|
|
<warning>
|
|
<para>One option in <filename>localconfig</filename> you
|
|
might have problems with is the web server group. If you can't
|
|
successfully browse to the <filename>index.cgi</filename> (like
|
|
a Forbidden error), you may have to relax your permissions,
|
|
and blank out the web server group. Of course, this may pose
|
|
as a security risk. Having a properly jailed shell and/or
|
|
limited access to shell accounts may lessen the security risk,
|
|
but use at your own risk.</para>
|
|
</warning>
|
|
|
|
<section id="suexec">
|
|
<title>suexec or shared hosting</title>
|
|
|
|
<para>If you are running on a system that uses suexec (most shared
|
|
hosting environments do this), you will need to set the
|
|
<emphasis>webservergroup</emphasis> value in <filename>localconfig</filename>
|
|
to match <emphasis>your</emphasis> primary group, rather than the one
|
|
the web server runs under. You will need to run the following
|
|
shell commands after running <command>./checksetup.pl</command>,
|
|
every time you run it (or modify <filename>checksetup.pl</filename>
|
|
to do them for you via the system() command).
|
|
<programlisting> for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done
|
|
for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done
|
|
find . -name .htaccess -exec chmod o+r {} \;
|
|
chmod o+x . data data/webdot</programlisting>
|
|
Pay particular attention to the number of semicolons and dots.
|
|
They are all important. A future version of Bugzilla will
|
|
hopefully be able to do this for you out of the box.</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
<section id="upgrade">
|
|
<title>Upgrading to New Releases</title>
|
|
|
|
<para>Upgrading to new Bugzilla releases is very simple. There is
|
|
a script included with Bugzilla that will automatically
|
|
do all of the database migration for you.</para>
|
|
|
|
<para>The following sections explain how to upgrade from one
|
|
version of Bugzilla to another. Whether you are upgrading
|
|
from one bug-fix version to another (such as 3.0.1 to 3.0.2)
|
|
or from one major version to another (such as from 3.0 to 3.2),
|
|
the instructions are always the same.</para>
|
|
|
|
<note>
|
|
<para>
|
|
Any examples in the following sections are written as though the
|
|
user were updating to version 2.22.1, but the procedures are the
|
|
same no matter what version you're updating to. Also, in the
|
|
examples, the user's Bugzilla installation is found at
|
|
<filename>/var/www/html/bugzilla</filename>. If that is not the
|
|
same as the location of your Bugzilla installation, simply
|
|
substitute the proper paths where appropriate.
|
|
</para>
|
|
</note>
|
|
|
|
<section id="upgrade-before">
|
|
<title>Before You Upgrade</title>
|
|
|
|
<para>Before you start your upgrade, there are a few important
|
|
steps to take:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Read the <ulink url="http://www.bugzilla.org/releases/">Release
|
|
Notes</ulink> of the version you're upgrading to,
|
|
particularly the "Notes for Upgraders" section.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
View the Sanity Check (<xref linkend="sanitycheck"/>) page
|
|
on your installation before upgrading. Attempt to fix all warnings
|
|
that the page produces before you go any further, or you may
|
|
experience problems during your upgrade.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Shut down your Bugzilla installation by putting some HTML or
|
|
text in the shutdownhtml parameter
|
|
(see <xref linkend="parameters"/>).
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Make a backup of the Bugzilla database.
|
|
<emphasis>THIS IS VERY IMPORTANT</emphasis>. If
|
|
anything goes wrong during the upgrade, your installation
|
|
can be corrupted beyond recovery. Having a backup keeps you safe.
|
|
</para>
|
|
|
|
<warning>
|
|
<para>
|
|
Upgrading is a one-way process. You cannot "downgrade" an
|
|
upgraded Bugzilla. If you wish to revert to the old Bugzilla
|
|
version for any reason, you will have to restore your database
|
|
from this backup.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>Here are some sample commands you could use to backup
|
|
your database, depending on what database system you're
|
|
using. You may have to modify these commands for your
|
|
particular setup.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>MySQL:</term>
|
|
<listitem>
|
|
<para>
|
|
<command>mysqldump --opt -u bugs -p bugs > bugs.sql</command>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>PostgreSQL:</term>
|
|
<listitem>
|
|
<para>
|
|
<command>pg_dump --no-privileges --no-owner -h localhost -U bugs
|
|
> bugs.sql</command>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="upgrade-files">
|
|
<title>Getting The New Bugzilla</title>
|
|
|
|
<para>There are three ways to get the new version of Bugzilla.
|
|
We'll list them here briefly and then explain them
|
|
more later.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>CVS (<xref linkend="upgrade-cvs"/>)</term>
|
|
<listitem>
|
|
<para>
|
|
If have <command>cvs</command> installed on your machine
|
|
and you have Internet access, this is the easiest way to
|
|
upgrade, particularly if you have made modifications
|
|
to the code or templates of Bugzilla.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Download the tarball (<xref linkend="upgrade-tarball"/>)</term>
|
|
<listitem>
|
|
<para>
|
|
This is a very simple way to upgrade, and good if you
|
|
haven't made many (or any) modifications to the code or
|
|
templates of your Bugzilla.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Patches (<xref linkend="upgrade-patches"/>)</term>
|
|
<listitem>
|
|
<para>
|
|
If you have made modifications to your Bugzilla, and
|
|
you don't have Internet access or you don't want to use
|
|
cvs, then this is the best way to upgrade.
|
|
</para>
|
|
|
|
<para>
|
|
You can only do minor upgrades (such as 3.0 to 3.0.1 or
|
|
3.0.1 to 3.0.2) with patches.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<section id="upgrade-modified">
|
|
<title>If you have modified your Bugzilla</title>
|
|
|
|
<para>
|
|
If you have modified the code or templates of your Bugzilla,
|
|
then upgrading requires a bit more thought and effort.
|
|
A discussion of the various methods of updating compared with
|
|
degree and methods of local customization can be found in
|
|
<xref linkend="template-method"/>.
|
|
</para>
|
|
|
|
<para>
|
|
The larger the jump you are trying to make, the more difficult it
|
|
is going to be to upgrade if you have made local customizations.
|
|
Upgrading from 3.0 to 3.0.1 should be fairly painless even if
|
|
you are heavily customized, but going from 2.18 to 3.0 is going
|
|
to mean a fair bit of work re-writing your local changes to use
|
|
the new files, logic, templates, etc. If you have done no local
|
|
changes at all, however, then upgrading should be approximately
|
|
the same amount of work regardless of how long it has been since
|
|
your version was released.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="upgrade-cvs">
|
|
<title>Upgrading using CVS</title>
|
|
|
|
<para>
|
|
This requires that you have cvs installed (most Unix machines do),
|
|
and requires that you are able to access cvs-mirror.mozilla.org
|
|
on port 2401, which may not be an option if you are behind a
|
|
highly restrictive firewall or don't have Internet access.
|
|
</para>
|
|
|
|
<para>
|
|
The following shows the sequence of commands needed to update a
|
|
Bugzilla installation via CVS, and a typical series of results.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html/bugzilla</command>
|
|
bash$ <command>cvs login</command>
|
|
Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot
|
|
CVS password: <emphasis>('anonymous', or just leave it blank)</emphasis>
|
|
bash$ <command>cvs -q update -r BUGZILLA-2_22_1 -dP</command>
|
|
P checksetup.pl
|
|
P collectstats.pl
|
|
P docs/rel_notes.txt
|
|
P template/en/default/list/quips.html.tmpl
|
|
<emphasis>(etc.)</emphasis>
|
|
</programlisting>
|
|
|
|
<caution>
|
|
<para>
|
|
If a line in the output from <command>cvs update</command> begins
|
|
with a <computeroutput>C</computeroutput>, then that represents a
|
|
file with local changes that CVS was unable to properly merge. You
|
|
need to resolve these conflicts manually before Bugzilla (or at
|
|
least the portion using that file) will be usable.
|
|
</para>
|
|
</caution>
|
|
</section>
|
|
|
|
<section id="upgrade-tarball">
|
|
<title>Upgrading using the tarball</title>
|
|
|
|
<para>
|
|
If you are unable (or unwilling) to use CVS, another option that's
|
|
always available is to obtain the latest tarball from the <ulink
|
|
url="http://www.bugzilla.org/download/">Download Page</ulink> and
|
|
create a new Bugzilla installation from that.
|
|
</para>
|
|
|
|
<para>
|
|
This sequence of commands shows how to get the tarball from the
|
|
command-line; it is also possible to download it from the site
|
|
directly in a web browser. If you go that route, save the file
|
|
to the <filename class="directory">/var/www/html</filename>
|
|
directory (or its equivalent, if you use something else) and
|
|
omit the first three lines of the example.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html</command>
|
|
bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz</command>
|
|
<emphasis>(Output omitted)</emphasis>
|
|
bash$ <command>tar xzvf bugzilla-2.22.1.tar.gz</command>
|
|
bugzilla-2.22.1/
|
|
bugzilla-2.22.1/.cvsignore
|
|
<emphasis>(Output truncated)</emphasis>
|
|
bash$ <command>cd bugzilla-2.22.1</command>
|
|
bash$ <command>cp ../bugzilla/localconfig* .</command>
|
|
bash$ <command>cp -r ../bugzilla/data .</command>
|
|
bash$ <command>cd ..</command>
|
|
bash$ <command>mv bugzilla bugzilla.old</command>
|
|
bash$ <command>mv bugzilla-2.22.1 bugzilla</command>
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>
|
|
The <command>cp</command> commands both end with periods which
|
|
is a very important detail--it means that the destination
|
|
directory is the current working directory.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
This upgrade method will give you a clean install of Bugzilla.
|
|
That's fine if you don't have any local customizations that you
|
|
want to maintain. If you do have customizations, then you will
|
|
need to reapply them by hand to the appropriate files.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="upgrade-patches">
|
|
<title>Upgrading using patches</title>
|
|
|
|
<para>
|
|
A patch is a collection of all the bug fixes that have been made
|
|
since the last bug-fix release.
|
|
</para>
|
|
|
|
<para>
|
|
If you are doing a bug-fix upgrade—that is, one where only the
|
|
last number of the revision changes, such as from 2.22 to
|
|
2.22.1—then you have the option of obtaining and applying a
|
|
patch file from the <ulink
|
|
url="http://www.bugzilla.org/download/">Download Page</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
As above, this example starts with obtaining the file via the
|
|
command line. If you have already downloaded it, you can omit the
|
|
first two commands.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html/bugzilla</command>
|
|
bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz</command>
|
|
<emphasis>(Output omitted)</emphasis>
|
|
bash$ <command>gunzip bugzilla-2.22-to-2.22.1.diff.gz</command>
|
|
bash$ <command>patch -p1 < bugzilla-2.22-to-2.22.1.diff</command>
|
|
patching file checksetup.pl
|
|
patching file collectstats.pl
|
|
<emphasis>(etc.)</emphasis>
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>
|
|
Be aware that upgrading from a patch file does not change the
|
|
entries in your <filename class="directory">CVS</filename> directory.
|
|
This could make it more difficult to upgrade using CVS
|
|
(<xref linkend="upgrade-cvs"/>) in the future.
|
|
</para>
|
|
</warning>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id="upgrade-completion">
|
|
<title>Completing Your Upgrade</title>
|
|
|
|
<para>
|
|
Now that you have the new Bugzilla code, there are a few final
|
|
steps to complete your upgrade.
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
If your new Bugzilla installation is in a different
|
|
directory or on a different machine than your old Bugzilla
|
|
installation, make sure that you have copied the
|
|
<filename>data</filename> directory and the
|
|
<filename>localconfig</filename> file from your old Bugzilla
|
|
installation. (If you followed the tarball instructions
|
|
above, this has already happened.)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If this is a major update, check that the configuration
|
|
(<xref linkend="configuration"/>) for your new Bugzilla is
|
|
up-to-date. Sometimes the configuration requirements change
|
|
between major versions.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If you didn't do it as part of the above configuration step,
|
|
now you need to run <command>checksetup.pl</command>, which
|
|
will do everything required to convert your existing database
|
|
and settings for the new version:
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html/bugzilla</command>
|
|
bash$ <command>./checksetup.pl</command>
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>
|
|
The period at the beginning of the command
|
|
<command>./checksetup.pl</command> is important and can not
|
|
be omitted.
|
|
</para>
|
|
</warning>
|
|
|
|
<caution>
|
|
<para>
|
|
If this is a major upgrade (say, 2.22 to 3.0 or similar),
|
|
running <command>checksetup.pl</command> on a large
|
|
installation (75,000 or more bugs) can take a long time,
|
|
possibly several hours.
|
|
</para>
|
|
</caution>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Clear any HTML or text that you put into the shutdownhtml
|
|
parameter, to re-activate Bugzilla.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
View the Sanity Check (<xref linkend="sanitycheck"/>) page in your
|
|
upgraded Bugzilla.
|
|
</para>
|
|
<para>
|
|
It is recommended that, if possible, you fix any problems
|
|
you see, immediately. Failure to do this may mean that Bugzilla
|
|
will not work correctly. Be aware that if the sanity check page
|
|
contains more errors after an upgrade, it doesn't necessarily
|
|
mean there are more errors in your database than there were
|
|
before, as additional tests are added to the sanity check over
|
|
time, and it is possible that those errors weren't being
|
|
checked for in the old version.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section id="upgrade-notifications">
|
|
<title>Automatic Notifications of New Releases</title>
|
|
|
|
<para>
|
|
Bugzilla 3.0 introduced the ability to automatically notify
|
|
administrators when new releases are available, based on the
|
|
<literal>upgrade_notification</literal> parameter, see
|
|
<xref linkend="parameters"/>. Administrators will see these
|
|
notifications when they access the <filename>index.cgi</filename>
|
|
page, i.e. generally when logging in. Bugzilla will check once per
|
|
day for new releases, unless the parameter is set to
|
|
<quote>disabled</quote>. If you are behind a proxy, you may have to set
|
|
the <literal>proxy_url</literal> parameter accordingly. If the proxy
|
|
requires authentication, use the
|
|
<literal>http://user:pass@proxy_url/</literal> syntax.
|
|
</para>
|
|
</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:
|
|
-->
|