Contents
- Introduction
- Resources
- Installing gnats and gnatsweb from cvs
- Initial Checkout of gnats
- Configuring gnats
- Submitting a Bug to gnats
Introduction
Bug tracking is more than keeping a list of outstanding software issues. It's keeping track of hardware problems, feature requests, common questions from the field, etc. It will also help you to work out developer schedules and keep a close watch on how the team is doing overall. In short, a good bug tracker is essential to your business.
This article will show you how to install and configure gnats, a popular bug tracker that is easy to install and takes only minimal work to maintain. It has a decent web interface and you can do general queries and generate reports easily.
One of the problems with flashier bug trackers like Bugzilla is that they require some fairly advanced database administration skills to set up and maintain. The gnats database, if you want to call it that, uses the file system. It's simple, robust, and it's good enough.
We're assuming you've got a handle on FreeBSD ports and have worked through the material in the previous articles and have a working postfix and Apache 2 sysytem.
Resources
Unfortunately, there is not a lot of information available on using, installing, and customizing gnats.
There's the main GNU gnats project page.
The gnats manual and gnats FAQ are also good resources.
Installing gnats and gnatsweb from cvs
If you've followed along in this series of articles so far, the process of getting the source code and building software should be old hat.
Here are the gnats and gnatsweb dependencies, with duplicates removed:
databases/gnats4 +- textproc/expat2 * already installed +- devel/gettext * already installed +- devel/gmake * already installed +- converters/libiconv * already installed databases/gnatsweb4 +- lang/perl5.8 * already installed +- converters/p5-MIME-Base64
Remember that you figure out the download name of the port by clicking on the "Description" link and checking the title of the page you end up on. After a while, you'll figure out that you can just hover the mouse over the "Description" link and get the name from the status bar of your browser.
Now we have enough information to go and get the relevant port files to build gnats and gnatsweb. Here are the commands I used to get the gnats and gnatsweb requirements, as root of course.
setenv CVSROOT :pserver:anoncvs@anoncvs.fr.FreeBSD.org:/home/ncvs cd /usr cvs login cvs checkout -A -P -r RELEASE_4_10_0 ports/databases/gnats4 cvs checkout -A -P -r RELEASE_4_10_0 ports/databases/gnatsweb4 cvs checkout -A -P -r RELEASE_4_10_0 ports/converters/p5-MIME-Base64 cvs logout
Building gnats and gnatsweb should now simply be a matter of:
cd /usr/ports/databases/gnats4 make install cd /usr/ports/databases/gnatsweb4 make install
The build should complete without errors. Now it's time to do some checking and post-install configuration.
Initial Checkout of gnats
The original gnats product was pretty simple, and considering that it's been around since the early 90's, it's not surprising that it's based on good old C code. The web interface is a relatively recent addition, and it uses some perl scripts to do the CGI interface.
Once you get your arms around the configuration files, it's easy to make changes to tailor gnats permisisons and database structure to your own needs.
Here's a very useful tip. When making changes to any
configuration files, back them up in a safe place. I personally like
to append an underscore and an incrementing number to the backups. So
/usr/local/etc/gnats/gnatsd.host_access
becomes:
/usr/local/etc/gnats/gnatsd.host_access_n
where n is the next avaialable number.
First things first. Download the gnats manual in whatever format is most useful to you and read it over. I'm not going to duplicate all of the hard work that went into that manual. What this section will do is go over the steps that you must take to get a minimal working gnats installation on your server. Customizing things for your site is up to you.
Fortunately, the FreeBSD installation does everything up to Section 3.3 - Installing the default database in the gnats manual. So let's pick up from there.
You get to the default gnatsweb page like this:
http://some.internet.address/cgi-bin/gnatsweb.pl
or through your local network like this:
http://192.168.1.2:80/cgi-bin/gnatsweb.pl
On a clean install of gnats and gnatsweb, you should get a picture like this:
This is OK. You didn't actually expect it to work, did you? The gnats daemon must run when you make a connection to it through gnatsweb, so edit your /etc/inetd.conf file and add the following to the end of it:
# $FreeBSD: src/etc/inetd.conf,v 1.44.2.17 2003/06/13 10:43:19 yar Exp $ # # Internet server configuration database ... # 30July2004 Ralph Hempel - Added gnats daemon # support stream tcp nowait gnats /usr/local/libexec/gnats/gnatsd gnatsd
Then restart the inetd system by sending a HUP signal to it. On my system, inetd is running as PID 78, so the following line does the trick:
funkenfanger# kill -s HUP 78
Now try to log in again, and you should see the following screen:
OK, now we're getting somewhere, we have a connection through gnatsweb to gnatsd, but we still can't look at a database because we have not yet set it up. The following line will set the default database up for us...
funkenfanger# /usr/local/libexec/gnats/mkdb default Copying default files from /usr/local/etc/gnats/defaults funkenfanger#
And this time we are greeted with what looks like a reasonable login screen:
Of course, you won't actually be able to log in to the gnats system yet, because we haven't given anyone permission to do anything but look at what the names of the available databases are, but we'll get to that in the next section.
Configuring gnats
Once again, I'll put in a gentle reminder to read the gnats manual for anyone that has got this far in the article. For this section, if you read nothing else, at least have a look at Appendix A: Where gnats lives.
For now, the only access to gnats on the server we're setting up is through gnatsweb, so we don't need, much less have the ability to accept PRs (Problem Reports) by email. Maybe later. we don't need to change anything in the cron files right now.
One thing we do need to do is set up appropriate mail aliases on the box so that notifications of new PRs accepted by gnats go to the right place. Fortunately, this is straighforward on a FreeBSD box.
I've added the following to the end of /etc/aliases as shown below:
# $FreeBSD: src/etc/mail/aliases,v 1.10.4.7 2003/04/04 06:15:55 gshapiro Exp $ # @(#)aliases 5.3 (Berkeley) 5/24/90 # # Aliases in this file will NOT be expanded in the header from # Mail, but WILL be visible over networks. # # >>>>>>>>>> The program "newaliases" must be run after # >> NOTE >> this file is updated for any changes to # >>>>>>>>>> show through to sendmail. # # # See also RFC 2142, `MAILBOX NAMES FOR COMMON SERVICES, ROLES # AND FUNCTIONS', May 1997 ... # GNATS gnats-admin: gnats-admin
Remember, this is where incoming mail gets redirected. It's a good idea to run newaliases every time you add a new mail alias, and of course, you should test the new alias right away by sending it some email. See the article on setting up Postfix for information on sending mail from the commandline.
Now we need to configure our test database. As always, your default database will probably get mangled in the course of testing. Eventually we'll hide the default database and create a "real" one, but for now your edits in default can't break your real system.
If you've read the gnats manual you'll know that the default database lives at:
/var/db/gnats/gnatsdb
and that you'll need to do some editing in the files in the gnats-adm directory to get anything to work. Let's give ourselves access to the default database.
The basic security principle of gnats is that you can always raise a user's priviledge level, but level lower it. That's why the default gnats installation on FreeBSD gives everyone the ability to list the databases, but nobody can login or do anything else unless explicitly enabled by an administrator.
When adding users to a gnats you can put the passwords into the file in plaintext format, but that would be a bit - um, how should I put it - stupid. If you want to use MD5 or Blowfish encoding, you'll need to figure out a way to encode the passwords using the appropriate method, ant that means downloading and installing some source ports. The list is below, with duplicates removed:
security/p5-Crypt-PasswdMD5 +- security/p5-Digest +- security/p5-Digest-MD5 +- converters/p5-MIME-Base64 * already installed +- lang/perl5.8 * already installed
And the commands to fetch and build the cryptographic packages...
setenv CVSROOT :pserver:anoncvs@anoncvs.fr.FreeBSD.org:/home/ncvs cd /usr cvs login cvs checkout -A -P -r RELEASE_4_10_0 ports/security/p5-Crypt-PasswdMD5 cvs checkout -A -P -r RELEASE_4_10_0 ports/security/p5-Digest cvs checkout -A -P -r RELEASE_4_10_0 ports/security/p5-Digest-MD5 cvs logout cd /usr/ports/security/p5-Crypt-PasswdMD5 make install
That went without a hitch, so let's move on to generating a password for a user. According to the gnats manual, the following incantation should do what we want:
funkenfanger# perl -e 'use Crypt::PasswdMD5 ; print Crypt::PasswdMD5::unix_md5_crypt "good_password" , time() % 100000000' $1$91332905$ZKtkDa3lodh3n1EwqWZRj1
Note that the perl script has conveniently prefixed the password string with $1$, which is the clue to the password authentication system that this is an MD5 password.
Now add that (using your own password and generated MD5 sum, of course) by editing /var/db/gnats/gnatsdb/gnats-adm/gnatsd.user_access and adding the appropriate user level id, password, and permission.
# # User access levels with the GNATS daemon. # # Any line which begins with a `#' is considered a comment, and GNATS # will ignore it. # # Each entry has the format: # # userid:password:access-level:database-alias # # Wildcard characters are supported for userid, password and database. ... #*::view: rhempel:$1$91332905$ZKtkDa3lodh3n1EwqWZRj1:view:
Note that this gives rhempel view priviledges on the default database, and along with view comes the ability to create problem reports, but not to edit them after the fact.
Before we get all excited and start testing things, let's make sure that we have the rest of the configuration items we need. Each database is individually configurable. If you have common site-wide database configuration, then it might be a good idea to fill in the items in the default templates that get copied when you make a new gnats database. The common files are in /usr/local/etc/gnats/defaults.
Deciding on categories, classes, states, and other items appropriate for your situation is up to you, but rest assured that it's quite easy to customize each gnats database for your exact needs.
Have a very good look at the file headers before changing anything. The header docs are a very good description of how to specify each field, and what they mean. Remember to make the changes first on a test database!
The categories file
This is where you set up the categories that your bugs can be classified by. The default is to have only one category, and that's pending. All the PRs in the pending category are sent to gnats-admin for review.
You might want to add new categories to match your particular workflow. If you do update the categories, then be sure to run /usr/local/libexec/gnats/mkcat to update the categories in the specified database index.
For now, we'll leave this alone. All submitted PRs will go to gnats-admin in the pending category for further analysis and classification.
The classes file
This is where you classify bugs into different types. Again, the defaults are probably sufficient to get you started. The default classes are shown in this excerpt:
# The first listed class is the default class for an incoming Problem # Report. sw-bug::Problem requiring a correction to software. doc-bug::Problem requiring a correction or improvement in documentation. support::A support problem or question. change-request::Suggested change in functionality. mistaken::Not a problem, bad PR submission. duplicate::Duplicate of another existing PR.
The classes do come in handy when you are querying the database for all outstanding sw-bug, for example.
The responsible file
The responsible file is where we associate gnats user names that are assigned to certain problem categories, classes, or submitters with the email addresses that the reports get sent to. The email adresses can be local to the machine or domain, and can even be set up to email off-site people.
The default is to have gnats-admin get all the email, and you can add users quite easily based on the information in the header of the file. If you're running your server in another domain, or your administrator's email address is really somewhere else, it's no problem to redirect gnats-admin to an arbitrary address.
The submitters file
This file is where we associate the user names on incoming PRs with gnats user names that are responsible for dealing with the individual submitters. You can also do things like specify a minimum response time, notification lists for PR updates.
By default, the only entry in this file is unknown and for now that's OK. Eventually, you'll want to give each person on the team a submitter entry.
Uncomment the test entry, because gnatsweb won;t let you submit bugs as the unknown user.
The states file
The states file tells gnats the allowable states that a bug can take during its life cycle. The gnats manual says that the only default states are open and closed but in reality, there are also states for analyzed, suspended, and feedback.
It is very likely that you will add or modify this file. Your company workflow is (or should be) pretty much the same for any kind of bug or issue. If you change the standards later, then make sure you update all the states files accordingly.
The adresses file
This is where you associate submitter IDs with email adresses. The nice thing about using email to submit PRs is that you can usually automatically associate a submitter with their email address.
The gnatsweb interface does not do this, even though it probably could based on your current login name. This leads to the possiblity of users submitting bugs with incorrect IDs, which is annoying.
Again, we'll leave this one alone for now.
Submitting a Bug to gnats
If you click on the "Create" button or tab on the main login screen, you'll be directed to something like this:
All we're doing here is testing, using the default database. So fill in the fields as directed and things should "just work". If gnatsweb decides that the fields you ahve filled in are somehow incorrect, you'll get a nice error page like this one that comes up if you try to submit a blank PR:
Just keep filling in the fields until gnatsweb accepts the PR, and you'll be rewarded with a notification at whatever address gnats-admin email goes to.
Really, that's ll there is to getting gnats and gnatsweb up and running. The discussion about how to submit, analyse, track, and close bugs is way beyont the scope of this article, but I do plan on one in the near future.
Send a nice note to the address at the bottom of this page and I'll be much more motivated to do it!
