c49182db0e
patch by mkanat r=justdave, a=justdave git-svn-id: svn://10.0.0.236/trunk@154295 18797224-902f-48f8-a5cc-f745e15eee43
2201 lines
82 KiB
XML
2201 lines
82 KiB
XML
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
|
|
<!-- $Id: installation.xml,v 1.70 2004-03-26 05:17:56 bugreport%peshkin.net Exp $ -->
|
|
<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 over the web.
|
|
</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>
|
|
As an alternative to following these instructions, you may wish to
|
|
try Arne Schirmacher's unofficial and unsupported
|
|
<ulink url="http://www.softwaretesting.de/article/view/33/1/8/">Bugzilla
|
|
Installer</ulink>, which installs Bugzilla and all its prerequisites
|
|
on Linux or Solaris systems.
|
|
</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-mysql">Install MySQL</link>
|
|
(&min-mysql-ver; or above)
|
|
</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>Configure all of the above.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<section id="install-perl">
|
|
<title>Perl</title>
|
|
|
|
<para>Installed Version Test: <filename>perl -v</filename></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.com"/>.
|
|
Although Bugzilla runs with Perl &min-perl-ver;,
|
|
it's a good idea to be using the latest stable version.
|
|
As of this writing, that is Perl &newest-perl-ver;.</para>
|
|
</section>
|
|
|
|
<section id="install-mysql">
|
|
<title>MySQL</title>
|
|
|
|
<para>Installed Version Test: <filename>mysql -V</filename></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, .dep, .exe, or .msi) make sure the MySQL server
|
|
is started when the machine boots.
|
|
</para>
|
|
|
|
</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 webserver,
|
|
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>
|
|
Download a Bugzilla tarball (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 main web space for your
|
|
web server or perhaps in
|
|
<filename>/usr/local</filename>
|
|
with a symbolic link from the web space.
|
|
</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 webserver'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,
|
|
<emphasis>do not run it again</emphasis>,
|
|
but 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. Then run:
|
|
</para>
|
|
|
|
<screen><prompt>bash#</prompt> ./checksetup.pl</screen>
|
|
|
|
<!-- We really need a "module-check" switch for checksetup,
|
|
which we can use here to make it really clear when they've got
|
|
all the modules. -->
|
|
|
|
|
|
<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>
|
|
There is a meta-module called Bundle::Bugzilla,
|
|
which installs all the other
|
|
modules with a single command. You should use this if you are running
|
|
Perl 5.6.1 or above.
|
|
</para>
|
|
|
|
<para>
|
|
The preferred way of installing Perl modules is via CPAN on Unix,
|
|
or PPM on Windows (see <xref linkend="win32-perlmodules"/>). These
|
|
instructions assume you are using CPAN; if for some reason you need
|
|
to install the Perl modules manually, see
|
|
<xref linkend="install-perlmodules-manual"/>.
|
|
</para>
|
|
|
|
<screen><prompt>bash#</prompt> perl -MCPAN -e 'install "<modulename>"'</screen>
|
|
|
|
<para>
|
|
If you using Bundle::Bugzilla, invoke the magic CPAN command on it.
|
|
Otherwise, you need to work down the
|
|
list of modules that <filename>checksetup.pl</filename> says are
|
|
required, in the order given, invoking the command on each.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>Many people complain that Perl modules will not install for
|
|
them. Most times, the error messages complain that they are missing a
|
|
file in
|
|
<quote>@INC</quote>.
|
|
Virtually every time, this error is due to permissions being set too
|
|
restrictively for you to compile Perl modules or not having the
|
|
necessary Perl development libraries installed on your system.
|
|
Consult your local UNIX systems administrator for help solving these
|
|
permissions issues; if you
|
|
<emphasis>are</emphasis>
|
|
the local UNIX sysadmin, please consult the newsgroup/mailing list
|
|
for further assistance or hire someone to help you out.</para>
|
|
</tip>
|
|
|
|
<para>
|
|
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>
|
|
AppConfig (&min-appconfig-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
CGI (&min-cgi-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Data::Dumper (&min-data-dumper-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Date::Format (&min-date-format-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
DBI (&min-dbi-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-dbd-mysql">DBD::mysql</link>
|
|
(&min-dbd-mysql-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
File::Spec (&min-file-spec-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
File::Temp (&min-file-temp-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-template">Template</link>
|
|
(&min-template-ver;)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Text::Wrap (&min-text-wrap-ver;)
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
Optional Perl modules:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-gd">GD</link>
|
|
(&min-gd-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-chart-base">Chart::Base</link>
|
|
(&min-chart-base-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-gd-graph">GD::Graph</link>
|
|
(&min-gd-graph-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-gd-text-align">GD::Text::Align</link>
|
|
(&min-gd-text-align-ver;) for bug charting
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-xml-parser">XML::Parser</link>
|
|
(&min-xml-parser-ver;) for the XML interface
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-patchreader">PatchReader</link>
|
|
(&min-patchreader-ver;) for pretty HTML view of patches
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<link linkend="install-modules-mime-parser">MIME::Parser</link>
|
|
(&min-mime-parser-ver;) for the optional email interface
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<section id="install-modules-dbd-mysql">
|
|
<title>DBD::mysql</title>
|
|
|
|
<para>The installation process will ask you a few questions about the
|
|
desired compilation target and your MySQL installation. For most of the
|
|
questions the provided default will be adequate, but when asked if your
|
|
desired target is the MySQL or mSQL packages, you should
|
|
select the MySQL-related ones. Later you will be asked if you wish to
|
|
provide backwards compatibility with the older MySQL packages; you
|
|
should answer YES to this question. The default is NO.</para>
|
|
|
|
<para>A host of 'localhost' should be fine. A testing user of 'test',
|
|
with a null password, should have sufficient access to run
|
|
tests on the 'test' database which MySQL creates upon installation.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-modules-template">
|
|
<title>Template Toolkit (&min-template-ver;)</title>
|
|
|
|
<para>When you install Template Toolkit, you'll get asked various
|
|
questions about features to enable. The defaults are fine, except
|
|
that it is recommended you use the high speed XS Stash of the Template
|
|
Toolkit, in order to achieve best performance.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-modules-gd">
|
|
<title>GD (&min-gd-ver;)</title>
|
|
|
|
<para>The GD module is only required if you want graphical reports.
|
|
</para>
|
|
|
|
<note>
|
|
<para>The Perl GD module 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 module README.
|
|
If compiling GD fails, it's probably because you're
|
|
missing a required library.</para>
|
|
</note>
|
|
|
|
<tip>
|
|
<para>The version of the GD module you need is very closely tied
|
|
to the <classname>libgd</classname> version installed on your system.
|
|
If you have a version 1.x of <classname>libgd</classname> the 2.x
|
|
versions of the GD module won't work for you.
|
|
</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="install-modules-chart-base">
|
|
<title>Chart::Base (&min-chart-base-ver;)</title>
|
|
|
|
<para>The Chart::Base module is only required if you want graphical
|
|
reports.
|
|
Note that earlier versions that 0.99c used GIFs, which are no longer
|
|
supported by the latest versions of GD.</para>
|
|
</section>
|
|
|
|
<section id="install-modules-gd-graph">
|
|
<title>GD::Graph (&min-gd-graph-ver;)</title>
|
|
|
|
<para>The GD::Graph module is only required if you want graphical
|
|
reports.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-modules-gd-text-align">
|
|
<title>GD::Text::Align (&min-gd-text-align-ver;)</title>
|
|
|
|
<para>The GD::Text::Align module is only required if you want graphical
|
|
reports.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-modules-xml-parser">
|
|
<title>XML::Parser (&min-xml-parser-ver;)</title>
|
|
|
|
<para>The XML::Parser module is only required if you want to import
|
|
XML bugs using the <filename>importxml.pl</filename>
|
|
script. This is required to use Bugzilla's "move bugs" feature;
|
|
you may also want to use it for migrating from another bug database.
|
|
XML::Parser requires that the
|
|
<classname>expat</classname> library is already installed on your machine.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-modules-mime-parser">
|
|
<title>MIME::Parser (&min-mime-parser-ver;)</title>
|
|
|
|
<para>The MIME::Parser module is only required if you want to use the
|
|
email interface
|
|
located in the <filename class="directory">contrib</filename> directory.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="install-modules-patchreader">
|
|
<title>PatchReader (&min-patchreader-ver;)</title>
|
|
|
|
<para>The PatchReader module is only required if you want to use
|
|
Patch Viewer, a
|
|
Bugzilla feature to show code patches in your web browser in a more
|
|
readable form.
|
|
</para>
|
|
</section>
|
|
</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.</para>
|
|
</warning>
|
|
|
|
<section id="localconfig">
|
|
<title>localconfig</title>
|
|
|
|
<para>
|
|
Once you run <filename>checksetup.pl</filename> with all the correct
|
|
modules installed, it displays 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 value you
|
|
<emphasis>need</emphasis> to change is $db_pass, 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.
|
|
</para>
|
|
|
|
<para>
|
|
The other options in the <filename>localconfig</filename> file
|
|
are documented by their accompanying comments. If you have a slightly
|
|
non-standard MySQL setup, you may wish to change one or more of
|
|
the other "$db_*" parameters.
|
|
</para>
|
|
|
|
<para>
|
|
You may also wish to change the names of
|
|
the priorities, severities, operating systems and platforms for your
|
|
installation. However, you can always change these after installation
|
|
has finished; if you then re-run
|
|
<filename>checksetup.pl</filename>, the changes will get picked up.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="mysql">
|
|
<title>MySQL</title>
|
|
|
|
<section id="security-mysql">
|
|
<title>Security</title>
|
|
|
|
<para>MySQL ships as insecure by default.
|
|
It allows anybody to on the local machine full administrative
|
|
capabilities without requiring a password; the special
|
|
MySQL root account (note: this is <emphasis>not</emphasis> the same as
|
|
the system root) also has no password.
|
|
Also, many installations default to running
|
|
<application>mysqld</application> as the system root.
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>To disable the anonymous user account
|
|
and set a password for the root user, execute the following. The
|
|
root user password should be different to the bugs user password
|
|
you set in
|
|
<filename>localconfig</filename> in the previous section,
|
|
and also different to
|
|
the password for the system root account on your machine.
|
|
</para>
|
|
<screen> <prompt>bash$</prompt> mysql mysql
|
|
<prompt>mysql></prompt> DELETE FROM user WHERE user = '';
|
|
<prompt>mysql></prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
|
|
<prompt>mysql></prompt> FLUSH PRIVILEGES;</screen>
|
|
|
|
<para>From this point forward, to run the
|
|
<filename>mysql</filename> command-line client,
|
|
you will need to type
|
|
<command>mysql -u root -p</command> and enter
|
|
<replaceable>new_password</replaceable> when prompted.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you run MySQL on the same machine as your web server, you
|
|
should disable remote access to MySQL by adding
|
|
the following to your <filename>/etc/my.cnf</filename>:
|
|
</para>
|
|
<programlisting> [myslqd]
|
|
# Prevent network access to MySQL.
|
|
skip-networking</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Consult the documentation that came with your system for
|
|
information on making <application>mysqld</application> run as an
|
|
unprivileged user.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>For added security, you could also run MySQL, or even all
|
|
of Bugzilla
|
|
in a chroot jail; however, instructions for doing that are beyond
|
|
the scope of this document.
|
|
</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section id="install-setupdatabase">
|
|
<title>Allow large attachments</title>
|
|
|
|
<para>You need to configure MySQL to accept large packets, if you
|
|
want to have attachments larger than 64K. Add the text
|
|
below to your
|
|
<filename>/etc/my.cnf</filename>.
|
|
There is also a parameter in Bugzilla
|
|
for setting the maximum allowable attachment size, (default 1MB).
|
|
Bugzilla will only accept attachments up to the lower of these two
|
|
sizes.
|
|
</para>
|
|
|
|
<screen> [mysqld]
|
|
# Allow packets up to 1M
|
|
set-variable = max_allowed_packet=1M</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>
|
|
<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 or if you are using RAID. To set a higher
|
|
limit, follow these instructions.</para>
|
|
<para>Run the <filename>MySQL</filename> command-line client and
|
|
enter:</para>
|
|
|
|
<screen> <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>
|
|
</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,
|
|
DROP,REFERENCES ON bugs.* TO bugs@localhost
|
|
IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
|
|
<prompt>mysql></prompt> FLUSH PRIVILEGES;</screen>
|
|
|
|
<note>
|
|
<para>If you are using MySQL 4, you need to add
|
|
the <computeroutput>LOCK TABLES</computeroutput> and
|
|
<computeroutput>CREATE TEMPORARY TABLES</computeroutput> permissions
|
|
to the list.
|
|
</para>
|
|
</note>
|
|
</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. The Bugzilla Team recommends Apache.
|
|
</para>
|
|
|
|
<section id="http-apache">
|
|
<title>Apache <productname>httpd</productname></title>
|
|
|
|
<para>Load <filename>httpd.conf</filename> in your editor.</para>
|
|
|
|
<para>Uncomment (or add) the following line.
|
|
This configures Apache to run .cgi files outside the
|
|
<filename class="directory">cgi-bin</filename> directory.
|
|
</para>
|
|
|
|
<programlisting> AddHandler cgi-script .cgi</programlisting>
|
|
|
|
<para>Apache uses <computeroutput><Directory></computeroutput>
|
|
directives to permit fine-grained permission setting.
|
|
Add the following two lines to a
|
|
<computeroutput><Directory></computeroutput> directive that
|
|
applies either to the Bugzilla directory or one of its parents
|
|
(e.g. the <computeroutput><Directory /var/www/html></computeroutput>
|
|
directive).
|
|
This allows Bugzilla's <filename>.htaccess</filename> files to
|
|
override global permissions, and allows .cgi files to run in the
|
|
Bugzilla directory.
|
|
</para>
|
|
|
|
<programlisting> Options +ExecCGI +FollowSymLinks
|
|
AllowOverride Limit</programlisting>
|
|
|
|
<para>Add <filename>index.cgi</filename> to the end
|
|
of the <computeroutput>DirectoryIndex</computeroutput>
|
|
line.</para>
|
|
|
|
<para><filename>checksetup.pl</filename> can set tighter permissions
|
|
on Bugzilla's files and directories if it knows what user the
|
|
webserver runs as. Look for the <computeroutput>User</computeroutput>
|
|
line in <filename>httpd.conf</filename>, and place that value in
|
|
the <replaceable>$webservergroup</replaceable> variable in
|
|
<filename>localconfig</filename>. Then rerun
|
|
<filename>checksetup.pl</filename>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="http-iis">
|
|
<title>Microsoft <productname>Internet Information Services</productname></title>
|
|
|
|
<para>If you need, or for some reason even want, to use Microsoft's
|
|
<productname>Internet Information Services</productname> or
|
|
<productname>Personal Web Server</productname> you should be able
|
|
to. You will need to configure them to know how to run CGI scripts.
|
|
This is described in Microsoft Knowledge Base article
|
|
<ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225</ulink>
|
|
for <productname>Internet Information Services</productname> and
|
|
<ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink>
|
|
for <productname>Personal Web Server</productname>.
|
|
</para>
|
|
|
|
<para>Also, and this can't be stressed enough, make sure that files such as
|
|
<filename>localconfig</filename> and your <filename class="directory">data</filename>
|
|
directory are secured as described in <xref linkend="security-access"/>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="http-aol">
|
|
<title>AOL Server</title>
|
|
|
|
<para>Ben FrantzDale reported success using AOL Server with Bugzilla. He
|
|
reported his experience and what appears below is based on that.
|
|
</para>
|
|
|
|
<para>AOL Server will have to be configured to run
|
|
<glossterm linkend="gloss-cgi">CGI</glossterm> scripts, please consult
|
|
the documentation that came with your server for more information on
|
|
how to do this.
|
|
</para>
|
|
|
|
<para>Because AOL Server doesn't support <filename>.htaccess</filename>
|
|
files, you'll have to create a <glossterm linkend="gloss-tcl">TCL</glossterm>
|
|
script. You should create an <filename>aolserver/modules/tcl/filter.tcl</filename>
|
|
file (the filename shouldn't matter) with the following contents (change
|
|
<computeroutput>/bugzilla/</computeroutput> to the web-based path to
|
|
your Bugzilla installation):
|
|
</para>
|
|
|
|
<programlisting>
|
|
ns_register_filter preauth GET /bugzilla/localconfig filter_deny
|
|
ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny
|
|
ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny
|
|
ns_register_filter preauth GET /bugzilla/*.pl filter_deny
|
|
ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny
|
|
ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny
|
|
ns_register_filter preauth GET /bugzilla/data/* filter_deny
|
|
ns_register_filter preauth GET /bugzilla/template/* filter_deny
|
|
|
|
proc filter_deny { why } {
|
|
ns_log Notice "filter_deny"
|
|
return "filter_return"
|
|
}
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>This probably doesn't account for all possible editor backup
|
|
files so you may wish to add some additional variations of
|
|
<filename>localconfig</filename>. For more information, see
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">
|
|
bug 186383</ulink> or <ulink
|
|
url="http://online.securityfocus.com/bid/6501">Bugtraq ID 6501</ulink>.
|
|
</para>
|
|
</warning>
|
|
|
|
<note>
|
|
<para>If you are using webdot from research.att.com (the default
|
|
configuration for the <option>webdotbase</option> paramater), you
|
|
will need to allow access to <filename>data/webdot/*.dot</filename>
|
|
for the reasearch.att.com machine.
|
|
</para>
|
|
<para>If you are using a local installation of <ulink
|
|
url="http://www.graphviz.org">GraphViz</ulink>, you will need to allow
|
|
everybody to access <filename>*.png</filename>,
|
|
<filename>*.gif</filename>, <filename>*.jpg</filename>, and
|
|
<filename>*.map</filename> in the
|
|
<filename class="directory">data/webdot</filename> directory.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="security-access">
|
|
<title>Web Server Access Controls</title>
|
|
|
|
<para>Users of Apache can skip this section because
|
|
Bugzilla ships with <filename>.htaccess</filename> files which
|
|
restrict access in the manner required.
|
|
Users of other webservers, read on.
|
|
</para>
|
|
|
|
<para>There are several files in the Bugzilla directory
|
|
that should not be accessible from the web. You need to configure
|
|
your webserver so they they aren't. Not doing this may reveal
|
|
sensitive information such as database passwords.
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>In the main Bugzilla directory, you should:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block:
|
|
<simplelist type="inline">
|
|
<member><filename>*.pl</filename></member>
|
|
<member><filename>*localconfig*</filename></member>
|
|
<member><filename>runtests.sh</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>But allow:
|
|
<simplelist type="inline">
|
|
<member><filename>localconfig.js</filename></member>
|
|
<member><filename>localconfig.rdf</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In <filename class="directory">data</filename>:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>But allow:
|
|
<simplelist type="inline">
|
|
<member><filename>duplicates.rdf</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In <filename class="directory">data/webdot</filename>:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>If you use a remote webdot server:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>But allow
|
|
<simplelist type="inline">
|
|
<member><filename>*.dot</filename></member>
|
|
</simplelist>
|
|
only for the remote webdot server</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Otherwise, if you use a local GraphViz:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>But allow:
|
|
<simplelist type="inline">
|
|
<member><filename>*.png</filename></member>
|
|
<member><filename>*.gif</filename></member>
|
|
<member><filename>*.jpg</filename></member>
|
|
<member><filename>*.map</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>And if you don't use any dot:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In <filename class="directory">Bugzilla</filename>:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In <filename class="directory">template</filename>:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Block everything</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>You should test to make sure that the files mentioned above are
|
|
not accessible from the Internet, especially your
|
|
<filename>localconfig</filename> file which contains your database
|
|
password. To test, simply point your web browser at the file; for
|
|
example, to test mozilla.org's installation, we'd try to access
|
|
<ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should
|
|
get a <errorcode>403</errorcode> <errorname>Forbidden</errorname>
|
|
error.
|
|
</para>
|
|
</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>
|
|
|
|
<para>
|
|
Log in with the administrator account you defined in the last
|
|
<filename>checksetup.pl</filename> run. You should go through
|
|
the parameters on the Edit Parameters page
|
|
(see link in the footer) 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>
|
|
This would also be a good time to revisit the
|
|
<filename>localconfig</filename> file and make sure that the
|
|
names of the priorities, severities, platforms and operating systems
|
|
are those you wish to use when you start creating bugs. Remember
|
|
to rerun <filename>checksetup.pl</filename> if you change it.
|
|
</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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependency Charts</title>
|
|
|
|
<para>As well as the text-based dependency trees, Bugzilla also
|
|
supports a graphical view of dependency relationships, using a
|
|
package called 'dot'.
|
|
Exactly how this works is controlled by the 'webdotbase' parameter,
|
|
which can have one of three values:
|
|
</para>
|
|
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
A complete file path to the command 'dot' (part of
|
|
<ulink url="http://www.graphviz.org/">GraphViz</ulink>)
|
|
will generate the graphs locally
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A URL prefix pointing to an installation of the webdot package will
|
|
generate the graphs remotely
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A blank value will disable dependency graphing.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>The easiest way to get this working is to install
|
|
<ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you
|
|
do that, you need to
|
|
<ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable
|
|
server-side image maps</ulink> in Apache.
|
|
Alternatively, you could set up a webdot server, or use the AT&T
|
|
public webdot server. This is the default for the webdotbase param,
|
|
but it's often overloaded and slow. Note that AT&T's server
|
|
won't work
|
|
if Bugzilla is only accessible using HARTS.
|
|
<emphasis>Editor's note: What the heck is HARTS? Google doesn't know...
|
|
</emphasis>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<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>
|
|
|
|
</section>
|
|
|
|
<section id="patch-viewer">
|
|
<title>Patch Viewer</title>
|
|
|
|
<para>
|
|
Patch Viewer is the engine behind Bugzilla's graphical display of
|
|
code patches. You can integrate this with copies of the
|
|
<filename>cvs</filename>, <filename>lxr</filename> and
|
|
<filename>bonsai</filename> tools if you have them, by giving
|
|
the locations of your installation of these tools in
|
|
<filename>editparams.cgi</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
Patch Viewer also optionally will use the
|
|
<filename>cvs</filename>, <filename>diff</filename> and
|
|
<filename>interdiff</filename>
|
|
command-line utilities if they exist on the system.
|
|
Interdiff can be obtained from
|
|
<ulink url="http://cyberelk.net/tim/patchutils/"/>.
|
|
If these programs are not in the system path, you can configure
|
|
their locations in <filename>localconfig</filename>.
|
|
</para>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="bzldap">
|
|
<title>LDAP Authentication</title>
|
|
|
|
<para>LDAP authentication is a module for Bugzilla's plugin
|
|
authentication architecture.
|
|
</para>
|
|
|
|
<para>
|
|
The existing authentication
|
|
scheme for Bugzilla uses email addresses as the primary user ID, and a
|
|
password to authenticate that user. All places within Bugzilla where
|
|
you need to deal with user ID (e.g assigning a bug) use the email
|
|
address. The LDAP authentication builds on top of this scheme, rather
|
|
than replacing it. The initial log in is done with a username and
|
|
password for the LDAP directory. This then fetches the email address
|
|
from LDAP and authenticates seamlessly in the standard Bugzilla
|
|
authentication scheme using this email address. If an account for this
|
|
address already exists in your Bugzilla system, it will log in to that
|
|
account. If no account for that email address exists, one is created at
|
|
the time of login. (In this case, Bugzilla will attempt to use the
|
|
"displayName" or "cn" attribute to determine the user's full name.)
|
|
After authentication, all other user-related tasks are still handled by
|
|
email address, not LDAP username. You still assign bugs by email
|
|
address, query on users by email address, etc.
|
|
</para>
|
|
|
|
<caution>
|
|
<para>Because the Bugzilla account is not created until the first time
|
|
a user logs in, a user who has not yet logged is unknown to Bugzilla.
|
|
This means they cannot be used as an assignee or QA contact (default or
|
|
otherwise), added to any cc list, or any other such operation. One
|
|
possible workaround is the <filename>bugzilla_ldapsync.rb</filename>
|
|
script in the
|
|
<glossterm linkend="gloss-contrib"><filename class="directory">contrib</filename></glossterm> directory. Another possible solution is fixing
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug
|
|
201069</ulink>.
|
|
</para>
|
|
</caution>
|
|
|
|
<para>Parameters required to use LDAP Authentication:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="param-loginmethod">
|
|
<term>loginmethod</term>
|
|
<listitem>
|
|
<para>This parameter should be set to <quote>LDAP</quote>
|
|
<emphasis>only</emphasis> if you will be using an LDAP directory
|
|
for authentication. If you set this param to <quote>LDAP</quote> but
|
|
fail to set up the other parameters listed below you will not be
|
|
able to log back in to Bugzilla one you log out. If this happens
|
|
to you, you will need to manually edit
|
|
<filename>data/params</filename> and set loginmethod to
|
|
<quote>DB</quote>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPserver">
|
|
<term>LDAPserver</term>
|
|
<listitem>
|
|
<para>This parameter should be set to the name (and optionally the
|
|
port) of your LDAP server. If no port is specified, it assumes
|
|
the default LDAP port of 389.
|
|
</para>
|
|
<para>Ex. <quote>ldap.company.com</quote>
|
|
or <quote>ldap.company.com:3268</quote>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPbinddn">
|
|
<term>LDAPbinddn [Optional]</term>
|
|
<listitem>
|
|
<para>Some LDAP servers will not allow an anonymous bind to search
|
|
the directory. If this is the case with your configuration you
|
|
should set the LDAPbinddn parameter to the user account Bugzilla
|
|
should use instead of the anonymous bind.
|
|
</para>
|
|
<para>Ex. <quote>cn=default,cn=user:password</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPBaseDN">
|
|
<term>LDAPBaseDN</term>
|
|
<listitem>
|
|
<para>The LDAPBaseDN parameter should be set to the location in
|
|
your LDAP tree that you would like to search for email addresses.
|
|
Your uids should be unique under the DN specified here.
|
|
</para>
|
|
<para>Ex. <quote>ou=People,o=Company</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPuidattribute">
|
|
<term>LDAPuidattribute</term>
|
|
<listitem>
|
|
<para>The LDAPuidattribute parameter should be set to the attribute
|
|
which contains the unique UID of your users. The value retrieved
|
|
from this attribute will be used when attempting to bind as the
|
|
user to confirm their password.
|
|
</para>
|
|
<para>Ex. <quote>uid</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPmailattribute">
|
|
<term>LDAPmailattribute</term>
|
|
<listitem>
|
|
<para>The LDAPmailattribute parameter should be the name of the
|
|
attribute which contains the email address your users will enter
|
|
into the Bugzilla login boxes.
|
|
</para>
|
|
<para>Ex. <quote>mail</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="content-type">
|
|
|
|
<title>Prevent users injecting malicious
|
|
Javascript</title>
|
|
|
|
<para>It is possible for a Bugzilla user to take advantage of character
|
|
set encoding ambiguities to inject HTML into Bugzilla comments. This
|
|
could include malicious scripts.
|
|
Due to internationalization concerns, we are unable to
|
|
incorporate by default the code changes suggested by
|
|
<ulink
|
|
url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">
|
|
the CERT advisory</ulink> on this issue.
|
|
If your installation is for an English speaking audience only, making the
|
|
change below will prevent this problem.
|
|
</para>
|
|
|
|
<para>Simply locate the following line in
|
|
<filename>Bugzilla/CGI.pm</filename>:
|
|
<programlisting>$self->charset('');</programlisting>
|
|
and change it to:
|
|
<programlisting>$self->charset('ISO-8859-1');</programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="mod-throttle"
|
|
xreflabel="Using mod_throttle to prevent Denial of Service attacks">
|
|
<title>
|
|
<filename>mod_throttle</filename></title>
|
|
|
|
<para>It is possible for a user, by mistake or on purpose, to access
|
|
the database many times in a row which can result in very slow access
|
|
speeds for other users. If your Bugzilla installation is experiencing
|
|
this problem, you may install the Apache module
|
|
<filename>mod_throttle</filename>
|
|
which can limit connections by IP address. You may download this module
|
|
at
|
|
<ulink url="http://www.snert.com/Software/mod_throttle/"/>.
|
|
Follow the instructions to install into your Apache install.
|
|
<emphasis>This module only functions with the Apache web
|
|
server!</emphasis>
|
|
The command you need is
|
|
<command>ThrottleClientIP</command>. See the
|
|
<ulink url="http://www.snert.com/Software/mod_throttle/">documentation</ulink>
|
|
for more information.</para>
|
|
</section>
|
|
|
|
<section id="security-networking">
|
|
<title>TCP/IP Ports</title>
|
|
|
|
<para>A single-box Bugzilla only requires port 80, plus port 25 if
|
|
you are using the optional email interface. You should firewall all
|
|
other ports and/or disable services listening on them.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="security-daemon">
|
|
<title>Daemon Accounts</title>
|
|
|
|
<para>Many daemons, such as Apache's httpd and MySQL's mysqld default to
|
|
running as either <quote>root</quote> or <quote>nobody</quote>. Running
|
|
as <quote>root</quote> introduces obvious security problems, but the
|
|
problems introduced by running everything as <quote>nobody</quote> may
|
|
not be so obvious. Basically, if you're running every daemon as
|
|
<quote>nobody</quote> and one of them gets compromised, they all get
|
|
compromised. For this reason it is recommended that you create a user
|
|
account for each daemon.
|
|
</para>
|
|
</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 text/xml .rdf</screen>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
<section id="os-specific">
|
|
<title>OS-Specific Installation Notes</title>
|
|
|
|
<para>Many aspects of the Bugzilla installation can be affected by the
|
|
the operating system you choose to install it on. Sometimes it can be made
|
|
easier and others more difficult. This section will attempt to help you
|
|
understand both the difficulties of running on specific operating systems
|
|
and the utilities available to make it easier.
|
|
</para>
|
|
|
|
<para>If you have anything to add or notes for an operating system not
|
|
covered, please file a bug in &bzg-bugs;.
|
|
</para>
|
|
|
|
<section id="os-win32">
|
|
<title>Microsoft Windows</title>
|
|
|
|
<para>Making Bugzilla work on Windows is still a painful processes.
|
|
The Bugzilla Team is working to make it easier, but that goal is not
|
|
considered a top priority. If you wish to run Bugzilla, we still
|
|
recommend doing so on a Unix based system such as GNU/Linux. As of this
|
|
writing, all members of the Bugzilla team and all known large installations
|
|
run on Unix based systems.
|
|
</para>
|
|
|
|
<para>If after hearing all that, you have enough pain tolerance to attempt
|
|
installing Bugzilla on Win32, here are some pointers.
|
|
<![%bz-devel;[
|
|
Because this is a development version of the guide, these instructions
|
|
are subject to change without notice. In fact, the Bugzilla Team hopes
|
|
to have Bugzilla reasonably close to "out of
|
|
the box" compatibility with Windows by the 2.18 release.
|
|
]]>
|
|
</para>
|
|
|
|
<section id="win32-perl">
|
|
<title>Win32 Perl</title>
|
|
|
|
<para>Perl for Windows can be obtained from <ulink
|
|
url="http://www.activestate.com/">ActiveState</ulink>. You should be
|
|
able to find a compiled binary at <ulink
|
|
url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/"/>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="win32-perlmodules">
|
|
<title>Perl Modules on Win32</title>
|
|
|
|
<para>Bugzilla on Windows requires the same perl modules found in
|
|
<xref linkend="install-perlmodules"/>. The main difference is that
|
|
windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead of
|
|
CPAN.
|
|
</para>
|
|
|
|
<programlisting>
|
|
C:\perl> <command>ppm install <module name></command>
|
|
</programlisting>
|
|
|
|
<note>
|
|
<para>The above syntax should work for all modules with the exception
|
|
of Template Toolkit. The <ulink
|
|
url="http://tt2.org/download.html#win32">Template Toolkit website</ulink>
|
|
suggests using the instructions on <ulink
|
|
url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>.
|
|
</para>
|
|
|
|
<para>The following commands will install the required packages
|
|
missing from the ActivePerl default installation:
|
|
</para>
|
|
|
|
<programlisting>
|
|
<command>ppm repository add oi http://openinteract.sourceforge.net/ppmpackages</command>
|
|
<command>ppm install DBD-mysql</command>
|
|
<command>ppm install Template-Toolkit</command>
|
|
<command>ppm install TimeDate</command>
|
|
</programlisting>
|
|
|
|
</note>
|
|
</section>
|
|
|
|
<section id="win32-code-changes">
|
|
<title>Code changes required to run on win32</title>
|
|
|
|
<para>As Bugzilla still doesn't run "out of the box" on
|
|
Windows, code has to be modified. This section lists the required
|
|
changes.
|
|
</para>
|
|
|
|
<section id="win32-code-checksetup">
|
|
<title>Changes to <filename>checksetup.pl</filename></title>
|
|
|
|
<para>In <filename>checksetup.pl</filename>, the line reading:</para>
|
|
|
|
<programlisting>
|
|
my $mysql_binaries = `which mysql`;
|
|
</programlisting>
|
|
<para>to</para>
|
|
<programlisting>
|
|
my $mysql_binaries = "D:\\mysql\\bin\\mysql";
|
|
</programlisting>
|
|
|
|
<para>And you'll also need to change:</para>
|
|
|
|
<programlisting>
|
|
my $webservergid = getgrnam($my_webservergroup)
|
|
</programlisting>
|
|
<para>to</para>
|
|
<programlisting>
|
|
my $webservergid = '8'
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="win32-code-bugmail">
|
|
<title>Changes to <filename>BugMail.pm</filename></title>
|
|
|
|
<para>To make bug email work on Win32 (until
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=84876">bug
|
|
84876</ulink> lands), the
|
|
simplest way is to have the Net::SMTP Perl module installed and
|
|
change this:</para>
|
|
|
|
<programlisting>
|
|
open(SENDMAIL, "|/usr/lib/sendmail $sendmailparam -t -i") ||
|
|
die "Can't open sendmail";
|
|
|
|
print SENDMAIL trim($msg) . "\n";
|
|
close SENDMAIL;
|
|
</programlisting>
|
|
<para>to</para>
|
|
<programlisting>
|
|
use Net::SMTP;
|
|
my $smtp_server = 'smtp.mycompany.com'; # change this
|
|
|
|
# Use die on error, so that the mail will be in the 'unsent mails' and
|
|
# can be sent from the sanity check page.
|
|
my $smtp = Net::SMTP->new($smtp_server) ||
|
|
die 'Cannot connect to server \'$smtp_server\'';
|
|
|
|
$smtp->mail('bugzilla-daemon@mycompany.com'); # change this
|
|
$smtp->to($person);
|
|
$smtp->data();
|
|
$smtp->datasend($msg);
|
|
$smtp->dataend();
|
|
$smtp->quit;
|
|
</programlisting>
|
|
|
|
<para>Don't forget to change the name of your SMTP server and the
|
|
domain of the sending email address (after the '@') in the above
|
|
lines of code.</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="win32-http">
|
|
<title>Serving the web pages</title>
|
|
|
|
<para>As is the case on Unix based systems, any web server should be
|
|
able to handle Bugzilla; however, the Bugzilla Team still recommends
|
|
Apache whenever asked. No matter what web server you choose, be sure
|
|
to pay attention to the security notes in <xref linkend="security-access"/>.
|
|
More information on configuring specific web servers can be found in
|
|
<xref linkend="http"/>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>If using Apache on windows, you can set the <ulink
|
|
url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink>
|
|
directive in your Apache config to avoid having
|
|
to modify the first line of every script to contain your path to
|
|
perl instead of <filename>/usr/bin/perl</filename>.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="os-macosx">
|
|
<title><productname>Mac OS X</productname></title>
|
|
|
|
<para>Apple did not include the GD library with Mac OS X. Bugzilla
|
|
needs this for bug graphs.</para>
|
|
|
|
<para>You can install it using a program called
|
|
Fink, which is similar in nature to the CPAN installer, but installs
|
|
common GNU utilities. Fink is available from
|
|
<ulink url="http://sourceforge.net/projects/fink/"/>.</para>
|
|
|
|
<para>Follow the instructions for setting up Fink. Once it's installed,
|
|
you'll want to use it to install the <filename>gd2</filename> package.
|
|
</para>
|
|
|
|
<para>It will prompt you for a number of dependencies, type 'y' and hit
|
|
enter to install all of the dependencies and then watch it work. You will
|
|
then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to
|
|
install the GD Perl module.
|
|
</para>
|
|
|
|
<note>
|
|
<para>To prevent creating conflicts with the software that Apple
|
|
installs by default, Fink creates its own directory tree at
|
|
<filename class="directory">/sw</filename> where it installs most of
|
|
the software that it installs. This means your libraries and headers
|
|
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 Fink is <filename>expat</filename>. After using
|
|
fink to install the expat package you will be able to install
|
|
XML::Parser using CPAN. There is one caveat. Unlike recent versions of
|
|
the GD module, XML::Parser doesn't prompt for the location of the
|
|
required libraries. When using CPAN, you will need to use the following
|
|
command sequence:
|
|
</para>
|
|
|
|
<screen>
|
|
# perl -MCPAN -e'look XML::Parser' <co id="macosx-look"/>
|
|
# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include
|
|
# make; make test; make install <co id="macosx-make"/>
|
|
# exit <co id="macosx-exit"/>
|
|
</screen>
|
|
<calloutlist>
|
|
<callout arearefs="macosx-look macosx-exit">
|
|
<para>The look command will download the module and spawn a
|
|
new shell with the extracted files as the current working directory.
|
|
The exit command will return you to your original shell.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="macosx-make">
|
|
<para>You should watch the output from these make commands,
|
|
especially <quote>make test</quote> as errors may prevent XML::Parser
|
|
from functioning correctly with Bugzilla.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</section>
|
|
|
|
<section id="os-mandrake">
|
|
<title>Linux-Mandrake 8.0</title>
|
|
|
|
<para>Linux-Mandrake 8.0 includes every required and optional library
|
|
for Bugzilla. The easiest way to install them is by using the
|
|
<command>urpmi</command> utility. If you follow these commands, you
|
|
should have everything you need for Bugzilla, and
|
|
<command>./checksetup.pl</command> should not complain about any
|
|
missing libraries. You may already have some of these installed.
|
|
</para>
|
|
|
|
<screen>
|
|
<prompt>bash#</prompt> <command>urpmi perl-mysql</command>
|
|
<prompt>bash#</prompt> <command>urpmi perl-chart</command>
|
|
<prompt>bash#</prompt> <command>urpmi perl-gd</command>
|
|
<prompt>bash#</prompt> <command>urpmi perl-MailTools</command> <co id="test-mailtools"/>
|
|
<prompt>bash#</prompt> <command>urpmi apache-modules</command>
|
|
</screen>
|
|
<calloutlist>
|
|
<callout arearefs="test-mailtools">
|
|
<para>for Bugzilla email integration</para>
|
|
</callout>
|
|
</calloutlist>
|
|
|
|
</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 adminstrator 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.com/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'll have to
|
|
change the locations on the scripts, which is detailed later on
|
|
this page.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Perl Modules</title>
|
|
|
|
<para>Installing the Perl modules as a non-root user is probably the
|
|
hardest part of the process. There are two different methods: a
|
|
completely independant Perl with its own modules, or personal
|
|
modules using the current (root installed) version of Perl. The
|
|
independant method takes up quite a bit of disk space, but is
|
|
less complex, while the mixed method only uses as much space as the
|
|
modules themselves, but takes more work to setup.</para>
|
|
|
|
<section>
|
|
<title>The Independant Method</title>
|
|
|
|
<para>The independant method requires that you install your own
|
|
personal version of Perl, as detailed in the previous section. Once
|
|
installed, you can start the CPAN shell with the following
|
|
command:</para>
|
|
|
|
<para>
|
|
<screen>
|
|
<prompt>bash$</prompt>
|
|
<command>/home/foo/perl/bin/perl -MCPAN -e 'shell'</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>And then:</para>
|
|
|
|
<para>
|
|
<screen>
|
|
<prompt>cpan></prompt>
|
|
<command>install Bundle::Bugzilla</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>With this method, module installation will usually go a lot
|
|
smoother, but if you have any hang-ups, you can consult the next
|
|
section.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>The Mixed Method</title>
|
|
|
|
<para>First, you'll need to configure CPAN to
|
|
install modules in your home directory. The CPAN FAQ says the
|
|
following on this issue:</para>
|
|
|
|
<para>
|
|
<programlisting>
|
|
5) I am not root, how can I install a module in a personal directory?
|
|
|
|
You will most probably like something like this:
|
|
|
|
o conf makepl_arg "LIB=~/myperl/lib \
|
|
INSTALLMAN1DIR=~/myperl/man/man1 \
|
|
INSTALLMAN3DIR=~/myperl/man/man3"
|
|
install Sybase::Sybperl
|
|
|
|
You can make this setting permanent like all "o conf" settings with "o conf commit".
|
|
|
|
You will have to add ~/myperl/man to the MANPATH environment variable and also tell your Perl programs to
|
|
look into ~/myperl/lib, e.g. by including
|
|
|
|
use lib "$ENV{HOME}/myperl/lib";
|
|
|
|
or setting the PERL5LIB environment variable.
|
|
|
|
Another thing you should bear in mind is that the UNINST parameter should never be set if you are not root.</programlisting>
|
|
</para>
|
|
|
|
<para>So, you will need to create a Perl directory in your home
|
|
directory, as well as the <filename class="directory">lib</filename>,
|
|
<filename class="directory">man</filename>,
|
|
<filename class="directory">man/man1</filename>, and
|
|
<filename class="directory">man/man3</filename> directories in that
|
|
Perl directory. Set the MANPATH variable and PERL5LIB variable, so
|
|
that the installation of the modules goes smoother. (Setting
|
|
UNINST=0 in your "make install" options, on the CPAN first-time
|
|
configuration, is also a good idea.)</para>
|
|
|
|
<para>After that, go into the CPAN shell:</para>
|
|
|
|
<para>
|
|
<screen>
|
|
<prompt>bash$</prompt>
|
|
<command>perl -MCPAN -e 'shell'</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>From there, you will need to type in the above "o conf" command
|
|
and commit the changes. Then you can run through the installation:</para>
|
|
|
|
<para>
|
|
<screen>
|
|
<prompt>cpan></prompt>
|
|
<command>install Bundle::Bugzilla</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>Most of the module installation process should go smoothly. However,
|
|
you may have some problems with Template. When you first start, you will
|
|
want to try to install Template with the XS Stash options on. If this
|
|
doesn't work, it may spit out C compiler error messages and croak back
|
|
to the CPAN shell prompt. So, redo the install, and turn it off. (In fact,
|
|
say no to all of the Template questions.) It may also start failing on a
|
|
few of the tests. If the total tests passed is a reasonable figure (90+%),
|
|
force the install with the following command:</para>
|
|
|
|
<para>
|
|
<screen>
|
|
<prompt>cpan></prompt>
|
|
<command>force install Template</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>You may also want to install the other optional modules:</para>
|
|
|
|
<screen>
|
|
<prompt>cpan></prompt>
|
|
<command>install GD</command>
|
|
<prompt>cpan></prompt>
|
|
<command>install Chart::Base</command>
|
|
<prompt>cpan></prompt>
|
|
<command>install MIME::Parser</command>
|
|
</screen>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>HTTP Server</title>
|
|
|
|
<para>Ideally, this also needs to be installed as root and
|
|
run under a special webserver 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>Since you probably can't set up a symbolic link to
|
|
<filename>/usr/bonsaitools/bin/perl</filename> as a non-root user,
|
|
you will need to hack the scripts to point to the right Perl:</para>
|
|
|
|
<para>
|
|
<programlisting>perl -pi -e
|
|
's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm
|
|
processmail syncshadowdb</programlisting>
|
|
|
|
Change <filename>/usr/bin/perl</filename> to match the location
|
|
of Perl on your machine. If you had to install Perl as non-root,
|
|
this would be the location in your home directory.
|
|
</para>
|
|
|
|
<note>
|
|
<para>Version 2.17+ of Bugzilla now already has the scripts
|
|
pointing to <filename>/usr/bin/perl</filename>.</para>
|
|
</note>
|
|
|
|
<para>Of course, the scripts will not work if they don't know the
|
|
location of your newly install Perl modules, so you will have to hack
|
|
the scripts to look for those, too:</para>
|
|
|
|
<para>
|
|
<programlisting>perl -pi -e
|
|
's@use strict\;@use strict\; use lib \"/home/foo/perl/lib\"\;@'
|
|
*cgi *pl Bug.pm processmail syncshadowdb</programlisting>
|
|
|
|
Change <filename class="directory">/home/foo/perl/lib</filename> to
|
|
your personal Perl library directory. You can probably skip this
|
|
step if you are using the independant method of Perl module
|
|
installation.
|
|
</para>
|
|
|
|
<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 the CPAN shell, then delete the
|
|
<filename>localconfig</filename> file and try again.</para>
|
|
|
|
<warning>
|
|
<para>The 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>
|
|
</section>
|
|
|
|
<section id="troubleshooting">
|
|
<title>Troubleshooting</title>
|
|
|
|
<para>This section gives solutions to common Bugzilla installation
|
|
problems. If none of the section headings seems to match your
|
|
problem, read the general advice.
|
|
</para>
|
|
|
|
<section id="general-advice">
|
|
<title>General Advice</title>
|
|
<para>
|
|
If you can't get <filename>checksetup.pl</filename> to run to
|
|
completion, it normally explains what's wrong and how to fix it.
|
|
If you can't work it out, or if it's being uncommunicative, post
|
|
the errors in the
|
|
<ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">netscape.public.mozilla.webtools</ulink>
|
|
newsgroup.
|
|
</para>
|
|
|
|
<para>
|
|
If you have made it all the way through
|
|
<xref linkend="installation"/> (Installation) and
|
|
<xref linkend="configuration"/> (Configuration) but
|
|
accessing the Bugzilla URL doesn't work,
|
|
the first thing to do is to check your webserver error log. For
|
|
Apache, this is often located at
|
|
<filename>/etc/logs/httpd/error_log</filename>. The error messages
|
|
you see may be self-explanatory enough to enable you to diagnose and
|
|
fix the problem. If not, see below for some commonly-encountered
|
|
errors. If that doesn't help, post the errors to the newsgroup.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>I installed a Perl module, but
|
|
<filename>checksetup.pl</filename> claims it's not installed!</title>
|
|
|
|
<para>
|
|
You have two versions of Perl on your machine. You are installing
|
|
modules into one, and Bugzilla is using the other. Rerun the CPAN
|
|
commands (or manual compile) using the full path to Perl from the
|
|
top of <filename>checksetup.pl</filename>. This will make sure you
|
|
are installing the modules in the right place.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title>
|
|
|
|
<para>
|
|
Try executing <command>perl -MCPAN -e 'install CPAN'</command>
|
|
and then continuing.
|
|
</para>
|
|
|
|
<para>
|
|
Certain older versions of the CPAN toolset were somewhat naive about how
|
|
to upgrade Perl modules. When a couple of modules got rolled into the core
|
|
Perl distribution for 5.6.1, CPAN thought that the best way to get those
|
|
modules up to date was to haul down the Perl distribution itself and
|
|
build it. Needless to say, this has caused headaches for just about
|
|
everybody. Upgrading to a newer version of CPAN with the
|
|
commandline above should fix things.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>DBD::Sponge::db prepare failed</title>
|
|
|
|
<para>
|
|
The following error message may appear due to a bug in DBD::mysql
|
|
(over which the Bugzilla team have no control):
|
|
</para>
|
|
|
|
<programlisting><![CDATA[ DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248.
|
|
SV = NULL(0x0) at 0x20fc444
|
|
REFCNT = 1
|
|
FLAGS = (PADBUSY,PADMY)
|
|
]]></programlisting>
|
|
|
|
<para>
|
|
To fix this, go to
|
|
<filename><path-to-perl>/lib/DBD/sponge.pm</filename>
|
|
in your Perl installation and replace
|
|
</para>
|
|
|
|
<programlisting><![CDATA[ my $numFields;
|
|
if ($attribs->{'NUM_OF_FIELDS'}) {
|
|
$numFields = $attribs->{'NUM_OF_FIELDS'};
|
|
} elsif ($attribs->{'NAME'}) {
|
|
$numFields = @{$attribs->{NAME}};
|
|
]]></programlisting>
|
|
|
|
<para>
|
|
by
|
|
</para>
|
|
|
|
<programlisting><![CDATA[ my $numFields;
|
|
if ($attribs->{'NUM_OF_FIELDS'}) {
|
|
$numFields = $attribs->{'NUM_OF_FIELDS'};
|
|
} elsif ($attribs->{'NAMES'}) {
|
|
$numFields = @{$attribs->{NAMES}};
|
|
]]></programlisting>
|
|
|
|
<para>
|
|
(note the S added to NAME.)
|
|
</para>
|
|
</section>
|
|
|
|
<section id="paranoid-security">
|
|
<title>cannot chdir(/var/spool/mqueue)</title>
|
|
|
|
<para>If you are installing Bugzilla on SuSE Linux, or some other
|
|
distributions with
|
|
<quote>paranoid</quote>
|
|
security options, it is possible that the checksetup.pl script may fail
|
|
with the error:
|
|
<programlisting><![CDATA[cannot chdir(/var/spool/mqueue): Permission denied
|
|
]]></programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
This is because your
|
|
<filename>/var/spool/mqueue</filename>
|
|
directory has a mode of
|
|
<quote>drwx------</quote>. Type
|
|
<command>chmod 755
|
|
<filename>/var/spool/mqueue</filename>
|
|
</command>
|
|
as root to fix this problem.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="trouble-filetemp">
|
|
<title>Your vendor has not defined Fcntl macro O_NOINHERIT</title>
|
|
|
|
<para>This is caused by a bug in the version of
|
|
<productname>File::Temp</productname> that is distributed with perl
|
|
5.6.0. Many minor variations of this error have been reported:
|
|
</para>
|
|
|
|
<programlisting>Your vendor has not defined Fcntl macro O_NOINHERIT, used
|
|
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208.
|
|
|
|
Your vendor has not defined Fcntl macro O_EXLOCK, used
|
|
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210.
|
|
|
|
Your vendor has not defined Fcntl macro O_TEMPORARY, used
|
|
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.</programlisting>
|
|
|
|
<para>Numerous people have reported that upgrading to version 5.6.1
|
|
or higher solved the problem for them. A less involved fix is to apply
|
|
the following patch, which is also
|
|
available as a <ulink url="../xml/filetemp.patch">patch file</ulink>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[--- File/Temp.pm.orig Thu Feb 6 16:26:00 2003
|
|
+++ File/Temp.pm Thu Feb 6 16:26:23 2003
|
|
@@ -205,6 +205,7 @@
|
|
# eg CGI::Carp
|
|
local $SIG{__DIE__} = sub {};
|
|
local $SIG{__WARN__} = sub {};
|
|
+ local *CORE::GLOBAL::die = sub {};
|
|
$bit = &$func();
|
|
1;
|
|
};
|
|
@@ -226,6 +227,7 @@
|
|
# eg CGI::Carp
|
|
local $SIG{__DIE__} = sub {};
|
|
local $SIG{__WARN__} = sub {};
|
|
+ local *CORE::GLOBAL::die = sub {};
|
|
$bit = &$func();
|
|
1;
|
|
};]]></programlisting>
|
|
</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:
|
|
-->
|
|
|