xref: /dports/databases/gnats4/gnats-4.1.0/doc/gnats.info

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

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

   Copyright (C) 1993, 1995, 2001, 2002, 2003 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: Top,  Next: Introduction,  Up: (dir)

Overview
********

This manual documents GNATS, the GNU Problem Report Management System,
version 4.1.0.  GNATS is a bug-tracking tool designed for use at a
central "Support Site".  Users who experience problems use electronic
mail, web-based or other clients communicating with the GNATS network
daemon running at the support site or direct database submissions to
communicate these problems to "maintainers" at that Support Site.
GNATS partially automates the tracking of these "Problem Reports"
("PR"s) by:

   * organizing problem reports into a database and notifying
     responsible parties of suspected bugs;

   * allowing support personnel and their managers to edit and query
     accumulated bugs; and

   * providing a reliable archive of problems (and their subsequent
     solutions) with a given program.

   GNATS offers many of the same features offered by more generalized
databases, including editing, querying, and basic reporting.  The GNATS
database itself is an ordered repository for problem reports; each PR
receives a unique, incremental "PR number" which identifies it
throughout its lifetime.  For a discussion on the working system
adopted by GNATS, see *Note The database paradigm: Paradigm.

   You can access the submitting, editing, and querying functions of
GNATS from within GNU Emacs.  *Note The GNATS user tools: GNATS user
tools.

* Menu:

* Introduction::          Introducing GNATS.
* GNATS user tools::      The GNATS user tools.
* Installation::          Installing GNATS.
* Management::            GNATS Administration.
* Locations::             Where GNATS lives.
* gnatsd::                The GNATS network server.
* Access Control::        Controlling access to GNATS databases.
* Regexps::               Querying using regular expressions.
* dbconfig recipes::      Useful dbconfig tricks.
* Support::               GNATS related sites and mailing lists.
* Index::


File: gnats.info,  Node: Introduction,  Next: GNATS user tools,  Prev: Top,  Up: Top

1 Introducing GNATS
*******************

Any support organization realizes that a large amount of data flows back
and forth between the maintainers and the users of their products.  This
data often takes the form of problem reports and communication via
electronic mail.  GNATS addresses the problem of organizing this
communication by defining a database made up of archived and indexed
problem reports.

   GNATS was designed as a tool for software maintainers.  It consists
of several utilities which, when used in concert, formulate and
administer a database of Problem Reports grouped by site-defined
"problem categories".  It allows a support organization to keep track
of problems (hence the term "Problem Report") in an organized fashion.
Essentially, GNATS acts as an active archive for field-separated
textual data.

* Menu:

* Paradigm::       The database paradigm
* Flowchart::      Flowchart of GNATS activities
* States::         States of Problem Reports
* Fields::         Problem Report format


File: gnats.info,  Node: Paradigm,  Next: Flowchart,  Up: Introduction

1.1 The database paradigm
=========================

It is in your best interest as the maintainer of a body of work to
organize the feedback you receive on that work, and to make it easy for
users of your work to report problems and suggestions.

   GNATS makes this easy by automatically filing incoming problem
reports into appropriate places, by notifying responsible parties of the
existence of the problem and (optionally) sending an acknowledgment to
the submitter that the report was received, and by making these Problem
Reports accessible to queries and easily editable.  GNATS is a database
specialized for a specific task.

   GNATS was designed for use at a Support Site that handles a high
