Circles of Archimedes

Background

Bugzilla is a very popular open-source issue tracking system.  However, setting up all the user accounts can be a tedious chore, particularly for large user bases.  In addition, there are additional user-management headaches associated with maintaining another list of user names, password issues, and access changes due to staff turnover.

Fortunately, Bugzilla is capable of integrating with the RADIUS service available on the Mac OS X Server.  RADIUS is a remote authentication and authorization service which can handle the user authentication requests for Bugzilla and permit users to simply sign on with their standard account name and passwords.  This relieves the administrator from having to create and maintain another set of accounts and allows the users to simply use their standard account name and password.

It should be noted that the implementation of the RADIUS service on the Mac OS X Server is the open-source FreeRADIUS.  More configuration information and usage can be found on the projects web site.

Prior installation of Bugzilla is assumed for these directions.

Enabling the RADIUS Service

If the RADIUS service has not been enabled on the server, then it is necessary to activate it.  Do not start the service during this step.

1. Open the Server Admin application and connect to the server hosting the RADIUS service.
2. Select the server in the “Servers” pane and then click on the “Settings” icon.
3. Click on the “Services” tab and enable the “RADIUS” service by clicking on the appropriate checkbox.
4. Save the new configuration by clicking on the “Save” button.
5. Select the “RADIUS” service now available in the “Servers” pane.
6. Select the “Settings” icon and select a security certificate to use for the service.  A self-signed certificate can easily be created using the “Manage Certificates” option in the drop-down menu.  Regardless, the certificate used for this service should not have a Private Key Passphrase set.
7. Save the new configuration by clicking on the “Save” button.

Configuring the RADIUS service

The stock RADIUS service on Mac OS X (Leopard) has been configured to work only with Apple’s Airport and Airport Express WiFi systems.  In order to extend its functionality to provide service to other types of systems,  the configuration file must be edited and a special entry must be created.

1. Open the Server Admin application and connect to the server hosting the RADIUS service.
2. Select the RADIUS service for configuration.  If the service is already running, then click on the “Stop RADIUS” button to stop it.
3. Click on the “Base Stations” icon and then the “Add…” button to create a new entry.  The most important elements to set correctly are the Type and IP Address.  Type must be “other” and the IP Address should be the address of the Bugzilla server.
   

   Name: Bugzilla
   Type: other
   IP Address: 192.168.1.2
   Shared Secret: ********
   Verify: ********

4. Make a backup copy of the /etc/raddb/users configuration file for safety.

   sudo cp /etc/raddb/users /etc/raddb/users.orig

5. Edit the /etc/raddb/users configuration file to alter the default authentication type to use the Open Directory service instead of the local account database.  The line in question should be approximately 153 lines down in the file (as of 10.5.8).

   Replace: DEFAULT Auth-Type = System
   with: DEFAULT Auth-Type = opendirectory

6. Return to the Server Admin application and start the RADIUS service.

Testing the RADIUS service

In order to verify the RADIUS service is working properly it should be tested using the included test tool radtest.  The general format for testing the RADIUS service is:

radtest user password radius-server nas-port-number shared-secret

user is the username to be tested.

password is the user’s password.  Note that this is given in cleartext and so may be considered a security risk.  It is suggested that you change the password immediately after concluding the test.

radius-server is the hostname (or IP address) of the server hosting the RADIUS service.

nas-port-number is the value of the NAS-Port attribute.  For testing purposes, it does not matter what value is provided as long as it is between 0 and 2^31.

shared-secret is the shared secret established when the service was configured.

The following is an example usage showing the result of a successful test:

$ radtest groucho RufusTFirefly radius.example.com 10 SecretWord
Sending Access-Request of id 203 to 192.168.1.2 port 1812
User-Name = "groucho"
User-Password = "RufusTFirefly"
NAS-IP-Address = 255.255.255.255
NAS-Port = 10
rad_recv: Access-Accept packet from host 192.168.1.2:1812, id=203, length=20

