In daily usage, GNATS is self-maintaining. However, there are various administrative duties which need to be performed periodically:
pending
directory 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 (Setting up mail 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.
dbconfig
file), you need to use the `mkcat' program.
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).
responsible
file.
gen-index
(see section Regenerating the
index).
See section Where GNATS lives.
3.1 Overview of GNATS configuration 3.2 The databases
fileThe databases file 3.3 The dbconfig
fileThe dbconfig file 3.4 Other database-specific config files Configuration files 3.5 Administrative data files 3.6 Administrative utilities 3.7 Internal utilities
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
See section Where GNATS lives.
GNATS has two 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. 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
databases
file.
gnatsd.host_access
The database-specific configuration is determined by the following files in the `gnats-adm' subdirectory of the database directory.
dbconfig
dbconfig
file.
categories
categories
file.
responsible
responsible
file.
submitters
submitters
file.
addresses
addresses
file.
states
states
file.
classes
sw-bug
, doc-bug
, change-request
etc. See section The classes
file.
gnatsd.access
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
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.
3.3.1 Overall database configuration 3.3.2 Individual field configuration 3.3.3 Field datatypes 3.3.4 Edit controls Trigger on certain edit actions 3.3.5 Named query definitions Define and name standard queries 3.3.6 Audit-trail formats Specify formatting of the audit-trail 3.3.7 Outgoing email formats Specify contents and formatting of messages sent out by GNATS. 3.3.8 Index file description Specify the general format and contents of the database index 3.3.9 Initial PR input fields Which fields should be present on initial PR entry.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
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
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
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
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"
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
day-start
and 17 for day-end
.
business-week-days week-start - week-end
week-start
and 5 for week-end
.
create-category-dirs true | false
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
0750
, yielding user read, write and execute, and group read and execute.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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"
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:
number
category
synopsis
confidential
yes
, the PR is confidential
severity
priority
responsible
state
submitter
arrival-date
last-modified
audit-trail
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.
description "description text"
--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
^
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
--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
By default, editing is allowed.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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" ... ] } ]
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" } ]
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" ]
}
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" ]
}
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 (`:').
enumerated-in-file {
path "filename"
fields {
"name" [ "name" ... ]
} key "name"
[ allow-any-value ]
}
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.
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. Fields 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 fields in the administrative file. There
must be at least one field, 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.
date
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" } ]
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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" ] { |
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.
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.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 XXX refer to query-pr XXX. It contains a string with
printf-like % escapes. The output of the query is then formatted as specified
by the 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
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
$OldValue
$NewValue
$EditUserEmailAddr
$CurrentDate
$ChangeReason
These parameters may be used anywhere a fieldname
can appear.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
During the life of a PR, GNATS can be configured to send out a range of
email messages. When a PR first arrives, an acknowledgment message is sent out
if the send-submitter-ack
parameter above is set to true
. Certain edits to the PR may also cause email to be sent out to the
various parties, and if a PR is deleted, GNATS may send notification email.
The formats of the email messages are controlled by mail-format
sections in the `dbconfig' file. The general structure of a mail-format
section is as follows:
mail-format "format-name" { from-address { [ fixed-address "address" ] [ email-header-name | [ mail-header-name | ... ] ] } to-address { [ fixed-address "address" ] [ "email-header-name" | [ "mail-header-name" | ... ] ] } reply-to { [ fixed-address "address" ] [ "email-header-name" | ... ] | [ "gnats-field-name" | ... ] } header { format "formatstring" [ fields { "fieldname" [ "fieldname" ... ] } ] } body { format "formatstring" [ fields { "fieldname" [ "fieldname" ... ] } ] } } |
gnats
recognizes and uses 6 different format-name
values:
initial-response-to-submitter
send-submitter-ack
in the overall database configuration is set to true
.
initial-pr-notification
initial-pr-notification-pending
appended-email-response
audit-mail
deleted-pr-mail
The from-address
, to-address
and reply-to
subsections of a mail-format section specify the contents of the To:
, From:
and Reply-To:
headers in outgoing email. There are two ways to specify the contents:
by using a fixed-address
specification, or by specifying email-header-name
s and gnats-field-name
s separated by the (`|') symbol.
When email-header-name
and/or gnats-field-name
values are given, GNATS will attempt to extract email addresses from
the specified locations, in turn until it finds a header or field which is
nonempty. The following example should clarify this:
mail-format "initial-response-to-submitter" { from-address { fixed-address "gnats-admin" } to-addresses { "Reply-To:" | "From:" | "Submitter-Id" }... |
This partial mail-format
section specifies the format of the address headers in the email
message that is sent out as an acknowledgment of a received PR. The From:
field of the message will contain the email address of the GNATS
administrator, as specified by the gnats-admin
line in the `responsible' file. To fill in the To:
header, GNATS will first look for the mail header Reply-To:
in the PR and use the contents of that, if any. If that header doesn't
exist or is empty, it will look for the contents of the From:
email header, and if that is without results, it will look for the
GNATS Submitter-Id
field and use the contents of that.
Other email headers to be included in messages sent out by GNATS can be
specified by header
subsections of the mail-header
section. formatstring
and fieldname
are similar to those used by the named query format. Each header line
must have a newline character (`\n') at the end.
The email message body is specified in the body
subsection of the mail-format
section. Just as for a header
section, the body
section must contain a formatstring
and fieldname
values.
For some of the formats that GNATS recognizes, special variables are available for use. The following table lists the formats that provide special variables. See the example below for an illustration of how they are used.
appended-email-response
$MailFrom
$MailTo
$MailSubject
$MailCC
$NewAuditTrail
audit-mail
$EditUserEmailAddr
$OldResponsible
$NewAuditTrail
deleted-pr-mail
$EditUserEmailAddr
$PRNum
The following example illustrates the use of these special variables:
mail-format "deleted-pr-mail" { from-address { "$EditUserEmailAddr" } to-addresses { fixed-address "gnats-admin" } header { format "Subject: Deleted PR %s\n" fields { "$PRNum" } } body { format "PR %s was deleted by user %s.\n" fields { "$PRNum" "$EditUserEmailAddr" } } } |
This mail-format
section specifies the format of the email message that is sent out when
a PR is deleted. The From:
field is set to the email address field of the user who deleted the PR,
the subject of the message contains the number of the deleted PR, and the
message body contains both the PR number and the user's email address.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The index
section of the `dbconfig' file lists the fields that appear in
the database index. The index is always keyed by PR number. The general format
for the index
section is
index { path "file" fields { "fieldname" [ "fieldname" ... ] } binary-index true | false [ separator "symbol" ] } |
The path
parameter gives the name of the index file in the `gnats-adm'
directory of the database. Only one index is allowed per database, so only one path
entry is allowed.
The fields
parameter controls what fields will appear, and in what order, in the
index. Fields are listed by their names, separated by spaces (`
'). Fields will appear in the order they are listed.
The binary-index
parameter controls whether the index is supposed to be in plaintext or
binary format. Binary format is recommended, as it avoids potential problems
when field separators appear as bona-fide field contents.
When plaintext format is used, by setting binary-index false
, the symbol (`|') is used as a field separator in the
index, unless the optional separator
parameter is used to redefine the separator character.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An initial-entry
section in the `dbconfig' file is used to describe which
fields should be present on initial PR entry; this is used by tools such as
send-pr to determine which fields to include in a "blank" PR template. The
general format for the initial-entry
section is
initial-entry { fields { "fieldname" [ "fieldname" ... ] } } |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.4.1 The categories
file3.4.2 The responsible
file3.4.3 The submitters
file3.4.4 The states
file3.4.5 The addresses
file3.4.6 The classes
file
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
categories
file The `categories' file contains a list of problem categories,
specific to the database, which GNATS tracks. This file also matches
responsible people with these categories. You must edit this file initially,
creating valid categories. In most installations, GNATS is configured to create
directories on disk for valid categories automatically as needed (see section
Overall database configuration). If
GNATS isn't set up to do this, you need to run mkcat
to create the corresponding subdirectories of the database directory.
For instructions on running mkcat
, see Adding a problem category.
To create a new category, log in as GNATS, add a line to this file, and
run mkcat
if applicable. Lines beginning with `#' are ignored.
A line in the `categories' file consists of four fields delimited by colons, as follows:
category:description:responsible:notify
|
! $ & * ( ) { } [ ] ` ' " ; : < > ~ |
Ideally, category names should not contain commas or begin with periods. Each line has a corresponding subdirectory in the database directory.
responsible
file).
A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for.
rock:ROCK program:me:myboss,fred stone:STONE utils:barney:fred iron:IRON firewall:me:firewall-log |
In the above example, the nametags `myboss',
`me', `fred', and `barney' must be
defined in the `responsible' file (see section
The responsible
file).
Problem Reports with a category of `rock' are sent to the
local mail address (or alias) `me', and also sent to the addresses
`myboss' and `fred'. PRs with a category of
`stone' are sent to the local addresses `barney' and
`fred' only, while PRs with the category `iron' are
sent only to `me', and are also filed in firewall-log
(in this case, a mail alias should be set up, see section
Setting up mail aliases.
If you want to separate PRs in each problem category into specific subsets, say documentation and software bugs, using the `classes' file is recommended. See section The `classes' file.
Only one category must be present for GNATS to function:
pending:Non-categorized PRs:gnats-admin: |
The `pending' directory is created
automatically when you run mkdb
to initialize a new database. (see section
Configuring and compiling the software).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
responsible
file This file contains a list of the responsible parties. Lines beginning with `#' are ignored. Each entry contains three fields, separated by colons:
responsible:full-name:mail-address |
A sample `responsible' listing might be:
ren:Ren Hoek: stimpy:Stimpson J. Cat:stimpy@lederhosen.org |
Here, ren
is a local user. stimpy
is remote, so his full address must be specified.
The following entry must be present for GNATS to function:
gnats-admin:GNATS administrator: |
gnats-admin
is usually defined as a mail alias when GNATS is installed, so for this
purpose gnats-admin
is a local address. However, this line can alos be used to redefine the
email address of the GNATS administrator, by adding the desired address at the
end of the line.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
submitters
file This is a database of sites which submit bugs to your support site. It contains six fields delineated by colons. Lines beginning with `#' will be ignored.
Entries are of the format:
submitter-id:name:type:resp-time:contact:notify |
submitter-id
listed in the file will be the default for PRs that arrive with invalid
or empty submitter fields.
notify-about-expired-prs
entry set to true (see section
Overall database configuration, GNATS
will use this field to schedule when GNATS should notify the gnats-admin,
responsible person and submitter contact that the PR wasn't analyzed within the
agreed response time. Business hours and business-week days are set in the
`dbconfig' file. For information on at-pr
, the program which sends out this reminder, see
Timely Reminders.
responsible
file). Incoming bugs from submitter are sent to this
contact. Optionally, this field can be left blank.
A few example entries in the `submitters' file:
univ-hell:University of Hades:eternal:3:beelzebub:lucifer tta:Telephones and Telegraphs of America:support:720:dave: |
In this example, when a PR comes in from the University of Hades (who
has an eternal contract), it should have `univ-hell' in its
`Submitter-Id' field. This Problem Report goes to beelzebub
(who should be in the `responsible' file), and if it is not
analyzed within three business hours a reminder message is sent. lucifer
also receives a copy of the bug, and a copy of the reminder message as
well (if it is sent). When Telephones and Telegraphs of America utilizes their
support contract and submits a bug, a copy is sent only to dave
, who has 720 business hours to return an analysis before a reminder is
sent.
To disable the feature of GNATS which tracks the `>Submitter-Id:', simply alter the `submitters' file to only contain one submitter-id value, and instruct your submitters to ignore the field.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
states
file This file lists the possible states for Problem Reports. Each line consists of a state, followed optionally by colon and a one-line description of what the state means. Lines beginning with `#' will be ignored.
state:optional descriptive text |
State names can contain any alphanumeric character, `-' (hyphen), `_' (underscore), or `.' (period), but no other characters. The state name ends with a newline, or else with a colon followed by optional descriptive text. The descriptive text, if present, can contain any character except newline, which marks the end of the description. Empty or all-whitespace descriptions are allowed. This is not recommended, however, since although GNATS doesn't use this field, external tools might.
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".
It is probably best to leave "open" as the first state and "closed" as the last, otherwise some external tools looking for those two states by name may be fooled.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
addresses
file This file contains mappings between submitter IDs and corresponding e-mail addresses.
When a PR comes in without a submitter ID (if someone sends unformatted e-mail to the PR submission email address), GNATS will try to derive the submitter ID from the address in the "From:" header. The entries in this file consist of two fields, separated by a colon:
submitter-id:address-fragment |
Here is an example of an addresses
file:
# Addresses for Yoyodine Inc yoyodine:yoyodine.com yoyodine:yoyodine.co.uk # Addresses for Foobar Inc. foobar1:sales.foobar.com foobar2:admin.foobar.com foobar3:clark@research.foobar.com |
GNATS checks each line in the addresses
file, comparing address-fragment to the end of the "From:"
header, until it finds a match. If no match is found, GNATS uses the default
submitter ID.
You can only have one address fragment per line, but you can have more than one line for a given submitter ID. An address fragment can be a domain (i.e. yoyodine.com), a machine location (admin.foobar.com), or a full e-mail address (clark@research.foobar.com).
GNATS can match addresses in three e-mail formats:
If GNATS sees other e-mail address formats, it uses the default submitter ID.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
classes
file This file lists the possible classes of Problem Reports. Each line
consists of a class name, followed by a colon and an optional class type name
(the class type name is not used for anything in the current implementation of
GNATS, so it may be left blank. The class
and class-type-name
fields may only contain alphanumerics, `-',
`_', and `.', but no other characters.
Then comes another colon, followed by an optional one-line description of the class. GNATS itself does not use the class description, but external tools such as Gnatsweb and TkGnats may use it. Therefore, a line in this file should at least contain the following:
class::class description |
Lines beginning with `#' will be ignored, and the first listed class is the default class for an incoming Problem Report.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following files are database-specific and are located in the `gnats-adm' subdirectory of the database directory. These files are maintained by GNATS; you should never need to touch them.
3.5.1 The index
fileThe `index' file 3.5.2 The current
fileThe `current' file
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
index
file The index is used to accelerate searches on the database by query-pr
and edit-pr
. This file is not created until the first PR comes in. It is then kept
up to date by GNATS; you should never touch this file.
Searches on subjects contained in the index are much faster than searches which depend on data not in the index. Inexes come in two different formats: binary and plain-text. Binary indexes are safer, in that they avoid certain problems that may crop up if the field separators used by plain-text indexes appear in field data.
A plain-text index contains single-line entries for all PR fields except for the multitext fields such as Description, How-To-Repeat, etc. Fields are separated by bars (`|') except for `>Category:' and `>Number:', which are separated by a slash (`/').
Binary indexes are not meant to be human-readable, but they are safer than the plain-text variety, in that they avoid certain problems that may crop up if the field separators used by plain-text indexes appear in field data.
The format of the index for a database is set in the `dbconfig' file. See section Index file description.
Should the `index' file become corrupted, the gen-index
utility can be used to regenerate it. See section
Regenerating the index.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
current
file This file contains the last serial number assigned to an incoming PR. It is used internally by GNATS; you need never touch this file.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These tools are used by the GNATS administrator as part of the periodic maintenance and configuration of GNATS. See section GNATS Administration.
3.6.1 Initializing a new database 3.6.2 Adding a problem category 3.6.3 Removing a problem category 3.6.4 Regenerating the index
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To initialize a new GNATS database:
mkdb
, using
mkdb directory |
Where directory is the directory you specified in the
`databases' file. mkdb
creates this directory and populates it with the directories
`pending', `gnats-queue' and `gnats-adm'. A full set
of sample configuration files is copied to the `gnats-adm' directory.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To add new categories to the database:
categories
file.
mkcat
If applicable. If create-category-dirs
is set to false
in the database `dbconfig' file, you need to create category
directories with mkcat
. mkcat
creates a subdirectory under the database directory for any new
categories which appear in the `categories' file. [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To remove a category from the database:
rmcat
using
rmcat category [ category... ] |
where category is the category you wish to remove. You
can specify as many categories as you wish as long as each category has no PRs
associated with it. rmcat
removes the directory where the Problem Reports for that category had
been stored.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If your `index' file becomes corrupted, or if you need a copy of the current index for some reason, use
gen-index [ -n | --numeric ] [ -d databasename | --database=databasename ] [ -o filename | --outfile=filename ] [ -i | --import ] [ -e | --export ] [ -h | --help] [ -V | --version ] |
With no options, gen-index
generates an index that is sorted by the order that the categories
appear in the `categories' file. The index is generated in plaintext
or binary format according to the value of binary-index
in the `dbconfig' file (see section
Index file description). The results are
printed to standard output. The options are:
-n
--numeric
-d databasename
--database=databasename
gen-index
attempts to index the database with name taken from the the
GNATSDB environment variable, and if that is undefined, the default
database, as set when GNATS was built (usually default
).
-o filename
--outfile=filename
-i
--import
-e
--export
-h
--help
gen-index
.
-V
--version
gen-index
. [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These tools are used internally by GNATS. You should never need to run these by hand; however, a complete understanding may help you locate problems with the GNATS tools or with your local implementation.
3.7.1 Handling incoming traffic 3.7.2 Processing incoming traffic 3.7.3 Timely reminders 3.7.4 The edit-pr
driverThe edit-pr driver
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The program queue-pr
handles traffic coming into GNATS. queue-pr
queues incoming Problem Reports in the `gnats-queue' directory
of the database, and then periodically (via cron
) passes them on to file-pr
to be filed in the GNATS database. See section
Installing GNATS.
The usage for queue-pr
is as follows:
queue-pr [ -q | --queue ] [ -r | --run ] [ -f filename | --file=filename ] [ -d databasename | --database=databasename ] [ -h | --help] [ -V | --version ] |
One of `-q' or `-r' (or their longer-named
counterparts) must be present upon each call to queue-pr
. These options provide different functions, as described below.
-q
--queue
GNATS_ROOT
(see section Where GNATS lives).
-r
--run
file-pr
one by one.
-f filename
--file=filename
-d databasename
--directory=databasename
default
).
-h
--help
gen-index
.
-V
--version
gen-index
. [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
queue-pr
hands off queued Problem Reports to file-pr
one at a time. file-pr
checks each Problem Report for correct information in its fields
(particularly a correct `>Category:'), assigns it an
identification number, and files it in the database under the appropriate
category.
If the `>Category:' field does not contain a valid
category value (i.e., matching a line in the categories
file; see section The categories
file), the PR is assigned to the default category, as set in the dbconfig
file. If there is no default category defined, the PR is given a
`>Category:' value of `pending' and is placed in
the `pending' directory. The GNATS administrator is notified of the
unplaceable PR.
file-pr
assigns the Problem Report an identification number, files it in the
GNATS database (under the default, if the `>Category:' field
contains an invalid category), and sends acknowledgments to appropriate
parties. For the default GNATS configuration, the person responsible for that
category of problem (see section The categories
file) and the person responsible for the submitter site where the
PR originated (see section The 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 (see section Changing your GNATS
configuration).
The usage for file-pr
is as follows:
file-pr [ -f filename | --file=filename ] [ -d databasename | --directory=databasename ] [ -h | --help ] [ -V | --version ] network options: [ -H host | --host=host ] [ -P port | --port=port ] [ -v username | --user=username ] [ -w password | --passwd=password ] |
file-pr
requires no options in order to operate, and takes input from standard
input (normally, the output of `queue-pr -r') unless otherwise
specified. The options include:
-f filename
--filename=filename
-d databasename
--database=databasename
default
).
-h
--help
file-pr
.
-V
--version
file-pr
. file-pr
can file PRs across a network, talking to a remote gnatsd. The
following options relate to network access:
-H host
--host=host
-P port
--port=port
-v username
--username=username
-w password
--passwd=password
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
at-pr
creates a queued job using at
which, after an allotted response time is past, checks the PR
to see if its state has changed from `open'. When the PR is
originally filed, file-pr
checks the notify-about-expired-prs
parameter in the `dbconfig' file. If this parameter is set to true
, file-pr
calls at-pr
, which sets up the expiry check.
The `submitters' file contains the response time for each >Submitter-Id:
(see section The submitters
file). The time is determined in business hours, which are
defined in the database's `dbconfig' file (see section
Overall database configuration).
If the PR is still open after the requisite time period has passed, at-pr
sends a reminder to the GNATS administrator, to the maintainer
responsible for that submitter, and to the maintainer responsible for the PR
with the following message:
To: submitter-contact responsible gnats-admin Subject: PR gnats-id not analyzed in #hours hours PR gnats-id was not analyzed within the acknowledgment period of #hours business hours. The pertinent information is: Submitter-Id: submitter Originator: full name of the submitter Synopsis: synopsis Person responsible for the PR: responsible -- The GNU Problem Report Management System (GNATS) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
edit-pr
driver pr-edit
does the background work for edit-pr
, including error-checking and refiling newly edited Problem Reports,
handling file and database locks and deletion of PRs. It can be called
interactively, though it has no usable editing interface.
The usage for pr-edit
is:
pr-edit [ -l username | --lock=username ] [ -u | --unlockdb ] [ -L | --lockdb ] [ -U | --unlockdb ] [ -c | --check ] [ -C | --check-initial ] [ -s | --submit ] [ -a field | --append field=field ] [ -r field | --replace=field ] [ --delete-pr ] [ -p process-id | --process=process-id ] [ -d databasename | --database=databasename ] [ -f filename | --filename=filename ] [ -V | --version ] [ -h | --help ] [ -v username | --user=username ] [ -w passwd | --passwd=passwd ] [ -H host | --host=host ] [ -P port | --port=port ] [ -D | --debug ] [ PR number ] |
A lock is placed
on a Problem Report while the PR is being edited. The lock is simply a file in
the `locks' subdirectory of the `gnats-adm' directory of the
database, with the name `gnats-id.lock', which contains the
name of the user who created the lock. user then "owns" the lock,
and must remove it before the PR can be locked again, even by the same
user(3). If a PR
is already locked when you attempt to edit it, pr-edit
prints an error message giving the name of the user who is currently
editing the PR.
If you do not specify PR number, pr-edit
reads from standard input. You must specify PR number for
the functions which affect PR locks, `--lock=username'
and `--unlock'.
-L
--lockdb
--database
or -d
option. No PRs may be edited, created or deleted while the database is
locked. This option is generally used when editing the index file.
-U
--unlockdb
-c
--check
-C
--check-initial
--check
options are used to verify that a proposed PR's field contents are
valid. The PR is read in (either from stdin or a file specified with --filename
), and its fields are compared against the rules specified by the
database configuration of the selected database. Warnings are given for
enumerated fields whose contents do not contain one of the required values or
fields that do not match required regexps. --check-initial
is used to verify initial PRs, rather than proposed edits of existing
PRs.
-s
--submit
The following options require a PR number to be given.
--delete-pr
-l username
--lock=username
--process
or -p
option is also given, that process-id is associated with the lock.
-u
--unlock
-a field
--append=field
-r field
--replace=field
--append
and --replace
are used to append or replace content of a specific field within a PR.
The new field content is read in from stdin (or from the file specified with
the --filename
option), and either appended or replaced to the specified field. The
field contents are verified for correctness before the PR is rewritten. If the
edit is successful, a zero exit status is returned. If the edit failed, a
non-zero exit status is returned, and the reasons for the failure are printed
to stdout.
PR number
PR number
is specified with no other options, a replacement PR is read in (either
from stdin or the file specified with --filename
). If the PR contents are valid and correct, the existing PR is replaced
with the new PR contents. If the edit is successful, a zero exit status is re
turned. If the edit failed, a non-zero exit status is returned, and the reasons
for the failure are printed to stdout.
-d database
--database=database
default
). This option overrides the database specified in the GNATSDB
environment variable.
-f filename
--filename=filename
--filename
is not specified, the PR or field content is read in from stdin.
-h
--help
pr-edit
.
-V
--version
pr-edit
. pr-edit
can edit PRs across a network, talking to a remote gnatsd. The
following options relate to network access:
-H host
--host=host
-P port
--port=port
-v username
--username=username
-w password
--passwd=password
-D
--debug