Bugzilla

This page contains details about how to install and configure a bugtracking site using the Bugzilla software. For a long time I have been maintaining my site using the Bugzilla package in Debian. However, in mid-2013 I switched to a manual installation because the Debian package had not been updated for a long time (nearly 3 years).

Debian packages

The Installation and Maintenance Guide from the official Bugzilla documentation has a list of packages that they say are Bugzilla's dependencies. I recommend to not blindly install all of the dependencies. Instead run ./checksetup.pl --check-modules (see "Installation" below) which will tell you which Perl modules are missing, and which Bugzilla features will be enabled by installing each module.

Note: The link above points to the Bugzilla 5.0 documentation - adjust the URL for the version of Bugzilla that you want to install.

References

Links to the documentation for different versions of Bugzilla can be found here: http://www.bugzilla.org/docs/. The documentation, which is titled "The Bugzilla Guide", is actually a collection of guides, such as the "User guide", the "Installation and Maintenance Guide" and the "Administration Guide".

Installation

The instructions here mostly reflect the stuff that can be found in the "Installation and Maintenance Guide" section of the Bugzilla documentation.

Get the source code via Git. Replace "X.X" with the 2-digit version number of the stable release of Bugzilla that you want (e.g. "5.0"). If there is a bugfix version you will get that version (e.g. 5.0.3).

cd /var/www
git clone --branch release-X.X-stable https://github.com/bugzilla/bugzilla

If you are doing this while logged in as root there is no need to change permissions. Otherwise you may need to run this command:

chown -R root:root /var/www/bugzilla

Run checksetup.pl to see whether any dependencies are missing, then install the corresponding Debian packages.

cd /var/www/bugzilla
./checksetup.pl --check-modules

Important: The output of checksetup.pl tells you for each missing dependency which Bugzilla feature is enabled by that dependency. If there is no Debian package for a dependency, checksetup.pl also provides you with a command line that lets you install the Perl module locally, i.e. just for this Bugzilla installation. Outstanding!

Configuration

PostgreSQL setup

Create a dedicated user role. The created user will not be a superuser (-S) and will not be able to create new users (-R) or create databases (-D).

sudo -u postgres createuser -U postgres -DRSP bugzilla

Create an empty database for which the owner (-O) is the user "bugzilla":

sudo -u postgres createdb -U postgres -O bugzilla bugzilla

Bugzilla configuration

The Bugzilla configuration is stored in this file:

localconfig

To create this file with a number of default settings, run checksetup.pl without parameters:

./checksetup.pl

Edit the file and change the following settings

$webservergroup = 'www-data';
$db_driver = 'pg';
$db_name = 'bugzilla';
$db_user = 'bugzilla';
$db_pass = 'secret';

To create and populate the database, and perform other setup tasks, run

./checksetup.pl

Web server setup

Place the following Virtual Host configuration in /etc/apache2/sites-available/bugs.herzbube.ch.conf:

# --------------------------------------------------------------------------------
# bugs.herzbube.ch
# --------------------------------------------------------------------------------
<VirtualHost *:80>
  ServerName bugs.herzbube.ch
  Redirect permanent "/" "https://bugs.herzbube.ch/"
</VirtualHost>

# --------------------------------------------------------------------------------
# SSL Host
# --------------------------------------------------------------------------------
<VirtualHost *:443>
  ServerName bugs.herzbube.ch
  ServerAdmin webmaster@herzbube.ch
  ErrorLog ${APACHE_LOG_DIR}/bugs.herzbube.ch/error.log
  CustomLog ${APACHE_LOG_DIR}/bugs.herzbube.ch/access.log combined

  DocumentRoot /var/www/bugzilla

  <Directory /var/www/bugzilla>
    Require all granted

    # The following directives were taken from the Bugzilla docs
    # --- BEGIN ---
    AddHandler cgi-script .cgi
    Options +ExecCGI +FollowSymLinks
    DirectoryIndex index.cgi index.html
    AllowOverride All
    # ---- END ----
  </Directory>

  Include conf-available/pelargir-herzbube.ch-vhosts-ssl.conf
</VirtualHost>

Notes:

Access to the DocumentRoot is allowed in the context of the vhost only
With AllowOverride All we trust Bugzilla's .htaccess to not contain any nonsense
The following settings on Bugzilla's administration pages need to be changed:
- urlbase
- sslbase
- cookiepath
Bugzilla thoughtfully provides a robots.txt

Web browser setup

Log in to the site as admin, then on the "Administration" page select "Parameters" and change the following parameters:

required settings
- maintainer = bugzilla@herzbube.ch
- urlbase = http://bugs.herzbube.ch/
- ssl_redirect = on
- sslbase = https://bugs.herzbube.ch/
general
- upgrade_notification = disabled
user authentication
- user_verify_class = LDAP
bug fields
- usetargetmilestone = on
- defaultpriority = p3
LDAP
- LDAPserver = ldapi:///
- LDAPbinddn = cn=readonly-users,ou=users,dc=herzbube,dc=ch:<secret>
- LDAPBaseDN = ou=users,dc=herzbube,dc=ch
- LDAPmailattribute = bugzillaEmail (default is "mail")

