3.1 General Configuration Questions

3.1.1 How do I add a new database?

A: (GNATS 3.1xx) (Please consider upgrading to GNATS 4.0 or greater.)

1. Create the base directory for the new database, say ‘/usr/local/gnats/db2’, and make sure it is owned by the GNATS user.
2. In there, create subdirectories ‘gnats-adm’, ‘gnats-adm/locks’, and ‘gnats-queue’, and make sure they is owned by the GNATS user.
3. Now you need to populate the new ‘gnats-adm’ directory. The easiest way is to copy all files from ‘gnats-db/gnats-adm’ to ‘/usr/local/gnats/db2/gnats-adm’, and edit them to reflect the needs of your new database. Again, make sure they are owned by the gnats user.

   Note that there must be a category named pending. It is used when no category is given in a report, and when a report names an invalid category.

   Also note that each database needs its own mail address for submissions (see also step 8 below), and that you must enter it in the file ‘config’.

4. As the GNATS user, run ‘mkcat --directory=/usr/local/gnats/db2’ to create the directories for the categories. Remove the files ‘current’ and ‘index’, if they exist.
5. If the new database is split off of another one, move or copy the existing reports to their new location. This is easiest if the categories have the same names as in the original database. (See How do I rename a category? if some of them changed names.)

   Run the program gen-index to create the index file (see (gnats)gen-index section ‘Regenerating the index’ in Keeping Track).

   Find the greatest report number and put it (or any larger number) into ‘/usr/local/gnats/db2/gnats-adm/current’.

   Caution: E-mail updates to the PRs you moved to the new database may still arrive at the old database. You may want to contact everybody who knows about these PRs, asking them to use the mail address of the new database when sending a follow-up.

6. Now add a line for the new database to ‘gnats-db.conf’, like this:

   /usr/local/gnats/db2:GreatNewDB

   Gnatsd reads it on startup (and as it is started by inetd, this means it becomes effective with the next connection to gnatsd). Gnatsweb (see Gnatsweb) learns the database list from gnatsd, so it will offer you the new database "GreatNewDB" when it is invoked next time.

   If you do not know where ‘gnats-db.conf’ lives, run:

   ‘strings /where/ever/gnatsd | grep gnats-db.conf’

7. Don’t forget to setup a cron job to run through the additional ‘gnats-queue’. Note that you need to specify the database directory to ‘queue-pr’, i.e.,

   ‘/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -r’

   or, if you prefer the long options,

   ‘/usr/local/lib/gnats/queue-pr --directory=/usr/local/gnats/db2 --run’

8. Don’t forget to create mail aliases for your new database (see (gnats)Aliases section ‘Setting up mail aliases’ in Keeping Track). Take care that the aliases have the right database, e.g.,

   GreatNewDB-bugs: "|/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -q" GreatNewDB-query: "|/usr/local/lib/gnats/mail-query -d /usr/local/gnats/db2"

   If you do not want to allow querying the database by mail, omit the ‘GreatNewDB-query’ alias.

   You usually need the cooperation of a system administrator for this step (if you are not a system administrator yourself, of course).

   Make sure that ‘/usr/local/gnats/db2/gnats-adm/config’ gives the correct mail addresses for GNATS_ADDR (this must be different for each database) and for GNATS_ADMIN (this is probably the same for all databases).

   GNATS_ADDR="GreatNewDB-bugs@bugs.example.com" GNATS_ADMIN="gnats-admin@bugs.example.com"

   If your GNATS sits behind a firewall and needs to exchange mails with the outside world, see also Outgoing mail bounces.

A: (GNATS 4.x) With version 4, this has become much easier (see (gnats)mkdb section ‘Adding another database’ in Keeping Track):

1. Add a line for the new database to ‘databases’, like this:

   GreatNewDB:Our great tools:/usr/local/gnats/db2

   Then, as the GNATS user, run ‘mkdb GreatNewDB’ to create the database. Make sure that the directory (in our example, ‘/usr/local/gnats/db2’) can be created by the GNATS user.

   (Note that there must be a database named default. It is used as a fallback by some tools if no database is specified. You need not use it actively, but you should have run ‘mkdb default’.)

   Gnatsd reads the file ‘databases’ on startup (and as it is started by inetd, this means it becomes effective with the next connection to gnatsd). Gnatsweb (see Gnatsweb) learns the database list from gnatsd, so it will offer you the new database "GreatNewDB" when it is invoked next time.

   If you do not know where ‘databases’ lives, run:

   ‘strings /where/ever/gnatsd | grep databases’

2. Now, as the GNATS user, edit the files in directory ‘/usr/local/gnats/db2/gnats-adm’ to reflect the needs of your new database.
3. Depending on the settings in the ‘dbconfig’ file of the new database, you need not run mkcat anymore in order to create new category directories in your database—GNATS 4 creates them automatically when they are missing. See (gnats)dbconfig file section ‘The dbconfig file’ in Keeping Track, for details.
4. Don’t forget to setup a cron job to run through the additional ‘gnats-queue’. Note that you need to specify the database to ‘queue-pr’, i.e.,

   ‘/usr/local/libexec/gnats/queue-pr -d GreatNewDB -r’

   or, if you prefer the long options,

   ‘/usr/local/libexec/gnats/queue-pr --database=GreatNewDB --run’

5. Don’t forget to create mail aliases for your new database (see (gnats)Aliases section ‘Setting up mail aliases’ in Keeping Track). Take care that the aliases have the right database, e.g.,

   GreatNewDB-bugs: "|/usr/local/libexec/gnats/queue-pr -d GreatNewDB -q" GreatNewDB-query: "|/usr/local/libexec/gnats/mail-query -d GreatNewDB"

   If you are updating from GNATS 3.1xx, note that the ‘-d’ option has changed its meaning: it does not give the directory of the database, but its name. (In case you prefer the long form of the option, it is now ‘--database’ instead of ‘--directory’.)

   If your GNATS sits behind a firewall and needs to exchange mails with the outside world, see also Outgoing mail bounces.

3.1.2 How do I rename a category?

Renaming a category requires to touch every PR in that category, because each report contains the name of its category.

To rename category A to B, proceed as follows:

1. Create a new category B.
2. Edit every report in category A, changing its category to B. This can be done with any GNATS client; check the archives of the HELP-GNATS mailing list for hints about automating this step.
3. Run gen-index (see (gnats)gen-index section ‘Regenerating the index’ in Keeping Track) to refresh the ‘index’ file.
4. If you are using GNATS 4 (or planning to upgrade soon), you should not remove the category A. When a follow-up to an existing PR arrives via e-mail, GNATS 4.x checks that both the category and the PR number indicated in the mail exist (this is a sanity check).

   To reduce the risk of new reports being filed to category A, change its description in the ‘categories’ file to something like ‘obsolete, use category B instead’.

3.1.3 How do I add, remove, or rename a PR field?

A: (GNATS 3.1xx) The fields and their names are fixed in GNATS 3.1xx, so this is not possible.

A: (GNATS 4.x) Edit the file ‘dbconfig’ to reflect your changes.

Note that the PR fields with the builtin-names severity, priority and state are required if you want automatic reminders (notify-about-expired-prs = true). In this case, the file ‘submitters’ must also contain a response time. The severity field is checked for values critical and serious, and priority for value high. This is currently not configurable.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.