Configuring Bugzilla for RADIUS authentication

RADIUS configuration requires administrative access to the Bugzilla installation.  It cannot be performed as a “normal” user of the system.  It is best practice to verify the RADIUS service is working properly before attempting to configure a dependent service.

1. Install the Authen::Radius perl module (if not already installed as part of the initial setup).

   sudo cpan -i Authen::Radius

2. Login as administrator to Bugzilla.
3. Click on the “Administration” link.
4. Click on the “Parameters” link.
5. Click on the “RADIUS” link
6. Fill in the information for all the RADIUS fields.  The server is the hostname where the RADIUS service is running.  The secret it the shared secret established when the service was configured.  The NAS IP is the address where the Bugzilla service is running.  The email suffix is appended to the username to generate the appropriate email address for each user.
   

   RADIUS_server:  radius.example.com
   RADIUS_secret:  ********
   RADIUS_NAS_IP:  192.168.1.2
   RADIUS_email_suffix:  @example.com

7. Click on the “Save Changes” button to save the new configuration information.
8. Click on the “User Authentication” link.
9. Navigate to the user_verify_class and activate RADIUS as a valid authentication mechanism.  It is strongly suggested that you leave the DB method also activated.
10. Click on the “Save Changes” button to save the new configuration information.

Related Links

• Installing Bugzilla on Mac OS X Server

Background

Bugzilla is a very popular open-source bug-tracking system.  It is used by many companies (large and small) to not only track defects and their remediation, but also to track various other development tasks, including new feature work, enhancement requests, etc.  It can even be used as part of a change-control process (e.g. SAS-70, SOx, etc.).

Because Bugzilla is an open-source project, it is actively enhanced and can be installed on a number of different systems.  It is easily customized in both appearance and functionality which provides it with the flexibility to fit into the existing development process of almost any team.