After parameters have been set up

Add products & components (e.g. product "AceXpander", components "GUI", "unace communication")

Some notes:

See section about LDAP below for details about how the login procedure works
New users are automatically part of the groups canconfirm and editbugs because these groups have ".*" as the so-called "User RegExp" (i.e. all users match)
New users therefore automatically inherit the appropriate rights from these groups

LDAP

Login procedure

In LDAP mode, when a user tries to login, Bugzilla does the following:

User has entered a user name and a password on the login form
Bugzilla binds to the directory using the LDAPbinddn parameter (or it binds anonymously if the parameter is not set, but my directory does not allow this)
After the initial bind, Bugzilla tries to match the user name entered on the login form to an LDAP entry
The LDAP entry to match is searched below LDAPBaseDN
To match, an entry must have an attribute named LDAPuidattribute whose value is equal to the user name
If a matching entry (M) is found, Bugzilla now tries to bind a second time
It uses the matching entry (M) to bind, in conjunction with the password entered on the login form
If successful, this constitutes a successful login
Bugzilla now tries to extract an email address that it should use as the user name for all of the subsequent actions during this session
The email address is extracted from the attribute named LDAPmailattribute within the matching entry (M)

Schema customizations to support Bugzilla

Originally, my LDAP entries below ou=users were simple entries with a structural object class "organizationalRole" and an auxiliary object class "simpleSecurityObject". These two object classes did not support either the "uid" or any "mail" attribute.

Solution for "uid":

LDAPuidattribute could have been set to "cn"
Or even better, LDAP entries could have been augmented with the additional auxiliary object class "uidObject"

Solution for "mail":

Create a new auxiliary object class "bugzillaAccount"
Add attribute "bugzillaEmail" to this class and set LDAPmailattribute to this attribute name

Actual LDAP configuration

Is done via web browser in editparams.cgi. Details are listed in the corresponding section further up.

Upgrade

General upgrade procedure

TODO: Update this section. I no longer use a version-suffixed database, which means the upgrade will happen in-place. Also the codebase can now be upgraded via git. Read the docs.

Log in as admin on the existing installation and click the "Sanity Check" link in the admin page. Check that no errors are displayed. If there are, fix them.
Log out
Read the release notes to get familiar with the stuff that has changed in the last releases and that might be important for the upgrade process
Download the Bugzilla tarball to

/var/archive/bugzilla

Extract the tar ball to

/var/www/bugzilla-<version>

Adjust permissions

chown -R root:root bugzilla-<version>

In phpMyAdmin, give the MySQL database user bugzilla permissions for the database that we are going to create. The bugzilla user is expected to already exist. This SQL query can be used to grant the necessary privileges:

grant all privileges on bugzilla<version>.* to bugzilla@localhost;

Backup the current database

mysqldump --add-drop-table -u bugzilla -p bugzilla<oldversion> >/tmp/bugzilla.mysqldump

Create the new database by restoring the backed up data

mysql -u bugzilla -p bugzilla<newversion> </tmp/bugzilla.mysqldump

Run checksetup.pl to see whether any dependencies are missing. If there are, install the corresponding Debian packages.

./checksetup.pl --check-modules

Run checksetup.pl without parameters to create the localconfig file

./checksetup.pl

Edit localconfig so that its settings point to the newly created database.
Diff the old and the new version of localconfig to make sure that no settings from the old configuration were forgotten.

diff ../bugzilla<oldversion>/localconfig localconfig

Copy the data folder from the old Bugzilla installation

cp -Rp ../bugzilla<oldversion>/data .

Run checksetup.pl a final time to perform the database upgrade

./checksetup.pl

Update the symlink to point to the new installation

rm /var/www/bugzilla
ln -s /var/www/bugzilla<newversion> /var/www/bugzilla

Log in as admin and click the "Sanity Check" link in the admin page. Check that no errors are displayed. If there are, fix them.

2.20 -> 4.4.0

I performed several upgrades between Bugzilla 2.20 and 4.4.0. I decided to remove this ancient information to clean up this wiki page a little. If you are desperate to see this old stuff, check out older revisions of this page.

4.4.0 -> 5.0.3

I performed this upgrade on pelargir's reincarnation as a Virtual Server. I performed the upgrade in two steps:

First, follow the steps in this guide to migrate from a tarball setup to a setup based on Git
Afterwards, follow the steps in this guide to upgrade the Git-based installation from 4.4 to 5.0.3

Step 1: Migrate from tarball setup to Git-based setup. A noticeable change from my previous setup is that I no longer use a database with a version suffix.

Run a few commands

