Back to Free Stuff

Obsolete: creating a bug-tracking system using VMware ESXi, FreeBSD, MySQL, Apache and Bugzilla

As of 2014, this article's almost completely obsolete.
Please see this guide for a much newer version.

Author:  Robroy Gregg
Revision:  A

This cookbook-style, step-by-step guide covers:

Versions Covered and Things you'll Need
 Downloading FreeBSD and making an ESXi VM
 Installing FreeBSD
 Installing Apache, MySQL, and Bugzilla
 Configuring Apache for Bugzilla
 Configuring MySQL for Bugzilla
 Configuring Bugzilla for MySQL
 Basic Bugzilla Setup
 Additional Suggestions


Software Versions and Things you'll Need

This guide's based on these software versions—this is all free software:

Things You'll Need:

  • A VMware ESXi server (ESXi's a free VMware product)
  • A Windows computer running the VMware vSphere Client (can be an ESXi VM)
  • A Unix-like computer or suitable Windows software for checking an MD5 checksum (can be an ESXi VM)
  • An IP address and hostname allocated for the FreeBSD VM
  • The e-mail address of the person you'll designate to manage your Bugzilla system
  • A total of four passwords made up for the FreeBSD and MySQL root accounts, the MySQL Bugzilla account, and the Bugzilla administrator account


Downloading FreeBSD and making an ESXi VM

  1. Begin downloading the FreeBSD 8.0-RELEASE ISO image from here:
    ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/ISO-IMAGES/8.0/8.0-RELEASE-amd64-disc1.iso
  2. Download the ISO image checksum file from here:
    ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/ISO-IMAGES/8.0/CHECKSUM.MD5
  3. While the downloads take place, start the VMware vSphere Client and log in to your VMware ESXi server.

  4. Create an ESXi VM for FreeBSD by following these steps:

    1. In the left-hand pane, right-click on the ESXi host and select "New Virtual Machine..."

    2. Choose a "Custom" configuration.

    3. Name the VM; I'm naming mine Ocean.

    4. Select a datastore with at least 10G of free space.

    5. Choose Virtual Machine Version 7.

    6. Under "Guest Operating System," click "Other."  Then select "FreeBSD (64-bit)" from the select-box entitled, "Version."

    7. For small installations (perhaps up to 25 simultaneous users), allocate one vCPU to the VM.  If allocating additional vCPUs, keep the number of vCPUs to no more than half the number of physical CPU cores; that means you should only increase the vCPU count above 1 if you have at least four physical CPU cores in your ESXi server.

    8. For small installations you can leave the RAM size at 256MB.

    9. Allocate one virtual NIC.  Be sure to connect it to a vSwitch with an uplink to a network that your Bugzilla clients can reach.  Leave the virtual NIC type set at E1000.

    10. Leave the SCSI controller type set to LSI Logic Parallel.

    11. Create a new virtual disk.  For small installations with a you can probably leave the virtual disk size at 8GB.   If you have the storage space and think your Bugzilla content will grow large, make the virtual disk 100GB or larger.

    12. Accept virtual disk addressing at SCSI bus 0, target 0 (the default).

Installing FreeBSD

  1. If your FreeBSD ISO image download hasn't completed yet, wait for it.  Once that's complete, get its checksum value like this (note that your MD5 checksum utility might be called either md5 or md5sum):
    unix$ md5 8.0-RELEASE-amd64-disc1.iso
    MD5 (8.0-RELEASE-amd64-disc1.iso) = eba84fbd08133cbc8c9ed67be27ee0c8
  2. Get the official MD5 value from the CHECKSUM.MD5 file, then compare them.  Consider using cut-and-paste and the shell to compare them instead of "eye-balling" them.
    unix$ grep 8.0-RELEASE-amd64-disc1.iso CHECKSUM.MD5
    MD5 (8.0-RELEASE-amd64-disc1.iso) = eba84fbd08133cbc8c9ed67be27ee0c8
    unix$ if test "eba84fbd08133cbc8c9ed67be27ee0c8" = "eba84fbd08133cbc8c9ed67be27ee0c8"; then
    > echo "They Match."; fi
    They Match.
    If the shell doesn't print "They Match," and the syntax was entered exactly as shown above, you may want to try downloading the ISO image again—it could have been corrupted during transfer.

  3. Using the VMware vSphere Client, transfer the FreeBSD ISO image to the ESXi VMFS volume.

    1. Ensure that the FreeBSD ISO image is accessible to the Windows computer running the vSphere Client.

    2. With your ESXi host selected in the left-hand pane, select the "Configuration" tab in the right-hand pane, then click on "Storage" under "Hardware."

    3. Right-click on a VMFS volume and select "Browse Datastore..."  A dialog box will appear.

    4. In the top of the dialog box, you'll see an icon that looks like a stack of grey disk platters with a green arrow pointing upwards.  That's the upload icon.  Click on it, then select "Upload File..."

    5. Browse to the FreeBSD ISO image in the "Upload Items" dialog box and click on "Open."  Wait for it to transfer to the VMFS volume.  Close the Datastore Browser when the upload's complete.

  4. Associate the FreeBSD ISO image with your VM's virtual CD drive.

    1. Right-click on the VM, then choose "Edit Settings."

    2. Highlight "CD/DVD Drive 1," then on the right, click on "Datastore ISO File," and "Browse..."

    3. Open the VMFS volume that you uploaded the FreeBSD ISO image to, highlight it, and click "OK."

    4. Returning to the "Virtual Machine Properties" dialog box, find the "Device Status" area in the upper-right corner.   Check the "Connect at power on" checkbox, then click "OK."

  5. Returning to the main vSphere Client window, right-click on the VM and choose "Open Console."  Power up the VM.

  6. The VM should automatically boot from the FreeBSD ISO image.   Hit Enter or wait for the default boot option to take effect.

  7. Choose your localization settings.  At the FreeBSD sysinstall main menu, select the "Custom" install method.

  8. Choose the "Partition" option.  You'll see the partition table content stored inside of your virtual disk.  Hit "c" (it's a "hot key") to create a "slice."  In this context, a "slice" is synonymous with a PC hard disk primary partition.

  9. When prompted for the size of the slice, hit <Enter> to accept the default.  This will fill the entire virtual disk with a single partition for FreeBSD.  Accept the default "165" partition ID.

  10. Use the UP arrow to highlight the "da0s1" slice, then hit the "s" key to mark it as a bootable partition.  You should see an "A" appear on the right, in the "Flags" column.

  11. Hit "q" to quit the slice editor.  You'll be prompted to install a boot sector-resident boot program (similar to GRUB).  Accept the default "Standard" to leave out a boot program.  This will write a standard boot sector containing code that will redirect the VM to the first sector of the "slice."

  12. Returning to the "Choose Custom Installation Options" screen, highlight "Label" and hit <Enter>.  This will start the FreeBSD disklabel editor, which allows you to define separate areas within the slice.

  13. Hit "c" to create the first area.  The first area will contain the root filesystem.  This filesystem contains only FreeBSD operating system files (it's not where the Bugzilla database will live), so 1GB is usually enough space.  Enter "1G" and hit <Enter>.

  14. Leave "A file system" highlighted and hit <Enter>.

  15. Enter "/" as the mount point; this is the root filesystem.

  16. Hit "c" to create the next area.  This will be the swap area, which should be at least as large as the RAM size allocated to the VM.  Since my VM has 256MB of RAM allocated to it, I'll make a 600MB swap area.  This makes it convenient to allocate more RAM to the VM in the future without needing to increase the swap area size.  Enter "600M" for 600 Megabytes and hit <Enter>.

  17. Choose "A swap partition," then hit <Enter>.

  18. If at any time the disklabel editor should highlight the swap area instead of the slice, use the UP arrow key to move the highlighted item back to the slice (at the very top of the screen).  Sometimes it gets a "mind of its own."

  19. Hit "c" to create the next area.  This area will be the /usr filesystem, which will contain the FreeBSD Ports tree and other application files.  I'll make this 2GB by entering, "2G," then hitting <Enter>.

  20. Choose "A file system," then enter "/usr" as the mount point and hit <Enter>.

  21. Hit "c" to create the final area, which will contain the "/var" filesystem, which is used for the MySQL database.  This time, at the sizing screen, hit <Enter> to accept the entire number that's pre-entered in the entry box.  This will make the "/var" filesystem fill all of the remaining space in your slice.

  22. Choose "A file system," enter "/var" as the mount point, and hit <Enter>.

  23. Hit "q" to quit the disklabel editor.

  24. Returning to the "Choose Custom Installation Options" screen, highlight the "Distributions" selection and hit <Enter>.

  25. Highlight the "User" distribution and hit .

  26. You'll see the FreeBSD documentation install screen.  You can skip installing the doc, since The FreeBSD Handbook and Google are available for that purpose.  Hit <Enter> to install no doc.

  27. You'll be prompted to install the FreeBSD ports collection. We'll add everything from packages so this isn't necessary.  Highlight "No" and hit <Enter>.

  28. Returning to the "Choose Distributions" screen, use the UP arrow to highlight "Exit," then hit <Enter>.

  29. Returning to the "Choose Custom Installation Options" screen, highlight "Commit" and hit <Enter>.  Accept the default media source (FreeBSD CD/DVD), and hit <Enter> at the "Last Chance" screen.

  30. The FreeBSD installation may take a few minutes.

  31. You'll be prompted with a screen asking you if you'd like to visit the general configuration menu again.  Highlight "Yes" and hit <Enter> to return to the menu.

  32. Highlight "Root Password" and use it to set your root password.

  33. Highlight "Time Zone" and use it to select the correct time zone.  Note that FreeBSD needs to be set to the correct time for the timestamps to show up correctly in Bugzilla.

  34. Configure the FreeBSD TCP/IP settings thusly:

    1. Highlight "Networking" and hit <Enter>.
    2. Highlight "Interfaces" and hit <Enter>.
    3. Hit <Enter> to configure em0 (the virtual NIC).
    4. Accept the default IPv6 setting, which is "No."
    5. Accept the default DHCP setting, which is "No."
    6. Fill in your VM's hostname, domain name, gateway, name server, IP address, and netmask settings.  Use to move between the fields.
    7. When prompted to bring the em0 interface up, leave "No" highlighted and hit <Enter>.
    8. Highlight "Exit" and hit <Enter>.

  35. Exit the sysinstall (the FreeBSD installer) by exiting out of two menu levels, then highlighting "Exit Install" and hitting <Enter>.

  36. Agree to reboot.  Your FreeBSD VM will now boot from the installation!

Installing Apache, MySQL, and Bugzilla

  1. Once FreeBSD has booted, log in as root.

  2. Install Apache using pkg_add like this; note that networking must be completely functional for "pkg_add -r" to work.
    FreeBSD# pkg_add -r apache
  3. Add this line to the end of /etc/rc.conf to ensure Apache starts automatically with FreeBSD.
    apache_enable="YES"
  4. Install the MySQL server, client, and scripts packages.
    FreeBSD# pkg_add -r mysql50-client mysql50-server mysql50-scripts
  5. Add this line to /etc/rc.local to ensure MySQL starts automatically with FreeBSD.
    /usr/local/share/mysql/mysql.server start
  6. Add this line nearby the end of /etc/rc.shutdown to ensure that MySQL stops automatically during FreeBSD shutdown (add it right after that line that reads "Insert other shutdown procedures here").
    /usr/local/share/mysql/mysql.server stop
  7. Download Bugzilla 3.6 from here:
    http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-3.6.tar. gz
  8. Place the Bugzilla tarball in the Apache data directory, unroll it, and keep it around for future reference in /usr/src (or anywhere that's outside of the Web server directories).
    FreeBSD# mv bugzilla-3.6.tar.gz /usr/local/www/data
    FreeBSD# cd /usr/local/www/data
    FreeBSD# tar zxvf bugzilla-3.6.tar.gz
    ...
    FreeBSD# mv bugzilla-3.6.tar.gz /usr/src
  9. Make a symlink to the version-specific Bugzilla directory; this will simplify upgrading to future Bugzilla versions.
    FreeBSD# pwd
    /usr/local/www/data
    FreeBSD# ln -s bugzilla-3.6 bugzilla

Configuring Apache for Bugzilla

  1. Edit the Apache configuration file to suit Bugzilla.

    1. Note that in /usr/local/etc/apache, a backup configuration file is supplied by default entitled, "httpd.conf-dist."  So you can edit the httpd.conf file without worrying about being unable to start over later.

    2. Open /usr/local/etc/apache/httpd.conf in a text editor.

    3. Find the "ServerAdmin" line and put your e-mail address there, replacing "you@example.com."

    4. Navigate to the spot directly following the Directory entry for the main document root (/usr/local/www/data).  This should be around line number 404 in the supplied httpd.conf.  Add this new Directory section there:
           <Directory "/usr/local/www/data/bugzilla">
         AddHandler cgi-script .cgi
         Options +Indexes +ExecCGI
         DirectoryIndex index.cgi
         AllowOverride Limit
         Order allow,deny
         Allow from all
     </Directory>
    5. Save httpd.conf and quit your editor.

  2. Start Apache and make sure it's running.
    FreeBSD# /usr/local/sbin/apachectl start
    FreeBSD# ps ax | grep httpd
    ...
    You should see several "httpd" processes in the process list.

Configuring MySQL for Bugzilla

  1. Get MySQL running and basically secured.

    1. Make the directory where MySQL will store its database files:
      FreeBSD# mkdir /var/db/mysql
    2. Create the initial MySQL database files, including those it uses to store its own configuration.
      FreeBSD# /usr/local/bin/mysql_install_db
    3. Give the mysql account ownership and sole access rights.
      FreeBSD# chown -R mysql:mysql /var/db/mysql
      FreeBSD# chmod 700 /var/db/mysql
    4. Start the MySQL server.
      FreeBSD# /usr/local/bin/mysqld_safe &
    5. Use the "mysql_secure_installation" utility to apply a basic level of security to MySQL.

    6. Run the "mysql_secure_installation" program:
      FreeBSD# /usr/local/bin/mysql_secure_installation
    7. Enter the existing MySQL "root" account password (not the same as the FreeBSD "root" account password).  Just hit <Enter> here if you've followed these instructions explicitly, since it should still be blank.

    8. Enter a new MySQL root password.  If you care about security, make this different from the FreeBSD root account password.

    9. Agree to the removal of anonymous MySQL users.

    10. Agree to disallow remote MySQL root logins.

    11. Agree to remove the "test" database.

    12. Agree to reload the privilege tables.

  2. Configure MySQL to suit Bugzilla.

    1. Come up with a password that Bugzilla will use to connect to MySQL.  I'll use "w0ndrrDog," so replace that with the password you come up with for the following steps.

    2. Use the MySQL client program to access the MySQL server using the MySQL "root" account configured above.
      FreeBSD# /usr/local/bin/mysql -u root -p
      Enter password:
    3. Make a MySQL "bugs" account with permissions sufficient for Bugzilla's setup script to do its job later on.
      mysql> GRANT SELECT, INSERT, UPDATE, DELETE, INDEX, ALTER,
      -> CREATE, LOCK TABLES, CREATE TEMPORARY TABLES, DROP,
      -> REFERENCES ON bugs.* TO bugs@localhost IDENTIFIED BY
      -> 'w0ndrrDog';
      Query OK, 0 rows affected (0.00 sec)

      mysql> FLUSH PRIVILEGES;
      Query OK, 0 rows affected (0.00 sec)

      mysql> quit
      Bye
      FreeBSD#

Configuring Bugzilla for MySQL

  1. Use the "install-module.pl" script included with Bugzilla to install Bugzilla's many Perl dependencies.  I've left out install-module.pl's copious output.

    Note:  while installing DateTime, you'll be prompted as to whether or not you'd like to install several optional dependencies that are only required to get DateTime initially installed.  I chose to install them.
    FreeBSD# cd /usr/local/www/data/bugzilla-3.6
    FreeBSD# perl install-module.pl Digest::SHA
    FreeBSD# perl install-module.pl Date::Format
    FreeBSD# perl install-module.pl DateTime
    FreeBSD# perl install-module.pl DateTime::TimeZone
    FreeBSD# perl install-module.pl Template
    FreeBSD# perl install-module.pl Email::Send
    FreeBSD# perl install-module.pl Email::MIME
    FreeBSD# perl install-module.pl Email::MIME::Encodings
    FreeBSD# perl install-module.pl Email::MIME::Modifier
    FreeBSD# perl install-module.pl URI
  2. Edit the Bugzilla "localconfig" file to tell Bugzilla how to access MySQL.

    1. Make a backup localconfig copy in case you'd like to revert.
      FreeBSD# cd /usr/local/www/data/bugzilla-3.6
      FreeBSD# copy localconfig localconfig.dist
    2. Open /usr/local/www/data/bugzilla-3.6/localconfig with a text editor and perform these updates:

      1. Find the line that reads:
        $webservergroup = 'apache';
        And change it to read:
        $webservergroup = 'www';
      2. Find the line that reads:
        $use_suexec = 0;
        And change it to read:
        $use_suexec = 1;
      3. Find the line that reads:
        $db_pass = '';
        And change it to specify the password you chose— here's mine:
        $db_pass = 'w0nderrDog';
  3. Run the Bugzilla "checksetup.pl" script to automatically complete the MySQL database setup.

    1. Run the script.  It will connect to the MySQL server and set up its databases first.
      FreeBSD# /usr/local/www/data/bugzilla-3.6/checksetup.pl
      ...
    2. You'll be prompted to enter an e-mail address, name, and password for the Bugzilla administrator account.  This account's accessible through the Web UI once Bugzilla's up and running.  If you care about security, choose yet a different password for this account.  I'm choosing "K1ngRoo1es" (Mnemonic:  King Rules).

    3. Once you're prompted to visit the Bugzilla Web-based Parameters page, checksetup.pl's finished.  You may need to hit <Enter> to get your shell prompt back.

Basic Bugzilla Setup

  1. Open a Web browser and attempt to connect to Bugzilla.   Use this URL:
    http://yourHost.yourDomain.com/bugzilla/
    You should see the Bugzilla welcome screen, with three large icons:  a green bug, an orange magnifying glass, and a blue person.  If you see Bugzilla-related text but no colorful icons, as though the browser isn't loading the style sheet, you'll probably need to revisit your Apache configuration.

  2. Click on the "Log In" link nearby the top of the screen.   Log in using the e-mail address you previously configured for the Bugzilla "administrator," and the account's password.  I picked the password:  K1ngRoo1es

  3. You'll see a Bugzilla Welcome screen prompting you to perform some initial setup.  Since the rest of point-and-click, you'll probably want to take it from here, yet these are the initial customizations I made:

    1. Click on the "urlbase" link, then set the urlbase to http://yourHost.yourDomain.com/bugzilla/, or simply http://yourHost/bugzilla/ if that works in your network.

    2. Set "cookiepath" to /bugzilla/

    3. Click on "Save Changes."

  4. As prompted by Bugzilla, you'll need to configure at least one product with one component before you can start entering bugs.  You can create these by clicking on "Administration" (at the top of the screen), then "Products" (on the lower-left).


Additional Suggestions

  • By default you only get a few bug status values.  You may wish to create a few more, namely INPROGRESS and WAITING.  If you visit the "Field Values" portion of the "Administration" menu to do this, you'll also need to fill in the "Bug Status Workflow" data for those states—it won't work unless you do this after creating the new states.