3. GNATS Administration

In daily usage, GNATS is self-maintaining. However, there are various administrative duties which need to be performed periodically:

emptying the pending directory
If a Problem Report arrives with a `>Category:' value that is unrecognized by the `categories' file, or if that field is missing, GNATS places the PR in the `pending' directory (see section Where the tools and utilities reside). PRs submitted in free-form by email will always be filed in the `pending' directory. If so configured, GNATS sends a notice to the gnats-admin and to the party responsible for that submitter (as listed in the `submitters' file) when this occurs.

To have these "categoryless" PRs filed correctly, you can then use a GNATS tool such as edit-pr to set the correct category of each PR in the `pending' directory.

In order to protect yourself from problems caused by full disks, you should arrange to have all mail that is sent to the GNATS database copied to a log file (Setting up mail aliases). Then, should you run out of disk space, and an empty file ends up in the database's `pending' directory, you need only look in the log file, which should still contain the full message that was submitted.

adding new categories
Most installations of GNATS will only require you to add a new line to the `categories' file. The category directory will then be created autmatically as needed. However, if automatic directory creation has been switched off in the `dbconfig' file (see section The dbconfig file), you need to use the `mkcat' program.

removing categories
To remove a category, you need to make sure the relevant subdirectory is empty (in other words, make sure no PRs exist for the category you wish to remove). You can then remove the category listing from the `categories' file, and invoke

  rmcat category

to remove category (any number of categories may be specified on the command line to rmcat, so long as they abide by the above constraints).

adding and removing maintainers
Edit the `responsible' file to add a new maintainer or to remove an existing maintainer. See section The responsible file.

building a new index
If your index becomes corrupted, or if you wish to generate a new one for some reason, use the program gen-index (see section Regenerating the index).

pruning log files
Log files often grow to unfathomable proportions. As with gardening, it is best to prune these as they grow, lest they take over your disk and leave you with no room to gather more Problem Reports. If you keep log files, be sure to keep an eye on them. (See section Setting up mail aliases.)

Any database is only useful if its data remains uncorrupted and safe. Performing periodic backups ensures that problems like disk crashes and data corruption are reversible.

See section Where GNATS lives.

3.1 Overview of GNATS configuration   
3.2 The databases file    The databases file
3.3 The dbconfig file    The dbconfig file
3.4 Other database-specific config files    Configuration files
3.5 Administrative data files   
3.6 Administrative utilities   
3.7 Internal utilities   

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 Overview of GNATS configuration

See section Where GNATS lives.

GNATS has two different kinds of configuration file. The site-wide configuration files determine overall behaviour across all the databases on your machine, while the database-specific configuration files determine how GNATS behaves when dealing with a specific database. These files can be edited at any time -- the next time a GNATS tool is invoked, the new parameters will take effect.

These are the site-wide configuration files used by GNATS:

Specifies database names and their associated parameters, such as in which directory they are located. This file is used by the GNATS clients to determine the location of a database referred to by name. See section The databases file.

Controls access levels for the different machines that will do lookups in the databases on this machine. See section GNATS access control.

The database-specific configuration is determined by the following files in the `gnats-adm' subdirectory of the database directory.

Controls most aspects of how GNATS behaves when dealing with your database. See section The dbconfig file.

The list of categories that GNATS accepts as valid for the `>Category:' field, and the maintainers responsible for each category. Update this file whenever you have a new category, or whenever a category is no longer valid. You must also update this file whenever responsibility for a category changes, or if a maintainer is no longer valid. See section The categories file.

An alias list mapping names to their associated mailing addresses. The names in this list can have multiple email addresses associated with them. If a responsible user does not show up in this list, they are assumed to be a user local to the system. This list is not associated with just the responsible user field; all email addresses are mapped through this file whenever mail is sent from GNATS. See section The responsible file.

Lists sites from whom GNATS accepts Problem Reports. The existence of this file is mandatory, although the feature it provides is not; see The submitters file.

Mappings between submitter IDs and submitters' e-mail addresses. Use of this file is optional. If you get Problem reports where the `>Submitter' field is not filled in, GNATS will use entries in this file to try to derive the submitter ID from the e-mail headers. See section The addresses file.

Lists the possible states for Problem Reports, typically ranging from open to closed. See section The states file.

Lists the possible classes of Problem Report. This provides an easy way to have "subcategories", for example by setting up classes such as sw-bug, doc-bug, change-request etc. See section The classes file.

Specify the access levels for different users to your database. See section GNATS access control.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 The databases file

The `databases' configuration file is a site-wide configuration file containing the list of GNATS databases that are available either on the host itself or remotely over the network, together with some parameters associated with each database.

The file contains one line for each database. For databases located on the host itself, each line consists of three fields separated by colons:

database name:short description of database:path/to/database

The first field is the database name. This is the name used to identify the database when invoking programs such as query-pr or send-pr, either by using the --database option of the program or by setting the GNATSDB environment variable to the name of the database. The second field is a short human-readable description of the database contents, and the final field is the directory where the database contents are kept.

For a database that is located across a network, but which should be accessible from this host, the entry for the database should look like this:

database name:short description of database::hostname:port

The first two fields are the same as for local databases, the third field is empty (notice the two adjacent `:' symbols, indicating an empty field), the fourth field is the hostname of the remote GNATS server, and the fifth field is the port number that the remote GNATS is running on.

