Home | Topics | Links | About

GNATS issue tracking system configuration howto

GNATS is an issue tracking system that has important advantages when compared to other alternatives. This howto is a simple step by step guide for setting-up and using the GNATS issue tracker.

Advantages of GNATS

The advantage of GNATS over several other issue tracking system are : (1) GNATS offers client/server interface through the gnatsd,send-pr,query-pr,edit-pr these allow the interaction with GNATS database from the command line which is great. (2) GNATS allows 'relocation' of issues or bugs and moving them freely between categories/modules. If in a hurry, the user can just post an issue to an un-undefined category. GNATS will associate the default 'pending' category to the new issue until the administrator or the user himself assigns the correct category to the new issue. (3) GNATS uses a file-based back-end database which makes it easy to backup and.

Installing GNATS

GNATS can be installed through packages system in most linux/unix systems. Under FreeBSD using the ports collection, you can install gnats and gnats web as follows

cd /usr/ports/databases/gnats4
make install
cd /usr/ports/databases/gnatsweb4
make install

The installation will add a user gnats in the system. All the files used by the GNATS system must be owned by the gnats user.

Setting up the gnatsd server

Update /etc/aliases

Add the following

gnats-admin:  address
bugs:  "| /usr/local/libexec/gnats/queue-pr -q"

Then run

newaliases

Update /etc/inetd.conf

Add the following

  support	stream	tcp	nowait	gnats	/usr/local/libexec/gnats/gnatsdgnatsd

Then restart inetd as follows

/etc/rc.d/inetd restart

Add a new cron-job for the gnats user

As root type

crontab -u gnats -e
0,10,20,30,40,50 * * * * /usr/local/libexec/gnats/queue-pr --run

Adding databases

To add a database, the following steps are required :

Edit /usr/local/etc/gnats/databases

Add an entry as follows :

databasename:Bug database:/var/db/gnats/databasename

Create the database

 
/usr/local/libexec/gnats/mkdb databasename

Configuring access privileges

Host based access control :
Edit /var/db/gnats/databasename/gnats-adm/gnatsd.host_access, and add lines such as

   localhost:edit:
   156.54.55.*:view:

User based access control :
Edit /var/db/gnats/databasename/gnats-adm/gnatsd.user_access, and add lines such as

   joe:$0$joepassword:admin
   bill:$0$billpassword:edit

Configuring categories and responsibles

Add a new category or module :
Edit the file /var/db/gnats/databasename/gnats-adm/categories, and add a line such as

  modulename:Some Project or Module:joe:

Where joe is a responsible.

Add responsibles:
Edit /var/db/gnats/databasename/gnats-adm/responsibles, and add a line such as

joe:Joe Foe:joe
bill:Mister Bill:bill@example.com

Add submitters:
Edit /var/db/gnats/databasename/gnats-adm/submitters, and add a line such as

dod:Department of Defense:DARPA:4:bill:al

Using and administrating GNATS

Accessing GNATS databases using gnatsweb

The gnatsweb will install cgi scripts in the default cgi-bin directory (/usr/local/www/cgi-bin). Edit the gnatsweb.pl file to customize some variables, then put these files in a location where they can be accessed and executed as cg-scripts. You can access the GNATS database using the web interface by pointing the browser to the gnatsweb.pl script (e.g. http://www.example.com/cgi-bin/gnatsweb).

Using the client/server interface

To use the GNATS system from remote locations, the users can access databases through the web interface or using the client/server interface. The latter alternative requires installing client side scripts. Under Debian/Ubuntu, you can do this by issuing the following command :

apt-get install gnats-user

The programs send-pr,query-pr,edit-pr will all be installed. To use them, it is preferable that the environment variable GNATSDB points to the GNATS database. Set it as follows (assuming bash shell)

export GNATSDB=gnatsserver:1529:database:login:pass

Now the user can access the database using the client tools. The following is a list of examples

Command	Description
query-pr -q	List summary of all issues
query-pr –list-fields	List all fields
query-pr –valid-values class	List all classes/projects
query-pr –category somecategory	Lists all issues in the category somecategory
edit-pr 2	Edits issue number 2
send-pr	Presents the user with fields to fill in and creates a new issue report based on the provided information