# Prepare Git-based folder
cd /var/www
git clone https://github.com/bugzilla/bugzilla bugzilla
cd bugzilla
git checkout release-4.4

# Copy across data
cd /path/to/bugzilla-4.4
cp -Rp lib/* lib/.htaccess /var/www/bugzilla/lib
cp -Rp data /var/www/bugzilla/data
cp -Rp localconfig /var/www/bugzilla
# I haven't patched the source code, nor do I have custom templates or extensions, so I can skip all steps pertaining to these

# Restore database
mysql -u root -p -e "create database bugzilla;"
mysql -u root -p -e "grant all privileges on bugzilla.* to bugzilla@localhost identified by 'secret';"
mysql -u root -p bugzilla  </path/to/backup/bugzilla44.sql

cd /var/www/bugzilla
# Change configuration to match new MySQL server setup
# - Set db_name to "bugzilla" (previously "bugzilla44")
# - Set db_pass to correct password
vi localconfig
# Change configuration to match new LDAP server setup
# - Set LDAPserver to "ldapi:///" (previously "localhost")
# - Change LDAPbinddn to use correct password
vi data/params

# Run checksetup.pl repeatedly to find missing dependencies. Install
# dependencies via <code>aptitude</code>.
./checksetup.pl --check-modules

# Install a missing dependency. Debian jessie now has Email::Sender
# which replaces the obsolete Email::Send, so we can't use a Debian
# package. Unfortunately, manually installing a Perl module like we
# do here requires that we install "gcc" and "make" on the system.
# Running the following command does an unholy shitload of things
# (typical Perl "magick") 
/usr/bin/perl install-module.pl Email::Send

# checksetup.pl wants to convert MySQL tables to UTF-8. To make sure
# that no data is lost, checksetup.pl recommends to first run
# contrib/recode.pl, which will convert data inside the tables to
# UTF-8. This is not necessary in my case because I know that my
# data already is in UTF-8 (can be checked by looking at the database
# dump I restored further up).
./checksetup.pl

# Now log in to the website with user "admin". If this works the LDAP
# setup is correct. Run the sanity check.

Step 2: Upgrade from 4.4 to 5.0.3

The upgrade docs suggest to run the sanity check as the first thing before attempting the upgrade. I already completed this at the end of the migration step 1.
The release notes for 5.0.3 do not reveal any changes that might be relevant for the upgrade
Update to the newest source code, then run checksetup.pl

cd /var/www/bugzilla
git checkout release-5.0-stable
./checksetup.pl

checksetup.pl notifies me that the following variables in localconfig have changed

db_mysql_ssl_ca_file, db_mysql_ssl_ca_path, db_mysql_ssl_client_cert,
db_mysql_ssl_client_key

Since I don't need to set those, I simply run checksetup.pl again. This performs the database scheme upgrade and all the filesystem changes necessary to bring the installation to 5.0.3. Notable changes are
- Obsolete parameters are removed from ./data/params and moved to ./data/old-params.txt
- ./data/params is converted into ./data/params.json

Fixes after the upgrade:

There is some obsolete stuff in the lib subfolder that can be moved away

cd /var/www/bugzilla
mkdir lib.old
mv lib/CGI lib/CGI.pm lib/Email lib/man lib/Return lib.old

The website is accessible but completely without CSS. The reason is that all the .htaccess files in the installation are set up incorrectly, they all use outdated "deny from all" permission declarations. For instance:

root@pelargir:/var/www/bugzilla# cat template/.htaccess 
# nothing in this directory is retrievable unless overridden by an .htaccess
# in a subdirectory
deny from all

These all need to be fixed to use the new "Require" directive (necessary since Apache 2.4). This is how the same file looks like after the fix.

root@pelargir:/var/www/bugzilla# cat template/.htaccess 
# nothing in this directory is retrievable unless overridden by an .htaccess
# in a subdirectory
<IfModule mod_version.c>
  <IfVersion < 2.4>
    Deny from all
  </IfVersion>
  <IfVersion >= 2.4>
    Require all denied
  </IfVersion>
</IfModule>
<IfModule !mod_version.c>
  Deny from all
</IfModule>

Bugzilla

Contents

Debian packages

References

Installation

Configuration

PostgreSQL setup

Bugzilla configuration

Web server setup

Web browser setup

LDAP

Login procedure

Schema customizations to support Bugzilla

Actual LDAP configuration

Upgrade

General upgrade procedure

2.20 -> 4.4.0

4.4.0 -> 5.0.3

Navigation menu

Bugzilla

Debian packages

References

Installation

Configuration

PostgreSQL setup

Bugzilla configuration

Web server setup

Web browser setup

LDAP

Login procedure

Schema customizations to support Bugzilla

Actual LDAP configuration

Upgrade

General upgrade procedure

2.20 -> 4.4.0

4.4.0 -> 5.0.3

Navigation menu

Search