This is gnats.info, produced by makeinfo version 4.2 from gnats.texi.

START-INFO-DIR-ENTRY
* Keeping Track: (gnats).	GNU Problem Report Management System
END-INFO-DIR-ENTRY

   Copyright (C) 2002 Milan Zamazal Copyright (C) 1993, 1995, 2001 Free
Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: gnats.info,  Node: Outgoing email formats,  Next: Index file description,  Prev: Audit-trail formats,  Up: dbconfig file

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:

`initial-response-to-submitter'
     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'.

`initial-pr-notification'
     Format of the message sent to the responsible parties when a new
     PR with category different from "pending" arrives.

`initial-pr-notification-pending'
     Format of the message sent to the responsible parties when a new
     PR that ends up with category "pending" arrives.

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

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

`deleted-pr-mail'
     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-name's or `gnats-field-name's.

   When an `email-header-name' or `gnats-field-name' value is given,
GNATS will attempt to extract an email address from the specified
location.  If several values are given on the same line, separated by
`|' characters, GNATS will try to extract an address from each location
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 yields nothing, 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.

`appended-email-response'

    `$MailFrom'
          The From: line of the original message.

    `$MailTo'
          The To: line of the original message.

    `$MailSubject'
          The Subject: line of the original message.

    `$MailCC'
          The CC: line of the original message.

    `$NewAuditTrail'
          The text of the new audit trail entry (corresponds to the
          body of the message).

`audit-mail'

    `$EditUserEmailAddr'
          The email address of the user editing the PR.  Set by the
          `EDITADDR' `gnatsd' command or from the `responsible' file;
          if not available, user's local address is used.

    `$OldResponsible'
          The previous Responsible field entry, if it was changed.

    `$NewAuditTrail'
          The Audit-Trail: entries that have been appended by the edits.

`deleted-pr-mail'

    `$EditUserEmailAddr'
          The email address of the user deleting the PR.  Set by the
          `EDITADDR' `gnatsd' command or from the `responsible' file;
          if not available, user's local address is used.

    `$PRNum'
          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 {
         "$EditUserEmailAddr"
       }
       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.


File: gnats.info,  Node: Index file description,  Next: Initial PR input fields,  Prev: Outgoing email formats,  Up: dbconfig file

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.


File: gnats.info,  Node: Initial PR input fields,  Prev: Index file description,  Up: dbconfig file

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. An optional `require' parameter can be defined to
specify a subset of the `intial-entry' fields which must be assigned a
value upon initial creation of the PR.

   The general format for the `initial-entry' section is

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


File: gnats.info,  Node: Other config files,  Next: send-pr.conf file,  Prev: dbconfig file,  Up: Management

Other database-specific config files
====================================

* Menu:

* categories file::
* responsible file::
* submitters file::
* states file::
* addresses file::
* classes file::


File: gnats.info,  Node: categories file,  Next: responsible file,  Up: Other config files

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 (*note Overall database configuration: 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 *Note Adding a
problem category: mkcat.

   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:

     CATEGORY:DESCRIPTION:RESPONSIBLE:NOTIFY

CATEGORY
     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.

DESCRIPTION
     A terse textual description of the category.

RESPONSIBLE
     The name tag of the party responsible for this category of
     problems, as listed in the `responsible' file (*note The
     `responsible' file: responsible file.).

NOTIFY
     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 (*note The
`responsible' file: 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, *note Setting up mail aliases: 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.  *Note The `classes' file: 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.  (*note Configuring and compiling the
software: Configure and make.).


File: gnats.info,  Node: responsible file,  Next: submitters file,  Prev: categories file,  Up: Other config files

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:

     RESPONSIBLE:FULL-NAME:MAIL-ADDRESS

RESPONSIBLE
     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.

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

MAIL-ADDRESS
     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.


File: gnats.info,  Node: submitters file,  Next: states file,  Prev: responsible file,  Up: Other config files

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:

     SUBMITTER-ID:NAME:TYPE:RESP-TIME:CONTACT:NOTIFY

SUBMITTER-ID
     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.

NAME
     The full name or a description of this entity.

TYPE
     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.

