| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In daily usage, GNATS is self-maintaining. However, there are various administrative duties which need to be performed periodically. Also, requirements may change with time, so it may be necessary to make changes to the GNATS configuration at some point:
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.
mkdb tool
does most of the work for you. See section Adding another database.
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.
4.1 Overview of GNATS configuration 4.2 The databasesfileThe databases file 4.3 The dbconfigfileThe dbconfig file 4.4 Other database-specific config files Configuration files 4.5 Administrative data files 4.6 Administrative utilities 4.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.
Note that if you add a new local database, you must create its data
directory, including appropriate subdirectories and administrative
files. This is to be best done using the mkdb tool,
See section 4.6.1 Adding another database.
| [ < ] | [ > ] | [ << ] | [ 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.
4.3.1 Overall database configuration 4.3.2 Individual field configuration 4.3.3 Field datatypes 4.3.4 Edit controls Trigger on certain edit actions. 4.3.5 Named query definitions Define and name standard queries. 4.3.6 Audit-trail formats Specify formatting of the audit-trail. 4.3.7 Outgoing email formats Specify contents and formatting of messages sent out by GNATS. 4.3.8 Index file description Specify the general format and contents of the database index. 4.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] | [ ? ] |
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
(`:').
The values in the default string for this field type should be
separated by one of the defined separators. An example clarifies this.
If we have a field named ingredients where the default values
should be `sugar', `flour' and `baking powder' and the
separator is a colon `:', the following sets these defaults:
default "sugar:flour:baking powder" |
enumerated-in-file {
path "filename"
fields {
"name" [ "name" ... ]
} key "name"
[ allow-any-value ]
}
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. Subfields within the file are separated with colons (`:'). Lines beginning with a hash sign (`#') are ignored as comments. Records within the file are separated with newlines.
The field option is used to name the subfields in the
administrative file. There must be at least one subfield, which is used
to list the legal values for the field. If the administrative file is
empty (or does not contain any non-empty non-comment lines), the PR
field must be empty.
The key option is used to designate which field in the
administrative file should be used to list the legal values for the PR
field. The value must match one of the field names in the field
option.
If the allow-any-value option is present, the value of the PR
field is not required to appear in the administrative file -- any value
will be accepted.
Note that there is no default keyword for
enumerated-in-file. These fields get their default value from
the first entry in the associated administrative file.
multi-enumerated-in-file {
path "filename"
fields {
"name" [ "name" ... ]
} key "name"
[ default "string" ]
[ allow-any-value ]
[ separators "string" ]
}
multi-enumerated-in-file is to multienum what
enumerated-in-file is to enum. Its options have the
same meaning as their counterparts in the multienum and
enumerated-in-file fields.
NOTE: Keywords may appear in any sequence, with one exception --
the separators keyword, if present, has to come last. This rule
only applies to fields of type multi-enumerated-in-file.
date
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. See 4.3.6 Audit-trail formats and 4.3.7 Outgoing email formats.
The require-change-reason option specifies that a change reason
must be present in the PR when this field is edited. This option only
makes sense if an audit-trail entry is required, as the change reason is
otherwise unused.
The set-field and append-to-field options are used to
change the value of the field fieldname in the PR. The supplied
format is used to format the value that will be placed in the field.
append-to-field appends the resulting formatted string to the
existing, while set-field completely replaces the contents.
Any field may be edited by the set-field or
append-to-field option (the read-only option on a field is
ignored). However, the changes are subject to the usual field content
checks.
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 2.4.2 Formatting query-pr output.
It basically contains a string with printf-like % escapes. The output
of the query is formatted as specified by this format string.
The fields option lists the fields to be used with the format
string. If the fields option is present without a format
option, the contents of the listed fields are printed out, separated by
newlines.
The named query formats full, standard amd summary
must be present in the `dbconfig' file. full and
summary correspond to the query-pr options --full
and --summary, while standard is used when no format
option is given to query-pr.
| [ < ] | [ > ] | [ << ] | [ 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
EDITADDR gnatsd command or from the `responsible'
file; if not available, user's local address is used.
$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-names or
gnats-field-names.
When an email-header-name or gnats-field-name value is
given, GNATS will attempt to extract an email address from the
specified location. If several values are given on the same line,
separated by `|' characters, GNATS will try to extract an address
from each location in turn until it finds a header or field which is
nonempty. The following example should clarify this:
mail-format "initial-response-to-submitter" {
from-address {
fixed-address "gnats-admin"
}
to-addresses {
"Reply-To:" | "From:" | "Submitter-Id"
} ...
|
This partial mail-format section specifies the format of the
address headers in the email message that is sent out as an
acknowledgment of a received PR. The From: field of the message
will contain the email address of the GNATS administrator, as
specified by the gnats-admin line in the `responsible' file.
To fill in the To: header, GNATS will first look for the
mail header Reply-To: in the PR and use the contents of that, if
any. If that header doesn't exist or is empty, it will look for the
contents of the From: email header, and if that yields nothing,
it will look for the GNATS Submitter-Id field and use the
contents of that.
Other email headers to be included in messages sent out by GNATS
can be specified by header subsections of the mail-header
section. formatstring and fieldname are similar to those
used by the named query format. Each header line must have a newline
character (`\n') at the end.
The email message body is specified in the body subsection of the
mail-format section. Just as for a header section, the
body section must contain a formatstring and
fieldname values.
For some of the formats that GNATS recognizes, special variables are available for use. The following table lists the formats that provide special variables. See the example below for an illustration of how they are used.
appended-email-response
$MailFrom
$MailTo
$MailSubject
$MailCC
$NewAuditTrail
audit-mail
$EditUserEmailAddr
EDITADDR gnatsd command or from the `responsible'
file; if not available, user's local address is used.
$OldResponsible
$NewAuditTrail
deleted-pr-mail
$EditUserEmailAddr
EDITADDR gnatsd command or from the `responsible'
file; if not available, user's local address is used.
$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] | [ ? ] |
4.4.1 The categoriesfile4.4.2 The responsiblefile4.4.3 The submittersfile4.4.4 The statesfile4.4.5 The addressesfile4.4.6 The classesfile
| [ < ] | [ > ] | [ << ] | [ 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 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.
4.5.1 The indexfileThe `index' file 4.5.2 The currentfileThe `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.
4.6.1 Adding another database 4.6.2 Adding a problem category 4.6.3 Removing a problem category 4.6.4 Regenerating the index 4.6.5 Checking database health 4.6.6 Managing user passwords
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To initialize a new GNATS database:
mkdb, using
mkdb database |
where database is the database you specified in the
`databases' file. mkdb creates the database directory and
populates it with the directories `pending', `gnats-queue'
and `gnats-adm'. A full set of sample configuration files is
copied to the `gnats-adm' directory.
| [ < ] | [ > ] | [ << ] | [ 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] | [ ? ] |
The `check-db' script is useful for performing periodic checks on database health. It accepts the following options:
-d databasename
--database=databasename
--all-databases
--database option.
If no option is given, the default database is checked.
During its operation, check-db first attempts to lock
database. If this is not possible, it repeats the locking
attempts for five minutes; if it fails, it sends a mail message
notifying the administrator of the failure and exits.
Once the database is locked, the script searches the database for lock files that are more than 24 hours old. Any old lock files are reported to the administrator in a mail message.
After checking for old lock files, it calls gen-index
(see section Regenerating the index) and compares the
results with the current `index' file of the database; any
inconsistencies are reported to the administrators in a mail message.
After checking the index file for inconsistencies, the script unlocks
the database and exits.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Older versions of GNATS, up to and including version 3.x, stored
user passwords in plaintext in the `gnatsd.access' files. Version 4
has the options of storing the password as MD5 or standard DES
crypt() hashes (as most UNIX versions do in the system password
files) as well as in plaintext. Since the password strings require a
prefix to indicate how they are encrypted, one is forced to convert the
old password files to a new format when upgrading to GNATS version
4. See section Upgrading from older versions.
The gnats-pwconv tool takes care of converting the old password
files to the new format:
gnats-pwconv [ -c | --crypt ] [ -m | --md5 ] [ -p | --plaintext ]
[ -h | --help] [ -V | --version ] INFILE [OUTFILE]
|
Unless the --version or --help options are given, exactly
one encryption method must be specified, as well as an input file. The
output file parameter is optional. If one is not specified, results will
be printed on standard output.
| [ < ] | [ > ] | [ << ] | [ 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.
4.7.1 Handling incoming traffic 4.7.2 Processing incoming traffic 4.7.3 Timely reminders 4.7.4 The edit-prdriverThe edit-pr driver 4.7.5 The diff-prstool4.7.6 The pr-agetool
| [ < ] | [ > ] | [ << ] | [ 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
DATABASEDIR (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 | --database=databasename ]
[ -h | --help ] [ -V | --version ]
network options:
[ -H host | --host=host ]
[ -P port | --port=port ]
[ -v username | --user=username ]
[ -w password | --passwd=password ]
|
file-pr requires no options in order to operate, and takes input
from standard input (normally, the output of `queue-pr -r')
unless otherwise specified. The options include:
-f filename
--filename=filename
-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 urgent and is still open after the requisite time period
has passed, at-pr sends a reminder to the GNATS
administrator, to the maintainer responsible for that submitter, and
to the maintainer responsible for the PR with the following message:
To: submitter-contact responsible gnats-admin Subject: PR gnats-id not analyzed in #hours hours PR gnats-id was not analyzed within the acknowledgment period of #hours business hours. The pertinent information is: Submitter-Id: submitter Originator: full name of the submitter Synopsis: synopsis Person responsible for the PR: responsible -- The GNU Problem Report Management System (GNATS) |
The PR is urgent if its priority is `critical' or if its priority is `serious' and the severity is `high'.
| [ < ] | [ > ] | [ << ] | [ 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 ]
[ -R reason | --reason=reason ]
[ -p process-id | --process=process-id ]
[ -d databasename | --database=databasename ]
[ -f filename | --filename=filename ]
[ -V | --version ]
[ -h | --help ] [ -v username | --user=username ]
[ -w passwd | --passwd=passwd ]
[ -H host | --host=host ]
[ -P port | --port=port ]
[ -D | --debug ] [ PR number ]
|
A lock is placed on a Problem Report while the PR is being edited.
The lock is simply a file in the `locks' subdirectory of the
`gnats-adm' directory of the database, with the name
`gnats-id.lock', which contains the name of the
user who created the lock. user then "owns" the
lock, and must remove it before the PR can be locked again, even by the
same user(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.
-R reason
--reason=reason
dbconfig file. If you edit a problem and
change any of such fields, you must issue a short text, the
reason of the change, through this option. If the option is
used and no change-reason requiring field is actually changed, the
option has no effect.
PR number
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
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
diff-prs tool
The diff-prs tool is invoked as follows:
diff-prs prfile1 prfile2 |
diff-prs simply reads the PRs contained in prfile1 and
prfile2 and returns a list of the fields that are different
between the two. No output is produced if the PRs are identical.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pr-age tool
The pr-age tool reports the time, in days and hours, since the PR
arrived. Usage is
pr-age [ -d databasename | --database=databasename ]
[ -H host | --host=host ]
[ -P port | --port=port ]
[ -v username | --user=username ]
[ -w password | --passwd=password ]
[ -h | --help ] [ -V | --version ]
|
For an explanation of the arguments listed above, please refer to the
usage description for file-pr (file-pr).
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |