@node Management
@chapter @sc{gnats} Administration
@cindex administering @sc{gnats}
@cindex managing @sc{gnats}
@cindex GNATS management
@cindex duties for @code{gnats-admin}

In daily usage, @sc{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 @sc{gnats} configuration at some point:

@table @emph
@item emptying the @code{pending} directory
@cindex emptying the @code{pending} directory
If a Problem Report arrives with a @code{Category} value that is
unrecognized by the @file{categories} file, or if that field is missing,
@sc{gnats} places the PR in the @w{@file{pending}} directory
(@pxref{Locations,,Where @sc{gnats} lives}).  PRs
submitted in free-form by email will always be filed in the
@w{@file{pending}} directory.  If so configured, @sc{gnats} sends a
notice to the @code{gnats-admin} and to the party responsible for that
submitter (as listed in the @file{submitters} file) when this occurs.

To have these "categoryless" PRs filed correctly, you can then use a
@sc{gnats} tool such as @code{edit-pr} to set the correct category of
each PR in the @file{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 @sc{gnats} database
copied to a log file (@ref{Aliases,,Setting up mail aliases}).  Then,
should you run out of disk space, and an empty file ends up in the
database's @file{pending} directory, you need only look in the log file,
which should still contain the full message that was submitted.

@item adding another database
@cindex adding another database
@cindex @code{mkdb}
@sc{gnats} supports multiple databases.  If you find at some point that
you need to add another database to your server, the @code{mkdb} tool
does most of the work for you.  @xref{mkdb,,Adding
another database}.

@item adding new categories
@cindex adding a problem category
@cindex @code{mkcat}
Most installations of @sc{gnats} will only require you to add a new line
to the @w{@file{categories}} file.  The category directory will then be
created automatically as needed.  However, if automatic directory
creation has been switched off in the @file{dbconfig} file
(@pxref{dbconfig file,,The @code{dbconfig} file}), you need to use the
@file{mkcat} program.

@item removing categories
@cindex removing a problem category
@cindex @code{rmcat}
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
@file{categories} file, and invoke 

@smallexample
rmcat @var{category@dots{}}
@end smallexample

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

@item adding and removing maintainers
@cindex adding and removing maintainers
Edit the @file{responsible} file to add a new maintainer or to remove an
existing maintainer.  @xref{responsible file,,The @code{responsible} file}.

@item building a new index
@cindex building a new index
@cindex @code{gen-index}
If your index becomes corrupted, or if you wish to generate a new one
for some reason, use the program @code{gen-index}
(@pxref{gen-index,,Regenerating the index}).

@item pruning log files
@cindex 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.  (@xref{Aliases,,Setting up mail
aliases}.)
@c "gather ye rosebugs while ye may..."

@item BACKING UP YOUR DATA
@cindex BACK 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.

@end table

@xref{Locations,,Where @sc{gnats} lives}.

@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
@end menu

@node GNATS configuration
@section Overview of @sc{gnats} configuration
@cindex @sc{gnats} configuration
@cindex Overview of @sc{gnats} configuration

@xref{Locations,,Where @sc{gnats} lives}.

@sc{gnats} has two, well, actually three, different kinds of
configuration file.  The @dfn{site-wide} configuration files determine
overall behaviour across all the databases on your machine, while the
@dfn{database-specific} configuration files determine how @sc{gnats}
behaves when dealing with a specific database.  In addition, there is
a single file that needs to be set up for the @code{send-pr} tool to
work properly.  These files can be edited at any time --- the next
time a @sc{gnats} tool is invoked, the new parameters will take
effect.

These are the site-wide configuration files used by @sc{gnats}:

@cindex Site wide configuration files
@table @code
@item databases
@cindex @file{databases}
Specifies database names and their associated parameters, such as in
which directory they are located.  This file is used by the @sc{gnats}
clients to determine the location of a database referred to by name.
@xref{databases file,,The @code{databases} file}.

@item defaults
@cindex @file{defaults}
This directory contains the set of default per-database configuration
files used when a new database is created with @code{mkdb}.

@item gnatsd.host_access
@cindex @file{gnatsd.host_access}
Controls access levels for the different machines that will do lookups
in the databases on this machine.  @xref{Access Control,,@sc{gnats}
access control}.

@item gnatsd.user_access
@cindex @file{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).  @xref{Access Control,,@sc{gnats} access
control}.
@end table

@noindent The database-specific configuration is determined by the
following files in the @file{gnats-adm} subdirectory of the database
directory.

@table @code
@cindex @code{dbconfig} file
@item dbconfig
Controls most aspects of how @sc{gnats} behaves when dealing with your
database.  @xref{dbconfig file,,The @code{dbconfig} file}.

@cindex @code{categories} file
@item categories
The list of categories that @sc{gnats} accepts as valid for the
@code{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.  @xref{categories file,,The @code{categories} file}.

@cindex @code{responsible} file
@item 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 @sc{gnats}.
@xref{responsible file,,The @code{responsible} file}.

@cindex @code{submitters} file
@item submitters
Lists sites from whom @sc{gnats} accepts Problem Reports.  The existence
of this file is mandatory, although the feature it provides is not; see
@ref{submitters file,,The @code{submitters} file}.

@cindex @code{addresses} file
@item addresses
Mappings between submitter IDs and submitters' e-mail addresses.  Use of
this file is optional.  If you get Problem reports where the
@code{Submitter} field is not filled in, @sc{gnats} will use entries in
this file to try to derive the submitter ID from the e-mail headers.
@xref{addresses file,,The @code{addresses} file}.

@cindex @code{states} file
@item states
Lists the possible states for Problem Reports, typically ranging from
@dfn{open} to @dfn{closed}.  @xref{addresses file,,The @code{states}
file}.

@cindex @code{classes} file
@item classes
Lists the possible classes of Problem Report.  This provides an easy way
to have ``subcategories'', for example by setting up classes such as
@code{sw-bug}, @code{doc-bug}, @code{change-request} etc.
@xref{classes file,,The @code{classes} file}.

@cindex @code{gnatsd.user_access} file
@item gnatsd.user_access
Specify the access levels for different users to your database.
@xref{Access Control,,@sc{gnats} access control}.

@end table

The last file in this menagerie is the @code{send-pr} configuration
file @file{send-pr.conf}.  This file contains some defaults that need
to be known in order for @code{send-pr} to work.  The file needs to
be present on all hosts where @code{send-pr} is to be used.
@xref{send-pr.conf file,,the @file{send-pr.conf} file}.

@node databases file
@section The @code{databases} file
@cindex @code{databases} file

The @file{databases} configuration file is a site-wide configuration
file containing the list of @sc{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:

@var{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 @code{query-pr} or
@code{send-pr}, either by using the @code{--database} option of the
program or by setting the @var{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:

@var{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 @samp{:} symbols, indicating an
empty field), the fourth field is the hostname of the remote @sc{gnats}
server, and the fifth field is the port number that the remote
@sc{gnats} is running on.

If @sc{gnats} was built with default options, the @file{databases} file
will be located in the @w{@file{/usr/local/etc/gnats}} directory.
However, if the option @code{--with-gnats-dblist-file} was used during building
of @sc{gnats}, the @file{databases} file has the name and location given
to this option.  A sample @file{databases} file is installed together
with @sc{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 @code{mkdb} tool, @xref{mkdb}.


@node dbconfig file
@section The @code{dbconfig} file
@cindex @code{dbconfig} file

The @file{dbconfig} configuration file controls the configuration of a
@sc{gnats} database.  Each database has its own individual copy of this
file, which is located in the @file{gnats-adm} subdirectory of the
database.

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

The @file{dbconfig} file contains 6 major sections, which must appear in the
following order:

@itemize @bullet
@item Overall database configuration
@item Individual field configuration
@item Named query definitions
@item Audit-trail and outgoing email formats
@item Index file description
@item Initial Problem Report input fields
@end itemize

The different sections are described below.  While reading the following
sections, it will be useful to refer to the sample @file{dbconfig} file
which is installed when a new database is initialized with the
@code{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
@sc{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.
@end menu

@node Overall database configuration
@subsection Overall database configuration
@cindex Overall database configuration

The overall database options are controlled by settings in the
@code{database-info} section of the @file{dbconfig} file.  The following
is the general format of this section:

@example
database-info @{
  [options]
@}
@end example

The following options and values may be used in the @code{database-info}
section:

@table @code
@cindex @code{debug-mode}
@item debug-mode@ @ @var{true | false}
If set to @code{true}, the database is placed into debug mode.  This causes all
outgoing email to be sent to the @dfn{gnats-admin} user listed in the
@file{responsible} file of the database.  The default value is @code{false}.

@cindex @code{keep-all-received-headers}
@item keep-all-received-headers@ @ @var{true | false}
If set to @code{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 @code{false}.

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

@cindex @code{send-submitter-ack}
@item send-submitter-ack@ @ @var{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 @code{true}.
This is in addition to the normal notification mail to the person(s)
responsible for the new PR.  The default value is @code{false}.

@cindex @code{libexecdir}
@item libexecdir@ @ @var{"directory"}
Specifies the directory where the @sc{gnats} administrative executables
are located.  In particular, @code{at-pr} and @code{mail-pr} are invoked
from this directory.  The default value is the empty string, which is
unlikely to be useful.

@cindex @code{business-day-hours}
@item business-day-hours@ @ @var{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.  @sc{gnats} uses these values to determine whether the required
completion time for a PR has passed.  The default values are 8 for
@code{day-start} and 17 for @code{day-end}.

@cindex @code{business-week-days}
@item business-week-days@ @ @var{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.  @sc{gnats} uses these values to
determine whether the required completion time for a PR has passed.  The
default values are 1 for @code{week-start} and 5 for @code{week-end}.

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

@cindex @code{category-dir-perms}
@item category-dir-perms@ @ @var{mode}
Standard octal mode-specification specifying the permissions to be set
on auto-created category directories. Default is @code{0750}, yielding
user read, write and execute, and group read and execute.  Note that
if you have local users on the @sc{gnats} server itself, running for
instance @code{query-pr}, you may need to change the permissions to
@code{0755}.
@end table

@node Individual field configuration
@subsection Individual field configuration
@cindex Individual field configuration

Each type of field in a PR must be described with a @code{field} section
in the @file{dbconfig} file.  These sections have the following general
structure:

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

@code{fieldname} is used as the field header in the PR.  The characters @code{>}
and @code{:} are used internally as field markers by @sc{gnats}, so they must
not be used in fieldnames.

The order in which the @code{field} sections appear in the
@file{dbconfig} file determines the order in which they appear in the PR
text.  There is no required order, unlike previous versions of @sc{gnats}
--- the Unformatted field and multitext fields may appear anywhere in
the PR.

The following @code{field-options} may be present within a @code{field} section:

@table @code
@cindex @code{builtin-name}
@item builtin-name@ @ @var{"name"}
Indicates that this field corresponds to one of the @sc{gnats} built-in
fields.

@sc{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:

@table @code
@item arrival-date
@cindex @code{arrival-date}
The arrival date of the PR

@item audit-trail
@cindex @code{audit-trail}
The audit-trail recording changes to the PR

@item category
@cindex @code{category}
The category that the PR falls into

@item closed-date
@cindex @code{closed-date}
The date that the PR was closed

@item confidential
@cindex @code{confidential}
If set to @code{yes}, the PR is confidential

@item description
@cindex @code{description}
A description of the problem

@item last-modified
@cindex @code{last-modified}
The date the PR was last modified

@item number
@cindex @code{number}
The PR's unique numeric identifier

@item originator
@cindex @code{originator}
The originator of the PR

@item priority
@cindex @code{priority}
Priority of the PR

@item responsible
@cindex @code{responsible}
The person responsible for handling the PR

@item severity
@cindex @code{severity}
Severity of the problem described by the PR

@item state
@cindex @code{state}
The current state of the PR

@item submitter-id
@cindex @code{submitter-id}
The user that submitted the PR

@item synopsis
@cindex @code{synopsis}
The one-line description of the PR

@item unformatted
@cindex @code{unformatted}
PR text which cannot be parsed and associated with other fields.
@end table

For these built-in fields, a matching field description @emph{must}
appear in the @file{dbconfig} file. Otherwise, the configuration will
be considered invalid, and errors will be generated from the
@sc{gnats} clients and @code{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.

@item description@ @ @var{"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
@code{--field-description} option in @code{query-pr}.

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

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

If the option is not given, the default search is @code{exact-regexp}.

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

By default, fields are not marked as @code{textsearch} fields.

@item 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.
@end table

@node Field datatypes
@subsection Field datatypes
@cindex 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

@table @code
@cindex @code{datatype}
@item datatype@ @ [ options ... ]
@end table

The available datatypes are:

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

If the @code{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
@code{matching} qualifier is present, no restriction is placed on
what values may appear in the field.

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

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

@cindex @code{enum}
@item enum@ @ @{
@itemx @ @ values @{
@itemx @ @ @ @ "string" [ "string" ... ]
@itemx @ @ @}
@itemx @ @ [ default "string" ]
@itemx @}
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 @code{values} option. The @code{values} option is
required for an enumerated field.

If a @code{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 @code{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 @code{default} option is specified, the default value for the
field is the first value in the @code{values} section.

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

The values in the @code{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 @code{ingredients} where the default values
should be @samp{sugar}, @samp{flour} and @samp{baking powder} and the
separator is a colon @samp{:}, the following sets these defaults:

@smallexample
default "sugar:flour:baking powder"
@end smallexample

@cindex @code{enumerated-in-file}
@item enumerated-in-file@ @{
@itemx @ @ path "filename"
@itemx @ @ fields @{
@itemx @ @ @ @ "name" [ "name" ... ]
@itemx @ @ @} key "name"
@itemx @ @ [ allow-any-value ]
@itemx @}
@anchor{administrative files}The @code{enumerated-in-file} type is used
to describe an enumerated field with an associated @dfn{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 @code{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 @file{categories} administrative file.

@code{filename} is the name of a file in the @file{gnats-adm}
administrative directory for the database.

The format of the administrative file should be simple ASCII.
@dfn{Subfields} within the file are separated with colons (@samp{:}).
Lines beginning with a hash sign (@samp{#}) are ignored as comments.
Records within the file are separated with newlines.

The @code{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 @code{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 @code{field}
option.

If the @code{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 @code{default} keyword for
@code{enumerated-in-file}.  These fields get their default value from
the @emph{first} entry in the associated administrative file.

@cindex @code{multi-enumerated-in-file}
@item multi-enumerated-in-file@ @{
@itemx @ @ path "filename"
@itemx @ @ fields @{
@itemx @ @ @ @ "name" [ "name" ... ]
@itemx @ @ @} key "name"
@itemx @ @ [ default "string" ]
@itemx @ @ [ allow-any-value ]
@itemx @ @ [ separators "string" ]
@itemx @}

@code{multi-enumerated-in-file} is to @code{multienum} what
@code{enumerated-in-file} is to @code{enum}.  Its options have the
same meaning as their counterparts in the @code{multienum} and
@code{enumerated-in-file} fields.

@emph{NOTE}: Keywords may appear in any sequence, with one exception --
the @code{separators} keyword, if present, has to come last.  This rule
only applies to fields of type @code{multi-enumerated-in-file}.

@cindex @code{date}
@item date
The @code{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.

@cindex @code{integer}
@item 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 @code{default} option is present, the field will have the value
of @code{integer} if the field is not given a value when the PR is
initially created.  Otherwise, the field will be left empty.
@end table

@node Edit controls
@subsection Edit controls
@cindex edit controls

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

@example
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" ... @} ]
@}
@end example

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

The @code{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 @code{audit-trail-format}
section within the field, or by the global @code{audit-trail-format}
section. See @ref{Audit-trail formats} and @ref{Outgoing email formats}.

The @code{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 @code{set-field} and @code{append-to-field} options are used to
change the value of the field @code{fieldname} in the PR.  The supplied
format is used to format the value that will be placed in the field.

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

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

The @code{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
@ref{Initial PR input fields}, as well as in the set of fields
required on change of the field itself.

There is also a global @code{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.

@node Named query definitions
@subsection Named query definitions
@cindex Named query definitions

When queries are performed via @code{query-pr}, they can refer to a
query format described by a @code{query} section in the @file{dbconfig}
file:

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

@code{formatstring} is as described in @ref{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 @code{fields} option lists the fields to be used with the format
string.  If the @code{fields} option is present without a @code{format}
option, the contents of the listed fields are printed out, separated by
newlines.

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

@node Audit-trail formats
@subsection Audit-trail formats
@cindex Audit-trail format

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
@code{audit-trail-format} option:

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

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
@code{audit-trail-format} is used in preference to this one, if it
exists.

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

The following format parameters are defined for
@code{audit-trail-format} entries:

@table @code
@cindex format parameters
@item $Fieldname
The name of the field for which an audit-trail entry is being created.

@item $OldValue
The old value of the field.

@item $NewValue
The new field value.

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

@item $CurrentDate
The current date.

@item $ChangeReason
The reason for the change; may be blank if no reason was supplied.
@end table

These parameters may be used anywhere a @code{fieldname} can appear.

@node Outgoing email formats
@subsection Outgoing email formats
@cindex Outgoing email formats

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

The formats of the email messages are controlled by @code{mail-format}
sections in the @file{dbconfig} file.  The general structure of a
@code{mail-format} section is as follows:
@c XXX The use of | and []'s below needs to be cleaned up

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

@code{gnats} recognizes and uses 6 different @code{format-name} values:

@table @code
@cindex @code{format-name}
@item initial-response-to-submitter
@cindex @code{initial-response-to-submitter}
Format of the message used when mailing an initial response back to the
PR submitter.  This message will only be sent if
@code{send-submitter-ack} in the overall database configuration is set
to @code{true}.

@item initial-pr-notification
@cindex @code{initial-pr-notification}
Format of the message sent to the responsible parties when a new PR with
category different from ``pending'' arrives.

@item initial-pr-notification-pending
@cindex @code{initial-pr-notification-pending}
Format of the message sent to the responsible parties when a new PR that
ends up with category ``pending'' arrives.

@item appended-email-response
@cindex @code{appended-email-response}
Format of the notification message sent out when a response to a PR is
received via email.

@item audit-mail
@cindex @code{audit-mail}
Format of the message sent out when a PR edit generates an Audit-Trail
entry.

@item deleted-pr-mail
@cindex @code{deleted-pr-mail}
Format of the message sent out when a PR is deleted.
@end table

The @code{from-address}, @code{to-address} and @code{reply-to}
subsections of a mail-format section specify the contents of the @code{To:},
@code{From:} and @code{Reply-To:} headers in outgoing email.  There are
two ways to specify the contents: by using a @code{fixed-address}
specification, or by specifying @code{email-header-name}s or
@code{gnats-field-name}s.

When an @code{email-header-name} or @code{gnats-field-name} value is
given, @sc{gnats} will attempt to extract an email address from the
specified location.  If several values are given on the same line,
separated by @samp{|} characters, @sc{gnats} will try to extract an address
from each location in turn until it finds a header or field which is
nonempty.  The following example should clarify this:

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

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

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

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

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

@table @code
@item appended-email-response
@table @code
@item $MailFrom
The From: line of the original message.

@item $MailTo
The To: line of the original message.

@item $MailSubject
The Subject: line of the original message.

@item $MailCC
The CC: line of the original message.

@item $NewAuditTrail
The text of the new audit trail entry (corresponds to the body of the
message).
@end table

@item audit-mail
@table @code
@item $EditUserEmailAddr
The email address of the user editing the PR.  Set by the
@code{EDITADDR} @code{gnatsd} command or from the @file{responsible}
file; if not available, user's local address is used.

@item $OldResponsible
The previous Responsible field entry, if it was changed.

@item $NewAuditTrail
The Audit-Trail: entries that have been appended by the edits.
@end table

@item deleted-pr-mail
@table @code
@item $EditUserEmailAddr
The email address of the user deleting the PR.  Set by the
@code{EDITADDR} @code{gnatsd} command or from the @file{responsible}
file; if not available, user's local address is used.

@item $PRNum
The number of the PR that was deleted.
@end table
@end table

The following example illustrates the use of these special variables:

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

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

@node Index file description
@subsection Index file description
@cindex Index file description

The @code{index} section of the @file{dbconfig} file lists the fields
that appear in the database index.  The index is always keyed by PR
number.  The general format for the @code{index} section is

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

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

The @code{fields} parameter controls what fields will appear, and in
what order, in the index.  Fields are listed by their names, separated by
spaces (@samp{ }).  Fields will appear in the order they are listed.

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

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

@node Initial PR input fields
@subsection Initial PR input fields
@cindex Initial PR input fields

An @code{initial-entry} section in the @file{dbconfig} file is used to
describe which fields should be present on initial PR entry; this is
used by tools such as send-pr to determine which fields to include in a
``blank'' PR template. An optional @code{require} parameter can be
defined to specify a subset of the @code{intial-entry} fields which must
be assigned a value upon initial creation of the PR.

The general format for the @code{initial-entry} section is

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

@node Other config files
@section Other database-specific config files

@menu
* categories file::
* responsible file::
* submitters file::
* states file::
* addresses file::
* classes file::
@end menu

@node categories file
@subsection The @code{categories} file
@cindex @code{categories} file

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

To create a new category, log in as @sc{gnats}, add a line to this file,
and run @code{mkcat} if applicable.  Lines beginning with @samp{#} are
ignored.

A line in the @file{categories} file consists of four fields delimited
by colons, as follows:

@smallexample
@var{category}:@var{description}:@var{responsible}:@var{notify}
@end smallexample

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

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

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

@item description
A terse textual description of the category.

@item responsible
The name tag of the party responsible for this category of problems, as
listed in the @file{responsible} file (@pxref{responsible file,,The
@code{responsible} file}).

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

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

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

In the above example, the nametags @samp{myboss}, @samp{me},
@samp{fred}, and @samp{barney} must be defined in the @file{responsible}
file (@pxref{responsible file,,The @code{responsible} file}).

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

If you want to separate PRs in each problem category into specific
subsets, say @emph{documentation} and @emph{software bugs},
using the @file{classes} file is recommended.  @xref{classes file,,The
@file{classes} file}.

Only one category @emph{must} be present for @sc{gnats} to function:

@smallexample
pending:Non-categorized PRs:gnats-admin:
@end smallexample

@cindex @code{pending} file
The @file{pending} directory is created automatically when you run
@code{mkdb} to initialize a new database.  (@pxref{Configure and
make,,Configuring and compiling the software}).

@node responsible file
@subsection The @code{responsible} file
@cindex @code{responsible} file

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

@smallexample
@var{responsible}:@var{full-name}:@var{mail-address}
@end smallexample

@noindent
@table @var
@item responsible
A name-tag description of the party in question, such as her or his user
name, or the name of the group.  This name is listed in the PR in
the @code{Responsible} field.

@item full-name
The full name of the party (``Charlotte Bronte''; ``Compiler Group'').

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

@noindent
A sample @file{responsible} listing might be:

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

@noindent Here, @code{ren} is a local user.  @code{stimpy} is remote, so his full
address must be specified.

@noindent The following entry @emph{must} be present for @sc{gnats} to function:

@smallexample
gnats-admin:GNATS administrator:
@end smallexample

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

@node submitters file
@subsection The @code{submitters} file
@cindex @code{submitters} file

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

Entries are of the format:

@smallexample
@var{submitter-id}:@var{name}:@var{type}:@var{resp-time}:@var{contact}:@var{notify}
@end smallexample

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

@item name
The full name or a description of this entity.

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

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

@item contact
The name tag of the main @dfn{contact} at the Support Site for this
submitter.  This contact should be in the @file{responsible} file
(@pxref{responsible file,,The @code{responsible} file}).  Incoming bugs
from @var{submitter} are sent to this contact.  Optionally, this field
can be left blank.

@item notify
Any other parties who should receive copies of Problem Reports sent in
by @var{submitter}.  They need not be listed in the @file{responsible} file.
@end table

A few example entries in the @file{submitters} file:

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

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

@cindex disabling @var{submitter-id}
To disable the feature of @sc{gnats} which tracks the
@code{Submitter-Id}, simply alter the @file{submitters} file to only
contain one @var{submitter-id} value, and instruct your submitters to
ignore the field.

@node states file
@subsection The @code{states} file
@cindex @code{states} file

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

@smallexample
@var{state}:@var{type}:@var{description}
@end smallexample

@noindent
@table @var
@item state
The name of the state.  It may contain alphanumerics as well as
@samp{-} (hyphen), @samp{_} (underscore), or @samp{.} (period), but no
other characters.

@item type
This is the type of the state.  This field is optional and it may
contain alphanumerics as well as @samp{-} (hyphen), @samp{_}
(underscore), or @samp{.} (period), but no other characters.

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

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

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

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

The first state listed will be the state automatically assigned to
Problem Reports when they arrive; by default this is named ``open''.
The last state listed is the end state for Problem Reports --- one
should usually assume that a PR in this state is not being actively
worked on; by default this state is named ``closed''.  Even if a
different name has been chosen for this state, @sc{gnats} will force
this state to be of type ``closed''.

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

@node addresses file
@subsection The @code{addresses} file
@cindex @code{addresses} file

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

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

@smallexample
@var{submitter-id}:@var{address-fragment}
@end smallexample

@noindent
@table @var
@item @var{submitter-id}
A valid submitter ID

@item @var{address-fragment}
Part of, or all of the e-mail address to be matched
@end table

Here is an example of an @code{addresses} file:

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

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

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

@sc{gnats} can match addresses in three e-mail formats:

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

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

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

If @sc{gnats} sees other e-mail address formats, it uses the default
submitter ID.

@node classes file
@subsection The @code{classes} file
@cindex @code{classes} file
This file lists the possible classes of Problem Reports.  Each line
consists of a class name, followed by a colon and an optional class type
name (the class type name is not used for anything in the current
implementation of @sc{gnats}, so it may be left blank.  The @code{class}
and @code{class-type-name} fields may only contain alphanumerics,
@samp{-}, @samp{_}, and @samp{.}, but no other
characters.

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

@smallexample
class::class description
@end smallexample

Lines beginning with @samp{#} will be ignored, and the first listed
class is the default class for an incoming Problem Report.

@node send-pr.conf file
@section The @file{send-pr.conf} file
@cindex @code{send-pr.conf} file
This file contains some default values that need to be known in order
for @code{send-pr} to work properly.  This file needs to be copied to
all hosts where @code{send-pr} will be used.

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

Entries in this file are on the format

@smallexample
variable=@var{value}
@end smallexample

The valid variables are:

@table @code
@item SUBMITTER
The default value to be used for the Submitter-Id field when
@code{send-pr} is invoked.

@item DEFAULT_RELEASE
The default value to be used for the Release field (only applicable if
the Release field is defined in the @file{dbconfig} file.

@item DEFAULT_ORGANIZATION
The default value to be used for the Organization field.  (only
applicable if the Organization field is defined in the @file{dbconfig}
file.

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

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

@item TEMPLATE
When invoked, @code{send-pr} communicates directly over the network
with the @sc{gnats} server to determine what fields to include in a
correctly formatted Problem Report so that it can present the user
with a template.  If the @sc{gnats} server can't be reached directly
over the network, a template must be provided.  Set the
@code{TEMPLATE} variable to point to a template file created on the
@sc{gnats} server by using the command @command{send-pr -p}.
@xref{Installing tools,,Installing the user tools}.
@end table

@node Admin files
@section Administrative data files
@cindex admin files
@cindex files used for @sc{gnats} administration

The following files are database-specific and are located in the
@file{gnats-adm} subdirectory of the database directory.  These files
are maintained by @sc{gnats}; you should never need to touch them.

@menu
* index file::      The `index' file
* current file::    The `current' file
@end menu

@node index file
@subsection The @code{index} file
@cindex @code{index} file

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

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

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

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

The format of the index for a database is set in the @file{dbconfig}
file. @xref{Index file description,,Index file description}.

Should the @file{index} file become corrupted, the @code{gen-index}
utility can be used to regenerate it. @xref{gen-index,,Regenerating the
index}.

@node current file
@subsection The @code{current} file
@cindex @code{current} file

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

@node Admin utils
@section Administrative utilities
@cindex administrative utilities

These tools are used by the @sc{gnats} administrator as part of the
periodic maintenance and configuration of @sc{gnats}.
@xref{Management,,@sc{gnats} Administration}.

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

@node mkdb
@subsection Adding another database
@cindex @code{mkdb}
@cindex initializing a database
@cindex new database

To initialize a new @sc{gnats} database:

@enumerate 1
@item
Add a line for the new database in the @file{databases} file
(@pxref{Locations,,Where @sc{gnats} lives}.

@item
Run @code{mkdb}, using

@smallexample
mkdb @var{database}
@end smallexample

where @var{database} is the database you specified in the
@file{databases} file.  @code{mkdb} creates the database directory and
populates it with the directories @file{pending}, @file{gnats-queue}
and @file{gnats-adm}.  A full set of sample configuration files is
copied to the @file{gnats-adm} directory.
@end enumerate

@node mkcat
@subsection Adding a problem category
@cindex @code{mkcat}
@cindex adding a problem category
@cindex new problem categories
@cindex @code{categories} file

To add new categories to the database:

@enumerate 1
@item 
Add a line to for each new category to the @file{categories} file in the
gnats-adm directory of the database. @xref{categories file,,The
@code{categories} file}.

@item
Run @code{mkcat} If applicable.  If @code{create-category-dirs} is set
to @code{false} in the database @file{dbconfig} file, you need to create
category directories with @code{mkcat}.  @code{mkcat} creates a
subdirectory under the database directory for any new categories which
appear in the @file{categories} file.
@end enumerate

@node rmcat
@subsection Removing a problem category
@cindex @code{rmcat}
@cindex removing a problem category
@cindex @code{categories} file

To remove a category from the database:

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

@item
Run @code{rmcat} using

@smallexample
rmcat @var{category} [ @var{category@dots{}} ]
@end smallexample

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

@c FIXME!  Should we suggest this?
@ignore
To reassign a group of categories....

(The idea is to call "query-pr --full", run the output through sed, and
then throw it at pr-edit.  This approach is untested, and may be unhealthy.)

@end ignore

@node gen-index
@subsection Regenerating the index
@cindex @code{gen-index}
@cindex @code{index} file

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

@smallexample
gen-index [ -n | --numeric ]
          [ -d @var{databasename} | --database=@var{databasename} ]
          [ -o @var{filename} | --outfile=@var{filename} ]
          [ -i | --import ] [ -e | --export ]
          [ -h | --help] [ -V | --version ]
@end smallexample

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

@table @code
@item -n
@itemx --numeric
Sorts index entries numerically.

@item -d @var{databasename}
@itemx --database=@var{databasename}
Specifies the database to index.  If this option is left out,
@code{gen-index} attempts to index the database with name taken from the
the @var{GNATSDB} environment variable, and if that is undefined, the
default database, as set when @sc{gnats} was built (usually
@code{default}).

@item -o @var{filename}
@itemx --outfile=@var{filename}
Places output in @var{filename} rather than sending it to standard
output.

@item -i
@itemx --import
Import the existing index file instead of re-indexing the database.

@item -e
@itemx --export
Force plaintext output.

@item -h
@itemx --help
Prints the usage for @code{gen-index}.

@item -V
@itemx --version
Prints the version number for @code{gen-index}.
@end table

@node check-db
@subsection Checking database health
@cindex @code{check-db}

The @file{check-db} script is useful for performing periodic checks on
database health.  It accepts the following options:

@table @code
@item -d @var{databasename}
@itemx --database=@var{databasename}
Determines the database which to operate on.

@item --all-databases
Check all @sc{gnats} databases on the system.  This option takes
precedence over the @code{--database} option.
@end table

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

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

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

After checking for old lock files, it calls @code{gen-index}
(@pxref{gen-index,,Regenerating the index}) and compares the
results with the current @file{index} file of the database; any
inconsistencies are reported to the administrators in a mail message.
 
After checking the index file for inconsistencies, the script unlocks
the database and exits.

@node gnats-pwconv
@subsection Managing user passwords
@cindex @code{gnats-pwconv}

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

The @code{gnats-pwconv} tool takes care of converting the old password
files to the new format:

@smallexample
gnats-pwconv [ -c | --crypt ] [ -m | --md5 ] [ -p | --plaintext ]
         [ -h | --help] [ -V | --version ] @var{INFILE} [@var{OUTFILE}]
@end smallexample

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

@node Internal utils
@section Internal utilities
@cindex internal utilities

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

@menu
* queue-pr::    Handling incoming traffic
* file-pr::     Processing incoming traffic
* at-pr::       Timely reminders
* pr-edit::     The edit-pr driver
* diff-prs::    The @code{diff-prs} tool
* pr-age::      The @code{pr-age} tool
@end menu

@node queue-pr
@subsection Handling incoming traffic
@cindex @code{queue-pr}
@cindex handling incoming traffic

The program @code{queue-pr} handles traffic coming into @sc{gnats}.
@code{queue-pr} queues incoming Problem Reports in the
@file{gnats-queue} directory of the database, and then periodically (via
@code{cron}) passes them on to @code{file-pr} to be filed in the
@sc{gnats} database.  @xref{Installation,,Installing @sc{gnats}}.

The usage for @code{queue-pr} is as follows:

@smallexample
queue-pr [ -q | --queue ] [ -r | --run ]
         [ -f @var{filename} | --file=@var{filename} ]
         [ -m @var{kbytes} | --max-size=@var{kbytes} ]
         [ -d @var{databasename} | --database=@var{databasename} ]
         [ -h | --help] [ -V | --version ]
@end smallexample

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

@table @code
@item -q
@itemx --queue
Accepts standard input as an incoming mail message, placing this
message in an incrementally numbered file in the
@w{@file{gnats-queue}} directory under the database directory
(@pxref{Locations,,Where @sc{gnats} lives}).

@item -r
@itemx --run
Redirects files in the @file{gnats-queue} directory into the program
@code{file-pr} one by one.

@item -f @var{filename}
@itemx --file=@var{filename}
Used with @samp{-q} (or @samp{--queue}), accepts the file denoted by
@var{filename} as input rather than reading from standard input.

@item -m @var{kbytes}
@itemx --max-size=@var{kbytes}
Do not process messages larger then @var{kbytes} kilobytes.  Files
larger than the limit are left for human intervention.

@item -d @var{databasename}
@itemx --directory=@var{databasename}
Specifies database to operate on.  If this option is left out, the value
of the @var{GNATSDB} environment variable is used, and if that is
undefined, the default database name set when @sc{gnats} was built is
used (usually @code{default}).

@item -h
@itemx --help
Prints the usage for @code{gen-index}.

@item -V
@itemx --version
Prints the version number for @code{gen-index}.
@end table

@node file-pr
@subsection Processing incoming traffic
@cindex @code{file-pr}
@cindex processing incoming traffic

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

If the @code{Category} field does not contain a valid category value
(i.e., matching a line in the @code{categories} file; @pxref{categories
file,,The @code{categories} file}), the PR is assigned to the default
category, as set in the @code{dbconfig} file.  If there is no default
category defined, the PR is given a @code{Category} value of
@samp{pending} and is placed in the @file{pending} directory.  The
@sc{gnats} administrator is notified of the unplaceable PR.

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

The usage for @code{file-pr} is as follows:

@smallexample
file-pr [ -f @var{filename} | --file=@var{filename} ]
        [ -d @var{databasename} | --database=@var{databasename} ]
	    [ -h | --help ] [ -V | --version ]
 
       network options:
        [ -H @var{host} | --host=@var{host} ]
        [ -P @var{port} | --port=@var{port} ]
        [ -v @var{username} | --user=@var{username} ]
        [ -w @var{password} | --passwd=@var{password} ]
@end smallexample

@code{file-pr} requires no options in order to operate, and takes input
from standard input (normally, the output of @w{@samp{queue-pr -r}})
unless otherwise specified.  The options include:

@table @code
@item -f @var{filename}
@itemx --filename=@var{filename}
Uses @var{filename} as input rather than standard input.

@item -d @var{databasename}
@itemx --database=@var{databasename}
Performs refiling operations on @var{database}.  If this option is left
out, the value of the @var{GNATSDB} environment variable is used, and if
that is undefined, the default database name set when @sc{gnats} was
built is used (usually @code{default}).

@item -h
@itemx --help
Prints the usage for @code{file-pr}.

@item -V
@itemx --version
Prints the version number for @code{file-pr}.
@end table

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

@table @code
@item -H @var{host}
@itemx --host=@var{host}
Hostname of the @sc{gnats} server.

@item -P @var{port}
@itemx --port=@var{port}
The port that the @sc{gnats} server runs on.

@item -v @var{username}
@itemx --username=@var{username}
Username used to log into the @sc{gnats} server.

@item -w @var{password}
@itemx --passwd=@var{password}
Password used to log into the @sc{gnats} server.
@end table

@node at-pr
@subsection Timely reminders
@cindex @code{at-pr}
@cindex timely reminders
@cindex automatic notification
@cindex notification of overdue PRs

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

The @file{submitters} file contains the response time for each
@w{@code{>Submitter-Id:}} (@pxref{submitters file,,The @code{submitters}
file}).  The time is determined in @dfn{business hours}, which are
defined in the database's @file{dbconfig} file (@pxref{Overall database
configuration,,Overall database configuration}).

If the PR is urgent and is still open after the requisite time period
has passed, @code{at-pr} sends a reminder to the @sc{gnats}
administrator, to the maintainer responsible for that submitter, and
to the maintainer responsible for the PR with the following message:

@cindex reminder message
@cindex @code{at-pr}
@smallexample
To: @var{submitter-contact} @var{responsible} @var{gnats-admin}
Subject: PR @var{gnats-id} not analyzed in @var{#hours} hours

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

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

--
The GNU Problem Report Management System (GNATS)
@end smallexample

The PR is @dfn{urgent} if its priority is @samp{critical} or if its
priority is @samp{serious} and the severity is @samp{high}.


@node pr-edit
@subsection The @code{edit-pr} driver
@cindex @code{pr-edit}
@cindex @code{edit-pr} driver
@cindex driver for @code{edit-pr}

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

The usage for @code{pr-edit} is:

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

@cindex PR locks
@cindex locks
A @dfn{lock} is placed on a Problem Report while the PR is being edited.
The lock is simply a file in the @file{locks} subdirectory of the
@file{gnats-adm} directory of the database, with the name
@w{@file{@var{gnats-id}.lock}}, which contains the name of the
user who created the lock.  @var{user} then ``owns'' the
lock, and must remove it before the PR can be locked again, even by the
same @var{user}@footnote{This approach may seem heavy-handed, but
it ensures that changes are not overwritten.}.  If a PR is already
locked when you attempt to edit it, @code{pr-edit} prints an error
message giving the name of the user who is currently editing the
PR.

If you do not specify @w{@var{PR number}}, @code{pr-edit} reads from
standard input.  You must specify @w{@var{PR number}} for the functions
which affect PR locks, @samp{--lock=@var{username}} and
@samp{--unlock}.

@table @code
@item -L
@itemx --lockdb
Locks the database specified with the @code{--database} or @code{-d}
option.  No PRs may be edited, created or deleted while the database is
locked.  This option is generally used when editing the index file.

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

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

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

@noindent The following options require a PR number to be given.

@table @code
@item --delete-pr
Deletes the specified PR from the database.  The PR must be in a closed
state, and not locked.  Only the user @emph{gnats} (or the user name
specified instead of @emph{gnats} during the building of @sc{gnats}) is
permitted to delete PRs.

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

@item -u
@itemx --unlock
Unlocks the specified PR.

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

@item -R @var{reason}
@itemx --reason=@var{reason}
Certain PR fields are configured in the database configuration to
require a short text describing the reason of every change that
happens to them, @xref{dbconfig file}.  If you edit a problem and
change any of such fields, you must issue a short text, the
@var{reason} of the change, through this option.  If the option is
used and no change-reason requiring field is actually changed, the
option has no effect.

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

@item -d @var{database}
@itemx --database=@var{database}
Specifies the database which is to be manipulated.  If no database is
specified, the default database name set when @sc{gnats} was built is
used (usually @code{default}).  This option overrides the database
specified in the GNATSDB environment variable.

@item -f @var{filename}
@itemx --filename=@var{filename}
For actions that require reading in a PR or field content, this
specifies the name of a file to read.  If @code{--filename} is not
specified, the PR or field content is read in from stdin.

@item -h
@itemx --help
Prints the usage for @code{pr-edit}.

@item -V
@itemx --version
Prints the version number for @code{pr-edit}.
@end table

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

@table @code
@item -H @var{host}
@itemx --host=@var{host}
Hostname of the @sc{gnats} server.

@item -P @var{port}
@itemx --port=@var{port}
The port that the @sc{gnats} server runs on.

@item -v @var{username}
@itemx --username=@var{username}
Username used to log into the @sc{gnats} server.

@item -w @var{password}
@itemx --passwd=@var{password}
Password used to log into the @sc{gnats} server.

@item -D
@itemx --debug
Used to debug network connections.
@end table

@node diff-prs
@subsection The @code{diff-prs} tool
@cindex @code{diff-prs}

The @code{diff-prs} tool is invoked as follows:

@example
diff-prs @var{prfile1} @var{prfile2}
@end example

@code{diff-prs} simply reads the PRs contained in @var{prfile1} and
@var{prfile2} and returns a list of the fields that are different
between the two.  No output is produced if the PRs are identical.

@node pr-age
@subsection The @code{pr-age} tool
@cindex @code{pr-age}
@cindex age of PR

The @code{pr-age} tool reports the time, in days and hours, since the PR
arrived.  Usage is

@smallexample
pr-age  [ -d @var{databasename} | --database=@var{databasename} ]
        [ -H @var{host} | --host=@var{host} ]
        [ -P @var{port} | --port=@var{port} ]
        [ -v @var{username} | --user=@var{username} ]
        [ -w @var{password} | --passwd=@var{password} ]
        [ -h | --help ] [ -V | --version ]
@end smallexample

For an explanation of the arguments listed above, please refer to the
usage description for @code{file-pr} (@ref{file-pr,,@code{file-pr}}).