If GNATS was built with default options, the `databases' file will be located in the `/usr/local/etc/gnats' directory. However, if the option --with-gnats-dblist-file was used during building of GNATS, the `databases' file has the name and location given to this option. A sample `databases' file is installed together with GNATS.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 The dbconfig file

The `dbconfig' configuration file controls the configuration of a GNATS database. Each database has its own individual copy of this file, which is located in the `gnats-adm' subdirectory of the database.

The file consists of standard plain text. Whitespace is completely optional and is ignored. Sets of braces `@' are used to delimit the different sections, and all non-keyword values must be surrounded with double quotes. The values in `dbconfig' can be changed at any time; the new values take effect for all subsequent iterations of GNATS tools.

The `dbconfig' file contains 6 major sections, which must appear in the following order:

The different sections are described below. While reading the following sections, it will be useful to refer to the sample `dbconfig' file which is installed when a new database is initialized with the mkdb tool. In fact, the sample file provides a configuration that should be usable for a great range of sites, since it reproduces the behaviour of the older, less customizable 3.x versions of GNATS.

3.3.1 Overall database configuration   
3.3.2 Individual field configuration   
3.3.3 Field datatypes   
3.3.4 Edit controls    Trigger on certain edit actions
3.3.5 Named query definitions    Define and name standard queries
3.3.6 Audit-trail formats    Specify formatting of the audit-trail
3.3.7 Outgoing email formats    Specify contents and formatting of messages sent out by GNATS.
3.3.8 Index file description    Specify the general format and contents of the database index
3.3.9 Initial PR input fields    Which fields should be present on initial PR entry.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.1 Overall database configuration

The overall database options are controlled by settings in the database-info section of the `dbconfig' file. The following is the general format of this section:

database-info {

The following options and values may be used in the database-info section:

debug-mode true | false
If set to true, the database is placed into debug mode. This causes all outgoing email to be sent to the gnats-admin user listed in the `responsible' file of the database. The default value is false.

keep-all-received-headers true | false
If set to true, all of the Received: headers for PRs submitted via email are kept in the PR. Otherwise, only the first one is kept. The default value is false.

notify-about-expired-prs true | false
If set to true, notification email about expired PRs is sent via the at-pr command. Otherwise, required times for PR fixes are not used. The default value is false.

send-submitter-ack true | false
When new PRs are submitted to the database, an acknowledgment email will be sent to the submitter of send-submitter-ack is set to true. This is in addition to the normal notification mail to the person(s) responsible for the new PR. The default value is false.

libexecdir "directory"
Specifies the directory where the GNATS administrative executables are located. In particular, at-pr and mail-pr are invoked from this directory. The default value is the empty string, which is unlikely to be useful.

business-day-hours day-start - day-end
Used to specify the hours that define a business day. The values are inclusive and should be given in 24-hour format, with a dash separating them. GNATS uses these values to determine whether the required completion time for a PR has passed. The default values are 8 for day-start and 17 for day-end.

business-week-days week-start - week-end
Specifies the start and ending days of the business week, where 0 is Sunday, 1 is Monday, etc. The days are inclusive, and the values should be given with a dash separating them. GNATS uses these values to determine whether the required completion time for a PR has passed. The default values are 1 for week-start and 5 for week-end.

create-category-dirs true | false
If set to true, database directories for categories are automatically created as needed. Otherwise, they must be created manually (usually with the mkcat script). It is recommended that the default value of true be kept.

category-dir-perms mode
Standard octal mode-specification specifying the permissions to be set on auto-created category directories. Default is 0750, yielding user read, write and execute, and group read and execute.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.2 Individual field configuration

Each type of field in a PR must be described with a field section in the `dbconfig' file. These sections have the following general structure:

field "fieldname" {
  description "string"
  [ field-options ... ]
  datatype [ datatype-options ... ]
  [ on-change { edit-options ... } ]

fieldname is used as the field header in the PR. The characters > and : are used internally as field markers by GNATS, so they must not be used in fieldnames.

The order in which the field sections appear in the `dbconfig' file determines the order in which they appear in the PR text. There is no required order, unlike previous versions of GNATS --- the Unformatted field and multitext fields may appear anywhere in the PR.

The following field-options may be present within a field section:

builtin-name "name"
Indicates that this field corresponds to one of the GNATS built-in fields.

GNATS has several fields which are required to be present in a PR, and this option is used to map their external descriptions to their internal usage. The external field names are:

The PR's unique numeric identifier

The category that the PR falls into

The one-line description of the PR

If set to yes, the PR is confidential

Severity of the problem described by the PR

Priority of the PR

The person responsible for handling the PR

The current state of the PR

The user that submitted the PR

The arrival date of the PR

The date the PR was last modified

The audit-trail recording changes to the PR

