     [file version.texi not included]

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

Copyright © 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.

Overview
********

This manual documents GNATS, the GNU Problem Report Management System, version VERSION.  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 (PRs) 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 The database paradigm.

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

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.

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 (see GNATS data 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. See GNATS administration.

Each PR is a separate file within a main repository (see Where GNATS lives).  Editing access to the database is regulated to maintain consistency.  To make queries on the database faster, an index is kept automatically (see The 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 GNATS Administration, 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.  See Overview of 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 (see GNATS Administration).

Once a problem is recorded in the database, work can begin toward a solution.  A problem's initial state type is open (see States of Problem Reports).  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.  (see Editing existing Problem Reports.  For information on the Audit-Trail field, see Problem Report format.)

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 States of Problem Reports.)

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 The dbconfig file and see States of Problem Reports.)

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.

          [file flowchart.txt not included]

     [file states.texi not included]

     [file fields.texi not included]

     [file p-usage.texi not included]

Installing GNATS
****************

     [file p-inst.texi not included]

     [file p-admin.texi not included]

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 (see Installing GNATS).

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

See Configuring and compiling the software.

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 Using configure (Cygnus configure), before attempting this.

The gnats-adm directory
=======================

Each GNATS database located on a server has its own directory, as listed in the databases (see The databases file and given when the mkdb utility is invoked to initialize the database (see Initializing a new database). 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.

Default installation locations
==============================

PREFIX
     defaults to /usr/local; change using configure (see Configuring and compiling the software).

EXEC-PREFIX
     defaults to PREFIX; change using configure (see Configuring and compiling the software).

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

EXEC-PREFIX/bin

     send-pr
          See Submitting Problem Reports.

     edit-pr
          See Editing existing Problem Reports.

     query-pr
          See Querying the database.

EXEC-PREFIX/libexec/gnats

     at-pr
          See Timely reminders.

     check-db
          See Checking database health.

     delete-pr
          Tool for deleting PRs.  Deprecated.  Use the --delete-pr option of pr-edit instead (see The edit-pr driver).

     diff-prs
          See The diff-prs tool.

     file-pr
          See Interface to pr-edit for filing new PRs.

     gen-index
          See Regenerating the index.

     gnatsd
          The GNATS daemon.

     gnats-pwconv
          See Converting old password files.

     mail-query
          See Setting up mail aliases.

     mkcat
          See Adding a problem category.

     mkdb
          See Script for creating new databases.

     pr-age
          See The pr-age tool.

     pr-edit
          See The main PR processor.

     queue-pr
          See Handling incoming traffic.

     rmcat
          See Removing categories.

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

PREFIX/etc/gnats

     databases
          See The databases file.

     defaults
          See Overview of GNATS configuration.

     gnatsd.host_access
          See The gnatsd.host_access file.

     gnatsd.user_access
          See The gnatsd.user_access file.

PREFIX/share/emacs/site-lisp

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

PREFIX/info

     gnats.info
     send-pr.info
          The GNATS manuals, in a form readable by info (the GNU hypertext browser).  See Reading GNU Online Documentation (GNU Online Documentation).

PREFIX/man/man1
PREFIX/man/man8

     man pages for all the GNATS tools and utilities.
          See The 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. See Other database-specific config files, Administrative data files and Controlling access to databases.

     gnats-queue
          Incoming Problem Reports are queued here until the next iteration of queue-pr -r (see Handling incoming traffic).

     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. See GNATS administration.

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

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.

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 Controlling access to databases.  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, see Configuring and compiling the software for details.)

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 Controlling access to databases for details on access levels.

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

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 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 (see 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 (see Controlling access to databases).  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.  See Controlling access to databases.

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, (see 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 (see Named query definitions), or an actual query format (see 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).

gnatsd environment variables
============================

gnatsd supports the GNATSDB environment varable, see 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.

Controlling access to databases
*******************************

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

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.

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

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() (DES crypt is the standard password encryption format used by most UNIX systems) or MD5 hash format (MD5 is only supported on platforms that have a crypt() function that supports MD5. Among others, this currently includes GNU Linux and OpenBSD.).

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$. (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.) 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.  See Converting old password files.

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 (see The 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.

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.  See The GNATS User Tools.

Querying using regular expressions
**********************************

See also 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.

See Regular Expression Syntax (Regex), for details on regular expression syntax.  Also see Syntax of Regular Expressions (GNU Emacs Manual), 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 (see 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 Regular Expression Syntax (Regex), for a much more complete discussion on regular expression syntax.

dbconfig recipes
****************

The dbconfig file (The 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 (see The gnatsd.user_access file.)

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] (see Enumerated field 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
}

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.