Gentoo Wiki




Let's say, for the sake of argument, that you have a masochistic need to give yourself some pain, so you decide to install Bugzilla. This document tells you how to go about it.

This document requires that you have some knowledge of MySQL and have already set up the root password for MySQL and secured it. If you have not done so please read this page: HOWTO MySQL.

This document also assumes that you've set up apache and are already running some content off the apache server. Therefore, the bugzilla install will need to work as a vhost website served by the same apache process as the content you're already running.

We're going to be setting up bugzilla to run on an alternate HTTP port. This document was originally written for the following versions of apache and bugzilla:

It has been extended for the following versions of lighttpd and bugzilla:

We'll be configuring bugzilla according to the following server details. Please replace all occurrences of the below example settings to be as per your particular setup/requirement.

Assumptions for Setup

Note that if you want bugzilla to be served off the standard HTTP port 80, then simply replace 8666 with 80 where indicated in this document.


WARNING: Do not ever try to install perl with USE=threads or ithreads, for you are doomed to failure. Apache, mod_perl, perl, and libperl all need to be using threads, or no threads. If you ever want to use mod_perl, you must go the non-threaded route. This is just a warning as I spent a number of hours learning this information. Maybe I'll try again when perl 6 comes out...

For Bugzilla, you'll require apache and mysql as well as a bunch of perl modules. Since I wanted to run bugzilla in a virtual host environment, I also used the vhosts use variable.

echo "www-apps/bugzilla apache2 mysql vhosts" >> /etc/portage/package.use
emerge -uDav www-apps/bugzilla www-apache/mod_perl

Be careful, however, since the above emerge command will update whatever needs updating. If you've spend long tedious hours resolving versioning problems in your emerges, then simply use the following command:

emerge www-apps/bugzilla www-apache/mod_perl

In a pinch, if mod_perl gives you trouble (like on amd64), it's sufficient to just emerge bugzilla.

(With lighttpd I just did emerge bugzilla...)

Configuring your webserver for Bugzilla

After the above, the emerge will inform you that since you used the "vhosts" option, webapp-config was not automatically run. This is ok, you'll be doing it yourself in a bit. Now, you need to create a vhosts file to tell the webserver (apache or lighttpd) that you want to run bugzilla on the same server, but from a separate port, say 8666 (For the remainder of this document, we'll assume that you want to run bugzilla off HTTP port 8666). You'll also need to modify the httpd.conf file of apache2, or lighttpd.conf file of lighttpd, to tell it to listen on port 8666. This can be done as below:

Modifying your webserver to listen on port 8666

Apache: httpd.conf
File: /etc/apache2/httpd.conf

Edit the file /etc/apache2/httpd.conf in an editor of your choice. If httpd.conf is not at the aforementioned location, hunt down the correct location (maybe try emerge slocate;updatedb;locate httpd.conf) and edit the file there.

Find the line in the file which says

Listen 80

Underneath the above, add a line that says:

Listen 8666
  • Note: If you want bugzilla to run on standard port 80, you may skip the above step.

Now, find the lines which contain the <Directory> ... </Directory> specifications, and add a new directory specification as follows:

#### Directory entry added by The Beast in Black on 3-Aug-2006
#    for bugzilla. God save us all.
<Directory /var/www/bugzilla>
  AddHandler cgi-script .cgi
  Options +Indexes +ExecCGI +FollowSymLinks
  DirectoryIndex index.cgi
  AllowOverride Limit

Note that setting AllowOverride Limit may cause an apache error with the the .htaccess file included with bugzilla. Either rename the .htaccess file or else grant larger AllowOverride privileges

Ensure that the file contains a line which allows vhost configuration files to be read from some directory. In my case, the relevant line reads as follows:

