4.1. Step-by-step Install
4.1.1. Introduction
Bugzilla has been successfully installed under Solaris, Linux, and Win32. Win32 is not yet officially supported, but many people have got it working fine. Please see the Win32 Installation Notes for further advice on getting Bugzilla to work on Microsoft Windows.
4.1.2. Package List
 | If you are running the very most recent version of Perl and MySQL (both the executables and development libraries) on your system, you can skip these manual installation steps for the Perl modules by using Bundle::Bugzilla; see Using Bundle::Bugzilla instead of manually installing Perl modules. |
The software packages necessary for the proper running of Bugzilla (with download links) are:
MySQL database server (3.22.5 or greater)
Perl (5.005 or greater, 5.6.1 is recommended if you wish to use Bundle::Bugzilla)
Perl Modules (minimum version):
Template (v2.07)
AppConfig (v1.52)
Text::Wrap (v2001.0131)
File::Spec (v0.8.2)
Data::Dumper (any)
DBD::mysql (v1.2209)
DBI (v1.13)
Date::Parse (any)
CGI::Carp (any)
GD (v1.19) for bug charting
Chart::Base (v0.99c) for bug charting
XML::Parser (any) for the XML interface
MIME::Parser (any) for the email interface
The web server of your choice. Apache is highly recommended.
 | It is a good idea, while installing Bugzilla, to ensure that there is some kind of firewall between you and the rest of the Internet, because your machine may be insecure for periods during the install. Many installation steps require an active Internet connection to complete, but you must take care to ensure that at no point is your machine vulnerable to an attack. |
| Linux-Mandrake 8.0 includes every required and optional library for Bugzilla. The easiest way to install them is by using the urpmi utility. If you follow these commands, you should have everything you need for Bugzilla, and checksetup.pl should not complain about any missing libraries. You may already have some of these installed.
|
4.1.3. MySQL
Visit the MySQL homepage at www.mysql.com to grab and install the latest stable release of the server.
| Many of the binary versions of MySQL store their data files in /var. On some Unix systems, this is part of a smaller root partition, and may not have room for your bug database. You can set the data directory as an option to configure if you build MySQL from source yourself. |
If you install from something other than an RPM or Debian package, you will need to add mysqld to your init scripts so the server daemon will come back up whenever your machine reboots. Further discussion of UNIX init sequences are beyond the scope of this guide.
Change your init script to start mysqld with the ability to accept large packets. By default, mysqld only accepts packets up to 64K long. This limits the size of attachments you may put on bugs. If you add -O max_allowed_packet=1M to the command that starts mysqld (or safe_mysqld), then you will be able to have attachments up to about 1 megabyte. There is a Bugzilla parameter for maximum attachment size; you should configure it to match the value you choose here.
If you plan on running Bugzilla and MySQL on the same machine, consider using the --skip-networking option in the init script. This enhances security by preventing network access to MySQL.
4.1.4. Perl
Any machine that doesn't have Perl on it is a sad machine indeed. Perl can be got in source form from perl.com for the rare *nix systems which don't have it. Although Bugzilla runs with all post-5.005 versions of Perl, it's a good idea to be up to the very latest version if you can when running Bugzilla. As of this writing, that is Perl version 5.6.1.
 | You can skip the following Perl module installation steps by installing Bundle::Bugzilla from CPAN, which installs all required modules for you. bash# perl -MCPAN -e 'install "Bundle::Bugzilla"' Bundle::Bugzilla doesn't include GD, Chart::Base, or MIME::Parser, which are not essential to a basic Bugzilla install. If installing this bundle fails, you should install each module individually to isolate the problem. |