For these built-in fields, a matching field description must appear in the `dbconfig' file. Otherwise, the configuration will be considered invalid, and errors will be generated from the GNATS clients and gnatsd.

description "description text"
A one-line human-readable description of the field. Clients can use this string to describe the field in a help dialog. The string is returned from the FDSC command in gnatsd and is also available via the --field-description option in query-pr.

This entry must be present in the field description, and there is no default value.

query-default exact-regexp | inexact-regexp
Used to specify the default type of searches performed on this field. This is used when the ^ search operator appears in a query, and is also used for queries in query-pr that use the old --field query options.

If the option is not given, the default search is exact-regexp.

If this option is present, the field will be searched when the user performs a --text search from query-pr. The field is also flagged as a textsearch field in the set of field flags returned by the FIELDFLAGS command in gnatsd.

By default, fields are not marked as textsearch fields.

When this option is present, the field contents may not be edited -- they must be set when the PR is initially created. In general, this should only be used for fields that are given as internal values rather than fields supplied by the user.

By default, editing is allowed.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.3 Field datatypes

Each field description has to contain a datatype declaration which describes what data are to be store in the field. The general format for such a declaration is

datatype [ options ... ]

The available datatypes are:

text [ matching { "regexp" [ "regexp" ... ] } ]
The text datatype is the most commonly used type; it is a one-line text string.

If the matching qualifier is present, the data in the field must match at least one of the specified regexps. This provides an easy and flexible way to limit what text is allowed in a field. If no matching qualifier is present, no restriction is placed on what values may appear in the field.

multitext [ { default "string" } ]
The field can contain multiple lines of text.

If the default option is present, the field will default to the specified string if the field is not given a value when the PR is initially created. Otherwise, the field will be left empty.

enum {
values {
"string" [ "string" ... ]
[ default "string" ]
Defines an enumerated field, where the values in the PR field must match an entry from a list of specified values. The list of allowed values is given with the values option. The values option is required for an enumerated field.

If a default option is present, it is used to determine the initial value of the field if no entry for the field appears in an initial OR (or if the value in the initial PR is not one of the acceptable values). However, the value in the default statement is not required to be one of the accepted values; this can be used to allow the field to be initially empty, for example.

If no default option is specified, the default value for the field is the first value in the values section.

multienum {
values {
"string" [ "string" ... ]
[ separators "string" ]
[ default "string" ]
The multienum datatype is similar to the enum datatype, except that the field can contain multiple values, separated by one or more characters from the separators list. If no separators option is present, the default separators are space (` ') and colon (`:').

enumerated-in-file {
path "filename"
fields {
"name" [ "name" ... ]
} key "name"
[ allow-any-value ]
The enumerated-in-file type is used to describe an enumerated field with an associated administrative file which lists the legal values for the field, and may optionally contain additional fields that can be examined by query clients or used for other internal purposes. It is similar to the enum datatype, except that the list of legal values is stored in a separate file.

filename is the name of a file in the `gnats-adm' administrative directory for the database.

The format of the administrative file should be simple ASCII. Fields within the file are separated with colons (`:'). Lines beginning with a hash sign (`#') are ignored as comments. Records within the file are separated with newlines.

The field option is used to name the fields in the administrative file. There must be at least one field, which is used to list the legal values for the field. If the administrative file is empty (or does not contain any non-empty non-comment lines), the PR field must be empty.

The key option is used to designate which field in the administrative file should be used to list the legal values for the PR field. The value must match one of the field names in the field option.

If the allow-any-value option is present, the value of the PR field is not required to appear in the administrative file -- any value will be accepted.

The date datatype is used to hold dates. Date fields must either be empty or contain a correctly formatted date.

No defaults or other options are available. The field is left empty if no value for the field is given in the initial PR.

integer [ { default "integer" } ]
Integer fields are used to hold numbers. They must either be empty or contain a value composed entirely of digits, with an optional leading sign.

If the default option is present, the field will have the value of integer if the field is not given a value when the PR is initially created. Otherwise, the field will be left empty.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.4 Edit controls

The on-change subsection of a fields section specifies one or more actions to be performed when the field value is edited by the user. It has the general form

on-change [ "query-expression" ] {

[ add-audit-trail ]
[ audit-trail-format { format "formatstring" [ fields { "fieldname" ... } ] } ]
[ require-change-reason ]
[ set-field | append-to-field "fieldname" { "format-string" [ fieldlist ] } ] }

The optional query-expression controls whether or not the actions in the on-change section are taken. If the expression fails to match, the actions are skipped.

The add-audit-trail option indicates that an entry should be appended to the PR's audit-trail when this field is changed. The format of the entry is controlled by the optional audit-trail-format section within the field, or by the global audit-trail-format section.

The require-change-reason option specifies that a change reason must be present in the PR when this field is edited. This option only makes sense if an audit-trail entry is required, as the change reason is otherwise unused.

The set-field and append-to-field options are used to change the value of the field fieldname in the PR. The supplied format is used to format the value that will be placed in the field.

append-to-field appends the resulting formatted string to the existing, while set-field completely replaces the contents.

Any field may be edited by the set-field or append-to-field option (the read-only option on a field is ignored). However, the changes are subject to the usual field content checks.

There is also a global on-change section that is executed once for each PR edit. A typical use for such a section is to set the last-modified date of the PR.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.5 Named query definitions

When queries are performed via query-pr, they can refer to a query format described by a query section in the `dbconfig' file:

query "queryname" {
  format "formatstring"
  [fields { "fieldname" [ "fieldname" ... ] } ]

formatstring is as described in XXX refer to query-pr XXX. It contains a string with printf-like % escapes. The output of the query is then formatted as specified by the format string.

The fields option lists the fields to be used with the format string. If the fields option is present without a format option, the contents of the listed fields are printed out, separated by newlines.

The named query formats full, standard amd summary must be present in the `dbconfig' file. full and summary correspond to the query-pr options --full and --summary, while standard is used when no format option is given to query-pr.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.6 Audit-trail formats

