| <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> |
| <!-- $Id: installation.xml,v 1.98.2.9 2005/12/30 15:29:01 mozilla%colinogilvie.co.uk 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 for non-Windows platforms; &min-perl-ver-win; |
| for Windows) |
| </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: <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. |
| </para> |
| </section> |
| |
| <section id="install-database"> |
| <title>Database Engine</title> |
| |
| <para>From Bugzilla 2.20, support is included for using both the MySQL and |
| PostgreSQL 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: <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 (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: <filename>psql -V</filename></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> |
| |
| <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, 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> |
| 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-perl-modules"/>). 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> |
| |
| <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> |
| 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;) if using MySQL |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| DBD::Pg (&min-dbd-pg-ver;) if using PostgreSQL |
| </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> |
| |
| <listitem> |
| <para> |
| Mail::Mailer (&min-mail-mailer-ver;) |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Storable (&min-storable-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 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 accouts). |
| </para> |
| |
| <para> |
| For more information, see the "maildeliverymethod" 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> |
| |
| |
| <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 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> |
| 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 in run. |
| </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="database-engine"> |
| <title>Database Server</title> |
| <para>This section deals with configuring your database server for use |
| with Bugzilla. Currently <xref linkend="mysql"/> and |
| <xref linkend="postgresql"/> are available.</para> |
| |
| <section id="mysql"> |
| <title>MySQL</title> |
| |
| <caution> |
| <para> |
| MySQL's default configuration is very insecure. |
| <xref linkend="security-mysql"/> has some good information for |
| improving your installation's security. |
| </para> |
| </caution> |
| |
| <section id="install-setupdatabase"> |
| <title>Allow large attachments</title> |
| |
| <para> |
| By default, MySQL will only accept packets up to 64Kb in size. |
| If you want to have attachments larger than this, you will need |
| to modify your <filename>/etc/my.cnf</filename> as below. |
| </para> |
| |
| <para> |
| If you are using MySQL 4.0 or newer, enter: |
| </para> |
| <screen> [mysqld] |
| # Allow packets up to 1M |
| max_allowed_packet=1M</screen> |
| |
| <para> |
| If you are using an older version of MySQL, enter: |
| </para> |
| <screen> [mysqld] |
| # Allow packets up to 1M |
| set-variable = max_allowed_packet=1M</screen> |
| |
| <para> |
| There is also a parameter in Bugzilla called 'maxattachmentsize' |
| (default = 1000 Kb) that controls the maximum allowable attachment |
| size. Attachments larger than <emphasis>either</emphasis> the |
| 'max_allowed_packet' or 'maxattachmentsize' value will not be |
| accepted by Bugzilla. |
| </para> |
| |
| <note> |
| <para> |
| This does not affect Big Files, attachments that are stored directly |
| on disk instead of in the database. Their maximum size is |
| controlled using the 'maxlocalattachment' parameter. |
| </para> |
| </note> |
| </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> |
| |
| <note> |
| <para> |
| The ft_min_word_len parameter is only suported in MySQL v4 or higher. |
| </para> |
| </note> |
| </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> |
| 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> |
| |
| <note> |
| <para> |
| This does not affect Big Files, attachments that are stored directly |
| on disk instead of in the database. |
| </para> |
| </note> |
| </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. |
| </para> |
| |
| <para> |
| If you are using MySQL 4.0 or newer, 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> |
| |
| <para> |
| If you are using an older version of MySQL,the |
| <computeroutput>LOCK TABLES</computeroutput> and |
| <computeroutput>CREATE TEMPORARY TABLES</computeroutput> |
| permissions will be unavailable and should be removed from |
| the permissions list. In this case, the following command |
| line can be used: |
| </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> |
| </section> |
| </section> |
| |
| <section id="postgresql"> |
| <title>PostgreSQL</title> |
| <note> |
| <para>Note if you are using PostgreSQL 8.0.1 or higher, then you |
| will require to use a version of DBD::Pg which is equal to or |
| greater than version 1.41 |
| </para> |
| </note> |
| |
| <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 -dAP 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 have the ability to create databases and will not be |
| able to create new users.</para> |
| </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>If you are using <emphasis role="bold">versions of PostgreSQL |
| before version 8</emphasis>, you may also need to edit <filename>postgresql.conf</filename> |
| , also usually found in the <filename>/var/lib/pgsql/data/</filename> folder. |
| You will need to make a single line change, changing</para> |
| |
| <para> |
| <computeroutput># tcpip_socket = false</computeroutput> |
| </para> |
| |
| <para>to</para> |
| |
| <para> |
| <computeroutput>tcpip_socket = true</computeroutput> |
| </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> |
| |
| <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.) Regardless of which webserver |
| you are using, however, ensure that sensitive information is |
| not remotely available by properly applying the access controls in |
| <xref linkend="security-webserver-access"/>. |
| </para> |
| |
| <section id="http-apache"> |
| <title>Apache <productname>httpd</productname></title> |
| |
| <para> |
| To configure your Apache web server to work with Bugzilla, |
| 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> |
| </step> |
| |
| <step> |
| <para> |
| <filename>checksetup.pl</filename> can set tighter permissions |
| on Bugzilla's files and directories if it knows what group the |
| webserver 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-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 webserver. |
| </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 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> |
| |
| <para> |
| When upgrading Bugzilla, this format may change. |
| To create new status data, (re)move old data and run the following |
| commands: |
| </para> |
| |
| <screen> |
| <prompt>bash$</prompt> |
| <command>cd <your-bugzilla-directory></command> |
| <prompt>bash$</prompt> |
| <command>./collectstats.pl --regenerate</command> |
| </screen> |
| |
| <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> |
| <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 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="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="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="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 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. |
| </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> |
| </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. |
| </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 the Bugzilla Test Server (aka 'Landfill'), so |
| you should add the Landfill package repository as follows: |
| </para> |
| |
| <programlisting> |
| <command>ppm repository add landfill http://www.landfill.bugzilla.org/ppm/</command> |
| </programlisting> |
| |
| <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 acccess |
| 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-code-changes"> |
| <title>Code changes required to run on Win32</title> |
| |
| <para> |
| Bugzilla on Win32 is supported out of the box from version 2.20; this |
| means that no code changes are required to get Bugzilla running. |
| </para> |
| |
| </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> |
| 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 |
| perl instead of <filename>/usr/bin/perl</filename>. |
| </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>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 id="install-perlmodules-nonroot"> |
| <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>If you had to install Perl modules as a non-root user |
| (<xref linkend="install-perlmodules-nonroot" />) or to non-standard |
| directories, you will need to change the scripts, setting the correct |
| location of the Perl modules:</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> |
| |
| </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: |
| --> |