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

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

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

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

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

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


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

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.

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

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

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.

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.

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

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

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

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

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

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

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

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

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

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

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.