These formats are similar to the named query formats, but they include more options. They are used for formatting audit-trail entries and for outgoing email messages.

There is currently only one audit-trail format, defined by the audit-trail-format option:

audit-trail-format {
  format "formatstring"
  [ fields { "fieldname" [ "fieldname" ... ] } ]

For those fields that require an audit-trail entry, the audit-trail text to be appended is formatted as described by this format. The per-field audit-trail-format is used in preference to this one, if it exists.

formatstring and fieldname are similar to those used by the named query format. fieldname may also be a format parameter, which is a context-specific value. (Format parameters are distinguished from fieldnames by a leading dollar sign (`$')).

The following format parameters are defined for audit-trail-format entries:

The name of the field for which an audit-trail entry is being created.

The old value of the field.

The new field value.

The email address of the user editing the field.

The current date.

The reason for the change; may be blank if no reason was supplied.

These parameters may be used anywhere a fieldname can appear.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.7 Outgoing email formats

During the life of a PR, GNATS can be configured to send out a range of email messages. When a PR first arrives, an acknowledgment message is sent out if the send-submitter-ack parameter above is set to true. Certain edits to the PR may also cause email to be sent out to the various parties, and if a PR is deleted, GNATS may send notification email.

The formats of the email messages are controlled by mail-format sections in the `dbconfig' file. The general structure of a mail-format section is as follows:

mail-format "format-name" {
  from-address {
    [ fixed-address "address" ]
    [ email-header-name | [ mail-header-name | ... ] ]
  to-address {
    [ fixed-address "address" ] 
    [ "email-header-name" | [ "mail-header-name" | ... ] ]
  reply-to {
    [ fixed-address "address" ]
    [ "email-header-name" | ... ] | [ "gnats-field-name" | ... ]
  header {
    format "formatstring"
    [ fields { "fieldname" [ "fieldname" ... ] } ]
  body {
    format "formatstring"
    [ fields { "fieldname" [ "fieldname" ... ] } ]

gnats recognizes and uses 6 different format-name values:

Format of the message used when mailing an initial response back to the PR submitter. This message will only be sent if send-submitter-ack in the overall database configuration is set to true.

Format of the message sent to the responsible parties when a new PR with category different from "pending" arrives.

Format of the message sent to the responsible parties when a new PR that ends up with category "pending" arrives.

Format of the notification message sent out when a response to a PR is received via email.

Format of the message sent out when a PR edit generates an Audit-Trail entry.

Format of the message sent out when a PR is deleted.

The from-address, to-address and reply-to subsections of a mail-format section specify the contents of the To:, From: and Reply-To: headers in outgoing email. There are two ways to specify the contents: by using a fixed-address specification, or by specifying email-header-names and gnats-field-names separated by the (`|') symbol.

When email-header-name and/or gnats-field-name values are given, GNATS will attempt to extract email addresses from the specified locations, in turn until it finds a header or field which is nonempty. The following example should clarify this:

mail-format "initial-response-to-submitter" {
  from-address {
    fixed-address "gnats-admin"
  to-addresses {
    "Reply-To:" | "From:" | "Submitter-Id"

This partial mail-format section specifies the format of the address headers in the email message that is sent out as an acknowledgment of a received PR. The From: field of the message will contain the email address of the GNATS administrator, as specified by the gnats-admin line in the `responsible' file. To fill in the To: header, GNATS will first look for the mail header Reply-To: in the PR and use the contents of that, if any. If that header doesn't exist or is empty, it will look for the contents of the From: email header, and if that is without results, it will look for the GNATS Submitter-Id field and use the contents of that.

Other email headers to be included in messages sent out by GNATS can be specified by header subsections of the mail-header section. formatstring and fieldname are similar to those used by the named query format. Each header line must have a newline character (`\n') at the end.

The email message body is specified in the body subsection of the mail-format section. Just as for a header section, the body section must contain a formatstring and fieldname values.

For some of the formats that GNATS recognizes, special variables are available for use. The following table lists the formats that provide special variables. See the example below for an illustration of how they are used.

The From: line of the original message.

The To: line of the original message.

The Subject: line of the original message.

The CC: line of the original message.

The text of the new audit trail entry (corresponds to the body of the message).

The email address of the user editing the PR.

The previous Responsible field entry, if it was changed.

The Audit-Trail: entries that have been appended by the edits.

The email address of the user deleting the PR.

The number of the PR that was deleted.

The following example illustrates the use of these special variables:

mail-format "deleted-pr-mail" {
  from-address {
  to-addresses {
    fixed-address "gnats-admin"
  header {
    format "Subject: Deleted PR %s\n"
    fields { "$PRNum" }
  body {
    format "PR %s was deleted by user %s.\n"
    fields { "$PRNum" "$EditUserEmailAddr" }

This mail-format section specifies the format of the email message that is sent out when a PR is deleted. The From: field is set to the email address field of the user who deleted the PR, the subject of the message contains the number of the deleted PR, and the message body contains both the PR number and the user's email address.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.8 Index file description

The index section of the `dbconfig' file lists the fields that appear in the database index. The index is always keyed by PR number. The general format for the index section is

index {
  path "file"
  fields { "fieldname" [ "fieldname" ... ] }
  binary-index true | false
  [ separator "symbol" ]

The path parameter gives the name of the index file in the `gnats-adm' directory of the database. Only one index is allowed per database, so only one path entry is allowed.

The fields parameter controls what fields will appear, and in what order, in the index. Fields are listed by their names, separated by spaces (` '). Fields will appear in the order they are listed.

The binary-index parameter controls whether the index is supposed to be in plaintext or binary format. Binary format is recommended, as it avoids potential problems when field separators appear as bona-fide field contents.

When plaintext format is used, by setting binary-index false, the symbol (`|') is used as a field separator in the index, unless the optional separator parameter is used to redefine the separator character.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.9 Initial PR input fields

An initial-entry section in the `dbconfig' file is used to describe which fields should be present on initial PR entry; this is used by tools such as send-pr to determine which fields to include in a "blank" PR template. The general format for the initial-entry section is

initial-entry {
  fields { "fieldname" [ "fieldname" ... ] }

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 Other database-specific config files

3.4.1 The categories file   
3.4.2 The responsible file   
3.4.3 The submitters file   
3.4.4 The states file   
3.4.5 The addresses file   
3.4.6 The classes file   

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.1 The categories file

The `categories' file contains a list of problem categories, specific to the database, which GNATS tracks. This file also matches responsible people with these categories. You must edit this file initially, creating valid categories. In most installations, GNATS is configured to create directories on disk for valid categories automatically as needed (see section Overall database configuration). If GNATS isn't set up to do this, you need to run mkcat to create the corresponding subdirectories of the database directory. For instructions on running mkcat, see Adding a problem category.

To create a new category, log in as GNATS, add a line to this file, and run mkcat if applicable. Lines beginning with `#' are ignored.

A line in the `categories' file consists of four fields delimited by colons, as follows:


A unique category name, made up of text characters. This name cannot contain spaces or any of the following characters:

! $ & * ( ) { } [ ] ` ' " ; : < > ~

Ideally, category names should not contain commas or begin with periods. Each line has a corresponding subdirectory in the database directory.

A terse textual description of the category.

The name tag of the party responsible for this category of problems, as listed in the `responsible' file (see section The responsible file).

One or more other parties which should be notified when a Problem Report with this category arrives, such as a project manager, other members of the same project, other interested parties, or even log files. These should be separated with commas.

A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for.

rock:ROCK program:me:myboss,fred
stone:STONE utils:barney:fred
iron:IRON firewall:me:firewall-log

In the above example, the nametags `myboss', `me', `fred', and `barney' must be defined in the `responsible' file (see section The responsible file).

Problem Reports with a category of `rock' are sent to the local mail address (or alias) `me', and also sent to the addresses `myboss' and `fred'. PRs with a category of `stone' are sent to the local addresses `barney' and `fred' only, while PRs with the category `iron' are sent only to `me', and are also filed in firewall-log (in this case, a mail alias should be set up, see section Setting up mail aliases.

If you want to separate PRs in each problem category into specific subsets, say documentation and software bugs, using the `classes' file is recommended. See section The `classes' file.

Only one category must be present for GNATS to function:

pending:Non-categorized PRs:gnats-admin:

The `pending' directory is created automatically when you run mkdb to initialize a new database. (see section Configuring and compiling the software).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.2 The responsible file

This file contains a list of the responsible parties. Lines beginning with `#' are ignored. Each entry contains three fields, separated by colons:


A name-tag description of the party in question, such as her or his user name, or the name of the group. This name is listed in the PR in the `>Responsible:' field.

The full name of the party ("Charlotte Bronte"; "Compiler Group").

The full, valid mail address of the party. This field is only necessary if the responsible party has no local mail address or alias.

A sample `responsible' listing might be:

ren:Ren Hoek:
stimpy:Stimpson J. Cat:stimpy@lederhosen.org

Here, ren is a local user. stimpy is remote, so his full address must be specified.

The following entry must be present for GNATS to function:

gnats-admin:GNATS administrator:

gnats-admin is usually defined as a mail alias when GNATS is installed, so for this purpose gnats-admin is a local address. However, this line can alos be used to redefine the email address of the GNATS administrator, by adding the desired address at the end of the line.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.3 The submitters file

This is a database of sites which submit bugs to your support site. It contains six fields delineated by colons. Lines beginning with `#' will be ignored.

Entries are of the format:


A unique identifier for a specific site or other entity who submits Problem Reports. The first submitter-id listed in the file will be the default for PRs that arrive with invalid or empty submitter fields.

The full name or a description of this entity.

Optional description for the type of relationship of this submitter to your support site. This could indicate a contract type, a level of expertise, etc., or it can remain blank.

Optional quoted response time in business hours. If the database `dbconfig' file has the notify-about-expired-prs entry set to true (see section Overall database configuration, GNATS will use this field to schedule when GNATS should notify the gnats-admin, responsible person and submitter contact that the PR wasn't analyzed within the agreed response time. Business hours and business-week days are set in the `dbconfig' file. For information on at-pr, the program which sends out this reminder, see Timely Reminders.

The name tag of the main contact at the Support Site for this submitter. This contact should be in the `responsible' file (see section The responsible file). Incoming bugs from submitter are sent to this contact. Optionally, this field can be left blank.

Any other parties who should receive copies of Problem Reports sent in by submitter. They need not be listed in the `responsible' file.

A few example entries in the `submitters' file:

univ-hell:University of Hades:eternal:3:beelzebub:lucifer
tta:Telephones and Telegraphs of America:support:720:dave:

In this example, when a PR comes in from the University of Hades (who has an eternal contract), it should have `univ-hell' in its `Submitter-Id' field. This Problem Report goes to beelzebub (who should be in the `responsible' file), and if it is not analyzed within three business hours a reminder message is sent. lucifer also receives a copy of the bug, and a copy of the reminder message as well (if it is sent). When Telephones and Telegraphs of America utilizes their support contract and submits a bug, a copy is sent only to dave, who has 720 business hours to return an analysis before a reminder is sent.

To disable the feature of GNATS which tracks the `>Submitter-Id:', simply alter the `submitters' file to only contain one submitter-id value, and instruct your submitters to ignore the field.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.4 The states file

This file lists the possible states for Problem Reports. Each line consists of a state, followed optionally by colon and a one-line description of what the state means. Lines beginning with `#' will be ignored.

state:optional descriptive text

State names can contain any alphanumeric character, `-' (hyphen), `_' (underscore), or `.' (period), but no other characters. The state name ends with a newline, or else with a colon followed by optional descriptive text. The descriptive text, if present, can contain any character except newline, which marks the end of the description. Empty or all-whitespace descriptions are allowed. This is not recommended, however, since although GNATS doesn't use this field, external tools might.

The first state listed will be the state automatically assigned to Problem Reports when they arrive; by default this is named "open". The last state listed is the end state for Problem Reports -- one should usually assume that a PR in this state is not being actively worked on; by default this state is named "closed".

It is probably best to leave "open" as the first state and "closed" as the last, otherwise some external tools looking for those two states by name may be fooled.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.5 The addresses file

This file contains mappings between submitter IDs and corresponding e-mail addresses.

When a PR comes in without a submitter ID (if someone sends unformatted e-mail to the PR submission email address), GNATS will try to derive the submitter ID from the address in the "From:" header. The entries in this file consist of two fields, separated by a colon:


A valid submitter ID

Part of all of the e-mail address to be matched

Here is an example of an addresses file:

# Addresses for Yoyodine Inc
# Addresses for Foobar Inc.

GNATS checks each line in the addresses file, comparing address-fragment to the end of the "From:" header, until it finds a match. If no match is found, GNATS uses the default submitter ID.

You can only have one address fragment per line, but you can have more than one line for a given submitter ID. An address fragment can be a domain (i.e. yoyodine.com), a machine location (admin.foobar.com), or a full e-mail address (clark@research.foobar.com).

GNATS can match addresses in three e-mail formats:

From: name@address.com
The address by itself without a full name, not enclosed in brackets

From: Real Person <name@address.com>
A full name (optional, with or without quotation marks), followed by the address enclosed in angle brackets

From: name@address.com (Real Person)
An address, followed by a name or comment in parentheses

If GNATS sees other e-mail address formats, it uses the default submitter ID.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.6 The classes file

This file lists the possible classes of Problem Reports. Each line consists of a class name, followed by a colon and an optional class type name (the class type name is not used for anything in the current implementation of GNATS, so it may be left blank. The class and class-type-name fields may only contain alphanumerics, `-', `_', and `.', but no other characters.

Then comes another colon, followed by an optional one-line description of the class. GNATS itself does not use the class description, but external tools such as Gnatsweb and TkGnats may use it. Therefore, a line in this file should at least contain the following:

class::class description

Lines beginning with `#' will be ignored, and the first listed class is the default class for an incoming Problem Report.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 Administrative data files

The following files are database-specific and are located in the `gnats-adm' subdirectory of the database directory. These files are maintained by GNATS; you should never need to touch them.

3.5.1 The index file    The `index' file
3.5.2 The current file    The `current' file

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.1 The index file

The index is used to accelerate searches on the database by query-pr and edit-pr. This file is not created until the first PR comes in. It is then kept up to date by GNATS; you should never touch this file.

Searches on subjects contained in the index are much faster than searches which depend on data not in the index. Inexes come in two different formats: binary and plain-text. Binary indexes are safer, in that they avoid certain problems that may crop up if the field separators used by plain-text indexes appear in field data.

A plain-text index contains single-line entries for all PR fields except for the multitext fields such as Description, How-To-Repeat, etc. Fields are separated by bars (`|') except for `>Category:' and `>Number:', which are separated by a slash (`/').

Binary indexes are not meant to be human-readable, but they are safer than the plain-text variety, in that they avoid certain problems that may crop up if the field separators used by plain-text indexes appear in field data.

The format of the index for a database is set in the `dbconfig' file. See section Index file description.

Should the `index' file become corrupted, the gen-index utility can be used to regenerate it. See section Regenerating the index.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2 The current file

This file contains the last serial number assigned to an incoming PR. It is used internally by GNATS; you need never touch this file.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6 Administrative utilities

These tools are used by the GNATS administrator as part of the periodic maintenance and configuration of GNATS. See section GNATS Administration.

3.6.1 Initializing a new database   
3.6.2 Adding a problem category   
3.6.3 Removing a problem category   
3.6.4 Regenerating the index   

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6.1 Initializing a new database

To initialize a new GNATS database:

  1. Add a line for the new database in the `databases' file (see section Where GNATS lives.

  2. Run mkdb, using

    mkdb directory

Where directory is the directory you specified in the `databases' file. mkdb creates this directory and populates it with the directories `pending', `gnats-queue' and `gnats-adm'. A full set of sample configuration files is copied to the `gnats-adm' directory.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6.2 Adding a problem category

To add new categories to the database:

  1. Add a line to for each new category to the `categories' file in the gnats-adm directory of the database. See section The categories file.

  2. Run mkcat If applicable. If create-category-dirs is set to false in the database `dbconfig' file, you need to create category directories with mkcat. mkcat creates a subdirectory under the database directory for any new categories which appear in the `categories' file.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6.3 Removing a problem category

To remove a category from the database:

  1. Remove the Problem Reports from the subdirectories corresponding to the categories you wish to remove, or assign the PRs to new categories. All PRs for a given category reside in a subdirectory of the database directory, with the same name as the category.

  2. Run rmcat using

    rmcat category [ category
    ... ]

    where category is the category you wish to remove. You can specify as many categories as you wish as long as each category has no PRs associated with it. rmcat removes the directory where the Problem Reports for that category had been stored.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6.4 Regenerating the index

If your `index' file becomes corrupted, or if you need a copy of the current index for some reason, use

gen-index [ -n | --numeric ]
          [ -d databasename | --database=databasename ]
	  [ -o filename | --outfile=filename ]
          [ -i | --import ] [ -e | --export ]
          [ -h | --help] [ -V | --version ]

With no options, gen-index generates an index that is sorted by the order that the categories appear in the `categories' file. The index is generated in plaintext or binary format according to the value of binary-index in the `dbconfig' file (see section Index file description). The results are printed to standard output. The options are:

Sorts index entries numerically.

-d databasename
Specifies the database to index. If this option is left out, gen-index attempts to index the database with name taken from the the GNATSDB environment variable, and if that is undefined, the default database, as set when GNATS was built (usually default).

-o filename
Places output in filename rather than sending it to standard output.

Import the existing index file instead of re-indexing the database.

Force plaintext output.

Prints the usage for gen-index.

Prints the version number for gen-index.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7 Internal utilities

These tools are used internally by GNATS. You should never need to run these by hand; however, a complete understanding may help you locate problems with the GNATS tools or with your local implementation.

3.7.1 Handling incoming traffic   
3.7.2 Processing incoming traffic   
3.7.3 Timely reminders   
3.7.4 The edit-pr driver    The edit-pr driver

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7.1 Handling incoming traffic

The program queue-pr handles traffic coming into GNATS. queue-pr queues incoming Problem Reports in the `gnats-queue' directory of the database, and then periodically (via cron) passes them on to file-pr to be filed in the GNATS database. See section Installing GNATS.

The usage for queue-pr is as follows:

queue-pr [ -q | --queue ] [ -r | --run ]
         [ -f filename | --file=filename ]
         [ -d databasename | --database=databasename ]
         [ -h | --help] [ -V | --version ]

One of `-q' or `-r' (or their longer-named counterparts) must be present upon each call to queue-pr. These options provide different functions, as described below.

Accepts standard input as an incoming mail message, placing this message in an incrementally numbered file in the `gnats-queue' directory under GNATS_ROOT (see section Where GNATS lives).

Redirects files in the `gnats-queue' directory into the program file-pr one by one.

-f filename
Used with `-q' (or `--queue'), accepts the file denoted by filename as input rather than reading from standard input.

-d databasename
Specifies database to operate on. If this option is left out, the value of the GNATSDB environment variable is used, and if that is undefined, the default database name set when GNATS was built is used (usually default).

Prints the usage for gen-index.

Prints the version number for gen-index.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7.2 Processing incoming traffic

queue-pr hands off queued Problem Reports to file-pr one at a time. file-pr checks each Problem Report for correct information in its fields (particularly a correct `>Category:'), assigns it an identification number, and files it in the database under the appropriate category.

If the `>Category:' field does not contain a valid category value (i.e., matching a line in the categories file; see section The categories file), the PR is assigned to the default category, as set in the dbconfig file. If there is no default category defined, the PR is given a `>Category:' value of `pending' and is placed in the `pending' directory. The GNATS administrator is notified of the unplaceable PR.

file-pr assigns the Problem Report an identification number, files it in the GNATS database (under the default, if the `>Category:' field contains an invalid category), and sends acknowledgments to appropriate parties. For the default GNATS configuration, the person responsible for that category of problem (see section The categories file) and the person responsible for the submitter site where the PR originated (see section The submitters file) receive a copy of the PR in its entirety. Optionally, the originator of the PR receives an acknowledgment that the PR arrived and was filed (see section Changing your GNATS configuration).

The usage for file-pr is as follows:

file-pr [ -f filename | --file=filename ]
        [ -d databasename | --directory=databasename ]
	    [ -h | --help ] [ -V | --version ]
       network options:
        [ -H host | --host=host ]
        [ -P port | --port=port ]
        [ -v username | --user=username ]
        [ -w password | --passwd=password ]

file-pr requires no options in order to operate, and takes input from standard input (normally, the output of `queue-pr -r') unless otherwise specified. The options include:

-f filename
Uses filename as input rather than standard input.

-d databasename
Performs refiling operations on database. If this option is left out, the value of the GNATSDB environment variable is used, and if that is undefined, the default database name set when GNATS was built is used (usually default).

Prints the usage for file-pr.

Prints the version number for file-pr.

file-pr can file PRs across a network, talking to a remote gnatsd. The following options relate to network access:

-H host
Hostname of the GNATS server.

-P port
The port that the GNATS server runs on.

-v username
Username used to log into the GNATS server.

-w password
Password used to log into the GNATS server.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7.3 Timely reminders

at-pr creates a queued job using at which, after an allotted response time is past, checks the PR to see if its state has changed from `open'. When the PR is originally filed, file-pr checks the notify-about-expired-prs parameter in the `dbconfig' file. If this parameter is set to true, file-pr calls at-pr, which sets up the expiry check.

The `submitters' file contains the response time for each >Submitter-Id: (see section The submitters file). The time is determined in business hours, which are defined in the database's `dbconfig' file (see section Overall database configuration).

If the PR is still open after the requisite time period has passed, at-pr sends a reminder to the GNATS administrator, to the maintainer responsible for that submitter, and to the maintainer responsible for the PR with the following message:

To: submitter-contact responsible gnats-admin
Subject: PR gnats-id not analyzed in #hours hours

PR gnats-id was not analyzed within the acknowledgment period
of #hours business hours.  The pertinent information is:

 Submitter-Id: submitter
 Originator: full name of the submitter
 Synopsis: synopsis
 Person responsible for the PR: responsible

The GNU Problem Report Management System (GNATS)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7.4 The edit-pr driver

pr-edit does the background work for edit-pr, including error-checking and refiling newly edited Problem Reports, handling file and database locks and deletion of PRs. It can be called interactively, though it has no usable editing interface.

The usage for pr-edit is:

pr-edit   [ -l username | --lock=username ] [ -u | --unlockdb ]
          [ -L | --lockdb ] [ -U | --unlockdb ] [ -c | --check ]
          [ -C | --check-initial ] [ -s | --submit ]
          [ -a field | --append field=field ]
          [ -r field | --replace=field ] [ --delete-pr ]
          [ -p process-id | --process=process-id ]
          [ -d databasename | --database=databasename ]
          [ -f filename | --filename=filename ]
          [ -V | --version ]
          [ -h | --help ] [ -v username | --user=username ]
          [ -w passwd | --passwd=passwd ]
          [ -H host | --host=host ]
          [ -P port | --port=port ]
          [ -D | --debug ] [ PR number ]

A lock is placed on a Problem Report while the PR is being edited. The lock is simply a file in the `locks' subdirectory of the `gnats-adm' directory of the database, with the name `gnats-id.lock', which contains the name of the user who created the lock. user then "owns" the lock, and must remove it before the PR can be locked again, even by the same user(3). If a PR is already locked when you attempt to edit it, pr-edit prints an error message giving the name of the user who is currently editing the PR.

If you do not specify PR number, pr-edit reads from standard input. You must specify PR number for the functions which affect PR locks, `--lock=username' and `--unlock'.

Locks the database specified with the --database or -d option. No PRs may be edited, created or deleted while the database is locked. This option is generally used when editing the index file.

Unlocks the specified database. No check is made that the invoking user actually had locked the database in the first place; hence, it is possible for anyone to steal a database lock.

The --check options are used to verify that a proposed PR's field contents are valid. The PR is read in (either from stdin or a file specified with --filename), and its fields are compared against the rules specified by the database configuration of the selected database. Warnings are given for enumerated fields whose contents do not contain one of the required values or fields that do not match required regexps. --check-initial is used to verify initial PRs, rather than proposed edits of existing PRs.

Used to submit a new PR to the database. The PR is read in and verified for content; if the PR is valid as an initial PR, it is then added to the database. A zero exit code is returned if the submission was successful. Otherwise, the reason(s) for the PR being rejected are printed to stdout, and a non-zero exit code is returned.

The following options require a PR number to be given.

Deletes the specified PR from the database. The PR must be in a closed state, and not locked. Only the user gnats (or the user name specified instead of gnats during the building of GNATS) is permitted to delete PRs.

-l username
Locks the PR. username is associated with the lock, so the system administrator can determine who actually placed the lock on the PR. However, anyone is permitted to remove locks on a PR. If the optional --process or -p option is also given, that process-id is associated with the lock.

Unlocks the specified PR.

-a field
-r field
--append and --replace are used to append or replace content of a specific field within a PR. The new field content is read in from stdin (or from the file specified with the --filename option), and either appended or replaced to the specified field. The field contents are verified for correctness before the PR is rewritten. If the edit is successful, a zero exit status is returned. If the edit failed, a non-zero exit status is returned, and the reasons for the failure are printed to stdout.

PR number
If only a PR number is specified with no other options, a replacement PR is read in (either from stdin or the file specified with --filename). If the PR contents are valid and correct, the existing PR is replaced with the new PR contents. If the edit is successful, a zero exit status is re turned. If the edit failed, a non-zero exit status is returned, and the reasons for the failure are printed to stdout.

-d database
Specifies the database which is to be manipulated. If no database is specified, the default database name set when GNATS was built is used (usually default). This option overrides the database specified in the GNATSDB environment variable.

-f filename
For actions that require reading in a PR or field content, this specifies the name of a file to read. If --filename is not specified, the PR or field content is read in from stdin.

Prints the usage for pr-edit.

Prints the version number for pr-edit.

pr-edit can edit PRs across a network, talking to a remote gnatsd. The following options relate to network access:

-H host
Hostname of the GNATS server.

-P port
The port that the GNATS server runs on.

-v username
Username used to log into the GNATS server.

-w password
Password used to log into the GNATS server.

Used to debug network connections.