3. Configuration Issues

3.1 General Configuration Questions		General questions about GNATS configuration
3.2 Gnatsd, the GNATS Daemon		Configuration of the GNATS daemon
3.3 E-Mail Issues		Problems with the e-mail interface
3.4 Miscellaneous Configuration Issues		Other configuration problems

3.1 General Configuration Questions

3.1.1 How do I add a new database?		How to create a new database
3.1.2 How do I rename a category?		How to rename categories
3.1.3 How do I add, remove, or rename a PR field?		Add, remove, or rename a PR field

3.1.1 How do I add a new database?

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

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 3.1.2 How do I rename a category? if some of them changed names.)

   Run the program gen-index to create the index file (see 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 4.1 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 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 Mail from GNATS bounces.

A: (GNATS 4.x) With version 4, this has become much easier (see 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 4.1 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 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 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 Mail from GNATS 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 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.

3.2 Gnatsd, the GNATS Daemon

3.2.1 Gnatsd Port Number		How to connect to gnatsd
3.2.2 How to Start Gnatsd		How to make gnatsd accept connections
3.2.3 Gnatsd Messages		Some error messages and what they mean

3.2.1 Gnatsd Port Number

In 3.xxx versions, gnatsd uses port 1529 by default; as this port is officially assigned to another application (see the list of port numbers maintained by the Internet Assigned Numbers Authority) it will probably change in 4.x.

If you want/need to run gnatsd on another port, you can change the default port at compile time (call configure --help to learn about compile time configuration options). Most clients also accept an option or configuration variable to change the port. Don't forget to tell inetd (or xinetd, or whatever super-server you use) to start gnatsd on the other port.

3.2.2 How to Start Gnatsd

Gnatsd is intended to be started by some "super server", like inetd or xinetd. ("Super servers" are sometimes also called "super daemons".)

This is also described in the GNATS manual; see section `Installing the daemon' in Keeping Track.

How to configure inetd to start gnatsd		The traditional super server
How to configure xinetd to start gnatsd		Another widespread super server

How to configure inetd to start gnatsd

If your gnatsd will be started by inetd (the "internet daemon"), add the following entry to your `/etc/inetd.conf':

# port userid program support stream tcp nowait gnats /usr/local/libexec/gnats/gnatsd gnatsd

and to `/etc/services':

support 1529/tcp # GNATS

(You may need to use tabulator characters to separate the fields of `/etc/services'.) Then send inetd a hangup signal (kill -HUP pid-of-inetd).

You may want to use another port instead of 1529 (see section 3.2.1 Gnatsd Port Number).

How to configure xinetd to start gnatsd

If your gnatsd will be started by xinetd (the "extended internet daemon"), create a file `/etc/xinetd.d/support' with the following lines (see section `Installing the daemon' in Keeping Track):

service support {         disable = no         socket_type = stream         protocol = tcp         wait = no         user = gnats         server = /usr/local/libexec/gnats/gnatsd server_args = gnatsd }

or add theses lines to your `xinetd.conf' file, whatever is appropriate. The equal signs seem to need spaces around them with some versions of xinetd.

You need to add

support 1529/tcp # GNATS

to `/etc/services' (it may be necessary to use tabulator characters to separate the fields), and to tell xinetd to reread its configuration (kill -HUP pid-of-xinetd).

3.2.3 Gnatsd Messages

You are not on the host access list: stdin (stdin)		Error when starting gnatsd manually
You are not on the host access list		Cannot connect from another machine

You are not on the host access list: stdin (stdin)

Q: When starting gnatsd manually (on the command line), I get `520 You are not on the host access list: stdin (stdin)'.

A: (GNATS 3.1xx) Gnatsd is not intended to be started manually, but via inetd, xinetd, or a similar "super server". When gnatsd is started this way, its stdin and stdout (standard input and standard output streams) are connected to a so called "TCP socket" (one end of the network connection), and from this socket gnatsd learns the IP address of the remote end (and from this it derives the remote host name). When you start gnatsd from the command line, its stdin and stdout are connected to the terminal, and thus gnatsd gets a nonsense value.

You usually need `root' privileges in order to change the configuration of your "super server". If you don't have them, contact your system administrator.

See 3.2.2 How to Start Gnatsd for inetd and xinetd configuration.

A: (GNATS 4.0) This error message should not occur with gnatsd 4.0 anymore, because gnatsd can be started from the command line. However, this probably only makes sense for debugging and diagnosing problems. Furthermore, you need to play the part of the client program yourself (i.e., you must "speak" the gnatsd client protocol).

You are not on the host access list

Q: Gnatsd rejects connections from a remote host with the error message `520 You are not on the host access list'.

A: Check the file `gnatsd.host_access'; if you are using the default locations, this is `/usr/local/etc/gnats/gnatsd.host_access'. (If you are still using GNATS 3.xxx, the file is named `gnatsd.conf'; its default place is `/usr/local/etc/gnatsd.conf'.)

Each line of the file names a host and its access level, separated by colons. Gnatsd tries the lines in turn to match the remote host, and the first line that matches wins.

The first field specifies the host(s); it may be a host name (like `goedel.example.com'), a partial domain (like `*.example.com'), an IP address (like `192.168.1.5'), or a partial IP address (like `192.168.*'). If it is only `*', it matches all hosts.

Depending on how IP addresses are mapped to hostnames on your gnatsd machine, you may be able to omit the domain (like in `goedel'). You may even need to omit the domain for some hosts.

The second field is the access level granted to the remote host. This is usually increased by the access level granted to the user as soon as (s)he logs in.

The third field is currently not used; just leave it empty (but supply the colon between the second and the third field).

Example:

# # This is a comment # # Grant view access to all hosts with IP addresses # ranging from 192.168.0.0 to 192.168.255.255: 192.168.*:view: # Users on host goedel.example.com get (at least) edit access: goedel.example.com:edit: # Users from escher.example.com may view all reports, even # confidential ones: escher.example.com:viewconf: # Users from bach.example.com may only view all non-confidential # reports: bach.example.com:view: # Users from other example.com hosts # only get the access specified for them in gnatsd.user_access: *.example.com:none: # Same for domain our-users.example: *.our-users.example:none: # All other hosts are rejected # without even asking for username and password: *:deny:

The format is described in detail in the comments at the beginning of the file.

3.3 E-Mail Issues

queue-pr not available for sendmail programs		Sendmail refuses to run queue-pr
Mail from GNATS bounces		Mail system complains on outgoing mail

queue-pr not available for sendmail programs

Your sendmail installation uses `smrsh' to check programs that are invoked from a mail alias. `smrsh' only allows the execution of programs of which it is told that they are save. To tell it that `queue-pr' is save, create a symbolic link in the directory `/etc/smrsh' to `queue-pr', like this:

mkdir /etc/smrsh # if it does not yet exist cd /etc/smrsh ln -s /usr/local/libexec/gnats/queue-pr queue-pr

Replace `/usr/local/libexec/gnats/queue-pr' by the real path to `queue-pr'.

Mail from GNATS bounces

You are getting bounce mails like this:

----- Transcript of session follows ----- ... while talking to mail.example.com.: >>> MAIL From:<gnats@mymachine.subdomain.example.com> SIZE=334 <<< 501 5.1.8 <gnats@mymachine.subdomain.example.com>... Domain of sender address gnats@mymachine.subdomain.example.com does not exist

Probably your GNATS sits behind a firewall, but it needs to exchange mails with the world outside the firewall. Make sure that GNATS_ADDR is valid outside.

This is what probably happens behind the scenes: On its way to the outside world, the sender address of the mail gets rewritten to something "official" (like Hans-Albert.Schneider@example.com, as opposed to me@mymachine.subdomain.example.com). This is especially necessary if the internal hosts are not visible outside. If your outgoing mail gateway still sees the internal address, it complains with a message like the above (it has probably checked mymachine.subdomain.example.com with your organization's external DNS server, which does not know mymachine).

To solve this problem, get an "official" address for your GNATS system, e.g., tool-bugs@example.com, and use that one for GNATS_ADDR.

3.4 Miscellaneous Configuration Issues

New reports do not show up in the database
Assigning responsible etc. when entering a report		If you want to set additional fields when entering a report

New reports do not show up in the database

1. Make sure you have set up the mail aliases for your database(s). (See 3.1.1 How do I add a new database? and section `Adding another database' in Keeping Track.)

2. Try to send a PR using `send-pr'. If you get error replies, investigate the causes. See 3.3 E-Mail Issues.

3. Does a new file show up in the `gnats-queue' directory of your database, with the report as its contents? If it does, make sure you have created the cron job for this database.

4. If the report does not show up in the `gnats-queue' of the desired database, does it show up in the `gnats-queue' directory of another database? In this case, make sure your mail aliases are set up correctly; especially, make sure that you have specified the correct `--directory' option (`--database' for GNATS 4.x) for each `queue-pr'.

Assigning responsible etc. when entering a report

Q: When entering a new PR, I want to assign a value to some field (e.g., Responsible) which is normally assigned by GNATS.

A: (GNATS 3.1xx) This is not possible in GNATS 3.1xx.

A: (GNATS 4.x) This is done by adding the field name (in this example, Responsible) to the initial-entry item at the very end of the `dbconfig' file. Gnatsweb will pick this up and add a Responsible field to the Create PR form.