gnatsd
This manual documents gnats, the gnu Problem Report Management System, version 4.1.999. gnats is a bug-tracking tool designed for use at a central Support Site. Users who experience problems use electronic mail, web-based or other clients communicating with the gnats network daemon running at the support site or direct database submissions to communicate these problems to maintainers at that Support Site. gnats partially automates the tracking of these Problem Reports (PRs) by:
gnats offers many of the same features offered by more generalized databases, including editing, querying, and basic reporting. The gnats database itself is an ordered repository for problem reports; each PR receives a unique, incremental PR number which identifies it throughout its lifetime. For a discussion on the working system adopted by gnats, see The database paradigm.
You can access the submitting, editing, and querying functions of gnats from within gnu Emacs. See The gnats user tools.
Any support organization realizes that a large amount of data flows back and forth between the maintainers and the users of their products. This data often takes the form of problem reports and communication via electronic mail. gnats addresses the problem of organizing this communication by defining a database made up of archived and indexed problem reports.
gnats was designed as a tool for software maintainers. It consists of several utilities which, when used in concert, formulate and administer a database of Problem Reports grouped by site-defined problem categories. It allows a support organization to keep track of problems (hence the term Problem Report) in an organized fashion. Essentially, gnats acts as an active archive for field-separated textual data.
It is in your best interest as the maintainer of a body of work to organize the feedback you receive on that work, and to make it easy for users of your work to report problems and suggestions.
gnats makes this easy by automatically filing incoming problem reports into appropriate places, by notifying responsible parties of the existence of the problem and (optionally) sending an acknowledgment to the submitter that the report was received, and by making these Problem Reports accessible to queries and easily editable. gnats is a database specialized for a specific task.
gnats was designed for use at a Support Site that handles a high level of problem-related traffic. It maintains Problem Reports in the form of text files with defined fields (see gnats data fields). The location of the database, as well as the categories it accepts as valid, the maintainers for whom it provides service, and the submitters from whom it accepts Problem Reports, are all definable by the Support Site. See gnats administration.
Each PR is a separate file within a main repository
(see Where gnats lives). Editing access to the
database is regulated to maintain consistency. To make queries on
the database faster, an index is kept automatically (see The index file).
We provide several software tools so that users may submit new Problem Reports, edit existing Problem Reports, and query the database.
send-pr is used by both product maintainers and the end users
of the products they support to submit PRs to the database.
edit-pr is used by maintainers when editing problem
reports in the database.
query-pr to
make inquiries about individual PRs or groups of PRs.
Other interfaces to gnats include Gnatsweb, a web-based tool which provides features for submitting and editing PRs and querying the database, and TkGnats, a Tcl/Tk-based frontend. These tools are distributed together with gnats.
At the Support Site, a gnats administrator is charged with the
duty of maintaining gnats. These duties are discussed in detail in
gnats Administration, and generally include
configuring gnats for the Support Site, editing PRs that gnats
cannot process, pruning log files, setting up new problem categories,
backing up the database, and distributing send-pr so that others
may submit Problem Reports.
Responsibility for a given Problem Report initially depends on the category of the problem. Optionally, an automated reminder can be sent to the responsible person if a problem report is neglected for a requisite time period. See Overview of gnats configuration.
gnats does not have the ability to decipher random text. If there is no default category set, any problem reports which arrive in a format gnats does not recognize are placed in a separate directory pending investigation by the gnats administrator (see gnats Administration).
Once a problem is recorded in the database, work can begin toward a solution. A problem's initial state type is open (see States of Problem Reports). An acknowledgment may be sent to the originator of the bug report (depending on whether this feature has been switched on in the gnats configuration). gnats forwards copies of the report to the party responsible for that problem category and to the person responsible for problems arriving from that submitter.
When a problem has been identified, the maintainer can change its state
to analyzed, and then to feedback when a solution is found.
gnats may be configured so that each time the state of a PR
changes, the submitter of the problem report is notified of the reason
for the change. If the party responsible for the PR changes, the
previous responsible party and the new responsible party receive notice
of the change. The change and reason are also recorded in the
Audit-Trail field of the Problem Report. (See Editing existing Problem Reports. For information on the Audit-Trail
field, see Problem Report format.)
When the originator of the Problem Report confirms that the solution works, the maintainer can change the state to closed. If the PR cannot be closed, the maintainer can change its state to suspended as a last resort. (For a more detailed description of the standard states, see States of Problem Reports.)
It should be emphasized that what we describe here is the default way
that gnats works, but as of version 4, gnats is extremely
customizable, allowing sites to tailor almost every aspect of its
behavior. See for instance The dbconfig file and See States of Problem Reports.)
This informal flowchart shows the relationships of the gnats tools to each other and to the files with which they interoperate.
Each PR goes through a defined series of states between origination and closure. By default, the originator of a PR receives notification automatically of any state changes.
Unless your site has customized states (see states file (gnats)), gnats uses these states:
The format of a PR is designed to reflect the nature of gnats as a database. Information is arranged into fields, and kept in individual records (Problem Reports).
A Problem Report contains two different types of fields: Mail Header fields, which are used by the mail handler for delivery, and Problem Report fields, which contain information relevant to the Problem Report and its submitter. A Problem Report is essentially a specially formatted electronic mail message.
Problem Report fields are denoted by a keyword which begins with > and ends with :, as in >Confidential:. Fields belong to one of eight data types as listed in Field datatypes reference. As of version 4 of gnats all characteristics of fields, such as field name, data type, allowed values, permitted operations, on-change actions etc. are configurable.
For details, see see The dbconfig file.
The following is an example Problem Report with the fields that would be
present in a standard gnats configuration. Mail headers are at the
top, followed by gnats fields, which begin with > and end
with :. The Subject: line in the mail header and the
Synopsis field are usually duplicates of each other.
Message-Id: message-id
Date: date
From: address
Reply-To: address
To: bug-address
Subject: subject
>Number: gnats-id
>Category: category
>Synopsis: synopsis
>Confidential: yes or no
>Severity: critical, serious, or non-critical
>Priority: high, medium or low
>Responsible: responsible
>State: open, analyzed, suspended, feedback, or closed
>Class: sw-bug, doc-bug, change-request, support,
duplicate, or mistaken
>Submitter-Id: submitter-id
>Arrival-Date: date
>Originator: name
>Organization: organization
>Release: release
>Environment:
environment
>Description:
description
>How-To-Repeat:
how-to-repeat
>Fix:
fix
>Audit-Trail:
appended-messages...
State-Changed-From-To: from-to
State-Changed-When: date
State-Changed-Why:
reason
Responsible-Changed-From-To: from-to
Responsible-Changed-When: date
Responsible-Changed-Why:
reason
>Unformatted:
miscellaneous
|
The following is a short reference to the characteristics of the different field types.
For details, see Field datatypes.
textmultitextenum(See The dbconfig file, for details.
multienumenum datatype, except that the field can contain
multiple values.
enumerated-in-fileenum, but the allowed field values are listed in a
separate file on the gnats server.
multi-enumerated-in-fileenumerated-in-file, except that the field can contain
multiple values.
dateinteger
A Problem Report may contain any mail header field described in the
Internet standard RFC-822. The send-pr tool can be configured
either to submit PRs to the support site by e-mail or by talking
directly to the gnatsd network daemon on the gnats server.
This is also true for other client tools such as Gnatsweb. Even when
these tools are set up submit PRs directly to gnatsd, they will
still include mail header fields that identify the sender and the
subject in the submitted PR:
To:Subject:Synopsis field.
From:send-pr are used; should always
contain the originator's e-mail address.
Reply-To:From: field.
One of the configurable options for gnats is whether or not to
retain Received-By headers, which often consume a lot of
space and are not often used. See The dbconfig file.
In a standard gnats installation, certain fields will always be
present in a Problem Report. If a PR arrives without one or more of
these fields, gnats will add them, and if they have default
values set by the configuration at the Support Site, they will be
filled in with these values. Certain tools such as send-pr are
set up to provide sensible defaults for most fields
(see The send-pr.conf configuration file.)
In the list below, the field type (text, multitext,
enumerated, etc.) is supplied in parantheses. The different
field types are explained briefly in Field datatypes reference.
Submitter-Idenumerated-in-file) A unique identification code assigned by the
Support Site. It is used to identify all Problem Reports coming from a
particular site. Submitters without a value for this field can invoke
send-pr with the --request-id option to apply for one from
the support organization. Problem Reports from those not affiliated
with the support organization should use the default value of net
for this field.
See The submitters file, for details.
Notify-Listtext) Comma-separated list of e-mail-addresses of people to
notify when the PR changes significantly, i.e. when the Audit-Trail
changes. This list is independent from the Notify subfield of entries
in the categories file of the gnats database.
Originatortext) Originator's real name. Note that the Submitter and
Originator might not be the same person/entity in all cases.
Organizationmultitext) The originator's organization.
Confidentialenum) Use of this field depends on the originator's relationship
with the support organization; contractual agreements often have
provisions for preserving confidentiality. Conversely, a lack of a
contract often means that any data provided will not be considered
confidential. Submitters should be advised to contact the support
organization directly if this is an issue.
If the originator's relationship to the support organization provides for confidentiality, then if the value of this field is yes the support organization treats the PR as confidential; any code samples provided are not made publicly available.
Synopsistext) One-line summary of the problem. send-pr copies
this information to the Subject line when you submit a Problem
Report.
Severityenum) The severity of the problem. By default, accepted
values include:
criticalseriousnon-criticalPriorityenumerated) How soon the originator requires a solution.
Accepted values include:
highmediumlowCategoryenumerated-in-file) The name of the product, component or
concept where the problem lies. The values for this field are defined
by the Support Site.
See The categories file, for details.
Classenumerated-in-file) The class of a problem in a default
gnats installation can be one of the following:
sw-bugdoc-bugchange-requestsupportduplicate (pr-number)mistakenSee The classes file, for details.
Releasetext) Release or version number of the product, component or
concept.
Environmentmultitext) Description of the environment where the problem
occurred: machine architecture, operating system, host and target types,
libraries, pathnames, etc.
Descriptionmultitext) Precise description of the problem.
How-To-Repeatmultitext) Example code, input, or activities to reproduce the
problem. The support organization uses example code both to reproduce
the problem and to test whether the problem is fixed. Include all
preconditions, inputs, outputs, conditions after the problem, and
symptoms. Any additional important information should be included.
Include all the details that would be necessary for someone else to
recreate the problem reported, however obvious. Sometimes seemingly
arbitrary or obvious information can point the way toward a solution.
See also Helpful hints.
Fixmultitext) A description of a solution to the problem, or a
patch which solves the problem. (This field is most often filled in at
the Support Site; we provide it to the submitter in case he or she has
solved the problem.)
gnats adds the following fields when the PR arrives at the Support Site:
Numberenumerated) The incremental identification number for this PR.
This is included in the automated reply to the submitter (if that
feature of gnats is activated; see The dbconfig file). It is also included in the copy of the PR that
is sent to the maintainer.
The Number field is often paired with the Category field
as
category/number
in subsequent email messages. This is gnats' way of tracking followup messages that arrive by mail so that they are filed as part of the original PR.
Stateenumerated) The current state of the PR. In default gnats
installations, accepted values are:
openanalyzedfeedbackclosedsuspendedThe initial state of a PR is open. See States of Problem Reports.
Responsibletext) The person at the Support Site who is responsible for this
PR.
gnats retrieves this information from the categories file
(see The categories file).
Arrival-Datedate) The time that this PR was received by gnats. The
date is provided automatically by gnats.
Date-Requireddate) The date by which a fix is required. This is up to the
maintainers at the Support Site to determine, so this field is not
available until after the PR has been submitted.
Audit-Trailmultitext) Tracks related electronic mail as well as changes in
the State and Responsible fields with the sub-fields:
State-Changed-<From>-<To>: oldstate>-<newstateState field values.
Responsible-Changed-<From>-<To>: oldresp>-<newrespResponsible field values.
State-Changed-By: nameResponsible-Changed-By: nameState-Changed-When: timestampResponsible-Changed-When: timestampState-Changed-Why: reason...Responsible-Changed-Why: reason...The Audit-Trail field also contains any mail messages received by
gnats related to this PR, in the order received. gnats needs
to find a reference to the PR in the Subject field of received email in
order to be able to file it correctly, see Following up via direct email.
Unformattedmultitext) Any random text found outside the fields in the
original Problem Report.
During a Problem Report's journey from open to closed, two
more fields, Last-Modified and Closed Date (both of type
date) will be added.
This chapter describes the user tools distributed with gnats. The gnats administrative and internal tools are described in gnats Administration. The user tools provide facilities for initial submission, querying and editing of Problem Reports:
send-prquery-predit-pr
All the gnats user tools honor the GNATSDB environment
variable which is used to determine which database to use. For a local
database, it contains the name of the database to access.
For network access via gnatsd, it contains a colon-separated list of strings that describe the remote database in the form
server:port:databasename:username:password
Any of the fields may be omitted except for server, but at least one colon must appear; otherwise, the value is assumed to be the name of a local database.
If GNATSDB is not set and no command-line options are used to
specify the database, it is assumed that the database is local and that
its name is default.
Use send-pr to submit Problem Reports to the database.
send-pr is a shell script which composes a template for
submitters to complete.
You can invoke send-pr from a shell prompt, or from within
gnu Emacs using M-x send-pr (see Submitting Problem Reports from Emacs.)
send-pr from the shell send-pr [ -b | --batch ]
[ -d database | --database database ]
[ -f file | --file file ]
[ -p | --print ] [ --request-id ]
[ -s severity | --severity severity ]
[ -V | --version ] [ -h | --help ]
Invoking send-pr with no options assumes that you want to
submit to the local gnats database named default and calls
the editor named in your environment variable EDITOR on a PR
template for this database.
-b--batchsend-pr usually
prints while running.
-d database, --database databasedefault is
assumed. This option overrides the database specified in the
GNATSDB environment variable. database can also be set
to a remote database by using the format for GNATSDB described
in Environment variables and gnats tools.
-f problem-report--file problem-reportsend-pr verifies that the
contents of the file constitute a valid PR and asks you if you want to
edit it or send it directly. If the PR text is invalid you will be
told what is wrong and be given the option to edit it. If
problem-report is -, send-pr reads from
standard input.
-p--print-d or --database options aren't specified, print the
template for the local default database. No PR is submitted.
--request-idSubmitter-Id to the Support Site.
-s severity--severity severitySeverity field to severity.
-V--versionsend-pr version number and a usage summary. No mail
is sent.
-h--helpsend-pr. No mail is sent.
send-pr from within Emacs
You can use an interactive send-pr interface from within gnu
Emacs to fill out your Problem Report. We recommend that you
familiarize yourself with Emacs before using this feature
(see Introduction (GNU Emacs)).
Call send-pr with M-x send-pr.1 send-pr responds
with a preconfigured Problem Report template. The Emacs interface is
described in more detail in a separate section, See The Emacs interface to gnats.
Invoking send-pr presents a PR template with a number of
fields already filled in with default values for the database you are
submitting to. Complete the template as thoroughly as possible to
make a useful bug report. Submit only one bug with each PR.
A template consists of three sections:
The Comments section at the top of the template contains basic
instructions for completing the Problem Report, as well as a list of
valid entries for the Category field. One (and only one) of
these values should be placed in the Category field further down
in the Problem Report.
SEND-PR: -*- send-pr -*-
SEND-PR: Lines starting with `SEND-PR' will be removed
SEND-PR: automatically as well as all comments (the text
SEND-PR: below enclosed in `<' and `>').
SEND-PR:
SEND-PR: Please consult the document `Reporting Problems
SEND-PR: Using send-pr' if you are not sure how to fill out
SEND-PR: a problem report.
SEND-PR:
SEND-PR: Choose from the following categories:
The comments lines are all preceded by the string SEND-PR: and are erased automatically when the PR is submitted. The instructional comments within < and > are also removed. (Only these comments are removed; lines you provide that happen to have those characters in them, such as examples of shell-level redirection, are not affected.)
The Mail Header section of the template contains a standard
mail header constructed by send-pr. send-pr can be set up
to submit PRs by e-mail or by speaking directly to the gnats
server, but since this header is part of the standard format of Problem
Reports, send-pr includes it even when it is set up to speak
directly to the server.
To: PR submission address
Subject: complete this field
From: your-login@your-site
Reply-To: your-login@your-site
X-send-pr-version: send-pr 4.1.999
send-pr automatically completes all the mail header fields except
the Subject line with default values. (See Problem Report format.)
The gnats fields below the mail header form the bulk of a gnats Problem Report.
Each field is either automatically completed with valid information
(such as your Submitter-Id) or contains a one-line instruction
specifying the information that field requires in order to be correct.
For example, the Confidential field expects a value of yes
or no, and the answer must fit on one line; similarly, the
Synopsis field expects a short synopsis of the problem, which
must also fit on one line. Fill out the fields as completely as
possible. See Helpful hints, for suggestions as to
what kinds of information to include.
The mechanisms send-pr uses to fill in default values is as
follows: Your preconfigured Submitter-Id is taken from the local
send-pr.conf configuration file. send-pr will set the
Originator field to the value of the NAME environment
variable if it has been set; similarly, Organization will be set
to the value of ORGANIZATION. If these variables aren't set in
you environment, send-pr uses the values set in the local
send-pr.conf configuration file, if that exists. If not, these
values are left blank in the template. send-pr also attempts to
find out some information about your system and architecture, and places
this information in the Environment field if it finds any.
In this example, words in italics are filled in with pre-configured information:
>Submitter-Id: your submitter-id
>Originator: your name here
>Organization:
your organization
>Confidential:<[ yes | no ] (one line)>
>Synopsis: <synopsis of the problem (one line)>
>Severity: <[non-critical | serious | critical](one line)>
>Priority: <[ low | medium | high ] (one line)>
>Category: <name of the product (one line)>
>Class: <[sw-bug | doc-bug | change-request | support]>
>Release: <release number (one line)>
>Environment:
<machine, os, target, libraries (multiple lines)>
>Description:
<precise description of the problem (multiple lines)>
>How-To-Repeat:
<code/input/activities to reproduce (multiple lines)>
>Fix:
<how to correct or work around the problem, if known
(multiple lines)>
When you finish editing the Problem Report, send-pr validates the
contents and if it looks OK either submits it directly to the
gnats server or submits it by mail to the address named in the
To field in the mail header.
If your PR contains one or more invalid field values, send-pr
places the PR in a temporary file named /tmp/pbadnnnn on
your machine. nnnn is the process identification number given
to your current send-pr session. If you are running
send-pr from the shell, you are prompted as to whether or not
you wish to try editing the same Problem Report again. If you are
running send-pr from Emacs, the Problem Report is placed in the
buffer *gnats-send*; you can edit this file and then submit
it with C-c C-c.
In addition to using send-pr, there is another way to submit a
problem report. You can simply send an e-mail message to the PR
submission e-mail address of the support site (This address should be
published by the support site.)
When you send unformatted e-mail to this address, gnats processes the message as a new problem report, filling in as many fields from defaults as it can:
SynopsisSynopsis field is filled in by the Subject header of
the e-mail message.
Submitter IDSubmitter field from the address
in the From header of the e-mail.
DescriptionDescription field.
Other fields, such as Category, Version, Severity,
etc. are set to default values as defined by the gnats administrator.
There is no orthodox standard for submitting effective bug reports,
though you might do well to consult the section on submitting bugs for
gnu gcc in Reporting Bugs (Using and Porting GNU CC), by Richard Stallman. This section contains
instructions on what kinds of information to include and what kinds of
mistakes to avoid.
In general, common sense (assuming such an animal exists) dictates the kind of information that would be most helpful in tracking down and resolving problems in software.
Use edit-pr to make changes to existing PRs in the database.
This tool can be invoked both from a shell prompt or from within GNU
Emacs using M-x edit-pr.
edit-pr first examines the PR you wish to edit and locks it if it
is not already locked. This is to prevent you from editing a PR at the
same time as another user. If the PR you wish to edit is already in the
process of being edited, edit-pr tells you the name of the person
who owns the lock.
You may edit any non-readonly fields in the database. We recommend that
you avoid deleting any information in the Text and MultiText
fields (such as Description and How-To-Repeat
(see Problem Report format). We also recommend that you
record the final solution to the problem in the Fix field for
future reference. Note that heavily customized installations of
gnats may have differently named fields, and sites using such
installations should provide their own set of routines and instructions
regarding how PRs should be treated throughout their life span.
After the PR has been edited, it is then resubmitted to the database,
and the index is updated (see The index file).
For information on pr-edit, the main driver for edit-pr,
see Internal utilities.
If you change a field that requires a reason for the change, such as the
Responsible or State fields in the default configuration,
edit-pr prompts you to supply a reason for the change. A message
is then appended to the Audit-Trail field of the PR with the
changed values and the change reason.
Depending on how the database is configured, editing various fields in the PR may also cause mail to be sent concerning these changes. In the default configuration, any fields that generate Audit-Trail entries will also cause a copy of the new Audit-Trail message to be sent.
Mail received at the PR submission email address and recognized by gnats as relating to an existing PR is also appended to the Audit-Trail field, see follow-up via email.
edit-pr from the shell edit-pr [ -V | --version ] [ -h | --help ]
[-d database | --database database] PR Number
Network-mode-only options:
[--host host | -H host] [--port port]
[--user user | -v user]
[--passwd passwd | -w passwd]
The options have the following meaning:
-h, --help-V, --version-d database, --database databaseGNATSDB environment
variable.
--host host, -H hostGNATSDB environment variable.
--port portGNATSDB environment variable.
--user user, -v userGNATSDB environment
variable.
--passwd passwd, -w passwdGNATSDB environment
variable.
edit-pr calls the editor specified in your environment variable
EDITOR on a temporary copy of that PR. (If you don't have the
variable EDITOR defined in your environment, the default editor
vi is used.)
Edit the PR, changing any relevant fields or adding to existing
information. When you exit the editor, edit-pr prompts you on
standard input for a reason if you have changed a field that requires
specifying a reason for the change.
If you have some additional information for a PR and for some reason do not want to (or cannot) edit the PR directly, you may append the information to the Audit-Trail field by mailing it to the PR submission address.
In order for GNATS to be able to recognize the mail as pertaining to an existing PR (as opposed to a new PR, see Submitting via e-mail), the Subject mail header field must contain a reference to the PR. GNATS matches the Subject header against the regular expression
\<(PR[ \t#/]?|[-[:alnum:]+.]+/)[0-9]+
to determine whether such a reference is present. Any text may precede or follow the reference in the Subject header. If more than one reference is present, the first is used and the rest ignored.
A PR reference matching the regular expression above has two parts. The second is the PR number (one or more digits). The first is either the capital letters 'PR' optionally followed by a separator character (blank, tab, hash mark or forward slash) or the category name followed by a forward slash. Following are some examples which match the regular expression:
PR 123 PR4567 PR#890 gnats/4711
The PR number and the category (if present) are checked for existence, and if the outcome is positive, the mail is appended to the Audit-Trail field of the PR. Note that the PR need not belong to the category because PRs may move between categories.
Outgoing emails sent by GNATS itself may be configured to have a Subject header field that refers to the PR in question:
Subject: Re: PR category/gnats-id: original message subject
This makes it extremely easy to follow up on a PR by replying to such an
email, see The dbconfig file and the sample,
default dbconfig file installed by mkdb.
Obtain information from the database by using the program
query-pr. query-pr uses search parameters you provide
to find matching Problem Reports in the database. You can invoke
query-pr from the shell or from within Emacs. query-pr
uses the same arguments whether it is invoked from the shell or from
Emacs.
PRs may be selected via the use of the --expr option, directly by
number, or by the use of the (now deprecated) field-specific query
operators.
By default, query options are connected with a logical AND. For example,
query-pr --category=foo --responsible=bar
only prints PRs which have a Category field of foo and a Responsible field of bar.
The --or option may be used to connect query options with a logical
OR. For example,
query-pr --category=baz --or --responsible=blee
prints PRs which have either a Category field of baz or a Responsible field of blee.
It should be emphasized, however, that the use of these field-specific
options is strongly discouraged, since they exist only for compatibility
with older versions of gnats and are likely to be deleted in the next
release. The expressions specified by the --expr option are much more
flexible (see below).
query-prFrom the shell, simply type query-pr, followed by any search
parameters you wish to exercise. From Emacs, type M-x query-pr. query-pr prompts you for search parameters in the
minibuffer.
query-pr can also be accessed by electronic mail, if your version
of gnats is configured for this. To use this feature, simply send
mail to the address query-pr@your-site with command
line arguments or options in the Subject line of the mail header.
gnats replies to your mail with the results of your query. The
default settings for the query-pr mail server are
--restricted --state="open|analyzed|feedback|suspended"
To override the --state parameter, specify
--state=state in the Subject line of the mail
header. You can not query on confidential Problem Reports by mail.
The usage for query-pr is:
query-pr [--debug | -D] [--help | -h] [--version | -V]
[--output file | -o file] [--list-databases]
[--list-fields] [--list-input-fields]
[--responsible-address name] [--field-type field]
[--field-description field]
[--field-flags field]
[--adm-field field] [--adm-subfield subfield]
[--adm-key key]
[--valid-values field]
[--format format | -f format]
[--full | -F] [--summary | -q]
[--database database | -d database] [--and | -&]
[--or | -|] [--expr expr] [PR Number]
Non-network-mode options:
[--print-sh-vars] [--print-directory-for-database]
Network-mode-only options:
[--host host | -H host] [--port port]
[--user user | -v user] [--passwd passwd | -w passwd]
[--print-server-addr]
Deprecated Options:
[--list-categories | -j] [--list-states | -T]
[--list-responsible | -k] [--list-submitters | -l]
[--category category | -c category]
[--synopsis synopsis | -y synopsis]
[--confidential confidential | -C confidential]
[--multitext multitext | -m multitext]
[--originator originator | -O originator]
[--release release | -A release]
[--class class | -L class] [--cases cases | -E cases]
[--quarter quarter | -Q quarter]
[--keywords keywords | -K keywords]
[--priority priority | -p priority]
[--responsible responsible | -r responsible]
[--restricted | -R] [--severity severity | -e severity]
[--skip-closed | -x] [--sql | -i] [--sql2 | -I]
[--state state | -s state]
[--submitter submitter | -S submitter]
[--text text | -t text]
[--required-before date | -u date]
[--required-after date | -U date]
[--arrived-before date | -b date]
[--arrived-after date | -a date]
[--modified-before date | -B date]
[--modified-after date | -M date]
[--closed-before date | -z date]
[--closed-after date | -Z date]
The options have the following meaning:
--help, -h--version, -V--output file, -o file--database database, -d databaseGNATSDB environment
variable; see Environment for more
information.)
--list-categories, -j--list-states, -T--list-responsible, -k--list-submitters, -lThe previous –list-* options are deprecated and may be removed in future releases of gnats; their functionality can be replaced with
query-pr --valid-values field
where field is one of Category, Class,
Responsible, Submitter-Id, or State.
--list-databases--list-fields--list-input-fields--field-type field--field-description field--field-flags fieldtextsearch and
readonly. See Individual field configuration.
--adm-field field--adm-key option, this returns a record
from the administrative file (if any) associated with the field. For
more material on administrative files, see Enumerated field administrative files.
--adm-subfield subfield--adm-field and --adm-key options,
this returns the contents of a particular subfield from the record
specified by --adm-field and --adm-key. Subfields are
treated in Enumerated field administrative files.
--adm-key key--adm-field to select a record from the
administrative file associated with the field specified by
--adm-field. See Enumerated field administrative files.
--valid-values field--responsible-address name--print-sh-varsGNATSDBGNATSDB_VALIDGNATSDBDIRDEBUG_MODEDEFAULTCATEGORYDEFAULTSTATE--print-server-addrGNATSDB environment variable. This option
works only in the network mode.
--print-directory-for-database--format format, -f format--full, -F query-pr --format full
--summary, -q query-pr --format summary
--debug, -D--host host, -H hostGNATSDB environment variable.
--port portGNATSDB environment variable.
--user user, -v userGNATSDB environment
variable.
--passwd passwd, -w passwdGNATSDB environment
variable.
--and, -&, --or, -|--expr exprThe remaining deprecated options are not described here, since their use
is fairly obvious and their functionality is completely replaced by the
use of the --expr option.
query-pr outputPrinting formats for PRs are in one of three forms:
The first three are the ones most commonly used when performing queries. standard is the format used by default if no other format is specified.
Use of the latter two are discouraged; they are merely kept for
historical purposes. Other named formats may have been added by the
database administrator.
%[positionalspecifiers]s: Prints the field as a string. The
positional specifiers are similar to those of printf, as +, - and digit
qualifiers can be used to force a particular alignment of the field
contents.
%[positionalspecifiers]S: Similar to %s, except that the
field contents are terminated at the first space character.
%[positionalspecifiers]d: Similar to %s, except that the
field contents are written as a numeric value. For integer fields, the
value is written as a number. For enumerated fields, the field is
converted into a numeric equivalent (i.e. if the field can have two
possible values, the result will be either 1 or 2). For date fields,
the value is written as seconds since Jan 1, 1970.
%F: The field is written as it would appear within a PR, complete
with field header.
%D: For date fields, the date is written in a standard gnats
format.
%Q: For date fields, the date is written in an arbitrary "SQL"
format.
An example formatted query looks as follows (note that the whole format specification should be quoted):
query-pr --format '"%s, %s" Synopsis State'
Query expressions are used to select specific PRs based on their field contents. The general form is
fieldname|"value" operator fieldname|"value" [booleanop ...]
value is a literal string or regular expression; it must be surrounded by double quotes, otherwise it is interpreted as a fieldname.
fieldname is the name of a field in the PR.
operator is one of:
=~==The equality of two values depends on what type of data is stored in the field(s) being queried. For example, when querying a field containing integer values, literal strings are interpreted as integers. The query expression
Number == "0123"
is identical to
Number == "123"
as the leading zero is ignored. If the values were treated as strings
instead of integers, then the two comparisons would return different
results.
!=<,>booleanop is either | (logical or), or & (logical and). The query expression
Category="baz" | Responsible="blee"
selects all PRs with a Category field of baz or a Responsible field of blee.
The not operator ! may be used to negate a test:
! Category="foo"
searches for PRs where the category is not equal to the regular expression foo.
Parentheses may be used to force a particular interpretation of the expression:
!(Category="foo" & Submitter-Id="blaz")
skips PRs where the Category field is equal to foo and the Submitter-Id field is equal to blaz. Parentheses may be nested to any arbitrary depth.
Fieldnames can be specified in several ways. The simplest and most obvious is just a name:
Category="foo"
which checks the value of the category field for the value foo.
A fieldname qualifier may be prepended to the name of the field; a colon is used to separate the qualifier from the name. To refer directly to a builtin field name:
builtin:Number="123"
In this case, Number is interpreted as the builtin name of the
field to
check. (This is useful if the fields have been renamed. For further
discussion of builtin field names, see The dbconfig file.
To scan all fields of a particular type, the fieldtype qualifier may be used:
fieldtype:Text="bar"
This searches all text fields for the regular expression bar.
Note that it is not required that the right-hand side of the expression be a literal string. To query all PRs where the PR has been modified since it was closed, the expression
Last-Modified != Closed-Date
will work; for each PR, it compares the value of its Last-Modified field against its Closed-Date field, and returns those PRs where the values differ. However, this query will also return all PRs with empty Last-Modified or Closed-Date fields. To further narrow the search:
Last-Modified != Closed-Date & Last-Modified != "" & Closed-Date != ""
In general, comparing fields of two different types (an integer field against a date field, for example) will probably not do what you want.
Also, a field specifier may be followed by the name of a subfield in braces:
State[type] != "closed"
or even
builtin:State[type] != "closed"
Subfields are further discussed in The dbconfig file.
query-pr --expr 'Category~"rats" & State~"analyzed"
& Responsible~"fred"'
yields all PRs in the database which contain the field values:
>Category: rats and
>Responsible: fred and
>State: analyzed
The following query:
query-pr --expr 'State~"open|analyzed"'
yields all PRs in the database whose State values match either
open or analyzed (see Querying using regular expressions. This search is useful as a daily report that lists all
Problem Reports which require attention.
The following query:
query-pr --expr 'fieldtype:Text="The quick.*brown fox"'
yields all PRs whose Text fields contain the text The quick followed by brown fox within the same field. See Querying using regular expressions, which also contains further useful examples of query expressions.
Emacs interface to gnats provides basic access to gnats databases, i.e. sending, editing, and querying Problem Reports. It also defines a simple major mode for editing dbconfig files.
This section provides an overview of using gnats with Emacs. It does not describe the use of Emacs itself, for detailed instructions on using Emacs, see Top (GNU Emacs). For installation instructions of the gnats Emacs mode, see Installing utils.
Please note the Emacs interface was completely rewritten between
gnats 3 and gnats 4. It now uses gnatsd,
gnatsd, exclusively for its operations and uses modern Emacs
features like faces. Its features are not complete though, you can
send your suggestions and patches to the appropriate gnats
mailing list, Support.
To view a particular Problem Report, use the command M-x view-pr. It asks for a Problem Report number and displays that Problem Report.
The displayed buffer is put in the view mode, Misc File Ops (GNU Emacs). If you decide to edit the displayed Problem
Report, use the command e (gnats-view-edit-pr).
gnats-view-mode-hookgnats-view-mode is entered.
Querying the database is performed by the M-x query-pr command. The command prompts for the query expression, Query expressions, and displays a buffer with the list of the matching Problem Reports.
The list of the Problem Reports is displayed in the summary query format, Formatting query-pr output. Currently, the display format cannot be changed and it must output each Problem Report's number in the first column.
The Problem Report list buffer is put in the view mode, Misc File Ops (GNU Emacs). You can use most of the standard view mode commands in it. Additionally, the following special commands are available:
gnats-query-view-pr),
Emacs viewing.
gnats-query-edit-pr),
Emacs editing.
gnats-query-reread). The last
performed query is executed again and the buffer is filled with the
new results.
query-pr).
send-pr), Emacs submitting.
gnats-change-database), Emacs and databases.
If the value of the variable gnats-query-reverse-listing is
non-nil, the listing appears in the reversed order, i.e. with
the Problem Reports of the highest number first, in the buffer.
Similarly to other gnats Emacs modes, there is a hook available for the Problem Report list.
gnats-query-mode-hookgnats-query-mode is entered.
You can submit new Problem Reports with the command M-x send-pr. The command puts you to the problem editing buffer, Emacs editing. The buffer is prefilled with the initial report fields and their default values, if defined. You can use the usual Problem Report editing commands, Emacs editing. When you have filled in all the fields, you can send the Problem Report by presing C-c C-c.
If you run M-x send-pr with a prefix argument, it runs the
gnats-change-database command before putting you to the editing
buffer, Emacs and databases.
You can set the following variables to get some fields pre-filled:
To edit a particular Problem Report, use the command M-x edit-pr. It asks for a Problem Report number and puts the given Problem Report in the editing buffer. See Emacs editing buffer, for information how to edit the Problem Report in the buffer and how to submit your changes.
Note you can also start editing of a selected Problem Report directly from within the viewing buffer, Emacs viewing, or the query result buffer, Emacs querying.
When you invoke a Problem Report editing command, the Problem Report
is put into a special editing buffer. The Problem Report is formatted
similarly to the query-pr -F output, Formatting query-pr output. Field identifiers are formatted as
>Field:
with the text of the field following the identifier on the same line for single-line fields or starting on the next line for multi-line fields.
The Problem Report editing mode tries to prevent you from violating the Problem Report format and the constraints put on the possible field values. Generally, you can use usual editing commands, some of them have a slightly modified behavior though. (If you encounter a very strange behavior somewhere, please report it as a bug, Support.)
You can move between fields easily by pressing the TAB
(gnats-next-field) or M-TAB
(gnats-previous-field) keys.
The field tags are read-only and you cannot edit them nor delete them. If you want to “remove” a field, just make its value empty.
Editing a field value depends on the type of the edited field, Field datatypes. For text fields, you can edit the value directly, assuming you preserve the rule about single-line and multi-line values mentioned above.
For enumerated fields, you cannot edit the value directly. You can
choose it from the list of the allowed values, either from the menu
popped up by pressing the middle mouse button or from within
minibuffer by pressing any key on the field's value. If the pressed
key matches any of the allowed field values, that value is put as the
default value after the minibuffer prompt. You can also cycle through
the allowed field values directly in the editing buffer using the
SPACE key. Enumerated field values are marked by a special
face to not confuse you; you must have enabled font lock mode to
benefit from this feature, Font Lock (GNU Emacs).
Some field values can be read-only, you cannot edit them at all.
Once you have edited the Problem Report as needed, you can send it to
the server with the C-c C-c command
(gnats-apply-or-submit). Successful submission is reported by
a message and the buffer modification flag in mode line is cleared.
Then you can either kill the buffer or continue with further
modifications.
gnats-edit-mode-hookgnats-edit-mode is entered.
By default, the Emacs interface connects to the default database, databases file. If you want to connect to another database, use the command M-x gnats-change-database. It will ask you for the database name to use, server and port it can be accessed on, and your login name.
If you want to use the gnatsd command, gnatsd, directly, without connecting to a remote server or the localhost connection port, provide your local file system full path to gnatsd as the server name. Port number does not matter in this case.
If the database requires a password to allow you the access to it, you are prompted for the password the first time you connect to the database. If you provide an invalid password, you cannot connect to the database anymore and you have to run the M-x gnats-change-database command again.
The Emacs interface defines a simple major mode
gnats-dbconfig-mode for editing dbconfig files,
dbconfig file. It defines basic mode attributes like character
syntax and font lock keywords, it does not define any special commands
now.
gnats-dbconfig-mode-hookgnats-dbconfig-mode is entered.
unlock-pr is used.
All the user variables can be customized in the customization group
gnats, Easy customization (GNU Emacs).
See also Where the tools and utilities reside.
There are several steps you need to follow to fully configure and
install gnats on your system. You need root access in order
to create a new account for gnats and to install the gnats
utilities. You may need root access on some systems in order to
set up mail aliases and to allow this new account access to
cron and at.
If you are updating an older version of gnats rather than installing from scratch, see Upgrading from older versions.
gnats installation relies on two other freely available software
packages, which should be installed before you go on to configure and
build gnats. These are gnu make and Texinfo
(version 4.2 or higher). Both are available from the gnu FTP site at
ftp://ftp.gnu.org.
To build and install gnats, you must:
configure, with correct options if the defaults are
unsuitable for your site. See Configuring and compiling the software. Default installation locations are in
Where gnats lives.
mkdb command.
See Setting up the default database.
query-pr, edit-pr, send-pr) on every machine
in your local network. See Installing the user tools.
query-pr, edit-pr and send-pr for their systems.
However, for many sites, setting up a remote access interface to
gnats, such as Gnatsweb is a better solution since this requires
no configuration on the remote side.
tar
file which was compressed using gzip. The code can be extracted
into a directory unpackdir using
cd unpackdir
gunzip gnats-4.1.999.tar.gz
tar xvf gnats-4.1.999.tar
The sources reside in a directory called gnats-4.1.999 when unpacked. We call this the top level of the source directory, or srcdir. The sources for the gnats tools are in the subdirectory gnats-4.1.999/gnats/*. Lists of files included in the distribution are in each directory in the file MANIFEST.
You may wish to alter the installation directory for the Emacs lisp
files. If your Emacs lisp library is not in
prefix/share/emacs/site-lisp, edit the file
srcdir/gnats/Makefile.in. Change the variable
lispdir from prefix/emacs/site-lisp to the
directory containing your Emacs lisp library. For information on
prefix, see prefix.
gnats user. You can actually name this
user whatever you want to, as long as it is a valid username on your
system, but we strongly recommend that you call the user gnats.
If you do decide to give it some other name, remember to use the option
--enable-gnats-user when running configure below. Below, we
will anyway refer to this user by the name gnats.
This user must have an entry in the file /etc/passwd. As for
ordinary users, create a standard home directory for the gnats
user. The default PATH for this user should contain
exec-prefix/bin and
exec-prefix/libexec/gnats. The exec-prefix value
is configurable with the --exec-prefix configure option described
below, but for standard installations, these two directories correspond
to /usr/local/bin and /usr/local/libexec/gnats.
configure. You can nearly always run configure with
the simple command
./configure
and the “Right Thing” happens:
-d databasename or --directory=databasename, or
set the GNATSDB environment variable to point to some other database.
The most common options to configure are listed below:
configure [ --prefix=prefix ]
[ --exec-prefix=exec-prefix ]
[ --enable-gnats-service=service-name ]
[ --enable-gnats-user=username ]
[ --enable-gnatsd-user-access-file=path ]
[ --enable-gnatsd-host-access-file=path ]
[ --enable-gnats-dblist-file=path ]
[ --enable-gnats-default-db=path ]
[ --with-kerberos ] [ --with-krb4 ]
[ --verbose ]
--prefix=prefix--exec-prefix=exec-prefix--enable-gnats-service=service-name--enable-gnats-user=username--enable-gnatsd-user-access-file=path--enable-gnatsd-host-access-file=path--enable-gnats-dblist-file=pathDefault is prefix/etc/gnats/databases.
--enable-gnats-default-db=path-d or --databasename option, and when the
GNATSDB envrionment variable hasn't been set. Default is
/prefix/com/gnatsdb.
--with-kerberos--with-krb4--verboseconfigure runs.
configure supports several more options which allow you to
specify in great detail where files are installed. For a complete list
of options, run ./configure --help in the source directory.
You can build gnats in a different directory (objdir) from the
source code by calling the configure program from the new
directory, as in
mkdir objdir
cd objdir
srcdir/configure ...
By default, make compiles the programs in the same directory
as the sources (srcdir).
make, then run
make all info
from the directory where configure created a Makefile
(this is objdir if you used it, otherwise srcdir.) These
targets indicate:
allinfomakeinfo.
The following steps are necessary for a complete installation. You may
need root access for these.
make install install-info
These targets indicate:
installinstall-infoAfter you have installed gnats, you can remove the object files with
make clean
Place the following lines in the file default.el in your Emacs lisp library, or instruct your local responsible parties to place the lines in their .emacs:
(autoload 'send-pr "gnats"
"Command to create and send a problem report." t)
(autoload 'edit-pr "gnats"
"Command to edit a problem report." t)
(autoload 'view-pr "gnats"
"Command to view a problem report." t)
(autoload 'query-pr "gnats"
"Command to query information about problem reports." t)
(autoload 'unlock-pr "gnats"
"Unlock a problem report." t)
(autoload 'gnats-dbconfig-mode "gnats"
"Major mode for editing the `dbconfig' GNATS configuration file." t)
(add-to-list 'auto-mode-alist '("\\<dbconfig$" . gnats-dbconfig-mode))
send-pr tool to submit problem reports, you
need to create a configuration file for send-pr on the server.
See The send-pr.conf configuration file.
For the following steps, log in as the user gnats.
We are now going to initialize the default gnats database. Run the following command:
mkdb default
This creates a database named default, with all its data stored
below the directory prefix/com/gnatsdb, in a default
installation this corresponds to /usr/local/com/gnatsdb. If
you specified the --enable-gnats-default-db option when running
configure, the default database will be created under the directory you
specified instead. mkdb creates the database directory itself,
together with three different subdirectories2:
file-pr.
The next configuration step is to edit the default files copied to the
database's gnats-adm directory by mkdb.
The default dbconfig file installed by mkdb provides a
good basis for many gnats databases. The default file causes
similar behaviour to the 3.x versions of gnats. However, even if
this might be precisely what you want, you should still go through the
file and check that the default settings suit your needs.
See The dbconfig file.
Then edit the files categories, responsible, and submitters in the gnats-adm directory (see Other database-specific config files) to reflect your local needs. For special configurations, you may also have to edit the states and classes files.
If you used the --enable-gnats-default-db option in the pre-build
configure to change the location of the default database, you need to
edit the databases config file, see The databases file. This file is by default located in the
prefix/etc/gnats directory, but may have been changed
by the option --enable-gnats-dblist-file option during configure.
Allow the new user gnats access to cron and at. To
do this, add the name gnats to the files cron.allow and
at.allow, which normally reside in the directory
/var/spool/cron. If these files do not exist, make sure
gnats does not appear in either of the files cron.deny
and at.deny (in the same directory). If you changed the name
of the gnats user during configure, remember to substitute as
appropriate in the previous steps.
Create a crontab entry that periodically runs the program
queue-pr with the --run option
(see queue-pr). For example, to run
queue-pr --run every ten minutes, create a file called
.mycron in the home directory of the user gnats which
contains the line:
0,10,20,30,40,50 * * * * exec-prefix/libexec/gnats/queue-pr --run
(Specify the full path name for queue-pr.) Then run
crontab .mycron
See the man pages for cron and crontab for details
on using cron.
The following mail aliases must be added on the machine where the gnats server is installed. The instructions below are for Sendmail or Sendmail-like mail systems. If these instructions don't fit your system, particularly if you do not have an aliases file, ask your mail administrator for advice.
The following aliases should be placed in the file
/etc/aliases. Yoy may need root access to add these
aliases:
gnats-admin: address
bugs: "| exec-prefix/libexec/gnats/queue-pr -q"
This places incoming Problem Reports in
the gnats-queue directory of your database. Remember to
fill in the full path of the queue-pr command as appropriate for
your installation.
bug-q: "| exec-prefix/libexec/gnats/queue-pr -q"
bug-log: /some/path/bugs.log
bugs: bug-q, bug-log
This configuration archives incoming Problem Reports in the file
bug.log, and also feeds them to the program queue-pr.
(Remember, bug.log needs to be world-writable, and should be
pruned regularly; see gnats Administration.) In
order for the log file to protect fully against data loss in case a disk
runs full, try to place it on a different disk volume than the
gnats database.
query-pr: "| exec-prefix/libexec/gnats/mail-query"
The mail-query program uses --restricted to search on the
database, and by default only searches for PRs that aren't closed
(see Querying the database).
By default, the daemon and clients are set to use port 1529. Add the line
support 1529/tcp # GNATS
to your /etc/services file. If you want a different service name, configure gnats with
--enable-gnats-service=servicename
In your inetd.conf file, add the line
support stream tcp nowait gnats /usr/local/libexec/gnats/gnatsd gnatsd
adjusting the path accordingly if you used configure options to make
changes to the defaults. To make inetd start spawning the
gnats daemon when connected on that port, send it a hangup signal
(HUP).
Some operating systems have replaced inetd with the more modern
xinetd. Instead of editing inetd.conf, you should create
the file /etc/xinetd.d/support, containing something like the
following:
service support
{
disable = no
socket_type = stream
protocol = tcp
wait = no
user = gnats
server = /usr/local/libexec/gnats/gnatsd
}
If you specified a different service name when running configure,
you need to give the file the same name as the service name, and you
need to adjust the service line above. If the --prefix or
--exec-prefix options were passed to configure, adjust the
server line above, and if you used the --enable-gnats-user
option, adjust the user line.
Then restart xinetd to make the new configuration current.
If you use an Internet superserver different from inetd or xinetd, please refer to its documentation for information how to configure it.
At this point, you will probably want to set the access permissions of the different hosts that are going to be accessing your databases. The access permissions can currently only be set on a global scale (that is, across all the databases on a gnats server). The location and name of the global host access configuration file can be set during the pre-build configure as shown above, but by default the file is /usr/local/etc/gnats/gnatsd_host.access. It lists the hosts allowed to access your server, and what their default access levels are. Each line in the file denotes one server, or one part of a network domain. There are three fields on each line, but only two are currently used. To grant all hosts from the domain site.com edit access, use this line:
site.com:edit
If you run a gnats web interface or similar tool on the same machine as the server is running on, you probably want to grant localhost edit access:
localhost:edit
If you are using Kerberos, the gnatsd_host.access file shows the sites that don't require Kerberos authentication.
The third field might in the future be used for things like controlling what categories, submitter-id's PRs, etc., can be accessed from that site. Access attempts that are denied are logged to the syslog messages file (/var/adm/messages on many systems).
When you install the gnats utilities, the user tools
send-pr, query-pr and edit-pr are installed on the
server machine. If your machine is part of a network, however, you may
wish to install the user tools on each machine in the network so that
responsible parties on those machines can submit new Problem Reports,
query the database, and edit existing PRs. In the following discussion,
machines with the gnats user tools installed are referred to as
client machines. In general, there are three distinct types of
client that a gnats server may have to cater for:
Each type of client requires a different approach when it comes to providing access.
If all the machines involved reside on the same local network as the gnats server, you can simply share out the directories on the server that contain the user tools, by default /usr/local/bin and the directory which contains the send-pr.conf configuration file (see The send-pr.conf configuration file), by default /usr/local/etc/gnats. If you have a heterogeneous environment, i.e. hosts running different operating systems, you need to create several shared gnats installations, one for each platform. The send-pr.conf file is platform-independent, though.
In order to submit a new PR, send-pr would then be invoked as
follows on the client machines:
send-pr -d hostname:port:database:username:password
Or by first setting the environment variable GNATSDB as follows
(the exact syntax will vary depending on what shell you use):
export GNATSDB=hostname:port:database:username:password
Then, send-pr can simply be invoked without any options.
The other tools, query-pr and edit-pr, work in similar
ways, honoring the -d option as well as the GNATSDB
environment variable. See GNATS user tools.
When client machines reside on the general Internet, both security and practical considerations may make it impossible to provide a shared installation of the gnats tools. In this case, you may choose to only provide access through a web interface such as Gnatsweb. For clients that need the gnats tools, the following needs to be carried out on the remote machines:
send-pr on the client machine
You should unpack the distribution and run configure on the
client machine in the same way as described in Configuring and compiling the software. Note, however, that you
do not need to create a gnats user on the client and you should
not use the make all info command to build. Instead, issue the
following commands from the top level directory of the source
distribution:
cd gnats
make install-tools
cd ../send-pr
make all install
This builds and installs the send-pr, query-pr and
edit-pr tools on the client machine. You should now configure
send-pr by editing the send-pr.conf file
(see The send-pr.conf configuration file.)
Users on the client machine can now either use the send-pr syntax or the
GNATSDBenvironment variable described in the previous section.
For sites that need to submit Problem Reports by having send-pr send
e-mail instead of speaking directly over the network to the gnats
server, you need to create a problem report template on the gnats
server and have that template copied to a suitable location on the
client machine (any filename and any location will do, as long as
send-pr on the client machine can read the file). On the
gnats server, use the command
send-pr -p > filename
The file filename now contains a PR template for your database.
Copy this file to the client. Then edit the send-pr.conf file
that you created on the client, set the TEMPLATE variable to
point to the template file (see The send-pr.conf configuration file) and make sure that the MAILPROG and
MAILADDR varables in send-pr.conf are correctly set. You
should now have a working remote tool installation.
For clients that have no direct network access to your gnats
server, such as those that are located behind strict firewalls, you
either need to set up a web interface such as Gnatsweb (provided that
the firewall lets web traffic through) or use the procedure above which
sets up send-pr to submit Problem Reports by e-mail. In order to
query PRs, users on the remote machines will then have to use the the
e-mail functionality of query-pr (see Invoking query-pr.
Editing PRs by e-mail is not possible, so clients in this group who need
edit access have to get access through a web interface if possible.
Note that when send-pr is set up to work over e-mail, the
GNATSDB environment variable and the -d command line
option have no effect since send-pr is tied to a specific
database by way of the value of MAILADDR in the
send-pr.conf file.
The following procedure covers an upgrade from all gnats 3 versions newer than 3.108. If your installation is an older 3.10x version, or even the ancient 3.2 version, you need to review the UPGRADING.old file in the gnats distribution before carrying out the steps detailed here.
Although almost all of the gnats internals have been redesigned and
rewritten for gnats 4, little has changed in the format and
structure of the database data. The only change that needs to be taken
into account when upgrading is the fact that the database index format
is binary in a default installation of gnats 4. Thus, you will
need to regenerate your database index by using the gen-index
tool. In addition, if your old gnats installation was so-called
“release-based”, you need to make some simple modifications to the
database setup file dbconfig. See below for details.
Apart from building and installing new binaries, the major changes which impinge on the upgrade procedure are all on the configuration side. The main database configuration file, dbconfig, is far more complex and powerful than the old config file, and while the installation process creates a sensible set of default values which are similar to gnats 3.11x's defaults, you still need to migrate any changes you may have made to your own local configuration.
Another aspect which needs consideration are remote submitter sites.
Such sites either need to be instructed to upgrade their locally
installed copies of the gnats user tools (send-pr,
edit-pr and query-pr), or they should be given access
through interfaces such as Gnatsweb.
Since the gnats network daemon has been completely reworked, with an entirely new command set, all network-based interfaces, such as Gnatsweb and TkGnats need to be upgraded to versions that support gnats 4. The contrib directory of this distribution contains some third-party interfaces, and the README file contains pointers to where you can obtain the newest versions of these tools.
This document only deals with upgrading gnats itself. Third-party tools should have separate upgrading instructions in their distributions.
send-pr, query-pr etc.) The
locations of these may vary, but in a default gnats 3 installation,
the database(s) reside under /usr/local/share/gnats, the
executables are located in /usr/local/libexec/gnats and the
user tools reside in /usr/local/bin.
--enable-gnats-default-db option when running configure,
in order to set the default database to be one of your already existing
gnats 3 databases.
gnatsd. There is one gnatsd.conf for each database. In
gnats 4, these files have been replaced by a single file named
gnatsd.host_access which contains settings that apply across all
the databases on the server. This file is located in the same directory
as the databases file. You need to combine the host access
settings from all your gnats 3 databases and add them to the
gnatsd.host_access file. Note that you are no longer able to
control host access on a per-database basis. Optionally, you may delete
the old gnatsd.conf files. See Controlling access to gnats databases.
--enable-gnats-default-db configure option
got a default dbconfig installed. This default file contains
field definitions etc. which makes this version of gnats behave
almost exactly like older versions. Copy this default file to the
gnats-adm directories of any other gnats databases that
you may have on your host before you proceed to migrate your old
configuration settings.
The following is a list of the configuration directives that may be present in a config file and their counterparts (if any) in gnats 4.
default keyword in these sections. See The dbconfig file.
notify-about-expired-prs setting in the
dbconfig file.
send-submitter-ack setting in the
dbconfig file.
keep-all-received-headers setting in the
dbconfig file.
debug-mode setting in the dbconfig file.
business-day-hours and
business-week-days in the dbconfig file.
After your are done migrating the settings, you may optionally delete the old config files. Since there are many more configuration settings available in the gnats 4 dbconfig file, you should take some time to review them all before proceeding. See The dbconfig file.
If your old gnats installations was release-based, i.e. it included the fields Quarter, Keywords and Date-Required, you need to define those fields in the dbconfig file by following the instructions in Supporting old gnats “release-based” fields.
crypt() and MD5 passwords (see Controlling access to gnats databases). You need to translate your old
gnatsd.user_access files to the new format by using the
gnats-pwconv tool which was installed in the
EXEC-PREFIX/libexec/gnats directory, typically
/usr/local/libexec/gnats. See Managing user passwords.
gnats. Then run the gen-index
command for each of your databases. See Administrative Utilities for details on how to use
gen-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 directoryCategory value that is
unrecognized by the categories file, or if that field is missing,
gnats places the PR in the pending directory
(see Where gnats lives). PRs
submitted in free-form by email will always be filed in the
pending directory. If so configured, gnats sends a
notice to the gnats-admin and to the party responsible for that
submitter (as listed in the submitters file) when this occurs.
To have these "categoryless" PRs filed correctly, you can then use a
gnats tool such as edit-pr to set the correct category of
each PR in the pending directory.
In order to protect yourself from problems caused by full disks, you
should arrange to have all mail that is sent to the gnats database
copied to a log file (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 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 Regenerating the index).
See Where gnats lives.
See Where gnats lives.
gnats has two, well, actually three, different kinds of
configuration file. The site-wide configuration files determine
overall behaviour across all the databases on your machine, while the
database-specific configuration files determine how gnats
behaves when dealing with a specific database. In addition, there is
a single file that needs to be set up for the send-pr tool to
work properly. These files can be edited at any time — the next
time a gnats tool is invoked, the new parameters will take
effect.
These are the site-wide configuration files used by gnats:
databasesdatabases file.
defaultsmkdb.
gnatsd.host_accessgnatsd.user_accessThe database-specific configuration is determined by the following files in the gnats-adm subdirectory of the database directory.
dbconfigdbconfig file.
categoriesCategory field, and the maintainers responsible for each
category. Update this file whenever you have a new category, or
whenever a category is no longer valid. You must also update this file
whenever responsibility for a category changes, or if a maintainer is
no longer valid. See The categories file.
responsibleresponsible file.
submitterssubmitters file.
addressesSubmitter field is not filled in, gnats will use entries in
this file to try to derive the submitter ID from the e-mail headers.
See The addresses file.
statesstates file.
classessw-bug, doc-bug, change-request etc.
See The classes file.
gnatsd.user_accessThe last file in this menagerie is the send-pr configuration
file send-pr.conf. This file contains some defaults that need
to be known in order for send-pr to work. The file needs to
be present on all hosts where send-pr is to be used.
See the send-pr.conf file.
databases fileThe 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 --enable-gnats-dblist-file was used during building
of gnats, the databases file has the name and location given
to this option. A sample databases file is installed together
with gnats.
Note that if you add a new local database, you must create its data
directory, including appropriate subdirectories and administrative
files. This is best done using the mkdb tool, See mkdb.
dbconfig fileThe 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.
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 | falsetrue, 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 | falsetrue, 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 | falsetrue, 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 | falsetrue.
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-endday-start and 17 for day-end.
business-week-days week-start - week-endweek-start and 5 for week-end.
create-category-dirs true | falsetrue, 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 mode0750, yielding
user read, write and execute, and group read and execute. Note that
if you have local users on the gnats server itself, running for
instance query-pr, you may need to change the permissions to
0755.
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:
arrival-dateaudit-trailcategoryclosed-dateconfidentialyes, the PR is confidential
descriptionlast-modifiednumberoriginatorpriorityresponsibleseveritystatesubmitter-idsynopsisunformattedFor these built-in fields, a matching field description must
appear in the dbconfig file. Otherwise, the configuration will
be considered invalid, and errors will be generated from the
gnats clients and gnatsd. We also recommend that you
leave the actual fieldnames of these fields at their default values
(i.e. capitalized versions of their built-in names), since some
clients may depend on these names.
description "description text"--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-onlyBy default, editing is allowed.
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 ... ]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. An
example of this kind of field is the built-in Category field with its
associeted categories administrative file.
filename is the name of a file in the gnats-adm
administrative directory for the database.
The format of the administrative file should be simple ASCII. Subfields within the file are separated with colons (:). Lines beginning with a hash sign (#) are ignored as comments. Records within the file are separated with newlines.
The field option is used to name the subfields in the
administrative file. There must be at least one subfield, which is used
to list the legal values for the field. If the administrative file is
empty (or does not contain any non-empty non-comment lines), the PR
field must be empty.
The key option is used to designate which field in the
administrative file should be used to list the legal values for the PR
field. The value must match one of the field names in the field
option.
If the allow-any-value option is present, the value of the PR
field is not required to appear in the administrative file — any value
will be accepted.
Note that there is no default keyword for
enumerated-in-file. These fields get their default value from
the first entry in the associated administrative file.
multi-enumerated-in-file { path "filename" fields { "name" [ "name" ... ] } key "name" [ default "string" ] [ allow-any-value ] [ separators "string" ]}multi-enumerated-in-file is to multienum what
enumerated-in-file is to enum. Its options have the
same meaning as their counterparts in the multienum and
enumerated-in-file fields.
NOTE: Keywords may appear in any sequence, with one exception –
the separators keyword, if present, has to come last. This rule
only applies to fields of type multi-enumerated-in-file.
datedate 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.
The on-change subsection of a fields section specifies one
or more actions to be performed when the field value is edited by the
user. It has the general form
on-change [ "query-expression" ] {
[ add-audit-trail ]
[ audit-trail-format {
format "formatstring"
[ fields { "fieldname" ... } ]
} ]
[ require-change-reason ]
[ set-field | append-to-field "fieldname" {
"format-string" [ fieldlist ]
} ]
[ require { "fieldname" ... } ]
}
The optional query-expression controls whether or not the actions
in the on-change section are taken. If the expression fails to
match, the actions are skipped.
The add-audit-trail option indicates that an entry should be
appended to the PR's audit-trail when this field is changed. The format
of the entry is controlled by the optional audit-trail-format
section within the field, or by the global audit-trail-format
section. See Audit-trail formats and Outgoing email formats.
The require-change-reason option specifies that a change reason
must be present in the PR when this field is edited. This option only
makes sense if an audit-trail entry is required, as the change reason is
otherwise unused.
The set-field and append-to-field options are used to
change the value of the field fieldname in the PR. The supplied
format is used to format the value that will be placed in the field.
append-to-field appends the resulting formatted string to the
existing, while set-field completely replaces the contents.
Any field may be edited by the set-field or
append-to-field option (the read-only option on a field is
ignored). However, the changes are subject to the usual field content
checks.
The require option specifies that one or more fields must have
a (non-blank) value when this field is changed.
A field may be enforced to have a (non-blank) value at all times by including it in the set of fields required for the initial PR, see Initial PR input fields, as well as in the set of fields required on change of the field itself.
There is also a global on-change section that is executed once
for each PR edit. A typical use for such a section is to set the
last-modified date of the PR.
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 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.
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$EditUserEmailAddrEDITADDR gnatsd command or from the responsible
file; if not available, user's local address is used.
$CurrentDate$ChangeReasonThese parameters may be used anywhere a fieldname can appear.
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-submittersend-submitter-ack in the overall database configuration is set
to true.
initial-pr-notificationinitial-pr-notification-pendingappended-email-responseaudit-maildeleted-pr-mailThe 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$NewAuditTrailaudit-mail$EditUserEmailAddrEDITADDR gnatsd command or from the responsible
file; if not available, user's local address is used.
$OldResponsible$NewAuditTraildeleted-pr-mail$EditUserEmailAddrEDITADDR gnatsd command or from the responsible
file; if not available, user's local address is used.
$PRNumThe 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.
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.
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. An optional require parameter can be
defined to specify a subset of the intial-entry fields which must
be assigned a value upon initial creation of the PR.
The general format for the initial-entry section is
initial-entry {
fields { "fieldname" [ "fieldname" ... ] }
[ require { "fieldname" [ "fieldname" ... ] } ]
}
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 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 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 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 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 Configuring and compiling the software).
responsible fileThis 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
Responsible field.
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.
submitters fileThis 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 Overall database configuration, gnats will use
this field to schedule when it should notify the gnats-admin,
responsible person and submitter contact that the PR wasn't analyzed
within the agreed response time. Business hours and business-week
days are set in the 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.
states fileThis file lists the possible states for Problem Reports. Each entry has up to three fields, separated by colons. Lines beginning with # will be ignored.
state:type:description
The concept of the type of a state recognizes that there may for instance be several possible states for a Problem Report which effectively means that the PR is closed and that there may be certain actions that need to be taken when a PR reaches a “closed state”. The problem may have been resolved, it might have been decided that the problem is unsolvable or simply that it won't be solved. Some organizations may for instance wish to consider the “suspended” state as a state of type “closed”.
Currently, the only defined state types are “open” and “closed”, the “open” type isn't currently used for anything while the “closed” type is only used to control the Closed-Date field of PRs. Changing the state of a PR to any state of type “closed” will set the Closed-Date field with a time stamp and changing the state of a PR from one “closed” state to another will leave the Closed-Date field as it was. Changing the state of a PR from any state of type “closed” to a non-closed state will clear the Closed-Date field.
The --skip-closed option of query-pr refers to all
states of type “closed”, not to a specific state name of “closed”.
The first state listed will be the state automatically assigned to Problem Reports when they arrive; by default this is named “open”. The last state listed is the end state for Problem Reports — one should usually assume that a PR in this state is not being actively worked on; by default this state is named “closed”. Even if a different name has been chosen for this state, gnats will force this state to be of type “closed”.
It is recommended that you keep the default names of “open” and “closed” for the first and last states respectively, since there may be external tools that depend on these names.
addresses fileThis 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.
classes fileThis 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.
This file contains some default values that need to be known in order
for send-pr to work properly. This file needs to be copied to
all hosts where send-pr will be used.
If gnats was built with default options, the send-pr.conf
file should be placed in the /usr/local/etc/gnats directory.
However, if the option --sysconfdir was used during building of
gnats, the send-pr.conf file resides at the location
given to this option.
Entries in this file are on the format
variable=value
The valid variables are:
SUBMITTERsend-pr is invoked.
DEFAULT_RELEASEDEFAULT_ORGANIZATIONMAILPROGsend-pr can be set up
to submit Problem Reports by e-mail. This is done by setting the
MAILPROG variable to point to a mailer such as Sendmail. If
MAILPROG needs to have the address that the mail is being sent
to specified on the command line, it should be specified here as well
(for example, MAILPROG=''mail bugs@foo.bar.com'' should work).
If Sendmail is used, use MAILPROG=''/usr/lib/sendmail -oi
-t''. See also MAILADDR and TEMPLATE below.
MAILADDRTEMPLATEsend-pr communicates directly over the network
with the gnats server to determine what fields to include in a
correctly formatted Problem Report so that it can present the user
with a template. If the gnats server can't be reached directly
over the network, a template must be provided. Set the
TEMPLATE variable to point to a template file created on the
gnats server by using the command send-pr -p.
See Installing the user tools.
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.
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 Index file description.
Should the index file become corrupted, the gen-index
utility can be used to regenerate it. See Regenerating the index.
current fileThis file contains the last serial number assigned to an incoming PR. It is used internally by gnats; you need never touch this file.
These tools are used by the gnats administrator as part of the periodic maintenance and configuration of gnats. See gnats Administration.
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.
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.
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.
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 Index file description). The results are printed to
standard output. The options are:
-n--numeric-d databasename--database=databasenamegen-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--helpgen-index.
-V--versiongen-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 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.
Older versions of gnats, up to and including version 3.x, stored
user passwords in plaintext in the gnatsd.user_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 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.
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.
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 Installing gnats.
The usage for queue-pr is as follows:
queue-pr [ -q | --queue ] [ -r | --run ]
[ -f filename | --file=filename ]
[ -m kbytes | --max-size=kbytes ]
[ -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-r--runfile-pr one by one.
-f filename--file=filename-m kbytes--max-size=kbytes-d databasename--directory=databasenamedefault).
-h--helpgen-index.
-V--versiongen-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 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 The categories file) and the person
responsible for the submitter site where the PR originated
(see 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 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=databasenamedefault).
-h--helpfile-pr.
-V--versionfile-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
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 The submitters file). The time is determined in business hours, which are
defined in the database's dbconfig file (see 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.
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 [ --show-prnum ] ]
[ -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 user3. 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--show-prnum--submit option to display the PR
number associated with the submitted PR.
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=reasonPR numberPR 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=databasedefault). 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--helppr-edit.
-V--versionpr-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--debugdiff-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.
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).
We use a few conventions when referring to the installation structure gnats uses. These values are adjustable when you build and install gnats (see Installing gnats).
prefix corresponds to the variable prefix for
configure, which passes it on to the Makefile it creates.
prefix sets the root installation directory for
host-independent files as follows:
man pagesinfo documentsinclude filesThe default value for prefix is /usr/local, which can
be changed on the command line to configure using
configure --prefix=prefix ...
See Configuring and compiling the software.
exec-prefix corresponds to the variable exec-prefix for
configure, which passes it on to the Makefile it creates.
exec-prefix sets the root installation for
host-dependent files as follows:
configure supports several more options which allow you to
specify in great detail where different files are installed. The
locations given in this appendix do not take into account highly
customized installations, but fairly ordinary gnats installations
should be covered by the material here. For a complete list of options
accepted by configure, run ./configure --help in the
gnats subdirectory of the distribution.
Since most installations are not intended to be distributed around a network, the default value for exec-prefix is the value of prefix, i.e., /usr/local. However, using exec-prefix saves space when you are installing a package on several different platforms for which many files are identical; rather than duplicate them for each host, these files can be shared in a common repository, and you can use symbolic links on each host to find the host-dependent files.
Use exec-prefix in conjunction with prefix to share
host-independent files, like libraries and info documents. For
example:
for each host:
configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-host
make all install ...
Using this paradigm, all host-dependent binary files are installed into /usr/gnu/H-host/bin, while files which do not depend on the host type for which they were configured are installed into /usr/gnu.
You can then use a different symbolic link for /usr/gnu on each host (/usr is usually specific to a particular machine; it is always specific to a particular architecture).
on host-1:
ln -s /usr/gnu/H-host-1 /usr/gnu
on host-2:
ln -s /usr/gnu/H-host-2 /usr/gnu
To the end user, then, placing /usr/gnu/bin in her or his
PATH simply works transparently for each host type.
You can change exec-prefix on the command line to
configure using
configure --exec-prefix=exec-prefix ...
We recommend that you consult Using configure (Cygnus configure), before attempting this.
Each gnats database located on a server has its own directory, as
listed in the databases (see The databases file and given when the mkdb utility is invoked
to initialize the database (see Initializing a new database).
This directory has several subdirectories, one of which is named
gnats-adm. This directory contains all configuration files
related to this specific database, including the categories,
submitters, responsible, states, classes,
dbconfig, addresses, states and
gnatsd.user_access, as well as two
files generated and maintained by gnats, index and
current.
configure
(see Configuring and compiling the software).
configure
(see Configuring and compiling the software).
gnats installs tools, utilities, and files into the following locations.
/binsend-predit-prquery-pr/libexec/gnatsat-prcheck-dbdelete-prpr-edit instead (see The edit-pr driver).
diff-prsdiff-prs tool.
file-prgen-indexgnatsdgnats-pwconvmail-querymkcatmkdbpr-agepr-age tool.
pr-editqueue-prrmcat/lib/libiberty.alibiberty library.
/etc/gnats/share/emacs/site-lispsend-pr, query-pr,
edit-pr, and view-pr. See The gnats user tools. To change this directory you must change the
lispdir variable in Makefile.in; see Configuring and compiling the software.
/infoinfo (the gnu
hypertext browser). See Reading GNU Online Documentation (GNU Online Documentation).
/man/man1/man/man8man pages for all the gnats tools and utilities.Per-database directoryexist here.
See Other database-specific config files,
Administrative data files and Controlling access to databases.
gnatsdThis section describes in details how the gnats network daemon works. This information is mainly assumed to be useful for developers of gnats client software.
gnatsd
The gnatsd network daemon is used to service remote gnats
requests such as querying PRs, PR creation, deletion, and editing, and
miscellaneous database queries. It uses a simple ASCII-based command
protocol (similar to SMTP or POP3) for communicating with remote
clients.
It also provides a security model based either on IP-based
authentication (generally considered very weak) or username/passwords,
where passwords may be in cleartext, UNIX crypt or MD5 hash format.
Access through gnatsd is granted according to certain predefined
access levels. Access levels are further discussed in Controlling access to databases. It should be emphasized that
security has not been a focus of development until now, but future
versions are expected to address this more thoroughly.
All of the gnats clients are capable of communicating via the gnats remote protocol to perform their functions.
gnatsd is usually started from the inetd facility and should run as
the gnats user (the actual username of this user is configurable
during installation, see Configuring and compiling the software for details.)
gnatsd optionsThe daemon supports the following command-line options:
gnatsd [--database database | -d database]
[--not-inetd | -n] [--max-access-level level | -m level]
[--version | -V] [--help | -h]
-V, --version-h, --help-d, --databasegnatsd. (The selected database may be changed via
the CHDB command; the name set with this option is simply the
default if no CHDB command is issued.) If no database is
specified, the database named default is assumed. This option overrides
the database specified in the GNATSDB environment variable.
-n, --not-inetdgnatsd is not being invoked
from inetd. This can be used when testing gnatsd, or if it is
being run via ssh or some other mechanism.
This has the effect of using the local hostname where gnatsd is
being invoked for authentication purposes, rather than the remote
address of the connecting client.
--max-access-level, -mgnatsd command protocol
Commands are issued to gnatsd as one or more words followed by a
carriage-return/linefeed pair. For example, the CHDB (change
database) command is sent as CHDB database<CR><LF> (the
CRLF will not be explicitly written for future examples.)
Replies from gnatsd are returned as one or more response lines
containing a 3-digit numeric code followed by a human-readable string;
the line is terminated with a <CR><LF> pair. For example, one
possible response to the CHDB command above would be:
210 Now accessing GNATS database 'database'.
The three-digit code is normally followed by a single ASCII space (character 0x20). However, if additional response lines are to be returned from the server, there will be a single dash - instead of the space character after the three-digit code.
Response code values are divided into ranges. The first digit reflects the general type of response (such as ”successful” or ”error”), and the subsequent digits identify the specific type of response.
CODE_OK) is used as the positive result code for most
simple commands.
Commands that expect additional data from the client (such as
SUBM or VFLD) use a two-step mechanism for sending the
data. The server will respond to the initial command with either a 211
(CODE_SEND_PR) or 212 (CODE_SEND_TEXT) response line, or
an error code if an error occurred with the initial command. The client
is then expected to send the remaining data using the same quoting
mechanism as described for server responses in the 300-349 range. The
server will then send a final response line to the command.
Codes in the 300-349 range are followed by a series of
CRLF-terminated lines containing the command response, usually a
PR. The final line of the result is a single period .. Result
lines that begin with a period have an extra period prepended to them.
Codes in the 350-399 range use a different scheme for sending their responses. The three-digit numeric code will be followed by either a dash - or a single space. If the code is followed by a dash, that indicates that another response line will follow. The final line of the response has a single space after the three-digit code.
In previous versions of the protocol the first line of a
CODE_INFORMATION (310) response was to be ignored. This is no
longer the case. Instead, any lines marked with code
CODE_INFORMATION_FILLER (351) are to be ignored. This allows the
server to transmit additional headers or other human-readable text that
can be safely ignored by the clients.
Multiple error messages may be returned from a command; in this case the
- continuation character is used on all but the last response
line.
gnatsd commands
Note that the set of gnats commands and their responses is somewhat
inconsistent and is very much in flux. At present the gnats
clients are rather simple-minded and not very strict about processing
responses. For example, if the server were to issue a code 300
(CODE_PR_READY) response to a CHDB command, the client
would happily expect to see a PR appear (and would print it out if one
was sent).
It is thus suggested that any clients that use the gnats protocol be equally flexible about the way received responses are handled; in particular, only the first digit of the response code should be assumed to be meaningful, although subsequent digits are needed in some cases (codes 300-399). No attempt should be made to parse the message strings on error response lines; they are only intended to be read by humans, and will be changed on a regular basis.
Almost every command may result in the response 440
(CODE_CMD_ERROR). This indicates that there was a problem with
the command arguments, usually because of insufficient or too many
arguments being specified.
Access to most gnatsd commands requires a certain access
level. For details of this, see Privileged gnatsd commands.
USER [userid password]The possible server responses are:
350 (CODE_INFORMATION)
The current access level is specified.
422 (CODE_NO_ACCESS)
A matching username and password could not be found.
200 (CODE_OK)
A matching username and password was found, and the login was
successful.
QUIT201 (CODE_CLOSING)
Normal exit.
The QUIT command has the dubious distinction of being the only command
that cannot fail.
LIST list typePossible values for list type include
Categories
Describes the legal categories for the database.
Submitters
Describes the set of submitters for the database.
Responsible
Lists the names in the responsible administrative file, including
their full names and email addresses.
States
Lists the states listed in the state administrative file, including
the state type (usually blank for most states; the closed state has a
special type).
FieldNames
Lists the entire set of PR fields.
InitialInputFields
Lists the fields that should be present when a PR is
initially entered.
InitialRequiredFields
Lists fields that have to be present and nonempty when a PR
is initially entered (fields containing only blank characters such as
spaces or newlines are considered empty.)
Databases
Lists the set of databases.
The possible responses are:
301 (CODE_TEXT_READY)
Normal response, followed by the records making up the list as
described above.
416 (CODE_INVALID_LIST)
The requested list does not exist.
FTYP field [field ...]Text
A plain text field, containing exactly one line.
MultiText
A text field possibly containing multiple lines of text.
Enum
An enumerated data field; the value is restricted to one entry out of
a list of values associated with the field.
MultiEnum
The field contains one or more enumerated values. Values are
separated with spaces or colons :.
Integer
The field contains an integer value, possibly signed.
Date
The field contains a date.
TextWithRegex
The value in the field must match one or more regular expressions
associated with the field.
The possible responses are:
350 (CODE_INFORMATION)
The normal response; the supplied text is the data type.
410 (CODE_INVALID_FIELD_NAME)
The specified field does not exist.
If multiple field names were given, multiple response lines will be
sent, one for each field, using the standard continuation protocol; each
response except the last will have a dash - immedately after the
response code.
FTYPINFO field property350 (CODE_INFORMATION)
A proper MultiEnum field was specified and the returned text is
the string of separators specified for the field in the dbconfig file
(see Field datatypes) quoted in ''s.
435 (CODE_INVALID_FTYPE_PROPERTY)
The separators property is not defined for this field, i.e. the
specified field is not of type MultiEnum.
Currently, specifying a different property than separators
results in return code 435 as above.
FDSC field [field ... ]350 (CODE_INFORMATION)
The normal response; the supplied text is the field description.
410 (CODE_INVALID_FIELD_NAME)
The specified field does not exist.
Like the FVLD command, the standard continuation protocol will be
used if multiple fields were specified with the command.
FIELDFLAGS field [field ... ]410 (CODE_INVALID_FIELD_NAME)
meaning that the specified field is invalid or nonexistent, or
350 (CODE_INFORMATION)
which contains the set of flags for the field. The flags may be
blank, which indicate that no special flags have been set for this
field.
Like the FDSC and FTYP commands, multiple field names may
be listed with the command, and a response line will be returned for
each one in the order that the fields appear on the command line.
The flags include:
textsearch
The field will be searched when a text field search is requested.
allowAnyValue
For fields that contain enumerated values, any legal value may be used
in the field, not just ones that appear in the enumerated list.
requireChangeReason
If the field is edited, a reason for the change must be supplied in
the new PR text describing the reason for the change. The reason must be
supplied as a multitext PR field in the new PR whose name is
field-Changed-Why (where field is the name of the field
being edited).
readonly
The field is read-only, and cannot be edited.
FVLD fieldThe possible responses are:
301 (CODE_TEXT_READY)
The normal response, which is followed by the list of regexps or
strings.
410 (CODE_INVALID_FIELD_NAME)
The specified field does not exist.
VFLD fieldVFLD can be used to validate a given value for a field in the
database. The client issues the VFLD command with the name of
the field to validate as an argument. The server will either respond
with 212 (CODE_SEND_TEXT), or 410
(CODE_INVALID_FIELD_NAME) if the specified field does not exist.
Once the 212 response is received from the server, the client
should then send the line(s) of text to be validated, using the normal
quoting mechanism described for PRs. The final line of text is followed
by a line containing a single period, again as when sending PR text.
The server will then either respond with 210 (CODE_OK),
indicating that the text is acceptable, or one or more error codes
describing the problems with the field contents.
INPUTDEFAULT field [field ... ]410
(CODE_INVALID_FIELD_NAME), meaning that the specified field is invalid
or nonexistent, or 350 (CODE_INFORMATION) which contains the
default value for the field.
Like the FDSC and FTYP commands, multiple field names may
be listed with the command, and a response line will be returned for
each one in the order that the fields appear on the command line.
RSET200 (CODE_OK)
The state has been reset.
440 (CODE_CMD_ERROR)
One or more arguments were supplied to the command.
6xx (internal error)
There were problems resetting the state (usually because the index could
not be reread). The session will be immediately terminated.
LKDB200 (CODE_OK)
The lock has been established.
440 (CODE_CMD_ERROR)
One or more arguments were supplied to the command.
431 (CODE_GNATS_LOCKED)
The database is already locked, and the lock could not be obtained after
10 seconds.
6xx (internal error)
An internal error occurred, usually because of permission or other
filesystem-related problems. The lock may or may not have been
established.
UNDB200 (CODE_OK)
The lock has been removed.
432 (CODE_GNATS_NOT_LOCKED)
The database was not locked.
440 (CODE_CMD_ERROR)
One or more arguments were supplied to the command.
6xx (internal error)
The database lock could not be removed, usually because of permissions
or other filesystem-related issues.
LOCK PR user [pid]The EDIT command requires that the PR be locked before it may be
successfully executed. However, it does not require that the lock is
owned by the editing session, so the usefulness of the lock is simply as
an advisory measure.
The APPN and REPL commands lock the PR as part of the
editing process, and they do not require that the PR be locked before
they are invoked.
The possible responses are:
440 (CODE_CMD_ERROR)
Insufficient or too many arguments were specified to the command.
300 (CODE_PR_READY)
The lock was successfully obtained; the text of the PR (using the
standard quoting mechanism for PRs) follows.
400 (CODE_NONEXISTENT_PR)
The PR specified does not exist.
430 (CODE_LOCKED_PR)
The PR is already locked by another session.
6xx (internal error)
The PR lock could not be created, usually because of permissions or
other filesystem-related issues.
UNLK PRThe possible responses are:
440 (CODE_CMD_ERROR)
Insufficient or too many arguments were specified to the command.
200 (CODE_OK)
The PR was successfully unlocked.
433 (CODE_PR_NOT_LOCKED)
The PR was not locked.
6xx (internal error)
The PR could not be unlocked, usually because of permission or other
filesystem-related problems.
DELETE PRThe possible responses are:
200 (CODE_OK)
The PR was successfully deleted.
422 (CODE_NO_ACCESS)
The user requesting the delete does not have admin privileges.
430 (CODE_LOCKED_PR)
The PR is locked by another session.
431 (CODE_GNATS_LOCKED)
The database has been locked, and no PRs may be updated until the lock
is cleared.
6xx (internal error)
The PR could not be successfully deleted, usually because of
permission or other filesystem-related problems.
CHEK [initial]VFLD command, it accepts an entire PR at once instead of the
contents of an individual field.
The initial argument indicates that the PR text to be checked is
for a PR that will be newly created, rather than an edit or replacement
of an existing PR.
After the CHEK command is issued, the server will respond with
either a 440 (CODE_CMD_ERROR) response indicating that the
command arguments were incorrect, or a 211 (CODE_SEND_PR)
response code will be sent.
Once the 211 response is received from the server, the client
should send the PR using the normal PR quoting mechanism; the final line
of the PR is then followed by a line containing a single period, as
usual.
The server will then respond with either a 200 (CODE_OK)
response, indicating there were no problems with the supplied text, or
one or more error codes listing the problems with the PR.
EDIT PRLOCK command.
The possible responses are:
431 (CODE_GNATS_LOCKED)
The database has been locked, and no PRs may be updated until the lock
is cleared.
433 (CODE_PR_NOT_LOCKED)
The PR was not previously locked with the LOCK command.
400 (CODE_NONEXISTENT_PR)
The specified PR does not currently exist. The SUBM command
should be used to create new PRs.
211 (CODE_SEND_PR)
The client should now transmit the replacement PR text using the
normal PR quoting mechanism. After the PR has been sent, the server
will respond with either 200 (CODE_OK) indicating that the edit
was successful, or one or more error codes listing problems either with
the replacement PR text or errors encountered while updating the PR file
or index.
EDITADDR addressgnatsd. The command requires at least the edit access
level.
The possible responses are:
200 (CODE_OK)
The address was successfully set.
440 (CODE_CMD_ERROR)
Invalid number of arguments were supplied.
APPN PR fieldREPL PR field201 (CODE_SEND_TEXT)
response; the client should then transmit the new field contents using
the standard PR quoting mechanism. After the server has read the new
contents, it then attempts to make the requested change to the PR.
The possible responses are:
200 (CODE_OK)
The PR field was successfully changed.
400 (CODE_NONEXISTENT_PR)
The PR specified does not exist.
410 (CODE_INVALID_FIELD_NAME)
The specified field does not exist.
402 (CODE_UNREADABLE_PR)
The PR could not be read.
431 (CODE_GNATS_LOCKED)
The database has been locked, and no PRs may be updated until the lock
is cleared.
430 (CODE_LOCKED_PR)
The PR is locked, and may not be altered until the lock is cleared.
413 (CODE_INVALID_FIELD_CONTENTS)
The supplied (or resulting) field contents are not valid for the
field.
6xx (internal error)
An internal error occurred, usually because of permission or other
filesystem-related problems. The PR may or may not have been altered.
SUBMThe possible responses are:
431 (CODE_GNATS_LOCKED)
The database has been locked, and no PRs may be submitted until the
lock is cleared.
211 (CODE_SEND_PR)
The client should now transmit the new PR text using the normal
quoting mechanism. After the PR has been sent, the server will respond
with either 351 (CODE_INFORMATION_FILLER) and
350 (CODE_INFORMATION) responses indicating that the new PR
has been created and supplying the number assigned to it, or one or
more error codes listing problems with the new PR text.
CHDB databaseThe possible responses are:
422 (CODE_NO_ACCESS)
The user does not have permission to access the requested database.
417 (CODE_INVALID_DATABASE)
The database specified does not exist, or one or more configuration
errors in the database were encountered.
220 (CODE_OK)
The current database is now database. Any operations performed
will now be applied to database.
DBLSThe possible responses are:
6xx (internal error)
An internal error was encountered while trying to obtain the list of
available databases, usually due to lack of permissions or other
filesystem-related problems, or the list of databases is empty.
301 (CODE_TEXT_READY)
The list of databases follows, one per line, using the standard
quoting mechanism. Only the database names are sent.
The gnatsd access level listdb denies access until the
user has authenticated with the USER command. The only other command
available at this access level is DBLS. This access level
provides a way for a site to secure its gnats databases while still
providing a way for client tools to obtain a list of the databases for
use on login screens etc. See Controlling access to databases.
DBDESC databaseResponses include:
6xx (internal error)
An internal error was encountered while trying to read the list of
available databases, usually due to lack of permissions or other
filesystem-related problems, or the list of databases is empty.
350 (CODE_INFORMATION)
The normal response; the supplied text is the database description.
417 (CODE_INVALID_DATABASE)
The specified database name does not have an entry.
EXPR query expressionQUER command. The expression uses the normal query
expression syntax, (see Query expressions).
Multiple EXPR commands may be issued; the expressions are boolean
ANDed together.
Expressions are cleared by the RSET command.
Possible responses include:
415 (CODE_INVALID_EXPR)
The specified expression is invalid, and could not be parsed.
200 (CODE_OK)
The expression has been accepted and will be used to limit the
results returned from QUER.
QFMT query formatQUER command. The query format may be either the name of a query
format known to the server (see Named query definitions), or an
actual query format (see Formatting query-pr output). The possible
responses are:
200 (CODE_OK)
The normal response, which indicates that the query format is
acceptable.
440 (CODE_CMD_ERROR)
No query format was supplied.
418 (CODE_INVALID_QUERY_FORMAT)
The specified query format does not exist, or could not be parsed.
QUER [PR] [PR] [...]EXPR command. If no
expressions were specified with EXPR, the entire set of PRs is
returned.
If one or more PRs are specified on the command line, only those PRs will be searched and/or output.
The format of the output from the command is determined by the query
format selected with the QFMT command.
The possible responses are:
418 (CODE_INVALID_QUERY_FORMAT)
A valid format was not specified with the QFMT command prior to
invoking QUER.
300 (CODE_PR_READY)
One or more PRs will be output using the requested query format. The
PR text is quoted using the normal quoting mechanisms for PRs.
220 (CODE_NO_PRS_MATCHED)
No PRs met the specified criteria.
ADMV field key [subfield]The responses are:
410 (CODE_INVALID_FIELD_NAME)
The specified field does not exist.
221 (CODE_NO_ADM_ENTRY)
An adm entry matching the key was not found, or the field does not have
an adm file associated with it.
350 (CODE_INFORMATION)
The normal response; the supplied text is the requested field(s).
gnatsd environment variables
gnatsd supports the GNATSDB environment varable,
See Environment, in almost the same way as the gnats tools do.
This variable is used to determine which database to use. For a local
database, it contains the name of the database to
access. gnatsd cannot service remote databases (though it might
be interesting if it could) so the database is always assumed to be
local.
If GNATSDB is not set and the --database option is not
supplied, it is assumed that the database is local and that its name is
default.
gnats supports granting various levels of access to the gnats
databases served by the network daemon, gnatsd.
gnats access can be controlled at these levels:
denynonelistdbviewviewconfeditadminThese access levels are used in the following settings:
gnatsd access levelThe overall gnatsd access level is set by starting gnatsd
with the option
-mlevel or--maximum-access-level=level,
where level is one of the six access levels listed above. This restricts any access to the gnats daemon to levels up to and including level, regardless of the settings in the access control files discussed below. If this option is left out, any access levels set in the access control files will be allowed.
The discussion below assumes that the pre-build configure of gnats
was done without altering the default values for the
--enable-gnatsd-user-access-file and
--enable-gnatsd-host-access-file options. If non-default values
were given, substitute as appropriate below.
The host access file (by default /usr/local/etc/gnats/gnatsd.host_access) controls overall access levels on a per-host basis, meaning that settings in this file apply across all databases on the server. Entries in this file are in the following format:
host:access-level:whatever
host is the hostname or IP address of the host contacting gnatsd. Wildcard characters are supported: * matches anything; ? matches any single character. By using wildcards, you can specify access levels for entire network subnets and domains. Note that when gnats authenticates hosts, it reads the entries in this file in sequence until a match is found. This means that wildcard entries must be placed near the end of the file, otherwise, they will override non-wildcard entries appearing after the wildcard ones.
The second field is the access level of host. The default is
deny. If the user's hostname isn't in the file or its access
level is set to deny, the connection is closed immediately.
gnats currently doesn't make use of the third field. Remember to still include the second : on the line if you choose to leave the third field empty.
Whenever a CHDB command is processed (or defaulted), the user's
access level is set to the level for their host, as determined by the
values in the gnatsd.host_access file. However, even if a host
is given the none access level, an individual can still give the
USER command to possibly gain a higher (but never lower) access
than is set for their host. The gnatsd USER command takes two
arguments: USER <userid> <passwd>.
Access levels per user can be set both across all databases on the
server or on a per-database basis. The gnatsd.user_access file
in a database's gnats-adm directory specifies the user access
rules for that database. If it doesn't exist, or doesn't contain the
user name given to gnatsd, then the overall user access file
(by default /usr/local/etc/gnats/gnatsd.user_access)
specifying the per-user access levels across all the databases on the
server is checked.
The user access files can only increase the access level defined in the host access files for the given host, they can never lower it.
If the access level is none after processing the userid and
password, the connection is closed.
The gnatsd.user_access files can contain plain text passwords, in such a case they should be owned by the gnats user with file permission 600.
Wildcard characters are supported for the userid and password with plain text passwords. A null string or * matches anything; ? matches any one character. Note that when gnats authenticates users, it reads the entries in this file in sequence until a match is found. This means that wildcard entries must be placed near the end of the file, otherwise, they will override non-wildcard entries appearing after the wildcard ones.
Entries in the database-specific gnatsd.user_access user access file in the gnats-adm directory of the database have the following general format:
userid:password:access-level
The overall gnatsd.user_access user access file adds a fourth databases field:
userid:password:access-level:databases
password should either be in plain text, DES
crypt()4 or MD5 hash format5.
If the password is in plain text format, it must be prefixed by
$0$ and if it is in MD5 format, it needs to be prefixed by the
string $1$.6 Passwords encrypted by crypt() should have no
prefix. If no password is given then users can login with an empty
password string.
A gnats-passwd tool to manage gnatsd.user_access files is
planned. In the meantime, crypt() passwords can be generated by
using standard UNIX passwords tools, while MD5 passwords can be
generated with the following little Perl snippet:
perl -e 'use Crypt::PasswdMD5 ; print Crypt::PasswdMD5::unix_md5_crypt
"password" , time() % 100000000'
If your Perl installation doesn't have the Crypt module installed, you need to install it. On most systems, the following command achieves this:
perl -MCPAN -e 'install Crypt::PasswdMD5'
A tool for conversion of pre-version 4 gnatsd.user_access files is distributed with gnats 4. See Converting old password files.
The access-level field should contain one of the values listed at the beginning of this appendix. This overrides (increases but never lowers) the access level given as the default for the user's host in the global gnatsd.host_access file.
The following shows an example gnatsd.user_access file with plain text passwords:
rickm:$0$ruckm:edit
pablo:$0$pueblo:view
*::none
And this is the same file with MD5-encrypted passwords:
rickm:$1$92388613$D7ZIYikzTUqd./dODTFrI.:edit
pablo:$1$92388652$QRfAhIBG5elT.FQjQKhj80:view
*::none
In these examples, anybody other than rickm and pablo get
denied access, assuming that the host access level is also none.
You could set the catch-all rule at the end to be *::view to
allow view access to anyone who does not supply a password. Note the
important detail that such a rule would allow view access only to
persons who do not supply a password at all, i.e. if rickm or pablo tries
to log in but mistypes his password, this rule would not apply and
they would be denied access entirely. This is by design, since people
might be surprised if they suddenly found themselves logged in, but with
a lower access level than they usually have.
The databases field contains a comma-separated list of database
names, as defined in the databases file (see The databases file. Wildcard characters are
supported. The databases listed in this field are the ones to which
the other settings on the same line will be applied.
gnatsd commandsEvery gnatsd command has a minimum access level attached to
it. If your access level is too low for a command, you get this
response:
LOCK 12
422 You are not authorized to perform this operation (LOCK).
The commands CHDB, USER and QUIT are
unrestricted.
The DBLS command requires at least listdb access.
A user must have at least edit access for these commands:
LKDBUNDBLOCK PR user pidUNLK PREDIT PRAPPN PR field, REPL PR fieldThe DELETE PR command is special in that it requires
admin access.
All other commands require view access.
edit-pr and query-pr accept the command line arguments
-v|--user and -w|--passwd. See The gnats User Tools.
See also Query expressions.
Unfortunately, we do not have room in this manual for a complete exposition on regular expressions. The following is a basic summary of some regular expressions you might wish to use.
NOTE: When you use query expressions containing regular
expressions as part of an ordinary query-pr shell command line, you need
to quote them with '', otherwise the shell will try to interpret
the special characters used, yielding highly unpredictable results.
See Regular Expression Syntax (Regex), for details on regular expression syntax. Also see Syntax of Regular Expressions (GNU Emacs Manual), but beware that the syntax for regular expressions in Emacs is slightly different.
All search criteria options to query-pr rely on regular
expression syntax to construct their search patterns. For example,
query-pr --expr 'State="open"' --format full
matches all PRs whose State values match with the regular
expression open.
We can substitute the expression o for open, according
to gnu regular expression syntax. This matches all values of
State which begin with the letter o.
We see that
query-pr --expr 'State="o"' --format full
is equivalent to
query-pr --expr 'State="open"' --format full
in this case, since the only value for State which matches
the expression o in a standard installation is open.
State="o" also matches o, oswald, and even
oooooo, but none of those values are valid states for a Problem
Report in default gnats installations.
We can also use the expression operator | to signify a logical
OR, such that
query-pr --expr 'State="o|a"' --format full
matches all open or analyzed Problem Reports.
Regular expression syntax considers a regexp token surrounded with parentheses, as in (regexp), to be a group. This means that (ab)* matches any number (including zero) of contiguous instances of ab. Matches include , ab, and ababab.
Regular expression syntax considers a regexp token surrounded with square brackets, as in [regexp], to be a list. This means that Char[(ley)(lene)(broiled) matches any of the words Charley, Charlene, or Charbroiled (case is significant; charbroiled is not matched).
Using groups and lists, we see that
query-pr --expr 'Category="gcc|gdb|gas"' --format full
is equivalent to
query-pr --expr 'Category="g(cc|db|as)"' --format full
and is also very similar to
query-pr --expr 'Category="g[cda]"' --format full
with the exception that this last search matches any values which begin with gc, gd, or ga.
The . character is known as a wildcard. . matches on any single character. * matches the previous character (except newlines), list, or group any number of times, including zero. Therefore, we can understand .* to mean “match zero or more instances of any character.”
query-pr --expr 'State=".*a"' --format full
matches all values for State which contain an a. (These
include analyzed and feedback.)
Another way to understand what wildcards do is to follow them on their search for matching text. By our syntax, .* matches any character any number of times, including zero. Therefore, .*a searches for any group of characters which end with a, ignoring the rest of the field. .*a matches analyzed (stopping at the first a) as well as feedback.
Note: When using fieldtype:Text or fieldtype:Multitext (see Query expressions), you do not have to specify the token .* at the beginning of your expression to match the entire field. For the technically minded, this is because these queries use re_search rather than re_match. re_match anchors the search at the beginning of the field, while re_search does not anchor the search.
For example, to search in the >Description: field for the text
The defrobulator component returns a nil value.
we can use
query-pr --expr 'fieldtype:Multitext="defrobulator.*nil"' --format full
To also match newlines, we have to include the expression (.|^M) instead of just a dot (.). (.|^M) matches “any single character except a newline (.) or (|) any newline (^M).” This means that to search for the text
The defrobulator component enters the bifrabulator routine
and returns a nil value.
we must use
query-pr --expr 'fieldtype:Multitext="defrobulator(.|^M)*nil"'
--format full
To generate the newline character ^M, type the following depending on your shell:
cshtcshsh (or bash) (.|
)
Again, see Regular Expression Syntax (Regex), for a much more complete discussion on regular expression syntax.
The dbconfig file (The dbconfig file) is the heart of any gnats installation. It contains some very powerful machinery, something which this appendix tries to illustrate.
We provide a range of examples that are both intended to be useful in their own right and to serve as starting points or building blocks for your own modifications.
Sites that have Gnatsweb installed may wish to modify the response e-mail which is sent to the submitter of a PR so that it includes a URL where the status of the PR can be monitored. In order to allow this, you should first create an entry in gnatsd.user_access which allows viewing of PRs in your database (See The gnatsd.user_access file.)
Next, locate the entry mail-format
"initial-response-to-submitter" in the dbconfig file of your
database and add the following before the line reading “The
individual assigned...” in the body section:
\nYou can follow the status of this report on\n\ http://hostname/cgi-bin/scriptname?\n\ cmd=view&database=dbname&user=username&\n\ password=passwd&pr=%s\n\n\
Substitute hostname, cgi-bin and scriptname as
appropriate for the setup of your web server. The part before the
? would typically look something like
http://www.example.com/cgi-bin/gnatsweb.pl. Substitute the
name of your database for dbname, and the username and password
of the user with view rights for username and
passwd.
Next, add a Number to the fields list statement inside
the body so it reads as follows:
fields { "Category" "Number" "Number" "Responsible"
"Category" "Responsible" "Synopsis"
"Arrival-Date" }
The initial e-mail response to the submitter of a PR identifies the responsible person assigned to the PR as follows: “The individual assigned to look at your report is: GNATS username”. Some sites may wish to modify this so that the full name of the responsible person is used instead of the gnats user name.
The full name is contained in the fullname subfield of the
user's entry in the responsible file and can be accessed as
Responsible[fullname] (see Enumerated field administrative files.)
The change is achieved by editing the dbconfig item
mail-format "initial-response-to-submitter" and changing the
fields part of the Body from
fields { "Category" "Number" "Responsible"
"Category" "Responsible" "Synopsis"
"Arrival-Date" }
to
fields { "Category" "Number" "Responsible[fullname]"
"Category" "Responsible" "Synopsis"
"Arrival-Date" }
The Audit-Trail of a PR is by default editable. For some applications, one might want to make the Audit-Trail append-only, so it provides a full and unchangeable case history. Also by default, only certain changes, such as change of state and change of responsible gets recorded in the Audit-Trail. In some cases, it might also be convenient to have a way of inserting comments directly into the Audit-Trail.
The following procedure creates such an append-only Audit-Trail and adds a PR field which makes it possible to register comments in the Audit-Trail.
First, add the keyword read-only to the Audit-Trail field
definition in dbconfig.
Then, add the following field definition to dbconfig:
field "Add-To-Audit-Trail" {
description "Add a log entry to the Audit Trail"
multitext { default "\n" }
on-change {
add-audit-trail
audit-trail-format {
format "**** Comment added by %s on %s ****\n %s\n\n"
fields { "$EditUserEmailAddr" "$CurrentDate" "$NewValue"
}
}
}
on-change {
set-field "Add-To-Audit-Trail" { "\n" }
}
}
When installing gnats version 3.x, it was possible to choose
whether to enable three optional fields: Quarter, Keywords
and Date-Required. Default installations had these fields
switched off, and installations which had them were called
“release-based”.
The default dbconfig shipped with gnats version 4 or newer does not have these fields, so if you are upgrading from an old release-based system, you need to add the following field definitions to your dbconfig file:
field "Quarter" {
description "What quarter does the PR fall into?"
text
query-default inexact-regexp
textsearch
}
field "Keywords" {
description "Keywords used to index this PR"
text
query-default inexact-regexp
textsearch
}
field "Date-Required" {
description "Date that the PR must be fixed by"
date
}
A side note: Pre-release versions of gnats 4 also had a field
named Cases. For those who may need it, here is the field
definition of Cases:
field "Cases" {
text
query-default inexact-regexp
textsearch
}
The gnats home page is located at http://www.gnu.org/software/gnats. It contains all the important references to the available information about gnats and the related software.
There is also a special page dedicated to the gnats development at http://savannah.gnu.org/projects/gnats.
There are several gnats mailing lists. The most important ones are:
The complete list of gnats related mailing lists is available from the web page at http://savannah.gnu.org/project/gnats.
When you report problems concerning gnats itself, please do not forget to provide especially the following information:
Providing this information in the initial report avoids further unnecessary communication, saves our limited development resources and helps to track down and fix the problem soon.
>Submitter-Id: PR templateaddresses file: addresses fileaddresses file: GNATS configurationappended-email-response: Outgoing email formatsarrival-date: Individual field configurationArrival-Date field: Problem Report fieldsat: Setting up the default databaseat-pr: at-praudit-mail: Outgoing email formatsaudit-trail: Individual field configurationAudit-Trail field: Problem Report fieldsautoload commands: Installing utilsbuiltin-name: Individual field configurationbury-buffer: Emacs queryingbusiness-day-hours: Overall database configurationbusiness-week-days: Overall database configurationcategories file: rmcatcategories file: mkcatcategories file: categories filecategories file: GNATS configurationcategory: Individual field configurationCategory field: Problem Report fieldscategory-dir-perms: Overall database configurationcheck-db: check-dbClass field: Problem Report fieldsclasses file: classes fileclasses file: GNATS configurationclosed-date: Individual field configurationconfidential: Individual field configurationConfidential field: Problem Report fieldsconfigure: Configure and makecreate-category-dirs: Overall database configurationcron: Setting up the default databasecrontab: Setting up periodic jobscurrent file: current filedatabases file: databases filedatatype: Field datatypesdate: Field datatypesDate-Required: Problem Report fieldsDate-Required field: Problem Report fieldsdbconfig file: dbconfig filedbconfig file: GNATS configurationdebug-mode: Overall database configurationdeleted-pr-mail: Outgoing email formatsdescription: Individual field configurationDescription field: Problem Report fieldsdiff-prs: diff-prsedit-pr: pr-editgnats-admin: Managementedit-pr: Emacs editingedit-pr: edit-predit-pr driver: pr-editedit-pr from the shell: edit-pr from the shellpending directory: Managementenum: Field datatypesenumerated-in-file: Field datatypesEnvironment field: Problem Report fieldsfile-pr: file-prFix field: Problem Report fieldsformat-name: Outgoing email formatsFrom header: Mail header fieldsgen-index: gen-indexgen-index: Managementgnats-admin alias: Aliasesgnats-apply-or-submit: Emacs editing buffergnats-change-database: Emacs and databasesgnats-change-database: Emacs queryinggnats-dbconfig-mode: dbconfig modegnats-dbconfig-mode-hook: dbconfig modegnats-edit-mode-hook: Emacs editing buffergnats-next-field: Emacs editing buffergnats-previous-field: Emacs editing buffergnats-pwconv: gnats-pwconvgnats-query-edit-pr: Emacs queryinggnats-query-mode-hook: Emacs queryinggnats-query-reread: Emacs queryinggnats-query-view-pr: Emacs queryinggnats-show-connection: Other Emacs commandsgnats-view-edit-pr: Emacs viewinggnats-view-mode-hook: Emacs viewinggnatsd: gnatsdgnatsd command protocol: gnatsd command protocolgnatsd commands: gnatsd commandsgnatsd description: Description of gnatsdgnatsd environment variables: gnatsd environment variablesgnatsd options: gnatsd optionsgnatsd startup options: gnatsd optionsgnatsd.user_access file: GNATS configurationGNATSDB: gnatsd environment variablesGNATSDB: EnvironmentHow-To-Repeat field: Problem Report fieldsindex file: gen-indexindex file: index fileinitial-pr-notification: Outgoing email formatsinitial-pr-notification-pending: Outgoing email formatsinitial-response-to-submitter: Outgoing email formatsinteger: Field datatypesedit-pr: edit-prquery-pr: query-prsend-pr: send-prsend-pr from Emacs: send-pr in Emacssend-pr from the shell: send-pr from the shellkeep-all-received-headers: Overall database configurationlast-modified: Individual field configurationlibexecdir: Overall database configuration.el files: Installing utilsmake: Configure and makemkcat: mkcatmkcat: Managementmkdb: mkdbmkdb: Managementmulti-enumerated-in-file: Field datatypesmultienum: Field datatypesmultitext: Field datatypesnotify-about-expired-prs: Overall database configurationNotify-List field: Problem Report fieldsnumber: Individual field configurationNumber field: Problem Report fieldsOrganization field: Problem Report fieldsoriginator: Individual field configurationOriginator field: Problem Report fieldspending directory: Paradigmpending file: categories filepr-age: pr-agepr-edit: pr-editpriority: Individual field configurationPriority field: Problem Report fieldsquery-pr: Emacs queryingquery-pr: query-prquery-pr by mail: Invoking query-prqueue-pr: queue-prqueue-pr -q: AliasesReceived-By headers: Mail header fieldsRelease field: Problem Report fieldsReply-To header: Mail header fieldssend-pr: send-prresponsible: Individual field configurationResponsible field: Problem Report fieldsresponsible file: responsible fileresponsible file: GNATS configurationResponsible-Changed-<From>-<To> in Audit-Trail: Problem Report fieldsResponsible-Changed-By in Audit-Trail: Problem Report fieldsResponsible-Changed-When in Audit-Trail: Problem Report fieldsResponsible-Changed-Why in Audit-Trail: Problem Report fieldsrmcat: rmcatrmcat: Managementsend-pr: Emacs submittingsend-pr: Emacs queryingsend-pr: send-prsend-pr fields: PR templatesend-pr fields: send-pr from the shellsend-pr within Emacs: send-pr in Emacssend-pr.conf file: send-pr.conf filesend-submitter-ack: Overall database configurationseverity: Individual field configurationSeverity field: Problem Report fieldsstate: Individual field configurationState field: Problem Report fieldsState-Changed-<From>-<To> in Audit-Trail: Problem Report fieldsState-Changed-By in Audit-Trail: Problem Report fieldsState-Changed-When in Audit-Trail: Problem Report fieldsState-Changed-Why in Audit-Trail: Problem Report fieldsstates file: states filestates file: GNATS configurationSubject header: Mail header fieldssubmitter-id: Individual field configurationSubmitter-Id field: PR templateSubmitter-Id field: Problem Report fieldssubmitters file: submitters filesubmitters file: GNATS configurationsynopsis: Individual field configurationSynopsis field: Problem Report fieldstext: Field datatypesTo header: Mail header fieldsunformatted: Individual field configurationUnformatted field: Problem Report fieldsunlock-database: Other Emacs commandsunlock-pr: Other Emacs commandsedit-pr: edit-prquery-pr: query-prsend-pr: send-prsend-pr from within Emacs: send-pr in Emacsview-pr: Emacs viewing[1] If typing M-x send-pr doesn't work, see your system administrator for help loading gnats.el into Emacs.
[2] Upgraders from older versions of gnats should note that category directories are now created “on-the-fly” as needed by default.
[3] This approach may seem heavy-handed, but it ensures that changes are not overwritten.
[4] DES crypt is the standard password encryption format used by most UNIX systems
[5] MD5 is
only supported on platforms that have a crypt() function that
supports MD5. Among others, this currently includes gnu Linux and
OpenBSD.
[6] Some systems support even more encryption methods. In FreeBSD, for instance, a prefix of $2$ implies Blowfish encoding. gnats will happily accept any encryption that the OS supports.