level of problem-related traffic.  It maintains Problem Reports in the
form of text files with defined "fields" (*note GNATS data fields:
Fields.).  The location of the database, as well as the categories it
accepts as valid, the maintainers for whom it provides service, and the
submitters from whom it accepts Problem Reports, are all definable by
the "Support Site".  *Note GNATS administration: Management.

   Each PR is a separate file within a main repository (*note Where
GNATS lives: Locations.).  Editing access to the database is regulated
to maintain consistency.  To make queries on the database faster, an
index is kept automatically (*note The `index' file: index file.).

   We provide several software tools so that users may submit new
Problem Reports, edit existing Problem Reports, and query the database.

   * `send-pr' is used by both product maintainers and the end users of
     the products they support to submit PRs to the database.

   * `edit-pr' is used by maintainers when editing problem reports in
     the database.

   * Maintainers, managers and administrators can use `query-pr' to
     make inquiries about individual PRs or groups of PRs.


   Other interfaces to GNATS include Gnatsweb, a web-based tool which
provides features for submitting and editing PRs and querying the
database, and TkGnats, a Tcl/Tk-based frontend.  These tools are
distributed together with GNATS.

   At the Support Site, a GNATS "administrator" is charged with the
duty of maintaining GNATS.  These duties are discussed in detail in
*Note GNATS Administration: Management, and generally include
configuring GNATS for the Support Site, editing PRs that GNATS cannot
process, pruning log files, setting up new problem categories, backing
up the database, and distributing `send-pr' so that others may submit
Problem Reports.

   Responsibility for a given Problem Report initially depends on the
category of the problem.  Optionally, an automated reminder can be sent
to the responsible person if a problem report is neglected for a
requisite time period.  *Note Overview of GNATS configuration: GNATS
configuration.

   GNATS does not have the ability to decipher random text.  If there
is no default category set, any problem reports which arrive in a
format GNATS does not recognize are placed in a separate directory
pending investigation by the GNATS administrator (*note GNATS
Administration: Management.).

   Once a problem is recorded in the database, work can begin toward a
solution.  A problem's initial "state" type is "open" (*note States of
Problem Reports: States.).  An acknowledgment may be sent to the
originator of the bug report (depending on whether this feature has
been switched on in the GNATS configuration).  GNATS forwards copies of
the report to the party responsible for that problem category and to
the person responsible for problems arriving from that submitter.

   When a problem has been identified, the maintainer can change its
state to "analyzed", and then to "feedback" when a solution is found.
GNATS may be configured so that each time the state of a PR changes,
the submitter of the problem report is notified of the reason for the
change.  If the party responsible for the PR changes, the previous
responsible party and the new responsible party receive notice of the
change.  The change and reason are also recorded in the `Audit-Trail'
field of the Problem Report.  (*Note Editing existing Problem Reports:
edit-pr.  For information on the `Audit-Trail' field, see *Note Problem
Report format: Fields.)

   When the originator of the Problem Report confirms that the solution
works, the maintainer can change the state to "closed".  If the PR
cannot be closed, the maintainer can change its state to "suspended" as
a last resort.  (For a more detailed description of the standard
states, see *Note States of Problem Reports: States.)

   It should be emphasized that what we describe here is the default way
that GNATS works, but as of version 4, GNATS is extremely customizable,
allowing sites to tailor almost every aspect of its behavior.  See for
instance *Note The `dbconfig' file: dbconfig file. and *Note States of
Problem Reports: States.)


File: gnats.info,  Node: Flowchart,  Next: States,  Prev: Paradigm,  Up: Introduction

1.2 Flowchart of GNATS activities
=================================

This informal flowchart shows the relationships of the GNATS tools to
each other and to the files with which they interoperate.



     +===========+       +===========+        +============+
     # USER SITE #       # USER SITE #        # USER SITE  #
     #           #       #           #        #            #
     # *send-pr* #       # *send-pr* #        # Web client #
     +=====|=====+       +=====|=====+        +=====|======+
           |                   V                    |
           `--------->    Email/gnatsd...   <-------'
                     ,--->     |
     +===============|=========|===================+
     # SUPPORT SITE  |         `---> /etc/aliases  #
     #          *send-pr*                |         #
     #     +-----------------------------V--------+#
     #     | GNATS        DATABASEDIR/gnats-queue/|#
     #     |                             |        |#
     #     |        _________            V        |#
     #     |       |*file-pr*|<--- *queue-pr -r*  |#
     #     |       |         |                    |#
     #  _  |       |  valid  |                    |#
     # |M| |       |Category?|N--.                |#
     # |A| |       |_________|   |      GNATS     |#
     # |I| |              Y|     |  ADMINISTRATOR |#
     # |N| |               |     |                |#
     # |T|<----------------|     |                |#
     # |A| |               |     |  .-> *edit-pr* |#
     # |I|--->*edit-pr*-.  |     V  |           | |#
     # |N| |            |  |DATABASEDIR/pending | |#
     # |E|<--*query-pr* |  |                    | |#
     # |R| |       |    |  |                    | |#
     # |S| |       |    V  V                    V |#
     # |_| |+------------------------------------+|#
     #     ||         GNATS Database             ||#
     #     ||  DATABASEDIR/CATEGORY/GNATS-ID     ||#
     #     |+------------------------------------+|#
     #     +--------------------------------------+#
     +=============================================+




File: gnats.info,  Node: States,  Next: Fields,  Prev: Flowchart,  Up: Introduction

1.3 States of Problem Reports
=============================

Each PR goes through a defined series of states between origination and
closure.  By default, the originator of a PR receives notification
automatically of any state changes.

   Unless your site has customized states (*note states file:
(gnats)states file.), GNATS uses these states:

"open"
     The initial state of a Problem Report.  This means the PR has been
     filed and the responsible person(s) notified.

"analyzed"
     The responsible person has analyzed the problem.  The analysis
     should contain a preliminary evaluation of the problem and an
     estimate of the amount of time and resources necessary to solve
     the problem.  It should also suggest possible workarounds.

"feedback"
     The problem has been solved, and the originator has been given a
     patch or other fix.  The PR remains in this state until the
     originator acknowledges that the solution works.

"closed"
     A Problem Report is closed ("the bug stops here") only when any
     changes have been integrated, documented, and tested, and the
     submitter has confirmed the solution.

"suspended"
     Work on the problem has been postponed.  This happens if a timely
     solution is not possible or is not cost-effective at the present
     time.  The PR continues to exist, though a solution is not being
     actively sought.  If the problem cannot be solved at all, it
     should be closed rather than suspended.


File: gnats.info,  Node: Fields,  Prev: States,  Up: Introduction

1.4 Problem Report format
=========================

The format of a PR is designed to reflect the nature of GNATS as a
database.  Information is arranged into "fields", and kept in
individual records (Problem Reports).

   A Problem Report contains two different types of fields: "Mail
Header" fields, which are used by the mail handler for delivery, and
"Problem Report" fields, which contain information relevant to the
Problem Report and its submitter.  A Problem Report is essentially a
specially formatted electronic mail message.

   Problem Report fields are denoted by a keyword which begins with `>'
and ends with `:', as in `>Confidential:'.  Fields belong to one of
eight data types as listed in *Note Field datatypes reference::.  As of
version 4 of GNATS all characteristics of fields, such as field name,
data type, allowed values, permitted operations, on-change actions etc.
are configurable.

   For details, see *note The `dbconfig' file: dbconfig file.

Example Problem Report
----------------------

   The following is an example Problem Report with the fields that
would be present in a standard GNATS configuration.  Mail headers are
at the top, followed by GNATS fields, which begin with `>' and end with
`:'.  The `Subject:' line in the mail header and the `Synopsis' field
are usually duplicates of each other.

     Message-Id:  MESSAGE-ID
     Date:        DATE
     From:        ADDRESS
     Reply-To:    ADDRESS
     To:          BUG-ADDRESS
     Subject:     SUBJECT

     >Number:       GNATS-ID
     >Category:     CATEGORY
     >Synopsis:     SYNOPSIS
     >Confidential: yes _or_ no
     >Severity:     critical, serious, _or_ non-critical
     >Priority:     high, medium _or_ low
     >Responsible:  RESPONSIBLE
     >State:        open, analyzed, suspended, feedback, _or_ closed
     >Class:        sw-bug, doc-bug, change-request, support,
     duplicate, _or_ mistaken
     >Submitter-Id: SUBMITTER-ID
     >Arrival-Date: DATE
     >Originator:   NAME
     >Organization: ORGANIZATION
     >Release:      RELEASE
     >Environment:
        ENVIRONMENT
     >Description:
        DESCRIPTION
     >How-To-Repeat:
        HOW-TO-REPEAT
     >Fix:
        FIX
     >Audit-Trail:
     APPENDED-MESSAGES...
     State-Changed-From-To: FROM-TO
     State-Changed-When: DATE
     State-Changed-Why:
        REASON
     Responsible-Changed-From-To: FROM-TO
     Responsible-Changed-When: DATE
     Responsible-Changed-Why:
        REASON
     >Unformatted:
        MISCELLANEOUS

* Menu:

* Field datatypes reference::
* Mail header fields::
* Problem Report fields::


File: gnats.info,  Node: Field datatypes reference,  Next: Mail header fields,  Up: Fields

1.4.1 Field datatypes reference
-------------------------------

The following is a short reference to the characteristics of the
different field types.

   For details, see *Note Field datatypes::.

`text'
     A one-line text string.

`multitext'
     Multiple lines of text.

`enum'
     The value in this field is required to be from a list of specified
     values, defined at the Support Site.

     (*Note The `dbconfig' file: dbconfig file, for details.

`multienum'
     Similar to the `enum' datatype, except that the field can contain
     multiple values.

`enumerated-in-file'
     Similar to `enum', but the allowed field values are listed in a
     separate file on the GNATS server.

`multi-enumerated-in-file'
     Similar to `enumerated-in-file', except that the field can contain
     multiple values.

`date'
     Used to hold dates.

`integer'
     Used to hold integer numbers.


File: gnats.info,  Node: Mail header fields,  Next: Problem Report fields,  Prev: Field datatypes reference,  Up: Fields

1.4.2 Mail header fields
------------------------

A Problem Report may contain any mail header field described in the
Internet standard RFC-822.  The `send-pr' tool can be configured either
to submit PRs to the support site by e-mail or by talking directly to
the `gnatsd' network daemon on the GNATS server.  This is also true for
other client tools such as Gnatsweb.  Even when these tools are set up
submit PRs directly to `gnatsd', they will still include mail header
fields that identify the sender and the subject in the submitted PR:

`To:'
     The mail address for the Support Site, automatically supplied by
     the tool used to submit the PR or by the originator if plain
     e-mail was used.

`Subject:'
     A terse description of the problem.  This field normally contains
     the same information as the `Synopsis' field.

`From:'
     Supplied automatically when PRs are submitted by plain e-mail and
     when well-behaved tools such as `send-pr' are used; should always
     contain the originator's e-mail address.

`Reply-To:'
     A return address to which electronic replies can be sent; in most
     cases, the same address as the `From:' field.

   One of the configurable options for GNATS is whether or not to
retain `Received-By' headers, which often consume a lot of space and
are not often used.  *Note The dbconfig file: dbconfig file.


File: gnats.info,  Node: Problem Report fields,  Prev: Mail header fields,  Up: Fields

1.4.3 Problem Report fields
---------------------------

In a standard GNATS installation, certain fields will always be present
in a Problem Report.  If a PR arrives without one or more of these
fields, GNATS will add them, and if they have default values set by the
configuration at the Support Site, they will be filled in with these
values.  Certain tools such as `send-pr' are set up to provide sensible
defaults for most fields (*note The send-pr.conf configuration file:
send-pr.conf file.)

   In the list below, the field type (`text', `multitext',
`enumerated', etc.) is supplied in parantheses.  The different field
types are explained briefly in *Note Field datatypes reference::.

`Submitter-Id'
     (`enumerated-in-file') A unique identification code assigned by the
     Support Site.  It is used to identify all Problem Reports coming
     from a particular site.  Submitters without a value for this field
     can invoke `send-pr' with the `--request-id' option to apply for
     one from the support organization.  Problem Reports from those not
     affiliated with the support organization should use the default
     value of `net' for this field.

     *Note The `submitters' file: submitters file, for details.

`Notify-List'
     (`text') Comma-separated list of e-mail-addresses of people to
     notify when the PR changes significantly, i.e. when the Audit-Trail
     changes.  This list is independent from the Notify subfield of
     entries in the `categories' file of the GNATS database.

`Originator'
     (`text') Originator's real name.  Note that the Submitter and
     Originator might not be the same person/entity in all cases.

`Organization'
     (`multitext') The originator's organization.

`Confidential'
     (`enum') Use of this field depends on the originator's relationship
     with the support organization; contractual agreements often have
     provisions for preserving confidentiality.  Conversely, a lack of a
     contract often means that any data provided will not be considered
     confidential.  Submitters should be advised to contact the support
     organization directly if this is an issue.

     If the originator's relationship to the support organization
     provides for confidentiality, then if the value of this field is
     `yes' the support organization treats the PR as confidential; any
     code samples provided are not made publicly available.

`Synopsis'
     (`text') One-line summary of the problem.  `send-pr' copies this
     information to the `Subject' line when you submit a Problem Report.

`Severity'
     (`enum') The severity of the problem.  By default, accepted values
     include:

    `critical'
          The product, component or concept is completely
          non-operational or some essential functionality is missing.
          No workaround is known.

    `serious'
          The product, component or concept is not working properly or
          significant functionality is missing.  Problems that would
          otherwise be considered `critical' are usually rated
          `serious' when a workaround is known.

    `non-critical'
          The product, component or concept is working in general, but
          lacks features, has irritating behavior, does something
          wrong, or doesn't match its documentation.

`Priority'
     (`enumerated') How soon the originator requires a solution.
     Accepted values include:

    `high'
          A solution is needed as soon as possible.

    `medium'
          The problem should be solved in the next release.

    `low'
          The problem should be solved in a future release.

`Category'
     (`enumerated-in-file') The name of the product, component or
     concept where the problem lies.  The values for this field are
     defined by the Support Site.  *Note The `categories' file:
     categories file, for details.

`Class'
     (`enumerated-in-file') The class of a problem in a default GNATS
     installation can be one of the following:

    `sw-bug'
          A general product problem.  (`sw' stands for "software".)

    `doc-bug'
          A problem with the documentation.

    `change-request'
          A request for a change in behavior, etc.

    `support'
          A support problem or question.

    `duplicate (PR-NUMBER)'
          Duplicate PR.  PR-NUMBER should be the number of the original
          PR.

    `mistaken'
          No problem, user error or misunderstanding.  This value can
          only be set by tools at the Support Site, since it has no
          meaning for ordinary submitters.

     *Note The `classes' file: classes file, for details.

`Release'
     (`text') Release or version number of the product, component or
     concept.

`Environment'
     (`multitext') Description of the environment where the problem
     occurred: machine architecture, operating system, host and target
     types, libraries, pathnames, etc.

`Description'
     (`multitext') Precise description of the problem.

`How-To-Repeat'
     (`multitext') Example code, input, or activities to reproduce the
     problem.  The support organization uses example code both to
     reproduce the problem and to test whether the problem is fixed.
     Include all preconditions, inputs, outputs, conditions after the
     problem, and symptoms.  Any additional important information
     should be included.  Include all the details that would be
     necessary for someone else to recreate the problem reported,
     however obvious.  Sometimes seemingly arbitrary or obvious
     information can point the way toward a solution.  See also *Note
     Helpful hints: Helpful hints.

`Fix'
     (`multitext') A description of a solution to the problem, or a
     patch which solves the problem.  (This field is most often filled
     in at the Support Site; we provide it to the submitter in case he
     or she has solved the problem.)

GNATS adds the following fields when the PR arrives at the Support Site:

`Number'
     (`enumerated') The incremental identification number for this PR.
     This is included in the automated reply to the submitter (if that
     feature of GNATS is activated; *note The `dbconfig' file: dbconfig
     file.).  It is also included in the copy of the PR that is sent to
     the maintainer.

     The `Number' field is often paired with the `Category' field as

          CATEGORY/NUMBER

     in subsequent email messages.  This is GNATS' way of tracking
     followup messages that arrive by mail so that they are filed as
     part of the original PR.

`State'
     (`enumerated') The current state of the PR.  In default GNATS
     installations, accepted values are:

    `open'
          The PR has been filed and the responsible person notified.

    `analyzed'
          The responsible person has analyzed the problem.

    `feedback'
          The problem has been solved, and the originator has been
          given a patch or other fix.  Support organizations may also
          choose to temporarily "park" PRs that are awaiting further
          input from the submitter under this state.

    `closed'
          The changes have been integrated, documented, and tested, and
          the originator has confirmed that the solution works.

    `suspended'
          Work on the problem has been postponed.

     The initial state of a PR is `open'.  *Note States of Problem
     Reports: States.

`Responsible'
     (`text') The person at the Support Site who is responsible for this
     PR.  GNATS retrieves this information from the `categories' file
     (*note The `categories' file: categories file.).

`Arrival-Date'
     (`date') The time that this PR was received by GNATS.  The date is
     provided automatically by GNATS.

`Date-Required'
     (`date') The date by which a fix is required.  This is up to the
     maintainers at the Support Site to determine, so this field is not
     available until after the PR has been submitted.

`Audit-Trail'
     (`multitext') Tracks related electronic mail as well as changes in
     the `State' and `Responsible' fields with the sub-fields:

    `State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE'
          The old and new `State' field values.

    `Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP'
          The old and new `Responsible' field values.

    `State-Changed-By: NAME'
    `Responsible-Changed-By: NAME'
          The name of the maintainer who effected the change.

    `State-Changed-When: TIMESTAMP'
    `Responsible-Changed-When: TIMESTAMP'
          The time the change was made.

    `State-Changed-Why: REASON...'
    `Responsible-Changed-Why: REASON...'
          The reason for the change.

     The `Audit-Trail' field also contains any mail messages received by
     GNATS related to this PR, in the order received.  GNATS needs to
     find a reference to the PR in the Subject field of received email
     in order to be able to file it correctly, see *Note Following up
     via direct email: follow-up via email.

`Unformatted'
     (`multitext') Any random text found outside the fields in the
     original Problem Report.

   During a Problem Report's journey from `open' to `closed', two more
fields, `Last-Modified' and `Closed Date' (both of type `date') will be
added.


File: gnats.info,  Node: GNATS user tools,  Next: Installation,  Prev: Introduction,  Up: Top

2 The GNATS User Tools
**********************

This chapter describes the user tools distributed with GNATS.  The
GNATS administrative and internal tools are described in *Note GNATS
Administration: Management. The user tools provide facilities for
initial submission, querying and editing of Problem Reports:

`send-pr'
     Used by anyone who has a problem with a body of work to submit a
     report of the problem to the maintainers of that work (*note
     Submitting Problem Reports: send-pr.).

`query-pr'
     Used to query the GNATS database (*note Querying the database:
     query-pr.).

`edit-pr'
     Used to edit Problem Reports (to record new data, to change the
     responsible party, etc.) (*note Editing existing Problem Reports:
     edit-pr.).

* Menu:

* Environment::       Environment variables and GNATS tools
* send-pr::           Submitting Problem Reports
* edit-pr::           Editing existing Problem Reports
* query-pr::          Querying the database
* Emacs::             The Emacs interface


File: gnats.info,  Node: Environment,  Next: send-pr,  Up: GNATS user tools

2.1 Environment variables and GNATS tools
=========================================

All the GNATS user tools honor the `GNATSDB' environment variable which
is used to determine which database to use.  For a local database, it
contains the name of the database to access.

   For network access via gnatsd, it contains a colon-separated list of
strings that describe the remote database in the form

     SERVER:PORT:DATABASENAME:USERNAME:PASSWORD

   Any of the fields may be omitted except for SERVER, but at least one
colon must appear; otherwise, the value is assumed to be the name of a
local database.

   If `GNATSDB' is not set and no command-line options are used to
specify the database, it is assumed that the database is local and that
its name is `default'.


File: gnats.info,  Node: send-pr,  Next: edit-pr,  Prev: Environment,  Up: GNATS user tools

2.2 Submitting Problem Reports
==============================

Use `send-pr' to submit Problem Reports to the database.  `send-pr' is
a shell script which composes a template for submitters to complete.

   You can invoke `send-pr' from a shell prompt, or from within GNU
Emacs using `M-x send-pr' (*note Submitting Problem Reports from Emacs:
Emacs submitting.)

* Menu:

* PR template::               The Problem Report template
* send-pr in Emacs::          Using send-pr from within Emacs
* send-pr from the shell::    Invoking send-pr from the shell
* Submitting via e-mail::     Submitting a Problem Report via direct e-mail
* Helpful hints::


File: gnats.info,  Node: send-pr from the shell,  Next: Submitting via e-mail,  Prev: send-pr in Emacs,  Up: send-pr

2.2.1 Invoking `send-pr' from the shell
---------------------------------------

     send-pr [ -b | --batch ]
             [ -d DATABASE | --database DATABASE ]
             [ -f FILE | --file FILE ]
             [ -p | --print ] [ --request-id ]
             [ -s SEVERITY | --severity SEVERITY ]
             [ -V | --version ] [ -h | --help ]

   Invoking `send-pr' with no options assumes that you want to submit
to the local GNATS database named DEFAULT and calls the editor named in
your environment variable `EDITOR' on a PR template for this database.

`-b'
`--batch'
     Suppresses printing of most of the messages `send-pr' usually
     prints while running.

`-d DATABASE, --database DATABASE'
     Specifies the database to which the PR is to be submitted; if no
     database is specified, the local database named `default' is
     assumed.  This option overrides the database specified in the
     `GNATSDB' environment variable.  DATABASE can also be set to a
     remote database by using the format for `GNATSDB' described in
     *Note Environment variables and GNATS tools: Environment.

`-f PROBLEM-REPORT'
`--file PROBLEM-REPORT'
     Specifies a file, PROBLEM-REPORT, where a completed Problem Report
     or a PR template exists.  `send-pr' verifies that the contents of
     the file constitute a valid PR and asks you if you want to edit it
     or send it directly.  If the PR text is invalid you will be told
     what is wrong and be given the option to edit it. If
     PROBLEM-REPORT is `-', `send-pr' reads from standard input.

`-p'
`--print'
     Displays the PR template for the specified database, or if the
     `-d' or `--database' options aren't specified, print the template
     for the local DEFAULT database.  No PR is submitted.

`--request-id'
     Sends a request for a `Submitter-Id' to the Support Site.

`-s SEVERITY'
`--severity SEVERITY'
     Sets the initial value of the `Severity' field to SEVERITY.

`-V'
`--version'
     Displays the `send-pr' version number and a usage summary.  No mail
     is sent.

`-h'
`--help'
     Displays a usage summary for `send-pr'.  No mail is sent.


File: gnats.info,  Node: send-pr in Emacs,  Next: send-pr from the shell,  Prev: PR template,  Up: send-pr

2.2.2 Using `send-pr' from within Emacs
---------------------------------------

You can use an interactive `send-pr' interface from within GNU Emacs to
fill out your Problem Report.  We recommend that you familiarize
yourself with Emacs before using this feature (*note Introduction:
(emacs)Introduction.).

   Call `send-pr' with `M-x send-pr'.(1)  `send-pr' responds with a
preconfigured Problem Report template.  The Emacs interface is
described in more detail in a separate section, *Note The Emacs
interface to GNATS: Emacs.

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

   (1) If typing `M-x send-pr' doesn't work, see your system
administrator for help loading `gnats.el' into Emacs.


File: gnats.info,  Node: PR template,  Next: send-pr in Emacs,  Up: send-pr

2.2.3 The Problem Report template
---------------------------------

Invoking `send-pr' presents a PR "template" with a number of fields
already filled in with default values for the database you are
submitting to.  Complete the template as thoroughly as possible to make
a useful bug report.  Submit only one bug with each PR.

   A template consists of three sections:

   * Comments

   * Mail Header

   * GNATS fields

   The *Comments section* at the top of the template contains basic
instructions for completing the Problem Report, as well as a list of
valid entries for the `Category' field.  One (and only one) of these
values should be placed in the `Category' field further down in the
Problem Report.

     SEND-PR: -*- send-pr  -*-
     SEND-PR: Lines starting with `SEND-PR' will be removed
     SEND-PR: automatically as well as all comments (the text
     SEND-PR: below enclosed in `<' and `>').
     SEND-PR:
     SEND-PR: Please consult the document `Reporting Problems
     SEND-PR: Using send-pr' if you are not sure how to fill out
     SEND-PR: a problem report.
     SEND-PR:
     SEND-PR: Choose from the following categories:

   The comments lines are all preceded by the string `SEND-PR:' and are
erased automatically when the PR is submitted.  The instructional
comments within `<' and `>' are also removed.  (Only these comments are
removed; lines you provide that happen to have those characters in
them, such as examples of shell-level redirection, are not affected.)

   The *Mail Header* section of the template contains a standard mail
header constructed by `send-pr'.  `send-pr' can be set up to submit PRs
by e-mail or by speaking directly to the GNATS server, but since this
header is part of the standard format of Problem Reports, `send-pr'
includes it even when it is set up to speak directly to the server.

     To: PR SUBMISSION ADDRESS
     Subject: _complete this field_
     From: YOUR-LOGIN@YOUR-SITE
     Reply-To: YOUR-LOGIN@YOUR-SITE
     X-send-pr-version: send-pr 4.1.0

`send-pr' automatically completes all the mail header fields except the
`Subject' line with default values.  (*Note Problem Report format:
Fields.)

   The *GNATS fields* below the mail header form the bulk of a GNATS
Problem Report.

   Each field is either automatically completed with valid information
(such as your `Submitter-Id') or contains a one-line instruction
specifying the information that field requires in order to be correct.
For example, the `Confidential' field expects a value of `yes' or `no',
and the answer must fit on one line; similarly, the `Synopsis' field
expects a short synopsis of the problem, which must also fit on one
line.  Fill out the fields as completely as possible.  *Note Helpful
hints: Helpful hints, for suggestions as to what kinds of information
to include.

   The mechanisms `send-pr' uses to fill in default values is as
follows: Your preconfigured `Submitter-Id' is taken from the local
`send-pr.conf' configuration file.  `send-pr' will set the `Originator'
field to the value of the `NAME' environment variable if it has been
set; similarly, `Organization' will be set to the value of
`ORGANIZATION'.  If these variables aren't set in you environment,
`send-pr' uses the values set in the local `send-pr.conf' configuration
file, if that exists.  If not, these values are left blank in the
template.  `send-pr' also attempts to find out some information about
your system and architecture, and places this information in the
`Environment' field if it finds any.

   In this example, words in _italics_ are filled in with
pre-configured information:

     >Submitter-Id: _your submitter-id_
     >Originator:   _your name here_
     >Organization:
         _your organization_
     >Confidential:<[ yes | no ] (one line)>
     >Synopsis:    <synopsis of the problem (one line)>
     >Severity:    <[non-critical | serious | critical](one line)>
     >Priority:    <[ low | medium | high ] (one line)>
     >Category:    <name of the product (one line)>
     >Class:       <[sw-bug | doc-bug | change-request | support]>
     >Release:     <release number (one line)>
     >Environment:
              <machine, os, target, libraries (multiple lines)>

     >Description:
            <precise description of the problem (multiple lines)>
     >How-To-Repeat:
            <code/input/activities to reproduce (multiple lines)>
     >Fix:
            <how to correct or work around the problem, if known
             (multiple lines)>

   When you finish editing the Problem Report, `send-pr' validates the
contents and if it looks OK either submits it directly to the GNATS
server or submits it by mail to the address named in the `To' field in
the mail header.

   If your PR contains one or more invalid field values, `send-pr'
places the PR in a temporary file named `/tmp/pbadNNNN' on your
machine.  NNNN is the process identification number given to your
current `send-pr' session.  If you are running `send-pr' from the
shell, you are prompted as to whether or not you wish to try editing
the same Problem Report again.  If you are running `send-pr' from
Emacs, the Problem Report is placed in the buffer `*gnats-send*'; you
can edit this file and then submit it with `C-c C-c'.


File: gnats.info,  Node: Submitting via e-mail,  Next: Helpful hints,  Prev: send-pr from the shell,  Up: send-pr

2.2.4 Submitting a Problem Report via direct e-mail
---------------------------------------------------

In addition to using `send-pr', there is another way to submit a
problem report.  You can simply send an e-mail message to the PR
submission e-mail address of the support site (This address should be
published by the support site.)

   When you send unformatted e-mail to this address, GNATS processes
the message as a new problem report, filling in as many fields from
defaults as it can:

`Synopsis'
     The `Synopsis' field is filled in by the `Subject' header of the
     e-mail message.

`Submitter ID'
     GNATS will try to derive the `Submitter' field from the address in
     the `From' header of the e-mail.

`Description'
     All of the text in the body of the e-mail message is put into the
     `Description' field.

   Other fields, such as `Category', `Version', `Severity', etc. are
set to default values as defined by the GNATS administrator.


File: gnats.info,  Node: Helpful hints,  Prev: Submitting via e-mail,  Up: send-pr

2.2.5 Helpful hints
-------------------

There is no orthodox standard for submitting effective bug reports,
though you might do well to consult the section on submitting bugs for
GNU `gcc' in *Note Reporting Bugs: (gcc)Bugs, by Richard Stallman.
This section contains instructions on what kinds of information to
include and what kinds of mistakes to avoid.

   In general, common sense (assuming such an animal exists) dictates
the kind of information that would be most helpful in tracking down and
resolving problems in software.
   * Include anything _you_ would want to know if you were looking at
     the report from the other end.  There's no need to include every
     minute detail about your environment, although anything that might
     be different from someone else's environment should be included
     (your path, for instance).

   * Narratives are often useful, given a certain degree of restraint.
     If a person responsible for a bug can see that A was executed, and
     then B and then C, knowing that sequence of events might trigger
     the realization of an intermediate step that was missing, or an
     extra step that might have changed the environment enough to cause
     a visible problem.  Again, restraint is always in order ("I set
     the build running, went to get a cup of coffee (Columbian, cream
     but no sugar), talked to Sheila on the phone, and then THIS
     happened...") but be sure to include anything relevant.

   * Richard Stallman writes, "The fundamental principle of reporting
     bugs usefully is this: *report all the facts*.  If you are not sure
     whether to state a fact or leave it out, state it!"  This holds
     true across all problem reporting systems, for computer software
     or social injustice or motorcycle maintenance.  It is especially
     important in the software field due to the major differences
     seemingly insignificant changes can make (a changed variable, a
     missing semicolon, etc.).

   * Submit only _one_ problem with each Problem Report.  If you have
     multiple problems, use multiple PRs.  This aids in tracking each
     problem and also in analyzing the problems associated with a given
     program.

   * It never hurts to do a little research to find out if the bug
     you've found has already been reported.  Most software releases
     contain lists of known bugs in the Release Notes which come with
     the software; see your system administrator if you don't have a
     copy of these.

   * The more closely a PR adheres to the standard format, the less
     interaction is required by a database administrator to route the
     information to the proper place.  Keep in mind that anything that
     requires human interaction also requires time that might be better
     spent in actually fixing the problem.  It is therefore in
     everyone's best interest that the information contained in a PR be
     as correct as possible (in both format and content) at the time of
     submission.


File: gnats.info,  Node: edit-pr,  Next: query-pr,  Prev: send-pr,  Up: GNATS user tools

2.3 Editing existing Problem Reports
====================================

Use `edit-pr' to make changes to existing PRs in the database.  This
tool can be invoked both from a shell prompt or from within GNU Emacs
using `M-x edit-pr'.

   `edit-pr' first examines the PR you wish to edit and locks it if it
is not already locked.  This is to prevent you from editing a PR at the
same time as another user.  If the PR you wish to edit is already in the
process of being edited, `edit-pr' tells you the name of the person who
owns the lock.

   You may edit any non-readonly fields in the database.  We recommend
that you avoid deleting any information in the TEXT and MULTITEXT
fields (such as `Description' and `How-To-Repeat' (*note Problem Report
format: Fields.).  We also recommend that you record the final solution
to the problem in the `Fix' field for future reference.  Note that
heavily customized installations of GNATS may have differently named
fields, and sites using such installations should provide their own set
of routines and instructions regarding how PRs should be treated
throughout their life span.

   After the PR has been edited, it is then resubmitted to the database,
and the index is updated (*note The `index' file: index file.).  For
information on `pr-edit', the main driver for `edit-pr', see *Note
Internal utilities: Internal utils.

   If you change a field that requires a reason for the change, such as
the `Responsible' or `State' fields in the default configuration,
`edit-pr' prompts you to supply a reason for the change.  A message is
then appended to the `Audit-Trail' field of the PR with the changed
values and the change reason.

   Depending on how the database is configured, editing various fields
in the PR may also cause mail to be sent concerning these changes.  In
the default configuration, any fields that generate `Audit-Trail'
entries will also cause a copy of the new `Audit-Trail' message to be
sent.

   Mail received at the PR submission email address and recognized by
GNATS as relating to an existing PR is also appended to the
`Audit-Trail' field, see *Note follow-up via email::.

* Menu:

* edit-pr from the shell::  Invoking `edit-pr' from the shell
* follow-up via email:: Following up via direct email


File: gnats.info,  Node: edit-pr from the shell,  Next: follow-up via email,  Up: edit-pr

2.3.1 Invoking `edit-pr' from the shell
---------------------------------------

The usage for `edit-pr' is:

     edit-pr [ -V | --version ] [ -h | --help ]
             [-d DATABASE | --database DATABASE] PR NUMBER

Network-mode-only options:

              [--host HOST | -H HOST] [--port PORT]
              [--user USER | -v USER]
              [--passwd PASSWD | -w PASSWD]

The options have the following meaning:

`-h, --help'
     Prints a brief usage message for edit-pr.

`-V, --version'
     Prints the version number for edit-pr.

`-d DATABASE, --database DATABASE'
     Specifies the database containing the PR to be edited; if no
     database is specified, the database named `default' is assumed.
     This option overrides the database specified in the `GNATSDB'
     environment variable.

`--host HOST, -H HOST'
     Specifies the hostname of the gnatsd server to communicate with.
     This overrides the value in the `GNATSDB' environment variable.

`--port PORT'
     Specifies the port number of the gnatsd server to communicate with.
     This overrides the value in the `GNATSDB' environment variable.

`--user USER, -v USER'
     Specifies the username to login with when connecting to the gnatsd
     server.  This overrides the value in the `GNATSDB' environment
     variable.

`--passwd PASSWD, -w PASSWD'
     Specifies the password to login with when connecting to the gnatsd
     server.  This overrides the value in the `GNATSDB' environment
     variable.

   `edit-pr' calls the editor specified in your environment variable
`EDITOR' on a temporary copy of that PR.  (If you don't have the
variable `EDITOR' defined in your environment, the default editor `vi'
is used.)

   Edit the PR, changing any relevant fields or adding to existing
information.  When you exit the editor, `edit-pr' prompts you on
standard input for a reason if you have changed a field that requires
specifying a reason for the change.


File: gnats.info,  Node: follow-up via email,  Prev: edit-pr from the shell,  Up: edit-pr

2.3.2 Following up via direct email
-----------------------------------

If you have some additional information for a PR and for some reason do
not want to (or cannot) edit the PR directly, you may append the
information to the Audit-Trail field by mailing it to the PR submission
address.

   In order for GNATS to be able to recognize the mail as pertaining to
an existing PR (as opposed to a new PR, see *Note Submitting via
e-mail::), the Subject mail header field must contain a reference to
the PR.  GNATS matches the Subject header against the regular expression

     \<(PR[ \t#/]?|[-[:alnum:]+.]+/)[0-9]+

to determine whether such a reference is present. Any text may precede
or follow the reference in the Subject header. If more than one
reference is present, the first is used and the rest ignored.

   A PR reference matching the regular expression above has two parts.
The second is the PR number (one or more digits). The first is either
the capital letters 'PR' optionally followed by a separator character
(blank, tab, hash mark or forward slash) or the category name followed
by a forward slash. Following are some examples which match the regular
expression:

     PR 123 PR4567 PR#890 gnats/4711

   The PR number and the category (if present) are checked for
existence, and if the outcome is positive, the mail is appended to the
Audit-Trail field of the PR. Note that the PR need not belong to the
category because PRs may move between categories.

   Outgoing emails sent by GNATS itself may be configured to have a
Subject header field that refers to the PR in question:

     Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT

   This makes it extremely easy to follow up on a PR by replying to
such an email, see *Note The `dbconfig' file: dbconfig file. and the
sample, default `dbconfig' file installed by `mkdb'.


File: gnats.info,  Node: query-pr,  Next: Emacs,  Prev: edit-pr,  Up: GNATS user tools

2.4 Querying the database
=========================

Obtain information from the database by using the program `query-pr'.
`query-pr' uses search parameters you provide to find matching Problem
Reports in the database.  You can invoke `query-pr' from the shell or
from within Emacs.  `query-pr' uses the same arguments whether it is
invoked from the shell or from Emacs.

   PRs may be selected via the use of the `--expr' option, directly by
number, or by the use of the (now deprecated) field-specific query
operators.

   By default, query options are connected with a logical AND.  For
example,

     query-pr --category=foo --responsible=bar

only prints PRs which have a Category field of `foo' and a Responsible
field of `bar'.

   The `--or' option may be used to connect query options with a logical
OR. For example,

     query-pr --category=baz --or --responsible=blee

prints PRs which have either a Category field of `baz' or a Responsible
field of `blee'.

   It should be emphasized, however, that the use of these
field-specific options is strongly discouraged, since they exist only
for compatibility with older versions of GNATS and are likely to be
deleted in the next release.  The expressions specified by the `--expr'
option are much more flexible (see below).

* Menu:

* Invoking query-pr::
* Formatting query-pr output::
* Query expressions::
* Example queries::


File: gnats.info,  Node: Invoking query-pr,  Next: Formatting query-pr output,  Up: query-pr

2.4.1 Invoking `query-pr'
-------------------------

From the shell, simply type `query-pr', followed by any search
parameters you wish to exercise.  From Emacs, type `M-x query-pr'.
`query-pr' prompts you for search parameters in the minibuffer.

   `query-pr' can also be accessed by electronic mail, if your version
of GNATS is configured for this.  To use this feature, simply send mail
to the address `query-pr@YOUR-SITE' with command line arguments or
options in the `Subject' line of the mail header.  GNATS replies to
your mail with the results of your query.  The default settings for the
`query-pr' mail server are

     --restricted --state="open|analyzed|feedback|suspended"

To override the `--state' parameter, specify `--state=STATE' in the
`Subject' line of the mail header.  You can not query on confidential
Problem Reports by mail.

   The usage for `query-pr' is:

     query-pr [--debug | -D] [--help | -h] [--version | -V]
              [--output FILE | -o FILE] [--list-databases]
              [--list-fields] [--list-input-fields]
              [--responsible-address NAME] [--field-type FIELD]
              [--field-description FIELD]
              [--field-flags FIELD]
              [--adm-field FIELD] [--adm-subfield SUBFIELD]
              [--adm-key KEY]
              [--valid-values FIELD]
              [--format FORMAT | -f FORMAT]
              [--full | -F] [--summary | -q]
              [--database DATABASE | -d DATABASE] [--and | -&]
              [--or | -|] [--expr EXPR] [PR Number]

   Non-network-mode options:

              [--print-sh-vars] [--print-directory-for-database]

   Network-mode-only options:

              [--host HOST | -H HOST] [--port PORT]
              [--user USER | -v USER] [--passwd PASSWD | -w PASSWD]
              [--print-server-addr]

   Deprecated Options:
              [--list-categories | -j] [--list-states | -T]
              [--list-responsible | -k] [--list-submitters | -l]
              [--category CATEGORY | -c CATEGORY]
              [--synopsis SYNOPSIS | -y SYNOPSIS]
              [--confidential CONFIDENTIAL | -C CONFIDENTIAL]
              [--multitext MULTITEXT | -m MULTITEXT]
              [--originator ORIGINATOR | -O ORIGINATOR]
              [--release RELEASE | -A RELEASE]
              [--class CLASS | -L CLASS] [--cases CASES | -E CASES]
              [--quarter QUARTER | -Q QUARTER]
              [--keywords KEYWORDS | -K KEYWORDS]
              [--priority PRIORITY | -p PRIORITY]
              [--responsible RESPONSIBLE | -r RESPONSIBLE]
              [--restricted | -R] [--severity SEVERITY | -e SEVERITY]
              [--skip-closed | -x] [--sql | -i] [--sql2 | -I]
              [--state STATE | -s STATE]
              [--submitter SUBMITTER | -S SUBMITTER]
              [--text TEXT | -t TEXT]
              [--required-before DATE | -u DATE]
              [--required-after DATE | -U DATE]
              [--arrived-before DATE | -b DATE]
              [--arrived-after DATE | -a DATE]
              [--modified-before DATE | -B DATE]
              [--modified-after DATE | -M DATE]
              [--closed-before DATE | -z DATE]
              [--closed-after DATE | -Z DATE]

   The options have the following meaning:
`--help, -h'
     Prints a help message.

`--version, -V'
     Displays the program version to stdout.

`--output FILE, -o FILE'
     The results of the query will be placed in this file.

`--database DATABASE, -d DATABASE'
     Specifies the database to be used for the query.  If no database is
     specified, the database named default is assumed.  (This option
     overrides the database specified in the `GNATSDB' environment
     variable; see *Note Environment:: for more information.)

`--list-categories, -j'
     Lists the available PR categories for the selected database.

`--list-states, -T'
     Lists the valid PR states for PRs in this database.

`--list-responsible, -k'
     Lists the users that appear in the database's responsible list.

`--list-submitters, -l'
     Lists the valid submitters for this database.

   The previous -list-* options are deprecated and may be removed in
future releases of GNATS; their functionality can be replaced with

     query-pr --valid-values FIELD

where FIELD is one of `Category', `Class', `Responsible',
`Submitter-Id', or `State'.

`--list-databases'
     Lists the known databases.

`--list-fields'
     Lists the entire set of field names for PRs in the selected
     database.

`--list-input-fields'
     Lists the fields that should be provided when creating a new PR
     for the currently-specified database.  The fields are listed in an
     order that would make sense when used in a template or form.

`--field-type FIELD'
     Returns the data type contained in PR field FIELD.  The current
     set of data types includes `text', `multitext', `enum',
     `multienum', `enumerated-in-file', `multi-enumerated-in-file',
     `date' and `integer'.

`--field-description FIELD'
     Returns a human-readable description of the intended purpose of
     FIELD.

`--field-flags FIELD'
     Returns the flags set for the field in the `dbconfig' file
     associated with the database, such as `textsearch' and `readonly'.
     *Note Individual field configuration::.

`--adm-field FIELD'
     Used together with the `--adm-key' option, this returns a record
     from the administrative file (if any) associated with the field.
     For more material on administrative files, see *Note Enumerated
     field administrative files: administrative files.

`--adm-subfield SUBFIELD'
     Used together with the `--adm-field' and `--adm-key' options, this
     returns the contents of a particular subfield from the record
     specified by `--adm-field' and `--adm-key'.  Subfields are treated
     in *Note Enumerated field administrative files: administrative
     files.

`--adm-key KEY'
     Used together with `--adm-field' to select a record from the
     administrative file associated with the field specified by
     `--adm-field'.  *Note Enumerated field administrative files:
     administrative files.

`--valid-values FIELD'
     For fields of type `enum', a list of valid values (one per line) is
     returned.  Otherwise, a regular expression is returned that
     describes the legal values in FIELD.

`--responsible-address NAME'
     The mail address of NAME is returned; NAME is assumed to be a name
     either appearing in the database's responsible list, or is
     otherwise a user on the system.

`--print-sh-vars'
     A set of `/bin/sh' variables is returned that describe the selected
     database.  They include:

    `GNATSDB'
          The name of the currently-selected database.

    `GNATSDB_VALID'
          Set to 1 if the selected database is valid.

    `GNATSDBDIR'
          The directory  where  the  database  contents  are stored.

    `DEBUG_MODE'
          Set to 1 if debug mode has been  enabled  for  the database.

    `DEFAULTCATEGORY'
          The default category for PRs in the database.

    `DEFAULTSTATE'
          The default state for PRs in the database.

`--print-server-addr'
     Prints the information about a remote server database in the format
     suitable for the `GNATSDB' environment variable.  This option
     works only in the network mode.

`--print-directory-for-database'
     Returns the directory where the selected database is located.

`--format FORMAT, -f FORMAT'
     Used to specify the format of the output PRs, See *Note Formatting
     query-pr output:: for a complete description.

`--full, -F'
     When printing PRs, the entre PR is displayed.  This is exactly
     equivalent to

          query-pr --format full

`--summary, -q'
     When printing PRs, a summary format is used.  This is exactly
     equivalent to

          query-pr --format SUMMARY

`--debug, -D'
     Enables debugging output for network queries.

`--host HOST, -H HOST'
     Specifies the hostname of the gnatsd server to communicate with.
     This overrides the value in the `GNATSDB' environment variable.

`--port PORT'
     Specifies the port number of the gnatsd server to communicate with.
     This overrides the value in the `GNATSDB' environment variable.

`--user USER, -v USER'
     Specifies the username to login with when connecting to the gnatsd
     server.  This overrides the value in the `GNATSDB' environment
     variable.

`--passwd PASSWD, -w PASSWD'
     Specifies the password to login with when connecting to the gnatsd
     server.  This overrides the value in the `GNATSDB' environment
     variable.

`--and, -&, --or, -|'
     These options are used when connecting multiple query operators
     together.  They specify whether the previous and subsequent
     options are to be logically ANDed or logically ORed.

`--expr EXPR'
     Specifies a query expression to use when searching for PRs.  *Note
     Query expressions::.

   The remaining deprecated options are not described here, since their
use is fairly obvious and their functionality is completely replaced by
the use of the `--expr' option.


File: gnats.info,  Node: Formatting query-pr output,  Next: Query expressions,  Prev: Invoking query-pr,  Up: query-pr

2.4.2 Formatting `query-pr' output
----------------------------------

Printing formats for PRs are in one of three forms:

FORMATNAME
     This is a named format which is described by the database
     (specifically, these formats are described in the `dbconfig' file
     associated with the database).  The default configuration contains
     five such formats: `standard', `full', `summary', `sql', and
     `sql2'.

     The first three are the ones most commonly used when performing
     queries.  standard is the format used by default if no other
     format is specified.

     Use of the latter two are discouraged; they are merely kept for
     historical purposes.  Other named formats may have been added by
     the database administrator.

FIELDNAME
     A single field name may appear here.  Only the contents of this
     field will be displayed.

'"PRINTF STRING" FIELDNAME FIELDNAME ...'
     This provides a very flexible mechanism for formatting PR output.
     (The formatting is identical to that provided by the named formats
     described by the database configuration, *Note Named query
     definitions::.  The PRINTF STRING can contain the following %
     sequences:

     `%[positionalspecifiers]s': Prints the field as a string.  The
     positional specifiers are similar to those of printf, as +, - and
     digit qualifiers can be used to force a particular alignment of
     the field contents.

     `%[positionalspecifiers]S': Similar to `%s', except that the field
     contents are terminated at the first space character.

     `%[positionalspecifiers]d': Similar to `%s', except that the field
     contents are written as a numeric value.  For integer fields, the
     value is written as a number.  For enumerated fields, the field is
     converted into a numeric equivalent (i.e. if the field can have two
     possible values, the result will be either 1 or 2).  For date
     fields, the value is written as seconds since Jan 1, 1970.

     `%F': The field is written as it would appear within a PR, complete
     with field header.

     `%D': For date fields, the date is written in a standard GNATS
     format.

     `%Q': For date fields, the date is written in an arbitrary "SQL"
     format.

   An example formatted query looks as follows (note that the whole
format specification should be quoted):

     query-pr --format '"%s, %s" Synopsis State'


File: gnats.info,  Node: Query expressions,  Next: Example queries,  Prev: Formatting query-pr output,  Up: query-pr

2.4.3 Query expressions
-----------------------

Query expressions are used to select specific PRs based on their field
contents.  The general form is

     fieldname|"value" operator fieldname|"value" [booleanop ...]

   VALUE is a literal string or regular expression; it must be
surrounded by double quotes, otherwise it is interpreted as a fieldname.

   FIELDNAME is the name of a field in the PR.

   OPERATOR is one of:

`='
     The value of the left-hand side of the expression must exactly
     match the regular expression on the right-hand side of the
     expression.  *Note Querying using regular expressions: Regexps.

`~'
     Some portion of the left-hand side of the expression must match the
     regular expression on the right-hand side.

`=='
     The value of the left-hand side must be equal to the value on the
     right-hand side of the expression.

     The equality of two values depends on what type of data is stored
     in the field(s) being queried.  For example, when querying a field
     containing integer values, literal strings are interpreted as
     integers.  The query expression

          Number == "0123"

     is identical to

          Number == "123"

     as the leading zero is ignored.  If the values were treated as
     strings instead of integers, then the two comparisons would return
     different results.

`!='
     The not-equal operator. Produces the opposite result of the ==
     operator.

`<,>'
     The left-hand side must have a value less than or greater than the
     right-hand side.  Comparisons are done depending on the type of
     data being queried; in particular, integer fields and dates use a
     numeric comparison, and enumerated fields are ordered depending on
     the numeric equivalent of their enumerated values.

   BOOLEANOP is either `|' (logical or), or `&' (logical and).  The
query expression

     Category="baz" | Responsible="blee"

selects all PRs with a Category field of `baz' or a Responsible field
of `blee'.

   The not operator `!' may be used to negate a test:

     ! Category="foo"

searches for PRs where the category is not equal to the regular
expression foo.

   Parentheses may be used to force a particular interpretation of the
expression:

     !(Category="foo" & Submitter-Id="blaz")

skips PRs where the Category field is equal to `foo' and the
Submitter-Id field is equal to `blaz'.  Parentheses may be nested to
any arbitrary depth.

   Fieldnames can be specified in several ways.  The simplest and most
obvious is just a name:

     Category="foo"

which checks the value of the category field for the value FOO.

   A fieldname qualifier may be prepended to the name of the field; a
colon is used to separate the qualifier from the name.  To refer
directly to a builtin field name:

     builtin:Number="123"

   In this case, `Number' is interpreted as the builtin name of the
field to check.  (This is useful if the fields have been renamed.  For
further discussion of builtin field names, see *Note The `dbconfig'
file: dbconfig file.

   To scan all fields of a particular type, the FIELDTYPE qualifier may
be used:

     fieldtype:Text="bar"

This searches all text fields for the regular expression `bar'.

   Note that it is not required that the right-hand side of the
expression be a literal string.  To query all PRs where the PR has been
modified since it was closed, the expression

     Last-Modified != Closed-Date

will work; for each PR, it compares the value of its Last-Modified field
against its Closed-Date field, and returns those PRs where the values
differ.  However, this query will also return all PRs with empty
Last-Modified or Closed-Date fields.  To further narrow the search:

     Last-Modified != Closed-Date & Last-Modified != "" & Closed-Date != ""

In general, comparing fields of two different types (an integer field
against a date field, for example) will probably not do what you want.

   Also, a field specifier may be followed by the name of a subfield in
braces:

     State[type] != "closed"

or even

     builtin:State[type] != "closed"

Subfields are further discussed in *Note The `dbconfig' file: dbconfig
file.


File: gnats.info,  Node: Example queries,  Prev: Query expressions,  Up: query-pr

2.4.4 Example queries
---------------------

The following simple query:

     query-pr --expr 'Category~"rats" & State~"analyzed"
                      & Responsible~"fred"'

yields all PRs in the database which contain the field values:

     >Category:     rats         _and_
     >Responsible:  fred         _and_
     >State:        analyzed

   The following query:

     query-pr --expr 'State~"open|analyzed"'

yields all PRs in the database whose `State' values match either `open'
or `analyzed' (*note Querying using regular expressions: Regexps.  This
search is useful as a daily report that lists all Problem Reports which
require attention.

   The following query:

     query-pr --expr 'fieldtype:Text="The quick.*brown fox"'

yields all PRs whose TEXT fields contain the text `The quick' followed
by `brown fox' within the same field.  *Note Querying using regular
expressions: Regexps, which also contains further useful examples of
query expressions.


File: gnats.info,  Node: Emacs,  Prev: query-pr,  Up: GNATS user tools

2.5 The Emacs interface to GNATS
================================

Emacs interface to GNATS provides basic access to GNATS databases, i.e.
sending, editing, and querying Problem Reports.  It also defines a
simple major mode for editing `dbconfig' files.

   This section provides an overview of using GNATS with Emacs.  It
does not describe the use of Emacs itself, for detailed instructions on
using Emacs, see *Note Top: (emacs)Top.  For installation instructions
of the GNATS Emacs mode, see *Note Installing utils::.

   Please note the Emacs interface was completely rewritten between
GNATS 3 and GNATS 4.  It now uses `gnatsd', *Note gnatsd::, exclusively
for its operations and uses modern Emacs features like faces.  Its
features are not complete though, you can send your suggestions and
patches to the appropriate GNATS mailing list, *Note Support::.

* Menu:

* Emacs viewing::               Viewing PRs by their number.
* Emacs querying::              Querying the database.
* Emacs submitting::            Submitting new PRs.
* Emacs editing::               Editing PRs.
* Emacs editing buffer::        The editing buffer.
* Emacs and databases::         Changing the working database.
* dbconfig mode::               Major mode for dbconfig files.
* Other Emacs commands::        Miscellaneous commands.
* Emacs customization::         Customizing the Emacs interface.


File: gnats.info,  Node: Emacs viewing,  Next: Emacs querying,  Up: Emacs

2.5.1 Viewing Problem Reports
-----------------------------

To view a particular Problem Report, use the command `M-x view-pr'.  It
asks for a Problem Report number and displays that Problem Report.

   The displayed buffer is put in the view mode, *Note Misc File Ops:
(emacs)Misc File Ops.  If you decide to edit the displayed Problem
Report, use the command `e' (`gnats-view-edit-pr').

`gnats-view-mode-hook'
     Hook run when `gnats-view-mode' is entered.


File: gnats.info,  Node: Emacs querying,  Next: Emacs submitting,  Prev: Emacs viewing,  Up: Emacs

2.5.2 Querying Problem Reports
------------------------------

Querying the database is performed by the `M-x query-pr' command.  The
command prompts for the query expression, *Note Query expressions::,
and displays a buffer with the list of the matching Problem Reports.

   The list of the Problem Reports is displayed in the `summary' query
format, *Note Formatting query-pr output::.  Currently, the display
format cannot be changed and it must output each Problem Report's
number in the first column.

   The Problem Report list buffer is put in the view mode, *Note Misc
File Ops: (emacs)Misc File Ops.  You can use most of the standard view
mode commands in it.  Additionally, the following special commands are
available:

`v'
`RET'
`mouse-2'
     View the current Problem Report (`gnats-query-view-pr'), *Note
     Emacs viewing::.

`e'
     Edit the current Problem Report (`gnats-query-edit-pr'), *Note
     Emacs editing::.

`g'
     Update the Problem Report list (`gnats-query-reread').  The last
     performed query is executed again and the buffer is filled with the
     new results.

`G'
     Perform new query (`query-pr').

`s'
     Send new Problem Report (`send-pr'), *Note Emacs submitting::.

`D'
     Change the current database (`gnats-change-database'), *Note Emacs
     and databases::.

`q'
     Bury buffer, the buffer is put at the end of the list of all
     buffers.  This is useful for quick escape of the buffer, without
     killing it.

   If the value of the variable GNATS-QUERY-REVERSE-LISTING is
non-`nil', the listing appears in the reversed order, i.e. with the
Problem Reports of the highest number first, in the buffer.

   Similarly to other GNATS Emacs modes, there is a hook available for
the Problem Report list.

`gnats-query-mode-hook'
     Hook run when `gnats-query-mode' is entered.


File: gnats.info,  Node: Emacs submitting,  Next: Emacs editing,  Prev: Emacs querying,  Up: Emacs

2.5.3 Submitting new Problem Reports
------------------------------------

You can submit new Problem Reports with the command `M-x send-pr'.  The
command puts you to the problem editing buffer, *Note Emacs editing::.
The buffer is prefilled with the initial report fields and their
default values, if defined.  You can use the usual Problem Report
editing commands, *Note Emacs editing::.  When you have filled in all
the fields, you can send the Problem Report by presing `C-c C-c'.

   If you run `M-x send-pr' with a prefix argument, it runs the
`gnats-change-database' command before putting you to the editing
buffer, *Note Emacs and databases::.

   You can set the following variables to get some fields pre-filled:

GNATS-DEFAULT-ORGANIZATION
     Default value of the `Organization' field used in new Problem
     Reports.

GNATS-DEFAULT-SUBMITTER
     Default value of the `Submitter-Id' field used in new Problem
     Reports.


File: gnats.info,  Node: Emacs editing,  Next: Emacs editing buffer,  Prev: Emacs submitting,  Up: Emacs

2.5.4 Editing Problem Reports
-----------------------------

To edit a particular Problem Report, use the command `M-x edit-pr'.  It
asks for a Problem Report number and puts the given Problem Report in
the editing buffer.  *Note Emacs editing buffer::, for information how
to edit the Problem Report in the buffer and how to submit your changes.

   Note you can also start editing of a selected Problem Report directly
from within the viewing buffer, *Note Emacs viewing::, or the query
result buffer, *Note Emacs querying::.


File: gnats.info,  Node: Emacs editing buffer,  Next: Emacs and databases,  Prev: Emacs editing,  Up: Emacs

2.5.5 The Problem Report editing buffer
---------------------------------------

When you invoke a Problem Report editing command, the Problem Report is
put into a special editing buffer.  The Problem Report is formatted
similarly to the `query-pr -F' output, *Note Formatting query-pr
output::.  Field identifiers are formatted as

     >Field:

   with the text of the field following the identifier on the same line
for single-line fields or starting on the next line for multi-line
fields.

   The Problem Report editing mode tries to prevent you from violating
the Problem Report format and the constraints put on the possible field
values.  Generally, you can use usual editing commands, some of them
have a slightly modified behavior though.  (If you encounter a very
strange behavior somewhere, please report it as a bug, *Note Support::.)

   You can move between fields easily by pressing the `TAB'
(`gnats-next-field') or `M-TAB' (`gnats-previous-field') keys.

   The field tags are read-only and you cannot edit them nor delete
them.  If you want to "remove" a field, just make its value empty.

   Editing a field value depends on the type of the edited field, *Note
Field datatypes::.  For text fields, you can edit the value directly,
assuming you preserve the rule about single-line and multi-line values
mentioned above.

   For enumerated fields, you cannot edit the value directly.  You can
choose it from the list of the allowed values, either from the menu
popped up by pressing the middle mouse button or from within minibuffer
by pressing any key on the field's value.  If the pressed key matches
any of the allowed field values, that value is put as the default value
after the minibuffer prompt.  You can also cycle through the allowed
field values directly in the editing buffer using the `SPACE' key.
Enumerated field values are marked by a special face to not confuse
you; you must have enabled font lock mode to benefit from this feature,
*Note Font Lock: (emacs)Font Lock.

   Some field values can be read-only, you cannot edit them at all.

   Once you have edited the Problem Report as needed, you can send it to
the server with the `C-c C-c' command (`gnats-apply-or-submit').
Successful submission is reported by a message and the buffer
modification flag in mode line is cleared.  Then you can either kill
the buffer or continue with further modifications.

`gnats-edit-mode-hook'
     Hook run when `gnats-edit-mode' is entered.


File: gnats.info,  Node: Emacs and databases,  Next: dbconfig mode,  Prev: Emacs editing buffer,  Up: Emacs

2.5.6 Changing the database
---------------------------

By default, the Emacs interface connects to the default database, *Note
databases file::.  If you want to connect to another database, use the
command `M-x gnats-change-database'.  It will ask you for the database
name to use, server and port it can be accessed on, and your login name.

   If you want to use the `gnatsd' command, *Note gnatsd::, directly,
without connecting to a remote server or the localhost connection port,
provide your local file system full path to `gnatsd' as the server
name.  Port number does not matter in this case.

   If the database requires a password to allow you the access to it,
you are prompted for the password the first time you connect to the
database.  If you provide an invalid password, you cannot connect to
the database anymore and you have to run the `M-x
gnats-change-database' command again.


File: gnats.info,  Node: dbconfig mode,  Next: Other Emacs commands,  Prev: Emacs and databases,  Up: Emacs

2.5.7 dbconfig mode
-------------------

The Emacs interface defines a simple major mode `gnats-dbconfig-mode'
for editing `dbconfig' files, *Note dbconfig file::.  It defines basic
mode attributes like character syntax and font lock keywords, it does
not define any special commands now.

`gnats-dbconfig-mode-hook'
     Hook run when `gnats-dbconfig-mode' is entered.


File: gnats.info,  Node: Other Emacs commands,  Next: Emacs customization,  Prev: dbconfig mode,  Up: Emacs

2.5.8 Other commands
--------------------

`M-x unlock-pr'
     Ask for a Problem Report number and unlock that Problem Report.
     This function is useful if connection to a GNATS server was
     interrupted during an editing operation and further modifications
     of the Problem Report are blocked by a stealth lock.

`M-x unlock-database'
     Unlock the whole GNATS database.  This function is useful in
     situations similar to when `unlock-pr' is used.

`M-x gnats-show-connection'
     Show the connection buffer associated with the current buffer.  You
     can view the Emacs communication with GNATSD in it.  This is
     useful when something strange happens during the communication with
     the server, e.g. when sending a Problem Report with `C-c C-c' from
     a Problem Report editing buffer.


File: gnats.info,  Node: Emacs customization,  Prev: Other Emacs commands,  Up: Emacs

2.5.9 Customization
-------------------

All the user variables can be customized in the customization group
`gnats', *Note Easy customization: (emacs)Easy customization.


File: gnats.info,  Node: Installation,  Next: Management,  Prev: GNATS user tools,  Up: Top

3 Installing GNATS
******************

See also *Note Where the tools and utilities reside: Locations.

   There are several steps you need to follow to fully configure and
install GNATS on your system.  You need `root' access in order to
create a new account for `gnats' and to install the GNATS utilities.
You may need `root' access on some systems in order to set up mail
aliases and to allow this new account access to `cron' and `at'.

   If you are updating an older version of GNATS rather than installing
from scratch, see *Note Upgrading from older versions: Upgrading.

   GNATS installation relies on two other freely available software
packages, which should be installed before you go on to configure and
build GNATS.  These are GNU `make' and `Texinfo' (version 4.2 or
higher).  Both are available from the GNU FTP site at
`ftp://ftp.gnu.org'.

   To build and install GNATS, you must:

   * Run `configure', with correct options if the defaults are
     unsuitable for your site.  *Note Configuring and compiling the
     software: Configure and make.  Default installation locations are
     in *Note Where GNATS lives: Locations.

   * Compile the GNATS programs on your system.  *Note Configuring and
     compiling the software: Configure and make.

   * Create an initial database by using the `mkdb' command.  *Note
     Setting up the default database::.

   * Set up periodic jobs, using cron, to handle Problem Reports
     arriving by mail.  *Note Setting up periodic jobs::.

   * Set up mail aliases for GNATS.  *Note Setting up mail aliases:
     Aliases.

   * Install the GNATS tools and utilities locally, and install the user
     tools (`query-pr', `edit-pr', `send-pr') on every machine in your
     local network.  *Note Installing the user tools: Installing tools.

   * Install the GNATS daemon `gnatsd'.  *Note Installing the daemon::.

   * If there are people outside your organization who will be
     submitting PRs or who are supposed to be able to query and/or edit
     PRs, you may need to instruct them to obtain and build the GNATS
     tools `query-pr', `edit-pr' and `send-pr' for their systems.
     However, for many sites, setting up a remote access interface to
     GNATS, such as Gnatsweb is a better solution since this requires
     no configuration on the remote side.

* Menu:

* Configure and make::               Configuring and compiling the software
* Installing utils::                 Installing the utilities
* Setting up the default database::  Setting up the default database
* Setting up periodic jobs::         Setting up periodic jobs
* Aliases::                          Setting up mail aliases
* Installing the daemon::            Installing the daemon
* Installing tools::                 Installing the user tools
* Upgrading::                        Upgrading from older versions


File: gnats.info,  Node: Configure and make,  Next: Installing utils,  Up: Installation

3.1 Configuring and compiling the software
==========================================

  1. First, unpack your distribution.  We provide source code in a `tar'
     file which was compressed using `gzip'.  The code can be extracted
     into a directory UNPACKDIR using

          cd UNPACKDIR
          gunzip gnats-4.1.0.tar.gz
          tar xvf gnats-4.1.0.tar

     The sources reside in a directory called `gnats-4.1.0' when
     unpacked.  We call this the "top level" of the source directory,
     or "srcdir".  The sources for the GNATS tools are in the
     subdirectory `gnats-4.1.0/gnats/*'.  Lists of files included in
     the distribution are in each directory in the file `MANIFEST'.

  2. As of GNATS version 4, having Emacs installed on the GNATS server
     is no longer a requirement.  If you do not have Emacs installed,
     disregard this step altogether.

     You may wish to alter the installation directory for the Emacs lisp
     files.  If your Emacs lisp library is not in
     `PREFIX/share/emacs/site-lisp', edit the file
     `SRCDIR/gnats/Makefile.in'.  Change the variable `lispdir' from
     `PREFIX/emacs/site-lisp' to the directory containing your Emacs
     lisp library.  For information on PREFIX, see *Note PREFIX: prefix.

  3. Create an account for the `gnats' user.  You can actually name this
     user whatever you want to, as long as it is a valid username on
     your system, but we strongly recommend that you call the user
     `gnats'.  If you do decide to give it some other name, remember to
     use the option `--with-gnats-user' when running `configure' below.
     Below, we will anyway refer to this user by the name `gnats'.

     This user must have an entry in the file `/etc/passwd'.  As for
     ordinary users, create a standard home directory for the `gnats'
     user.  The default `PATH' for this user should contain
     `EXEC-PREFIX/bin' and `EXEC-PREFIX/libexec/gnats'.  The
     EXEC-PREFIX value is configurable with the `--exec-prefix'
     configure option described below, but for standard installations,
     these two directories correspond to `/usr/local/bin' and
     `/usr/local/libexec/gnats'.

  4. Run `configure'.  You can nearly always run `configure' with the
     simple command

          ./configure

     and the "Right Thing" happens:

        * GNATS is configured in the same directory you unpacked it in;

        * when built, GNATS runs on the machine you're building it on;

        * when installed, files are installed under `/usr/local' (*note
          Where GNATS lives: Locations.).

        * all GNATS utilities operate on the "default database", assumed
          to be named _default_ and to be located in
          `/usr/local/com/default', unless you invoke the utilities with
          `-d' DATABASENAME or `--directory='DATABASENAME, or set the
          GNATSDB environment variable to point to some other database.

     The most common options to `configure' are listed below:

          configure [ --prefix=PREFIX ]
                    [ --exec-prefix=EXEC-PREFIX ]
                    [ --with-gnats-service=SERVICE-NAME ]
                    [ --with-gnats-user=USERNAME ]
                    [ --with-gnatsd-user-access-file=PATH ]
                    [ --with-gnatsd-host-access-file=PATH ]
                    [ --with-gnats-dblist-file=PATH ]
                    [ --with-gnats-default-db=PATH ]
                    [ --with-kerberos ] [ --with-krb4 ]
                    [ --verbose ]

    `--prefix=PREFIX'
          All host-independent programs and files are to be installed
          under PREFIX.  (Host-dependent programs and files are also
          installed in PREFIX by default.)  The default for PREFIX is
          `/usr/local'.  *Note Where GNATS lives: Locations.

    `--exec-prefix=EXEC-PREFIX'
          All host-dependent programs and files are to be installed
          under EXEC-PREFIX.  The default for EXEC-PREFIX is PREFIX.
          *Note Where GNATS lives: Locations.

    `--with-gnats-service=SERVICE-NAME'
          Set SERVICE-NAME to be the GNATS network service.  Default
          name is SUPPORT.

    `--with-gnats-user=USERNAME'
          Set USERNAME to be the user name for GNATS.  Default username
          is GNATS.

    `--with-gnatsd-user-access-file=PATH'
          Set global (across all databases) gnatsd user access file to
          PATH. Default is `/USR/LOCAL/ETC/GNATS/GNATSD.USER_ACCESS'.
          Per-database user access permissions are set in a
          `gnatsd.user_access' file in the `gnats-adm' subdirectory of
          each database.

    `--with-gnatsd-host-access-file=PATH'
          Set global (across all databases) gnatsd host access file to
          PATH. Default is `/usr/local/etc/gnats/gnatsd_host.access'.
          There is currently no way to specify host access permissions
          on a per-database basis.

    `--with-gnats-dblist-file=PATH'
          Specify the file containing the list of databases.

          Default is `PREFIX/etc/gnats/databases'.

    `--with-gnats-default-db=PATH'
          Specify the default database to use when GNATS tools are
          invoked without the `-d' or `--databasename' option, and when
          the GNATSDB envrionment variable hasn't been set. Default is
          `/PREFIX/com/gnatsdb'.

    `--with-kerberos'
          Include code for Kerberos authentication.

    `--with-krb4'
          Support Kerberos 4.

    `--verbose'
          Give verbose output while `configure' runs.

     `configure' supports several more options which allow you to
     specify in great detail where files are installed. For a complete
     list of options, run `./configure --help' in the source directory.

     You can build GNATS in a different directory (OBJDIR) from the
     source code by calling the `configure' program from the new
     directory, as in

          mkdir OBJDIR
          cd OBJDIR
          SRCDIR/configure ...

     By default, `make' compiles the programs in the same directory as
     the sources (SRCDIR).

  5. Make sure you have GNU `make', then run

          make all info

     from the directory where `configure' created a `Makefile' (this is
     OBJDIR if you used it, otherwise SRCDIR.)  These targets indicate:

    `all'
          Compile all programs

    `info'
          Create `info' files using `makeinfo'.


File: gnats.info,  Node: Installing utils,  Next: Setting up the default database,  Prev: Configure and make,  Up: Installation

3.2 Installing the utilities
============================

The following steps are necessary for a complete installation.  You may
need `root' access for these.

  1. Install the utilities by invoking

          make install install-info

     These targets indicate:

    `install'
          Installs all programs into their configured locations (*note
          Where GNATS lives: Locations.).

    `install-info'
          Installs `info' files into their configured locations (*note
          Where GNATS lives: Locations.).

     After you have installed GNATS, you can remove the object files
     with

          make clean

  2. If you do not have Emacs installed on your GNATS server, this step
     should be skipped.

     Place the following lines in the file `default.el' in your Emacs
     lisp library, or instruct your local responsible parties to place
     the lines in their `.emacs':

          (autoload 'send-pr "gnats"
             "Command to create and send a problem report." t)
          (autoload 'edit-pr "gnats"
             "Command to edit a problem report." t)
          (autoload 'view-pr "gnats"
             "Command to view a problem report." t)
          (autoload 'query-pr "gnats"
             "Command to query information about problem reports." t)
          (autoload 'unlock-pr "gnats"
             "Unlock a problem report." t)
          (autoload 'gnats-dbconfig-mode "gnats"
            "Major mode for editing the `dbconfig' GNATS configuration file." t)
          (add-to-list 'auto-mode-alist '("\\<dbconfig$" . gnats-dbconfig-mode))

  3. If you want people who are logged into the GNATS server itself to
     be able to use the `send-pr' tool to submit problem reports, you
     need to create a configuration file for `send-pr' on the server.
     *Note The send-pr.conf configuration file: send-pr.conf file.



File: gnats.info,  Node: Setting up the default database,  Next: Setting up periodic jobs,  Prev: Installing utils,  Up: Installation

3.3 Installing the default database
===================================

For the following steps, log in as the user `gnats'.

   We are now going to initialize the default GNATS database.  Run the
following command:

     mkdb default

   This creates a database named `default', with all its data stored
below the directory `PREFIX/com/gnatsdb', in a default installation
this corresponds to `/usr/local/com/gnatsdb'.  If you specified the
`--with-gnats-default-db' option when running configure, the default
database will be created under the directory you specified instead.
`mkdb' creates the database directory itself, together with three
different subdirectories(1):

   * A directory for the mandatory GNATS category PENDING.

   * A `gnats-queue' directory for queueing new messages to GNATS
     before they are processed by `file-pr'.

   * The administrative directory `gnats-adm'. This directory is
     populated with default configuration files from the
     `PREFIX/etc/gnats/defaults' directory.

   The next configuration step is to edit the default files copied to
the database's `gnats-adm' directory by `mkdb'.

   The default `dbconfig' file installed by `mkdb' provides a good
basis for many GNATS databases. The default file causes similar
behaviour to the 3.x versions of GNATS. However, even if this might be
precisely what you want, you should still go through the file and check
that the default settings suit your needs.  *Note The `dbconfig' file:
dbconfig file.

   Then edit the files `categories', `responsible', and `submitters' in
the `gnats-adm' directory (*note Other database-specific config files:
Other config files.) to reflect your local needs.  For special
configurations, you may also have to edit the `states' and `classes'
files.

   If you used the `--with-gnats-default-db' option in the pre-build
configure to change the location of the default database, you need to
edit the `databases' config file, see *Note The `databases file':
databases file.  This file is by default located in the
`PREFIX/etc/gnats' directory, but may have been changed by the option
`--with-gnats-dblist-file' option during configure.

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

   (1) Upgraders from older versions of GNATS should note that category
directories are now created "on-the-fly" as needed by default.


File: gnats.info,  Node: Setting up periodic jobs,  Next: Aliases,  Prev: Setting up the default database,  Up: Installation

3.4 Setting up periodic jobs
============================

Allow the new user `gnats' access to `cron' and `at'.  To do this, add
the name `gnats' to the files `cron.allow' and `at.allow', which
normally reside in the directory `/var/spool/cron'.  If these files do
not exist, make sure `gnats' does not appear in either of the files
`cron.deny' and `at.deny' (in the same directory).  If you changed the
name of the GNATS user during configure, remember to substitute as
appropriate in the previous steps.

   Create a `crontab' entry that periodically runs the program
`queue-pr' with the `--run' option (*note `queue-pr': queue-pr.).  For
example, to run `queue-pr --run' every ten minutes, create a file called
`.mycron' in the home directory of the user `gnats' which contains the
line:

     0,10,20,30,40,50 * * * * EXEC-PREFIX/libexec/gnats/queue-pr --run

(Specify the full path name for `queue-pr'.)  Then run

     crontab .mycron

See the `man' pages for `cron' and `crontab' for details on using
`cron'.


File: gnats.info,  Node: Aliases,  Next: Installing the daemon,  Prev: Setting up periodic jobs,  Up: Installation

3.5 Setting up mail aliases
===========================

The following mail aliases must be added on the machine where the GNATS
server is installed.  The instructions below are for Sendmail or
Sendmail-like mail systems.  If these instructions don't fit your
system, particularly if you do not have an `aliases' file, ask your
mail administrator for advice.

   The following aliases should be placed in the file `/etc/aliases'.
Yoy may need `root' access to add these aliases:

   * Create an alias for the GNATS administrator.  This address should
     point to the address of the person in charge of administrating
     GNATS:

          gnats-admin:  ADDRESS

   * Create an alias to redirect incoming Problem Reports.  This alias
     should redirect incoming mail via a "pipe" to the program
     `queue-pr -q'.  For example, if Problem Reports coming to your
     site are to arrive at the address `bugs@your.company.com', create
     an alias to the effect of:

          bugs:  "| EXEC-PREFIX/libexec/gnats/queue-pr -q"

     This places incoming Problem Reports in the `GNATS-QUEUE'
     directory of your database.  Remember to fill in the full path of
     the `queue-pr' command as appropriate for your installation.

   * You may also wish to forward a copy of each incoming Problem
     Report to a log.  This can be accomplished with something like:

          bug-q: "| EXEC-PREFIX/libexec/gnats/queue-pr -q"
          bug-log:  /some/path/bugs.log
          bugs:      bug-q, bug-log

     This configuration archives incoming Problem Reports in the file
     `bug.log', and also feeds them to the program `queue-pr'.
     (Remember, `bug.log' needs to be world-writable, and should be
     pruned regularly; *note GNATS Administration: Management.)  In
     order for the log file to protect fully against data loss in case
     a disk runs full, try to place it on a different disk volume than
     the GNATS database.

   * If you want your users to be able to query the database by mail,
     use the following alias:

          query-pr: "| EXEC-PREFIX/libexec/gnats/mail-query"

     The `mail-query' program uses `--restricted' to search on the
     database, and by default only searches for PRs that aren't closed
     (*note Querying the database: query-pr.).



File: gnats.info,  Node: Installing the daemon,  Next: Installing tools,  Prev: Aliases,  Up: Installation

3.6 Installing the daemon
=========================

By default, the daemon and clients are set to use port 1529.  Add the
line

     support		1529/tcp			# GNATS

to your `/etc/services' file.  If you want a different service name,
configure GNATS with

     --with-gnats-service=SERVICENAME

   In your `inetd.conf' file, add the line

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

adjusting the path accordingly if you used configure options to make
changes to the defaults.  To make `inetd' start spawning the GNATS
daemon when connected on that port, send it a hangup signal (`HUP').

   Some operating systems have replaced `inetd' with the more modern
`xinetd'. Instead of editing `inetd.conf', you should create the file
`/etc/xinetd.d/support', containing something like the following:

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

   If you specified a different service name when running `configure',
you need to give the file the same name as the service name, and you
need to adjust the `service' line above.  If the `--prefix' or
`--exec-prefix' options were passed to `configure', adjust the `server'
line above, and if you used the `--with-gnats-user' option, adjust the
`user' line.

   Then restart `xinetd' to make the new configuration current.

   If you use an Internet superserver different from `inetd' or
`xinetd', please refer to its documentation for information how to
configure it.

   At this point, you will probably want to set the access permissions
of the different hosts that are going to be accessing your databases.
The access permissions can currently only be set on a global scale
(that is, across all the databases on a GNATS server).  The location
and name of the global host access configuration file can be set during
the pre-build configure as shown above, but by default the file is
`/usr/local/etc/gnats/gnatsd_host.access'.  It lists the hosts allowed
to access your server, and what their default access levels are.  Each
line in the file denotes one server, or one part of a network domain.
There are three fields on each line, but only two are currently used.
To grant all hosts from the domain SITE.COM edit access, use this line:

   SITE.COM:EDIT

If you run a GNATS web interface or similar tool on the same machine as
the server is running on, you probably want to grant LOCALHOST edit
access:

   LOCALHOST:EDIT

   If you are using Kerberos, the `gnatsd_host.access' file shows the
sites that don't require Kerberos authentication.

   The third field might in the future be used for things like
controlling what categories, submitter-id's PRs, etc., can be accessed
from that site.  Access attempts that are denied are logged to the
syslog messages file (`/var/adm/messages' on many systems).


File: gnats.info,  Node: Installing tools,  Next: Upgrading,  Prev: Installing the daemon,  Up: Installation

3.7 Installing the user tools
=============================

When you install the GNATS utilities, the user tools `send-pr',
`query-pr' and `edit-pr' are installed on the server machine.  If your
machine is part of a network, however, you may wish to install the user
tools on each machine in the network so that responsible parties on
those machines can submit new Problem Reports, query the database, and
edit existing PRs.  In the following discussion, machines with the
GNATS user tools installed are referred to as "client" machines.  In
general, there are three distinct types of client that a GNATS server
may have to cater for:

   - Machines that are on the same local network as the GNATS server,
     i.e. machines that are under the same administrative control.

   - Machines on the general, open Internet.

   - Machines behind firewalls etc. which deny direct access over the
     network to the GNATS server.

   Each type of client requires a different approach when it comes to
providing access.

3.7.1 User tools on a local network
-----------------------------------

If all the machines involved reside on the same local network as the
GNATS server, you can simply share out the directories on the server
that contain the user tools, by default `/usr/local/bin' and the
directory which contains the `send-pr.conf' configuration file (*note
The send-pr.conf configuration file: send-pr.conf file.), by default
`/usr/local/etc/gnats'.  If you have a heterogeneous environment, i.e.
hosts running different operating systems, you need to create several
shared GNATS installations, one for each platform.  The `send-pr.conf'
file is platform-independent, though.

   In order to submit a new PR, `send-pr' would then be invoked as
follows on the client machines:

     send-pr -d HOSTNAME:PORT:DATABASE:USERNAME:PASSWORD

   Or by first setting the environment variable `GNATSDB' as follows
(the exact syntax will vary depending on what shell you use):

     export GNATSDB=HOSTNAME:PORT:DATABASE:USERNAME:PASSWORD

   Then, `send-pr' can simply be invoked without any options.

   The other tools, `query-pr' and `edit-pr', work in similar ways,
honoring the `-d' option as well as the `GNATSDB' environment variable.
*Note GNATS user tools::.

3.7.2 User tools for remote users
---------------------------------

When client machines reside on the general Internet, both security and
practical considerations may make it impossible to provide a shared
installation of the GNATS tools.  In this case, you may choose to only
provide access through a web interface such as Gnatsweb.  For clients
that need the GNATS tools, the following needs to be carried out on the
remote machines:

  1. Configure and build GNATS on the client machine

  2. Configure `send-pr' on the client machine

   You should unpack the distribution and run `configure' on the client
machine in the same way as described in *Note Configuring and compiling
the software: Configure and make.  Note, however, that you do not need
to create a `gnats' user on the client and you should not use the `make
all info' command to build.  Instead, issue the following commands from
the top level directory of the source distribution:

     cd gnats
     make install-tools
     cd ../send-pr
     make all install

   This builds and installs the `send-pr', `query-pr' and `edit-pr'
tools on the client machine.  You should now configure `send-pr' by
editing the `send-pr.conf' file (*note The send-pr.conf configuration
file: send-pr.conf file.)

   Users on the client machine can now either use the send-pr syntax or
the `GNATSDB'environment variable described in the previous section.

   For sites that need to submit Problem Reports by having send-pr send
e-mail instead of speaking directly over the network to the GNATS
server, you need to create a problem report template on the GNATS
server and have that template copied to a suitable location on the
client machine (any filename and any location will do, as long as
`send-pr' on the client machine can read the file).  On the GNATS
server, use the command

     send-pr -p > `filename'

   The file `filename' now contains a PR template for your database.
Copy this file to the client.  Then edit the `send-pr.conf' file that
you created on the client, set the `TEMPLATE' variable to point to the
template file (*note The send-pr.conf configuration file: send-pr.conf
file.) and make sure that the `MAILPROG' and `MAILADDR' varables in
`send-pr.conf' are correctly set.  You should now have a working remote
tool installation.

   For clients that have no direct network access to your GNATS server,
such as those that are located behind strict firewalls, you either need
to set up a web interface such as Gnatsweb (provided that the firewall
lets web traffic through) or use the procedure above which sets up
`send-pr' to submit Problem Reports by e-mail.  In order to query PRs,
users on the remote machines will then have to use the the e-mail
functionality of `query-pr' (*note Invoking query-pr::.  Editing PRs by
e-mail is not possible, so clients in this group who need edit access
have to get access through a web interface if possible.

   Note that when `send-pr' is set up to work over e-mail, the
`GNATSDB' environment variable and the `-d' command line option have no
effect since `send-pr' is tied to a specific database by way of the
value of `MAILADDR' in the `send-pr.conf' file.


File: gnats.info,  Node: Upgrading,  Prev: Installing tools,  Up: Installation

3.8 Upgrading from older versions
=================================

The following procedure covers an upgrade from all GNATS 3 versions
newer than 3.108.  If your installation is an older 3.10x version, or
even the ancient 3.2 version, you need to review the `UPGRADING.old'
file in the GNATS distribution before carrying out the steps detailed
here.

3.8.1 Overview
--------------

Although almost all of the GNATS internals have been redesigned and
rewritten for GNATS 4, little has changed in the format and structure
of the database data.  The only change that needs to be taken into
account when upgrading is the fact that the database index format is
binary in a default installation of GNATS 4.  Thus, you will need to
regenerate your database index by using the `gen-index' tool.  In
addition, if your old GNATS installation was so-called "release-based",
you need to make some simple modifications to the database setup file
`dbconfig'.  See below for details.

   Apart from building and installing new binaries, the major changes
which impinge on the upgrade procedure are all on the configuration
side.  The main database configuration file, `dbconfig', is far more
complex and powerful than the old `config' file, and while the
installation process creates a sensible set of default values which are
similar to GNATS 3.11x's defaults, you still need to migrate any
changes you may have made to your own local configuration.

   Another aspect which needs consideration are remote submitter sites.
Such sites either need to be instructed to upgrade their locally
installed copies of the GNATS user tools (`send-pr', `edit-pr' and
`query-pr'), or they should be given access through interfaces such as
Gnatsweb.

   Since the GNATS network daemon has been completely reworked, with an
entirely new command set, all network-based interfaces, such as
Gnatsweb and TkGnats need to be upgraded to versions that support GNATS
4.  The `contrib' directory of this distribution contains some
third-party interfaces, and the `README' file contains pointers to
where you can obtain the newest versions of these tools.

   This document only deals with upgrading GNATS itself.  Third-party
tools should have separate upgrading instructions in their
distributions.

3.8.2 Upgrading
---------------

  1. Before you begin, make a backup of your entire GNATS database
     directory hierarchy, the GNATS executables directory and the GNATS
     user tools (`send-pr', `query-pr' etc.)  The locations of these
     may vary, but in a default GNATS 3 installation, the database(s)
     reside under `/usr/local/share/gnats', the executables are located
     in `/usr/local/libexec/gnats' and the user tools reside in
     `/usr/local/bin'.

  2. (optional) In order to avoid confusing your users, you may want to
     remove the old GNATS 3 executables and tools, escpecially if you
     plan to install GNATS 4 in a different location than version 3.

  3. Build and install GNATS 4.  *Note Installing GNATS: Installation.
     It is recommended that you use the `--with-gnats-default-db'
     option when running `configure', in order to set the default
     database to be one of your already existing GNATS 3 databases.

  4. Edit the GNATS `databases' file and add entries for all your old
     GNATS 3 databases.  In a default GNATS 4 installation the file is
     in `/usr/local/etc/gnats'.  *Note The `databases' file: databases
     file.

  5. In GNATS 3, the file `gnatsd.conf' specifies minimum access levels
     for the different hosts accessing the GNATS daemon, `gnatsd'.
     There is one `gnatsd.conf' for each database.  In GNATS 4, these
     files have been replaced by a single file named
     `gnatsd.host_access' which contains settings that apply across all
     the databases on the server.  This file is located in the same
     directory as the `databases' file.  You need to combine the host
     access settings from all your GNATS 3 databases and add them to the
     `gnatsd.host_access' file.  Note that you are no longer able to
     control host access on a per-database basis.  Optionally, you may
     delete the old `gnatsd.conf' files.  *Note Controlling access to
     GNATS databases: Access Control.

  6. Next, you need to migrate the settings in the old `config' files of
     your databases to corresponding `dbconfig' files.  The database you
     specified with the `--with-gnats-default-db' configure option got
     a default `dbconfig' installed.  This default file contains field
     definitions etc. which makes this version of GNATS behave almost
     exactly like older versions.  Copy this default file to the
     `gnats-adm' directories of any other GNATS databases that you may
     have on your host before you proceed to migrate your old
     configuration settings.

     The following is a list of the configuration directives that may be
     present in a `config' file and their counterparts (if any) in
     GNATS 4.

    GNATS_ADDR
          This setting has no counterpart in GNATS 4, since GNATS no
          longer needs to know its own mail address.

    GNATS_ADMIN
          This setting is now set in the `responsible' file in the
          `gnats-adm' directory of your database(s).

    GNATS_SITE
          GNATS 4 has no concept of a named `site', so this directive is
          obsolete.

    SUBMITTER
          Obsolete, since it relates to GNATS_SITE.

    DEFAULT_RELEASE
    DEFAULT_ORGANIZATION
          The GNATS 4 `dbconfig' file has separate configuration
          sections for each defined field.  Field defaults are set with
          the `default' keyword in these sections.  *Note The
          `dbconfig' file: dbconfig file.

    NOTIFY
          Controlled by the `notify-about-expired-prs' setting in the
          `dbconfig' file.

    ACKNOWLEDGE
          Controlled by the `send-submitter-ack' setting in the
          `dbconfig' file.

    DEFAULT_SUBMITTER
          The default submitter is now always the first entry in the
          `submitters' file of your database.

    KEEP_RECEIVED_HEADERS
          Controlled by the `keep-all-received-headers' setting in the
          `dbconfig' file.

    DEBUG_MODE
          Controlled by the `debug-mode' setting in the `dbconfig' file.

    BDAY_START
    BDAY_END
    BWEEK_START
    BWEEK_END
          Controlled by the settings `business-day-hours' and
          `business-week-days' in the `dbconfig' file.

    DEFINE_CATEGORY
          The default category for PRs that arrive without one is now
          the first category listed in the `categories' file of your
          database.

     After your are done migrating the settings, you may optionally
     delete the old `config' files.  Since there are many more
     configuration settings available in the GNATS 4 `dbconfig' file,
     you should take some time to review them all before proceeding.
     *Note The `dbconfig' file: dbconfig file.

     If your old GNATS installations was release-based, i.e. it included
     the fields Quarter, Keywords and Date-Required, you need to define
     those fields in the `dbconfig' file by following the instructions
     in *Note Supporting old GNATS "release-based" fields:
     release-based support.

  7. The file `gnatsd.access' has been renamed to `gnatsd.user_access'.
     Furthermore, GNATS 4 uses a different password format in the
     `gnatsd.user_access' file than older versions, since it supports
     `crypt()' and MD5 passwords (*note Controlling access to GNATS
     databases: Access Control.).  You need to translate your old
     `gnatsd.user_access' files to the new format by using the
     `gnats-pwconv' tool which was installed in the
     `EXEC-PREFIX/libexec/gnats' directory, typically
     `/usr/local/libexec/gnats'.  *Note Managing user passwords:
     gnats-pwconv.

  8. The final step involves regenerating the indexes of your
     databases.  For this, log in as the user `gnats'.  Then run the
     `gen-index' command for each of your databases.  See *Note
     Administrative Utilities: Admin utils. for details on how to use
     `gen-index'.

  9. Sit back and enjoy your new GNATS 4 setup...


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

4 GNATS Administration
**********************

In daily usage, GNATS is self-maintaining.  However, there are various
administrative duties which need to be performed periodically.  Also,
requirements may change with time, so it may be necessary to make
changes to the GNATS configuration at some point:

_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 (*note Where GNATS
     lives: Locations.).  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 (*Note Setting up mail aliases:
     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 another database_
     GNATS supports multiple databases.  If you find at some point that
     you need to add another database to your server, the `mkdb' tool
     does most of the work for you.  *Note Adding another database:
     mkdb.

_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 automatically as needed.  However, if automatic directory
     creation has been switched off in the `dbconfig' file (*note The
     `dbconfig' file: 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.  *Note The `responsible' file: 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' (*note
     Regenerating the index: gen-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.
     (*Note Setting up mail aliases: Aliases.)

_BACKING UP YOUR DATA_
     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.


   *Note Where GNATS lives: Locations.

* Menu:

* GNATS configuration::   Overview of GNATS configuration
* databases file::        The databases file
* dbconfig file::         The dbconfig file
* Other config files::    Configuration files
* send-pr.conf file::     The send-pr.conf file
* Admin files::           Administrative data files
* Admin utils::           Administrative utilities
* Internal utils::        Internal utilities


File: gnats.info,  Node: GNATS configuration,  Next: databases file,  Up: Management

4.1 Overview of GNATS configuration
===================================

*Note Where GNATS lives: Locations.

   GNATS has two, well, actually three, 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.  In addition, there is a single
file that needs to be set up for the `send-pr' tool to work properly.
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:

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

`defaults'
     This directory contains the set of default per-database
     configuration files used when a new database is created with
     `mkdb'.

`gnatsd.host_access'
     Controls access levels for the different machines that will do
     lookups in the databases on this machine.  *Note GNATS access
     control: Access Control.

`gnatsd.user_access'
     Controls user access levels for the databases on this server. The
     settings apply to all databases (there is also a database-specific
     user access level file).  *Note GNATS access control: Access
     Control.

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

`dbconfig'
     Controls most aspects of how GNATS behaves when dealing with your
     database.  *Note The `dbconfig' file: dbconfig file.

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

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

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

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

`states'
     Lists the possible states for Problem Reports, typically ranging
     from "open" to "closed".  *Note The `states' file: addresses file.

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

`gnatsd.user_access'
     Specify the access levels for different users to your database.
     *Note GNATS access control: Access Control.


   The last file in this menagerie is the `send-pr' configuration file
`send-pr.conf'.  This file contains some defaults that need to be known
in order for `send-pr' to work.  The file needs to be present on all
hosts where `send-pr' is to be used.  *Note the `send-pr.conf' file:
send-pr.conf file.


File: gnats.info,  Node: databases file,  Next: dbconfig file,  Prev: GNATS configuration,  Up: Management

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

   Note that if you add a new local database, you must create its data
directory, including appropriate subdirectories and administrative
files.  This is best done using the `mkdb' tool, *Note mkdb::.


File: gnats.info,  Node: dbconfig file,  Next: Other config files,  Prev: databases file,  Up: Management

4.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:

   * Overall database configuration

   * Individual field configuration

   * Named query definitions

   * Audit-trail and outgoing email formats

   * Index file description

   * Initial Problem Report input fields

   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.

* Menu:

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


File: gnats.info,  Node: Overall database configuration,  Next: Individual field configuration,  Up: dbconfig file

4.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 {
       [options]
     }

   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.
     Note that if you have local users on the GNATS server itself,
     running for instance `query-pr', you may need to change the
     permissions to `0755'.


File: gnats.info,  Node: Individual field configuration,  Next: Field datatypes,  Prev: Overall database configuration,  Up: dbconfig file

4.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:

    `arrival-date'
          The arrival date of the PR

    `audit-trail'
          The audit-trail recording changes to the PR

    `category'
          The category that the PR falls into

    `closed-date'
          The date that the PR was closed

    `confidential'
          If set to `yes', the PR is confidential

    `description'
          A description of the problem

    `last-modified'
          The date the PR was last modified

    `number'
          The PR's unique numeric identifier

    `originator'
          The originator of the PR

    `priority'
          Priority of the PR

    `responsible'
          The person responsible for handling the PR

    `severity'
          Severity of the problem described by the PR

    `state'
          The current state of the PR

    `submitter-id'
          The user that submitted the PR

    `synopsis'
          The one-line description of the PR

    `unformatted'
          PR text which cannot be parsed and associated with other
          fields.

     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'.  We also recommend that you leave the actual
     fieldnames of these fields at their default values (i.e.
     capitalized versions of their built-in names), since some clients
     may depend on these names.

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

`textsearch'
     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.

`read-only'
     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.


File: gnats.info,  Node: Field datatypes,  Next: Edit controls,  Prev: Individual field configuration,  Up: dbconfig file

4.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
     (`:').

     The values in the `default' string for this field type should be
     separated by one of the defined separators.  An example clarifies
     this.  If we have a field named `ingredients' where the default
     values should be `sugar', `flour' and `baking powder' and the
     separator is a colon `:', the following sets these defaults:

          default "sugar:flour:baking powder"

`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.  An
     example of this kind of field is the built-in Category field with
     its associeted `categories' administrative 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.
     "Subfields" 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 subfields in the
     administrative file.  There must be at least one subfield, 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.

     Note that there is no `default' keyword for `enumerated-in-file'.
     These fields get their default value from the _first_ entry in the
     associated administrative file.

`multi-enumerated-in-file {'
`  path "filename"'
`  fields {'
`    "name" [ "name" ... ]'
`  } key "name"'
`  [ default "string" ]'
`  [ allow-any-value ]'
`  [ separators "string" ]'
`}'
     `multi-enumerated-in-file' is to `multienum' what
     `enumerated-in-file' is to `enum'.  Its options have the same
     meaning as their counterparts in the `multienum' and
     `enumerated-in-file' fields.

     _NOTE_: Keywords may appear in any sequence, with one exception -
     the `separators' keyword, if present, has to come last.  This rule
     only applies to fields of type `multi-enumerated-in-file'.

`date'
     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.


File: gnats.info,  Node: Edit controls,  Next: Named query definitions,  Prev: Field datatypes,  Up: dbconfig file

4.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 ]
       } ]
       [ require { "fieldname" ... } ]
     }

   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. See
*Note Audit-trail formats:: and *Note Outgoing email formats::.

   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.

   The `require' option specifies that one or more fields must have a
(non-blank) value when this field is changed.

   A field may be enforced to have a (non-blank) value at all times by
including it in the set of fields required for the initial PR, see
*Note Initial PR input fields::, as well as in the set of fields
required on change of the field itself.

   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.


File: gnats.info,  Node: Named query definitions,  Next: Audit-trail formats,  Prev: Edit controls,  Up: dbconfig file

4.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 *Note Formatting query-pr output::.
It basically contains a string with printf-like % escapes.  The output
of the query is formatted as specified by this 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'.


File: gnats.info,  Node: Audit-trail formats,  Next: Outgoing email formats,  Prev: Named query definitions,  Up: dbconfig file

4.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:

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

`$OldValue'
     The old value of the field.

`$NewValue'
     The new field value.

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

`$CurrentDate'
     The current date.

`$ChangeReason'
     The reason for the change; may be blank if no reason was supplied.

   These parameters may be used anywhere a `fieldname' can appear.


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

4.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:

`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

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


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

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

4.4 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

4.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 (*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

4.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:

     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

4.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:

     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

4.4.4 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

4.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:

     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

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


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

4.5 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

4.6 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

4.6.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. *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

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


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

4.7 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

4.7.1 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

4.7.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. *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

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


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

4.7.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 (*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

4.7.5 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

4.7.6 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

4.8 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

4.8.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.  *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

4.8.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; *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

4.8.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:' (*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

4.8.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 [ --show-prnum ] ]
               [ -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.  If the submission is successful a
     zero exit code is returned.  Otherwise, the reason(s) for the PR
     being rejected are printed, and a non-zero exit code is returned.

`--show-prnum'
     This option is used with the `--submit' option to display the PR
     number associated with the submitted PR.

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

4.8.5 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

4.8.6 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

Appendix A 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

A.1 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.


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

A.2 EXEC-PREFIX
===============

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

GNATS user tools
     `EXEC-PREFIX/bin'

administrative and support utilities
     `EXEC-PREFIX/libexec/gnats'

compiled libraries
     `EXEC-PREFIX/lib'
_etc..._

   `configure' supports several more options which allow you to specify
in great detail where different files are installed.  The locations
given in this appendix do not take into account highly customized
installations, but fairly ordinary GNATS installations should be
covered by the material here.  For a complete list of options accepted
by `configure', run `./configure --help' in the `gnats' subdirectory of
the distribution.

   Since most installations are not intended to be distributed around a
network, the default value for EXEC-PREFIX is the value of `prefix',
i.e., `/usr/local'.  However, using EXEC-PREFIX saves space when you
are installing a package on several different platforms for which many
files are identical; rather than duplicate them for each host, these
files can be shared in a common repository, and you can use symbolic
links on each host to find the host-dependent files.

   Use EXEC-PREFIX in conjunction with PREFIX to share host-independent
files, like libraries and `info' documents.  For example:

        _for each host:_
     configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-HOST
     make all install ...

Using this paradigm, all host-dependent binary files are installed into
`/usr/gnu/H-HOST/bin', while files which do not depend on the host type
for which they were configured are installed into `/usr/gnu'.

   You can then use a different symbolic link for `/usr/gnu' on each
host (`/usr' is usually specific to a particular machine; it is always
specific to a particular architecture).

       _on host-1:_
     ln -s /usr/gnu/H-HOST-1 /usr/gnu
       _on host-2:_
     ln -s /usr/gnu/H-HOST-2 /usr/gnu

To the end user, then, placing `/usr/gnu/bin' in her or his `PATH'
simply works transparently for each HOST type.

   You can change EXEC-PREFIX on the command line to `configure' using

     configure --exec-prefix=EXEC-PREFIX ...

   We recommend that you consult *Note Using `configure':
(configure)Using configure, before attempting this.


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

A.3 The `gnats-adm' directory
=============================

Each GNATS database located on a server has its own directory, as
listed in the `databases' (*note The `databases' file: databases file.
and given when the `mkdb' utility is invoked to initialize the database
(*note Initializing a new database: mkdb.).  This directory has several
subdirectories, one of which is named `gnats-adm'.  This directory
contains all configuration files related to this specific database,
including the `categories', `submitters', `responsible', `states',
`classes', `dbconfig', `addresses', `states' and `gnatsd.user_access',
as well as two files generated and maintained by GNATS, `index' and
`current'.


File: gnats.info,  Node: defaults,  Prev: gnats-adm,  Up: Locations

A.4 Default installation locations
==================================

PREFIX
     defaults to `/usr/local'; change using `configure' (*note
     Configuring and compiling the software: Configure and make.).

EXEC-PREFIX
     defaults to PREFIX; change using `configure' (*note Configuring
     and compiling the software: Configure and make.).

GNATS installs tools, utilities, and files into the following locations.

`EXEC-PREFIX/bin'

    `send-pr'
          *Note Submitting Problem Reports: send-pr.

    `edit-pr'
          *Note Editing existing Problem Reports: edit-pr.

    `query-pr'
          *Note Querying the database: query-pr.

`EXEC-PREFIX/libexec/gnats'

    `at-pr'
          *Note Timely reminders: at-pr.

    `check-db'
          *Note Checking database health: check-db.

    `delete-pr'
          Tool for deleting PRs.  Deprecated.  Use the -delete-pr
          option of `pr-edit' instead (*note The edit-pr driver:
          pr-edit.).

    `diff-prs'
          *Note The `diff-prs' tool: diff-prs.

    `file-pr'
          *Note Interface to pr-edit for filing new PRs: file-pr.

    `gen-index'
          *Note Regenerating the index: gen-index.

    `gnatsd'
          The GNATS daemon.

    `gnats-pwconv'
          *Note Converting old password files: gnats-pwconv.

    `mail-query'
          *Note Setting up mail aliases: Aliases.

    `mkcat'
          *Note Adding a problem category: mkcat.

    `mkdb'
          *Note Script for creating new databases: mkdb.

    `pr-age'
          *Note The `pr-age' tool: pr-age.

    `pr-edit'
          *Note The main PR processor: pr-edit.

    `queue-pr'
          *Note Handling incoming traffic: queue-pr.

    `rmcat'
          *Note Removing categories: rmcat.

`EXEC-PREFIX/lib/libiberty.a'
     The GNU `libiberty' library.

`PREFIX/etc/gnats'

    `databases'
          *Note The `databases' file: databases file.

    `defaults'
          *Note Overview of GNATS configuration: GNATS configuration.

    `gnatsd.host_access'
          *Note The `gnatsd.host_access' file: gnatsd.host_access.

    `gnatsd.user_access'
          *Note The `gnatsd.user_access' file: gnatsd.user_access.

`PREFIX/share/emacs/site-lisp'

    `gnats.el'
    `gnats.elc'
          The Emacs versions of the programs `send-pr', `query-pr',
          `edit-pr', and `view-pr'.  *Note The GNATS user tools: GNATS
          user tools.  To change this directory you must change the
          `lispdir' variable in `Makefile.in'; see *Note Configuring
          and compiling the software: Configure and make.

`PREFIX/info'

    `gnats.info'
    `send-pr.info'
          The GNATS manuals, in a form readable by `info' (the GNU
          hypertext browser).  *Note Reading GNU Online Documentation:
          (infoman)Info.

`PREFIX/man/man1'
`PREFIX/man/man8'

    `man' pages for all the GNATS tools and utilities.
          *Note The GNATS user tools: GNATS user tools.

`Per-database directory'

    `gnats-adm'
          Administration and configuration data files that define
          behaviour of the particular database.  The files

         `categories'

         `submitters'

         `responsible'

         `states'

         `classes'

         `dbconfig'

         `addresses'

         `states'

         `gnatsd.user_access'

         `index'
               (_This file is created by GNATS._)

         `current'
               (_This file is created by GNATS._)

          exist here.  *Note Other database-specific config files:
          Other config files, *Note Administrative data files: Admin
          files. and *Note Controlling access to databases: Access
          Control.

    `gnats-queue'
          Incoming Problem Reports are queued here until the next
          iteration of `queue-pr -r' (*note Handling incoming traffic:
          queue-pr.).

    `pending'
          If no default category is set, problem reports without a
          category are reassigned to the category `pending' and placed
          here pending intervention by GNATS administrators.  *Note
          GNATS administration: Management.

    `CATEGORY'
          Each valid category has a corresponding subdirectory in the
          database.  All Problem Reports associated with that category
          are kept in that subdirectory.



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

Appendix B The GNATS network server - `gnatsd'
**********************************************

This section describes in details how the GNATS network daemon works.
This information is mainly assumed to be useful for developers of GNATS
client software.

* Menu:

* Description of gnatsd::
* gnatsd options::
* gnatsd command protocol::
* gnatsd commands::
* gnatsd environment variables::


File: gnats.info,  Node: Description of gnatsd,  Next: gnatsd options,  Up: gnatsd

B.1 Description of `gnatsd'
===========================

The `gnatsd' network daemon is used to service remote GNATS requests
such as querying PRs, PR creation, deletion, and editing, and
miscellaneous database queries.  It uses a simple ASCII-based command
protocol (similar to SMTP or POP3) for communicating with remote
clients.

   It also provides a security model based either on IP-based
authentication (generally considered very weak) or username/passwords,
where passwords may be in cleartext, UNIX crypt or MD5 hash format.
Access through `gnatsd' is granted according to certain predefined
"access levels".  Access levels are further discussed in *Note
Controlling access to databases: Access Control.  It should be
emphasized that security has not been a focus of development until now,
but future versions are expected to address this more thoroughly.

   All of the GNATS clients are capable of communicating via the GNATS
remote protocol to perform their functions.

   `gnatsd' is usually started from the inetd facility and should run as
the `gnats' user (the actual username of this user is configurable
during installation, *note Configuring and compiling the software:
Configure and make. for details.)


File: gnats.info,  Node: gnatsd options,  Next: gnatsd command protocol,  Prev: Description of gnatsd,  Up: gnatsd

B.2 `gnatsd' options
====================

The daemon supports the following command-line options:

     gnatsd [--database database | -d database]
            [--not-inetd | -n] [--max-access-level LEVEL | -m LEVEL]
            [--version | -V] [--help | -h]

`-V, --version'
     Prints the program version to stdout and exits.

`-h, --help'
     Prints a short help text to stdout and exits.

`-d, --database'
     Specifies the default database which is to be serviced by this
     invocation of `gnatsd'. (The selected database may be changed via
     the `CHDB' command; the name set with this option is simply the
     default if no `CHDB' command is issued.)  If no database is
     specified, the database named default is assumed. This option
     overrides the database specified in the `GNATSDB' environment
     variable.

`-n, --not-inetd'
     As its name suggests, indicates that `gnatsd' is not being invoked
     from inetd. This can be used when testing `gnatsd', or if it is
     being run via ssh or some other mechanism.

     This has the effect of using the local hostname where `gnatsd' is
     being invoked for authentication purposes, rather than the remote
     address of the connecting client.

`--max-access-level, -m'
     Specifies the maximum access level that the connecting client can
     authenticate to.  Authentication is as normal but if the user or
     host authenticates at a higher level, access level is still forced
     to this level.  See *Note Controlling access to databases: Access
     Control. for details on access levels.


File: gnats.info,  Node: gnatsd command protocol,  Next: gnatsd commands,  Prev: gnatsd options,  Up: gnatsd

B.3 `gnatsd' command protocol
=============================

Commands are issued to `gnatsd' as one or more words followed by a
carriage-return/linefeed pair.  For example, the `CHDB' (change
database) command is sent as `CHDB database<CR><LF>' (the `CRLF' will
not be explicitly written for future examples.)

   Replies from `gnatsd' are returned as one or more response lines
containing a 3-digit numeric code followed by a human-readable string;
the line is terminated with a `<CR><LF>' pair.  For example, one
possible response to the `CHDB' command above would be:

     210 Now accessing GNATS database 'database'.

   The three-digit code is normally followed by a single ASCII space
(character 0x20).  However, if additional response lines are to be
returned from the server, there will be a single dash `-' instead of
the space character after the three-digit code.

   Response code values are divided into ranges.  The first digit
reflects the general type of response (such as "successful" or
"error"), and the subsequent digits identify the specific type of
response.

CODES 200-299
     Positive response indicating that the command was successful.  No
     subsequent data will be transmitted with the response.  In
     particular, code 210 (`CODE_OK') is used as the positive result
     code for most simple commands.

     Commands that expect additional data from the client (such as
     `SUBM' or `VFLD') use a two-step mechanism for sending the data.
     The server will respond to the initial command with either a 211
     (`CODE_SEND_PR') or 212 (`CODE_SEND_TEXT') response line, or an
     error code if an error occurred with the initial command.  The
     client is then expected to send the remaining data using the same
     quoting mechanism as described for server responses in the 300-349
     range.  The server will then send a final response line to the
     command.

CODES 300-399
     Positive response indicating that the query request was
     successful, and that a PR or other data will follow.  Codes
     300-349 are used when transmitting PRs, and 350-399 are used for
     other responses.

     Codes in the 300-349 range are followed by a series of
     `CRLF'-terminated lines containing the command response, usually a
     PR.  The final line of the result is a single period `.'.  Result
     lines that begin with a period have an extra period prepended to
     them.

     Codes in the 350-399 range use a different scheme for sending their
     responses. The three-digit numeric code will be followed by either
     a dash `-' or a single space.  If the code is followed by a dash,
     that indicates that another response line will follow.  The final
     line of the response has a single space after the three-digit code.

     In previous versions of the protocol the first line of a
     `CODE_INFORMATION' (310) response was to be ignored.  This is no
     longer the case.  Instead, any lines marked with code
     `CODE_INFORMATION_FILLER' (351) are to be ignored.  This allows the
     server to transmit additional headers or other human-readable text
     that can be safely ignored by the clients.

CODES 400-599
     An error occurred, usually because of invalid command parameters or
     invalid input from the client, missing arguments to the command,
     or a command was issued out of sequence.  The human-readable
     message associated with the response line describes the general
     problem encountered with the command.

     Multiple error messages may be returned from a command; in this
     case the `-' continuation character is used on all but the last
     response line.

CODES 600-799
     An internal error occurred on the server, a timeout occurred
     reading data from the client, or a network failure occurred.
     These errors are of the "this should not occur" nature, and
     retrying the operation may resolve the problem.  Fortunately, most
     GNATS transactions are idempotent; unfortunately, locking the
     database or a PR are not repeatable actions (we cannot determine
     if an existing lock is the one we originally requested, or someone
     else's).


File: gnats.info,  Node: gnatsd commands,  Next: gnatsd environment variables,  Prev: gnatsd command protocol,  Up: gnatsd

B.4 `gnatsd' commands
=====================

Note that the set of GNATS commands and their responses is somewhat
inconsistent and is very much in flux.  At present the GNATS clients
are rather simple-minded and not very strict about processing
responses.  For example, if the server were to issue a code 300
(`CODE_PR_READY') response to a `CHDB' command, the client would
happily expect to see a PR appear (and would print it out if one was
sent).

   It is thus suggested that any clients that use the GNATS protocol be
equally flexible about the way received responses are handled; in
particular, only the first digit of the response code should be assumed
to be meaningful, although subsequent digits are needed in some cases
(codes 300-399).  No attempt should be made to parse the message strings
on error response lines; they are only intended to be read by humans,
and will be changed on a regular basis.

   Almost every command may result in the response 440
(`CODE_CMD_ERROR').  This indicates that there was a problem with the
command arguments, usually because of insufficient or too many
arguments being specified.

   Access to most `gnatsd' commands requires a certain "access level".
For details of this, see *Note Privileged `gnatsd' commands: Privileged
gnatsd commands.

`USER [USERID PASSWORD]'
     Specifies the userid and password for database access.  Either
     both a username and password must be specified, or they both may
     be omitted; in the latter case, the current access level is
     returned.

     The possible server responses are:

     `350 (CODE_INFORMATION)'
     The current access level is specified.

     `422 (CODE_NO_ACCESS)'
     A matching username and password could not be found.

     `200 (CODE_OK)'
     A matching username and password was found, and the login was
     successful.

`QUIT'
     Requests that the connection be closed. Possible responses:

     `201 (CODE_CLOSING)'
     Normal exit.

     The `QUIT' command has the dubious distinction of being the only
     command that cannot fail.

`LIST LIST TYPE'
     Describes various aspects of the database.  The lists are returned
     as a list of records, one per line.  Each line may contain a
     number of colon-separated fields.

     Possible values for LIST TYPE include

     `Categories'
     Describes the legal categories for the database.

     `Submitters'
     Describes the set of submitters for the database.

     `Responsible'
     Lists the names in the responsible administrative file, including
     their full names and email addresses.

     `States'
     Lists the states listed in the state administrative file, including
     the state type (usually blank for most states; the closed state
     has a special type).

     `FieldNames'
     Lists the entire set of PR fields.

     `InitialInputFields'
     Lists the fields that _should_ be present when a PR is initially
     entered.

     `InitialRequiredFields'
     Lists fields that _have_ to be present and nonempty when a PR is
     initially entered (fields containing only blank characters such as
     spaces or newlines are considered empty.)

     `Databases'
     Lists the set of databases.

     The possible responses are:

     `301 (CODE_TEXT_READY)'
     Normal response, followed by the records making up the list as
     described above.

     `416 (CODE_INVALID_LIST)'
     The requested list does not exist.

`FTYP FIELD [FIELD ...]'
     Describes the type of data held in the field(s) specified with the
     command.  The currently defined data types are:

     `Text'
     A plain text field, containing exactly one line.

     `MultiText'
     A text field possibly containing multiple lines of text.

     `Enum'
     An enumerated data field; the value is restricted to one entry out
     of a list of values associated with the field.

     `MultiEnum'
     The field contains one or more enumerated values.  Values are
     separated with spaces or colons `:'.

     `Integer'
     The field contains an integer value, possibly signed.

     `Date'
     The field contains a date.

     `TextWithRegex'
     The value in the field must match one or more regular expressions
     associated with the field.

     The possible responses are:

     `350 (CODE_INFORMATION)'
     The normal response; the supplied text is the data type.

     `410 (CODE_INVALID_FIELD_NAME)'
     The specified field does not exist.

     If multiple field names were given, multiple response lines will be
     sent, one for each field, using the standard continuation
     protocol; each response except the last will have a dash `-'
     immedately after the response code.

`FTYPINFO FIELD PROPERTY'
     Provides field-type-related information.  Currently, only the
     property `separators' for MultiEnum fields is supported.  When
     `separators' is specified, the possible return codes are:

     `350 (CODE_INFORMATION)' A proper MultiEnum FIELD was specified
     and the returned text is the string of separators specified for
     the field in the dbconfig file (*note Field datatypes::) quoted in
     `'''s.

     `435 (CODE_INVALID_FTYPE_PROPERTY)' The `separators' property is
     not defined for this field, i.e.  the specified FIELD is not of
     type MultiEnum.

     Currently, specifying a different property than `separators'
     results in return code 435 as above.

`FDSC FIELD [FIELD ... ]'
     Returns a human-readable description of the listed field(s).  The
     possible responses are:

     `350 (CODE_INFORMATION)' The normal response; the supplied text is
     the field description.

     `410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.

     Like the `FVLD' command, the standard continuation protocol will be
     used if multiple fields were specified with the command.

`FIELDFLAGS FIELD [FIELD ... ]'
     Returns a set of flags describing the specified field(s).  The
     possible responses are either

     `410 (CODE_INVALID_FIELD_NAME)'
     meaning that the specified field is invalid or nonexistent, or

     `350 (CODE_INFORMATION)'
     which contains the set of flags for the field.  The flags may be
     blank, which indicate that no special flags have been set for this
     field.

     Like the `FDSC' and `FTYP' commands, multiple field names may be
     listed with the command, and a response line will be returned for
     each one in the order that the fields appear on the command line.

     The flags include:

     `textsearch'
     The field will be searched when a text field search is requested.

     `allowAnyValue'
     For fields that contain enumerated values, any legal value may be
     used in the field, not just ones that appear in the enumerated
     list.

     `requireChangeReason'
     If the field is edited, a reason for the change must be supplied in
     the new PR text describing the reason for the change. The reason
     must be supplied as a multitext PR field in the new PR whose name
     is `field-Changed-Why' (where `field' is the name of the field
     being edited).

     `readonly'
     The field is read-only, and cannot be edited.

`FVLD FIELD'
     Returns one or more regular expressions or strings that describe
     the valid types of data that can be placed in field.  Exactly what
     is returned is dependent on the type of data that can be stored in
     the field.  For most fields a regular expression is returned; for
     enumerated fields, the returned values are the list of legal
     strings that can be held in the field.

     The possible responses are:

     `301 (CODE_TEXT_READY)'
     The normal response, which is followed by the list of regexps or
     strings.

     `410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.

`VFLD FIELD'
     `VFLD' can be used to validate a given value for a field in the
     database.  The client issues the `VFLD' command with the name of
     the field to validate as an argument.  The server will either
     respond with `212 (CODE_SEND_TEXT)', or `410
     (CODE_INVALID_FIELD_NAME)' if the specified field does not exist.

     Once the `212' response is received from the server, the client
     should then send the line(s) of text to be validated, using the
     normal quoting mechanism described for PRs.  The final line of
     text is followed by a line containing a single period, again as
     when sending PR text.

     The server will then either respond with `210 (CODE_OK)',
     indicating that the text is acceptable, or one or more error codes
     describing the problems with the field contents.

`INPUTDEFAULT FIELD [FIELD ... ]'
     Returns the suggested default value for a field when a PR is
     initially created.  The possible responses are either `410
     (CODE_INVALID_FIELD_NAME)', meaning that the specified field is
     invalid or nonexistent, or `350 (CODE_INFORMATION)' which contains
     the default value for the field.

     Like the `FDSC' and `FTYP' commands, multiple field names may be
     listed with the command, and a response line will be returned for
     each one in the order that the fields appear on the command line.

`RSET'
     Used to reset the internal server state.  The current query
     expression is cleared, and the index of PRs may be reread if it
     has been updated since the start of the session.  The possible
     responses are:

     `200 (CODE_OK)'
     The state has been reset.

     `440 (CODE_CMD_ERROR)'
     One or more arguments were supplied to the command.

     `6xx (internal error)'
     There were problems resetting the state (usually because the index
     could not be reread).  The session will be immediately terminated.

`LKDB'
     Locks the main GNATS database.  No subsequent database locks will
     succeed until the lock is removed.  Sessions that attempt to write
     to the database will fail.  The possible responses are:

     `200 (CODE_OK)' The lock has been established.

     `440 (CODE_CMD_ERROR)' One or more arguments were supplied to the
     command.

     `431 (CODE_GNATS_LOCKED)' The database is already locked, and the
     lock could not be obtained after 10 seconds.

     `6xx (internal error)' An internal error occurred, usually because
     of permission or other filesystem-related problems. The lock may
     or may not have been established.

`UNDB'
     Unlocks the database.  Any session may steal a database lock; no
     checking of any sort is done.  The possible responses are:

     `200 (CODE_OK)'
     The lock has been removed.

     `432 (CODE_GNATS_NOT_LOCKED)'
     The database was not locked.

     `440 (CODE_CMD_ERROR)'
     One or more arguments were supplied to the command.

     `6xx (internal error)'
     The database lock could not be removed, usually because of
     permissions or other filesystem-related issues.

`LOCK PR USER [PID]'
     Locks the specified PR, marking the lock with the USER name and
     the optional PID. (No checking is done that the USER or PID
     arguments are valid or meaningful; they are simply treated as
     strings.)

     The `EDIT' command requires that the PR be locked before it may be
     successfully executed.  However, it does not require that the lock
     is owned by the editing session, so the usefulness of the lock is
     simply as an advisory measure.

     The `APPN' and `REPL' commands lock the PR as part of the editing
     process, and they do not require that the PR be locked before they
     are invoked.

     The possible responses are:

     `440 (CODE_CMD_ERROR)'
     Insufficient or too many arguments were specified to the command.

     `300 (CODE_PR_READY)'
     The lock was successfully obtained; the text of the PR (using the
     standard quoting mechanism for PRs) follows.

     `400 (CODE_NONEXISTENT_PR)'
     The PR specified does not exist.

     `430 (CODE_LOCKED_PR)'
     The PR is already locked by another session.

     `6xx (internal error)'
     The PR lock could not be created, usually because of permissions or
     other filesystem-related issues.

`UNLK PR'
     Unlocks PR.  Any user may unlock a PR, as no checking is done to
     determine if the requesting session owns the lock.

     The possible responses are:

     `440 (CODE_CMD_ERROR)'
     Insufficient or too many arguments were specified to the command.

     `200 (CODE_OK)'
     The PR was successfully unlocked.

     `433 (CODE_PR_NOT_LOCKED)'
     The PR was not locked.

     `6xx (internal error)'
     The PR could not be unlocked, usually because of permission or
     other filesystem-related problems.

`DELETE PR'
     Deletes the specified PR. The user making the request must have
     admin privileges (*note Controlling access to databases: Access
     Control.).  If successful, the PR is removed from the filesystem
     and the index file; a gap will be left in the numbering sequence
     for PRs.  No checks are made that the PR is closed.

     The possible responses are:

     `200 (CODE_OK)'
     The PR was successfully deleted.

     `422 (CODE_NO_ACCESS)'
     The user requesting the delete does not have admin privileges.

     `430 (CODE_LOCKED_PR)'
     The PR is locked by another session.

     `431 (CODE_GNATS_LOCKED)'
     The database has been locked, and no PRs may be updated until the
     lock is cleared.

     `6xx (internal error)'
     The PR could not be successfully deleted, usually because of
     permission or other filesystem-related problems.

`CHEK [initial]'
     Used to check the text of an entire PR for errors.  Unlike the
     `VFLD' command, it accepts an entire PR at once instead of the
     contents of an individual field.

     The `initial' argument indicates that the PR text to be checked is
     for a PR that will be newly created, rather than an edit or
     replacement of an existing PR.

     After the `CHEK' command is issued, the server will respond with
     either a `440 (CODE_CMD_ERROR)' response indicating that the
     command arguments were incorrect, or a `211 (CODE_SEND_PR)'
     response code will be sent.

     Once the `211' response is received from the server, the client
     should send the PR using the normal PR quoting mechanism; the
     final line of the PR is then followed by a line containing a
     single period, as usual.

     The server will then respond with either a `200 (CODE_OK)'
     response, indicating there were no problems with the supplied
     text, or one or more error codes listing the problems with the PR.

`EDIT PR'
     Verifies the replacement text for PR.  If the command is
     successful, the contents of PR are completely replaced with the
     supplied text.  The PR must previously have been locked with the
     `LOCK' command.

     The possible responses are:

     `431 (CODE_GNATS_LOCKED)'
     The database has been locked, and no PRs may be updated until the
     lock is cleared.

     `433 (CODE_PR_NOT_LOCKED)'
     The PR was not previously locked with the `LOCK' command.

     `400 (CODE_NONEXISTENT_PR)'
     The specified PR does not currently exist.  The `SUBM' command
     should be used to create new PRs.

     `211 (CODE_SEND_PR)'
     The client should now transmit the replacement PR text using the
     normal PR quoting mechanism.  After the PR has been sent, the
     server will respond with either `200 (CODE_OK)' indicating that
     the edit was successful, or one or more error codes listing
     problems either with the replacement PR text or errors encountered
     while updating the PR file or index.

`EDITADDR ADDRESS'
     Sets the e-mail address of the person communicating with `gnatsd'.
     The command requires at least the `edit' access level.

     The possible responses are:

     `200 (CODE_OK)'
     The address was successfully set.

     `440 (CODE_CMD_ERROR)'
     Invalid number of arguments were supplied.

`APPN PR FIELD'
`REPL PR FIELD'
     Appends to or replaces the contents of FIELD in PR with the
     supplied text.  The command returns a `201 (CODE_SEND_TEXT)'
     response; the client should then transmit the new field contents
     using the standard PR quoting mechanism.  After the server has
     read the new contents, it then attempts to make the requested
     change to the PR.

     The possible responses are:

     `200 (CODE_OK)'
     The PR field was successfully changed.

     `400 (CODE_NONEXISTENT_PR)'
     The PR specified does not exist.

     `410 (CODE_INVALID_FIELD_NAME)'
     The specified field does not exist.

     `402 (CODE_UNREADABLE_PR)'
     The PR could not be read.

     `431 (CODE_GNATS_LOCKED)'
     The database has been locked, and no PRs may be updated until the
     lock is cleared.

     `430 (CODE_LOCKED_PR)'
     The PR is locked, and may not be altered until the lock is cleared.

     `413 (CODE_INVALID_FIELD_CONTENTS)'
     The supplied (or resulting) field contents are not valid for the
     field.

     `6xx (internal error)'
     An internal error occurred, usually because of permission or other
     filesystem-related problems.  The PR may or may not have been
     altered.

`SUBM'
     Submits a new PR into the database.  The supplied text is verified
     for correctness, and if no problems are found a new PR is created.

     The possible responses are:

     `431 (CODE_GNATS_LOCKED)'
     The database has been locked, and no PRs may be submitted until the
     lock is cleared.

     `211 (CODE_SEND_PR)'
     The client should now transmit the new PR text using the normal
     quoting mechanism.  After the PR has been sent, the server will
     respond with either `351 (CODE_INFORMATION_FILLER)' and `350
     (CODE_INFORMATION)' responses indicating that the new PR has been
     created and supplying the number assigned to it, or one or more
     error codes listing problems with the new PR text.

`CHDB DATABASE'
     Switches the current database to the name specified in the command.

     The possible responses are:

     `422 (CODE_NO_ACCESS)'
     The user does not have permission to access the requested database.

     `417 (CODE_INVALID_DATABASE)'
     The database specified does not exist, or one or more configuration
     errors in the database were encountered.

     `220 (CODE_OK)'
     The current database is now DATABASE.  Any operations performed
     will now be applied to DATABASE.

`DBLS'
     Lists the known set of databases.

     The possible responses are:

     `6xx (internal error)'
     An internal error was encountered while trying to obtain the list
     of available databases, usually due to lack of permissions or other
     filesystem-related problems, or the list of databases is empty.

     `301 (CODE_TEXT_READY)'
     The list of databases follows, one per line, using the standard
     quoting mechanism.  Only the database names are sent.

     The `gnatsd' access level `listdb' denies access until the user
     has authenticated with the USER command.  The only other command
     available at this access level is `DBLS'.  This access level
     provides a way for a site to secure its GNATS databases while still
     providing a way for client tools to obtain a list of the databases
     for use on login screens etc.  *Note Controlling access to
     databases: Access Control.

`DBDESC DATABASE'
     Returns a human-readable description of the specified DATABASE.

     Responses include:

     `6xx (internal error)'
     An internal error was encountered while trying to read the list of
     available databases, usually due to lack of permissions or other
     filesystem-related problems, or the list of databases is empty.

     `350 (CODE_INFORMATION)'
     The normal response; the supplied text is the database description.

     `417 (CODE_INVALID_DATABASE)'
     The specified database name does not have an entry.

`EXPR QUERY EXPRESSION'
     Specifies a QUERY EXPRESSION used to limit which PRs are returned
     from the `QUER' command.  The expression uses the normal query
     expression syntax, (*note Query expressions::).

     Multiple `EXPR' commands may be issued; the expressions are boolean
     ANDed together.

     Expressions are cleared by the `RSET' command.

     Possible responses include:

     `415 (CODE_INVALID_EXPR)'
     The specified expression is invalid, and could not be parsed.

     `200 (CODE_OK)'
     The expression has been accepted and will be used to limit the
     results returned from `QUER'.

`QFMT QUERY FORMAT'
     Use the specified QUERY FORMAT to format the output of the `QUER'
     command.  The query format may be either the name of a query
     format known to the server (*note Named query definitions::), or an
     actual query format (*note Formatting query-pr output::).  The
     possible responses are:

     `200 (CODE_OK)'
     The normal response, which indicates that the query format is
     acceptable.

     `440 (CODE_CMD_ERROR)'
     No query format was supplied.

     `418 (CODE_INVALID_QUERY_FORMAT)'
     The specified query format does not exist, or could not be parsed.

`QUER [PR] [PR] [...]'
     Searches the contents of the database for PRs that match the
     (optional) specified expressions with the `EXPR' command. If no
     expressions were specified with `EXPR', the entire set of PRs is
     returned.

     If one or more PRs are specified on the command line, only those
     PRs will be searched and/or output.

     The format of the output from the command is determined by the
     query format selected with the `QFMT' command.

     The possible responses are:

     `418 (CODE_INVALID_QUERY_FORMAT)'
     A valid format was not specified with the `QFMT' command prior to
     invoking `QUER'.

     `300 (CODE_PR_READY)'
     One or more PRs will be output using the requested query format.
     The PR text is quoted using the normal quoting mechanisms for PRs.

     `220 (CODE_NO_PRS_MATCHED)'
     No PRs met the specified criteria.

`ADMV FIELD KEY [SUBFIELD]'
     Returns an entry from an administrative data file associated with
     FIELD. KEY is used to look up the entry in the data file. If
     SUBFIELD is specified, only the value of that subfield is
     returned; otherwise, all of the fields in the adm data file are
     returned, separated by colons `:'.

     The responses are:

     `410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.

     `221 (CODE_NO_ADM_ENTRY)' An adm entry matching the key was not
     found, or the field does not have an adm file associated with it.

     `350 (CODE_INFORMATION)' The normal response; the supplied text is
     the requested field(s).


File: gnats.info,  Node: gnatsd environment variables,  Prev: gnatsd commands,  Up: gnatsd

B.5 `gnatsd' environment variables
==================================

`gnatsd' supports the `GNATSDB' environment varable, *Note
Environment::, in almost the same way as the GNATS tools do.  This
variable is used to determine which database to use.  For a local
database, it contains the name of the database to access. `gnatsd'
cannot service remote databases (though it might be interesting if it
could) so the database is always assumed to be local.

   If `GNATSDB' is not set and the `--database' option is not supplied,
it is assumed that the database is local and that its name is `default'.


File: gnats.info,  Node: Access Control,  Next: Regexps,  Prev: gnatsd,  Up: Top

Appendix C Controlling access to databases
******************************************

* Menu:

* Overview::
* Overall gnatsd access level::
* gnatsd.host_access::           Per-host access settings
* gnatsd.user_access::           Access levels per user
* Privileged gnatsd commands::


File: gnats.info,  Node: Overview,  Next: Overall gnatsd access level,  Up: Access Control

C.1 Overview
============

GNATS supports granting various levels of access to the GNATS databases
served by the network daemon, `gnatsd'.

   GNATS access can be controlled at these levels:

`deny'
     gnatsd closes the connection

`none'
     no further access until userid and password given

`listdb'
     only listing of available databases is allowed

`view'
     query and view PRs with Confidential=no only

`viewconf'
     query and view PRs with Confidential=yes

`edit'
     full edit access

`admin'
     full admin access

These access levels are used in the following settings:

   * overall gnatsd access level

   * overall access level set by host name or IP address

   * overall access level set by userid and password

   * per-database access level set by userid and password


File: gnats.info,  Node: Overall gnatsd access level,  Next: gnatsd.host_access,  Prev: Overview,  Up: Access Control

C.2 Overall `gnatsd' access level
=================================

The overall `gnatsd' access level is set by starting `gnatsd' with the
option

     `-m' LEVEL or `--maximum-access-level'=LEVEL,

where LEVEL is one of the six access levels listed above.  This
restricts any access to the GNATS daemon to levels up to and including
LEVEL, regardless of the settings in the access control files discussed
below.  If this option is left out, any access levels set in the access
control files will be allowed.

   The discussion below assumes that the pre-build configure of GNATS
was done without altering the default values for the
`--with-gnatsd-user-access-file' and `--with-gnatsd-host-access-file'
options.  If non-default values were given, substitute as appropriate
below.


File: gnats.info,  Node: gnatsd.host_access,  Next: gnatsd.user_access,  Prev: Overall gnatsd access level,  Up: Access Control

C.3 Overall access levels per host
==================================

The host access file (by default
`/usr/local/etc/gnats/gnatsd.host_access') controls overall access
levels on a per-host basis, meaning that settings in this file apply
across all databases on the server.  Entries in this file are in the
following format:

   HOST:ACCESS-LEVEL:WHATEVER

HOST is the hostname or IP address of the host contacting gnatsd.
Wildcard characters are supported: `*' matches anything; `?' matches
any single character.  By using wildcards, you can specify access
levels for entire network subnets and domains.  Note that when GNATS
authenticates hosts, it reads the entries in this file in sequence
until a match is found.  This means that wildcard entries must be
placed near the end of the file, otherwise, they will override
non-wildcard entries appearing after the wildcard ones.

   The second field is the access level of HOST.  The default is
`deny'.  If the user's hostname isn't in the file or its access level
is set to `deny', the connection is closed immediately.

   GNATS currently doesn't make use of the third field. Remember to
still include the second `:' on the line if you choose to leave the
third field empty.

   Whenever a `CHDB' command is processed (or defaulted), the user's
access level is set to the level for their host, as determined by the
values in the `gnatsd.host_access' file.  However, even if a host is
given the `none' access level, an individual can still give the `USER'
command to possibly gain a higher (but never lower) access than is set
for their host.  The gnatsd `USER' command takes two arguments: `USER
<userid> <passwd>'.


File: gnats.info,  Node: gnatsd.user_access,  Next: Privileged gnatsd commands,  Prev: gnatsd.host_access,  Up: Access Control

C.4 Access levels per user
==========================

Access levels per user can be set both across all databases on the
server or on a per-database basis.  The `gnatsd.user_access' file in a
database's `gnats-adm' directory specifies the user access rules for
that database.  If it doesn't exist, or doesn't contain the user name
given to `gnatsd', then the overall user access file (by default
`/usr/local/etc/gnats/gnatsd.user_access') specifying the per-user
access levels across all the databases on the server is checked.

   The user access files can only _increase_ the access level defined
in the host access files for the given host, they can never lower it.

   If the access level is `none' after processing the userid and
password, the connection is closed.

   The `gnatsd.user_access' files can contain plain text passwords, in
such a case they should be owned by the GNATS user with file permission
600.

   Wildcard characters are supported for the userid and password with
plain text passwords.  A null string or `*' matches anything; `?'
matches any one character.  Note that when GNATS authenticates users,
it reads the entries in this file in sequence until a match is found.
This means that wildcard entries must be placed near the end of the
file, otherwise, they will override non-wildcard entries appearing
after the wildcard ones.

   Entries in the database-specific `gnatsd.user_access' user access
file in the `gnats-adm' directory of the database have the following
general format:

   USERID:PASSWORD:ACCESS-LEVEL

   The overall `gnatsd.user_access' user access file adds a fourth
DATABASES field:

   USERID:PASSWORD:ACCESS-LEVEL:DATABASES

PASSWORD should either be in plain text, DES `crypt()'(1) or MD5 hash
format(2).

   If the password is in plain text format, it must be prefixed by
`$0$' and if it is in MD5 format, it needs to be prefixed by the string
`$1$'.(3) Passwords encrypted by `crypt()' should have no prefix. If no
password is given then users can login with an empty password string.

   A `gnats-passwd' tool to manage `gnatsd.user_access' files is
planned.  In the meantime, `crypt()' passwords can be generated by
using standard UNIX passwords tools, while MD5 passwords can be
generated with the following little Perl snippet:

     perl -e 'use Crypt::PasswdMD5 ; print Crypt::PasswdMD5::unix_md5_crypt
     "PASSWORD" , time() % 100000000'

If your Perl installation doesn't have the Crypt module installed, you
need to install it.  On most systems, the following command achieves
this:

     perl -MCPAN -e 'install Crypt::PasswdMD5'

   A tool for conversion of pre-version 4 `gnatsd.user_access' files is
distributed with GNATS 4.  *Note Converting old password files:
gnats-pwconv.

The ACCESS-LEVEL field should contain one of the values listed at the
beginning of this appendix.  This overrides (increases but never
lowers) the access level given as the default for the user's host in the
global gnatsd.host_access file.

   The following shows an example `gnatsd.user_access' file with plain
text passwords:

     rickm:$0$ruckm:edit
     pablo:$0$pueblo:view
     *::none

And this is the same file with MD5-encrypted passwords:
     rickm:$1$92388613$D7ZIYikzTUqd./dODTFrI.:edit
     pablo:$1$92388652$QRfAhIBG5elT.FQjQKhj80:view
     *::none

In these examples, anybody other than rickm and pablo get denied
access, assuming that the host access level is also `none'.  You could
set the catch-all rule at the end to be `*::view' to allow view access
to anyone who does not supply a password.  Note the important detail
that such a rule would allow view access only to persons who do not
supply a password at all, i.e. if rickm or pablo tries to log in but
mistypes his password, this rule would not apply and they would be
denied access entirely.  This is by design, since people might be
surprised if they suddenly found themselves logged in, but with a lower
access level than they usually have.

   The DATABASES field contains a comma-separated list of database
names, as defined in the `databases' file (*note The `databases' file:
databases file.  Wildcard characters are supported. The databases
listed in this field are the ones to which the other settings on the
same line will be applied.

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

   (1) DES crypt is the standard password encryption format used by
most UNIX systems

   (2) MD5 is only supported on platforms that have a `crypt()'
function that supports MD5. Among others, this currently includes GNU
Linux and OpenBSD.

   (3) Some systems support even more encryption methods.  In FreeBSD,
for instance, a prefix of `$2$' implies Blowfish encoding.  GNATS will
happily accept any encryption that the OS supports.


File: gnats.info,  Node: Privileged gnatsd commands,  Prev: gnatsd.user_access,  Up: Access Control

C.5 Privileged `gnatsd' commands
================================

Every `gnatsd' command has a minimum access level attached to it.  If
your access level is too low for a command, you get this response:

       LOCK 12
       422 You are not authorized to perform this operation (LOCK).

The commands `CHDB', `USER' and `QUIT' are unrestricted.

The `DBLS' command requires at least `listdb' access.

A user must have at least `edit' access for these commands:

`LKDB'
     lock the main GNATS database.

`UNDB'
     unlock the main GNATS database.

`LOCK PR USER PID'
     lock PR for USER and optional PID and return PR text.

`UNLK PR'
     unlock PR.

`EDIT PR'
     check in edited PR.

`APPN PR FIELD, REPL PR FIELD'
     Appends to or replaces the contents of FIELD in PR.

   The `DELETE' PR command is special in that it requires `admin'
access.

All other commands require `view' access.

   `edit-pr' and `query-pr' accept the command line arguments
`-v|--user' and `-w|--passwd'.  *Note The GNATS User Tools: GNATS user
tools.


File: gnats.info,  Node: Regexps,  Next: dbconfig recipes,  Prev: Access Control,  Up: Top

Appendix D Querying using regular expressions
*********************************************

See also *Note Query expressions::.

   Unfortunately, we do not have room in this manual for a complete
exposition on regular expressions.  The following is a basic summary of
some regular expressions you might wish to use.

   _NOTE: When you use query expressions containing regular expressions
as part of an ordinary query-pr shell command line, you need to quote
them with `''', otherwise the shell will try to interpret the special
characters used, yielding highly unpredictable results._

   *Note Regular Expression Syntax: (regex)Regular Expression Syntax,
for details on regular expression syntax.  Also see *Note Syntax of
Regular Expressions: (emacs)Regexps, but beware that the syntax for
regular expressions in Emacs is slightly different.

   All search criteria options to `query-pr' rely on regular expression
syntax to construct their search patterns.  For example,

     query-pr --expr 'State="open"' --format full

matches all PRs whose `State' values match with the regular expression
`open'.

   We can substitute the expression `o' for `open', according to GNU
regular expression syntax.  This matches all values of `State' which
begin with the letter `o'.

   We see that

     query-pr --expr 'State="o"' --format full

   is equivalent to

     query-pr --expr 'State="open"' --format full

in this case, since the only value for `State' which matches the
expression `o' in a standard installation is `open'.  `State="o"' also
matches `o', `oswald', and even `oooooo', but none of those values are
valid states for a Problem Report in default GNATS installations.

   We can also use the expression operator `|' to signify a logical
`OR', such that

     query-pr --expr 'State="o|a"' --format full

matches all `open' or `analyzed' Problem Reports.

   Regular expression syntax considers a regexp token surrounded with
parentheses, as in `(REGEXP)', to be a "group".  This means that
`(ab)*' matches any number (including zero) of contiguous instances of
`ab'.  Matches include `', `ab', and `ababab'.

   Regular expression syntax considers a regexp token surrounded with
square brackets, as in `[REGEXP]', to be a "list".  This means that
`Char[(ley)(lene)(broiled)' matches any of the words `Charley',
`Charlene', or `Charbroiled' (case is significant; `charbroiled' is not
matched).

   Using groups and lists, we see that

     query-pr --expr 'Category="gcc|gdb|gas"' --format full

is equivalent to

     query-pr --expr 'Category="g(cc|db|as)"' --format full

and is also very similar to

     query-pr --expr 'Category="g[cda]"' --format full

with the exception that this last search matches any values which begin
with `gc', `gd', or `ga'.

   The `.' character is known as a "wildcard".  `.' matches on any
single character.  `*' matches the previous character (except
newlines), list, or group any number of times, including zero.
Therefore, we can understand `.*' to mean "match zero or more instances
of any character."

     query-pr --expr 'State=".*a"' --format full

matches all values for `State' which contain an `a'.  (These include
`analyzed' and `feedback'.)

   Another way to understand what wildcards do is to follow them on
their search for matching text.  By our syntax, `.*' matches any
character any number of times, including zero.  Therefore, `.*a'
searches for any group of characters which end with `a', ignoring the
rest of the field.  `.*a' matches `analyzed' (stopping at the first
`a') as well as `feedback'.

   _Note:_ When using `fieldtype:Text' or `fieldtype:Multitext' (*note
Query expressions::), you do not have to specify the token `.*' at the
beginning of your expression to match the entire field.  For the
technically minded, this is because these queries use `re_search'
rather than `re_match'.  `re_match' "anchors" the search at the
beginning of the field, while `re_search' does not anchor the search.

   For example, to search in the `>Description:' field for the text

     The defrobulator component returns a nil value.

we can use

     query-pr --expr 'fieldtype:Multitext="defrobulator.*nil"' --format full

   To also match newlines, we have to include the expression `(.|^M)'
instead of just a dot (`.').  `(.|^M)' matches "any single character
except a newline (`.') _or_ (`|') any newline (`^M')."  This means that
to search for the text

     The defrobulator component enters the bifrabulator routine
     and returns a nil value.

we must use

     query-pr --expr 'fieldtype:Multitext="defrobulator(.|^M)*nil"'
              --format full

   To generate the newline character `^M', type the following depending
on your shell:

`csh'
     `_control_-V _control_-M'

`tcsh'
     `_control_-V _control_-J'

`sh (_or_ bash)'
     Use the <RETURN> key, as in

          (.|
          )

   Again, see *Note Regular Expression Syntax: (regex)Regular
Expression Syntax, for a much more complete discussion on regular
expression syntax.


File: gnats.info,  Node: dbconfig recipes,  Next: Support,  Prev: Regexps,  Up: Top

Appendix E `dbconfig' recipes
*****************************

The `dbconfig' file (*Note The `dbconfig' file: dbconfig file.) is the
heart of any GNATS installation.  It contains some very powerful
machinery, something which this appendix tries to illustrate.

   We provide a range of examples that are both intended to be useful in
their own right and to serve as starting points or building blocks for
your own modifications.

Provide Gnatsweb URL in initial response
........................................

Sites that have Gnatsweb installed may wish to modify the response
e-mail which is sent to the submitter of a PR so that it includes a URL
where the status of the PR can be monitored.  In order to allow this,
you should first create an entry in `gnatsd.user_access' which allows
viewing of PRs in your database (*Note The `gnatsd.user_access' file:
gnatsd.user_access.)

   Next, locate the entry `mail-format "initial-response-to-submitter"'
in the `dbconfig' file of your database and add the following _before_
the line reading "The individual assigned..." in the `body' section:


\nYou can follow the status of this report on\n\
http://hostname/cgi-bin/scriptname?\n\
cmd=view&database=dbname&user=username&\n\
password=passwd&pr=%s\n\n\

Substitute `hostname', `cgi-bin' and `scriptname' as appropriate for
the setup of your web server.  The part before the `?' would typically
look something like `http://www.example.com/cgi-bin/gnatsweb.pl'.
Substitute the name of your database for `dbname', and the username and
password of the user with `view' rights for `username' and `passwd'.

Next, add a `Number' to the `fields' list statement inside the `body'
so it reads as follows:


fields { "Category" "Number" "Number" "Responsible"
         "Category" "Responsible" "Synopsis"
         "Arrival-Date" }

State full name of responsible in initial response
..................................................

The initial e-mail response to the submitter of a PR identifies the
responsible person assigned to the PR as follows: "The individual
assigned to look at your report is: GNATS USERNAME".  Some sites may
wish to modify this so that the full name of the responsible person is
used instead of the GNATS user name.

   The full name is contained in the `fullname' subfield of the user's
entry in the `responsible' file and can be accessed as
`Responsible[fullname]' (*note Enumerated field administrative files:
administrative files.)

   The change is achieved by editing the `dbconfig' item `mail-format
"initial-response-to-submitter"' and changing the `fields' part of the
`Body' from


fields { "Category" "Number" "Responsible"
         "Category" "Responsible" "Synopsis"
         "Arrival-Date" }

to


fields { "Category" "Number" "Responsible[fullname]"
         "Category" "Responsible" "Synopsis"
         "Arrival-Date" }

Append-only Audit-Trail
.......................

The Audit-Trail of a PR is by default editable.  For some applications,
one might want to make the Audit-Trail append-only, so it provides a
full and unchangeable case history.  Also by default, only certain
changes, such as change of state and change of responsible gets
recorded in the Audit-Trail.  In some cases, it might also be
convenient to have a way of inserting comments directly into the
Audit-Trail.

   The following procedure creates such an append-only Audit-Trail and
adds a PR field which makes it possible to register comments in the
Audit-Trail.

First, add the keyword `read-only' to the Audit-Trail field definition
in `dbconfig'.

Then, add the following field definition to `dbconfig':


field "Add-To-Audit-Trail" {
   description "Add a log entry to the Audit Trail"
   multitext { default "\n" }
   on-change  {
        add-audit-trail
        audit-trail-format {
        format "**** Comment added by %s on %s ****\n %s\n\n"
        fields { "$EditUserEmailAddr" "$CurrentDate" "$NewValue"
        }
        }
    }
    on-change {
        set-field "Add-To-Audit-Trail" { "\n" }
    }
}

Supporting GNATS "release-based" fields
.......................................

When installing GNATS version 3.x, it was possible to choose whether to
enable three optional fields: `Quarter', `Keywords' and
`Date-Required'.  Default installations had these fields switched off,
and installations which had them were called "release-based".

   The default `dbconfig' shipped with GNATS version 4 or newer does
not have these fields, so if you are upgrading from an old
release-based system, you need to add the following field definitions to
your `dbconfig' file:


field "Quarter" {
    description "What quarter does the PR fall into?"
    text
    query-default inexact-regexp
    textsearch
}

field "Keywords" {
    description "Keywords used to index this PR"
    text
    query-default inexact-regexp
    textsearch
}

field "Date-Required" {
    description "Date that the PR must be fixed by"
    date
}

   A side note: Pre-release versions of GNATS 4 also had a field named
`Cases'.  For those who may need it, here is the field definition of
`Cases':


field "Cases" {
    text
    query-default inexact-regexp
    textsearch
}


File: gnats.info,  Node: Support,  Next: Index,  Prev: dbconfig recipes,  Up: Top

Appendix F GNATS support
************************

The GNATS home page is located at `http://www.gnu.org/software/gnats'.
It contains all the important references to the available information
about GNATS and the related software.

   There is also a special page dedicated to the GNATS development at
`http://savannah.gnu.org/projects/gnats'.

   There are several GNATS mailing lists.  The most important ones are:

<info-gnats@gnu.org>
     Announcements and other important information about GNATS and the
     related software.  This is a very low volume moderated list.

<bug-gnats@gnu.org>
     The bug reporting mailing list on the GNATS itself.  Please note
     that the preferred way to report GNATS bugs is to submit them via
     the web interface at
     `http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=gnats'.  New bug
     reports submitted via the web interface are copied to the mailing
     list automatically.

<help-gnats@gnu.org>
     General discussion about GNATS.  Anything related to GNATS (user
     questions, development, suggestions, etc.) can be discussed there.

   The complete list of GNATS related mailing lists is available from
the web page at `http://savannah.gnu.org/project/gnats'.

   When you report problems concerning GNATS itself, please do not
forget to provide especially the following information:

   * The GNATS version you are using.

   * The _exact_ way how to reproduce the bug.

   * Your configuration.

   * If you encounter a compilation or build problem, it is especially
     important to mention the operating system, compiler and possibly
     other build utilities you use.

   Providing this information in the initial report avoids further
unnecessary communication, saves our limited development resources and
helps to track down and fix the problem soon.


File: gnats.info,  Node: Index,  Prev: Support,  Up: Top

Index
*****

�[index�]
* Menu:

* -with-gnats-dblist-file:               Configure and make.  (line 112)
* -with-gnats-default-db:                Configure and make.  (line 117)
* -with-gnats-service:                   Configure and make.  (line  91)
* -with-gnats-user:                      Configure and make.  (line  95)
* -with-gnatsd-host-access-file:         Configure and make.  (line 106)
* -with-gnatsd-user-access-file:         Configure and make.  (line  99)
* -with-kerberos:                        Configure and make.  (line 123)
* -with-krb4:                            Configure and make.  (line 126)
* >Submitter-Id:                         PR template.         (line 108)
* _analyzed_ state:                      States.              (line  19)
* _change-request_ class:                Problem Report fields.
                                                              (line 108)
* _closed_ state:                        States.              (line  30)
* _critical_ severity problems:          Problem Report fields.
                                                              (line  63)
* _doc-bug_ class:                       Problem Report fields.
                                                              (line 105)
* _duplicate_ class:                     Problem Report fields.
                                                              (line 114)
* _feedback_ state:                      States.              (line  25)
* _high_ priority problems:              Problem Report fields.
                                                              (line  83)
* _low_ priority problems:               Problem Report fields.
                                                              (line  89)
* _medium_ priority problems:            Problem Report fields.
                                                              (line  86)
* _mistaken_ class:                      Problem Report fields.
                                                              (line 118)
* _non-critical_ severity problems:      Problem Report fields.
                                                              (line  74)
* _open_ state:                          States.              (line  15)
* _serious_ severity problems:           Problem Report fields.
                                                              (line  68)
* _support_ class:                       Problem Report fields.
                                                              (line 111)
* _suspended_ state:                     States.              (line  35)
* _sw-bug_ class:                        Problem Report fields.
                                                              (line 102)
* adding a problem category <1>:         mkcat.               (line   6)
* adding a problem category:             Management.          (line  40)
* adding and removing maintainers:       Management.          (line  60)
* adding another database:               Management.          (line  34)
* addresses file <1>:                    addresses file.      (line   6)
* addresses file:                        GNATS configuration. (line  71)
* admin files:                           Admin files.         (line   6)
* administering GNATS:                   Management.          (line   6)
* administrative utilities:              Admin utils.         (line   6)
* age of PR:                             pr-age.              (line   6)
* alias for incoming Problem Reports:    Aliases.             (line  21)
* aliases:                               Aliases.             (line   6)
* appended-email-response:               Outgoing email formats.
                                                              (line  57)
* arrival-date:                          Individual field configuration.
                                                              (line  38)
* Arrival-Date field:                    Problem Report fields.
                                                              (line 203)
* at:                                    Setting up the default database.
                                                              (line  53)
* at-pr:                                 at-pr.               (line   6)
* audit-mail:                            Outgoing email formats.
                                                              (line  61)
* audit-trail:                           Individual field configuration.
                                                              (line  41)
* Audit-Trail field:                     Problem Report fields.
                                                              (line 212)
* Audit-trail format:                    Audit-trail formats. (line   6)
* autoload commands:                     Installing utils.    (line  28)
* automatic notification <1>:            at-pr.               (line   6)
* automatic notification:                States.              (line   8)
* BACK UP YOUR DATA:                     Management.          (line  77)
* bad Problem Reports:                   PR template.         (line 113)
* bug alias:                             Aliases.             (line  21)
* bug reporting:                         Support.             (line  34)
* building a new index:                  Management.          (line  65)
* building GNATS:                        Installation.        (line   6)
* building in a different directory:     Configure and make.  (line 136)
* builtin-name:                          Individual field configuration.
                                                              (line  29)
* bury-buffer:                           Emacs querying.      (line  45)
* business-day-hours:                    Overall database configuration.
                                                              (line  46)
* business-week-days:                    Overall database configuration.
                                                              (line  53)
* categories file <1>:                   rmcat.               (line   6)
* categories file <2>:                   mkcat.               (line   6)
* categories file <3>:                   categories file.     (line   6)
* categories file:                       GNATS configuration. (line  48)
* category:                              Individual field configuration.
                                                              (line  44)
* Category field:                        Problem Report fields.
                                                              (line  92)
* category-dir-perms:                    Overall database configuration.
                                                              (line  67)
* check-db:                              check-db.            (line   6)
* Class field:                           Problem Report fields.
                                                              (line  98)
* classes file <1>:                      classes file.        (line   6)
* classes file:                          GNATS configuration. (line  82)
* closed-date:                           Individual field configuration.
                                                              (line  47)
* command line options:                  send-pr from the shell.
                                                              (line   6)
* comment section in the PR template:    PR template.         (line  25)
* compiling the software:                Configure and make.  (line   6)
* confidential:                          Individual field configuration.
                                                              (line  50)
* Confidential field:                    Problem Report fields.
                                                              (line  42)
* confidentiality in PRs:                Problem Report fields.
                                                              (line  42)
* configure:                             Configure and make.  (line   6)
* configuring  GNATS:                    Installation.        (line   6)
* configuring and compiling the software: Configure and make. (line   6)
* configuring GNATS for remote users:    Installing tools.    (line  59)
* configuring GNATS on a local network:  Installing tools.    (line  30)
* configuring GNATS on a network:        Installing tools.    (line   6)
* create-category-dirs:                  Overall database configuration.
                                                              (line  61)
* creating an account for the GNATS user: Configure and make. (line  31)
* cron:                                  Setting up the default database.
                                                              (line  53)
* crontab:                               Setting up periodic jobs.
                                                              (line  14)
* current file:                          current file.        (line   6)
* daemon:                                Installing the daemon.
                                                              (line   6)
* database paradigm:                     Paradigm.            (line   6)
* database rationale:                    Introduction.        (line   6)
* database similarities:                 Fields.              (line   6)
* databases:                             GNATS configuration. (line  20)
* databases file:                        databases file.      (line   6)
* datatype:                              Field datatypes.     (line  10)
* date:                                  Field datatypes.     (line 134)
* Date-Required:                         Problem Report fields.
                                                              (line 207)
* Date-Required field:                   Problem Report fields.
                                                              (line 207)
* dbconfig:                              dbconfig recipes.    (line   6)
* dbconfig file <1>:                     dbconfig file.       (line   6)
* dbconfig file:                         GNATS configuration. (line  44)
* dbconfig mode:                         dbconfig mode.       (line   6)
* dbconfig recipes:                      dbconfig recipes.    (line   6)
* debug-mode:                            Overall database configuration.
                                                              (line  17)
* default installation locations <1>:    defaults.            (line   6)
* default installation locations:        Locations.           (line   6)
* defaults:                              GNATS configuration. (line  26)
* deleted-pr-mail:                       Outgoing email formats.
                                                              (line  65)
* description:                           Individual field configuration.
                                                              (line  53)
* Description field:                     Problem Report fields.
                                                              (line 134)
* diff-prs:                              diff-prs.            (line   6)
* Direct e-mail:                         Submitting via e-mail.
                                                              (line   6)
* disabling SUBMITTER-ID:                submitters file.     (line  68)
* driver for edit-pr:                    pr-edit.             (line   6)
* duties for gnats-admin:                Management.          (line   6)
* edit controls:                         Edit controls.       (line   6)
* edit-pr <1>:                           Emacs editing.       (line   6)
* edit-pr:                               edit-pr.             (line   6)
* edit-pr driver:                        pr-edit.             (line   6)
* edit-pr from the shell:                edit-pr from the shell.
                                                              (line   6)
* effective problem reporting:           Helpful hints.       (line   6)
* Emacs:                                 Emacs.               (line   6)
* Emacs functions:                       Installing utils.    (line  28)
* Emacs lisp file installation:          Configure and make.  (line  20)
* emptying the pending directory:        Management.          (line  12)
* enum:                                  Field datatypes.     (line  31)
* enumerated-in-file:                    Field datatypes.     (line  73)
* Environment field:                     Problem Report fields.
                                                              (line 129)
* environment variables and GNATS tools: Environment.         (line   6)
* errors:                                PR template.         (line 113)
* example Problem Report:                Fields.              (line  34)
* example queries:                       Example queries.     (line   6)
* EXEC-PREFIX <1>:                       exec-prefix.         (line   6)
* EXEC-PREFIX:                           Configure and make.  (line  86)
* Field datatypes:                       Field datatypes.     (line   6)
* field format:                          Problem Report fields.
                                                              (line   6)
* fields:                                Fields.              (line   6)
* fields - list:                         Problem Report fields.
                                                              (line  18)
* file-pr:                               file-pr.             (line   6)
* files used for GNATS administration:   Admin files.         (line   6)
* final state ("closed"):                States.              (line  30)
* Fix field:                             Problem Report fields.
                                                              (line 149)
* flowchart of GNATS activities:         Flowchart.           (line   6)
* follow-up via email <1>:               follow-up via email. (line   6)
* follow-up via email:                   Problem Report fields.
                                                              (line 234)
* foreword:                              Top.                 (line   6)
* format:                                Fields.              (line   6)
* format parameters:                     Audit-trail formats. (line  31)
* format-name:                           Outgoing email formats.
                                                              (line  42)
* From header:                           Mail header fields.  (line  23)
* gen-index <1>:                         gen-index.           (line   6)
* gen-index:                             Management.          (line  65)
* GNATS administrator:                   Paradigm.            (line  48)
* GNATS configuration:                   GNATS configuration. (line   6)
* GNATS database fields:                 Problem Report fields.
                                                              (line   6)
* GNATS fields - list:                   Problem Report fields.
                                                              (line  18)
* GNATS management:                      Management.          (line   6)
* GNATS support:                         Support.             (line   6)
* GNATS-ADM:                             gnats-adm.           (line   6)
* gnats-admin alias:                     Aliases.             (line  15)
* gnats-apply-or-submit:                 Emacs editing buffer.
                                                              (line  47)
* gnats-change-database <1>:             Emacs and databases. (line   6)
* gnats-change-database:                 Emacs querying.      (line  41)
* gnats-dbconfig-mode:                   dbconfig mode.       (line   6)
* gnats-dbconfig-mode-hook:              dbconfig mode.       (line  11)
* GNATS-DEFAULT-ORGANIZATION:            Emacs submitting.    (line  19)
* GNATS-DEFAULT-SUBMITTER:               Emacs submitting.    (line  23)
* gnats-edit-mode-hook:                  Emacs editing buffer.
                                                              (line  53)
* gnats-next-field:                      Emacs editing buffer.
                                                              (line  23)
* gnats-previous-field:                  Emacs editing buffer.
                                                              (line  23)
* gnats-pwconv:                          gnats-pwconv.        (line   6)
* gnats-query-edit-pr:                   Emacs querying.      (line  26)
* gnats-query-mode-hook:                 Emacs querying.      (line  57)
* gnats-query-reread:                    Emacs querying.      (line  30)
* GNATS-QUERY-REVERSE-LISTING:           Emacs querying.      (line  50)
* gnats-query-view-pr:                   Emacs querying.      (line  20)
* gnats-show-connection:                 Other Emacs commands.
                                                              (line  16)
* gnats-view-edit-pr:                    Emacs viewing.       (line   9)
* gnats-view-mode-hook:                  Emacs viewing.       (line  13)
* gnatsd:                                gnatsd.              (line   6)
* gnatsd command protocol:               gnatsd command protocol.
                                                              (line   6)
* gnatsd commands:                       gnatsd commands.     (line   6)
* gnatsd description:                    Description of gnatsd.
                                                              (line   6)
* gnatsd environment variables:          gnatsd environment variables.
                                                              (line   6)
* gnatsd options:                        gnatsd options.      (line   6)
* gnatsd startup options:                gnatsd options.      (line  12)
* gnatsd, Emacs:                         Emacs and databases. (line  11)
* gnatsd.host_access <1>:                gnatsd.host_access.  (line   6)
* gnatsd.host_access:                    GNATS configuration. (line  31)
* gnatsd.user_access <1>:                gnatsd.user_access.  (line   6)
* gnatsd.user_access:                    GNATS configuration. (line  36)
* gnatsd.user_access file:               GNATS configuration. (line  88)
* GNATSDB <1>:                           gnatsd environment variables.
                                                              (line   6)
* GNATSDB:                               Environment.         (line   6)
* handling incoming traffic:             queue-pr.            (line   6)
* helpful hints:                         Helpful hints.       (line   6)
* How-To-Repeat field:                   Problem Report fields.
                                                              (line 137)
* incoming alias for Problem Reports:    Aliases.             (line  21)
* incoming PRs that GNATS cannot parse:  Paradigm.            (line  62)
* index file <1>:                        gen-index.           (line   6)
* index file:                            index file.          (line   6)
* Index file description:                Index file description.
                                                              (line   6)
* Individual field configuration:        Individual field configuration.
                                                              (line   6)
* information to submit:                 Helpful hints.       (line   6)
* Initial PR input fields:               Initial PR input fields.
                                                              (line   6)
* initial state ("open"):                States.              (line  15)
* initial-pr-notification:               Outgoing email formats.
                                                              (line  49)
* initial-pr-notification-pending:       Outgoing email formats.
                                                              (line  53)
* initial-response-to-submitter:         Outgoing email formats.
                                                              (line  43)
* initializing a database:               mkdb.                (line   6)
* installing GNATS:                      Installation.        (line   6)
* installing the utilities:              Installing utils.    (line   6)
* integer:                               Field datatypes.     (line 141)
* interactive interface:                 send-pr in Emacs.    (line   6)
* internal utilities:                    Internal utils.      (line   6)
* Internet standard RFC-822:             Mail header fields.  (line   6)
* introduction to GNATS:                 Introduction.        (line   6)
* invalid Problem Reports:               PR template.         (line 113)
* invoking edit-pr:                      edit-pr.             (line   6)
* invoking query-pr:                     query-pr.            (line   6)
* invoking send-pr:                      send-pr.             (line   6)
* invoking send-pr from Emacs:           send-pr in Emacs.    (line   6)
* invoking send-pr from the shell:       send-pr from the shell.
                                                              (line   6)
* invoking the GNATS user tools:         GNATS user tools.    (line   6)
* keep-all-received-headers:             Overall database configuration.
                                                              (line  23)
* kinds of helpful information:          Helpful hints.       (line   6)
* last-modified:                         Individual field configuration.
                                                              (line  56)
* libexecdir:                            Overall database configuration.
                                                              (line  40)
* life-cycle of a Problem Report:        States.              (line   8)
* lisp file installation:                Configure and make.  (line  20)
* loading .el files:                     Installing utils.    (line  28)
* locations:                             Locations.           (line   6)
* locks:                                 pr-edit.             (line  29)
* mail aliases:                          Aliases.             (line   6)
* mail header fields:                    Mail header fields.  (line   6)
* mail header section:                   PR template.         (line  48)
* mailing lists:                         Support.             (line  13)
* maintenance:                           Paradigm.            (line   6)
* make:                                  Configure and make.  (line   6)
* managing GNATS:                        Management.          (line   6)
* mkcat <1>:                             mkcat.               (line   6)
* mkcat:                                 Management.          (line  40)
* mkdb <1>:                              mkdb.                (line   6)
* mkdb:                                  Management.          (line  34)
* multi-enumerated-in-file:              Field datatypes.     (line 116)
* multienum:                             Field datatypes.     (line  52)
* multitext:                             Field datatypes.     (line  24)
* Named query definitions:               Named query definitions.
                                                              (line   6)
* networks:                              Installing tools.    (line   6)
* new database:                          mkdb.                (line   6)
* new problem categories:                mkcat.               (line   6)
* notification of overdue PRs:           at-pr.               (line   6)
* notify-about-expired-prs:              Overall database configuration.
                                                              (line  28)
* Notify-List field:                     Problem Report fields.
                                                              (line  29)
* number:                                Individual field configuration.
                                                              (line  59)
* Number field:                          Problem Report fields.
                                                              (line 157)
* OBJDIR:                                Configure and make.  (line 136)
* Organization field:                    Problem Report fields.
                                                              (line  39)
* originator:                            Individual field configuration.
                                                              (line  62)
* Originator field:                      Problem Report fields.
                                                              (line  35)
* Outgoing email formats:                Outgoing email formats.
                                                              (line   6)
* Overall database configuration:        Overall database configuration.
                                                              (line   6)
* Overview of GNATS configuration:       GNATS configuration. (line   6)
* overview to GNATS:                     Top.                 (line   6)
* paradigm:                              Paradigm.            (line   6)
* password, Emacs:                       Emacs and databases. (line  16)
* pending directory:                     Paradigm.            (line  62)
* pending file:                          categories file.     (line  77)
* PR confidentiality:                    Problem Report fields.
                                                              (line  42)
* PR locks:                              pr-edit.             (line  29)
* pr-age:                                pr-age.              (line   6)
* pr-edit:                               pr-edit.             (line   6)
* PREFIX <1>:                            prefix.              (line   6)
* PREFIX:                                Configure and make.  (line  80)
* prepare send-pr.conf:                  Installing utils.    (line  49)
* priority:                              Individual field configuration.
                                                              (line  65)
* Priority field:                        Problem Report fields.
                                                              (line  79)
* Problem Report format:                 Fields.              (line   6)
* Problem Report states:                 States.              (line   8)
* Problem Report template:               Fields.              (line  34)
* processing incoming traffic:           file-pr.             (line   6)
* pruning log files:                     Management.          (line  70)
* query expressions:                     Query expressions.   (line   6)
* query-pr <1>:                          Emacs querying.      (line   6)
* query-pr:                              query-pr.            (line   6)
* query-pr by mail:                      Invoking query-pr.   (line  10)
* query-pr output format:                Formatting query-pr output.
                                                              (line   6)
* querying individual problem reports:   query-pr.            (line   6)
* querying using regexps:                Regexps.             (line   6)
* queue-pr:                              queue-pr.            (line   6)
* queue-pr -q:                           Aliases.             (line  21)
* rationale:                             Introduction.        (line   6)
* Received-By headers:                   Mail header fields.  (line  32)
* regular expressions:                   Regexps.             (line   6)
* related mail <1>:                      follow-up via email. (line   6)
* related mail:                          Problem Report fields.
                                                              (line 234)
* Release field:                         Problem Report fields.
                                                              (line 125)
* reminder message:                      at-pr.               (line  24)
* removing a problem category <1>:       rmcat.               (line   6)
* removing a problem category:           Management.          (line  48)
* Reply-To header:                       Mail header fields.  (line  28)
* Report all the facts!:                 Helpful hints.       (line   6)
* reporting problems with send-pr:       send-pr.             (line   6)
* responsible:                           Individual field configuration.
                                                              (line  68)
* Responsible field:                     Problem Report fields.
                                                              (line 198)
* responsible file <1>:                  responsible file.    (line   6)
* responsible file:                      GNATS configuration. (line  57)
* Responsible-Changed-<From>-<To> in Audit-Trail: Problem Report fields.
                                                              (line 219)
* Responsible-Changed-By in Audit-Trail: Problem Report fields.
                                                              (line 222)
* Responsible-Changed-When in Audit-Trail: Problem Report fields.
                                                              (line 226)
* Responsible-Changed-Why in Audit-Trail: Problem Report fields.
                                                              (line 230)
* rmcat <1>:                             rmcat.               (line   6)
* rmcat:                                 Management.          (line  48)
* sample Problem Report:                 Fields.              (line  34)
* send-pr <1>:                           Emacs submitting.    (line   6)
* send-pr <2>:                           Emacs querying.      (line  38)
* send-pr:                               send-pr.             (line   6)
* send-pr fields <1>:                    PR template.         (line  86)
* send-pr fields:                        send-pr from the shell.
                                                              (line  50)
* send-pr within Emacs:                  send-pr in Emacs.    (line   6)
* send-pr.conf file:                     send-pr.conf file.   (line   6)
* send-submitter-ack:                    Overall database configuration.
                                                              (line  33)
* setting up GNATS:                      Installation.        (line   6)
* severity:                              Individual field configuration.
                                                              (line  71)
* Severity field:                        Problem Report fields.
                                                              (line  59)
* shell invocation:                      send-pr from the shell.
                                                              (line   6)
* Site wide configuration files:         GNATS configuration. (line  19)
* so what does it do:                    Paradigm.            (line   6)
* state:                                 Individual field configuration.
                                                              (line  74)
* State field:                           Problem Report fields.
                                                              (line 172)
* state--"analyzed":                     States.              (line  19)
* state--"closed":                       States.              (line  30)
* state--"feedback":                     States.              (line  25)
* state--"open":                         States.              (line  15)
* state--"suspended":                    States.              (line  35)
* State-Changed-<From>-<To> in Audit-Trail: Problem Report fields.
                                                              (line 216)
* State-Changed-By in Audit-Trail:       Problem Report fields.
                                                              (line 222)
* State-Changed-When in Audit-Trail:     Problem Report fields.
                                                              (line 226)
* State-Changed-Why in Audit-Trail:      Problem Report fields.
                                                              (line 230)
* states file <1>:                       states file.         (line   6)
* states file:                           GNATS configuration. (line  78)
* states of Problem Reports:             States.              (line   8)
* Subject header:                        Mail header fields.  (line  19)
* submitter-id:                          Individual field configuration.
                                                              (line  77)
* Submitter-Id field <1>:                PR template.         (line 108)
* Submitter-Id field:                    Problem Report fields.
                                                              (line  18)
* submitters file <1>:                   submitters file.     (line   6)
* submitters file:                       GNATS configuration. (line  66)
* Submitting a PR via e-mail:            Submitting via e-mail.
                                                              (line   6)
* subsequent mail <1>:                   follow-up via email. (line   6)
* subsequent mail:                       Problem Report fields.
                                                              (line 234)
* support site:                          Paradigm.            (line   6)
* synopsis:                              Individual field configuration.
                                                              (line  80)
* Synopsis field:                        Problem Report fields.
                                                              (line  55)
* syntax of regexps:                     Regexps.             (line   6)
* template:                              PR template.         (line  11)
* template comment section:              PR template.         (line  25)
* text:                                  Field datatypes.     (line  14)
* the section on query-by-mail needs to be relocated: Invoking query-pr.
                                                              (line  17)
* timely reminders:                      at-pr.               (line   6)
* To header:                             Mail header fields.  (line  14)
* unformatted:                           Individual field configuration.
                                                              (line  83)
* Unformatted field:                     Problem Report fields.
                                                              (line 240)
* unlock-database:                       Other Emacs commands.
                                                              (line  12)
* unlock-pr:                             Other Emacs commands.
                                                              (line   6)
* unpacking the distribution:            Configure and make.  (line   6)
* unparseable incoming PRs:              Paradigm.            (line  62)
* upgrade, procedure:                    Upgrading.           (line  53)
* upgrading from older versions:         Upgrading.           (line   6)
* upgrading, overview:                   Upgrading.           (line  15)
* usage for the GNATS user tools:        GNATS user tools.    (line   6)
* Using and Porting GNU CC:              Helpful hints.       (line   6)
* using edit-pr:                         edit-pr.             (line   6)
* using GNATS over a local network:      Installing tools.    (line  30)
* using GNATS over a network <1>:        Installing tools.    (line   6)
* using GNATS over a network:            Installing the daemon.
                                                              (line   6)
* using GNATS remotely:                  Installing tools.    (line  59)
* using query-pr:                        query-pr.            (line   6)
* using send-pr:                         send-pr.             (line   6)
* using send-pr from within Emacs:       send-pr in Emacs.    (line   6)
* view-pr:                               Emacs viewing.       (line   6)
* visual map of data flow:               Flowchart.           (line   6)
* what is a PR:                          Paradigm.            (line  25)
* where GNATS lives:                     Locations.           (line   6)
* why GNATS:                             Paradigm.            (line   6)



Tag Table:
Node: Top824
Node: Introduction2803
Node: Paradigm3904
Node: Flowchart8894
Node: States11061
Node: Fields12633
Node: Field datatypes reference15305
Node: Mail header fields16300
Node: Problem Report fields17795
Node: GNATS user tools27193
Node: Environment28316
Node: send-pr29167
Node: send-pr from the shell29912
Node: send-pr in Emacs32172
Ref: send-pr in Emacs-Footnote-132850
Node: PR template32966
Node: Submitting via e-mail38301
Node: Helpful hints39386
Node: edit-pr42488
Node: edit-pr from the shell44853
Node: follow-up via email46894
Node: query-pr48842
Node: Invoking query-pr50321
Node: Formatting query-pr output59526
Node: Query expressions62056
Node: Example queries66361
Node: Emacs67416
Node: Emacs viewing68874
Node: Emacs querying69415
Node: Emacs submitting71356
Node: Emacs editing72398
Node: Emacs editing buffer73035
Node: Emacs and databases75614
Node: dbconfig mode76625
Node: Other Emacs commands77107
Node: Emacs customization78034
Node: Installation78295
Node: Configure and make81248
Node: Installing utils87733
Node: Setting up the default database89729
Ref: Setting up the default database-Footnote-192063
Node: Setting up periodic jobs92199
Node: Aliases93345
Node: Installing the daemon95754
Node: Installing tools98798
Node: Upgrading104350
Node: Management112628
Node: GNATS configuration116672
Node: databases file120943
Node: dbconfig file123039
Node: Overall database configuration125274
Node: Individual field configuration128545
Node: Field datatypes132785
Ref: administrative files135772
Node: Edit controls138854
Node: Named query definitions141331
Node: Audit-trail formats142437
Node: Outgoing email formats144143
Node: Index file description150683
Node: Initial PR input fields152046
Node: Other config files152786
Node: categories file153104
Node: responsible file156394
Node: submitters file157781
Node: states file160786
Node: addresses file163710
Node: classes file165615
Node: send-pr.conf file166557
Node: Admin files168953
Node: index file169396
Node: current file170820
Node: Admin utils171084
Node: mkdb171665
Node: mkcat172278
Node: rmcat172937
Node: gen-index173744
Node: check-db175362
Node: gnats-pwconv176693
Node: Internal utils177830
Node: queue-pr178398
Node: file-pr180373
Node: at-pr183438
Node: pr-edit185053
Ref: pr-edit-Footnote-1191954
Node: diff-prs192048
Node: pr-age192452
Node: Locations193079
Node: prefix193520
Node: exec-prefix194258
Node: gnats-adm196745
Node: defaults197531
Node: gnatsd201912
Node: Description of gnatsd202389
Node: gnatsd options203699
Node: gnatsd command protocol205397
Node: gnatsd commands209683
Node: gnatsd environment variables232509
Node: Access Control233204
Node: Overview233575
Node: Overall gnatsd access level234468
Node: gnatsd.host_access235371
Node: gnatsd.user_access237173
Ref: gnatsd.user_access-Footnote-1241609
Ref: gnatsd.user_access-Footnote-2241696
Ref: gnatsd.user_access-Footnote-3241850
Node: Privileged gnatsd commands242045
Node: Regexps243189
Node: dbconfig recipes248306
Ref: release-based support252418
Node: Support253561
Node: Index255470

End Tag Table