# Gentoo VHosts
# For Gentoo we include External Virtual Hosts Files.
# Please see vhosts.d/00_default_vhost.conf for the default virtual host.
Include /etc/apache2/vhosts.d/*.conf
Lighttpd: lighttpd.conf
File: /etc/lighttpd/lighttpd.conf

Edit the file /etc/lighttpd/lighthttpd.conf in an editor of your choice. If lighttpd.conf is not at the aforementioned location, hunt down the correct location (maybe try emerge slocate;updatedb;locate lighttpd.conf) and edit the file there.

We want to extend the lighttpd configuration to listen to another port and interface. With lighttpd conditionals, this is a breeze. But, in order to keep your configuration organised, you had better create a new, bugzilla-site specific lighttpd include file.

Just add the following line to your lighttpd.conf:

include "bugzilla.conf"

Now create a new file, /etc/lighttpd/bugzilla.conf in your editor. The contents should be as follows. The main feature of lighttpd's flexible configuration is the 'conditional', which you can see wraps our first few bugzilla-specific configuration options...

$SERVER["socket"] == "" {
 server.modules += ( "mod_accesslog", "mod_dirlisting" )
 server.document-root = "/var/www/bugzilla/htdocs/"
 server.errorlog = "/var/www/bugzilla/logs/errors.log"
 accesslog.filename = "/var/www/bugzilla/logs/access.log"
 server.follow-symlink = "enable"
 server.indexfiles = ( "index.cgi" ) 

Now you should choose whether you want to use fastcgi or cgi. Since fastcgi is faster, I'd try with fastcgi, but since I can't find any example fastcgi + perl configurations, I am sticking with CGI.

For CGI, add the following lines inside the conditional.

 server.modules += ( "mod_cgi" )
 cgi.assign = ( ".pl" => "/usr/bin/perl" )


Creating/Modifying your vhosts config file for bugzilla

The above means that I can put my vhosts configuration files in the /etc/apache2/vhosts.d directory. Armed with this information, we can move right on to creating the vhosts file. We'll call it bugzilla-vhost.conf.

File: /etc/apache2/vhosts.d/bugzilla-vhost.conf

Create a new file called bugzilla-vhost.conf in the /etc/apache2/vhosts.d directory (or wherever httpd.conf says the vhosts config files ought to be)

vim /etc/apache2/vhosts.d/bugzilla-vhost.conf

Let's assume that your bugzilla/apache box has an IP address of Remember that we want our bugzilla to run on port 8666. Now, with this in mind, add the following text to the bugzilla-vhost.conf file you opened in the previous step

  ServerName ""
  DocumentRoot "/var/www/bugzilla/htdocs"

      <Directory "/var/www/bugzilla/htdocs">
          AddHandler cgi-script cgi
          Options +Indexes +ExecCGI +FollowSymLinks
          DirectoryIndex index.cgi
          AllowOverride All
          Order Allow,Deny
          Allow from All

It's important that the servername parameter be the FQDN of your server. For instance, if your server's DNS name is myserver and the domain name (got from the domainname command) is, then the FQDN of your server would be

  • Note that if you wanted bugzilla to run on standard port 80, then you would replace 8666 with 80 in the above bugzilla-vhost.conf file.
Save the bugzilla-vhost.conf file and exit the editor.

You don't need to worry about creating the directory structure for your new virtual host since the webapp-config command (down below) will do that for you automatically.

Using webapp-config to install bugzilla

Now, you're ready to use webapp-config to actually install the web-enabled bugzilla directories. Use the following command:

webapp-config -I -h bugzilla bugzilla 2.18.5

The explanation of this is as follows:

webapp-config -I -h bugzilla bugzilla 2.18.5
               ^  ^    ^        ^       ^
               |  |    |        |       +--- Application Version Number
               |  |    |        +----------- Application Name
               |  +----+-------------------- Specifies we're using a vhost named 'bugzilla'
               +---------------------------- Install

After this, webapp-config might whine that you're installing it to the website root, and is this what you really want to do. That's alright, this is exactly what you want to do. If webapp-config has run successfully, it should spit out a message resembling this:

* You may be installing into the website's root directory.
* Is this what you meant to do?
*   Creating required directories
*   Linking in required files
*     This can take several minutes for larger apps
*   Files and directories installed

Preliminary setup : Running

After the above, you need to perform some preliminary bugzilla setup, as follows.

chmod u+x ./
/usr/bin/perl5.8.8 -MCPAN -e 'install "DBD::mysql"' 

to install it, but installing with this method doesn't "stick", then install the package with emerge instead, using

emerge -v DBD-mysql
File: /var/www/bugzilla/htdocs/localconfig

The only mandatory change you absolutely need to make is to the line that reads:

$db_pass = '';

The above is the line which specifies the password for the "bugs" user for the mysql bugzilla database. Change the above blank password line to contain a password of your choice. For instance, if you wanted the "bugs" database user to have the password "246biteme135", you'd change the above line as follows:

$db_pass = '246biteme135';

You may change the other settings in this file as per your requirement.

* Install completed - success

Pay attention to the line which says Bugzilla has been installed into. We'll call this location the bugzilla install location. If necessary, edit your bugzilla-vhost.conf file, created in the previous section, to point to the correct bugzilla install location.

Note: If you try to install bugzilla on Apache in directory instead of vhost, you may see the Error 500 page. Don't panic, check apache error log, and if error looks like "Can't locate in @INC (...)" just add section about bugzilla directory to PerlSwitches
PerlSwitches -I/var/www/localhost/htdocs/bugzilla
into your apache mod_perl configuration (usualy in /etc/apache2/modules.d/XX_mod_perl.conf).

Tweaking MySQL for Bugzilla

Now, you need to make some mysql configuration changes to allow bugzilla to function properly. Find the mysql config file my.cnf. This is usually present at /etc/mysql/my.cnf.

File: /etc/mysql/my.cnf

Note: the following is appended to the [mysqld] section of my.conf

# Allow packets up to 1M

# Allow small words in full-text indexes

Restart MySQL:

/etc/init.d/mysql restart

Next we need to create the bugs user so that bugzilla can log in and create the database. Enter the mysql interpreter by running the following command:

mysql -u root -p

and enter in your MySQL root password when prompted. Execute the following SQL statements in the mysql interpreter.

          TO bugs@localhost IDENTIFIED BY '<bugzilla password used above>';


After the above, run again. If everything goes Ok you should see the table creation happening. If you get a nasty message like one below, you'll need to doublecheck the localhost file lines up with MySQL for your system, and that the passwords match for the bugs user.

DBI connect(';localhost;3306','bugs',...) failed: Access denied for 
user 'bugs'@'localhost' (using password: YES) at ./ line 1461
Can't connect to the mysql database. Is the database installed and
up and running?  Do you have the correct username and password selected in

Once you are prompted to create an administrator, the database should now be complete. Go ahead and fill out the administrator account with your information, preferably using a specific email account (EG: bugzilla-admin@localhost).

Re-enter MySQL and modify the attachments table to give MySQL a heads up on how the table is going to be used. From the mysql interpreter, type:

USE bugs;

ALTER TABLE attachments AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;

Re-configuring Bugzilla

After this, run again. You may run it as follows:

tux ~ # cd /var/www/bugzilla/htdocs
tux htdocs # ./

If it did not prompt you to enter the bugzilla administrator details when it ran earlier, it may prompt you for these details this time around. Enter the details as relevant to your organization. Now, it should show some minimal message indicating that it could connect to the database and create some backup data. If not, keep re-running, fixing problems as you go, until it does not complain about anything anymore.

If all has gone well, your output should look similar to this...

tux htdocs # ./

Checking perl modules ...
Checking for       AppConfig (v1.52)   ok: found v1.56
Checking for             CGI (v2.93)   ok: found v3.05
Checking for    Data::Dumper (any)     ok: found v2.121_02
Checking for    Date::Format (v2.21)   ok: found v2.22
Checking for             DBI (v1.36)   ok: found v1.46
Checking for      DBD::mysql (v2.1010) ok: found v2.9003
Checking for      File::Spec (v0.82)   ok: found v3.06
Checking for      File::Temp (any)     ok: found v0.14
Checking for        Template (v2.08)   ok: found v2.14
Checking for      Text::Wrap (v2001.0131) ok: found v2001.0929

The following Perl modules are optional:
Checking for              GD (v1.20)   ok: found v2.18
Checking for     Chart::Base (v1.0)    ok: found v2.3
Checking for     XML::Parser (any)     ok: found v2.34
Checking for       GD::Graph (any)     ok: found v1.43
Checking for GD::Text::Align (any)     ok: found v1.18
Checking for     PatchReader (v0.9.4)  ok: found v0.9.4

Checking user setup ...
Removing existing compiled templates ...
Precompiling templates ...
Checking for    MySQL Server (v3.23.41) ok: found v4.0.24

Populating duplicates table...

Run this command a couple of more times, just to make sure it's complete.

Testing your bugzilla installation

Assuming the installation went well, it's now time to test whether apache can see your brand spanking new bugzilla setup. Perform the following operations:

/etc/init.d/apache2 stop
/etc/init.d/apache2 start
/usr/sbin/apache2 -S

Note that on some apache installations the location of the apache2 executable might be different. Also, it might possibly be called httpd instead of apache2. Change the above command as applicable to your installation.

On running apache with the "-S" directive, you should see something resembling the following text. If you do, it means that your vhosts configuration is correct (at least, syntactically correct). If not, tweak your vhost config file /etc/apache2/vhosts.d/bugzilla-vhost.conf until /usr/sbin/apache2 -S does not bork anymore, and shows something resembling the following.

[warn] NameVirtualHost *:80 has no VirtualHosts
VirtualHost configuration:       is a NameVirtualHost
default server (/etc/apache2/vhosts.d/bugzilla-vhost.conf:31)
port 8666 namevhost (/etc/apache2/vhosts.d/bugzilla-vhost.conf:31)
Syntax OK

We now need to check whether all our hard work upto this point has borne fruit or not. In this document, we've set up everything assuming that we're going to be accessing the bugzilla web pages from the http://myserver:8666 URL. So fire up your browser, and point it to the following address:


If you see the bugzilla main page, you're good to go. If not, you've goofed something up. Feel free to cry for a while, then troubleshoot your installation. Don't ask me how, go check the Internet. A decent place to start is

Assuming that all went well (lucky you!), and you see the bugzilla main page, log in with the administrator account you defined in the last run. You should go through the parameters on the Edit Parameters page (see link in the bugzilla page footer, after logging in as the administrator) and see if there are any you wish to change. They key parameters you should certainly alter are maintainer and urlbase; you may also want to alter cookiepath or requirelogin.

Securing your installation

The initial installation is quite unsecure, and it's probably a good idea to secure your bugzilla installation using .htaccess files and a .htpasswd file to require users to authenticate themselves before they can even get to the bugzilla main page.

Securing the web directories

NOTE: If you require that web users land directly on your Bugzilla main page without first having to authenticate themselves using a separate login and password, please skip this section.

Set up .htpasswd file: A .htpasswd file requires users to authenticate themselves before they even see the main bugzilla page. The apache htpasswd documentation is at

The htpasswd2 command (just htpasswd on some systems) can be used to generate the .htpasswd file. This has be done on a per-user basis. See the man pages for the htpasswd command on how to create the file initially. In our case, we generate a file called bugzilla.htpasswd and put it in the /etc/apache2 directory. To add a user (say, "joeUser") to this file, the following command will suffice:

htpasswd2 /etc/apache2/bugzilla.htpasswd joeUser

After creating /etc/apache2/bugzilla.htpasswd, we'll need to change the .htaccess file in the bugzilla installation location (in our case, this is /var/www/bugzilla/htdocs/.htaccess) to use the htpasswd file we just created. Add the following text to the end of the /var/www/bugzilla/htdocs/.htaccess file:

File: /var/www/bugzilla/htdocs/.htaccess
AuthType Basic
AuthName "Bugzilla"
AuthUserFile /etc/apache2/bugzilla.htpasswd
Require valid-user

Securing MySQL

The following information has been taken from

bash$ mysql mysql
mysql> UPDATE user SET password = password('new_password') WHERE user = 'root';
mysql> quit
bash$ mysql -u root -p mysql          
Enter Password: new_password
mysql> DELETE FROM user WHERE user = '';
File: /etc/mysql/my.cnf
# Prevent network access to MySQL.

Securing Apache

Please refer to

Appendix #1 - Bugzilla upgrade using webapp-config (sample upgrade from 2.18.3 to 2.20rc2)

echo "~www-apps/bugzilla-2.20" >> /etc/portage/package.keywords
emerge www-apps/bugzilla

No need for backups yet, the emerge only installs a master copy in /usr/share/webapps for example:


This master copy can then be copied to the various vhosts on the machine using hardlinks if on the same file system or copied to each vhosts webapp-dir

Ok, now you can backup....

You might get this irritating error message:

*** Fatal error: The following does not work on previous installations, please run in /var/www/localhost/htdocs/bugzilla

Go to /var/www/localhost/htdocs/bugzilla and chmod +x and run it

you will get the following:

The following settings in your localconfig file are no longer used:
  @severities, @priorities, @opsys, @platforms

then backup your localconfig file and remove those sections

running will show you a missing file ->

-- 08:37, 26 September 2005 (GMT)

Retrieved from ""

Last modified: Thu, 02 Oct 2008 10:56:00 +0000 Hits: 29,425