4.1.5. Perl Modules
All Perl modules can be found on the Comprehensive Perl Archive Network (CPAN). The CPAN servers have a real tendency to bog down, so please use mirrors.
Quality, general Perl module installation instructions can be found on the CPAN website, but the easy thing to do is to just use the CPAN shell which does all the hard work for you. To use the CPAN shell to install a module:
bash# perl -MCPAN -e 'install "<modulename>"'
To do it the hard way:
Untar the module tarball -- it should create its own directory
CD to the directory just created, and enter the following commands:
bash# perl Makefile.PL
bash# make
bash# make test
bash# make install
| Many people complain that Perl modules will not install for them. Most times, the error messages complain that they are missing a file in "@INC". 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 are the local UNIX sysadmin, please consult the newsgroup/mailing list for further assistance or hire someone to help you out. |
4.1.5.1. DBI
The DBI module is a generic Perl module used the MySQL-related modules. As long as your Perl installation was done correctly the DBI module should be a breeze. It's a mixed Perl/C module, but Perl's MakeMaker system simplifies the C compilation greatly.
4.1.5.2. Data::Dumper
The Data::Dumper module provides data structure persistence for Perl (similar to Java's serialization). It comes with later sub-releases of Perl 5.004, but a re-installation just to be sure it's available won't hurt anything.
4.1.5.3. MySQL-related modules
The Perl/MySQL interface requires a few mutually-dependent Perl modules. These modules are grouped together into the the Msql-Mysql-modules package.
The MakeMaker process will ask you a few questions about the desired compilation target and your MySQL installation. For most of the questions the provided default will be adequate, but when asked if your desired target is the MySQL or mSQL packages, you should select the MySQL related ones. Later you will be asked if you wish to provide backwards compatibility with the older MySQL packages; you should answer YES to this question. The default is NO.
A host of 'localhost' should be fine and a testing user of 'test' with a null password should find itself with sufficient access to run tests on the 'test' database which MySQL created upon installation.
4.1.5.4. TimeDate modules
Many of the more common date/time/calendar related Perl modules have been grouped into a bundle similar to the MySQL modules bundle. This bundle is stored on the CPAN under the name TimeDate. The component module we're most interested in is the Date::Format module, but installing all of them is probably a good idea anyway.
4.1.5.5. GD (optional)
The GD library was written by Thomas Boutell a long while ago to programatically generate images in C. Since then it's become the defacto standard for programatic image construction. The Perl bindings to it found in the GD library are used on millions of web pages to generate graphs on the fly. That's what Bugzilla will be using it for so you must install it if you want any of the graphing to work.
| The Perl GD library requires some other libraries that may or may not be installed on your system, including libpng and libgd. The full requirements are listed in the Perl GD library README. If compiling GD fails, it's probably because you're missing a required library. |
4.1.5.6. Chart::Base (optional)
The Chart module provides Bugzilla with on-the-fly charting abilities. It can be installed in the usual fashion after it has been fetched from CPAN. Note that earlier versions that 0.99c used GIFs, which are no longer supported by the latest versions of GD.
4.1.5.7. Template Toolkit
When you install Template Toolkit, you'll get asked various questions about features to enable. The defaults are fine, except that it is recommended you use the high speed XS Stash of the Template Toolkit, in order to achieve best performance. However, there are known problems with XS Stash and Perl 5.005_02 and lower. If you wish to use these older versions of Perl, please use the regular stash.
4.1.6. HTTP Server
You have a freedom of choice here - Apache, Netscape or any other server on UNIX would do. You can run the web server on a different machine than MySQL, but need to adjust the MySQL "bugs" user permissions accordingly.
| We strongly recommend Apache as the web server to use. The Bugzilla Guide installation instructions, in general, assume you are using Apache. If you have got Bugzilla working using another webserver, please share your experiences with us. |
You'll want to make sure that your web server will run any file with the .cgi extension as a CGI and not just display it. If you're using Apache that means uncommenting the following line in the httpd.conf file:
AddHandler cgi-script .cgi |
With Apache you'll also want to make sure that within the httpd.conf file the line:
Options ExecCGI AllowOverride Limit |
| AllowOverride Limit allows the use of a Deny statement in the .htaccess file generated by checksetup.pl Users of older versions of Apache may find the above lines in the srm.conf and access.conf files, respecitvely. |
| There are important files and directories that should not be a served by the HTTP server - most files in the "data" and "shadow" directories and the "localconfig" file. You should configure your HTTP server to not serve these files. Failure to do so will expose critical passwords and other data. Please see .htaccess files and security for details on how to do this for Apache; the checksetup.pl script should create appropriate .htaccess files for you. |
4.1.7. Bugzilla
You should untar the Bugzilla files into a directory that you're willing to make writable by the default web server user (probably "nobody"). You may decide to put the files in the main web space for your web server or perhaps in /usr/local with a symbolic link in the web space that points to the Bugzilla directory.
| If you symlink the bugzilla directory into your Apache's HTML heirarchy, you may receive Forbidden errors unless you add the "FollowSymLinks" directive to the <Directory> entry for the HTML root in httpd.conf. |
Once all the files are in a web accessible directory, make that directory writable by your webserver's user. This is a temporary step until you run the post-install checksetup.pl script, which locks down your installation.
Lastly, you'll need to set up a symbolic link to /usr/bonsaitools/bin/perl for the correct location of your Perl executable (probably /usr/bin/perl). Otherwise you must hack all the .cgi files to change where they look for Perl. This can be done using the following Perl one-liner, but I suggest using the symlink approach to avoid upgrade hassles.
perl -pi -e
's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm
processmail syncshadowdb |
4.1.8. Setting Up the MySQL Database
After you've gotten all the software installed and working you're ready to start preparing the database for its life as the back end to a high quality bug tracker.
First, you'll want to fix MySQL permissions to allow access from Bugzilla. For the purpose of this Installation section, the Bugzilla username will be "bugs", and will have minimal permissions.
Begin by giving the MySQL root user a password. MySQL passwords are limited to 16 characters.
| bash# mysql -u root mysql |
| mysql> UPDATE user SET Password=PASSWORD('<new_password'>) WHERE user='root'; |
| mysql> FLUSH PRIVILEGES; |
Next, we use an SQL GRANT command to create a "bugs" user, and grant sufficient permissions for checksetup.pl, which we'll use later, to work its magic. This also restricts the "bugs" user to operations within a database called "bugs", and only allows the account to connect from "localhost". Modify it to reflect your setup if you will be connecting from another machine or as a different user.
Remember to set <bugs_password> to some unique password.
| mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX, ALTER,CREATE,DROP,REFERENCES ON bugs.* TO bugs@localhost IDENTIFIED BY '<bugs_password>'; |
| mysql> FLUSH PRIVILEGES; |
4.1.9. checksetup.pl
Next, run the magic checksetup.pl script. (Many thanks to Holger Schurig for writing this script!) This script is designed to make sure your MySQL database and other configuration options are consistent with the Bugzilla CGI files. It will make sure Bugzilla files and directories have reasonable permissions, set up the data directory, and create all the MySQL tables.
| bash# ./checksetup.pl |
This file contains a variety of settings you may need to tweak including how Bugzilla should connect to the MySQL database.
The connection settings include:
server's host: just use "localhost" if the MySQL server is local
database name: "bugs" if you're following these directions
MySQL username: "bugs" if you're following these directions
Password for the "bugs" MySQL account; (<bugs_password>) above
Once you are happy with the settings, su to the user your web server runs as, and re-run checksetup.pl. (Note: on some security-conscious systems, you may need to change the login shell for the webserver account before you can do this.) On this second run, it will create the database and an administrator account for which you will be prompted to provide information.
| The checksetup.pl script is designed so that you can run it at any time without causing harm. You should run it after any upgrade to Bugzilla. |
4.1.10. Securing MySQL
If you followed the installation instructions for setting up your "bugs" and "root" user in MySQL, much of this should not apply to you. If you are upgrading an existing installation of Bugzilla, you should pay close attention to this section.
Most MySQL installs have "interesting" default security parameters:
| mysqld defaults to running as root |
| it defaults to allowing external network connections |
| it has a known port number, and is easy to detect |
| it defaults to no passwords whatsoever |
| it defaults to allowing "File_Priv" |
This means anyone from anywhere on the internet can not only drop the database with one SQL command, and they can write as root to the system.
To see your permissions do:
| bash# mysql -u root -p |
| mysql> use mysql; |
| mysql> show tables; |
| mysql> select * from user; |
| mysql> select * from db; |
To fix the gaping holes:
| DELETE FROM user WHERE User=''; |
| UPDATE user SET Password=PASSWORD('new_password') WHERE user='root'; |
| FLUSH PRIVILEGES; |
If you're not running "mit-pthreads" you can use:
| GRANT USAGE ON *.* TO bugs@localhost; |
| GRANT ALL ON bugs.* TO bugs@localhost; |
| REVOKE DROP ON bugs.* FROM bugs@localhost; |
| FLUSH PRIVILEGES; |
With "mit-pthreads" you'll need to modify the "globals.pl" Mysql->Connect line to specify a specific host name instead of "localhost", and accept external connections:
| GRANT USAGE ON *.* TO bugs@bounce.hop.com; |
| GRANT ALL ON bugs.* TO bugs@bounce.hop.com; |
| REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com; |
| FLUSH PRIVILEGES; |
Consider also:
Turning off external networking with "--skip-networking", unless you have "mit-pthreads", in which case you can't. Without networking, MySQL connects with a Unix domain socket.
using the --user= option to mysqld to run it as an unprivileged user.
running MySQL in a chroot jail
running the httpd in a chroot jail
making sure the MySQL passwords are different from the OS passwords (MySQL "root" has nothing to do with system "root").
running MySQL on a separate untrusted machine
making backups ;-)
4.1.11. Configuring Bugzilla
You should run through the parameters on the Edit Parameters page (link in the footer) and set them all to appropriate values. They key parameters are documented in Section 5.1.