The project’s site (http://www.bugzilla.org) has a plethora of documentation, example usages, forums, as well as the latest releases.  The latest stable release can be found on their download page.  This post contains specific instructions for installing Bugzilla on a system running Mac OS X Server (Leopard).

Preliminary Preparations

Perl

An appropriate version of perl should already be available as part of the normal operating system installation.  Bugzilla requires a minimum of version 5.8.1 and version 5.8.8 should already be installed (as of OS X 10.5.8).  The version of perl can be verified with the following command:

/usr/bin/perl --version

MySQL

Bugzilla can utilize several different databases to store its data, but Mac OS X Server already has MySQL included in its normal installation so it makes sense to use that option.  However, the MySQL installed by default with Mac OS X Server does not include the necessary files to build a MySQL application so these must be installed manually.

To install the MySQL build files:

1. Go to the Apple open source download page and select the appropriate version of the operating system the installation is running.
2. Download the binary version of the MySQL package (for 10.5.8, the correct package is MySQL-45).
3. Decompress the packaged binary.

   tar xzf MySQL-45.binaries.tar.gz

4. Navigate to the uncompressed package directory.

   cd MySQL-45.binaries

5. Decompress the internal package into the destination directory.

   sudo tar -xzvf MySQL-45.root.tar.gz -C /

To enable the MySQL service:

1. Open the Server Admin application and connect to the server.
2. Select the server name and click on the “Settings” icon and then the “Services” tab.
3. Enable the MySQL service by clicking on the appropriate checkbox.
4. Click on the “Save” button to save the new configuration.

To start the MySQL service:

1. Open the Server Admin application and connect to the server.
2. Select the MySQL service from the list of available services.
3. Click on the “Settings” tab.
4. If necessary, set the root password for the MySQL service.  The default database location of /var/mysql may also be overridden if desired.
5. Click on the “Save” button to save the new configuration.
6. Click on the “Start MySQL” to startup the new service.

Apache

Bugzilla can utilize a wide variety of web servers, but Apache is already installed with Mac OS X Server so it makes sense to use that option.  For this installation, Bugzilla will be configured in its own subdomain (e.g. bugzilla.example.com) and not as a directory of another domain (e.g. www.example.com/bugzilla).

To setup the bugzilla domain:

1. Open the Server Admin application and connect to the server hosting DNS services.
2. Select the DNS service from the list of available services.
3. Select the “Zones” icon.
4. Select the Primary Zone for the site (e.g. example.com).
5. Click on the “Add Record” drop-down and select the “Add Alias (CNAME)” item.
6. Enter the Alias Name for the bugzilla subdomain.  The alias name should be fully qualified. This means the full domain name should be given and terminated with a period.

   bugzilla.example.com.

7. Enter the Destination for the bugzilla alias.  (i.e. the name of the server running Apache).  The domain name should be fully qualified. This means the full domain name should be given and terminated with a period.

   www.example.com.

8. Click on the “Save” button to save the new configuration.
9. Restart the DNS service to activate the new domain name.

To setup the bugzilla web site:

1. Open the Server Admin application and connect to the server hosting the web server.
2. Select the Web service from the list of available services.
3. Select the “Sites” icon.
4. Click on the “+” button to create a new site entry.
5. Click on the “General” tab and fill out the information for the new site entry:
   

   Domain Name: bugzilla.example.com
   Host Description: Bugzilla
   IP Address: any
   Port: 80
   Web Folder: /opt/local/www/bugzilla
   Default Index Files: index.cgi
   Error Document: /error.html
   Administrator Email: admin@example.com

6. Select the “Options” tab and enable the “CGI Execution” and “Allow All Overrides” options.
7. Select the “Logging” tab and setup the logging information:
   

   Enable Access Log: enabled
   Archive every: 7 days
   Location: /var/log/apache2/bugzilla_access_log
   Error Log Archive every: 7 days
   Error Log Location: /var/log/apache2/bugzilla_error_log
   Error Log Level: Warnings

8. Select the “Web Services” tab and disable any additional services selected.
9. Enable the new site by clicking the “Enabled” checkbox next to the site entry.
10. Click on the “Save” button to save the new configuration.
11. Restart the Web service to activate the new site.

Bugzilla

In this installation, Bugzilla is installed in the /opt/local/src directory so as to keep it isolated from the “stock” operating system tools and utilities.  This makes upgrading either the operating system or Bugzilla easier and less likely to result in conflicts.  In order to further simplify future upgrades, a symbolic link (/opt/local/www/bugzilla) is used as the root web folder instead of directly utilizing the actual Bugzilla source directory.

1. Download the latest Bugzilla source tarball.
2. Copy the tarball to source directory.

   sudo cp bugzilla-3.4.2.tar.gz /opt/local/src

3. Unpack the source tarball.

   cd /opt/local/src
sudo tar xzf bugzilla-3.4.2.tar.gz

4. Change the owner and group to the default web server user.

   sudo chown -R _www:_www bugzilla-3.4.2

5. Create an alias in the web folder to the active Bugzilla source.

   sudo ln -s /opt/local/src/bugzilla-3.4.2 /opt/local/www/bugzilla

Perl Modules

There are a number of perl modules (both required and optional) that Bugzilla requires for operating.  Fortunately, there are several utilities included in the Bugzilla directory that can be used to determine what needs installation as well as actually installing the necessary modules.  For these installations, it is strongly suggested that you run the commands in a root shell.

To install the perl modules:

1. Create a root shell.

   sudo bash

2. Execute the check-modules.pl script.

   /opt/local/src/bugzilla-3.4.2/checksetup.pl --check_modules

3. Install all the required perl modules identified by the check-modules.pl script.
4. Install the appropriate database binding module (DBD:mysql)

   /usr/bin/perl install-module.pl DBD::mysql

5. Install any optional modules desired.
6. Exit from the root shell.

   exit

Mail

Mac OS X Server already comes with a compatible mail transfer agent (Postfix) so no additional installation is necessary.  A working mail service is necessary for Bugzilla to issue event alerts and notifications.

Configuration

localconfig

The localconfig file is an auto-generated file that contains many of the core Bugzilla configuration variables.  Generation of the file is done by running the checksetup.pl script (with no additional parameters).  The resulting file is not immediately usable as it requires a couple quick updates to properly configure the database access.

1. Execute the checksetup.pl script to generate the localconfig file.

   cd /opt/local/src/bugzilla-3.4.2
./checksetup.pl

2. Change the $db_driver variable in the localconfig file.

   $db_driver = 'mysql'

3. Change the $db_pass variable in the localconfig file to the password for ‘bugs’ user of the database.  (The ‘bugs’ user will be created shortly.)

   $db_pass = '********'

4. Change the $webservergroup variable in the localconfig file.

   $webservergroup = '_www'

MySQL

In order to provide a better working experience with Bugzilla, it is necessary to update some of the MySQL configuration variables.  In addition, a new database user must be created.

1. Edit the /etc/my.cnf file to permit large attachments and many comments

   max_allowed_packet=4M

2. Edit the /etc/my.cnf file to allow small words in full-text indexes

   ft_min_word_len=2

3. Add the ‘bugs’ database user with associated privileges.  Be sure to specify the same password for the ‘bugs’ users as in the configuration of the localconfig file.

   mysql -u root -p
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, CREATE TEMPORARY TABLES, DROP, REFERENCES on bugs.* to bugs@localhost IDENTIFIED BY '********';
mysql> FLUSH PRIVILEGES;
mysql> commit;
mysql> exit;

4. Run the checksetup.pl script again to create the database tables, groups, users, and indexes.  Be sure to note the created administrator account and password for future reference.

Bugzilla

Bugzilla should now be accessible to a web browser at the domain specified earlier.  (http://bugzilla.example.com)  While it is usable in this state, there are some additional configuration settings that should be made with the administrator’s account.

1. Login as the administrator using the bugzilla administrator’s email address and password previously set.
2. Click on the “Administration” link.
3. Click on the “Parameters” link.
4. Set the email address of the maintainer.

   bugadmin@example.com

5. Set the URL base of the installation.

   http://bugzilla.example.com/

6. Set the cookie domain for the service.

   bugzilla.example.com

7. Click on the “Save Changes” button to save the new parameters.

Related Links

• Configuring RADIUS support for Bugzilla

The Development Dilemma

A common problem faced by developers and management is balancing efforts to implement new features and addressing bugs.  Frequently, there is intense pressure to focus efforts on feature development with the rationale that the bugs can be addressed “at a later time”.  Of course, other features are soon scheduled that prevent the “later time” from ever being realized, and so the list of bugs continues to grow over time.

Another common issue is that even when time is made to address bugs, only enough is scheduled for the highest priority issues to be resolved.  Lower priority issues continue to linger in the bug queue, resulting in an ever-growing list of minor bugs and issues that never seem to get addressed.  This situation is often readily apparent by bug queues that have very few Priority 1 or Priority 2 bugs, but dozens (hundreds!) of Priority 3 or lower bugs that have been open for months or even years.

Regardless as to what is causing the long-standing list of bugs, if the situation continues it will begin to affect the development efforts over time:

• Product quality steadily declines as the number of bugs increases over time
• Goodwill of the users is squandered as bugs continue to persist through multiple releases
• Prioritization loses value as all bugs begin getting filed as Priority 1 to ensure attention from development
• Developers become overwhelmed with the number of issues in their bug queues
• Management continuously has to assess priorities across an ever-increasing number of tasks

Bug Load provides assistance in prioritizing work efforts to address outstanding issues by providing an easy to calculate weighting for each issue.  With the Bug Load score available, developers can easily identify which issues have been lingering too long and when they need to scale back on feature development in order to attend to their bug queue.  Management benefits as well through increased insight into the work load of their engineering teams and the assurance that all bugs will be handled in a timely manner.

Prioritizing with Bug Load

Bug Load is a simple calculation based on the priority of the bug and the age of the bug:

Bug Load = Priority Weight x Age

Priority Weight establishes the initial importance of the bug with higher priority items having a corresponding higher value.  This helps to ensure that higher priority bugs are addressed sooner than a low priority bug of similar age.  Suggested Priority Weights are:

8 points assigned for each Priority 1 issue
4 points assigned for each Priority 2 issue
2 points assigned for each Priority 3 issue
1 point assigned for each Priority 4 (or lower) issue

Age is the time (in weeks) since the bug was initially reported.  As this is a multiplier of the Priority Weight, as a bug ages it will steadily increase its Bug Load value and so rise in importance.  This helps to ensure that even low priority bugs are eventually handled.

While knowing the raw Bug Load scores is useful to the developer for prioritizing which tasks to address, management needs to develop the appropriate policies and practices to make Bug Loads an effective tool.  The following are good starting efforts management should undertake when implementing Bug Loads for their team:

• Visibility is essential and Bug Loads should be presented to each developer at a minimum interval of once a week.  As the Age component of the equation is week-based, the Bug Load should not significantly change during the course of a week.  If possible, an automated system should be setup to generate individual reports and sent to each developer at the start of the week.
• Bug Loads without bounds are not effective, and so two threshold values should be established:  one to alert a developer that they are “at risk” and should step back from their feature commitments to attend to their bug queue, and another (higher) limit that results in a mandatory suspension of feature development work until the Bug Load is brought back down to a more reasonable value.  These threshold values may vary widely with the comfort level, age, or complexity of a given project and so there is no absolutely “right” values.  Management should set levels they are comfortable with and will not result in reasonably conscientious developers from falling into the feature suspension state on a regular basis.
• Bug Loads should only apply to real bugs.  Many development teams use bug tracking systems to track bugs, tasks, inquiries, etc.  The Bug Load is only designed to address the bug component and so proper classification of the entries in the bug tracking system is essential.  If a field is not available for identifying the type of entry, it may be possible to adopt a convention (e.g. prefix all bugs with “BUG:”) which may help in proper identification.

The Bug Load system can (and should) be adapted to the development environment of your team.  It may be appropriate to increase the age multipliers for projects with a quick development cycle or decrease them for longer term projects.  If severity is used in addition to priority for bugs, it may be desired to work that into the formula as a further refinement.

Example

P1 @ 1 week old:  8 x 1 == 8 points
P1 @ 2 weeks old:  8 x 2 == 16 points
P2 @ 1 week old: 4 x 1 == 4 points
P2 @ 3 weeks old:  4 x 3 == 12 points
P3 @ 2 weeks old:  2 x 2 == 4 points
P3 @ 5 weeks old:  2 x 5 == 10 points
P4 @ 2 weeks old: 1 x 2 == 2 points
P4 @ 10 weeks old: 1 x 10 == 10 points

In the above example, the developer has a relatively small number of bugs of varying priority and age.  A quick glance shows the P1 that is 2 weeks old (in the second row) should be of first importance.

Note also that the P4 that has been lingering for 10 weeks has steadily increased its relative importance and is now tied for third place.  This illustrates how the Bug Load metric can help escalate the priority of issues over time.  Bugs cannot be ignored for long periods of time, as they will eventually rise to dominate the Bug Load scores.

Caveats

Bug Load is not intended to be a quality metric.  A high (or low) Bug Load is not indicative of a developer’s skill or productivity as there may be any number of reasons behind a particular Bug Load value.

It is intended to be an objective measurement that can assist developers in prioritizing their work efforts and provide management with insight into the activities of the engineering team.  It also helps to ensure that all bugs are addressed in an appropriate timeframe and do not linger in the bug queue for extended periods of time.  It is best applied to individual developers and not as a team-based statistic.