RESP-TIME
     Optional quoted response time in "business hours".  If the
     database `dbconfig' file has the `notify-about-expired-prs' entry
     set to TRUE (*note Overall database configuration: Overall
     database configuration., GNATS will use this field to schedule
     when it 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 *Note Timely Reminders: at-pr.

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

NOTIFY
     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.


File: gnats.info,  Node: states file,  Next: addresses file,  Prev: submitters file,  Up: Other config files

The `states' file
-----------------

   This file lists the possible states for Problem Reports.  Each entry
has up to three fields, separated by colons.  Lines beginning with `#'
will be ignored.

     STATE:TYPE:DESCRIPTION

STATE
     The name of the state.  It may contain alphanumerics as well as
     `-' (hyphen), `_' (underscore), or `.' (period), but no other
     characters.

TYPE
     This is the type of the state.  This field is optional and it may
     contain alphanumerics as well as `-' (hyphen), `_' (underscore),
     or `.' (period), but no other characters.

     The concept of the type of a state recognizes that there may for
     instance be several possible states for a Problem Report which
     effectively means that the PR is closed and that there may be
     certain actions that need to be taken when a PR reaches a "closed
     state".  The problem may have been resolved, it might have been
     decided that the problem is unsolvable or simply that it won't be
     solved.  Some organizations may for instance wish to consider the
     "suspended" state as a state of type "closed".

     Currently, the only defined state types are "open" and "closed",
     the "open" type isn't currently used for anything while the
     "closed" type is only used to control the Closed-Date field of PRs.
     Changing the state of a PR to any state of type "closed" will set
     the Closed-Date field with a time stamp and changing the state of
     a PR from one "closed" state to another will leave the Closed-Date
     field as it was.  Changing the state of a PR from any state of type
     "closed" to a non-closed state will clear the Closed-Date field.

     The `--skip-closed' option of `query-pr' refers to all states of
     type "closed", not to a specific state name of "closed".

DESCRIPTION
     This is is an optional one-line description of what the state
     means.  Any character is okay in the description; a newline ends
     it.  GNATS itself does not currently use the description for
     anything, but certain external tools (such as TkGnats and
     Gnatsweb) look for it, so it's a good idea to include one for
     every state.

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".  Even if a different name has
been chosen for this state, GNATS will force this state to be of type
"closed".

   It is recommended that you keep the default names of "open" and
"closed" for the first and last states respectively, since there may be
external tools that depend on these names.


File: gnats.info,  Node: addresses file,  Next: classes file,  Prev: states file,  Up: Other config files

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:

     SUBMITTER-ID:ADDRESS-FRAGMENT

SUBMITTER-ID
     A valid submitter ID

ADDRESS-FRAGMENT
     Part of, or all of the e-mail address to be matched

Here is an example of an `addresses' file:

     # Addresses for Yoyodine Inc
     yoyodine:yoyodine.com
     yoyodine:yoyodine.co.uk
     # Addresses for Foobar Inc.
     foobar1:sales.foobar.com
     foobar2:admin.foobar.com
     foobar3:clark@research.foobar.com

   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.


File: gnats.info,  Node: classes file,  Prev: addresses file,  Up: Other config files

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.


File: gnats.info,  Node: send-pr.conf file,  Next: Admin files,  Prev: Other config files,  Up: Management

The `send-pr.conf' file
=======================

   This file contains some default values that need to be known in order
for `send-pr' to work properly.  This file needs to be copied to all
hosts where `send-pr' will be used.

   If GNATS was built with default options, the `send-pr.conf' file
should be placed in the `/usr/local/etc/gnats' directory.  However, if
the option `--sysconfdir' was used during building of GNATS, the
`send-pr.conf' file resides at the location given to this option.

   Entries in this file are on the format

     variable=VALUE

   The valid variables are:

`SUBMITTER'
     The default value to be used for the Submitter-Id field when
     `send-pr' is invoked.

`DEFAULT_RELEASE'
     The default value to be used for the Release field (only
     applicable if the Release field is defined in the `dbconfig' file.

`DEFAULT_ORGANIZATION'
     The default value to be used for the Organization field.  (only
     applicable if the Organization field is defined in the `dbconfig'
     file.

`MAILPROG'
     If the GNATS server can't be reached directly over the network,
     i.e. it is behind a firewall or suchlike, `send-pr' can be set up
     to submit Problem Reports by e-mail.  This is done by setting the
     `MAILPROG' variable to point to a mailer such as Sendmail.  If
     `MAILPROG' needs to have the address that the mail is being sent
     to specified on the command line, it should be specified here as
     well (for example, `MAILPROG=''mail bugs@foo.bar.com''' should
     work).  If Sendmail is used, use `MAILPROG=''/usr/lib/sendmail -oi
     -t'''.  See also `MAILADDR' and `TEMPLATE' below.

`MAILADDR'
     If using e-mail to submit PRs, this is the address that PRs should
     be sent to.

`TEMPLATE'
     When invoked, `send-pr' communicates directly over the network
     with the GNATS server to determine what fields to include in a
     correctly formatted Problem Report so that it can present the user
     with a template.  If the GNATS server can't be reached directly
     over the network, a template must be provided.  Set the `TEMPLATE'
     variable to point to a template file created on the GNATS server
     by using the command `send-pr -p'.  *Note Installing the user
     tools: Installing tools.


File: gnats.info,  Node: Admin files,  Next: Admin utils,  Prev: send-pr.conf file,  Up: Management

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.

* Menu:

* index file::      The `index' file
* current file::    The `current' file


File: gnats.info,  Node: index file,  Next: current file,  Up: Admin files

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. *Note Index file description: Index file description.

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


File: gnats.info,  Node: current file,  Prev: index file,  Up: Admin files

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.


File: gnats.info,  Node: Admin utils,  Next: Internal utils,  Prev: Admin files,  Up: Management

Administrative utilities
========================

   These tools are used by the GNATS administrator as part of the
periodic maintenance and configuration of GNATS.  *Note GNATS
Administration: Management.

* Menu:

* mkdb::          Adding another database
* mkcat::         Adding a problem category
* rmcat::         Removing a problem category
* gen-index::     Regenerating the index
* check-db::      Checking database health
* gnats-pwconv::  Managing user passwords


File: gnats.info,  Node: mkdb,  Next: mkcat,  Up: Admin utils

Adding another database
-----------------------

   To initialize a new GNATS database:

  1. Add a line for the new database in the `databases' file (*note
     Where GNATS lives: Locations..

  2. Run `mkdb', using

          mkdb DATABASE

     where DATABASE is the database you specified in the `databases'
     file.  `mkdb' creates the database 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.


File: gnats.info,  Node: mkcat,  Next: rmcat,  Prev: mkdb,  Up: Admin utils

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. *Note The `categories' file:
     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.


File: gnats.info,  Node: rmcat,  Next: gen-index,  Prev: mkcat,  Up: Admin utils

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.


File: gnats.info,  Node: gen-index,  Next: check-db,  Prev: rmcat,  Up: Admin utils

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 (*note Index file description:
Index file description.).  The results are printed to standard output.
The options are:

`-n'
`--numeric'
     Sorts index entries numerically.

`-d DATABASENAME'
`--database=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'
`--outfile=FILENAME'
     Places output in FILENAME rather than sending it to standard
     output.

`-i'
`--import'
     Import the existing index file instead of re-indexing the database.

`-e'
`--export'
     Force plaintext output.

`-h'
`--help'
     Prints the usage for `gen-index'.

`-V'
`--version'
     Prints the version number for `gen-index'.


File: gnats.info,  Node: check-db,  Next: gnats-pwconv,  Prev: gen-index,  Up: Admin utils

Checking database health
------------------------

   The `check-db' script is useful for performing periodic checks on
database health.  It accepts the following options:

`-d DATABASENAME'
`--database=DATABASENAME'
     Determines the database which to operate on.

`--all-databases'
     Check all GNATS databases on the system.  This option takes
     precedence over the `--database' option.

   If no option is given, the default database is checked.

   During its operation, `check-db' first attempts to lock DATABASE.
If this is not possible, it repeats the locking attempts for five
minutes; if it fails, it sends a mail message notifying the
administrator of the failure and exits.

   Once the database is locked, the script searches the database for
lock files that are more than 24 hours old.  Any old lock files are
reported to the administrator in a mail message.

   After checking for old lock files, it calls `gen-index' (*note
Regenerating the index: gen-index.) and compares the results with the
current `index' file of the database; any inconsistencies are reported
to the administrators in a mail message.

   After checking the index file for inconsistencies, the script unlocks
the database and exits.


File: gnats.info,  Node: gnats-pwconv,  Prev: check-db,  Up: Admin utils

Managing user passwords
-----------------------

   Older versions of GNATS, up to and including version 3.x, stored
user passwords in plaintext in the `gnatsd.user_access' files. Version 4
has the options of storing the password as MD5 or standard DES
`crypt()' hashes (as most UNIX versions do in the system password
files) as well as in plaintext. Since the password strings require a
prefix to indicate how they are encrypted, one is forced to convert the
old password files to a new format when upgrading to GNATS version 4.
*Note Upgrading from older versions: Upgrading.

   The `gnats-pwconv' tool takes care of converting the old password
files to the new format:

     gnats-pwconv [ -c | --crypt ] [ -m | --md5 ] [ -p | --plaintext ]
              [ -h | --help] [ -V | --version ] INFILE [OUTFILE]

   Unless the `--version' or `--help' options are given, exactly one
encryption method must be specified, as well as an input file. The
output file parameter is optional. If one is not specified, results will
be printed on standard output.


File: gnats.info,  Node: Internal utils,  Prev: Admin utils,  Up: Management

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.

* Menu:

* queue-pr::    Handling incoming traffic
* file-pr::     Processing incoming traffic
* at-pr::       Timely reminders
* pr-edit::     The edit-pr driver
* diff-prs::    The `diff-prs' tool
* pr-age::      The `pr-age' tool


File: gnats.info,  Node: queue-pr,  Next: file-pr,  Up: Internal utils

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.  *Note
Installing GNATS: Installation.

   The usage for `queue-pr' is as follows:

     queue-pr [ -q | --queue ] [ -r | --run ]
              [ -f FILENAME | --file=FILENAME ]
              [ -m KBYTES | --max-size=KBYTES ]
              [ -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.

`-q'
`--queue'
     Accepts standard input as an incoming mail message, placing this
     message in an incrementally numbered file in the `gnats-queue'
     directory under the database directory (*note Where GNATS lives:
     Locations.).

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

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

`-m KBYTES'
`--max-size=KBYTES'
     Do not process messages larger then KBYTES kilobytes.  Files
     larger than the limit are left for human intervention.

`-d DATABASENAME'
`--directory=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').

`-h'
`--help'
     Prints the usage for `gen-index'.

`-V'
`--version'
     Prints the version number for `gen-index'.


File: gnats.info,  Node: file-pr,  Next: at-pr,  Prev: queue-pr,  Up: Internal utils

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; *note The `categories'
file: 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 (*note The `categories' file: categories
file.) and the person responsible for the submitter site where the PR
originated (*note The `submitters' file: 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 (*note
Changing your GNATS configuration: GNATS configuration.).

   The usage for `file-pr' is as follows:

     file-pr [ -f FILENAME | --file=FILENAME ]
             [ -d DATABASENAME | --database=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'
`--filename=FILENAME'
     Uses FILENAME as input rather than standard input.

`-d DATABASENAME'
`--database=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').

`-h'
`--help'
     Prints the usage for `file-pr'.

`-V'
`--version'
     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'
`--host=HOST'
     Hostname of the GNATS server.

`-P PORT'
`--port=PORT'
     The port that the GNATS server runs on.

`-v USERNAME'
`--username=USERNAME'
     Username used to log into the GNATS server.

`-w PASSWORD'
`--passwd=PASSWORD'
     Password used to log into the GNATS server.


File: gnats.info,  Node: at-pr,  Next: pr-edit,  Prev: file-pr,  Up: Internal utils

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:' (*note The `submitters' file: submitters file.).  The
time is determined in "business hours", which are defined in the
database's `dbconfig' file (*note Overall database configuration:
Overall database configuration.).

   If the PR is urgent and 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)

   The PR is "urgent" if its priority is `critical' or if its priority
is `serious' and the severity is `high'.


File: gnats.info,  Node: pr-edit,  Next: diff-prs,  Prev: at-pr,  Up: Internal utils

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 ]
               [ -R REASON | --reason=REASON ]
               [ -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(1).  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'.

`-L'
`--lockdb'
     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.

`-U'
`--unlockdb'
     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.

`-c'
`--check'
`-C'
`--check-initial'
     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.

`-s'
`--submit'
     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.

`--delete-pr'
     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'
`--lock=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.

`-u'
`--unlock'
     Unlocks the specified PR.

`-a FIELD'
`--append=FIELD'

`-r FIELD'
`--replace=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.

`-R REASON'
`--reason=REASON'
     Certain PR fields are configured in the database configuration to
     require a short text describing the reason of every change that
     happens to them, *Note dbconfig file::.  If you edit a problem and
     change any of such fields, you must issue a short text, the REASON
     of the change, through this option.  If the option is used and no
     change-reason requiring field is actually changed, the option has
     no effect.

`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'
`--database=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'
`--filename=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.

`-h'
`--help'
     Prints the usage for `pr-edit'.

`-V'
`--version'
     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'
`--host=HOST'
     Hostname of the GNATS server.

`-P PORT'
`--port=PORT'
     The port that the GNATS server runs on.

`-v USERNAME'
`--username=USERNAME'
     Username used to log into the GNATS server.

`-w PASSWORD'
`--passwd=PASSWORD'
     Password used to log into the GNATS server.

`-D'
`--debug'
     Used to debug network connections.

   ---------- Footnotes ----------

   (1) This approach may seem heavy-handed, but it ensures that changes
are not overwritten.


File: gnats.info,  Node: diff-prs,  Next: pr-age,  Prev: pr-edit,  Up: Internal utils

The `diff-prs' tool
-------------------

   The `diff-prs' tool is invoked as follows:

     diff-prs PRFILE1 PRFILE2

   `diff-prs' simply reads the PRs contained in PRFILE1 and PRFILE2 and
returns a list of the fields that are different between the two.  No
output is produced if the PRs are identical.


File: gnats.info,  Node: pr-age,  Prev: diff-prs,  Up: Internal utils

The `pr-age' tool
-----------------

   The `pr-age' tool reports the time, in days and hours, since the PR
arrived.  Usage is

     pr-age  [ -d DATABASENAME | --database=DATABASENAME ]
             [ -H HOST | --host=HOST ]
             [ -P PORT | --port=PORT ]
             [ -v USERNAME | --user=USERNAME ]
             [ -w PASSWORD | --passwd=PASSWORD ]
             [ -h | --help ] [ -V | --version ]

   For an explanation of the arguments listed above, please refer to the
usage description for `file-pr' (*Note `file-pr': file-pr).


File: gnats.info,  Node: Locations,  Next: gnatsd,  Prev: Management,  Up: Top

Where GNATS lives
*****************

   We use a few conventions when referring to the installation structure
GNATS uses.  These values are adjustable when you build and install
GNATS (*note Installing GNATS: Installation.).

* Menu:

* prefix::
* exec-prefix::
* gnats-adm::
* defaults::                    Default installation locations


File: gnats.info,  Node: prefix,  Next: exec-prefix,  Up: Locations

PREFIX
======

   PREFIX corresponds to the variable `prefix' for `configure', which
passes it on to the `Makefile' it creates.  PREFIX sets the root
installation directory for "host-independent" files as follows:

the directory path of the default database
     `PREFIX/com'
site-wide configuration files
     `PREFIX/etc/gnats'
`man' pages
     `PREFIX/man'

`info' documents
     `PREFIX/info'

`include' files
     `PREFIX/include'

_etc..._
   The default value for PREFIX is `/usr/local', which can be changed
on the command line to `configure' using

     configure --prefix=PREFIX ...

*Note Configuring and compiling the software: Configure and make.

