« back to all changes in this revision
Viewing changes to doc/gnats.info
- browse files at revision 3
- compare with another revision
- download diff
- download tarball
- view history from revision 3
- Committer: Bazaar Package Importer
- Author(s): Chad Walstrom
- Date: 2005-03-07 17:56:31 UTC
- mfrom: (1.1.1 upstream) (2.1.1 hoary)
- Revision ID: james.westby@ubuntu.com-20050307175631-agtm10dvjbemuc64
Tags: 4.1.0-0
* New upstream version
* debian/rules: now uses '--with-lispdir' option instead of environment
variable overloading. Re-enabled optimization.
* debian/rules: now uses '--with-lispdir' option instead of environment
variable overloading. Re-enabled optimization.
- files added:
- .todo
- debian/po
- gnats/autom4te.cache
- files removed:
- config/mh-a68bsd
- config/mpw
- contrib/gnatsweb
- debian/scripts
- gnats/man
- include
- libiberty
- libiberty/config
- libiberty/include
- libiberty/testsuite
- files modified:
- ChangeLog
added
removed
doc/gnats.info
1
This is gnats.info, produced by makeinfo version 4.2 from gnats.texi.
1
This is gnats.info, produced by makeinfo version 4.7 from gnats.texi.
2
2
3
3
START-INFO-DIR-ENTRY
4
4
* Keeping Track: (gnats). GNU Problem Report Management System
5
5
END-INFO-DIR-ENTRY
6
6
7
Copyright (C) 2003 Milan Zamazal Copyright (C) 1993, 1995, 2001,
8
2003 Free Software Foundation, Inc.
7
Copyright (C) 1993, 1995, 2001, 2002, 2003 Free Software Foundation,
8
Inc.
9
9
10
10
Permission is granted to make and distribute verbatim copies of this
11
11
manual provided the copyright notice and this permission notice are
21
21
versions.
22
22
23
23
24
Indirect:
25
gnats.info-1: 851
26
gnats.info-2: 50222
27
gnats.info-3: 98524
28
gnats.info-4: 143745
29
gnats.info-5: 193471
30
gnats.info-6: 242245
24
File: gnats.info, Node: Top, Next: Introduction, Up: (dir)
25
26
Overview
27
********
28
29
This manual documents GNATS, the GNU Problem Report Management System,
30
version 4.1.0. GNATS is a bug-tracking tool designed for use at a
31
central "Support Site". Users who experience problems use electronic
32
mail, web-based or other clients communicating with the GNATS network
33
daemon running at the support site or direct database submissions to
34
communicate these problems to "maintainers" at that Support Site.
35
GNATS partially automates the tracking of these "Problem Reports"
36
("PR"s) by:
37
38
* organizing problem reports into a database and notifying
39
responsible parties of suspected bugs;
40
41
* allowing support personnel and their managers to edit and query
42
accumulated bugs; and
43
44
* providing a reliable archive of problems (and their subsequent
45
solutions) with a given program.
46
47
GNATS offers many of the same features offered by more generalized
48
databases, including editing, querying, and basic reporting. The GNATS
49
database itself is an ordered repository for problem reports; each PR
50
receives a unique, incremental "PR number" which identifies it
51
throughout its lifetime. For a discussion on the working system
52
adopted by GNATS, see *Note The database paradigm: Paradigm.
53
54
You can access the submitting, editing, and querying functions of
55
GNATS from within GNU Emacs. *Note The GNATS user tools: GNATS user
56
tools.
57
58
* Menu:
59
60
* Introduction:: Introducing GNATS.
61
* GNATS user tools:: The GNATS user tools.
62
* Installation:: Installing GNATS.
63
* Management:: GNATS Administration.
64
* Locations:: Where GNATS lives.
65
* gnatsd:: The GNATS network server.
66
* Access Control:: Controlling access to GNATS databases.
67
* Regexps:: Querying using regular expressions.
68
* dbconfig recipes:: Useful dbconfig tricks.
69
* Support:: GNATS related sites and mailing lists.
70
* Index::
71
72
73
File: gnats.info, Node: Introduction, Next: GNATS user tools, Prev: Top, Up: Top
74
75
1 Introducing GNATS
76
*******************
77
78
Any support organization realizes that a large amount of data flows back
79
and forth between the maintainers and the users of their products. This
80
data often takes the form of problem reports and communication via
81
electronic mail. GNATS addresses the problem of organizing this
82
communication by defining a database made up of archived and indexed
83
problem reports.
84
85
GNATS was designed as a tool for software maintainers. It consists
86
of several utilities which, when used in concert, formulate and
87
administer a database of Problem Reports grouped by site-defined
88
"problem categories". It allows a support organization to keep track
89
of problems (hence the term "Problem Report") in an organized fashion.
90
Essentially, GNATS acts as an active archive for field-separated
91
textual data.
92
93
* Menu:
94
95
* Paradigm:: The database paradigm
96
* Flowchart:: Flowchart of GNATS activities
97
* States:: States of Problem Reports
98
* Fields:: Problem Report format
99
100
101
File: gnats.info, Node: Paradigm, Next: Flowchart, Up: Introduction
102
103
1.1 The database paradigm
104
=========================
105
106
It is in your best interest as the maintainer of a body of work to
107
organize the feedback you receive on that work, and to make it easy for
108
users of your work to report problems and suggestions.
109
110
GNATS makes this easy by automatically filing incoming problem
111
reports into appropriate places, by notifying responsible parties of the
112
existence of the problem and (optionally) sending an acknowledgment to
113
the submitter that the report was received, and by making these Problem
114
Reports accessible to queries and easily editable. GNATS is a database
115
specialized for a specific task.
116
117
GNATS was designed for use at a Support Site that handles a high
118
level of problem-related traffic. It maintains Problem Reports in the
119
form of text files with defined "fields" (*note GNATS data fields:
120
Fields.). The location of the database, as well as the categories it
121
accepts as valid, the maintainers for whom it provides service, and the
122
submitters from whom it accepts Problem Reports, are all definable by
123
the "Support Site". *Note GNATS administration: Management.
124
125
Each PR is a separate file within a main repository (*note Where
126
GNATS lives: Locations.). Editing access to the database is regulated
127
to maintain consistency. To make queries on the database faster, an
128
index is kept automatically (*note The `index' file: index file.).
129
130
We provide several software tools so that users may submit new
131
Problem Reports, edit existing Problem Reports, and query the database.
132
133
* `send-pr' is used by both product maintainers and the end users of
134
the products they support to submit PRs to the database.
135
136
* `edit-pr' is used by maintainers when editing problem reports in
137
the database.
138
139
* Maintainers, managers and administrators can use `query-pr' to
140
make inquiries about individual PRs or groups of PRs.
141
142
143
Other interfaces to GNATS include Gnatsweb, a web-based tool which
144
provides features for submitting and editing PRs and querying the
145
database, and TkGnats, a Tcl/Tk-based frontend. These tools are
146
distributed together with GNATS.
147
148
At the Support Site, a GNATS "administrator" is charged with the
149
duty of maintaining GNATS. These duties are discussed in detail in
150
*Note GNATS Administration: Management, and generally include
151
configuring GNATS for the Support Site, editing PRs that GNATS cannot
152
process, pruning log files, setting up new problem categories, backing
153
up the database, and distributing `send-pr' so that others may submit
154
Problem Reports.
155
156
Responsibility for a given Problem Report initially depends on the
157
category of the problem. Optionally, an automated reminder can be sent
158
to the responsible person if a problem report is neglected for a
159
requisite time period. *Note Overview of GNATS configuration: GNATS
160
configuration.
161
162
GNATS does not have the ability to decipher random text. If there
163
is no default category set, any problem reports which arrive in a
164
format GNATS does not recognize are placed in a separate directory
165
pending investigation by the GNATS administrator (*note GNATS
166
Administration: Management.).
167
168
Once a problem is recorded in the database, work can begin toward a
169
solution. A problem's initial "state" type is "open" (*note States of
170
Problem Reports: States.). An acknowledgment may be sent to the
171
originator of the bug report (depending on whether this feature has
172
been switched on in the GNATS configuration). GNATS forwards copies of
173
the report to the party responsible for that problem category and to
174
the person responsible for problems arriving from that submitter.
175
176
When a problem has been identified, the maintainer can change its
177
state to "analyzed", and then to "feedback" when a solution is found.
178
GNATS may be configured so that each time the state of a PR changes,
179
the submitter of the problem report is notified of the reason for the
180
change. If the party responsible for the PR changes, the previous
181
responsible party and the new responsible party receive notice of the
182
change. The change and reason are also recorded in the `Audit-Trail'
183
field of the Problem Report. (*Note Editing existing Problem Reports:
184
edit-pr. For information on the `Audit-Trail' field, see *Note Problem
185
Report format: Fields.)
186
187
When the originator of the Problem Report confirms that the solution
188
works, the maintainer can change the state to "closed". If the PR
189
cannot be closed, the maintainer can change its state to "suspended" as
190
a last resort. (For a more detailed description of the standard
191
states, see *Note States of Problem Reports: States.)
192
193
It should be emphasized that what we describe here is the default way
194
that GNATS works, but as of version 4, GNATS is extremely customizable,
195
allowing sites to tailor almost every aspect of its behavior. See for
196
instance *Note The `dbconfig' file: dbconfig file. and *Note States of
197
Problem Reports: States.)
198
199
200
File: gnats.info, Node: Flowchart, Next: States, Prev: Paradigm, Up: Introduction
201
202
1.2 Flowchart of GNATS activities
203
=================================
204
205
This informal flowchart shows the relationships of the GNATS tools to
206
each other and to the files with which they interoperate.
207
208
209
210
+===========+ +===========+ +============+
211
# USER SITE # # USER SITE # # USER SITE #
212
# # # # # #
213
# *send-pr* # # *send-pr* # # Web client #
214
+=====|=====+ +=====|=====+ +=====|======+
215
| V |
216
`---------> Email/gnatsd... <-------'
217
,---> |
218
+===============|=========|===================+
219
# SUPPORT SITE | `---> /etc/aliases #
220
# *send-pr* | #
221
# +-----------------------------V--------+#
222
# | GNATS DATABASEDIR/gnats-queue/|#
223
# | | |#
224
# | _________ V |#
225
# | |*file-pr*|<--- *queue-pr -r* |#
226
# | | | |#
227
# _ | | valid | |#
228
# |M| | |Category?|N--. |#
229
# |A| | |_________| | GNATS |#
230
# |I| | Y| | ADMINISTRATOR |#
231
# |N| | | | |#
232
# |T|<----------------| | |#
233
# |A| | | | .-> *edit-pr* |#
234
# |I|--->*edit-pr*-. | V | | |#
235
# |N| | | |DATABASEDIR/pending | |#
236
# |E|<--*query-pr* | | | |#
237
# |R| | | | | | |#
238
# |S| | | V V V |#
239
# |_| |+------------------------------------+|#
240
# || GNATS Database ||#
241
# || DATABASEDIR/CATEGORY/GNATS-ID ||#
242
# |+------------------------------------+|#
243
# +--------------------------------------+#
244
+=============================================+
245
246
247
248
249
File: gnats.info, Node: States, Next: Fields, Prev: Flowchart, Up: Introduction
250
251
1.3 States of Problem Reports
252
=============================
253
254
Each PR goes through a defined series of states between origination and
255
closure. By default, the originator of a PR receives notification
256
automatically of any state changes.
257
258
Unless your site has customized states (*note states file:
259
(gnats)states file.), GNATS uses these states:
260
261
"open"
262
The initial state of a Problem Report. This means the PR has been
263
filed and the responsible person(s) notified.
264
265
"analyzed"
266
The responsible person has analyzed the problem. The analysis
267
should contain a preliminary evaluation of the problem and an
268
estimate of the amount of time and resources necessary to solve
269
the problem. It should also suggest possible workarounds.
270
271
"feedback"
272
The problem has been solved, and the originator has been given a
273
patch or other fix. The PR remains in this state until the
274
originator acknowledges that the solution works.
275
276
"closed"
277
A Problem Report is closed ("the bug stops here") only when any
278
changes have been integrated, documented, and tested, and the
279
submitter has confirmed the solution.
280
281
"suspended"
282
Work on the problem has been postponed. This happens if a timely
283
solution is not possible or is not cost-effective at the present
284
time. The PR continues to exist, though a solution is not being
285
actively sought. If the problem cannot be solved at all, it
286
should be closed rather than suspended.
287
288
289
File: gnats.info, Node: Fields, Prev: States, Up: Introduction
290
291
1.4 Problem Report format
292
=========================
293
294
The format of a PR is designed to reflect the nature of GNATS as a
295
database. Information is arranged into "fields", and kept in
296
individual records (Problem Reports).
297
298
A Problem Report contains two different types of fields: "Mail
299
Header" fields, which are used by the mail handler for delivery, and
300
"Problem Report" fields, which contain information relevant to the
301
Problem Report and its submitter. A Problem Report is essentially a
302
specially formatted electronic mail message.
303
304
Problem Report fields are denoted by a keyword which begins with `>'
305
and ends with `:', as in `>Confidential:'. Fields belong to one of
306
eight data types as listed in *Note Field datatypes reference::. As of
307
version 4 of GNATS all characteristics of fields, such as field name,
308
data type, allowed values, permitted operations, on-change actions etc.
309
are configurable.
310
311
For details, see *note The `dbconfig' file: dbconfig file.
312
313
Example Problem Report
314
----------------------
315
316
The following is an example Problem Report with the fields that
317
would be present in a standard GNATS configuration. Mail headers are
318
at the top, followed by GNATS fields, which begin with `>' and end with
319
`:'. The `Subject:' line in the mail header and the `Synopsis' field
320
are usually duplicates of each other.
321
322
Message-Id: MESSAGE-ID
323
Date: DATE
324
From: ADDRESS
325
Reply-To: ADDRESS
326
To: BUG-ADDRESS
327
Subject: SUBJECT
328
329
>Number: GNATS-ID
330
>Category: CATEGORY
331
>Synopsis: SYNOPSIS
332
>Confidential: yes _or_ no
333
>Severity: critical, serious, _or_ non-critical
334
>Priority: high, medium _or_ low
335
>Responsible: RESPONSIBLE
336
>State: open, analyzed, suspended, feedback, _or_ closed
337
>Class: sw-bug, doc-bug, change-request, support,
338
duplicate, _or_ mistaken
339
>Submitter-Id: SUBMITTER-ID
340
>Arrival-Date: DATE
341
>Originator: NAME
342
>Organization: ORGANIZATION
343
>Release: RELEASE
344
>Environment:
345
ENVIRONMENT
346
>Description:
347
DESCRIPTION
348
>How-To-Repeat:
349
HOW-TO-REPEAT
350
>Fix:
351
FIX
352
>Audit-Trail:
353
APPENDED-MESSAGES...
354
State-Changed-From-To: FROM-TO
355
State-Changed-When: DATE
356
State-Changed-Why:
357
REASON
358
Responsible-Changed-From-To: FROM-TO
359
Responsible-Changed-When: DATE
360
Responsible-Changed-Why:
361
REASON
362
>Unformatted:
363
MISCELLANEOUS
364
365
* Menu:
366
367
* Field datatypes reference::
368
* Mail header fields::
369
* Problem Report fields::
370
371
372
File: gnats.info, Node: Field datatypes reference, Next: Mail header fields, Up: Fields
373
374
1.4.1 Field datatypes reference
375
-------------------------------
376
377
The following is a short reference to the characteristics of the
378
different field types.
379
380
For details, see *Note Field datatypes::.
381
382
`text'
383
A one-line text string.
384
385
`multitext'
386
Multiple lines of text.
387
388
`enum'
389
The value in this field is required to be from a list of specified
390
values, defined at the Support Site.
391
392
(*Note The `dbconfig' file: dbconfig file, for details.
393
394
`multienum'
395
Similar to the `enum' datatype, except that the field can contain
396
multiple values.
397
398
`enumerated-in-file'
399
Similar to `enum', but the allowed field values are listed in a
400
separate file on the GNATS server.
401
402
`multi-enumerated-in-file'
403
Similar to `enumerated-in-file', except that the field can contain
404
multiple values.
405
406
`date'
407
Used to hold dates.
408
409
`integer'
410
Used to hold integer numbers.
411
412
413
File: gnats.info, Node: Mail header fields, Next: Problem Report fields, Prev: Field datatypes reference, Up: Fields
414
415
1.4.2 Mail header fields
416
------------------------
417
418
A Problem Report may contain any mail header field described in the
419
Internet standard RFC-822. The `send-pr' tool can be configured either
420
to submit PRs to the support site by e-mail or by talking directly to
421
the `gnatsd' network daemon on the GNATS server. This is also true for
422
other client tools such as Gnatsweb. Even when these tools are set up
423
submit PRs directly to `gnatsd', they will still include mail header
424
fields that identify the sender and the subject in the submitted PR:
425
426
`To:'
427
The mail address for the Support Site, automatically supplied by
428
the tool used to submit the PR or by the originator if plain
429
e-mail was used.
430
431
`Subject:'
432
A terse description of the problem. This field normally contains
433
the same information as the `Synopsis' field.
434
435
`From:'
436
Supplied automatically when PRs are submitted by plain e-mail and
437
when well-behaved tools such as `send-pr' are used; should always
438
contain the originator's e-mail address.
439
440
`Reply-To:'
441
A return address to which electronic replies can be sent; in most
442
cases, the same address as the `From:' field.
443
444
One of the configurable options for GNATS is whether or not to
445
retain `Received-By' headers, which often consume a lot of space and
446
are not often used. *Note The dbconfig file: dbconfig file.
447
448
449
File: gnats.info, Node: Problem Report fields, Prev: Mail header fields, Up: Fields
450
451
1.4.3 Problem Report fields
452
---------------------------
453
454
In a standard GNATS installation, certain fields will always be present
455
in a Problem Report. If a PR arrives without one or more of these
456
fields, GNATS will add them, and if they have default values set by the
457
configuration at the Support Site, they will be filled in with these
458
values. Certain tools such as `send-pr' are set up to provide sensible
459
defaults for most fields (*note The send-pr.conf configuration file:
460
send-pr.conf file.)
461
462
In the list below, the field type (`text', `multitext',
463
`enumerated', etc.) is supplied in parantheses. The different field
464
types are explained briefly in *Note Field datatypes reference::.
465
466
`Submitter-Id'
467
(`enumerated-in-file') A unique identification code assigned by the
468
Support Site. It is used to identify all Problem Reports coming
469
from a particular site. Submitters without a value for this field
470
can invoke `send-pr' with the `--request-id' option to apply for
471
one from the support organization. Problem Reports from those not
472
affiliated with the support organization should use the default
473
value of `net' for this field.
474
475
*Note The `submitters' file: submitters file, for details.
476
477
`Notify-List'
478
(`text') Comma-separated list of e-mail-addresses of people to
479
notify when the PR changes significantly, i.e. when the Audit-Trail
480
changes. This list is independent from the Notify subfield of
481
entries in the `categories' file of the GNATS database.
482
483
`Originator'
484
(`text') Originator's real name. Note that the Submitter and
485
Originator might not be the same person/entity in all cases.
486
487
`Organization'
488
(`multitext') The originator's organization.
489
490
`Confidential'
491
(`enum') Use of this field depends on the originator's relationship
492
with the support organization; contractual agreements often have
493
provisions for preserving confidentiality. Conversely, a lack of a
494
contract often means that any data provided will not be considered
495
confidential. Submitters should be advised to contact the support
496
organization directly if this is an issue.
497
498
If the originator's relationship to the support organization
499
provides for confidentiality, then if the value of this field is
500
`yes' the support organization treats the PR as confidential; any
501
code samples provided are not made publicly available.
502
503
`Synopsis'
504
(`text') One-line summary of the problem. `send-pr' copies this
505
information to the `Subject' line when you submit a Problem Report.
506
507
`Severity'
508
(`enum') The severity of the problem. By default, accepted values
509
include:
510
511
`critical'
512
The product, component or concept is completely
513
non-operational or some essential functionality is missing.
514
No workaround is known.
515
516
`serious'
517
The product, component or concept is not working properly or
518
significant functionality is missing. Problems that would
519
otherwise be considered `critical' are usually rated
520
`serious' when a workaround is known.
521
522
`non-critical'
523
The product, component or concept is working in general, but
524
lacks features, has irritating behavior, does something
525
wrong, or doesn't match its documentation.
526
527
`Priority'
528
(`enumerated') How soon the originator requires a solution.
529
Accepted values include:
530
531
`high'
532
A solution is needed as soon as possible.
533
534
`medium'
535
The problem should be solved in the next release.
536
537
`low'
538
The problem should be solved in a future release.
539
540
`Category'
541
(`enumerated-in-file') The name of the product, component or
542
concept where the problem lies. The values for this field are
543
defined by the Support Site. *Note The `categories' file:
544
categories file, for details.
545
546
`Class'
547
(`enumerated-in-file') The class of a problem in a default GNATS
548
installation can be one of the following:
549
550
`sw-bug'
551
A general product problem. (`sw' stands for "software".)
552
553
`doc-bug'
554
A problem with the documentation.
555
556
`change-request'
557
A request for a change in behavior, etc.
558
559
`support'
560
A support problem or question.
561
562
`duplicate (PR-NUMBER)'
563
Duplicate PR. PR-NUMBER should be the number of the original
564
PR.
565
566
`mistaken'
567
No problem, user error or misunderstanding. This value can
568
only be set by tools at the Support Site, since it has no
569
meaning for ordinary submitters.
570
571
*Note The `classes' file: classes file, for details.
572
573
`Release'
574
(`text') Release or version number of the product, component or
575
concept.
576
577
`Environment'
578
(`multitext') Description of the environment where the problem
579
occurred: machine architecture, operating system, host and target
580
types, libraries, pathnames, etc.
581
582
`Description'
583
(`multitext') Precise description of the problem.
584
585
`How-To-Repeat'
586
(`multitext') Example code, input, or activities to reproduce the
587
problem. The support organization uses example code both to
588
reproduce the problem and to test whether the problem is fixed.
589
Include all preconditions, inputs, outputs, conditions after the
590
problem, and symptoms. Any additional important information
591
should be included. Include all the details that would be
592
necessary for someone else to recreate the problem reported,
593
however obvious. Sometimes seemingly arbitrary or obvious
594
information can point the way toward a solution. See also *Note
595
Helpful hints: Helpful hints.
596
597
`Fix'
598
(`multitext') A description of a solution to the problem, or a
599
patch which solves the problem. (This field is most often filled
600
in at the Support Site; we provide it to the submitter in case he
601
or she has solved the problem.)
602
603
GNATS adds the following fields when the PR arrives at the Support Site:
604
605
`Number'
606
(`enumerated') The incremental identification number for this PR.
607
This is included in the automated reply to the submitter (if that
608
feature of GNATS is activated; *note The `dbconfig' file: dbconfig
609
file.). It is also included in the copy of the PR that is sent to
610
the maintainer.
611
612
The `Number' field is often paired with the `Category' field as
613
614
CATEGORY/NUMBER
615
616
in subsequent email messages. This is GNATS' way of tracking
617
followup messages that arrive by mail so that they are filed as
618
part of the original PR.
619
620
`State'
621
(`enumerated') The current state of the PR. In default GNATS
622
installations, accepted values are:
623
624
`open'
625
The PR has been filed and the responsible person notified.
626
627
`analyzed'
628
The responsible person has analyzed the problem.
629
630
`feedback'
631
The problem has been solved, and the originator has been
632
given a patch or other fix. Support organizations may also
633
choose to temporarily "park" PRs that are awaiting further
634
input from the submitter under this state.
635
636
`closed'
637
The changes have been integrated, documented, and tested, and
638
the originator has confirmed that the solution works.
639
640
`suspended'
641
Work on the problem has been postponed.
642
643
The initial state of a PR is `open'. *Note States of Problem
644
Reports: States.
645
646
`Responsible'
647
(`text') The person at the Support Site who is responsible for this
648
PR. GNATS retrieves this information from the `categories' file
649
(*note The `categories' file: categories file.).
650
651
`Arrival-Date'
652
(`date') The time that this PR was received by GNATS. The date is
653
provided automatically by GNATS.
654
655
`Date-Required'
656
(`date') The date by which a fix is required. This is up to the
657
maintainers at the Support Site to determine, so this field is not
658
available until after the PR has been submitted.
659
660
`Audit-Trail'
661
(`multitext') Tracks related electronic mail as well as changes in
662
the `State' and `Responsible' fields with the sub-fields:
663
664
`State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE'
665
The old and new `State' field values.
666
667
`Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP'
668
The old and new `Responsible' field values.
669
670
`State-Changed-By: NAME'
671
`Responsible-Changed-By: NAME'
672
The name of the maintainer who effected the change.
673
674
`State-Changed-When: TIMESTAMP'
675
`Responsible-Changed-When: TIMESTAMP'
676
The time the change was made.
677
678
`State-Changed-Why: REASON...'
679
`Responsible-Changed-Why: REASON...'
680
The reason for the change.
681
682
The `Audit-Trail' field also contains any mail messages received by
683
GNATS related to this PR, in the order received. GNATS needs to
684
find a reference to the PR in the Subject field of received email
685
in order to be able to file it correctly, see *Note Following up
686
via direct email: follow-up via email.
687
688
`Unformatted'
689
(`multitext') Any random text found outside the fields in the
690
original Problem Report.
691
692
During a Problem Report's journey from `open' to `closed', two more
693
fields, `Last-Modified' and `Closed Date' (both of type `date') will be
694
added.
695
696
697
File: gnats.info, Node: GNATS user tools, Next: Installation, Prev: Introduction, Up: Top
698
699
2 The GNATS User Tools
700
**********************
701
702
This chapter describes the user tools distributed with GNATS. The
703
GNATS administrative and internal tools are described in *Note GNATS
704
Administration: Management. The user tools provide facilities for
705
initial submission, querying and editing of Problem Reports:
706
707
`send-pr'
708
Used by anyone who has a problem with a body of work to submit a
709
report of the problem to the maintainers of that work (*note
710
Submitting Problem Reports: send-pr.).
711
712
`query-pr'
713
Used to query the GNATS database (*note Querying the database:
714
query-pr.).
715
716
`edit-pr'
717
Used to edit Problem Reports (to record new data, to change the
718
responsible party, etc.) (*note Editing existing Problem Reports:
719
edit-pr.).
720
721
* Menu:
722
723
* Environment:: Environment variables and GNATS tools
724
* send-pr:: Submitting Problem Reports
725
* edit-pr:: Editing existing Problem Reports
726
* query-pr:: Querying the database
727
* Emacs:: The Emacs interface
728
729
730
File: gnats.info, Node: Environment, Next: send-pr, Up: GNATS user tools
731
732
2.1 Environment variables and GNATS tools
733
=========================================
734
735
All the GNATS user tools honor the `GNATSDB' environment variable which
736
is used to determine which database to use. For a local database, it
737
contains the name of the database to access.
738
739
For network access via gnatsd, it contains a colon-separated list of
740
strings that describe the remote database in the form
741
742
SERVER:PORT:DATABASENAME:USERNAME:PASSWORD
743
744
Any of the fields may be omitted except for SERVER, but at least one
745
colon must appear; otherwise, the value is assumed to be the name of a
746
local database.
747
748
If `GNATSDB' is not set and no command-line options are used to
749
specify the database, it is assumed that the database is local and that
750
its name is `default'.
751
752
753
File: gnats.info, Node: send-pr, Next: edit-pr, Prev: Environment, Up: GNATS user tools
754
755
2.2 Submitting Problem Reports
756
==============================
757
758
Use `send-pr' to submit Problem Reports to the database. `send-pr' is
759
a shell script which composes a template for submitters to complete.
760
761
You can invoke `send-pr' from a shell prompt, or from within GNU
762
Emacs using `M-x send-pr' (*note Submitting Problem Reports from Emacs:
763
Emacs submitting.)
764
765
* Menu:
766
767
* PR template:: The Problem Report template
768
* send-pr in Emacs:: Using send-pr from within Emacs
769
* send-pr from the shell:: Invoking send-pr from the shell
770
* Submitting via e-mail:: Submitting a Problem Report via direct e-mail
771
* Helpful hints::
772
773
774
File: gnats.info, Node: send-pr from the shell, Next: Submitting via e-mail, Prev: send-pr in Emacs, Up: send-pr
775
776
2.2.1 Invoking `send-pr' from the shell
777
---------------------------------------
778
779
send-pr [ -b | --batch ]
780
[ -d DATABASE | --database DATABASE ]
781
[ -f FILE | --file FILE ]
782
[ -p | --print ] [ --request-id ]
783
[ -s SEVERITY | --severity SEVERITY ]
784
[ -V | --version ] [ -h | --help ]
785
786
Invoking `send-pr' with no options assumes that you want to submit
787
to the local GNATS database named DEFAULT and calls the editor named in
788
your environment variable `EDITOR' on a PR template for this database.
789
790
`-b'
791
`--batch'
792
Suppresses printing of most of the messages `send-pr' usually
793
prints while running.
794
795
`-d DATABASE, --database DATABASE'
796
Specifies the database to which the PR is to be submitted; if no
797
database is specified, the local database named `default' is
798
assumed. This option overrides the database specified in the
799
`GNATSDB' environment variable. DATABASE can also be set to a
800
remote database by using the format for `GNATSDB' described in
801
*Note Environment variables and GNATS tools: Environment.
802
803
`-f PROBLEM-REPORT'
804
`--file PROBLEM-REPORT'
805
Specifies a file, PROBLEM-REPORT, where a completed Problem Report
806
or a PR template exists. `send-pr' verifies that the contents of
807
the file constitute a valid PR and asks you if you want to edit it
808
or send it directly. If the PR text is invalid you will be told
809
what is wrong and be given the option to edit it. If
810
PROBLEM-REPORT is `-', `send-pr' reads from standard input.
811
812
`-p'
813
`--print'
814
Displays the PR template for the specified database, or if the
815
`-d' or `--database' options aren't specified, print the template
816
for the local DEFAULT database. No PR is submitted.
817
818
`--request-id'
819
Sends a request for a `Submitter-Id' to the Support Site.
820
821
`-s SEVERITY'
822
`--severity SEVERITY'
823
Sets the initial value of the `Severity' field to SEVERITY.
824
825
`-V'
826
`--version'
827
Displays the `send-pr' version number and a usage summary. No mail
828
is sent.
829
830
`-h'
831
`--help'
832
Displays a usage summary for `send-pr'. No mail is sent.
833
834
835
File: gnats.info, Node: send-pr in Emacs, Next: send-pr from the shell, Prev: PR template, Up: send-pr
836
837
2.2.2 Using `send-pr' from within Emacs
838
---------------------------------------
839
840
You can use an interactive `send-pr' interface from within GNU Emacs to
841
fill out your Problem Report. We recommend that you familiarize
842
yourself with Emacs before using this feature (*note Introduction:
843
(emacs)Introduction.).
844
845
Call `send-pr' with `M-x send-pr'.(1) `send-pr' responds with a
846
preconfigured Problem Report template. The Emacs interface is
847
described in more detail in a separate section, *Note The Emacs
848
interface to GNATS: Emacs.
849
850
---------- Footnotes ----------
851
852
(1) If typing `M-x send-pr' doesn't work, see your system
853
administrator for help loading `gnats.el' into Emacs.
854
855
856
File: gnats.info, Node: PR template, Next: send-pr in Emacs, Up: send-pr
857
858
2.2.3 The Problem Report template
859
---------------------------------
860
861
Invoking `send-pr' presents a PR "template" with a number of fields
862
already filled in with default values for the database you are
863
submitting to. Complete the template as thoroughly as possible to make
864
a useful bug report. Submit only one bug with each PR.
865
866
A template consists of three sections:
867
868
* Comments
869
870
* Mail Header
871
872
* GNATS fields
873
874
The *Comments section* at the top of the template contains basic
875
instructions for completing the Problem Report, as well as a list of
876
valid entries for the `Category' field. One (and only one) of these
877
values should be placed in the `Category' field further down in the
878
Problem Report.
879
880
SEND-PR: -*- send-pr -*-
881
SEND-PR: Lines starting with `SEND-PR' will be removed
882
SEND-PR: automatically as well as all comments (the text
883
SEND-PR: below enclosed in `<' and `>').
884
SEND-PR:
885
SEND-PR: Please consult the document `Reporting Problems
886
SEND-PR: Using send-pr' if you are not sure how to fill out
887
SEND-PR: a problem report.
888
SEND-PR:
889
SEND-PR: Choose from the following categories:
890
891
The comments lines are all preceded by the string `SEND-PR:' and are
892
erased automatically when the PR is submitted. The instructional
893
comments within `<' and `>' are also removed. (Only these comments are
894
removed; lines you provide that happen to have those characters in
895
them, such as examples of shell-level redirection, are not affected.)
896
897
The *Mail Header* section of the template contains a standard mail
898
header constructed by `send-pr'. `send-pr' can be set up to submit PRs
899
by e-mail or by speaking directly to the GNATS server, but since this
900
header is part of the standard format of Problem Reports, `send-pr'
901
includes it even when it is set up to speak directly to the server.
902
903
To: PR SUBMISSION ADDRESS
904
Subject: _complete this field_
905
From: YOUR-LOGIN@YOUR-SITE
906
Reply-To: YOUR-LOGIN@YOUR-SITE
907
X-send-pr-version: send-pr 4.1.0
908
909
`send-pr' automatically completes all the mail header fields except the
910
`Subject' line with default values. (*Note Problem Report format:
911
Fields.)
912
913
The *GNATS fields* below the mail header form the bulk of a GNATS
914
Problem Report.
915
916
Each field is either automatically completed with valid information
917
(such as your `Submitter-Id') or contains a one-line instruction
918
specifying the information that field requires in order to be correct.
919
For example, the `Confidential' field expects a value of `yes' or `no',
920
and the answer must fit on one line; similarly, the `Synopsis' field
921
expects a short synopsis of the problem, which must also fit on one
922
line. Fill out the fields as completely as possible. *Note Helpful
923
hints: Helpful hints, for suggestions as to what kinds of information
924
to include.
925
926
The mechanisms `send-pr' uses to fill in default values is as
927
follows: Your preconfigured `Submitter-Id' is taken from the local
928
`send-pr.conf' configuration file. `send-pr' will set the `Originator'
929
field to the value of the `NAME' environment variable if it has been
930
set; similarly, `Organization' will be set to the value of
931
`ORGANIZATION'. If these variables aren't set in you environment,
932
`send-pr' uses the values set in the local `send-pr.conf' configuration
933
file, if that exists. If not, these values are left blank in the
934
template. `send-pr' also attempts to find out some information about
935
your system and architecture, and places this information in the
936
`Environment' field if it finds any.
937
938
In this example, words in _italics_ are filled in with
939
pre-configured information:
940
941
>Submitter-Id: _your submitter-id_
942
>Originator: _your name here_
943
>Organization:
944
_your organization_
945
>Confidential:<[ yes | no ] (one line)>
946
>Synopsis: <synopsis of the problem (one line)>
947
>Severity: <[non-critical | serious | critical](one line)>
948
>Priority: <[ low | medium | high ] (one line)>
949
>Category: <name of the product (one line)>
950
>Class: <[sw-bug | doc-bug | change-request | support]>
951
>Release: <release number (one line)>
952
>Environment:
953
<machine, os, target, libraries (multiple lines)>
954
955
>Description:
956
<precise description of the problem (multiple lines)>
957
>How-To-Repeat:
958
<code/input/activities to reproduce (multiple lines)>
959
>Fix:
960
<how to correct or work around the problem, if known
961
(multiple lines)>
962
963
When you finish editing the Problem Report, `send-pr' validates the
964
contents and if it looks OK either submits it directly to the GNATS
965
server or submits it by mail to the address named in the `To' field in
966
the mail header.
967
968
If your PR contains one or more invalid field values, `send-pr'
969
places the PR in a temporary file named `/tmp/pbadNNNN' on your
970
machine. NNNN is the process identification number given to your
971
current `send-pr' session. If you are running `send-pr' from the
972
shell, you are prompted as to whether or not you wish to try editing
973
the same Problem Report again. If you are running `send-pr' from
974
Emacs, the Problem Report is placed in the buffer `*gnats-send*'; you
975
can edit this file and then submit it with `C-c C-c'.
976
977
978
File: gnats.info, Node: Submitting via e-mail, Next: Helpful hints, Prev: send-pr from the shell, Up: send-pr
979
980
2.2.4 Submitting a Problem Report via direct e-mail
981
---------------------------------------------------
982
983
In addition to using `send-pr', there is another way to submit a
984
problem report. You can simply send an e-mail message to the PR
985
submission e-mail address of the support site (This address should be
986
published by the support site.)
987
988
When you send unformatted e-mail to this address, GNATS processes
989
the message as a new problem report, filling in as many fields from
990
defaults as it can:
991
992
`Synopsis'
993
The `Synopsis' field is filled in by the `Subject' header of the
994
e-mail message.
995
996
`Submitter ID'
997
GNATS will try to derive the `Submitter' field from the address in
998
the `From' header of the e-mail.
999
1000
`Description'
1001
All of the text in the body of the e-mail message is put into the
1002
`Description' field.
1003
1004
Other fields, such as `Category', `Version', `Severity', etc. are
1005
set to default values as defined by the GNATS administrator.
1006
1007
1008
File: gnats.info, Node: Helpful hints, Prev: Submitting via e-mail, Up: send-pr
1009
1010
2.2.5 Helpful hints
1011
-------------------
1012
1013
There is no orthodox standard for submitting effective bug reports,
1014
though you might do well to consult the section on submitting bugs for
1015
GNU `gcc' in *Note Reporting Bugs: (gcc)Bugs, by Richard Stallman.
1016
This section contains instructions on what kinds of information to
1017
include and what kinds of mistakes to avoid.
1018
1019
In general, common sense (assuming such an animal exists) dictates
1020
the kind of information that would be most helpful in tracking down and
1021
resolving problems in software.
1022
* Include anything _you_ would want to know if you were looking at
1023
the report from the other end. There's no need to include every
1024
minute detail about your environment, although anything that might
1025
be different from someone else's environment should be included
1026
(your path, for instance).
1027
1028
* Narratives are often useful, given a certain degree of restraint.
1029
If a person responsible for a bug can see that A was executed, and
1030
then B and then C, knowing that sequence of events might trigger
1031
the realization of an intermediate step that was missing, or an
1032
extra step that might have changed the environment enough to cause
1033
a visible problem. Again, restraint is always in order ("I set
1034
the build running, went to get a cup of coffee (Columbian, cream
1035
but no sugar), talked to Sheila on the phone, and then THIS
1036
happened...") but be sure to include anything relevant.
1037
1038
* Richard Stallman writes, "The fundamental principle of reporting
1039
bugs usefully is this: *report all the facts*. If you are not sure
1040
whether to state a fact or leave it out, state it!" This holds
1041
true across all problem reporting systems, for computer software
1042
or social injustice or motorcycle maintenance. It is especially
1043
important in the software field due to the major differences
1044
seemingly insignificant changes can make (a changed variable, a
1045
missing semicolon, etc.).
1046
1047
* Submit only _one_ problem with each Problem Report. If you have
1048
multiple problems, use multiple PRs. This aids in tracking each
1049
problem and also in analyzing the problems associated with a given
1050
program.
1051
1052
* It never hurts to do a little research to find out if the bug
1053
you've found has already been reported. Most software releases
1054
contain lists of known bugs in the Release Notes which come with
1055
the software; see your system administrator if you don't have a
1056
copy of these.
1057
1058
* The more closely a PR adheres to the standard format, the less
1059
interaction is required by a database administrator to route the
1060
information to the proper place. Keep in mind that anything that
1061
requires human interaction also requires time that might be better
1062
spent in actually fixing the problem. It is therefore in
1063
everyone's best interest that the information contained in a PR be
1064
as correct as possible (in both format and content) at the time of
1065
submission.
1066
1067
1068
File: gnats.info, Node: edit-pr, Next: query-pr, Prev: send-pr, Up: GNATS user tools
1069
1070
2.3 Editing existing Problem Reports
1071
====================================
1072
1073
Use `edit-pr' to make changes to existing PRs in the database. This
1074
tool can be invoked both from a shell prompt or from within GNU Emacs
1075
using `M-x edit-pr'.
1076
1077
`edit-pr' first examines the PR you wish to edit and locks it if it
1078
is not already locked. This is to prevent you from editing a PR at the
1079
same time as another user. If the PR you wish to edit is already in the
1080
process of being edited, `edit-pr' tells you the name of the person who
1081
owns the lock.
1082
1083
You may edit any non-readonly fields in the database. We recommend
1084
that you avoid deleting any information in the TEXT and MULTITEXT
1085
fields (such as `Description' and `How-To-Repeat' (*note Problem Report
1086
format: Fields.). We also recommend that you record the final solution
1087
to the problem in the `Fix' field for future reference. Note that
1088
heavily customized installations of GNATS may have differently named
1089
fields, and sites using such installations should provide their own set
1090
of routines and instructions regarding how PRs should be treated
1091
throughout their life span.
1092
1093
After the PR has been edited, it is then resubmitted to the database,
1094
and the index is updated (*note The `index' file: index file.). For
1095
information on `pr-edit', the main driver for `edit-pr', see *Note
1096
Internal utilities: Internal utils.
1097
1098
If you change a field that requires a reason for the change, such as
1099
the `Responsible' or `State' fields in the default configuration,
1100
`edit-pr' prompts you to supply a reason for the change. A message is
1101
then appended to the `Audit-Trail' field of the PR with the changed
1102
values and the change reason.
1103
1104
Depending on how the database is configured, editing various fields
1105
in the PR may also cause mail to be sent concerning these changes. In
1106
the default configuration, any fields that generate `Audit-Trail'
1107
entries will also cause a copy of the new `Audit-Trail' message to be
1108
sent.
1109
1110
Mail received at the PR submission email address and recognized by
1111
GNATS as relating to an existing PR is also appended to the
1112
`Audit-Trail' field, see *Note follow-up via email::.
1113
1114
* Menu:
1115
1116
* edit-pr from the shell:: Invoking `edit-pr' from the shell
1117
* follow-up via email:: Following up via direct email
1118
1119
1120
File: gnats.info, Node: edit-pr from the shell, Next: follow-up via email, Up: edit-pr
1121
1122
2.3.1 Invoking `edit-pr' from the shell
1123
---------------------------------------
1124
1125
The usage for `edit-pr' is:
1126
1127
edit-pr [ -V | --version ] [ -h | --help ]
1128
[-d DATABASE | --database DATABASE] PR NUMBER
1129
1130
Network-mode-only options:
1131
1132
[--host HOST | -H HOST] [--port PORT]
1133
[--user USER | -v USER]
1134
[--passwd PASSWD | -w PASSWD]
1135
1136
The options have the following meaning:
1137
1138
`-h, --help'
1139
Prints a brief usage message for edit-pr.
1140
1141
`-V, --version'
1142
Prints the version number for edit-pr.
1143
1144
`-d DATABASE, --database DATABASE'
1145
Specifies the database containing the PR to be edited; if no
1146
database is specified, the database named `default' is assumed.
1147
This option overrides the database specified in the `GNATSDB'
1148
environment variable.
1149
1150
`--host HOST, -H HOST'
1151
Specifies the hostname of the gnatsd server to communicate with.
1152
This overrides the value in the `GNATSDB' environment variable.
1153
1154
`--port PORT'
1155
Specifies the port number of the gnatsd server to communicate with.
1156
This overrides the value in the `GNATSDB' environment variable.
1157
1158
`--user USER, -v USER'
1159
Specifies the username to login with when connecting to the gnatsd
1160
server. This overrides the value in the `GNATSDB' environment
1161
variable.
1162
1163
`--passwd PASSWD, -w PASSWD'
1164
Specifies the password to login with when connecting to the gnatsd
1165
server. This overrides the value in the `GNATSDB' environment
1166
variable.
1167
1168
`edit-pr' calls the editor specified in your environment variable
1169
`EDITOR' on a temporary copy of that PR. (If you don't have the
1170
variable `EDITOR' defined in your environment, the default editor `vi'
1171
is used.)
1172
1173
Edit the PR, changing any relevant fields or adding to existing
1174
information. When you exit the editor, `edit-pr' prompts you on
1175
standard input for a reason if you have changed a field that requires
1176
specifying a reason for the change.
1177
1178
1179
File: gnats.info, Node: follow-up via email, Prev: edit-pr from the shell, Up: edit-pr
1180
1181
2.3.2 Following up via direct email
1182
-----------------------------------
1183
1184
If you have some additional information for a PR and for some reason do
1185
not want to (or cannot) edit the PR directly, you may append the
1186
information to the Audit-Trail field by mailing it to the PR submission
1187
address.
1188
1189
In order for GNATS to be able to recognize the mail as pertaining to
1190
an existing PR (as opposed to a new PR, see *Note Submitting via
1191
e-mail::), the Subject mail header field must contain a reference to
1192
the PR. GNATS matches the Subject header against the regular expression
1193
1194
\<(PR[ \t#/]?|[-[:alnum:]+.]+/)[0-9]+
1195
1196
to determine whether such a reference is present. Any text may precede
1197
or follow the reference in the Subject header. If more than one
1198
reference is present, the first is used and the rest ignored.
1199
1200
A PR reference matching the regular expression above has two parts.
1201
The second is the PR number (one or more digits). The first is either
1202
the capital letters 'PR' optionally followed by a separator character
1203
(blank, tab, hash mark or forward slash) or the category name followed
1204
by a forward slash. Following are some examples which match the regular
1205
expression:
1206
1207
PR 123 PR4567 PR#890 gnats/4711
1208
1209
The PR number and the category (if present) are checked for
1210
existence, and if the outcome is positive, the mail is appended to the
1211
Audit-Trail field of the PR. Note that the PR need not belong to the
1212
category because PRs may move between categories.
1213
1214
Outgoing emails sent by GNATS itself may be configured to have a
1215
Subject header field that refers to the PR in question:
1216
1217
Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT
1218
1219
This makes it extremely easy to follow up on a PR by replying to
1220
such an email, see *Note The `dbconfig' file: dbconfig file. and the
1221
sample, default `dbconfig' file installed by `mkdb'.
1222
1223
1224
File: gnats.info, Node: query-pr, Next: Emacs, Prev: edit-pr, Up: GNATS user tools
1225
1226
2.4 Querying the database
1227
=========================
1228
1229
Obtain information from the database by using the program `query-pr'.
1230
`query-pr' uses search parameters you provide to find matching Problem
1231
Reports in the database. You can invoke `query-pr' from the shell or
1232
from within Emacs. `query-pr' uses the same arguments whether it is
1233
invoked from the shell or from Emacs.
1234
1235
PRs may be selected via the use of the `--expr' option, directly by
1236
number, or by the use of the (now deprecated) field-specific query
1237
operators.
1238
1239
By default, query options are connected with a logical AND. For
1240
example,
1241
1242
query-pr --category=foo --responsible=bar
1243
1244
only prints PRs which have a Category field of `foo' and a Responsible
1245
field of `bar'.
1246
1247
The `--or' option may be used to connect query options with a logical
1248
OR. For example,
1249
1250
query-pr --category=baz --or --responsible=blee
1251
1252
prints PRs which have either a Category field of `baz' or a Responsible
1253
field of `blee'.
1254
1255
It should be emphasized, however, that the use of these
1256
field-specific options is strongly discouraged, since they exist only
1257
for compatibility with older versions of GNATS and are likely to be
1258
deleted in the next release. The expressions specified by the `--expr'
1259
option are much more flexible (see below).
1260
1261
* Menu:
1262
1263
* Invoking query-pr::
1264
* Formatting query-pr output::
1265
* Query expressions::
1266
* Example queries::
1267
1268
1269
File: gnats.info, Node: Invoking query-pr, Next: Formatting query-pr output, Up: query-pr
1270
1271
2.4.1 Invoking `query-pr'
1272
-------------------------
1273
1274
From the shell, simply type `query-pr', followed by any search
1275
parameters you wish to exercise. From Emacs, type `M-x query-pr'.
1276
`query-pr' prompts you for search parameters in the minibuffer.
1277
1278
`query-pr' can also be accessed by electronic mail, if your version
1279
of GNATS is configured for this. To use this feature, simply send mail
1280
to the address `query-pr@YOUR-SITE' with command line arguments or
1281
options in the `Subject' line of the mail header. GNATS replies to
1282
your mail with the results of your query. The default settings for the
1283
`query-pr' mail server are
1284
1285
--restricted --state="open|analyzed|feedback|suspended"
1286
1287
To override the `--state' parameter, specify `--state=STATE' in the
1288
`Subject' line of the mail header. You can not query on confidential
1289
Problem Reports by mail.
1290
1291
The usage for `query-pr' is:
1292
1293
query-pr [--debug | -D] [--help | -h] [--version | -V]
1294
[--output FILE | -o FILE] [--list-databases]
1295
[--list-fields] [--list-input-fields]
1296
[--responsible-address NAME] [--field-type FIELD]
1297
[--field-description FIELD]
1298
[--field-flags FIELD]
1299
[--adm-field FIELD] [--adm-subfield SUBFIELD]
1300
[--adm-key KEY]
1301
[--valid-values FIELD]
1302
[--format FORMAT | -f FORMAT]
1303
[--full | -F] [--summary | -q]
1304
[--database DATABASE | -d DATABASE] [--and | -&]
1305
[--or | -|] [--expr EXPR] [PR Number]
1306
1307
Non-network-mode options:
1308
1309
[--print-sh-vars] [--print-directory-for-database]
1310
1311
Network-mode-only options:
1312
1313
[--host HOST | -H HOST] [--port PORT]
1314
[--user USER | -v USER] [--passwd PASSWD | -w PASSWD]
1315
[--print-server-addr]
1316
1317
Deprecated Options:
1318
[--list-categories | -j] [--list-states | -T]
1319
[--list-responsible | -k] [--list-submitters | -l]
1320
[--category CATEGORY | -c CATEGORY]
1321
[--synopsis SYNOPSIS | -y SYNOPSIS]
1322
[--confidential CONFIDENTIAL | -C CONFIDENTIAL]
1323
[--multitext MULTITEXT | -m MULTITEXT]
1324
[--originator ORIGINATOR | -O ORIGINATOR]
1325
[--release RELEASE | -A RELEASE]
1326
[--class CLASS | -L CLASS] [--cases CASES | -E CASES]
1327
[--quarter QUARTER | -Q QUARTER]
1328
[--keywords KEYWORDS | -K KEYWORDS]
1329
[--priority PRIORITY | -p PRIORITY]
1330
[--responsible RESPONSIBLE | -r RESPONSIBLE]
1331
[--restricted | -R] [--severity SEVERITY | -e SEVERITY]
1332
[--skip-closed | -x] [--sql | -i] [--sql2 | -I]
1333
[--state STATE | -s STATE]
1334
[--submitter SUBMITTER | -S SUBMITTER]
1335
[--text TEXT | -t TEXT]
1336
[--required-before DATE | -u DATE]
1337
[--required-after DATE | -U DATE]
1338
[--arrived-before DATE | -b DATE]
1339
[--arrived-after DATE | -a DATE]
1340
[--modified-before DATE | -B DATE]
1341
[--modified-after DATE | -M DATE]
1342
[--closed-before DATE | -z DATE]
1343
[--closed-after DATE | -Z DATE]
1344
1345
The options have the following meaning:
1346
`--help, -h'
1347
Prints a help message.
1348
1349
`--version, -V'
1350
Displays the program version to stdout.
1351
1352
`--output FILE, -o FILE'
1353
The results of the query will be placed in this file.
1354
1355
`--database DATABASE, -d DATABASE'
1356
Specifies the database to be used for the query. If no database is
1357
specified, the database named default is assumed. (This option
1358
overrides the database specified in the `GNATSDB' environment
1359
variable; see *Note Environment:: for more information.)
1360
1361
`--list-categories, -j'
1362
Lists the available PR categories for the selected database.
1363
1364
`--list-states, -T'
1365
Lists the valid PR states for PRs in this database.
1366
1367
`--list-responsible, -k'
1368
Lists the users that appear in the database's responsible list.
1369
1370
`--list-submitters, -l'
1371
Lists the valid submitters for this database.
1372
1373
The previous -list-* options are deprecated and may be removed in
1374
future releases of GNATS; their functionality can be replaced with
1375
1376
query-pr --valid-values FIELD
1377
1378
where FIELD is one of `Category', `Class', `Responsible',
1379
`Submitter-Id', or `State'.
1380
1381
`--list-databases'
1382
Lists the known databases.
1383
1384
`--list-fields'
1385
Lists the entire set of field names for PRs in the selected
1386
database.
1387
1388
`--list-input-fields'
1389
Lists the fields that should be provided when creating a new PR
1390
for the currently-specified database. The fields are listed in an
1391
order that would make sense when used in a template or form.
1392
1393
`--field-type FIELD'
1394
Returns the data type contained in PR field FIELD. The current
1395
set of data types includes `text', `multitext', `enum',
1396
`multienum', `enumerated-in-file', `multi-enumerated-in-file',
1397
`date' and `integer'.
1398
1399
`--field-description FIELD'
1400
Returns a human-readable description of the intended purpose of
1401
FIELD.
1402
1403
`--field-flags FIELD'
1404
Returns the flags set for the field in the `dbconfig' file
1405
associated with the database, such as `textsearch' and `readonly'.
1406
*Note Individual field configuration::.
1407
1408
`--adm-field FIELD'
1409
Used together with the `--adm-key' option, this returns a record
1410
from the administrative file (if any) associated with the field.
1411
For more material on administrative files, see *Note Enumerated
1412
field administrative files: administrative files.
1413
1414
`--adm-subfield SUBFIELD'
1415
Used together with the `--adm-field' and `--adm-key' options, this
1416
returns the contents of a particular subfield from the record
1417
specified by `--adm-field' and `--adm-key'. Subfields are treated
1418
in *Note Enumerated field administrative files: administrative
1419
files.
1420
1421
`--adm-key KEY'
1422
Used together with `--adm-field' to select a record from the
1423
administrative file associated with the field specified by
1424
`--adm-field'. *Note Enumerated field administrative files:
1425
administrative files.
1426
1427
`--valid-values FIELD'
1428
For fields of type `enum', a list of valid values (one per line) is
1429
returned. Otherwise, a regular expression is returned that
1430
describes the legal values in FIELD.
1431
1432
`--responsible-address NAME'
1433
The mail address of NAME is returned; NAME is assumed to be a name
1434
either appearing in the database's responsible list, or is
1435
otherwise a user on the system.
1436
1437
`--print-sh-vars'
1438
A set of `/bin/sh' variables is returned that describe the selected
1439
database. They include:
1440
1441
`GNATSDB'
1442
The name of the currently-selected database.
1443
1444
`GNATSDB_VALID'
1445
Set to 1 if the selected database is valid.
1446
1447
`GNATSDBDIR'
1448
The directory where the database contents are stored.
1449
1450
`DEBUG_MODE'
1451
Set to 1 if debug mode has been enabled for the database.
1452
1453
`DEFAULTCATEGORY'
1454
The default category for PRs in the database.
1455
1456
`DEFAULTSTATE'
1457
The default state for PRs in the database.
1458
1459
`--print-server-addr'
1460
Prints the information about a remote server database in the format
1461
suitable for the `GNATSDB' environment variable. This option
1462
works only in the network mode.
1463
1464
`--print-directory-for-database'
1465
Returns the directory where the selected database is located.
1466
1467
`--format FORMAT, -f FORMAT'
1468
Used to specify the format of the output PRs, See *Note Formatting
1469
query-pr output:: for a complete description.
1470
1471
`--full, -F'
1472
When printing PRs, the entre PR is displayed. This is exactly
1473
equivalent to
1474
1475
query-pr --format full
1476
1477
`--summary, -q'
1478
When printing PRs, a summary format is used. This is exactly
1479
equivalent to
1480
1481
query-pr --format SUMMARY
1482
1483
`--debug, -D'
1484
Enables debugging output for network queries.
1485
1486
`--host HOST, -H HOST'
1487
Specifies the hostname of the gnatsd server to communicate with.
1488
This overrides the value in the `GNATSDB' environment variable.
1489
1490
`--port PORT'
1491
Specifies the port number of the gnatsd server to communicate with.
1492
This overrides the value in the `GNATSDB' environment variable.
1493
1494
`--user USER, -v USER'
1495
Specifies the username to login with when connecting to the gnatsd
1496
server. This overrides the value in the `GNATSDB' environment
1497
variable.
1498
1499
`--passwd PASSWD, -w PASSWD'
1500
Specifies the password to login with when connecting to the gnatsd
1501
server. This overrides the value in the `GNATSDB' environment
1502
variable.
1503
1504
`--and, -&, --or, -|'
1505
These options are used when connecting multiple query operators
1506
together. They specify whether the previous and subsequent
1507
options are to be logically ANDed or logically ORed.
1508
1509
`--expr EXPR'
1510
Specifies a query expression to use when searching for PRs. *Note
1511
Query expressions::.
1512
1513
The remaining deprecated options are not described here, since their
1514
use is fairly obvious and their functionality is completely replaced by
1515
the use of the `--expr' option.
1516
1517
1518
File: gnats.info, Node: Formatting query-pr output, Next: Query expressions, Prev: Invoking query-pr, Up: query-pr
1519
1520
2.4.2 Formatting `query-pr' output
1521
----------------------------------
1522
1523
Printing formats for PRs are in one of three forms:
1524
1525
FORMATNAME
1526
This is a named format which is described by the database
1527
(specifically, these formats are described in the `dbconfig' file
1528
associated with the database). The default configuration contains
1529
five such formats: `standard', `full', `summary', `sql', and
1530
`sql2'.
1531
1532
The first three are the ones most commonly used when performing
1533
queries. standard is the format used by default if no other
1534
format is specified.
1535
1536
Use of the latter two are discouraged; they are merely kept for
1537
historical purposes. Other named formats may have been added by
1538
the database administrator.
1539
1540
FIELDNAME
1541
A single field name may appear here. Only the contents of this
1542
field will be displayed.
1543
1544
'"PRINTF STRING" FIELDNAME FIELDNAME ...'
1545
This provides a very flexible mechanism for formatting PR output.
1546
(The formatting is identical to that provided by the named formats
1547
described by the database configuration, *Note Named query
1548
definitions::. The PRINTF STRING can contain the following %
1549
sequences:
1550
1551
`%[positionalspecifiers]s': Prints the field as a string. The
1552
positional specifiers are similar to those of printf, as +, - and
1553
digit qualifiers can be used to force a particular alignment of
1554
the field contents.
1555
1556
`%[positionalspecifiers]S': Similar to `%s', except that the field
1557
contents are terminated at the first space character.
1558
1559
`%[positionalspecifiers]d': Similar to `%s', except that the field
1560
contents are written as a numeric value. For integer fields, the
1561
value is written as a number. For enumerated fields, the field is
1562
converted into a numeric equivalent (i.e. if the field can have two
1563
possible values, the result will be either 1 or 2). For date
1564
fields, the value is written as seconds since Jan 1, 1970.
1565
1566
`%F': The field is written as it would appear within a PR, complete
1567
with field header.
1568
1569
`%D': For date fields, the date is written in a standard GNATS
1570
format.
1571
1572
`%Q': For date fields, the date is written in an arbitrary "SQL"
1573
format.
1574
1575
An example formatted query looks as follows (note that the whole
1576
format specification should be quoted):
1577
1578
query-pr --format '"%s, %s" Synopsis State'
1579
1580
1581
File: gnats.info, Node: Query expressions, Next: Example queries, Prev: Formatting query-pr output, Up: query-pr
1582
1583
2.4.3 Query expressions
1584
-----------------------
1585
1586
Query expressions are used to select specific PRs based on their field
1587
contents. The general form is
1588
1589
fieldname|"value" operator fieldname|"value" [booleanop ...]
1590
1591
VALUE is a literal string or regular expression; it must be
1592
surrounded by double quotes, otherwise it is interpreted as a fieldname.
1593
1594
FIELDNAME is the name of a field in the PR.
1595
1596
OPERATOR is one of:
1597
1598
`='
1599
The value of the left-hand side of the expression must exactly
1600
match the regular expression on the right-hand side of the
1601
expression. *Note Querying using regular expressions: Regexps.
1602
1603
`~'
1604
Some portion of the left-hand side of the expression must match the
1605
regular expression on the right-hand side.
1606
1607
`=='
1608
The value of the left-hand side must be equal to the value on the
1609
right-hand side of the expression.
1610
1611
The equality of two values depends on what type of data is stored
1612
in the field(s) being queried. For example, when querying a field
1613
containing integer values, literal strings are interpreted as
1614
integers. The query expression
1615
1616
Number == "0123"
1617
1618
is identical to
1619
1620
Number == "123"
1621
1622
as the leading zero is ignored. If the values were treated as
1623
strings instead of integers, then the two comparisons would return
1624
different results.
1625
1626
`!='
1627
The not-equal operator. Produces the opposite result of the ==
1628
operator.
1629
1630
`<,>'
1631
The left-hand side must have a value less than or greater than the
1632
right-hand side. Comparisons are done depending on the type of
1633
data being queried; in particular, integer fields and dates use a
1634
numeric comparison, and enumerated fields are ordered depending on
1635
the numeric equivalent of their enumerated values.
1636
1637
BOOLEANOP is either `|' (logical or), or `&' (logical and). The
1638
query expression
1639
1640
Category="baz" | Responsible="blee"
1641
1642
selects all PRs with a Category field of `baz' or a Responsible field
1643
of `blee'.
1644
1645
The not operator `!' may be used to negate a test:
1646
1647
! Category="foo"
1648
1649
searches for PRs where the category is not equal to the regular
1650
expression foo.
1651
1652
Parentheses may be used to force a particular interpretation of the
1653
expression:
1654
1655
!(Category="foo" & Submitter-Id="blaz")
1656
1657
skips PRs where the Category field is equal to `foo' and the
1658
Submitter-Id field is equal to `blaz'. Parentheses may be nested to
1659
any arbitrary depth.
1660
1661
Fieldnames can be specified in several ways. The simplest and most
1662
obvious is just a name:
1663
1664
Category="foo"
1665
1666
which checks the value of the category field for the value FOO.
1667
1668
A fieldname qualifier may be prepended to the name of the field; a
1669
colon is used to separate the qualifier from the name. To refer
1670
directly to a builtin field name:
1671
1672
builtin:Number="123"
1673
1674
In this case, `Number' is interpreted as the builtin name of the
1675
field to check. (This is useful if the fields have been renamed. For
1676
further discussion of builtin field names, see *Note The `dbconfig'
1677
file: dbconfig file.
1678
1679
To scan all fields of a particular type, the FIELDTYPE qualifier may
1680
be used:
1681
1682
fieldtype:Text="bar"
1683
1684
This searches all text fields for the regular expression `bar'.
1685
1686
Note that it is not required that the right-hand side of the
1687
expression be a literal string. To query all PRs where the PR has been
1688
modified since it was closed, the expression
1689
1690
Last-Modified != Closed-Date
1691
1692
will work; for each PR, it compares the value of its Last-Modified field
1693
against its Closed-Date field, and returns those PRs where the values
1694
differ. However, this query will also return all PRs with empty
1695
Last-Modified or Closed-Date fields. To further narrow the search:
1696
1697
Last-Modified != Closed-Date & Last-Modified != "" & Closed-Date != ""
1698
1699
In general, comparing fields of two different types (an integer field
1700
against a date field, for example) will probably not do what you want.
1701
1702
Also, a field specifier may be followed by the name of a subfield in
1703
braces:
1704
1705
State[type] != "closed"
1706
1707
or even
1708
1709
builtin:State[type] != "closed"
1710
1711
Subfields are further discussed in *Note The `dbconfig' file: dbconfig
1712
file.
1713
1714
1715
File: gnats.info, Node: Example queries, Prev: Query expressions, Up: query-pr
1716
1717
2.4.4 Example queries
1718
---------------------
1719
1720
The following simple query:
1721
1722
query-pr --expr 'Category~"rats" & State~"analyzed"
1723
& Responsible~"fred"'
1724
1725
yields all PRs in the database which contain the field values:
1726
1727
>Category: rats _and_
1728
>Responsible: fred _and_
1729
>State: analyzed
1730
1731
The following query:
1732
1733
query-pr --expr 'State~"open|analyzed"'
1734
1735
yields all PRs in the database whose `State' values match either `open'
1736
or `analyzed' (*note Querying using regular expressions: Regexps. This
1737
search is useful as a daily report that lists all Problem Reports which
1738
require attention.
1739
1740
The following query:
1741
1742
query-pr --expr 'fieldtype:Text="The quick.*brown fox"'
1743
1744
yields all PRs whose TEXT fields contain the text `The quick' followed
1745
by `brown fox' within the same field. *Note Querying using regular
1746
expressions: Regexps, which also contains further useful examples of
1747
query expressions.
1748
1749
1750
File: gnats.info, Node: Emacs, Prev: query-pr, Up: GNATS user tools
1751
1752
2.5 The Emacs interface to GNATS
1753
================================
1754
1755
Emacs interface to GNATS provides basic access to GNATS databases, i.e.
1756
sending, editing, and querying Problem Reports. It also defines a
1757
simple major mode for editing `dbconfig' files.
1758
1759
This section provides an overview of using GNATS with Emacs. It
1760
does not describe the use of Emacs itself, for detailed instructions on
1761
using Emacs, see *Note Top: (emacs)Top. For installation instructions
1762
of the GNATS Emacs mode, see *Note Installing utils::.
1763
1764
Please note the Emacs interface was completely rewritten between
1765
GNATS 3 and GNATS 4. It now uses `gnatsd', *Note gnatsd::, exclusively
1766
for its operations and uses modern Emacs features like faces. Its
1767
features are not complete though, you can send your suggestions and
1768
patches to the appropriate GNATS mailing list, *Note Support::.
1769
1770
* Menu:
1771
1772
* Emacs viewing:: Viewing PRs by their number.
1773
* Emacs querying:: Querying the database.
1774
* Emacs submitting:: Submitting new PRs.
1775
* Emacs editing:: Editing PRs.
1776
* Emacs editing buffer:: The editing buffer.
1777
* Emacs and databases:: Changing the working database.
1778
* dbconfig mode:: Major mode for dbconfig files.
1779
* Other Emacs commands:: Miscellaneous commands.
1780
* Emacs customization:: Customizing the Emacs interface.
1781
1782
1783
File: gnats.info, Node: Emacs viewing, Next: Emacs querying, Up: Emacs
1784
1785
2.5.1 Viewing Problem Reports
1786
-----------------------------
1787
1788
To view a particular Problem Report, use the command `M-x view-pr'. It
1789
asks for a Problem Report number and displays that Problem Report.
1790
1791
The displayed buffer is put in the view mode, *Note Misc File Ops:
1792
(emacs)Misc File Ops. If you decide to edit the displayed Problem
1793
Report, use the command `e' (`gnats-view-edit-pr').
1794
1795
`gnats-view-mode-hook'
1796
Hook run when `gnats-view-mode' is entered.
1797
1798
1799
File: gnats.info, Node: Emacs querying, Next: Emacs submitting, Prev: Emacs viewing, Up: Emacs
1800
1801
2.5.2 Querying Problem Reports
1802
------------------------------
1803
1804
Querying the database is performed by the `M-x query-pr' command. The
1805
command prompts for the query expression, *Note Query expressions::,
1806
and displays a buffer with the list of the matching Problem Reports.
1807
1808
The list of the Problem Reports is displayed in the `summary' query
1809
format, *Note Formatting query-pr output::. Currently, the display
1810
format cannot be changed and it must output each Problem Report's
1811
number in the first column.
1812
1813
The Problem Report list buffer is put in the view mode, *Note Misc
1814
File Ops: (emacs)Misc File Ops. You can use most of the standard view
1815
mode commands in it. Additionally, the following special commands are
1816
available:
1817
1818
`v'
1819
`RET'
1820
`mouse-2'
1821
View the current Problem Report (`gnats-query-view-pr'), *Note
1822
Emacs viewing::.
1823
1824
`e'
1825
Edit the current Problem Report (`gnats-query-edit-pr'), *Note
1826
Emacs editing::.
1827
1828
`g'
1829
Update the Problem Report list (`gnats-query-reread'). The last
1830
performed query is executed again and the buffer is filled with the
1831
new results.
1832
1833
`G'
1834
Perform new query (`query-pr').
1835
1836
`s'
1837
Send new Problem Report (`send-pr'), *Note Emacs submitting::.
1838
1839
`D'
1840
Change the current database (`gnats-change-database'), *Note Emacs
1841
and databases::.
1842
1843
`q'
1844
Bury buffer, the buffer is put at the end of the list of all
1845
buffers. This is useful for quick escape of the buffer, without
1846
killing it.
1847
1848
If the value of the variable GNATS-QUERY-REVERSE-LISTING is
1849
non-`nil', the listing appears in the reversed order, i.e. with the
1850
Problem Reports of the highest number first, in the buffer.
1851
1852
Similarly to other GNATS Emacs modes, there is a hook available for
1853
the Problem Report list.
1854
1855
`gnats-query-mode-hook'
1856
Hook run when `gnats-query-mode' is entered.
1857
1858
1859
File: gnats.info, Node: Emacs submitting, Next: Emacs editing, Prev: Emacs querying, Up: Emacs
1860
1861
2.5.3 Submitting new Problem Reports
1862
------------------------------------
1863
1864
You can submit new Problem Reports with the command `M-x send-pr'. The
1865
command puts you to the problem editing buffer, *Note Emacs editing::.
1866
The buffer is prefilled with the initial report fields and their
1867
default values, if defined. You can use the usual Problem Report
1868
editing commands, *Note Emacs editing::. When you have filled in all
1869
the fields, you can send the Problem Report by presing `C-c C-c'.
1870
1871
If you run `M-x send-pr' with a prefix argument, it runs the
1872
`gnats-change-database' command before putting you to the editing
1873
buffer, *Note Emacs and databases::.
1874
1875
You can set the following variables to get some fields pre-filled:
1876
1877
GNATS-DEFAULT-ORGANIZATION
1878
Default value of the `Organization' field used in new Problem
1879
Reports.
1880
1881
GNATS-DEFAULT-SUBMITTER
1882
Default value of the `Submitter-Id' field used in new Problem
1883
Reports.
1884
1885
1886
File: gnats.info, Node: Emacs editing, Next: Emacs editing buffer, Prev: Emacs submitting, Up: Emacs
1887
1888
2.5.4 Editing Problem Reports
1889
-----------------------------
1890
1891
To edit a particular Problem Report, use the command `M-x edit-pr'. It
1892
asks for a Problem Report number and puts the given Problem Report in
1893
the editing buffer. *Note Emacs editing buffer::, for information how
1894
to edit the Problem Report in the buffer and how to submit your changes.
1895
1896
Note you can also start editing of a selected Problem Report directly
1897
from within the viewing buffer, *Note Emacs viewing::, or the query
1898
result buffer, *Note Emacs querying::.
1899
1900
1901
File: gnats.info, Node: Emacs editing buffer, Next: Emacs and databases, Prev: Emacs editing, Up: Emacs
1902
1903
2.5.5 The Problem Report editing buffer
1904
---------------------------------------
1905
1906
When you invoke a Problem Report editing command, the Problem Report is
1907
put into a special editing buffer. The Problem Report is formatted
1908
similarly to the `query-pr -F' output, *Note Formatting query-pr
1909
output::. Field identifiers are formatted as
1910
1911
>Field:
1912
1913
with the text of the field following the identifier on the same line
1914
for single-line fields or starting on the next line for multi-line
1915
fields.
1916
1917
The Problem Report editing mode tries to prevent you from violating
1918
the Problem Report format and the constraints put on the possible field
1919
values. Generally, you can use usual editing commands, some of them
1920
have a slightly modified behavior though. (If you encounter a very
1921
strange behavior somewhere, please report it as a bug, *Note Support::.)
1922
1923
You can move between fields easily by pressing the `TAB'
1924
(`gnats-next-field') or `M-TAB' (`gnats-previous-field') keys.
1925
1926
The field tags are read-only and you cannot edit them nor delete
1927
them. If you want to "remove" a field, just make its value empty.
1928
1929
Editing a field value depends on the type of the edited field, *Note
1930
Field datatypes::. For text fields, you can edit the value directly,
1931
assuming you preserve the rule about single-line and multi-line values
1932
mentioned above.
1933
1934
For enumerated fields, you cannot edit the value directly. You can
1935
choose it from the list of the allowed values, either from the menu
1936
popped up by pressing the middle mouse button or from within minibuffer
1937
by pressing any key on the field's value. If the pressed key matches
1938
any of the allowed field values, that value is put as the default value
1939
after the minibuffer prompt. You can also cycle through the allowed
1940
field values directly in the editing buffer using the `SPACE' key.
1941
Enumerated field values are marked by a special face to not confuse
1942
you; you must have enabled font lock mode to benefit from this feature,
1943
*Note Font Lock: (emacs)Font Lock.
1944
1945
Some field values can be read-only, you cannot edit them at all.
1946
1947
Once you have edited the Problem Report as needed, you can send it to
1948
the server with the `C-c C-c' command (`gnats-apply-or-submit').
1949
Successful submission is reported by a message and the buffer
1950
modification flag in mode line is cleared. Then you can either kill
1951
the buffer or continue with further modifications.
1952
1953
`gnats-edit-mode-hook'
1954
Hook run when `gnats-edit-mode' is entered.
1955
1956
1957
File: gnats.info, Node: Emacs and databases, Next: dbconfig mode, Prev: Emacs editing buffer, Up: Emacs
1958
1959
2.5.6 Changing the database
1960
---------------------------
1961
1962
By default, the Emacs interface connects to the default database, *Note
1963
databases file::. If you want to connect to another database, use the
1964
command `M-x gnats-change-database'. It will ask you for the database
1965
name to use, server and port it can be accessed on, and your login name.
1966
1967
If you want to use the `gnatsd' command, *Note gnatsd::, directly,
1968
without connecting to a remote server or the localhost connection port,
1969
provide your local file system full path to `gnatsd' as the server
1970
name. Port number does not matter in this case.
1971
1972
If the database requires a password to allow you the access to it,
1973
you are prompted for the password the first time you connect to the
1974
database. If you provide an invalid password, you cannot connect to
1975
the database anymore and you have to run the `M-x
1976
gnats-change-database' command again.
1977
1978
1979
File: gnats.info, Node: dbconfig mode, Next: Other Emacs commands, Prev: Emacs and databases, Up: Emacs
1980
1981
2.5.7 dbconfig mode
1982
-------------------
1983
1984
The Emacs interface defines a simple major mode `gnats-dbconfig-mode'
1985
for editing `dbconfig' files, *Note dbconfig file::. It defines basic
1986
mode attributes like character syntax and font lock keywords, it does
1987
not define any special commands now.
1988
1989
`gnats-dbconfig-mode-hook'
1990
Hook run when `gnats-dbconfig-mode' is entered.
1991
1992
1993
File: gnats.info, Node: Other Emacs commands, Next: Emacs customization, Prev: dbconfig mode, Up: Emacs
1994
1995
2.5.8 Other commands
1996
--------------------
1997
1998
`M-x unlock-pr'
1999
Ask for a Problem Report number and unlock that Problem Report.
2000
This function is useful if connection to a GNATS server was
2001
interrupted during an editing operation and further modifications
2002
of the Problem Report are blocked by a stealth lock.
2003
2004
`M-x unlock-database'
2005
Unlock the whole GNATS database. This function is useful in
2006
situations similar to when `unlock-pr' is used.
2007
2008
`M-x gnats-show-connection'
2009
Show the connection buffer associated with the current buffer. You
2010
can view the Emacs communication with GNATSD in it. This is
2011
useful when something strange happens during the communication with
2012
the server, e.g. when sending a Problem Report with `C-c C-c' from
2013
a Problem Report editing buffer.
2014
2015
2016
File: gnats.info, Node: Emacs customization, Prev: Other Emacs commands, Up: Emacs
2017
2018
2.5.9 Customization
2019
-------------------
2020
2021
All the user variables can be customized in the customization group
2022
`gnats', *Note Easy customization: (emacs)Easy customization.
2023
2024
2025
File: gnats.info, Node: Installation, Next: Management, Prev: GNATS user tools, Up: Top
2026
2027
3 Installing GNATS
2028
******************
2029
2030
See also *Note Where the tools and utilities reside: Locations.
2031
2032
There are several steps you need to follow to fully configure and
2033
install GNATS on your system. You need `root' access in order to
2034
create a new account for `gnats' and to install the GNATS utilities.
2035
You may need `root' access on some systems in order to set up mail
2036
aliases and to allow this new account access to `cron' and `at'.
2037
2038
If you are updating an older version of GNATS rather than installing
2039
from scratch, see *Note Upgrading from older versions: Upgrading.
2040
2041
GNATS installation relies on two other freely available software
2042
packages, which should be installed before you go on to configure and
2043
build GNATS. These are GNU `make' and `Texinfo' (version 4.2 or
2044
higher). Both are available from the GNU FTP site at
2045
`ftp://ftp.gnu.org'.
2046
2047
To build and install GNATS, you must:
2048
2049
* Run `configure', with correct options if the defaults are
2050
unsuitable for your site. *Note Configuring and compiling the
2051
software: Configure and make. Default installation locations are
2052
in *Note Where GNATS lives: Locations.
2053
2054
* Compile the GNATS programs on your system. *Note Configuring and
2055
compiling the software: Configure and make.
2056
2057
* Create an initial database by using the `mkdb' command. *Note
2058
Setting up the default database::.
2059
2060
* Set up periodic jobs, using cron, to handle Problem Reports
2061
arriving by mail. *Note Setting up periodic jobs::.
2062
2063
* Set up mail aliases for GNATS. *Note Setting up mail aliases:
2064
Aliases.
2065
2066
* Install the GNATS tools and utilities locally, and install the user
2067
tools (`query-pr', `edit-pr', `send-pr') on every machine in your
2068
local network. *Note Installing the user tools: Installing tools.
2069
2070
* Install the GNATS daemon `gnatsd'. *Note Installing the daemon::.
2071
2072
* If there are people outside your organization who will be
2073
submitting PRs or who are supposed to be able to query and/or edit
2074
PRs, you may need to instruct them to obtain and build the GNATS
2075
tools `query-pr', `edit-pr' and `send-pr' for their systems.
2076
However, for many sites, setting up a remote access interface to
2077
GNATS, such as Gnatsweb is a better solution since this requires
2078
no configuration on the remote side.
2079
2080
* Menu:
2081
2082
* Configure and make:: Configuring and compiling the software
2083
* Installing utils:: Installing the utilities
2084
* Setting up the default database:: Setting up the default database
2085
* Setting up periodic jobs:: Setting up periodic jobs
2086
* Aliases:: Setting up mail aliases
2087
* Installing the daemon:: Installing the daemon
2088
* Installing tools:: Installing the user tools
2089
* Upgrading:: Upgrading from older versions
2090
2091
2092
File: gnats.info, Node: Configure and make, Next: Installing utils, Up: Installation
2093
2094
3.1 Configuring and compiling the software
2095
==========================================
2096
2097
1. First, unpack your distribution. We provide source code in a `tar'
2098
file which was compressed using `gzip'. The code can be extracted
2099
into a directory UNPACKDIR using
2100
2101
cd UNPACKDIR
2102
gunzip gnats-4.1.0.tar.gz
2103
tar xvf gnats-4.1.0.tar
2104
2105
The sources reside in a directory called `gnats-4.1.0' when
2106
unpacked. We call this the "top level" of the source directory,
2107
or "srcdir". The sources for the GNATS tools are in the
2108
subdirectory `gnats-4.1.0/gnats/*'. Lists of files included in
2109
the distribution are in each directory in the file `MANIFEST'.
2110
2111
2. As of GNATS version 4, having Emacs installed on the GNATS server
2112
is no longer a requirement. If you do not have Emacs installed,
2113
disregard this step altogether.
2114
2115
You may wish to alter the installation directory for the Emacs lisp
2116
files. If your Emacs lisp library is not in
2117
`PREFIX/share/emacs/site-lisp', edit the file
2118
`SRCDIR/gnats/Makefile.in'. Change the variable `lispdir' from
2119
`PREFIX/emacs/site-lisp' to the directory containing your Emacs
2120
lisp library. For information on PREFIX, see *Note PREFIX: prefix.
2121
2122
3. Create an account for the `gnats' user. You can actually name this
2123
user whatever you want to, as long as it is a valid username on
2124
your system, but we strongly recommend that you call the user
2125
`gnats'. If you do decide to give it some other name, remember to
2126
use the option `--with-gnats-user' when running `configure' below.
2127
Below, we will anyway refer to this user by the name `gnats'.
2128
2129
This user must have an entry in the file `/etc/passwd'. As for
2130
ordinary users, create a standard home directory for the `gnats'
2131
user. The default `PATH' for this user should contain
2132
`EXEC-PREFIX/bin' and `EXEC-PREFIX/libexec/gnats'. The
2133
EXEC-PREFIX value is configurable with the `--exec-prefix'
2134
configure option described below, but for standard installations,
2135
these two directories correspond to `/usr/local/bin' and
2136
`/usr/local/libexec/gnats'.
2137
2138
4. Run `configure'. You can nearly always run `configure' with the
2139
simple command
2140
2141
./configure
2142
2143
and the "Right Thing" happens:
2144
2145
* GNATS is configured in the same directory you unpacked it in;
2146
2147
* when built, GNATS runs on the machine you're building it on;
2148
2149
* when installed, files are installed under `/usr/local' (*note
2150
Where GNATS lives: Locations.).
2151
2152
* all GNATS utilities operate on the "default database", assumed
2153
to be named _default_ and to be located in
2154
`/usr/local/com/default', unless you invoke the utilities with
2155
`-d' DATABASENAME or `--directory='DATABASENAME, or set the
2156
GNATSDB environment variable to point to some other database.
2157
2158
The most common options to `configure' are listed below:
2159
2160
configure [ --prefix=PREFIX ]
2161
[ --exec-prefix=EXEC-PREFIX ]
2162
[ --with-gnats-service=SERVICE-NAME ]
2163
[ --with-gnats-user=USERNAME ]
2164
[ --with-gnatsd-user-access-file=PATH ]
2165
[ --with-gnatsd-host-access-file=PATH ]
2166
[ --with-gnats-dblist-file=PATH ]
2167
[ --with-gnats-default-db=PATH ]
2168
[ --with-kerberos ] [ --with-krb4 ]
2169
[ --verbose ]
2170
2171
`--prefix=PREFIX'
2172
All host-independent programs and files are to be installed
2173
under PREFIX. (Host-dependent programs and files are also
2174
installed in PREFIX by default.) The default for PREFIX is
2175
`/usr/local'. *Note Where GNATS lives: Locations.
2176
2177
`--exec-prefix=EXEC-PREFIX'
2178
All host-dependent programs and files are to be installed
2179
under EXEC-PREFIX. The default for EXEC-PREFIX is PREFIX.
2180
*Note Where GNATS lives: Locations.
2181
2182
`--with-gnats-service=SERVICE-NAME'
2183
Set SERVICE-NAME to be the GNATS network service. Default
2184
name is SUPPORT.
2185
2186
`--with-gnats-user=USERNAME'
2187
Set USERNAME to be the user name for GNATS. Default username
2188
is GNATS.
2189
2190
`--with-gnatsd-user-access-file=PATH'
2191
Set global (across all databases) gnatsd user access file to
2192
PATH. Default is `/USR/LOCAL/ETC/GNATS/GNATSD.USER_ACCESS'.
2193
Per-database user access permissions are set in a
2194
`gnatsd.user_access' file in the `gnats-adm' subdirectory of
2195
each database.
2196
2197
`--with-gnatsd-host-access-file=PATH'
2198
Set global (across all databases) gnatsd host access file to
2199
PATH. Default is `/usr/local/etc/gnats/gnatsd_host.access'.
2200
There is currently no way to specify host access permissions
2201
on a per-database basis.
2202
2203
`--with-gnats-dblist-file=PATH'
2204
Specify the file containing the list of databases.
2205
2206
Default is `PREFIX/etc/gnats/databases'.
2207
2208
`--with-gnats-default-db=PATH'
2209
Specify the default database to use when GNATS tools are
2210
invoked without the `-d' or `--databasename' option, and when
2211
the GNATSDB envrionment variable hasn't been set. Default is
2212
`/PREFIX/com/gnatsdb'.
2213
2214
`--with-kerberos'
2215
Include code for Kerberos authentication.
2216
2217
`--with-krb4'
2218
Support Kerberos 4.
2219
2220
`--verbose'
2221
Give verbose output while `configure' runs.
2222
2223
`configure' supports several more options which allow you to
2224
specify in great detail where files are installed. For a complete
2225
list of options, run `./configure --help' in the source directory.
2226
2227
You can build GNATS in a different directory (OBJDIR) from the
2228
source code by calling the `configure' program from the new
2229
directory, as in
2230
2231
mkdir OBJDIR
2232
cd OBJDIR
2233
SRCDIR/configure ...
2234
2235
By default, `make' compiles the programs in the same directory as
2236
the sources (SRCDIR).
2237
2238
5. Make sure you have GNU `make', then run
2239
2240
make all info
2241
2242
from the directory where `configure' created a `Makefile' (this is
2243
OBJDIR if you used it, otherwise SRCDIR.) These targets indicate:
2244
2245
`all'
2246
Compile all programs
2247
2248
`info'
2249
Create `info' files using `makeinfo'.
2250
2251
2252
File: gnats.info, Node: Installing utils, Next: Setting up the default database, Prev: Configure and make, Up: Installation
2253
2254
3.2 Installing the utilities
2255
============================
2256
2257
The following steps are necessary for a complete installation. You may
2258
need `root' access for these.
2259
2260
1. Install the utilities by invoking
2261
2262
make install install-info
2263
2264
These targets indicate:
2265
2266
`install'
2267
Installs all programs into their configured locations (*note
2268
Where GNATS lives: Locations.).
2269
2270
`install-info'
2271
Installs `info' files into their configured locations (*note
2272
Where GNATS lives: Locations.).
2273
2274
After you have installed GNATS, you can remove the object files
2275
with
2276
2277
make clean
2278
2279
2. If you do not have Emacs installed on your GNATS server, this step
2280
should be skipped.
2281
2282
Place the following lines in the file `default.el' in your Emacs
2283
lisp library, or instruct your local responsible parties to place
2284
the lines in their `.emacs':
2285
2286
(autoload 'send-pr "gnats"
2287
"Command to create and send a problem report." t)
2288
(autoload 'edit-pr "gnats"
2289
"Command to edit a problem report." t)
2290
(autoload 'view-pr "gnats"
2291
"Command to view a problem report." t)
2292
(autoload 'query-pr "gnats"
2293
"Command to query information about problem reports." t)
2294
(autoload 'unlock-pr "gnats"
2295
"Unlock a problem report." t)
2296
(autoload 'gnats-dbconfig-mode "gnats"
2297
"Major mode for editing the `dbconfig' GNATS configuration file." t)
2298
(add-to-list 'auto-mode-alist '("\\<dbconfig$" . gnats-dbconfig-mode))
2299
2300
3. If you want people who are logged into the GNATS server itself to
2301
be able to use the `send-pr' tool to submit problem reports, you
2302
need to create a configuration file for `send-pr' on the server.
2303
*Note The send-pr.conf configuration file: send-pr.conf file.
2304
2305
2306
2307
File: gnats.info, Node: Setting up the default database, Next: Setting up periodic jobs, Prev: Installing utils, Up: Installation
2308
2309
3.3 Installing the default database
2310
===================================
2311
2312
For the following steps, log in as the user `gnats'.
2313
2314
We are now going to initialize the default GNATS database. Run the
2315
following command:
2316
2317
mkdb default
2318
2319
This creates a database named `default', with all its data stored
2320
below the directory `PREFIX/com/gnatsdb', in a default installation
2321
this corresponds to `/usr/local/com/gnatsdb'. If you specified the
2322
`--with-gnats-default-db' option when running configure, the default
2323
database will be created under the directory you specified instead.
2324
`mkdb' creates the database directory itself, together with three
2325
different subdirectories(1):
2326
2327
* A directory for the mandatory GNATS category PENDING.
2328
2329
* A `gnats-queue' directory for queueing new messages to GNATS
2330
before they are processed by `file-pr'.
2331
2332
* The administrative directory `gnats-adm'. This directory is
2333
populated with default configuration files from the
2334
`PREFIX/etc/gnats/defaults' directory.
2335
2336
The next configuration step is to edit the default files copied to
2337
the database's `gnats-adm' directory by `mkdb'.
2338
2339
The default `dbconfig' file installed by `mkdb' provides a good
2340
basis for many GNATS databases. The default file causes similar
2341
behaviour to the 3.x versions of GNATS. However, even if this might be
2342
precisely what you want, you should still go through the file and check
2343
that the default settings suit your needs. *Note The `dbconfig' file:
2344
dbconfig file.
2345
2346
Then edit the files `categories', `responsible', and `submitters' in
2347
the `gnats-adm' directory (*note Other database-specific config files:
2348
Other config files.) to reflect your local needs. For special
2349
configurations, you may also have to edit the `states' and `classes'
2350
files.
2351
2352
If you used the `--with-gnats-default-db' option in the pre-build
2353
configure to change the location of the default database, you need to
2354
edit the `databases' config file, see *Note The `databases file':
2355
databases file. This file is by default located in the
2356
`PREFIX/etc/gnats' directory, but may have been changed by the option
2357
`--with-gnats-dblist-file' option during configure.
2358
2359
---------- Footnotes ----------
2360
2361
(1) Upgraders from older versions of GNATS should note that category
2362
directories are now created "on-the-fly" as needed by default.
2363
2364
2365
File: gnats.info, Node: Setting up periodic jobs, Next: Aliases, Prev: Setting up the default database, Up: Installation
2366
2367
3.4 Setting up periodic jobs
2368
============================
2369
2370
Allow the new user `gnats' access to `cron' and `at'. To do this, add
2371
the name `gnats' to the files `cron.allow' and `at.allow', which
2372
normally reside in the directory `/var/spool/cron'. If these files do
2373
not exist, make sure `gnats' does not appear in either of the files
2374
`cron.deny' and `at.deny' (in the same directory). If you changed the
2375
name of the GNATS user during configure, remember to substitute as
2376
appropriate in the previous steps.
2377
2378
Create a `crontab' entry that periodically runs the program
2379
`queue-pr' with the `--run' option (*note `queue-pr': queue-pr.). For
2380
example, to run `queue-pr --run' every ten minutes, create a file called
2381
`.mycron' in the home directory of the user `gnats' which contains the
2382
line:
2383
2384
0,10,20,30,40,50 * * * * EXEC-PREFIX/libexec/gnats/queue-pr --run
2385
2386
(Specify the full path name for `queue-pr'.) Then run
2387
2388
crontab .mycron
2389
2390
See the `man' pages for `cron' and `crontab' for details on using
2391
`cron'.
2392
2393
2394
File: gnats.info, Node: Aliases, Next: Installing the daemon, Prev: Setting up periodic jobs, Up: Installation
2395
2396
3.5 Setting up mail aliases
2397
===========================
2398
2399
The following mail aliases must be added on the machine where the GNATS
2400
server is installed. The instructions below are for Sendmail or
2401
Sendmail-like mail systems. If these instructions don't fit your
2402
system, particularly if you do not have an `aliases' file, ask your
2403
mail administrator for advice.
2404
2405
The following aliases should be placed in the file `/etc/aliases'.
2406
Yoy may need `root' access to add these aliases:
2407
2408
* Create an alias for the GNATS administrator. This address should
2409
point to the address of the person in charge of administrating
2410
GNATS:
2411
2412
gnats-admin: ADDRESS
2413
2414
* Create an alias to redirect incoming Problem Reports. This alias
2415
should redirect incoming mail via a "pipe" to the program
2416
`queue-pr -q'. For example, if Problem Reports coming to your
2417
site are to arrive at the address `bugs@your.company.com', create
2418
an alias to the effect of:
2419
2420
bugs: "| EXEC-PREFIX/libexec/gnats/queue-pr -q"
2421
2422
This places incoming Problem Reports in the `GNATS-QUEUE'
2423
directory of your database. Remember to fill in the full path of
2424
the `queue-pr' command as appropriate for your installation.
2425
2426
* You may also wish to forward a copy of each incoming Problem
2427
Report to a log. This can be accomplished with something like:
2428
2429
bug-q: "| EXEC-PREFIX/libexec/gnats/queue-pr -q"
2430
bug-log: /some/path/bugs.log
2431
bugs: bug-q, bug-log
2432
2433
This configuration archives incoming Problem Reports in the file
2434
`bug.log', and also feeds them to the program `queue-pr'.
2435
(Remember, `bug.log' needs to be world-writable, and should be
2436
pruned regularly; *note GNATS Administration: Management.) In
2437
order for the log file to protect fully against data loss in case
2438
a disk runs full, try to place it on a different disk volume than
2439
the GNATS database.
2440
2441
* If you want your users to be able to query the database by mail,
2442
use the following alias:
2443
2444
query-pr: "| EXEC-PREFIX/libexec/gnats/mail-query"
2445
2446
The `mail-query' program uses `--restricted' to search on the
2447
database, and by default only searches for PRs that aren't closed
2448
(*note Querying the database: query-pr.).
2449
2450
2451
2452
File: gnats.info, Node: Installing the daemon, Next: Installing tools, Prev: Aliases, Up: Installation
2453
2454
3.6 Installing the daemon
2455
=========================
2456
2457
By default, the daemon and clients are set to use port 1529. Add the
2458
line
2459
2460
support 1529/tcp # GNATS
2461
2462
to your `/etc/services' file. If you want a different service name,
2463
configure GNATS with
2464
2465
--with-gnats-service=SERVICENAME
2466
2467
In your `inetd.conf' file, add the line
2468
2469
support stream tcp nowait gnats /usr/local/libexec/gnats/gnatsd gnatsd
2470
2471
adjusting the path accordingly if you used configure options to make
2472
changes to the defaults. To make `inetd' start spawning the GNATS
2473
daemon when connected on that port, send it a hangup signal (`HUP').
2474
2475
Some operating systems have replaced `inetd' with the more modern
2476
`xinetd'. Instead of editing `inetd.conf', you should create the file
2477
`/etc/xinetd.d/support', containing something like the following:
2478
2479
service support
2480
{
2481
disable = no
2482
socket_type = stream
2483
protocol = tcp
2484
wait = no
2485
user = gnats
2486
server = /usr/local/libexec/gnats/gnatsd
2487
}
2488
2489
If you specified a different service name when running `configure',
2490
you need to give the file the same name as the service name, and you
2491
need to adjust the `service' line above. If the `--prefix' or
2492
`--exec-prefix' options were passed to `configure', adjust the `server'
2493
line above, and if you used the `--with-gnats-user' option, adjust the
2494
`user' line.
2495
2496
Then restart `xinetd' to make the new configuration current.
2497
2498
If you use an Internet superserver different from `inetd' or
2499
`xinetd', please refer to its documentation for information how to
2500
configure it.
2501
2502
At this point, you will probably want to set the access permissions
2503
of the different hosts that are going to be accessing your databases.
2504
The access permissions can currently only be set on a global scale
2505
(that is, across all the databases on a GNATS server). The location
2506
and name of the global host access configuration file can be set during
2507
the pre-build configure as shown above, but by default the file is
2508
`/usr/local/etc/gnats/gnatsd_host.access'. It lists the hosts allowed
2509
to access your server, and what their default access levels are. Each
2510
line in the file denotes one server, or one part of a network domain.
2511
There are three fields on each line, but only two are currently used.
2512
To grant all hosts from the domain SITE.COM edit access, use this line:
2513
2514
SITE.COM:EDIT
2515
2516
If you run a GNATS web interface or similar tool on the same machine as
2517
the server is running on, you probably want to grant LOCALHOST edit
2518
access:
2519
2520
LOCALHOST:EDIT
2521
2522
If you are using Kerberos, the `gnatsd_host.access' file shows the
2523
sites that don't require Kerberos authentication.
2524
2525
The third field might in the future be used for things like
2526
controlling what categories, submitter-id's PRs, etc., can be accessed
2527
from that site. Access attempts that are denied are logged to the
2528
syslog messages file (`/var/adm/messages' on many systems).
2529
2530
2531
File: gnats.info, Node: Installing tools, Next: Upgrading, Prev: Installing the daemon, Up: Installation
2532
2533
3.7 Installing the user tools
2534
=============================
2535
2536
When you install the GNATS utilities, the user tools `send-pr',
2537
`query-pr' and `edit-pr' are installed on the server machine. If your
2538
machine is part of a network, however, you may wish to install the user
2539
tools on each machine in the network so that responsible parties on
2540
those machines can submit new Problem Reports, query the database, and
2541
edit existing PRs. In the following discussion, machines with the
2542
GNATS user tools installed are referred to as "client" machines. In
2543
general, there are three distinct types of client that a GNATS server
2544
may have to cater for:
2545
2546
- Machines that are on the same local network as the GNATS server,
2547
i.e. machines that are under the same administrative control.
2548
2549
- Machines on the general, open Internet.
2550
2551
- Machines behind firewalls etc. which deny direct access over the
2552
network to the GNATS server.
2553
2554
Each type of client requires a different approach when it comes to
2555
providing access.
2556
2557
3.7.1 User tools on a local network
2558
-----------------------------------
2559
2560
If all the machines involved reside on the same local network as the
2561
GNATS server, you can simply share out the directories on the server
2562
that contain the user tools, by default `/usr/local/bin' and the
2563
directory which contains the `send-pr.conf' configuration file (*note
2564
The send-pr.conf configuration file: send-pr.conf file.), by default
2565
`/usr/local/etc/gnats'. If you have a heterogeneous environment, i.e.
2566
hosts running different operating systems, you need to create several
2567
shared GNATS installations, one for each platform. The `send-pr.conf'
2568
file is platform-independent, though.
2569
2570
In order to submit a new PR, `send-pr' would then be invoked as
2571
follows on the client machines:
2572
2573
send-pr -d HOSTNAME:PORT:DATABASE:USERNAME:PASSWORD
2574
2575
Or by first setting the environment variable `GNATSDB' as follows
2576
(the exact syntax will vary depending on what shell you use):
2577
2578
export GNATSDB=HOSTNAME:PORT:DATABASE:USERNAME:PASSWORD
2579
2580
Then, `send-pr' can simply be invoked without any options.
2581
2582
The other tools, `query-pr' and `edit-pr', work in similar ways,
2583
honoring the `-d' option as well as the `GNATSDB' environment variable.
2584
*Note GNATS user tools::.
2585
2586
3.7.2 User tools for remote users
2587
---------------------------------
2588
2589
When client machines reside on the general Internet, both security and
2590
practical considerations may make it impossible to provide a shared
2591
installation of the GNATS tools. In this case, you may choose to only
2592
provide access through a web interface such as Gnatsweb. For clients
2593
that need the GNATS tools, the following needs to be carried out on the
2594
remote machines:
2595
2596
1. Configure and build GNATS on the client machine
2597
2598
2. Configure `send-pr' on the client machine
2599
2600
You should unpack the distribution and run `configure' on the client
2601
machine in the same way as described in *Note Configuring and compiling
2602
the software: Configure and make. Note, however, that you do not need
2603
to create a `gnats' user on the client and you should not use the `make
2604
all info' command to build. Instead, issue the following commands from
2605
the top level directory of the source distribution:
2606
2607
cd gnats
2608
make install-tools
2609
cd ../send-pr
2610
make all install
2611
2612
This builds and installs the `send-pr', `query-pr' and `edit-pr'
2613
tools on the client machine. You should now configure `send-pr' by
2614
editing the `send-pr.conf' file (*note The send-pr.conf configuration
2615
file: send-pr.conf file.)
2616
2617
Users on the client machine can now either use the send-pr syntax or
2618
the `GNATSDB'environment variable described in the previous section.
2619
2620
For sites that need to submit Problem Reports by having send-pr send
2621
e-mail instead of speaking directly over the network to the GNATS
2622
server, you need to create a problem report template on the GNATS
2623
server and have that template copied to a suitable location on the
2624
client machine (any filename and any location will do, as long as
2625
`send-pr' on the client machine can read the file). On the GNATS
2626
server, use the command
2627
2628
send-pr -p > `filename'
2629
2630
The file `filename' now contains a PR template for your database.
2631
Copy this file to the client. Then edit the `send-pr.conf' file that
2632
you created on the client, set the `TEMPLATE' variable to point to the
2633
template file (*note The send-pr.conf configuration file: send-pr.conf
2634
file.) and make sure that the `MAILPROG' and `MAILADDR' varables in
2635
`send-pr.conf' are correctly set. You should now have a working remote
2636
tool installation.
2637
2638
For clients that have no direct network access to your GNATS server,
2639
such as those that are located behind strict firewalls, you either need
2640
to set up a web interface such as Gnatsweb (provided that the firewall
2641
lets web traffic through) or use the procedure above which sets up
2642
`send-pr' to submit Problem Reports by e-mail. In order to query PRs,
2643
users on the remote machines will then have to use the the e-mail
2644
functionality of `query-pr' (*note Invoking query-pr::. Editing PRs by
2645
e-mail is not possible, so clients in this group who need edit access
2646
have to get access through a web interface if possible.
2647
2648
Note that when `send-pr' is set up to work over e-mail, the
2649
`GNATSDB' environment variable and the `-d' command line option have no
2650
effect since `send-pr' is tied to a specific database by way of the
2651
value of `MAILADDR' in the `send-pr.conf' file.
2652
2653
2654
File: gnats.info, Node: Upgrading, Prev: Installing tools, Up: Installation
2655
2656
3.8 Upgrading from older versions
2657
=================================
2658
2659
The following procedure covers an upgrade from all GNATS 3 versions
2660
newer than 3.108. If your installation is an older 3.10x version, or
2661
even the ancient 3.2 version, you need to review the `UPGRADING.old'
2662
file in the GNATS distribution before carrying out the steps detailed
2663
here.
2664
2665
3.8.1 Overview
2666
--------------
2667
2668
Although almost all of the GNATS internals have been redesigned and
2669
rewritten for GNATS 4, little has changed in the format and structure
2670
of the database data. The only change that needs to be taken into
2671
account when upgrading is the fact that the database index format is
2672
binary in a default installation of GNATS 4. Thus, you will need to
2673
regenerate your database index by using the `gen-index' tool. In
2674
addition, if your old GNATS installation was so-called "release-based",
2675
you need to make some simple modifications to the database setup file
2676
`dbconfig'. See below for details.
2677
2678
Apart from building and installing new binaries, the major changes
2679
which impinge on the upgrade procedure are all on the configuration
2680
side. The main database configuration file, `dbconfig', is far more
2681
complex and powerful than the old `config' file, and while the
2682
installation process creates a sensible set of default values which are
2683
similar to GNATS 3.11x's defaults, you still need to migrate any
2684
changes you may have made to your own local configuration.
2685
2686
Another aspect which needs consideration are remote submitter sites.
2687
Such sites either need to be instructed to upgrade their locally
2688
installed copies of the GNATS user tools (`send-pr', `edit-pr' and
2689
`query-pr'), or they should be given access through interfaces such as
2690
Gnatsweb.
2691
2692
Since the GNATS network daemon has been completely reworked, with an
2693
entirely new command set, all network-based interfaces, such as
2694
Gnatsweb and TkGnats need to be upgraded to versions that support GNATS
2695
4. The `contrib' directory of this distribution contains some
2696
third-party interfaces, and the `README' file contains pointers to
2697
where you can obtain the newest versions of these tools.
2698
2699
This document only deals with upgrading GNATS itself. Third-party
2700
tools should have separate upgrading instructions in their
2701
distributions.
2702
2703
3.8.2 Upgrading
2704
---------------
2705
2706
1. Before you begin, make a backup of your entire GNATS database
2707
directory hierarchy, the GNATS executables directory and the GNATS
2708
user tools (`send-pr', `query-pr' etc.) The locations of these
2709
may vary, but in a default GNATS 3 installation, the database(s)
2710
reside under `/usr/local/share/gnats', the executables are located
2711
in `/usr/local/libexec/gnats' and the user tools reside in
2712
`/usr/local/bin'.
2713
2714
2. (optional) In order to avoid confusing your users, you may want to
2715
remove the old GNATS 3 executables and tools, escpecially if you
2716
plan to install GNATS 4 in a different location than version 3.
2717
2718
3. Build and install GNATS 4. *Note Installing GNATS: Installation.
2719
It is recommended that you use the `--with-gnats-default-db'
2720
option when running `configure', in order to set the default
2721
database to be one of your already existing GNATS 3 databases.
2722
2723
4. Edit the GNATS `databases' file and add entries for all your old
2724
GNATS 3 databases. In a default GNATS 4 installation the file is
2725
in `/usr/local/etc/gnats'. *Note The `databases' file: databases
2726
file.
2727
2728
5. In GNATS 3, the file `gnatsd.conf' specifies minimum access levels
2729
for the different hosts accessing the GNATS daemon, `gnatsd'.
2730
There is one `gnatsd.conf' for each database. In GNATS 4, these
2731
files have been replaced by a single file named
2732
`gnatsd.host_access' which contains settings that apply across all
2733
the databases on the server. This file is located in the same
2734
directory as the `databases' file. You need to combine the host
2735
access settings from all your GNATS 3 databases and add them to the
2736
`gnatsd.host_access' file. Note that you are no longer able to
2737
control host access on a per-database basis. Optionally, you may
2738
delete the old `gnatsd.conf' files. *Note Controlling access to
2739
GNATS databases: Access Control.
2740
2741
6. Next, you need to migrate the settings in the old `config' files of
2742
your databases to corresponding `dbconfig' files. The database you
2743
specified with the `--with-gnats-default-db' configure option got
2744
a default `dbconfig' installed. This default file contains field
2745
definitions etc. which makes this version of GNATS behave almost
2746
exactly like older versions. Copy this default file to the
2747
`gnats-adm' directories of any other GNATS databases that you may
2748
have on your host before you proceed to migrate your old
2749
configuration settings.
2750
2751
The following is a list of the configuration directives that may be
2752
present in a `config' file and their counterparts (if any) in
2753
GNATS 4.
2754
2755
GNATS_ADDR
2756
This setting has no counterpart in GNATS 4, since GNATS no
2757
longer needs to know its own mail address.
2758
2759
GNATS_ADMIN
2760
This setting is now set in the `responsible' file in the
2761
`gnats-adm' directory of your database(s).
2762
2763
GNATS_SITE
2764
GNATS 4 has no concept of a named `site', so this directive is
2765
obsolete.
2766
2767
SUBMITTER
2768
Obsolete, since it relates to GNATS_SITE.
2769
2770
DEFAULT_RELEASE
2771
DEFAULT_ORGANIZATION
2772
The GNATS 4 `dbconfig' file has separate configuration
2773
sections for each defined field. Field defaults are set with
2774
the `default' keyword in these sections. *Note The
2775
`dbconfig' file: dbconfig file.
2776
2777
NOTIFY
2778
Controlled by the `notify-about-expired-prs' setting in the
2779
`dbconfig' file.
2780
2781
ACKNOWLEDGE
2782
Controlled by the `send-submitter-ack' setting in the
2783
`dbconfig' file.
2784
2785
DEFAULT_SUBMITTER
2786
The default submitter is now always the first entry in the
2787
`submitters' file of your database.
2788
2789
KEEP_RECEIVED_HEADERS
2790
Controlled by the `keep-all-received-headers' setting in the
2791
`dbconfig' file.
2792
2793
DEBUG_MODE
2794
Controlled by the `debug-mode' setting in the `dbconfig' file.
2795
2796
BDAY_START
2797
BDAY_END
2798
BWEEK_START
2799
BWEEK_END
2800
Controlled by the settings `business-day-hours' and
2801
`business-week-days' in the `dbconfig' file.
2802
2803
DEFINE_CATEGORY
2804
The default category for PRs that arrive without one is now
2805
the first category listed in the `categories' file of your
2806
database.
2807
2808
After your are done migrating the settings, you may optionally
2809
delete the old `config' files. Since there are many more
2810
configuration settings available in the GNATS 4 `dbconfig' file,
2811
you should take some time to review them all before proceeding.
2812
*Note The `dbconfig' file: dbconfig file.
2813
2814
If your old GNATS installations was release-based, i.e. it included
2815
the fields Quarter, Keywords and Date-Required, you need to define
2816
those fields in the `dbconfig' file by following the instructions
2817
in *Note Supporting old GNATS "release-based" fields:
2818
release-based support.
2819
2820
7. The file `gnatsd.access' has been renamed to `gnatsd.user_access'.
2821
Furthermore, GNATS 4 uses a different password format in the
2822
`gnatsd.user_access' file than older versions, since it supports
2823
`crypt()' and MD5 passwords (*note Controlling access to GNATS
2824
databases: Access Control.). You need to translate your old
2825
`gnatsd.user_access' files to the new format by using the
2826
`gnats-pwconv' tool which was installed in the
2827
`EXEC-PREFIX/libexec/gnats' directory, typically
2828
`/usr/local/libexec/gnats'. *Note Managing user passwords:
2829
gnats-pwconv.
2830
2831
8. The final step involves regenerating the indexes of your
2832
databases. For this, log in as the user `gnats'. Then run the
2833
`gen-index' command for each of your databases. See *Note
2834
Administrative Utilities: Admin utils. for details on how to use
2835
`gen-index'.
2836
2837
9. Sit back and enjoy your new GNATS 4 setup...
2838
2839
2840
File: gnats.info, Node: Management, Next: Locations, Prev: Installation, Up: Top
2841
2842
4 GNATS Administration
2843
**********************
2844
2845
In daily usage, GNATS is self-maintaining. However, there are various
2846
administrative duties which need to be performed periodically. Also,
2847
requirements may change with time, so it may be necessary to make
2848
changes to the GNATS configuration at some point:
2849
2850
_emptying the `pending' directory_
2851
If a Problem Report arrives with a `Category' value that is
2852
unrecognized by the `categories' file, or if that field is missing,
2853
GNATS places the PR in the `pending' directory (*note Where GNATS
2854
lives: Locations.). PRs submitted in free-form by email will
2855
always be filed in the `pending' directory. If so configured,
2856
GNATS sends a notice to the `gnats-admin' and to the party
2857
responsible for that submitter (as listed in the `submitters'
2858
file) when this occurs.
2859
2860
To have these "categoryless" PRs filed correctly, you can then use
2861
a GNATS tool such as `edit-pr' to set the correct category of each
2862
PR in the `pending' directory.
2863
2864
In order to protect yourself from problems caused by full disks,
2865
you should arrange to have all mail that is sent to the GNATS
2866
database copied to a log file (*Note Setting up mail aliases:
2867
Aliases.). Then, should you run out of disk space, and an empty
2868
file ends up in the database's `pending' directory, you need only
2869
look in the log file, which should still contain the full message
2870
that was submitted.
2871
2872
_adding another database_
2873
GNATS supports multiple databases. If you find at some point that
2874
you need to add another database to your server, the `mkdb' tool
2875
does most of the work for you. *Note Adding another database:
2876
mkdb.
2877
2878
_adding new categories_
2879
Most installations of GNATS will only require you to add a new line
2880
to the `categories' file. The category directory will then be
2881
created automatically as needed. However, if automatic directory
2882
creation has been switched off in the `dbconfig' file (*note The
2883
`dbconfig' file: dbconfig file.), you need to use the `mkcat'
2884
program.
2885
2886
_removing categories_
2887
To remove a category, you need to make sure the relevant
2888
subdirectory is empty (in other words, make sure no PRs exist for
2889
the category you wish to remove). You can then remove the
2890
category listing from the `categories' file, and invoke
2891
2892
rmcat CATEGORY...
2893
2894
to remove CATEGORY (any number of categories may be specified on
2895
the command line to `rmcat', so long as they abide by the above
2896
constraints).
2897
2898
_adding and removing maintainers_
2899
Edit the `responsible' file to add a new maintainer or to remove an
2900
existing maintainer. *Note The `responsible' file: responsible
2901
file.
2902
2903
_building a new index_
2904
If your index becomes corrupted, or if you wish to generate a new
2905
one for some reason, use the program `gen-index' (*note
2906
Regenerating the index: gen-index.).
2907
2908
_pruning log files_
2909
Log files often grow to unfathomable proportions. As with
2910
gardening, it is best to prune these as they grow, lest they take
2911
over your disk and leave you with no room to gather more Problem
2912
Reports. If you keep log files, be sure to keep an eye on them.
2913
(*Note Setting up mail aliases: Aliases.)
2914
2915
_BACKING UP YOUR DATA_
2916
Any database is only useful if its data remains uncorrupted and
2917
safe. Performing periodic backups ensures that problems like disk
2918
crashes and data corruption are reversible.
2919
2920
2921
*Note Where GNATS lives: Locations.
2922
2923
* Menu:
2924
2925
* GNATS configuration:: Overview of GNATS configuration
2926
* databases file:: The databases file
2927
* dbconfig file:: The dbconfig file
2928
* Other config files:: Configuration files
2929
* send-pr.conf file:: The send-pr.conf file
2930
* Admin files:: Administrative data files
2931
* Admin utils:: Administrative utilities
2932
* Internal utils:: Internal utilities
2933
2934
2935
File: gnats.info, Node: GNATS configuration, Next: databases file, Up: Management
2936
2937
4.1 Overview of GNATS configuration
2938
===================================
2939
2940
*Note Where GNATS lives: Locations.
2941
2942
GNATS has two, well, actually three, different kinds of
2943
configuration file. The "site-wide" configuration files determine
2944
overall behaviour across all the databases on your machine, while the
2945
"database-specific" configuration files determine how GNATS behaves
2946
when dealing with a specific database. In addition, there is a single
2947
file that needs to be set up for the `send-pr' tool to work properly.
2948
These files can be edited at any time -- the next time a GNATS tool is
2949
invoked, the new parameters will take effect.
2950
2951
These are the site-wide configuration files used by GNATS:
2952
2953
`databases'
2954
Specifies database names and their associated parameters, such as
2955
in which directory they are located. This file is used by the
2956
GNATS clients to determine the location of a database referred to
2957
by name. *Note The `databases' file: databases file.
2958
2959
`defaults'
2960
This directory contains the set of default per-database
2961
configuration files used when a new database is created with
2962
`mkdb'.
2963
2964
`gnatsd.host_access'
2965
Controls access levels for the different machines that will do
2966
lookups in the databases on this machine. *Note GNATS access
2967
control: Access Control.
2968
2969
`gnatsd.user_access'
2970
Controls user access levels for the databases on this server. The
2971
settings apply to all databases (there is also a database-specific
2972
user access level file). *Note GNATS access control: Access
2973
Control.
2974
2975
The database-specific configuration is determined by the following
2976
files in the `gnats-adm' subdirectory of the database directory.
2977
2978
`dbconfig'
2979
Controls most aspects of how GNATS behaves when dealing with your
2980
database. *Note The `dbconfig' file: dbconfig file.
2981
2982
`categories'
2983
The list of categories that GNATS accepts as valid for the
2984
`Category' field, and the maintainers responsible for each
2985
category. Update this file whenever you have a new category, or
2986
whenever a category is no longer valid. You must also update this
2987
file whenever responsibility for a category changes, or if a
2988
maintainer is no longer valid. *Note The `categories' file:
2989
categories file.
2990
2991
`responsible'
2992
An alias list mapping names to their associated mailing addresses.
2993
The names in this list can have multiple email addresses
2994
associated with them. If a responsible user does not show up in
2995
this list, they are assumed to be a user local to the system.
2996
This list is not associated with just the responsible user field;
2997
all email addresses are mapped through this file whenever mail is
2998
sent from GNATS. *Note The `responsible' file: responsible file.
2999
3000
`submitters'
3001
Lists sites from whom GNATS accepts Problem Reports. The existence
3002
of this file is mandatory, although the feature it provides is
3003
not; see *Note The `submitters' file: submitters file.
3004
3005
`addresses'
3006
Mappings between submitter IDs and submitters' e-mail addresses.
3007
Use of this file is optional. If you get Problem reports where the
3008
`Submitter' field is not filled in, GNATS will use entries in this
3009
file to try to derive the submitter ID from the e-mail headers.
3010
*Note The `addresses' file: addresses file.
3011
3012
`states'
3013
Lists the possible states for Problem Reports, typically ranging
3014
from "open" to "closed". *Note The `states' file: addresses file.
3015
3016
`classes'
3017
Lists the possible classes of Problem Report. This provides an
3018
easy way to have "subcategories", for example by setting up
3019
classes such as `sw-bug', `doc-bug', `change-request' etc. *Note
3020
The `classes' file: classes file.
3021
3022
`gnatsd.user_access'
3023
Specify the access levels for different users to your database.
3024
*Note GNATS access control: Access Control.
3025
3026
3027
The last file in this menagerie is the `send-pr' configuration file
3028
`send-pr.conf'. This file contains some defaults that need to be known
3029
in order for `send-pr' to work. The file needs to be present on all
3030
hosts where `send-pr' is to be used. *Note the `send-pr.conf' file:
3031
send-pr.conf file.
3032
3033
3034
File: gnats.info, Node: databases file, Next: dbconfig file, Prev: GNATS configuration, Up: Management
3035
3036
4.2 The `databases' file
3037
========================
3038
3039
The `databases' configuration file is a site-wide configuration file
3040
containing the list of GNATS databases that are available either on the
3041
host itself or remotely over the network, together with some parameters
3042
associated with each database.
3043
3044
The file contains one line for each database. For databases located
3045
on the host itself, each line consists of three fields separated by
3046
colons:
3047
3048
DATABASE NAME:SHORT DESCRIPTION OF DATABASE:PATH/TO/DATABASE
3049
3050
The first field is the database name. This is the name used to
3051
identify the database when invoking programs such as `query-pr' or
3052
`send-pr', either by using the `--database' option of the program or by
3053
setting the GNATSDB environment variable to the name of the database.
3054
The second field is a short human-readable description of the database
3055
contents, and the final field is the directory where the database
3056
contents are kept.
3057
3058
For a database that is located across a network, but which should be
3059
accessible from this host, the entry for the database should look like
3060
this:
3061
3062
DATABASE NAME:SHORT DESCRIPTION OF DATABASE::HOSTNAME:PORT
3063
3064
The first two fields are the same as for local databases, the third
3065
field is empty (notice the two adjacent `:' symbols, indicating an
3066
empty field), the fourth field is the hostname of the remote GNATS
3067
server, and the fifth field is the port number that the remote GNATS is
3068
running on.
3069
3070
If GNATS was built with default options, the `databases' file will
3071
be located in the `/usr/local/etc/gnats' directory. However, if the
3072
option `--with-gnats-dblist-file' was used during building of GNATS,
3073
the `databases' file has the name and location given to this option. A
3074
sample `databases' file is installed together with GNATS.
3075
3076
Note that if you add a new local database, you must create its data
3077
directory, including appropriate subdirectories and administrative
3078
files. This is best done using the `mkdb' tool, *Note mkdb::.
3079
3080
3081
File: gnats.info, Node: dbconfig file, Next: Other config files, Prev: databases file, Up: Management
3082
3083
4.3 The `dbconfig' file
3084
=======================
3085
3086
The `dbconfig' configuration file controls the configuration of a GNATS
3087
database. Each database has its own individual copy of this file,
3088
which is located in the `gnats-adm' subdirectory of the database.
3089
3090
The file consists of standard plain text. Whitespace is completely
3091
optional and is ignored. Sets of braces `@' are used to delimit the
3092
different sections, and all non-keyword values must be surrounded with
3093
double quotes. The values in `dbconfig' can be changed at any time;
3094
the new values take effect for all subsequent iterations of GNATS tools.
3095
3096
The `dbconfig' file contains 6 major sections, which must appear in
3097
the following order:
3098
3099
* Overall database configuration
3100
3101
* Individual field configuration
3102
3103
* Named query definitions
3104
3105
* Audit-trail and outgoing email formats
3106
3107
* Index file description
3108
3109
* Initial Problem Report input fields
3110
3111
The different sections are described below. While reading the
3112
following sections, it will be useful to refer to the sample `dbconfig'
3113
file which is installed when a new database is initialized with the
3114
`mkdb' tool. In fact, the sample file provides a configuration that
3115
should be usable for a great range of sites, since it reproduces the
3116
behaviour of the older, less customizable 3.x versions of GNATS.
3117
3118
* Menu:
3119
3120
* Overall database configuration:: Overall database configuration.
3121
* Individual field configuration:: Individual field configuration.
3122
* Field datatypes:: Field datatypes.
3123
* Edit controls:: Trigger on certain edit actions.
3124
* Named query definitions:: Define and name standard queries.
3125
* Audit-trail formats:: Specify formatting of the audit-trail.
3126
* Outgoing email formats:: Specify contents and formatting of
3127
messages sent out by GNATS.
3128
* Index file description:: Specify the general format and
3129
contents of the database index.
3130
* Initial PR input fields:: Which fields should be present on
3131
initial PR entry.
3132
3133
3134
File: gnats.info, Node: Overall database configuration, Next: Individual field configuration, Up: dbconfig file
3135
3136
4.3.1 Overall database configuration
3137
------------------------------------
3138
3139
The overall database options are controlled by settings in the
3140
`database-info' section of the `dbconfig' file. The following is the
3141
general format of this section:
3142
3143
database-info {
3144
[options]
3145
}
3146
3147
The following options and values may be used in the `database-info'
3148
section:
3149
3150
`debug-mode TRUE | FALSE'
3151
If set to `true', the database is placed into debug mode. This
3152
causes all outgoing email to be sent to the "gnats-admin" user
3153
listed in the `responsible' file of the database. The default
3154
value is `false'.
3155
3156
`keep-all-received-headers TRUE | FALSE'
3157
If set to `true', all of the Received: headers for PRs submitted
3158
via email are kept in the PR. Otherwise, only the first one is
3159
kept. The default value is `false'.
3160
3161
`notify-about-expired-prs TRUE | FALSE'
3162
If set to `true', notification email about expired PRs is sent via
3163
the `at-pr' command. Otherwise, required times for PR fixes are
3164
not used. The default value is `false'.
3165
3166
`send-submitter-ack TRUE | FALSE'
3167
When new PRs are submitted to the database, an acknowledgment
3168
email will be sent to the submitter of send-submitter-ack is set
3169
to `true'. This is in addition to the normal notification mail to
3170
the person(s) responsible for the new PR. The default value is
3171
`false'.
3172
3173
`libexecdir "DIRECTORY"'
3174
Specifies the directory where the GNATS administrative executables
3175
are located. In particular, `at-pr' and `mail-pr' are invoked
3176
from this directory. The default value is the empty string, which
3177
is unlikely to be useful.
3178
3179
`business-day-hours DAY-START - DAY-END'
3180
Used to specify the hours that define a business day. The values
3181
are inclusive and should be given in 24-hour format, with a dash
3182
separating them. GNATS uses these values to determine whether the
3183
required completion time for a PR has passed. The default values
3184
are 8 for `day-start' and 17 for `day-end'.
3185
3186
`business-week-days WEEK-START - WEEK-END'
3187
Specifies the start and ending days of the business week, where 0
3188
is Sunday, 1 is Monday, etc. The days are inclusive, and the
3189
values should be given with a dash separating them. GNATS uses
3190
these values to determine whether the required completion time for
3191
a PR has passed. The default values are 1 for `week-start' and 5
3192
for `week-end'.
3193
3194
`create-category-dirs TRUE | FALSE'
3195
If set to `true', database directories for categories are
3196
automatically created as needed. Otherwise, they must be created
3197
manually (usually with the `mkcat' script). It is recommended that
3198
the default value of `true' be kept.
3199
3200
`category-dir-perms MODE'
3201
Standard octal mode-specification specifying the permissions to be
3202
set on auto-created category directories. Default is `0750',
3203
yielding user read, write and execute, and group read and execute.
3204
Note that if you have local users on the GNATS server itself,
3205
running for instance `query-pr', you may need to change the
3206
permissions to `0755'.
3207
3208
3209
File: gnats.info, Node: Individual field configuration, Next: Field datatypes, Prev: Overall database configuration, Up: dbconfig file
3210
3211
4.3.2 Individual field configuration
3212
------------------------------------
3213
3214
Each type of field in a PR must be described with a `field' section in
3215
the `dbconfig' file. These sections have the following general
3216
structure:
3217
3218
field "fieldname" {
3219
description "string"
3220
[ field-options ... ]
3221
datatype [ datatype-options ... ]
3222
[ on-change { edit-options ... } ]
3223
}
3224
3225
`fieldname' is used as the field header in the PR. The characters
3226
`>' and `:' are used internally as field markers by GNATS, so they must
3227
not be used in fieldnames.
3228
3229
The order in which the `field' sections appear in the `dbconfig'
3230
file determines the order in which they appear in the PR text. There
3231
is no required order, unlike previous versions of GNATS -- the
3232
Unformatted field and multitext fields may appear anywhere in the PR.
3233
3234
The following `field-options' may be present within a `field'
3235
section:
3236
3237
`builtin-name "NAME"'
3238
Indicates that this field corresponds to one of the GNATS built-in
3239
fields.
3240
3241
GNATS has several fields which are required to be present in a PR,
3242
and this option is used to map their external descriptions to their
3243
internal usage. The external field names are:
3244
3245
`arrival-date'
3246
The arrival date of the PR
3247
3248
`audit-trail'
3249
The audit-trail recording changes to the PR
3250
3251
`category'
3252
The category that the PR falls into
3253
3254
`closed-date'
3255
The date that the PR was closed
3256
3257
`confidential'
3258
If set to `yes', the PR is confidential
3259
3260
`description'
3261
A description of the problem
3262
3263
`last-modified'
3264
The date the PR was last modified
3265
3266
`number'
3267
The PR's unique numeric identifier
3268
3269
`originator'
3270
The originator of the PR
3271
3272
`priority'
3273
Priority of the PR
3274
3275
`responsible'
3276
The person responsible for handling the PR
3277
3278
`severity'
3279
Severity of the problem described by the PR
3280
3281
`state'
3282
The current state of the PR
3283
3284
`submitter-id'
3285
The user that submitted the PR
3286
3287
`synopsis'
3288
The one-line description of the PR
3289
3290
`unformatted'
3291
PR text which cannot be parsed and associated with other
3292
fields.
3293
3294
For these built-in fields, a matching field description _must_
3295
appear in the `dbconfig' file. Otherwise, the configuration will
3296
be considered invalid, and errors will be generated from the GNATS
3297
clients and `gnatsd'. We also recommend that you leave the actual
3298
fieldnames of these fields at their default values (i.e.
3299
capitalized versions of their built-in names), since some clients
3300
may depend on these names.
3301
3302
`description "DESCRIPTION TEXT"'
3303
A one-line human-readable description of the field. Clients can
3304
use this string to describe the field in a help dialog. The
3305
string is returned from the FDSC command in gnatsd and is also
3306
available via the `--field-description' option in `query-pr'.
3307
3308
This entry must be present in the field description, and there is
3309
no default value.
3310
3311
`query-default EXACT-REGEXP | INEXACT-REGEXP'
3312
Used to specify the default type of searches performed on this
3313
field. This is used when the `^' search operator appears in a
3314
query, and is also used for queries in `query-pr' that use the old
3315
`--field' query options.
3316
3317
If the option is not given, the default search is `exact-regexp'.
3318
3319
`textsearch'
3320
If this option is present, the field will be searched when the user
3321
performs a `--text' search from `query-pr'. The field is also
3322
flagged as a `textsearch' field in the set of field flags returned
3323
by the `FIELDFLAGS' command in gnatsd.
3324
3325
By default, fields are not marked as `textsearch' fields.
3326
3327
`read-only'
3328
When this option is present, the field contents may not be edited
3329
-- they must be set when the PR is initially created. In general,
3330
this should only be used for fields that are given as internal
3331
values rather than fields supplied by the user.
3332
3333
By default, editing is allowed.
3334
3335
3336
File: gnats.info, Node: Field datatypes, Next: Edit controls, Prev: Individual field configuration, Up: dbconfig file
3337
3338
4.3.3 Field datatypes
3339
---------------------
3340
3341
Each field description has to contain a datatype declaration which
3342
describes what data are to be store in the field. The general format
3343
for such a declaration is
3344
3345
`datatype [ options ... ]'
3346
3347
The available datatypes are:
3348
3349
`text [ matching { "regexp" [ "regexp" ... ] } ]'
3350
The `text' datatype is the most commonly used type; it is a
3351
one-line text string.
3352
3353
If the `matching' qualifier is present, the data in the field must
3354
match at least one of the specified regexps. This provides an
3355
easy and flexible way to limit what text is allowed in a field.
3356
If no `matching' qualifier is present, no restriction is placed on
3357
what values may appear in the field.
3358
3359
`multitext [ { default "string" } ]'
3360
The field can contain multiple lines of text.
3361
3362
If the `default' option is present, the field will default to the
3363
specified `string' if the field is not given a value when the PR is
3364
initially created. Otherwise, the field will be left empty.
3365
3366
`enum {'
3367
` values {'
3368
` "string" [ "string" ... ]'
3369
` }'
3370
` [ default "string" ]'
3371
`}'
3372
Defines an enumerated field, where the values in the PR field must
3373
match an entry from a list of specified values. The list of
3374
allowed values is given with the `values' option. The `values'
3375
option is required for an enumerated field.
3376
3377
If a `default' option is present, it is used to determine the
3378
initial value of the field if no entry for the field appears in an
3379
initial OR (or if the value in the initial PR is not one of the
3380
acceptable values). However, the value in the `default' statement
3381
is not required to be one of the accepted values; this can be used
3382
to allow the field to be initially empty, for example.
3383
3384
If no `default' option is specified, the default value for the
3385
field is the first value in the `values' section.
3386
3387
`multienum {'
3388
` values {'
3389
` "string" [ "string" ... ]'
3390
` }'
3391
` [ separators "string" ]'
3392
` [ default "string" ]'
3393
`}'
3394
The `multienum' datatype is similar to the `enum' datatype, except
3395
that the field can contain multiple values, separated by one or
3396
more characters from the `separators' list. If no `separators'
3397
option is present, the default separators are space (` ') and colon
3398
(`:').
3399
3400
The values in the `default' string for this field type should be
3401
separated by one of the defined separators. An example clarifies
3402
this. If we have a field named `ingredients' where the default
3403
values should be `sugar', `flour' and `baking powder' and the
3404
separator is a colon `:', the following sets these defaults:
3405
3406
default "sugar:flour:baking powder"
3407
3408
`enumerated-in-file {'
3409
` path "filename"'
3410
` fields {'
3411
` "name" [ "name" ... ]'
3412
` } key "name"'
3413
` [ allow-any-value ]'
3414
`}'
3415
The `enumerated-in-file' type is used to describe an enumerated
3416
field with an associated "administrative file" which lists the
3417
legal values for the field, and may optionally contain additional
3418
fields that can be examined by query clients or used for other
3419
internal purposes. It is similar to the `enum' datatype, except
3420
that the list of legal values is stored in a separate file. An
3421
example of this kind of field is the built-in Category field with
3422
its associeted `categories' administrative file.
3423
3424
`filename' is the name of a file in the `gnats-adm' administrative
3425
directory for the database.
3426
3427
The format of the administrative file should be simple ASCII.
3428
"Subfields" within the file are separated with colons (`:').
3429
Lines beginning with a hash sign (`#') are ignored as comments.
3430
Records within the file are separated with newlines.
3431
3432
The `field' option is used to name the subfields in the
3433
administrative file. There must be at least one subfield, which
3434
is used to list the legal values for the field. If the
3435
administrative file is empty (or does not contain any non-empty
3436
non-comment lines), the PR field must be empty.
3437
3438
The `key' option is used to designate which field in the
3439
administrative file should be used to list the legal values for
3440
the PR field. The value must match one of the field names in the
3441
`field' option.
3442
3443
If the `allow-any-value' option is present, the value of the PR
3444
field is not required to appear in the administrative file -- any
3445
value will be accepted.
3446
3447
Note that there is no `default' keyword for `enumerated-in-file'.
3448
These fields get their default value from the _first_ entry in the
3449
associated administrative file.
3450
3451
`multi-enumerated-in-file {'
3452
` path "filename"'
3453
` fields {'
3454
` "name" [ "name" ... ]'
3455
` } key "name"'
3456
` [ default "string" ]'
3457
` [ allow-any-value ]'
3458
` [ separators "string" ]'
3459
`}'
3460
`multi-enumerated-in-file' is to `multienum' what
3461
`enumerated-in-file' is to `enum'. Its options have the same
3462
meaning as their counterparts in the `multienum' and
3463
`enumerated-in-file' fields.
3464
3465
_NOTE_: Keywords may appear in any sequence, with one exception -
3466
the `separators' keyword, if present, has to come last. This rule
3467
only applies to fields of type `multi-enumerated-in-file'.
3468
3469
`date'
3470
The `date' datatype is used to hold dates. Date fields must
3471
either be empty or contain a correctly formatted date.
3472
3473
No defaults or other options are available. The field is left
3474
empty if no value for the field is given in the initial PR.
3475
3476
`integer [ { default "integer" } ]'
3477
Integer fields are used to hold numbers. They must either be
3478
empty or contain a value composed entirely of digits, with an
3479
optional leading sign.
3480
3481
If the `default' option is present, the field will have the value
3482
of `integer' if the field is not given a value when the PR is
3483
initially created. Otherwise, the field will be left empty.
3484
3485
3486
File: gnats.info, Node: Edit controls, Next: Named query definitions, Prev: Field datatypes, Up: dbconfig file
3487
3488
4.3.4 Edit controls
3489
-------------------
3490
3491
The `on-change' subsection of a `fields' section specifies one or more
3492
actions to be performed when the field value is edited by the user. It
3493
has the general form
3494
3495
on-change [ "query-expression" ] {
3496
[ add-audit-trail ]
3497
[ audit-trail-format {
3498
format "formatstring"
3499
[ fields { "fieldname" ... } ]
3500
} ]
3501
[ require-change-reason ]
3502
[ set-field | append-to-field "fieldname" {
3503
"format-string" [ fieldlist ]
3504
} ]
3505
[ require { "fieldname" ... } ]
3506
}
3507
3508
The optional `query-expression' controls whether or not the actions
3509
in the `on-change' section are taken. If the expression fails to
3510
match, the actions are skipped.
3511
3512
The `add-audit-trail' option indicates that an entry should be
3513
appended to the PR's audit-trail when this field is changed. The format
3514
of the entry is controlled by the optional `audit-trail-format' section
3515
within the field, or by the global `audit-trail-format' section. See
3516
*Note Audit-trail formats:: and *Note Outgoing email formats::.
3517
3518
The `require-change-reason' option specifies that a change reason
3519
must be present in the PR when this field is edited. This option only
3520
makes sense if an audit-trail entry is required, as the change reason is
3521
otherwise unused.
3522
3523
The `set-field' and `append-to-field' options are used to change the
3524
value of the field `fieldname' in the PR. The supplied format is used
3525
to format the value that will be placed in the field.
3526
3527
`append-to-field' appends the resulting formatted string to the
3528
existing, while `set-field' completely replaces the contents.
3529
3530
Any field may be edited by the `set-field' or `append-to-field'
3531
option (the `read-only' option on a field is ignored). However, the
3532
changes are subject to the usual field content checks.
3533
3534
The `require' option specifies that one or more fields must have a
3535
(non-blank) value when this field is changed.
3536
3537
A field may be enforced to have a (non-blank) value at all times by
3538
including it in the set of fields required for the initial PR, see
3539
*Note Initial PR input fields::, as well as in the set of fields
3540
required on change of the field itself.
3541
3542
There is also a global `on-change' section that is executed once for
3543
each PR edit. A typical use for such a section is to set the
3544
last-modified date of the PR.
3545
3546
3547
File: gnats.info, Node: Named query definitions, Next: Audit-trail formats, Prev: Edit controls, Up: dbconfig file
3548
3549
4.3.5 Named query definitions
3550
-----------------------------
3551
3552
When queries are performed via `query-pr', they can refer to a query
3553
format described by a `query' section in the `dbconfig' file:
3554
3555
query "queryname" {
3556
format "formatstring"
3557
[fields { "fieldname" [ "fieldname" ... ] } ]
3558
}
3559
3560
`formatstring' is as described in *Note Formatting query-pr output::.
3561
It basically contains a string with printf-like % escapes. The output
3562
of the query is formatted as specified by this format string.
3563
3564
The `fields' option lists the fields to be used with the format
3565
string. If the `fields' option is present without a `format' option,
3566
the contents of the listed fields are printed out, separated by
3567
newlines.
3568
3569
The named query formats _full_, _standard_ amd _summary_ must be
3570
present in the `dbconfig' file. _full_ and _summary_ correspond to the
3571
`query-pr' options `--full' and `--summary', while _standard_ is used
3572
when no format option is given to `query-pr'.
3573
3574
3575
File: gnats.info, Node: Audit-trail formats, Next: Outgoing email formats, Prev: Named query definitions, Up: dbconfig file
3576
3577
4.3.6 Audit-trail formats
3578
-------------------------
3579
3580
These formats are similar to the named query formats, but they include
3581
more options. They are used for formatting audit-trail entries and for
3582
outgoing email messages.
3583
3584
There is currently only one audit-trail format, defined by the
3585
`audit-trail-format' option:
3586
3587
audit-trail-format {
3588
format "formatstring"
3589
[ fields { "fieldname" [ "fieldname" ... ] } ]
3590
}
3591
3592
For those fields that require an audit-trail entry, the audit-trail
3593
text to be appended is formatted as described by this format. The
3594
per-field `audit-trail-format' is used in preference to this one, if it
3595
exists.
3596
3597
`formatstring' and `fieldname' are similar to those used by the
3598
named query format. `fieldname' may also be a "format parameter",
3599
which is a context-specific value. (Format parameters are
3600
distinguished from fieldnames by a leading dollar sign (`$')).
3601
3602
The following format parameters are defined for `audit-trail-format'
3603
entries:
3604
3605
`$Fieldname'
3606
The name of the field for which an audit-trail entry is being
3607
created.
3608
3609
`$OldValue'
3610
The old value of the field.
3611
3612
`$NewValue'
3613
The new field value.
3614
3615
`$EditUserEmailAddr'
3616
The email address of the user editing the field. Set by the
3617
`EDITADDR' `gnatsd' command or from the `responsible' file; if not
3618
available, user's local address is used.
3619
3620
`$CurrentDate'
3621
The current date.
3622
3623
`$ChangeReason'
3624
The reason for the change; may be blank if no reason was supplied.
3625
3626
These parameters may be used anywhere a `fieldname' can appear.
3627
3628
3629
File: gnats.info, Node: Outgoing email formats, Next: Index file description, Prev: Audit-trail formats, Up: dbconfig file
3630
3631
4.3.7 Outgoing email formats
3632
----------------------------
3633
3634
During the life of a PR, GNATS can be configured to send out a range of
3635
email messages. When a PR first arrives, an acknowledgment message is
3636
sent out if the `send-submitter-ack' parameter above is set to `true'.
3637
Certain edits to the PR may also cause email to be sent out to the
3638
various parties, and if a PR is deleted, GNATS may send notification
3639
email.
3640
3641
The formats of the email messages are controlled by `mail-format'
3642
sections in the `dbconfig' file. The general structure of a
3643
`mail-format' section is as follows:
3644
3645
mail-format "format-name" {
3646
from-address {
3647
[ fixed-address "address" ]
3648
[ email-header-name | [ mail-header-name | ... ] ]
3649
}
3650
to-address {
3651
[ fixed-address "address" ]
3652
[ "email-header-name" | [ "mail-header-name" | ... ] ]
3653
}
3654
reply-to {
3655
[ fixed-address "address" ]
3656
[ "email-header-name" | ... ] | [ "gnats-field-name" | ... ]
3657
}
3658
header {
3659
format "formatstring"
3660
[ fields { "fieldname" [ "fieldname" ... ] } ]
3661
}
3662
body {
3663
format "formatstring"
3664
[ fields { "fieldname" [ "fieldname" ... ] } ]
3665
}
3666
}
3667
3668
`gnats' recognizes and uses 6 different `format-name' values:
3669
3670
`initial-response-to-submitter'
3671
Format of the message used when mailing an initial response back
3672
to the PR submitter. This message will only be sent if
3673
`send-submitter-ack' in the overall database configuration is set
3674
to `true'.
3675
3676
`initial-pr-notification'
3677
Format of the message sent to the responsible parties when a new
3678
PR with category different from "pending" arrives.
3679
3680
`initial-pr-notification-pending'
3681
Format of the message sent to the responsible parties when a new
3682
PR that ends up with category "pending" arrives.
3683
3684
`appended-email-response'
3685
Format of the notification message sent out when a response to a
3686
PR is received via email.
3687
3688
`audit-mail'
3689
Format of the message sent out when a PR edit generates an
3690
Audit-Trail entry.
3691
3692
`deleted-pr-mail'
3693
Format of the message sent out when a PR is deleted.
3694
3695
The `from-address', `to-address' and `reply-to' subsections of a
3696
mail-format section specify the contents of the `To:', `From:' and
3697
`Reply-To:' headers in outgoing email. There are two ways to specify
3698
the contents: by using a `fixed-address' specification, or by
3699
specifying `email-header-name's or `gnats-field-name's.
3700
3701
When an `email-header-name' or `gnats-field-name' value is given,
3702
GNATS will attempt to extract an email address from the specified
3703
location. If several values are given on the same line, separated by
3704
`|' characters, GNATS will try to extract an address from each location
3705
in turn until it finds a header or field which is nonempty. The
3706
following example should clarify this:
3707
3708
mail-format "initial-response-to-submitter" {
3709
from-address {
3710
fixed-address "gnats-admin"
3711
}
3712
to-addresses {
3713
"Reply-To:" | "From:" | "Submitter-Id"
3714
} ...
3715
3716
This partial `mail-format' section specifies the format of the
3717
address headers in the email message that is sent out as an
3718
acknowledgment of a received PR. The `From:' field of the message will
3719
contain the email address of the GNATS administrator, as specified by
3720
the `gnats-admin' line in the `responsible' file. To fill in the `To:'
3721
header, GNATS will first look for the mail header `Reply-To:' in the PR
3722
and use the contents of that, if any. If that header doesn't exist or
3723
is empty, it will look for the contents of the `From:' email header,
3724
and if that yields nothing, it will look for the GNATS `Submitter-Id'
3725
field and use the contents of that.
3726
3727
Other email headers to be included in messages sent out by GNATS can
3728
be specified by `header' subsections of the `mail-header' section.
3729
`formatstring' and `fieldname' are similar to those used by the named
3730
query format. Each header line must have a newline character (`\n') at
3731
the end.
3732
3733
The email message body is specified in the `body' subsection of the
3734
`mail-format' section. Just as for a `header' section, the `body'
3735
section must contain a `formatstring' and `fieldname' values.
3736
3737
For some of the formats that GNATS recognizes, special variables are
3738
available for use. The following table lists the formats that provide
3739
special variables. See the example below for an illustration of how
3740
they are used.
3741
3742
`appended-email-response'
3743
3744
`$MailFrom'
3745
The From: line of the original message.
3746
3747
`$MailTo'
3748
The To: line of the original message.
3749
3750
`$MailSubject'
3751
The Subject: line of the original message.
3752
3753
`$MailCC'
3754
The CC: line of the original message.
3755
3756
`$NewAuditTrail'
3757
The text of the new audit trail entry (corresponds to the
3758
body of the message).
3759
3760
`audit-mail'
3761
3762
`$EditUserEmailAddr'
3763
The email address of the user editing the PR. Set by the
3764
`EDITADDR' `gnatsd' command or from the `responsible' file;
3765
if not available, user's local address is used.
3766
3767
`$OldResponsible'
3768
The previous Responsible field entry, if it was changed.
3769
3770
`$NewAuditTrail'
3771
The Audit-Trail: entries that have been appended by the edits.
3772
3773
`deleted-pr-mail'
3774
3775
`$EditUserEmailAddr'
3776
The email address of the user deleting the PR. Set by the
3777
`EDITADDR' `gnatsd' command or from the `responsible' file;
3778
if not available, user's local address is used.
3779
3780
`$PRNum'
3781
The number of the PR that was deleted.
3782
3783
The following example illustrates the use of these special variables:
3784
3785
mail-format "deleted-pr-mail" {
3786
from-address {
3787
"$EditUserEmailAddr"
3788
}
3789
to-addresses {
3790
fixed-address "gnats-admin"
3791
}
3792
header {
3793
format "Subject: Deleted PR %s\n"
3794
fields { "$PRNum" }
3795
}
3796
body {
3797
format "PR %s was deleted by user %s.\n"
3798
fields { "$PRNum" "$EditUserEmailAddr" }
3799
}
3800
}
3801
3802
This `mail-format' section specifies the format of the email message
3803
that is sent out when a PR is deleted. The `From:' field is set to the
3804
email address field of the user who deleted the PR, the subject of the
3805
message contains the number of the deleted PR, and the message body
3806
contains both the PR number and the user's email address.
3807
3808
3809
File: gnats.info, Node: Index file description, Next: Initial PR input fields, Prev: Outgoing email formats, Up: dbconfig file
3810
3811
4.3.8 Index file description
3812
----------------------------
3813
3814
The `index' section of the `dbconfig' file lists the fields that appear
3815
in the database index. The index is always keyed by PR number. The
3816
general format for the `index' section is
3817
3818
index {
3819
path "file"
3820
fields { "fieldname" [ "fieldname" ... ] }
3821
binary-index true | false
3822
[ separator "symbol" ]
3823
}
3824
3825
The `path' parameter gives the name of the index file in the
3826
`gnats-adm' directory of the database. Only one index is allowed per
3827
database, so only one `path' entry is allowed.
3828
3829
The `fields' parameter controls what fields will appear, and in what
3830
order, in the index. Fields are listed by their names, separated by
3831
spaces (` '). Fields will appear in the order they are listed.
3832
3833
The `binary-index' parameter controls whether the index is supposed
3834
to be in plaintext or binary format. Binary format is recommended, as
3835
it avoids potential problems when field separators appear as bona-fide
3836
field contents.
3837
3838
When plaintext format is used, by setting `binary-index false', the
3839
symbol (`|') is used as a field separator in the index, unless the
3840
optional `separator' parameter is used to redefine the separator
3841
character.
3842
3843
3844
File: gnats.info, Node: Initial PR input fields, Prev: Index file description, Up: dbconfig file
3845
3846
4.3.9 Initial PR input fields
3847
-----------------------------
3848
3849
An `initial-entry' section in the `dbconfig' file is used to describe
3850
which fields should be present on initial PR entry; this is used by
3851
tools such as send-pr to determine which fields to include in a "blank"
3852
PR template. An optional `require' parameter can be defined to specify
3853
a subset of the `intial-entry' fields which must be assigned a value
3854
upon initial creation of the PR.
3855
3856
The general format for the `initial-entry' section is
3857
3858
initial-entry {
3859
fields { "fieldname" [ "fieldname" ... ] }
3860
[ require { "fieldname" [ "fieldname" ... ] } ]
3861
}
3862
3863
3864
File: gnats.info, Node: Other config files, Next: send-pr.conf file, Prev: dbconfig file, Up: Management
3865
3866
4.4 Other database-specific config files
3867
========================================
3868
3869
* Menu:
3870
3871
* categories file::
3872
* responsible file::
3873
* submitters file::
3874
* states file::
3875
* addresses file::
3876
* classes file::
3877
3878
3879
File: gnats.info, Node: categories file, Next: responsible file, Up: Other config files
3880
3881
4.4.1 The `categories' file
3882
---------------------------
3883
3884
The `categories' file contains a list of problem categories, specific
3885
to the database, which GNATS tracks. This file also matches
3886
responsible people with these categories. You must edit this file
3887
initially, creating valid categories. In most installations, GNATS is
3888
configured to create directories on disk for valid categories
3889
automatically as needed (*note Overall database configuration: Overall
3890
database configuration.). If GNATS isn't set up to do this, you need to
3891
run `mkcat' to create the corresponding subdirectories of the database
3892
directory. For instructions on running `mkcat', see *Note Adding a
3893
problem category: mkcat.
3894
3895
To create a new category, log in as GNATS, add a line to this file,
3896
and run `mkcat' if applicable. Lines beginning with `#' are ignored.
3897
3898
A line in the `categories' file consists of four fields delimited by
3899
colons, as follows:
3900
3901
CATEGORY:DESCRIPTION:RESPONSIBLE:NOTIFY
3902
3903
3904
CATEGORY
3905
A unique category name, made up of text characters. This name
3906
cannot contain spaces or any of the following characters:
3907
3908
! $ & * ( ) { } [ ] ` ' " ; : < > ~
3909
3910
Ideally, category names should not contain commas or begin with
3911
periods. Each line has a corresponding subdirectory in the
3912
database directory.
3913
3914
DESCRIPTION
3915
A terse textual description of the category.
3916
3917
RESPONSIBLE
3918
The name tag of the party responsible for this category of
3919
problems, as listed in the `responsible' file (*note The
3920
`responsible' file: responsible file.).
3921
3922
NOTIFY
3923
One or more other parties which should be notified when a Problem
3924
Report with this category arrives, such as a project manager,
3925
other members of the same project, other interested parties, or
3926
even log files. These should be separated with commas.
3927
3928
A good strategy for configuring this file is to have a different
3929
category for each product your organization supports or wishes to track
3930
information for.
3931
3932
rock:ROCK program:me:myboss,fred
3933
stone:STONE utils:barney:fred
3934
iron:IRON firewall:me:firewall-log
3935
3936
In the above example, the nametags `myboss', `me', `fred', and
3937
`barney' must be defined in the `responsible' file (*note The
3938
`responsible' file: responsible file.).
3939
3940
Problem Reports with a category of `rock' are sent to the local mail
3941
address (or alias) `me', and also sent to the addresses `myboss' and
3942
`fred'. PRs with a category of `stone' are sent to the local addresses
3943
`barney' and `fred' only, while PRs with the category `iron' are sent
3944
only to `me', and are also filed in `firewall-log' (in this case, a
3945
mail alias should be set up, *note Setting up mail aliases: Aliases.
3946
3947
If you want to separate PRs in each problem category into specific
3948
subsets, say _documentation_ and _software bugs_, using the `classes'
3949
file is recommended. *Note The `classes' file: classes file.
3950
3951
Only one category _must_ be present for GNATS to function:
3952
3953
pending:Non-categorized PRs:gnats-admin:
3954
3955
The `pending' directory is created automatically when you run `mkdb'
3956
to initialize a new database. (*note Configuring and compiling the
3957
software: Configure and make.).
3958
3959
3960
File: gnats.info, Node: responsible file, Next: submitters file, Prev: categories file, Up: Other config files
3961
3962
4.4.2 The `responsible' file
3963
----------------------------
3964
3965
This file contains a list of the responsible parties. Lines beginning
3966
with `#' are ignored. Each entry contains three fields, separated by
3967
colons:
3968
3969
RESPONSIBLE:FULL-NAME:MAIL-ADDRESS
3970
3971
3972
RESPONSIBLE
3973
A name-tag description of the party in question, such as her or
3974
his user name, or the name of the group. This name is listed in
3975
the PR in the `Responsible' field.
3976
3977
FULL-NAME
3978
The full name of the party ("Charlotte Bronte"; "Compiler Group").
3979
3980
MAIL-ADDRESS
3981
The full, valid mail address of the party. This field is only
3982
necessary if the responsible party has no local mail address or
3983
alias.
3984
3985
A sample `responsible' listing might be:
3986
3987
ren:Ren Hoek:
3988
stimpy:Stimpson J. Cat:stimpy@lederhosen.org
3989
3990
Here, `ren' is a local user. `stimpy' is remote, so his full address
3991
must be specified.
3992
3993
The following entry _must_ be present for GNATS to function:
3994
3995
gnats-admin:GNATS administrator:
3996
3997
`gnats-admin' is usually defined as a mail alias when GNATS is
3998
installed, so for this purpose `gnats-admin' is a local address.
3999
However, this line can alos be used to redefine the email address of the
4000
GNATS administrator, by adding the desired address at the end of the
4001
line.
4002
4003
4004
File: gnats.info, Node: submitters file, Next: states file, Prev: responsible file, Up: Other config files
4005
4006
4.4.3 The `submitters' file
4007
---------------------------
4008
4009
This is a database of sites which submit bugs to your support site. It
4010
contains six fields delineated by colons. Lines beginning with `#'
4011
will be ignored.
4012
4013
Entries are of the format:
4014
4015
SUBMITTER-ID:NAME:TYPE:RESP-TIME:CONTACT:NOTIFY
4016
4017
4018
SUBMITTER-ID
4019
A unique identifier for a specific site or other entity who submits
4020
Problem Reports. The first `submitter-id' listed in the file will
4021
be the default for PRs that arrive with invalid or empty submitter
4022
fields.
4023
4024
NAME
4025
The full name or a description of this entity.
4026
4027
TYPE
4028
Optional description for the type of relationship of this
4029
submitter to your support site. This could indicate a contract
4030
type, a level of expertise, etc., or it can remain blank.
4031
4032
RESP-TIME
4033
Optional quoted response time in "business hours". If the
4034
database `dbconfig' file has the `notify-about-expired-prs' entry
4035
set to TRUE (*note Overall database configuration: Overall
4036
database configuration, GNATS will use this field to schedule when
4037
it should notify the gnats-admin, responsible person and submitter
4038
contact that the PR wasn't analyzed within the agreed response
4039
time. Business hours and business-week days are set in the
4040
`dbconfig' file. For information on `at-pr', the program which
4041
sends out this reminder, see *Note Timely Reminders: at-pr.
4042
4043
CONTACT
4044
The name tag of the main "contact" at the Support Site for this
4045
submitter. This contact should be in the `responsible' file
4046
(*note The `responsible' file: responsible file.). Incoming bugs
4047
from SUBMITTER are sent to this contact. Optionally, this field
4048
can be left blank.
4049
4050
NOTIFY
4051
Any other parties who should receive copies of Problem Reports
4052
sent in by SUBMITTER. They need not be listed in the
4053
`responsible' file.
4054
4055
A few example entries in the `submitters' file:
4056
4057
univ-hell:University of Hades:eternal:3:beelzebub:lucifer
4058
tta:Telephones and Telegraphs of America:support:720:dave:
4059
4060
In this example, when a PR comes in from the University of Hades (who
4061
has an eternal contract), it should have `univ-hell' in its
4062
`Submitter-Id' field. This Problem Report goes to `beelzebub' (who
4063
should be in the `responsible' file), and if it is not analyzed within
4064
three business hours a reminder message is sent. `lucifer' also
4065
receives a copy of the bug, and a copy of the reminder message as well
4066
(if it is sent). When Telephones and Telegraphs of America utilizes
4067
their support contract and submits a bug, a copy is sent only to
4068
`dave', who has 720 business hours to return an analysis before a
4069
reminder is sent.
4070
4071
To disable the feature of GNATS which tracks the `Submitter-Id',
4072
simply alter the `submitters' file to only contain one SUBMITTER-ID
4073
value, and instruct your submitters to ignore the field.
4074
4075
4076
File: gnats.info, Node: states file, Next: addresses file, Prev: submitters file, Up: Other config files
4077
4078
4.4.4 The `states' file
4079
-----------------------
4080
4081
This file lists the possible states for Problem Reports. Each entry
4082
has up to three fields, separated by colons. Lines beginning with `#'
4083
will be ignored.
4084
4085
STATE:TYPE:DESCRIPTION
4086
4087
4088
STATE
4089
The name of the state. It may contain alphanumerics as well as
4090
`-' (hyphen), `_' (underscore), or `.' (period), but no other
4091
characters.
4092
4093
TYPE
4094
This is the type of the state. This field is optional and it may
4095
contain alphanumerics as well as `-' (hyphen), `_' (underscore),
4096
or `.' (period), but no other characters.
4097
4098
The concept of the type of a state recognizes that there may for
4099
instance be several possible states for a Problem Report which
4100
effectively means that the PR is closed and that there may be
4101
certain actions that need to be taken when a PR reaches a "closed
4102
state". The problem may have been resolved, it might have been
4103
decided that the problem is unsolvable or simply that it won't be
4104
solved. Some organizations may for instance wish to consider the
4105
"suspended" state as a state of type "closed".
4106
4107
Currently, the only defined state types are "open" and "closed",
4108
the "open" type isn't currently used for anything while the
4109
"closed" type is only used to control the Closed-Date field of PRs.
4110
Changing the state of a PR to any state of type "closed" will set
4111
the Closed-Date field with a time stamp and changing the state of
4112
a PR from one "closed" state to another will leave the Closed-Date
4113
field as it was. Changing the state of a PR from any state of type
4114
"closed" to a non-closed state will clear the Closed-Date field.
4115
4116
The `--skip-closed' option of `query-pr' refers to all states of
4117
type "closed", not to a specific state name of "closed".
4118
4119
DESCRIPTION
4120
This is is an optional one-line description of what the state
4121
means. Any character is okay in the description; a newline ends
4122
it. GNATS itself does not currently use the description for
4123
anything, but certain external tools (such as TkGnats and
4124
Gnatsweb) look for it, so it's a good idea to include one for
4125
every state.
4126
4127
The first state listed will be the state automatically assigned to
4128
Problem Reports when they arrive; by default this is named "open". The
4129
last state listed is the end state for Problem Reports -- one should
4130
usually assume that a PR in this state is not being actively worked on;
4131
by default this state is named "closed". Even if a different name has
4132
been chosen for this state, GNATS will force this state to be of type
4133
"closed".
4134
4135
It is recommended that you keep the default names of "open" and
4136
"closed" for the first and last states respectively, since there may be
4137
external tools that depend on these names.
4138
4139
4140
File: gnats.info, Node: addresses file, Next: classes file, Prev: states file, Up: Other config files
4141
4142
4.4.5 The `addresses' file
4143
--------------------------
4144
4145
This file contains mappings between submitter IDs and corresponding
4146
e-mail addresses.
4147
4148
When a PR comes in without a submitter ID (if someone sends
4149
unformatted e-mail to the PR submission email address), GNATS will try
4150
to derive the submitter ID from the address in the "From:" header. The
4151
entries in this file consist of two fields, separated by a colon:
4152
4153
SUBMITTER-ID:ADDRESS-FRAGMENT
4154
4155
4156
SUBMITTER-ID
4157
A valid submitter ID
4158
4159
ADDRESS-FRAGMENT
4160
Part of, or all of the e-mail address to be matched
4161
4162
Here is an example of an `addresses' file:
4163
4164
# Addresses for Yoyodine Inc
4165
yoyodine:yoyodine.com
4166
yoyodine:yoyodine.co.uk
4167
# Addresses for Foobar Inc.
4168
foobar1:sales.foobar.com
4169
foobar2:admin.foobar.com
4170
foobar3:clark@research.foobar.com
4171
4172
GNATS checks each line in the `addresses' file, comparing
4173
ADDRESS-FRAGMENT to the end of the "From:" header, until it finds a
4174
match. If no match is found, GNATS uses the default submitter ID.
4175
4176
You can only have one address fragment per line, but you can have
4177
more than one line for a given submitter ID. An address fragment can
4178
be a domain (i.e. yoyodine.com), a machine location (admin.foobar.com),
4179
or a full e-mail address (clark@research.foobar.com).
4180
4181
GNATS can match addresses in three e-mail formats:
4182
4183
`From: name@address.com'
4184
The address by itself without a full name, not enclosed in brackets
4185
4186
`From: Real Person <name@address.com>'
4187
A full name (optional, with or without quotation marks), followed
4188
by the address enclosed in angle brackets
4189
4190
`From: name@address.com (Real Person)'
4191
An address, followed by a name or comment in parentheses
4192
4193
If GNATS sees other e-mail address formats, it uses the default
4194
submitter ID.
4195
4196
4197
File: gnats.info, Node: classes file, Prev: addresses file, Up: Other config files
4198
4199
4.4.6 The `classes' file
4200
------------------------
4201
4202
This file lists the possible classes of Problem Reports. Each line
4203
consists of a class name, followed by a colon and an optional class type
4204
name (the class type name is not used for anything in the current
4205
implementation of GNATS, so it may be left blank. The `class' and
4206
`class-type-name' fields may only contain alphanumerics, `-', `_', and
4207
`.', but no other characters.
4208
4209
Then comes another colon, followed by an optional one-line
4210
description of the class. GNATS itself does not use the class
4211
description, but external tools such as Gnatsweb and TkGnats may use it.
4212
Therefore, a line in this file should at least contain the following:
4213
4214
class::class description
4215
4216
Lines beginning with `#' will be ignored, and the first listed class
4217
is the default class for an incoming Problem Report.
4218
4219
4220
File: gnats.info, Node: send-pr.conf file, Next: Admin files, Prev: Other config files, Up: Management
4221
4222
4.5 The `send-pr.conf' file
4223
===========================
4224
4225
This file contains some default values that need to be known in order
4226
for `send-pr' to work properly. This file needs to be copied to all
4227
hosts where `send-pr' will be used.
4228
4229
If GNATS was built with default options, the `send-pr.conf' file
4230
should be placed in the `/usr/local/etc/gnats' directory. However, if
4231
the option `--sysconfdir' was used during building of GNATS, the
4232
`send-pr.conf' file resides at the location given to this option.
4233
4234
Entries in this file are on the format
4235
4236
variable=VALUE
4237
4238
The valid variables are:
4239
4240
`SUBMITTER'
4241
The default value to be used for the Submitter-Id field when
4242
`send-pr' is invoked.
4243
4244
`DEFAULT_RELEASE'
4245
The default value to be used for the Release field (only
4246
applicable if the Release field is defined in the `dbconfig' file.
4247
4248
`DEFAULT_ORGANIZATION'
4249
The default value to be used for the Organization field. (only
4250
applicable if the Organization field is defined in the `dbconfig'
4251
file.
4252
4253
`MAILPROG'
4254
If the GNATS server can't be reached directly over the network,
4255
i.e. it is behind a firewall or suchlike, `send-pr' can be set up
4256
to submit Problem Reports by e-mail. This is done by setting the
4257
`MAILPROG' variable to point to a mailer such as Sendmail. If
4258
`MAILPROG' needs to have the address that the mail is being sent
4259
to specified on the command line, it should be specified here as
4260
well (for example, `MAILPROG=''mail bugs@foo.bar.com''' should
4261
work). If Sendmail is used, use `MAILPROG=''/usr/lib/sendmail -oi
4262
-t'''. See also `MAILADDR' and `TEMPLATE' below.
4263
4264
`MAILADDR'
4265
If using e-mail to submit PRs, this is the address that PRs should
4266
be sent to.
4267
4268
`TEMPLATE'
4269
When invoked, `send-pr' communicates directly over the network
4270
with the GNATS server to determine what fields to include in a
4271
correctly formatted Problem Report so that it can present the user
4272
with a template. If the GNATS server can't be reached directly
4273
over the network, a template must be provided. Set the `TEMPLATE'
4274
variable to point to a template file created on the GNATS server
4275
by using the command `send-pr -p'. *Note Installing the user
4276
tools: Installing tools.
4277
4278
4279
File: gnats.info, Node: Admin files, Next: Admin utils, Prev: send-pr.conf file, Up: Management
4280
4281
4.6 Administrative data files
4282
=============================
4283
4284
The following files are database-specific and are located in the
4285
`gnats-adm' subdirectory of the database directory. These files are
4286
maintained by GNATS; you should never need to touch them.
4287
4288
* Menu:
4289
4290
* index file:: The `index' file
4291
* current file:: The `current' file
4292
4293
4294
File: gnats.info, Node: index file, Next: current file, Up: Admin files
4295
4296
4.6.1 The `index' file
4297
----------------------
4298
4299
The index is used to accelerate searches on the database by `query-pr'
4300
and `edit-pr'. This file is not created until the first PR comes in.
4301
It is then kept up to date by GNATS; you should never touch this file.
4302
4303
Searches on subjects contained in the index are much faster than
4304
searches which depend on data not in the index. Inexes come in two
4305
different formats: "binary" and "plain-text". Binary indexes are
4306
safer, in that they avoid certain problems that may crop up if the
4307
field separators used by plain-text indexes appear in field data.
4308
4309
A plain-text index contains single-line entries for all PR fields
4310
except for the multitext fields such as Description, How-To-Repeat,
4311
etc. Fields are separated by bars (`|') except for `Category' and
4312
`Number', which are separated by a slash (`/').
4313
4314
Binary indexes are not meant to be human-readable, but they are safer
4315
than the plain-text variety, in that they avoid certain problems that
4316
may crop up if the field separators used by plain-text indexes appear in
4317
field data.
4318
4319
The format of the index for a database is set in the `dbconfig'
4320
file. *Note Index file description: Index file description.
4321
4322
Should the `index' file become corrupted, the `gen-index' utility
4323
can be used to regenerate it. *Note Regenerating the index: gen-index.
4324
4325
4326
File: gnats.info, Node: current file, Prev: index file, Up: Admin files
4327
4328
4.6.2 The `current' file
4329
------------------------
4330
4331
This file contains the last serial number assigned to an incoming PR.
4332
It is used internally by GNATS; you need never touch this file.
4333
4334
4335
File: gnats.info, Node: Admin utils, Next: Internal utils, Prev: Admin files, Up: Management
4336
4337
4.7 Administrative utilities
4338
============================
4339
4340
These tools are used by the GNATS administrator as part of the periodic
4341
maintenance and configuration of GNATS. *Note GNATS Administration:
4342
Management.
4343
4344
* Menu:
4345
4346
* mkdb:: Adding another database
4347
* mkcat:: Adding a problem category
4348
* rmcat:: Removing a problem category
4349
* gen-index:: Regenerating the index
4350
* check-db:: Checking database health
4351
* gnats-pwconv:: Managing user passwords
4352
4353
4354
File: gnats.info, Node: mkdb, Next: mkcat, Up: Admin utils
4355
4356
4.7.1 Adding another database
4357
-----------------------------
4358
4359
To initialize a new GNATS database:
4360
4361
1. Add a line for the new database in the `databases' file (*note
4362
Where GNATS lives: Locations.
4363
4364
2. Run `mkdb', using
4365
4366
mkdb DATABASE
4367
4368
where DATABASE is the database you specified in the `databases'
4369
file. `mkdb' creates the database directory and populates it with
4370
the directories `pending', `gnats-queue' and `gnats-adm'. A full
4371
set of sample configuration files is copied to the `gnats-adm'
4372
directory.
4373
4374
4375
File: gnats.info, Node: mkcat, Next: rmcat, Prev: mkdb, Up: Admin utils
4376
4377
4.7.2 Adding a problem category
4378
-------------------------------
4379
4380
To add new categories to the database:
4381
4382
1. Add a line to for each new category to the `categories' file in the
4383
gnats-adm directory of the database. *Note The `categories' file:
4384
categories file.
4385
4386
2. Run `mkcat' If applicable. If `create-category-dirs' is set to
4387
`false' in the database `dbconfig' file, you need to create
4388
category directories with `mkcat'. `mkcat' creates a subdirectory
4389
under the database directory for any new categories which appear
4390
in the `categories' file.
4391
4392
4393
File: gnats.info, Node: rmcat, Next: gen-index, Prev: mkcat, Up: Admin utils
4394
4395
4.7.3 Removing a problem category
4396
---------------------------------
4397
4398
To remove a category from the database:
4399
4400
1. Remove the Problem Reports from the subdirectories corresponding
4401
to the categories you wish to remove, or assign the PRs to new
4402
categories. All PRs for a given category reside in a subdirectory
4403
of the database directory, with the same name as the category.
4404
4405
2. Run `rmcat' using
4406
4407
rmcat CATEGORY [ CATEGORY... ]
4408
4409
where CATEGORY is the category you wish to remove. You can
4410
specify as many categories as you wish as long as each category
4411
has no PRs associated with it. `rmcat' removes the directory
4412
where the Problem Reports for that category had been stored.
4413
4414
4415
File: gnats.info, Node: gen-index, Next: check-db, Prev: rmcat, Up: Admin utils
4416
4417
4.7.4 Regenerating the index
4418
----------------------------
4419
4420
If your `index' file becomes corrupted, or if you need a copy of the
4421
current index for some reason, use
4422
4423
gen-index [ -n | --numeric ]
4424
[ -d DATABASENAME | --database=DATABASENAME ]
4425
[ -o FILENAME | --outfile=FILENAME ]
4426
[ -i | --import ] [ -e | --export ]
4427
[ -h | --help] [ -V | --version ]
4428
4429
With no options, `gen-index' generates an index that is sorted by the
4430
order that the categories appear in the `categories' file. The index is
4431
generated in plaintext or binary format according to the value of
4432
`binary-index' in the `dbconfig' file (*note Index file description:
4433
Index file description.). The results are printed to standard output.
4434
The options are:
4435
4436
`-n'
4437
`--numeric'
4438
Sorts index entries numerically.
4439
4440
`-d DATABASENAME'
4441
`--database=DATABASENAME'
4442
Specifies the database to index. If this option is left out,
4443
`gen-index' attempts to index the database with name taken from the
4444
the GNATSDB environment variable, and if that is undefined, the
4445
default database, as set when GNATS was built (usually `default').
4446
4447
`-o FILENAME'
4448
`--outfile=FILENAME'
4449
Places output in FILENAME rather than sending it to standard
4450
output.
4451
4452
`-i'
4453
`--import'
4454
Import the existing index file instead of re-indexing the database.
4455
4456
`-e'
4457
`--export'
4458
Force plaintext output.
4459
4460
`-h'
4461
`--help'
4462
Prints the usage for `gen-index'.
4463
4464
`-V'
4465
`--version'
4466
Prints the version number for `gen-index'.
4467
4468
4469
File: gnats.info, Node: check-db, Next: gnats-pwconv, Prev: gen-index, Up: Admin utils
4470
4471
4.7.5 Checking database health
4472
------------------------------
4473
4474
The `check-db' script is useful for performing periodic checks on
4475
database health. It accepts the following options:
4476
4477
`-d DATABASENAME'
4478
`--database=DATABASENAME'
4479
Determines the database which to operate on.
4480
4481
`--all-databases'
4482
Check all GNATS databases on the system. This option takes
4483
precedence over the `--database' option.
4484
4485
If no option is given, the default database is checked.
4486
4487
During its operation, `check-db' first attempts to lock DATABASE.
4488
If this is not possible, it repeats the locking attempts for five
4489
minutes; if it fails, it sends a mail message notifying the
4490
administrator of the failure and exits.
4491
4492
Once the database is locked, the script searches the database for
4493
lock files that are more than 24 hours old. Any old lock files are
4494
reported to the administrator in a mail message.
4495
4496
After checking for old lock files, it calls `gen-index' (*note
4497
Regenerating the index: gen-index.) and compares the results with the
4498
current `index' file of the database; any inconsistencies are reported
4499
to the administrators in a mail message.
4500
4501
After checking the index file for inconsistencies, the script unlocks
4502
the database and exits.
4503
4504
4505
File: gnats.info, Node: gnats-pwconv, Prev: check-db, Up: Admin utils
4506
4507
4.7.6 Managing user passwords
4508
-----------------------------
4509
4510
Older versions of GNATS, up to and including version 3.x, stored user
4511
passwords in plaintext in the `gnatsd.user_access' files. Version 4 has
4512
the options of storing the password as MD5 or standard DES `crypt()'
4513
hashes (as most UNIX versions do in the system password files) as well
4514
as in plaintext. Since the password strings require a prefix to
4515
indicate how they are encrypted, one is forced to convert the old
4516
password files to a new format when upgrading to GNATS version 4. *Note
4517
Upgrading from older versions: Upgrading.
4518
4519
The `gnats-pwconv' tool takes care of converting the old password
4520
files to the new format:
4521
4522
gnats-pwconv [ -c | --crypt ] [ -m | --md5 ] [ -p | --plaintext ]
4523
[ -h | --help] [ -V | --version ] INFILE [OUTFILE]
4524
4525
Unless the `--version' or `--help' options are given, exactly one
4526
encryption method must be specified, as well as an input file. The
4527
output file parameter is optional. If one is not specified, results will
4528
be printed on standard output.
4529
4530
4531
File: gnats.info, Node: Internal utils, Prev: Admin utils, Up: Management
4532
4533
4.8 Internal utilities
4534
======================
4535
4536
These tools are used internally by GNATS. You should never need to run
4537
these by hand; however, a complete understanding may help you locate
4538
problems with the GNATS tools or with your local implementation.
4539
4540
* Menu:
4541
4542
* queue-pr:: Handling incoming traffic
4543
* file-pr:: Processing incoming traffic
4544
* at-pr:: Timely reminders
4545
* pr-edit:: The edit-pr driver
4546
* diff-prs:: The `diff-prs' tool
4547
* pr-age:: The `pr-age' tool
4548
4549
4550
File: gnats.info, Node: queue-pr, Next: file-pr, Up: Internal utils
4551
4552
4.8.1 Handling incoming traffic
4553
-------------------------------
4554
4555
The program `queue-pr' handles traffic coming into GNATS. `queue-pr'
4556
queues incoming Problem Reports in the `gnats-queue' directory of the
4557
database, and then periodically (via `cron') passes them on to
4558
`file-pr' to be filed in the GNATS database. *Note Installing GNATS:
4559
Installation.
4560
4561
The usage for `queue-pr' is as follows:
4562
4563
queue-pr [ -q | --queue ] [ -r | --run ]
4564
[ -f FILENAME | --file=FILENAME ]
4565
[ -m KBYTES | --max-size=KBYTES ]
4566
[ -d DATABASENAME | --database=DATABASENAME ]
4567
[ -h | --help] [ -V | --version ]
4568
4569
One of `-q' or `-r' (or their longer-named counterparts) must be
4570
present upon each call to `queue-pr'. These options provide different
4571
functions, as described below.
4572
4573
`-q'
4574
`--queue'
4575
Accepts standard input as an incoming mail message, placing this
4576
message in an incrementally numbered file in the `gnats-queue'
4577
directory under the database directory (*note Where GNATS lives:
4578
Locations.).
4579
4580
`-r'
4581
`--run'
4582
Redirects files in the `gnats-queue' directory into the program
4583
`file-pr' one by one.
4584
4585
`-f FILENAME'
4586
`--file=FILENAME'
4587
Used with `-q' (or `--queue'), accepts the file denoted by
4588
FILENAME as input rather than reading from standard input.
4589
4590
`-m KBYTES'
4591
`--max-size=KBYTES'
4592
Do not process messages larger then KBYTES kilobytes. Files
4593
larger than the limit are left for human intervention.
4594
4595
`-d DATABASENAME'
4596
`--directory=DATABASENAME'
4597
Specifies database to operate on. If this option is left out, the
4598
value of the GNATSDB environment variable is used, and if that is
4599
undefined, the default database name set when GNATS was built is
4600
used (usually `default').
4601
4602
`-h'
4603
`--help'
4604
Prints the usage for `gen-index'.
4605
4606
`-V'
4607
`--version'
4608
Prints the version number for `gen-index'.
4609
4610
4611
File: gnats.info, Node: file-pr, Next: at-pr, Prev: queue-pr, Up: Internal utils
4612
4613
4.8.2 Processing incoming traffic
4614
---------------------------------
4615
4616
`queue-pr' hands off queued Problem Reports to `file-pr' one at a time.
4617
`file-pr' checks each Problem Report for correct information in its
4618
fields (particularly a correct `Category'), assigns it an
4619
identification number, and files it in the database under the
4620
appropriate category.
4621
4622
If the `Category' field does not contain a valid category value
4623
(i.e., matching a line in the `categories' file; *note The `categories'
4624
file: categories file.), the PR is assigned to the default category, as
4625
set in the `dbconfig' file. If there is no default category defined,
4626
the PR is given a `Category' value of `pending' and is placed in the
4627
`pending' directory. The GNATS administrator is notified of the
4628
unplaceable PR.
4629
4630
`file-pr' assigns the Problem Report an identification number, files
4631
it in the GNATS database (under the default, if the `Category' field
4632
contains an invalid category), and sends acknowledgments to appropriate
4633
parties. For the default GNATS configuration, the person responsible
4634
for that category of problem (*note The `categories' file: categories
4635
file.) and the person responsible for the submitter site where the PR
4636
originated (*note The `submitters' file: submitters file.) receive a
4637
copy of the PR in its entirety. Optionally, the originator of the PR
4638
receives an acknowledgment that the PR arrived and was filed (*note
4639
Changing your GNATS configuration: GNATS configuration.).
4640
4641
The usage for `file-pr' is as follows:
4642
4643
file-pr [ -f FILENAME | --file=FILENAME ]
4644
[ -d DATABASENAME | --database=DATABASENAME ]
4645
[ -h | --help ] [ -V | --version ]
4646
4647
network options:
4648
[ -H HOST | --host=HOST ]
4649
[ -P PORT | --port=PORT ]
4650
[ -v USERNAME | --user=USERNAME ]
4651
[ -w PASSWORD | --passwd=PASSWORD ]
4652
4653
`file-pr' requires no options in order to operate, and takes input
4654
from standard input (normally, the output of `queue-pr -r') unless
4655
otherwise specified. The options include:
4656
4657
`-f FILENAME'
4658
`--filename=FILENAME'
4659
Uses FILENAME as input rather than standard input.
4660
4661
`-d DATABASENAME'
4662
`--database=DATABASENAME'
4663
Performs refiling operations on DATABASE. If this option is left
4664
out, the value of the GNATSDB environment variable is used, and if
4665
that is undefined, the default database name set when GNATS was
4666
built is used (usually `default').
4667
4668
`-h'
4669
`--help'
4670
Prints the usage for `file-pr'.
4671
4672
`-V'
4673
`--version'
4674
Prints the version number for `file-pr'.
4675
4676
`file-pr' can file PRs across a network, talking to a remote gnatsd.
4677
The following options relate to network access:
4678
4679
`-H HOST'
4680
`--host=HOST'
4681
Hostname of the GNATS server.
4682
4683
`-P PORT'
4684
`--port=PORT'
4685
The port that the GNATS server runs on.
4686
4687
`-v USERNAME'
4688
`--username=USERNAME'
4689
Username used to log into the GNATS server.
4690
4691
`-w PASSWORD'
4692
`--passwd=PASSWORD'
4693
Password used to log into the GNATS server.
4694
4695
4696
File: gnats.info, Node: at-pr, Next: pr-edit, Prev: file-pr, Up: Internal utils
4697
4698
4.8.3 Timely reminders
4699
----------------------
4700
4701
`at-pr' creates a queued job using `at' which, after an allotted
4702
"response time" is past, checks the PR to see if its state has changed
4703
from `open'. When the PR is originally filed, `file-pr' checks the
4704
`notify-about-expired-prs' parameter in the `dbconfig' file. If this
4705
parameter is set to `true', `file-pr' calls `at-pr', which sets up the
4706
expiry check.
4707
4708
The `submitters' file contains the response time for each
4709
`>Submitter-Id:' (*note The `submitters' file: submitters file.). The
4710
time is determined in "business hours", which are defined in the
4711
database's `dbconfig' file (*note Overall database configuration:
4712
Overall database configuration.).
4713
4714
If the PR is urgent and is still open after the requisite time period
4715
has passed, `at-pr' sends a reminder to the GNATS administrator, to the
4716
maintainer responsible for that submitter, and to the maintainer
4717
responsible for the PR with the following message:
4718
4719
To: SUBMITTER-CONTACT RESPONSIBLE GNATS-ADMIN
4720
Subject: PR GNATS-ID not analyzed in #HOURS hours
4721
4722
PR GNATS-ID was not analyzed within the acknowledgment period
4723
of #HOURS business hours. The pertinent information is:
4724
4725
Submitter-Id: SUBMITTER
4726
Originator: FULL NAME OF THE SUBMITTER
4727
Synopsis: SYNOPSIS
4728
Person responsible for the PR: RESPONSIBLE
4729
4730
--
4731
The GNU Problem Report Management System (GNATS)
4732
4733
The PR is "urgent" if its priority is `critical' or if its priority
4734
is `serious' and the severity is `high'.
4735
4736
4737
File: gnats.info, Node: pr-edit, Next: diff-prs, Prev: at-pr, Up: Internal utils
4738
4739
4.8.4 The `edit-pr' driver
4740
--------------------------
4741
4742
`pr-edit' does the background work for `edit-pr', including
4743
error-checking and refiling newly edited Problem Reports, handling file
4744
and database locks and deletion of PRs. It can be called interactively,
4745
though it has no usable editing interface.
4746
4747
The usage for `pr-edit' is:
4748
4749
pr-edit [ -l USERNAME | --lock=USERNAME ] [ -u | --unlockdb ]
4750
[ -L | --lockdb ] [ -U | --unlockdb ] [ -c | --check ]
4751
[ -C | --check-initial ] [ -s | --submit [ --show-prnum ] ]
4752
[ -a FIELD | --append field=FIELD ]
4753
[ -r FIELD | --replace=FIELD ] [ --delete-pr ]
4754
[ -R REASON | --reason=REASON ]
4755
[ -p PROCESS-ID | --process=PROCESS-ID ]
4756
[ -d DATABASENAME | --database=DATABASENAME ]
4757
[ -f FILENAME | --filename=FILENAME ]
4758
[ -V | --version ]
4759
[ -h | --help ] [ -v USERNAME | --user=USERNAME ]
4760
[ -w PASSWD | --passwd=PASSWD ]
4761
[ -H HOST | --host=HOST ]
4762
[ -P PORT | --port=PORT ]
4763
[ -D | --debug ] [ PR NUMBER ]
4764
4765
A "lock" is placed on a Problem Report while the PR is being edited.
4766
The lock is simply a file in the `locks' subdirectory of the
4767
`gnats-adm' directory of the database, with the name `GNATS-ID.lock',
4768
which contains the name of the user who created the lock. USER then
4769
"owns" the lock, and must remove it before the PR can be locked again,
4770
even by the same USER(1). If a PR is already locked when you attempt
4771
to edit it, `pr-edit' prints an error message giving the name of the
4772
user who is currently editing the PR.
4773
4774
If you do not specify PR NUMBER, `pr-edit' reads from standard
4775
input. You must specify PR NUMBER for the functions which affect PR
4776
locks, `--lock=USERNAME' and `--unlock'.
4777
4778
`-L'
4779
`--lockdb'
4780
Locks the database specified with the `--database' or `-d' option.
4781
No PRs may be edited, created or deleted while the database is
4782
locked. This option is generally used when editing the index file.
4783
4784
`-U'
4785
`--unlockdb'
4786
Unlocks the specified database. No check is made that the
4787
invoking user actually had locked the database in the first place;
4788
hence, it is possible for anyone to steal a database lock.
4789
4790
`-c'
4791
`--check'
4792
`-C'
4793
`--check-initial'
4794
The `--check' options are used to verify that a proposed PR's field
4795
contents are valid. The PR is read in (either from stdin or a file
4796
specified with `--filename'), and its fields are compared against
4797
the rules specified by the database configuration of the selected
4798
database. Warnings are given for enumerated fields whose contents
4799
do not contain one of the required values or fields that do not
4800
match required regexps. `--check-initial' is used to verify
4801
initial PRs, rather than proposed edits of existing PRs.
4802
4803
`-s'
4804
`--submit'
4805
Used to submit a new PR to the database. The PR is read in and
4806
verified for content; if the PR is valid as an initial PR, it is
4807
then added to the database. If the submission is successful a
4808
zero exit code is returned. Otherwise, the reason(s) for the PR
4809
being rejected are printed, and a non-zero exit code is returned.
4810
4811
`--show-prnum'
4812
This option is used with the `--submit' option to display the PR
4813
number associated with the submitted PR.
4814
4815
The following options require a PR number to be given.
4816
4817
`--delete-pr'
4818
Deletes the specified PR from the database. The PR must be in a
4819
closed state, and not locked. Only the user _gnats_ (or the user
4820
name specified instead of _gnats_ during the building of GNATS) is
4821
permitted to delete PRs.
4822
4823
`-l USERNAME'
4824
`--lock=USERNAME'
4825
Locks the PR. USERNAME is associated with the lock, so the system
4826
administrator can determine who actually placed the lock on the PR.
4827
However, anyone is permitted to remove locks on a PR. If the
4828
optional `--process' or `-p' option is also given, that process-id
4829
is associated with the lock.
4830
4831
`-u'
4832
`--unlock'
4833
Unlocks the specified PR.
4834
4835
`-a FIELD'
4836
`--append=FIELD'
4837
4838
`-r FIELD'
4839
`--replace=FIELD'
4840
`--append' and `--replace' are used to append or replace content
4841
of a specific field within a PR. The new field content is read in
4842
from stdin (or from the file specified with the `--filename'
4843
option), and either appended or replaced to the specified field.
4844
The field contents are verified for correctness before the PR is
4845
rewritten. If the edit is successful, a zero exit status is
4846
returned. If the edit failed, a non-zero exit status is returned,
4847
and the reasons for the failure are printed to stdout.
4848
4849
`-R REASON'
4850
`--reason=REASON'
4851
Certain PR fields are configured in the database configuration to
4852
require a short text describing the reason of every change that
4853
happens to them, *Note dbconfig file::. If you edit a problem and
4854
change any of such fields, you must issue a short text, the REASON
4855
of the change, through this option. If the option is used and no
4856
change-reason requiring field is actually changed, the option has
4857
no effect.
4858
4859
`PR number'
4860
If only a `PR number' is specified with no other options, a
4861
replacement PR is read in (either from stdin or the file specified
4862
with `--filename'). If the PR contents are valid and correct, the
4863
existing PR is replaced with the new PR contents. If the edit is
4864
successful, a zero exit status is re turned. If the edit failed, a
4865
non-zero exit status is returned, and the reasons for the failure
4866
are printed to stdout.
4867
4868
`-d DATABASE'
4869
`--database=DATABASE'
4870
Specifies the database which is to be manipulated. If no database
4871
is specified, the default database name set when GNATS was built is
4872
used (usually `default'). This option overrides the database
4873
specified in the GNATSDB environment variable.
4874
4875
`-f FILENAME'
4876
`--filename=FILENAME'
4877
For actions that require reading in a PR or field content, this
4878
specifies the name of a file to read. If `--filename' is not
4879
specified, the PR or field content is read in from stdin.
4880
4881
`-h'
4882
`--help'
4883
Prints the usage for `pr-edit'.
4884
4885
`-V'
4886
`--version'
4887
Prints the version number for `pr-edit'.
4888
4889
`pr-edit' can edit PRs across a network, talking to a remote gnatsd.
4890
The following options relate to network access:
4891
4892
`-H HOST'
4893
`--host=HOST'
4894
Hostname of the GNATS server.
4895
4896
`-P PORT'
4897
`--port=PORT'
4898
The port that the GNATS server runs on.
4899
4900
`-v USERNAME'
4901
`--username=USERNAME'
4902
Username used to log into the GNATS server.
4903
4904
`-w PASSWORD'
4905
`--passwd=PASSWORD'
4906
Password used to log into the GNATS server.
4907
4908
`-D'
4909
`--debug'
4910
Used to debug network connections.
4911
4912
---------- Footnotes ----------
4913
4914
(1) This approach may seem heavy-handed, but it ensures that changes
4915
are not overwritten.
4916
4917
4918
File: gnats.info, Node: diff-prs, Next: pr-age, Prev: pr-edit, Up: Internal utils
4919
4920
4.8.5 The `diff-prs' tool
4921
-------------------------
4922
4923
The `diff-prs' tool is invoked as follows:
4924
4925
diff-prs PRFILE1 PRFILE2
4926
4927
`diff-prs' simply reads the PRs contained in PRFILE1 and PRFILE2 and
4928
returns a list of the fields that are different between the two. No
4929
output is produced if the PRs are identical.
4930
4931
4932
File: gnats.info, Node: pr-age, Prev: diff-prs, Up: Internal utils
4933
4934
4.8.6 The `pr-age' tool
4935
-----------------------
4936
4937
The `pr-age' tool reports the time, in days and hours, since the PR
4938
arrived. Usage is
4939
4940
pr-age [ -d DATABASENAME | --database=DATABASENAME ]
4941
[ -H HOST | --host=HOST ]
4942
[ -P PORT | --port=PORT ]
4943
[ -v USERNAME | --user=USERNAME ]
4944
[ -w PASSWORD | --passwd=PASSWORD ]
4945
[ -h | --help ] [ -V | --version ]
4946
4947
For an explanation of the arguments listed above, please refer to the
4948
usage description for `file-pr' (*Note `file-pr': file-pr.).
4949
4950
4951
File: gnats.info, Node: Locations, Next: gnatsd, Prev: Management, Up: Top
4952
4953
Appendix A Where GNATS lives
4954
****************************
4955
4956
We use a few conventions when referring to the installation structure
4957
GNATS uses. These values are adjustable when you build and install
4958
GNATS (*note Installing GNATS: Installation.).
4959
4960
* Menu:
4961
4962
* prefix::
4963
* exec-prefix::
4964
* gnats-adm::
4965
* defaults:: Default installation locations
4966
4967
4968
File: gnats.info, Node: prefix, Next: exec-prefix, Up: Locations
4969
4970
A.1 PREFIX
4971
==========
4972
4973
PREFIX corresponds to the variable `prefix' for `configure', which
4974
passes it on to the `Makefile' it creates. PREFIX sets the root
4975
installation directory for "host-independent" files as follows:
4976
4977
the directory path of the default database
4978
`PREFIX/com'
4979
site-wide configuration files
4980
`PREFIX/etc/gnats'
4981
`man' pages
4982
`PREFIX/man'
4983
4984
`info' documents
4985
`PREFIX/info'
4986
4987
`include' files
4988
`PREFIX/include'
4989
4990
_etc..._
4991
4992
The default value for PREFIX is `/usr/local', which can be changed
4993
on the command line to `configure' using
4994
4995
configure --prefix=PREFIX ...
4996
4997
*Note Configuring and compiling the software: Configure and make.
4998
4999
5000
File: gnats.info, Node: exec-prefix, Next: gnats-adm, Prev: prefix, Up: Locations
5001
5002
A.2 EXEC-PREFIX
5003
===============
5004
5005
EXEC-PREFIX corresponds to the variable `exec-prefix' for `configure',
5006
which passes it on to the `Makefile' it creates. EXEC-PREFIX sets the
5007
root installation for "host-dependent" files as follows:
5008
5009
GNATS user tools
5010
`EXEC-PREFIX/bin'
5011
5012
administrative and support utilities
5013
`EXEC-PREFIX/libexec/gnats'
5014
5015
compiled libraries
5016
`EXEC-PREFIX/lib'
5017
_etc..._
5018
5019
`configure' supports several more options which allow you to specify
5020
in great detail where different files are installed. The locations
5021
given in this appendix do not take into account highly customized
5022
installations, but fairly ordinary GNATS installations should be
5023
covered by the material here. For a complete list of options accepted
5024
by `configure', run `./configure --help' in the `gnats' subdirectory of
5025
the distribution.
5026
5027
Since most installations are not intended to be distributed around a
5028
network, the default value for EXEC-PREFIX is the value of `prefix',
5029
i.e., `/usr/local'. However, using EXEC-PREFIX saves space when you
5030
are installing a package on several different platforms for which many
5031
files are identical; rather than duplicate them for each host, these
5032
files can be shared in a common repository, and you can use symbolic
5033
links on each host to find the host-dependent files.
5034
5035
Use EXEC-PREFIX in conjunction with PREFIX to share host-independent
5036
files, like libraries and `info' documents. For example:
5037
5038
_for each host:_
5039
configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-HOST
5040
make all install ...
5041
5042
Using this paradigm, all host-dependent binary files are installed into
5043
`/usr/gnu/H-HOST/bin', while files which do not depend on the host type
5044
for which they were configured are installed into `/usr/gnu'.
5045
5046
You can then use a different symbolic link for `/usr/gnu' on each
5047
host (`/usr' is usually specific to a particular machine; it is always
5048
specific to a particular architecture).
5049
5050
_on host-1:_
5051
ln -s /usr/gnu/H-HOST-1 /usr/gnu
5052
_on host-2:_
5053
ln -s /usr/gnu/H-HOST-2 /usr/gnu
5054
5055
To the end user, then, placing `/usr/gnu/bin' in her or his `PATH'
5056
simply works transparently for each HOST type.
5057
5058
You can change EXEC-PREFIX on the command line to `configure' using
5059
5060
configure --exec-prefix=EXEC-PREFIX ...
5061
5062
We recommend that you consult *Note Using `configure':
5063
(configure)Using configure, before attempting this.
5064
5065
5066
File: gnats.info, Node: gnats-adm, Next: defaults, Prev: exec-prefix, Up: Locations
5067
5068
A.3 The `gnats-adm' directory
5069
=============================
5070
5071
Each GNATS database located on a server has its own directory, as
5072
listed in the `databases' (*note The `databases' file: databases file.
5073
and given when the `mkdb' utility is invoked to initialize the database
5074
(*note Initializing a new database: mkdb.). This directory has several
5075
subdirectories, one of which is named `gnats-adm'. This directory
5076
contains all configuration files related to this specific database,
5077
including the `categories', `submitters', `responsible', `states',
5078
`classes', `dbconfig', `addresses', `states' and `gnatsd.user_access',
5079
as well as two files generated and maintained by GNATS, `index' and
5080
`current'.
5081
5082
5083
File: gnats.info, Node: defaults, Prev: gnats-adm, Up: Locations
5084
5085
A.4 Default installation locations
5086
==================================
5087
5088
PREFIX
5089
defaults to `/usr/local'; change using `configure' (*note
5090
Configuring and compiling the software: Configure and make.).
5091
5092
EXEC-PREFIX
5093
defaults to PREFIX; change using `configure' (*note Configuring
5094
and compiling the software: Configure and make.).
5095
5096
GNATS installs tools, utilities, and files into the following locations.
5097
5098
`EXEC-PREFIX/bin'
5099
5100
`send-pr'
5101
*Note Submitting Problem Reports: send-pr.
5102
5103
`edit-pr'
5104
*Note Editing existing Problem Reports: edit-pr.
5105
5106
`query-pr'
5107
*Note Querying the database: query-pr.
5108
5109
`EXEC-PREFIX/libexec/gnats'
5110
5111
`at-pr'
5112
*Note Timely reminders: at-pr.
5113
5114
`check-db'
5115
*Note Checking database health: check-db.
5116
5117
`delete-pr'
5118
Tool for deleting PRs. Deprecated. Use the -delete-pr
5119
option of `pr-edit' instead (*note The edit-pr driver:
5120
pr-edit.).
5121
5122
`diff-prs'
5123
*Note The `diff-prs' tool: diff-prs.
5124
5125
`file-pr'
5126
*Note Interface to pr-edit for filing new PRs: file-pr.
5127
5128
`gen-index'
5129
*Note Regenerating the index: gen-index.
5130
5131
`gnatsd'
5132
The GNATS daemon.
5133
5134
`gnats-pwconv'
5135
*Note Converting old password files: gnats-pwconv.
5136
5137
`mail-query'
5138
*Note Setting up mail aliases: Aliases.
5139
5140
`mkcat'
5141
*Note Adding a problem category: mkcat.
5142
5143
`mkdb'
5144
*Note Script for creating new databases: mkdb.
5145
5146
`pr-age'
5147
*Note The `pr-age' tool: pr-age.
5148
5149
`pr-edit'
5150
*Note The main PR processor: pr-edit.
5151
5152
`queue-pr'
5153
*Note Handling incoming traffic: queue-pr.
5154
5155
`rmcat'
5156
*Note Removing categories: rmcat.
5157
5158
`EXEC-PREFIX/lib/libiberty.a'
5159
The GNU `libiberty' library.
5160
5161
`PREFIX/etc/gnats'
5162
5163
`databases'
5164
*Note The `databases' file: databases file.
5165
5166
`defaults'
5167
*Note Overview of GNATS configuration: GNATS configuration.
5168
5169
`gnatsd.host_access'
5170
*Note The `gnatsd.host_access' file: gnatsd.host_access.
5171
5172
`gnatsd.user_access'
5173
*Note The `gnatsd.user_access' file: gnatsd.user_access.
5174
5175
`PREFIX/share/emacs/site-lisp'
5176
5177
`gnats.el'
5178
`gnats.elc'
5179
The Emacs versions of the programs `send-pr', `query-pr',
5180
`edit-pr', and `view-pr'. *Note The GNATS user tools: GNATS
5181
user tools. To change this directory you must change the
5182
`lispdir' variable in `Makefile.in'; see *Note Configuring
5183
and compiling the software: Configure and make.
5184
5185
`PREFIX/info'
5186
5187
`gnats.info'
5188
`send-pr.info'
5189
The GNATS manuals, in a form readable by `info' (the GNU
5190
hypertext browser). *Note Reading GNU Online Documentation:
5191
(infoman)Info.
5192
5193
`PREFIX/man/man1'
5194
`PREFIX/man/man8'
5195
5196
`man' pages for all the GNATS tools and utilities.
5197
*Note The GNATS user tools: GNATS user tools.
5198
5199
`Per-database directory'
5200
5201
`gnats-adm'
5202
Administration and configuration data files that define
5203
behaviour of the particular database. The files
5204
5205
`categories'
5206
5207
`submitters'
5208
5209
`responsible'
5210
5211
`states'
5212
5213
`classes'
5214
5215
`dbconfig'
5216
5217
`addresses'
5218
5219
`states'
5220
5221
`gnatsd.user_access'
5222
5223
`index'
5224
(_This file is created by GNATS._)
5225
5226
`current'
5227
(_This file is created by GNATS._)
5228
5229
exist here. *Note Other database-specific config files:
5230
Other config files, *Note Administrative data files: Admin
5231
files. and *Note Controlling access to databases: Access
5232
Control.
5233
5234
`gnats-queue'
5235
Incoming Problem Reports are queued here until the next
5236
iteration of `queue-pr -r' (*note Handling incoming traffic:
5237
queue-pr.).
5238
5239
`pending'
5240
If no default category is set, problem reports without a
5241
category are reassigned to the category `pending' and placed
5242
here pending intervention by GNATS administrators. *Note
5243
GNATS administration: Management.
5244
5245
`CATEGORY'
5246
Each valid category has a corresponding subdirectory in the
5247
database. All Problem Reports associated with that category
5248
are kept in that subdirectory.
5249
5250
5251
5252
File: gnats.info, Node: gnatsd, Next: Access Control, Prev: Locations, Up: Top
5253
5254
Appendix B The GNATS network server - `gnatsd'
5255
**********************************************
5256
5257
This section describes in details how the GNATS network daemon works.
5258
This information is mainly assumed to be useful for developers of GNATS
5259
client software.
5260
5261
* Menu:
5262
5263
* Description of gnatsd::
5264
* gnatsd options::
5265
* gnatsd command protocol::
5266
* gnatsd commands::
5267
* gnatsd environment variables::
5268
5269
5270
File: gnats.info, Node: Description of gnatsd, Next: gnatsd options, Up: gnatsd
5271
5272
B.1 Description of `gnatsd'
5273
===========================
5274
5275
The `gnatsd' network daemon is used to service remote GNATS requests
5276
such as querying PRs, PR creation, deletion, and editing, and
5277
miscellaneous database queries. It uses a simple ASCII-based command
5278
protocol (similar to SMTP or POP3) for communicating with remote
5279
clients.
5280
5281
It also provides a security model based either on IP-based
5282
authentication (generally considered very weak) or username/passwords,
5283
where passwords may be in cleartext, UNIX crypt or MD5 hash format.
5284
Access through `gnatsd' is granted according to certain predefined
5285
"access levels". Access levels are further discussed in *Note
5286
Controlling access to databases: Access Control. It should be
5287
emphasized that security has not been a focus of development until now,
5288
but future versions are expected to address this more thoroughly.
5289
5290
All of the GNATS clients are capable of communicating via the GNATS
5291
remote protocol to perform their functions.
5292
5293
`gnatsd' is usually started from the inetd facility and should run as
5294
the `gnats' user (the actual username of this user is configurable
5295
during installation, *note Configuring and compiling the software:
5296
Configure and make. for details.)
5297
5298
5299
File: gnats.info, Node: gnatsd options, Next: gnatsd command protocol, Prev: Description of gnatsd, Up: gnatsd
5300
5301
B.2 `gnatsd' options
5302
====================
5303
5304
The daemon supports the following command-line options:
5305
5306
gnatsd [--database database | -d database]
5307
[--not-inetd | -n] [--max-access-level LEVEL | -m LEVEL]
5308
[--version | -V] [--help | -h]
5309
5310
`-V, --version'
5311
Prints the program version to stdout and exits.
5312
5313
`-h, --help'
5314
Prints a short help text to stdout and exits.
5315
5316
`-d, --database'
5317
Specifies the default database which is to be serviced by this
5318
invocation of `gnatsd'. (The selected database may be changed via
5319
the `CHDB' command; the name set with this option is simply the
5320
default if no `CHDB' command is issued.) If no database is
5321
specified, the database named default is assumed. This option
5322
overrides the database specified in the `GNATSDB' environment
5323
variable.
5324
5325
`-n, --not-inetd'
5326
As its name suggests, indicates that `gnatsd' is not being invoked
5327
from inetd. This can be used when testing `gnatsd', or if it is
5328
being run via ssh or some other mechanism.
5329
5330
This has the effect of using the local hostname where `gnatsd' is
5331
being invoked for authentication purposes, rather than the remote
5332
address of the connecting client.
5333
5334
`--max-access-level, -m'
5335
Specifies the maximum access level that the connecting client can
5336
authenticate to. Authentication is as normal but if the user or
5337
host authenticates at a higher level, access level is still forced
5338
to this level. See *Note Controlling access to databases: Access
5339
Control. for details on access levels.
5340
5341
5342
File: gnats.info, Node: gnatsd command protocol, Next: gnatsd commands, Prev: gnatsd options, Up: gnatsd
5343
5344
B.3 `gnatsd' command protocol
5345
=============================
5346
5347
Commands are issued to `gnatsd' as one or more words followed by a
5348
carriage-return/linefeed pair. For example, the `CHDB' (change
5349
database) command is sent as `CHDB database<CR><LF>' (the `CRLF' will
5350
not be explicitly written for future examples.)
5351
5352
Replies from `gnatsd' are returned as one or more response lines
5353
containing a 3-digit numeric code followed by a human-readable string;
5354
the line is terminated with a `<CR><LF>' pair. For example, one
5355
possible response to the `CHDB' command above would be:
5356
5357
210 Now accessing GNATS database 'database'.
5358
5359
The three-digit code is normally followed by a single ASCII space
5360
(character 0x20). However, if additional response lines are to be
5361
returned from the server, there will be a single dash `-' instead of
5362
the space character after the three-digit code.
5363
5364
Response code values are divided into ranges. The first digit
5365
reflects the general type of response (such as "successful" or
5366
"error"), and the subsequent digits identify the specific type of
5367
response.
5368
5369
CODES 200-299
5370
Positive response indicating that the command was successful. No
5371
subsequent data will be transmitted with the response. In
5372
particular, code 210 (`CODE_OK') is used as the positive result
5373
code for most simple commands.
5374
5375
Commands that expect additional data from the client (such as
5376
`SUBM' or `VFLD') use a two-step mechanism for sending the data.
5377
The server will respond to the initial command with either a 211
5378
(`CODE_SEND_PR') or 212 (`CODE_SEND_TEXT') response line, or an
5379
error code if an error occurred with the initial command. The
5380
client is then expected to send the remaining data using the same
5381
quoting mechanism as described for server responses in the 300-349
5382
range. The server will then send a final response line to the
5383
command.
5384
5385
CODES 300-399
5386
Positive response indicating that the query request was
5387
successful, and that a PR or other data will follow. Codes
5388
300-349 are used when transmitting PRs, and 350-399 are used for
5389
other responses.
5390
5391
Codes in the 300-349 range are followed by a series of
5392
`CRLF'-terminated lines containing the command response, usually a
5393
PR. The final line of the result is a single period `.'. Result
5394
lines that begin with a period have an extra period prepended to
5395
them.
5396
5397
Codes in the 350-399 range use a different scheme for sending their
5398
responses. The three-digit numeric code will be followed by either
5399
a dash `-' or a single space. If the code is followed by a dash,
5400
that indicates that another response line will follow. The final
5401
line of the response has a single space after the three-digit code.
5402
5403
In previous versions of the protocol the first line of a
5404
`CODE_INFORMATION' (310) response was to be ignored. This is no
5405
longer the case. Instead, any lines marked with code
5406
`CODE_INFORMATION_FILLER' (351) are to be ignored. This allows the
5407
server to transmit additional headers or other human-readable text
5408
that can be safely ignored by the clients.
5409
5410
CODES 400-599
5411
An error occurred, usually because of invalid command parameters or
5412
invalid input from the client, missing arguments to the command,
5413
or a command was issued out of sequence. The human-readable
5414
message associated with the response line describes the general
5415
problem encountered with the command.
5416
5417
Multiple error messages may be returned from a command; in this
5418
case the `-' continuation character is used on all but the last
5419
response line.
5420
5421
CODES 600-799
5422
An internal error occurred on the server, a timeout occurred
5423
reading data from the client, or a network failure occurred.
5424
These errors are of the "this should not occur" nature, and
5425
retrying the operation may resolve the problem. Fortunately, most
5426
GNATS transactions are idempotent; unfortunately, locking the
5427
database or a PR are not repeatable actions (we cannot determine
5428
if an existing lock is the one we originally requested, or someone
5429
else's).
5430
5431
5432
File: gnats.info, Node: gnatsd commands, Next: gnatsd environment variables, Prev: gnatsd command protocol, Up: gnatsd
5433
5434
B.4 `gnatsd' commands
5435
=====================
5436
5437
Note that the set of GNATS commands and their responses is somewhat
5438
inconsistent and is very much in flux. At present the GNATS clients
5439
are rather simple-minded and not very strict about processing
5440
responses. For example, if the server were to issue a code 300
5441
(`CODE_PR_READY') response to a `CHDB' command, the client would
5442
happily expect to see a PR appear (and would print it out if one was
5443
sent).
5444
5445
It is thus suggested that any clients that use the GNATS protocol be
5446
equally flexible about the way received responses are handled; in
5447
particular, only the first digit of the response code should be assumed
5448
to be meaningful, although subsequent digits are needed in some cases
5449
(codes 300-399). No attempt should be made to parse the message strings
5450
on error response lines; they are only intended to be read by humans,
5451
and will be changed on a regular basis.
5452
5453
Almost every command may result in the response 440
5454
(`CODE_CMD_ERROR'). This indicates that there was a problem with the
5455
command arguments, usually because of insufficient or too many
5456
arguments being specified.
5457
5458
Access to most `gnatsd' commands requires a certain "access level".
5459
For details of this, see *Note Privileged `gnatsd' commands: Privileged
5460
gnatsd commands.
5461
5462
`USER [USERID PASSWORD]'
5463
Specifies the userid and password for database access. Either
5464
both a username and password must be specified, or they both may
5465
be omitted; in the latter case, the current access level is
5466
returned.
5467
5468
The possible server responses are:
5469
5470
`350 (CODE_INFORMATION)'
5471
The current access level is specified.
5472
5473
`422 (CODE_NO_ACCESS)'
5474
A matching username and password could not be found.
5475
5476
`200 (CODE_OK)'
5477
A matching username and password was found, and the login was
5478
successful.
5479
5480
`QUIT'
5481
Requests that the connection be closed. Possible responses:
5482
5483
`201 (CODE_CLOSING)'
5484
Normal exit.
5485
5486
The `QUIT' command has the dubious distinction of being the only
5487
command that cannot fail.
5488
5489
`LIST LIST TYPE'
5490
Describes various aspects of the database. The lists are returned
5491
as a list of records, one per line. Each line may contain a
5492
number of colon-separated fields.
5493
5494
Possible values for LIST TYPE include
5495
5496
`Categories'
5497
Describes the legal categories for the database.
5498
5499
`Submitters'
5500
Describes the set of submitters for the database.
5501
5502
`Responsible'
5503
Lists the names in the responsible administrative file, including
5504
their full names and email addresses.
5505
5506
`States'
5507
Lists the states listed in the state administrative file, including
5508
the state type (usually blank for most states; the closed state
5509
has a special type).
5510
5511
`FieldNames'
5512
Lists the entire set of PR fields.
5513
5514
`InitialInputFields'
5515
Lists the fields that _should_ be present when a PR is initially
5516
entered.
5517
5518
`InitialRequiredFields'
5519
Lists fields that _have_ to be present and nonempty when a PR is
5520
initially entered (fields containing only blank characters such as
5521
spaces or newlines are considered empty.)
5522
5523
`Databases'
5524
Lists the set of databases.
5525
5526
The possible responses are:
5527
5528
`301 (CODE_TEXT_READY)'
5529
Normal response, followed by the records making up the list as
5530
described above.
5531
5532
`416 (CODE_INVALID_LIST)'
5533
The requested list does not exist.
5534
5535
`FTYP FIELD [FIELD ...]'
5536
Describes the type of data held in the field(s) specified with the
5537
command. The currently defined data types are:
5538
5539
`Text'
5540
A plain text field, containing exactly one line.
5541
5542
`MultiText'
5543
A text field possibly containing multiple lines of text.
5544
5545
`Enum'
5546
An enumerated data field; the value is restricted to one entry out
5547
of a list of values associated with the field.
5548
5549
`MultiEnum'
5550
The field contains one or more enumerated values. Values are
5551
separated with spaces or colons `:'.
5552
5553
`Integer'
5554
The field contains an integer value, possibly signed.
5555
5556
`Date'
5557
The field contains a date.
5558
5559
`TextWithRegex'
5560
The value in the field must match one or more regular expressions
5561
associated with the field.
5562
5563
The possible responses are:
5564
5565
`350 (CODE_INFORMATION)'
5566
The normal response; the supplied text is the data type.
5567
5568
`410 (CODE_INVALID_FIELD_NAME)'
5569
The specified field does not exist.
5570
5571
If multiple field names were given, multiple response lines will be
5572
sent, one for each field, using the standard continuation
5573
protocol; each response except the last will have a dash `-'
5574
immedately after the response code.
5575
5576
`FTYPINFO FIELD PROPERTY'
5577
Provides field-type-related information. Currently, only the
5578
property `separators' for MultiEnum fields is supported. When
5579
`separators' is specified, the possible return codes are:
5580
5581
`350 (CODE_INFORMATION)' A proper MultiEnum FIELD was specified
5582
and the returned text is the string of separators specified for
5583
the field in the dbconfig file (*note Field datatypes::) quoted in
5584
`'''s.
5585
5586
`435 (CODE_INVALID_FTYPE_PROPERTY)' The `separators' property is
5587
not defined for this field, i.e. the specified FIELD is not of
5588
type MultiEnum.
5589
5590
Currently, specifying a different property than `separators'
5591
results in return code 435 as above.
5592
5593
`FDSC FIELD [FIELD ... ]'
5594
Returns a human-readable description of the listed field(s). The
5595
possible responses are:
5596
5597
`350 (CODE_INFORMATION)' The normal response; the supplied text is
5598
the field description.
5599
5600
`410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.
5601
5602
Like the `FVLD' command, the standard continuation protocol will be
5603
used if multiple fields were specified with the command.
5604
5605
`FIELDFLAGS FIELD [FIELD ... ]'
5606
Returns a set of flags describing the specified field(s). The
5607
possible responses are either
5608
5609
`410 (CODE_INVALID_FIELD_NAME)'
5610
meaning that the specified field is invalid or nonexistent, or
5611
5612
`350 (CODE_INFORMATION)'
5613
which contains the set of flags for the field. The flags may be
5614
blank, which indicate that no special flags have been set for this
5615
field.
5616
5617
Like the `FDSC' and `FTYP' commands, multiple field names may be
5618
listed with the command, and a response line will be returned for
5619
each one in the order that the fields appear on the command line.
5620
5621
The flags include:
5622
5623
`textsearch'
5624
The field will be searched when a text field search is requested.
5625
5626
`allowAnyValue'
5627
For fields that contain enumerated values, any legal value may be
5628
used in the field, not just ones that appear in the enumerated
5629
list.
5630
5631
`requireChangeReason'
5632
If the field is edited, a reason for the change must be supplied in
5633
the new PR text describing the reason for the change. The reason
5634
must be supplied as a multitext PR field in the new PR whose name
5635
is `field-Changed-Why' (where `field' is the name of the field
5636
being edited).
5637
5638
`readonly'
5639
The field is read-only, and cannot be edited.
5640
5641
`FVLD FIELD'
5642
Returns one or more regular expressions or strings that describe
5643
the valid types of data that can be placed in field. Exactly what
5644
is returned is dependent on the type of data that can be stored in
5645
the field. For most fields a regular expression is returned; for
5646
enumerated fields, the returned values are the list of legal
5647
strings that can be held in the field.
5648
5649
The possible responses are:
5650
5651
`301 (CODE_TEXT_READY)'
5652
The normal response, which is followed by the list of regexps or
5653
strings.
5654
5655
`410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.
5656
5657
`VFLD FIELD'
5658
`VFLD' can be used to validate a given value for a field in the
5659
database. The client issues the `VFLD' command with the name of
5660
the field to validate as an argument. The server will either
5661
respond with `212 (CODE_SEND_TEXT)', or `410
5662
(CODE_INVALID_FIELD_NAME)' if the specified field does not exist.
5663
5664
Once the `212' response is received from the server, the client
5665
should then send the line(s) of text to be validated, using the
5666
normal quoting mechanism described for PRs. The final line of
5667
text is followed by a line containing a single period, again as
5668
when sending PR text.
5669
5670
The server will then either respond with `210 (CODE_OK)',
5671
indicating that the text is acceptable, or one or more error codes
5672
describing the problems with the field contents.
5673
5674
`INPUTDEFAULT FIELD [FIELD ... ]'
5675
Returns the suggested default value for a field when a PR is
5676
initially created. The possible responses are either `410
5677
(CODE_INVALID_FIELD_NAME)', meaning that the specified field is
5678
invalid or nonexistent, or `350 (CODE_INFORMATION)' which contains
5679
the default value for the field.
5680
5681
Like the `FDSC' and `FTYP' commands, multiple field names may be
5682
listed with the command, and a response line will be returned for
5683
each one in the order that the fields appear on the command line.
5684
5685
`RSET'
5686
Used to reset the internal server state. The current query
5687
expression is cleared, and the index of PRs may be reread if it
5688
has been updated since the start of the session. The possible
5689
responses are:
5690
5691
`200 (CODE_OK)'
5692
The state has been reset.
5693
5694
`440 (CODE_CMD_ERROR)'
5695
One or more arguments were supplied to the command.
5696
5697
`6xx (internal error)'
5698
There were problems resetting the state (usually because the index
5699
could not be reread). The session will be immediately terminated.
5700
5701
`LKDB'
5702
Locks the main GNATS database. No subsequent database locks will
5703
succeed until the lock is removed. Sessions that attempt to write
5704
to the database will fail. The possible responses are:
5705
5706
`200 (CODE_OK)' The lock has been established.
5707
5708
`440 (CODE_CMD_ERROR)' One or more arguments were supplied to the
5709
command.
5710
5711
`431 (CODE_GNATS_LOCKED)' The database is already locked, and the
5712
lock could not be obtained after 10 seconds.
5713
5714
`6xx (internal error)' An internal error occurred, usually because
5715
of permission or other filesystem-related problems. The lock may
5716
or may not have been established.
5717
5718
`UNDB'
5719
Unlocks the database. Any session may steal a database lock; no
5720
checking of any sort is done. The possible responses are:
5721
5722
`200 (CODE_OK)'
5723
The lock has been removed.
5724
5725
`432 (CODE_GNATS_NOT_LOCKED)'
5726
The database was not locked.
5727
5728
`440 (CODE_CMD_ERROR)'
5729
One or more arguments were supplied to the command.
5730
5731
`6xx (internal error)'
5732
The database lock could not be removed, usually because of
5733
permissions or other filesystem-related issues.
5734
5735
`LOCK PR USER [PID]'
5736
Locks the specified PR, marking the lock with the USER name and
5737
the optional PID. (No checking is done that the USER or PID
5738
arguments are valid or meaningful; they are simply treated as
5739
strings.)
5740
5741
The `EDIT' command requires that the PR be locked before it may be
5742
successfully executed. However, it does not require that the lock
5743
is owned by the editing session, so the usefulness of the lock is
5744
simply as an advisory measure.
5745
5746
The `APPN' and `REPL' commands lock the PR as part of the editing
5747
process, and they do not require that the PR be locked before they
5748
are invoked.
5749
5750
The possible responses are:
5751
5752
`440 (CODE_CMD_ERROR)'
5753
Insufficient or too many arguments were specified to the command.
5754
5755
`300 (CODE_PR_READY)'
5756
The lock was successfully obtained; the text of the PR (using the
5757
standard quoting mechanism for PRs) follows.
5758
5759
`400 (CODE_NONEXISTENT_PR)'
5760
The PR specified does not exist.
5761
5762
`430 (CODE_LOCKED_PR)'
5763
The PR is already locked by another session.
5764
5765
`6xx (internal error)'
5766
The PR lock could not be created, usually because of permissions or
5767
other filesystem-related issues.
5768
5769
`UNLK PR'
5770
Unlocks PR. Any user may unlock a PR, as no checking is done to
5771
determine if the requesting session owns the lock.
5772
5773
The possible responses are:
5774
5775
`440 (CODE_CMD_ERROR)'
5776
Insufficient or too many arguments were specified to the command.
5777
5778
`200 (CODE_OK)'
5779
The PR was successfully unlocked.
5780
5781
`433 (CODE_PR_NOT_LOCKED)'
5782
The PR was not locked.
5783
5784
`6xx (internal error)'
5785
The PR could not be unlocked, usually because of permission or
5786
other filesystem-related problems.
5787
5788
`DELETE PR'
5789
Deletes the specified PR. The user making the request must have
5790
admin privileges (*note Controlling access to databases: Access
5791
Control.). If successful, the PR is removed from the filesystem
5792
and the index file; a gap will be left in the numbering sequence
5793
for PRs. No checks are made that the PR is closed.
5794
5795
The possible responses are:
5796
5797
`200 (CODE_OK)'
5798
The PR was successfully deleted.
5799
5800
`422 (CODE_NO_ACCESS)'
5801
The user requesting the delete does not have admin privileges.
5802
5803
`430 (CODE_LOCKED_PR)'
5804
The PR is locked by another session.
5805
5806
`431 (CODE_GNATS_LOCKED)'
5807
The database has been locked, and no PRs may be updated until the
5808
lock is cleared.
5809
5810
`6xx (internal error)'
5811
The PR could not be successfully deleted, usually because of
5812
permission or other filesystem-related problems.
5813
5814
`CHEK [initial]'
5815
Used to check the text of an entire PR for errors. Unlike the
5816
`VFLD' command, it accepts an entire PR at once instead of the
5817
contents of an individual field.
5818
5819
The `initial' argument indicates that the PR text to be checked is
5820
for a PR that will be newly created, rather than an edit or
5821
replacement of an existing PR.
5822
5823
After the `CHEK' command is issued, the server will respond with
5824
either a `440 (CODE_CMD_ERROR)' response indicating that the
5825
command arguments were incorrect, or a `211 (CODE_SEND_PR)'
5826
response code will be sent.
5827
5828
Once the `211' response is received from the server, the client
5829
should send the PR using the normal PR quoting mechanism; the
5830
final line of the PR is then followed by a line containing a
5831
single period, as usual.
5832
5833
The server will then respond with either a `200 (CODE_OK)'
5834
response, indicating there were no problems with the supplied
5835
text, or one or more error codes listing the problems with the PR.
5836
5837
`EDIT PR'
5838
Verifies the replacement text for PR. If the command is
5839
successful, the contents of PR are completely replaced with the
5840
supplied text. The PR must previously have been locked with the
5841
`LOCK' command.
5842
5843
The possible responses are:
5844
5845
`431 (CODE_GNATS_LOCKED)'
5846
The database has been locked, and no PRs may be updated until the
5847
lock is cleared.
5848
5849
`433 (CODE_PR_NOT_LOCKED)'
5850
The PR was not previously locked with the `LOCK' command.
5851
5852
`400 (CODE_NONEXISTENT_PR)'
5853
The specified PR does not currently exist. The `SUBM' command
5854
should be used to create new PRs.
5855
5856
`211 (CODE_SEND_PR)'
5857
The client should now transmit the replacement PR text using the
5858
normal PR quoting mechanism. After the PR has been sent, the
5859
server will respond with either `200 (CODE_OK)' indicating that
5860
the edit was successful, or one or more error codes listing
5861
problems either with the replacement PR text or errors encountered
5862
while updating the PR file or index.
5863
5864
`EDITADDR ADDRESS'
5865
Sets the e-mail address of the person communicating with `gnatsd'.
5866
The command requires at least the `edit' access level.
5867
5868
The possible responses are:
5869
5870
`200 (CODE_OK)'
5871
The address was successfully set.
5872
5873
`440 (CODE_CMD_ERROR)'
5874
Invalid number of arguments were supplied.
5875
5876
`APPN PR FIELD'
5877
`REPL PR FIELD'
5878
Appends to or replaces the contents of FIELD in PR with the
5879
supplied text. The command returns a `201 (CODE_SEND_TEXT)'
5880
response; the client should then transmit the new field contents
5881
using the standard PR quoting mechanism. After the server has
5882
read the new contents, it then attempts to make the requested
5883
change to the PR.
5884
5885
The possible responses are:
5886
5887
`200 (CODE_OK)'
5888
The PR field was successfully changed.
5889
5890
`400 (CODE_NONEXISTENT_PR)'
5891
The PR specified does not exist.
5892
5893
`410 (CODE_INVALID_FIELD_NAME)'
5894
The specified field does not exist.
5895
5896
`402 (CODE_UNREADABLE_PR)'
5897
The PR could not be read.
5898
5899
`431 (CODE_GNATS_LOCKED)'
5900
The database has been locked, and no PRs may be updated until the
5901
lock is cleared.
5902
5903
`430 (CODE_LOCKED_PR)'
5904
The PR is locked, and may not be altered until the lock is cleared.
5905
5906
`413 (CODE_INVALID_FIELD_CONTENTS)'
5907
The supplied (or resulting) field contents are not valid for the
5908
field.
5909
5910
`6xx (internal error)'
5911
An internal error occurred, usually because of permission or other
5912
filesystem-related problems. The PR may or may not have been
5913
altered.
5914
5915
`SUBM'
5916
Submits a new PR into the database. The supplied text is verified
5917
for correctness, and if no problems are found a new PR is created.
5918
5919
The possible responses are:
5920
5921
`431 (CODE_GNATS_LOCKED)'
5922
The database has been locked, and no PRs may be submitted until the
5923
lock is cleared.
5924
5925
`211 (CODE_SEND_PR)'
5926
The client should now transmit the new PR text using the normal
5927
quoting mechanism. After the PR has been sent, the server will
5928
respond with either `351 (CODE_INFORMATION_FILLER)' and `350
5929
(CODE_INFORMATION)' responses indicating that the new PR has been
5930
created and supplying the number assigned to it, or one or more
5931
error codes listing problems with the new PR text.
5932
5933
`CHDB DATABASE'
5934
Switches the current database to the name specified in the command.
5935
5936
The possible responses are:
5937
5938
`422 (CODE_NO_ACCESS)'
5939
The user does not have permission to access the requested database.
5940
5941
`417 (CODE_INVALID_DATABASE)'
5942
The database specified does not exist, or one or more configuration
5943
errors in the database were encountered.
5944
5945
`220 (CODE_OK)'
5946
The current database is now DATABASE. Any operations performed
5947
will now be applied to DATABASE.
5948
5949
`DBLS'
5950
Lists the known set of databases.
5951
5952
The possible responses are:
5953
5954
`6xx (internal error)'
5955
An internal error was encountered while trying to obtain the list
5956
of available databases, usually due to lack of permissions or other
5957
filesystem-related problems, or the list of databases is empty.
5958
5959
`301 (CODE_TEXT_READY)'
5960
The list of databases follows, one per line, using the standard
5961
quoting mechanism. Only the database names are sent.
5962
5963
The `gnatsd' access level `listdb' denies access until the user
5964
has authenticated with the USER command. The only other command
5965
available at this access level is `DBLS'. This access level
5966
provides a way for a site to secure its GNATS databases while still
5967
providing a way for client tools to obtain a list of the databases
5968
for use on login screens etc. *Note Controlling access to
5969
databases: Access Control.
5970
5971
`DBDESC DATABASE'
5972
Returns a human-readable description of the specified DATABASE.
5973
5974
Responses include:
5975
5976
`6xx (internal error)'
5977
An internal error was encountered while trying to read the list of
5978
available databases, usually due to lack of permissions or other
5979
filesystem-related problems, or the list of databases is empty.
5980
5981
`350 (CODE_INFORMATION)'
5982
The normal response; the supplied text is the database description.
5983
5984
`417 (CODE_INVALID_DATABASE)'
5985
The specified database name does not have an entry.
5986
5987
`EXPR QUERY EXPRESSION'
5988
Specifies a QUERY EXPRESSION used to limit which PRs are returned
5989
from the `QUER' command. The expression uses the normal query
5990
expression syntax, (*note Query expressions::).
5991
5992
Multiple `EXPR' commands may be issued; the expressions are boolean
5993
ANDed together.
5994
5995
Expressions are cleared by the `RSET' command.
5996
5997
Possible responses include:
5998
5999
`415 (CODE_INVALID_EXPR)'
6000
The specified expression is invalid, and could not be parsed.
6001
6002
`200 (CODE_OK)'
6003
The expression has been accepted and will be used to limit the
6004
results returned from `QUER'.
6005
6006
`QFMT QUERY FORMAT'
6007
Use the specified QUERY FORMAT to format the output of the `QUER'
6008
command. The query format may be either the name of a query
6009
format known to the server (*note Named query definitions::), or an
6010
actual query format (*note Formatting query-pr output::). The
6011
possible responses are:
6012
6013
`200 (CODE_OK)'
6014
The normal response, which indicates that the query format is
6015
acceptable.
6016
6017
`440 (CODE_CMD_ERROR)'
6018
No query format was supplied.
6019
6020
`418 (CODE_INVALID_QUERY_FORMAT)'
6021
The specified query format does not exist, or could not be parsed.
6022
6023
`QUER [PR] [PR] [...]'
6024
Searches the contents of the database for PRs that match the
6025
(optional) specified expressions with the `EXPR' command. If no
6026
expressions were specified with `EXPR', the entire set of PRs is
6027
returned.
6028
6029
If one or more PRs are specified on the command line, only those
6030
PRs will be searched and/or output.
6031
6032
The format of the output from the command is determined by the
6033
query format selected with the `QFMT' command.
6034
6035
The possible responses are:
6036
6037
`418 (CODE_INVALID_QUERY_FORMAT)'
6038
A valid format was not specified with the `QFMT' command prior to
6039
invoking `QUER'.
6040
6041
`300 (CODE_PR_READY)'
6042
One or more PRs will be output using the requested query format.
6043
The PR text is quoted using the normal quoting mechanisms for PRs.
6044
6045
`220 (CODE_NO_PRS_MATCHED)'
6046
No PRs met the specified criteria.
6047
6048
`ADMV FIELD KEY [SUBFIELD]'
6049
Returns an entry from an administrative data file associated with
6050
FIELD. KEY is used to look up the entry in the data file. If
6051
SUBFIELD is specified, only the value of that subfield is
6052
returned; otherwise, all of the fields in the adm data file are
6053
returned, separated by colons `:'.
6054
6055
The responses are:
6056
6057
`410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.
6058
6059
`221 (CODE_NO_ADM_ENTRY)' An adm entry matching the key was not
6060
found, or the field does not have an adm file associated with it.
6061
6062
`350 (CODE_INFORMATION)' The normal response; the supplied text is
6063
the requested field(s).
6064
6065
6066
File: gnats.info, Node: gnatsd environment variables, Prev: gnatsd commands, Up: gnatsd
6067
6068
B.5 `gnatsd' environment variables
6069
==================================
6070
6071
`gnatsd' supports the `GNATSDB' environment varable, *Note
6072
Environment::, in almost the same way as the GNATS tools do. This
6073
variable is used to determine which database to use. For a local
6074
database, it contains the name of the database to access. `gnatsd'
6075
cannot service remote databases (though it might be interesting if it
6076
could) so the database is always assumed to be local.
6077
6078
If `GNATSDB' is not set and the `--database' option is not supplied,
6079
it is assumed that the database is local and that its name is `default'.
6080
6081
6082
File: gnats.info, Node: Access Control, Next: Regexps, Prev: gnatsd, Up: Top
6083
6084
Appendix C Controlling access to databases
6085
******************************************
6086
6087
* Menu:
6088
6089
* Overview::
6090
* Overall gnatsd access level::
6091
* gnatsd.host_access:: Per-host access settings
6092
* gnatsd.user_access:: Access levels per user
6093
* Privileged gnatsd commands::
6094
6095
6096
File: gnats.info, Node: Overview, Next: Overall gnatsd access level, Up: Access Control
6097
6098
C.1 Overview
6099
============
6100
6101
GNATS supports granting various levels of access to the GNATS databases
6102
served by the network daemon, `gnatsd'.
6103
6104
GNATS access can be controlled at these levels:
6105
6106
`deny'
6107
gnatsd closes the connection
6108
6109
`none'
6110
no further access until userid and password given
6111
6112
`listdb'
6113
only listing of available databases is allowed
6114
6115
`view'
6116
query and view PRs with Confidential=no only
6117
6118
`viewconf'
6119
query and view PRs with Confidential=yes
6120
6121
`edit'
6122
full edit access
6123
6124
`admin'
6125
full admin access
6126
6127
These access levels are used in the following settings:
6128
6129
* overall gnatsd access level
6130
6131
* overall access level set by host name or IP address
6132
6133
* overall access level set by userid and password
6134
6135
* per-database access level set by userid and password
6136
6137
6138
File: gnats.info, Node: Overall gnatsd access level, Next: gnatsd.host_access, Prev: Overview, Up: Access Control
6139
6140
C.2 Overall `gnatsd' access level
6141
=================================
6142
6143
The overall `gnatsd' access level is set by starting `gnatsd' with the
6144
option
6145
6146
`-m' LEVEL or `--maximum-access-level'=LEVEL,
6147
6148
where LEVEL is one of the six access levels listed above. This
6149
restricts any access to the GNATS daemon to levels up to and including
6150
LEVEL, regardless of the settings in the access control files discussed
6151
below. If this option is left out, any access levels set in the access
6152
control files will be allowed.
6153
6154
The discussion below assumes that the pre-build configure of GNATS
6155
was done without altering the default values for the
6156
`--with-gnatsd-user-access-file' and `--with-gnatsd-host-access-file'
6157
options. If non-default values were given, substitute as appropriate
6158
below.
6159
6160
6161
File: gnats.info, Node: gnatsd.host_access, Next: gnatsd.user_access, Prev: Overall gnatsd access level, Up: Access Control
6162
6163
C.3 Overall access levels per host
6164
==================================
6165
6166
The host access file (by default
6167
`/usr/local/etc/gnats/gnatsd.host_access') controls overall access
6168
levels on a per-host basis, meaning that settings in this file apply
6169
across all databases on the server. Entries in this file are in the
6170
following format:
6171
6172
HOST:ACCESS-LEVEL:WHATEVER
6173
6174
HOST is the hostname or IP address of the host contacting gnatsd.
6175
Wildcard characters are supported: `*' matches anything; `?' matches
6176
any single character. By using wildcards, you can specify access
6177
levels for entire network subnets and domains. Note that when GNATS
6178
authenticates hosts, it reads the entries in this file in sequence
6179
until a match is found. This means that wildcard entries must be
6180
placed near the end of the file, otherwise, they will override
6181
non-wildcard entries appearing after the wildcard ones.
6182
6183
The second field is the access level of HOST. The default is
6184
`deny'. If the user's hostname isn't in the file or its access level
6185
is set to `deny', the connection is closed immediately.
6186
6187
GNATS currently doesn't make use of the third field. Remember to
6188
still include the second `:' on the line if you choose to leave the
6189
third field empty.
6190
6191
Whenever a `CHDB' command is processed (or defaulted), the user's
6192
access level is set to the level for their host, as determined by the
6193
values in the `gnatsd.host_access' file. However, even if a host is
6194
given the `none' access level, an individual can still give the `USER'
6195
command to possibly gain a higher (but never lower) access than is set
6196
for their host. The gnatsd `USER' command takes two arguments: `USER
6197
<userid> <passwd>'.
6198
6199
6200
File: gnats.info, Node: gnatsd.user_access, Next: Privileged gnatsd commands, Prev: gnatsd.host_access, Up: Access Control
6201
6202
C.4 Access levels per user
6203
==========================
6204
6205
Access levels per user can be set both across all databases on the
6206
server or on a per-database basis. The `gnatsd.user_access' file in a
6207
database's `gnats-adm' directory specifies the user access rules for
6208
that database. If it doesn't exist, or doesn't contain the user name
6209
given to `gnatsd', then the overall user access file (by default
6210
`/usr/local/etc/gnats/gnatsd.user_access') specifying the per-user
6211
access levels across all the databases on the server is checked.
6212
6213
The user access files can only _increase_ the access level defined
6214
in the host access files for the given host, they can never lower it.
6215
6216
If the access level is `none' after processing the userid and
6217
password, the connection is closed.
6218
6219
The `gnatsd.user_access' files can contain plain text passwords, in
6220
such a case they should be owned by the GNATS user with file permission
6221
600.
6222
6223
Wildcard characters are supported for the userid and password with
6224
plain text passwords. A null string or `*' matches anything; `?'
6225
matches any one character. Note that when GNATS authenticates users,
6226
it reads the entries in this file in sequence until a match is found.
6227
This means that wildcard entries must be placed near the end of the
6228
file, otherwise, they will override non-wildcard entries appearing
6229
after the wildcard ones.
6230
6231
Entries in the database-specific `gnatsd.user_access' user access
6232
file in the `gnats-adm' directory of the database have the following
6233
general format:
6234
6235
USERID:PASSWORD:ACCESS-LEVEL
6236
6237
The overall `gnatsd.user_access' user access file adds a fourth
6238
DATABASES field:
6239
6240
USERID:PASSWORD:ACCESS-LEVEL:DATABASES
6241
6242
PASSWORD should either be in plain text, DES `crypt()'(1) or MD5 hash
6243
format(2).
6244
6245
If the password is in plain text format, it must be prefixed by
6246
`$0$' and if it is in MD5 format, it needs to be prefixed by the string
6247
`$1$'.(3) Passwords encrypted by `crypt()' should have no prefix. If no
6248
password is given then users can login with an empty password string.
6249
6250
A `gnats-passwd' tool to manage `gnatsd.user_access' files is
6251
planned. In the meantime, `crypt()' passwords can be generated by
6252
using standard UNIX passwords tools, while MD5 passwords can be
6253
generated with the following little Perl snippet:
6254
6255
perl -e 'use Crypt::PasswdMD5 ; print Crypt::PasswdMD5::unix_md5_crypt
6256
"PASSWORD" , time() % 100000000'
6257
6258
If your Perl installation doesn't have the Crypt module installed, you
6259
need to install it. On most systems, the following command achieves
6260
this:
6261
6262
perl -MCPAN -e 'install Crypt::PasswdMD5'
6263
6264
A tool for conversion of pre-version 4 `gnatsd.user_access' files is
6265
distributed with GNATS 4. *Note Converting old password files:
6266
gnats-pwconv.
6267
6268
The ACCESS-LEVEL field should contain one of the values listed at the
6269
beginning of this appendix. This overrides (increases but never
6270
lowers) the access level given as the default for the user's host in the
6271
global gnatsd.host_access file.
6272
6273
The following shows an example `gnatsd.user_access' file with plain
6274
text passwords:
6275
6276
rickm:$0$ruckm:edit
6277
pablo:$0$pueblo:view
6278
*::none
6279
6280
And this is the same file with MD5-encrypted passwords:
6281
rickm:$1$92388613$D7ZIYikzTUqd./dODTFrI.:edit
6282
pablo:$1$92388652$QRfAhIBG5elT.FQjQKhj80:view
6283
*::none
6284
6285
In these examples, anybody other than rickm and pablo get denied
6286
access, assuming that the host access level is also `none'. You could
6287
set the catch-all rule at the end to be `*::view' to allow view access
6288
to anyone who does not supply a password. Note the important detail
6289
that such a rule would allow view access only to persons who do not
6290
supply a password at all, i.e. if rickm or pablo tries to log in but
6291
mistypes his password, this rule would not apply and they would be
6292
denied access entirely. This is by design, since people might be
6293
surprised if they suddenly found themselves logged in, but with a lower
6294
access level than they usually have.
6295
6296
The DATABASES field contains a comma-separated list of database
6297
names, as defined in the `databases' file (*note The `databases' file:
6298
databases file. Wildcard characters are supported. The databases
6299
listed in this field are the ones to which the other settings on the
6300
same line will be applied.
6301
6302
---------- Footnotes ----------
6303
6304
(1) DES crypt is the standard password encryption format used by
6305
most UNIX systems
6306
6307
(2) MD5 is only supported on platforms that have a `crypt()'
6308
function that supports MD5. Among others, this currently includes GNU
6309
Linux and OpenBSD.
6310
6311
(3) Some systems support even more encryption methods. In FreeBSD,
6312
for instance, a prefix of `$2$' implies Blowfish encoding. GNATS will
6313
happily accept any encryption that the OS supports.
6314
6315
6316
File: gnats.info, Node: Privileged gnatsd commands, Prev: gnatsd.user_access, Up: Access Control
6317
6318
C.5 Privileged `gnatsd' commands
6319
================================
6320
6321
Every `gnatsd' command has a minimum access level attached to it. If
6322
your access level is too low for a command, you get this response:
6323
6324
LOCK 12
6325
422 You are not authorized to perform this operation (LOCK).
6326
6327
The commands `CHDB', `USER' and `QUIT' are unrestricted.
6328
6329
The `DBLS' command requires at least `listdb' access.
6330
6331
A user must have at least `edit' access for these commands:
6332
6333
`LKDB'
6334
lock the main GNATS database.
6335
6336
`UNDB'
6337
unlock the main GNATS database.
6338
6339
`LOCK PR USER PID'
6340
lock PR for USER and optional PID and return PR text.
6341
6342
`UNLK PR'
6343
unlock PR.
6344
6345
`EDIT PR'
6346
check in edited PR.
6347
6348
`APPN PR FIELD, REPL PR FIELD'
6349
Appends to or replaces the contents of FIELD in PR.
6350
6351
The `DELETE' PR command is special in that it requires `admin'
6352
access.
6353
6354
All other commands require `view' access.
6355
6356
`edit-pr' and `query-pr' accept the command line arguments
6357
`-v|--user' and `-w|--passwd'. *Note The GNATS User Tools: GNATS user
6358
tools.
6359
6360
6361
File: gnats.info, Node: Regexps, Next: dbconfig recipes, Prev: Access Control, Up: Top
6362
6363
Appendix D Querying using regular expressions
6364
*********************************************
6365
6366
See also *Note Query expressions::.
6367
6368
Unfortunately, we do not have room in this manual for a complete
6369
exposition on regular expressions. The following is a basic summary of
6370
some regular expressions you might wish to use.
6371
6372
_NOTE: When you use query expressions containing regular expressions
6373
as part of an ordinary query-pr shell command line, you need to quote
6374
them with `''', otherwise the shell will try to interpret the special
6375
characters used, yielding highly unpredictable results._
6376
6377
*Note Regular Expression Syntax: (regex)Regular Expression Syntax,
6378
for details on regular expression syntax. Also see *Note Syntax of
6379
Regular Expressions: (emacs)Regexps, but beware that the syntax for
6380
regular expressions in Emacs is slightly different.
6381
6382
All search criteria options to `query-pr' rely on regular expression
6383
syntax to construct their search patterns. For example,
6384
6385
query-pr --expr 'State="open"' --format full
6386
6387
matches all PRs whose `State' values match with the regular expression
6388
`open'.
6389
6390
We can substitute the expression `o' for `open', according to GNU
6391
regular expression syntax. This matches all values of `State' which
6392
begin with the letter `o'.
6393
6394
We see that
6395
6396
query-pr --expr 'State="o"' --format full
6397
6398
is equivalent to
6399
6400
query-pr --expr 'State="open"' --format full
6401
6402
in this case, since the only value for `State' which matches the
6403
expression `o' in a standard installation is `open'. `State="o"' also
6404
matches `o', `oswald', and even `oooooo', but none of those values are
6405
valid states for a Problem Report in default GNATS installations.
6406
6407
We can also use the expression operator `|' to signify a logical
6408
`OR', such that
6409
6410
query-pr --expr 'State="o|a"' --format full
6411
6412
matches all `open' or `analyzed' Problem Reports.
6413
6414
Regular expression syntax considers a regexp token surrounded with
6415
parentheses, as in `(REGEXP)', to be a "group". This means that
6416
`(ab)*' matches any number (including zero) of contiguous instances of
6417
`ab'. Matches include `', `ab', and `ababab'.
6418
6419
Regular expression syntax considers a regexp token surrounded with
6420
square brackets, as in `[REGEXP]', to be a "list". This means that
6421
`Char[(ley)(lene)(broiled)' matches any of the words `Charley',
6422
`Charlene', or `Charbroiled' (case is significant; `charbroiled' is not
6423
matched).
6424
6425
Using groups and lists, we see that
6426
6427
query-pr --expr 'Category="gcc|gdb|gas"' --format full
6428
6429
is equivalent to
6430
6431
query-pr --expr 'Category="g(cc|db|as)"' --format full
6432
6433
and is also very similar to
6434
6435
query-pr --expr 'Category="g[cda]"' --format full
6436
6437
with the exception that this last search matches any values which begin
6438
with `gc', `gd', or `ga'.
6439
6440
The `.' character is known as a "wildcard". `.' matches on any
6441
single character. `*' matches the previous character (except
6442
newlines), list, or group any number of times, including zero.
6443
Therefore, we can understand `.*' to mean "match zero or more instances
6444
of any character."
6445
6446
query-pr --expr 'State=".*a"' --format full
6447
6448
matches all values for `State' which contain an `a'. (These include
6449
`analyzed' and `feedback'.)
6450
6451
Another way to understand what wildcards do is to follow them on
6452
their search for matching text. By our syntax, `.*' matches any
6453
character any number of times, including zero. Therefore, `.*a'
6454
searches for any group of characters which end with `a', ignoring the
6455
rest of the field. `.*a' matches `analyzed' (stopping at the first
6456
`a') as well as `feedback'.
6457
6458
_Note:_ When using `fieldtype:Text' or `fieldtype:Multitext' (*note
6459
Query expressions::), you do not have to specify the token `.*' at the
6460
beginning of your expression to match the entire field. For the
6461
technically minded, this is because these queries use `re_search'
6462
rather than `re_match'. `re_match' "anchors" the search at the
6463
beginning of the field, while `re_search' does not anchor the search.
6464
6465
For example, to search in the `>Description:' field for the text
6466
6467
The defrobulator component returns a nil value.
6468
6469
we can use
6470
6471
query-pr --expr 'fieldtype:Multitext="defrobulator.*nil"' --format full
6472
6473
To also match newlines, we have to include the expression `(.|^M)'
6474
instead of just a dot (`.'). `(.|^M)' matches "any single character
6475
except a newline (`.') _or_ (`|') any newline (`^M')." This means that
6476
to search for the text
6477
6478
The defrobulator component enters the bifrabulator routine
6479
and returns a nil value.
6480
6481
we must use
6482
6483
query-pr --expr 'fieldtype:Multitext="defrobulator(.|^M)*nil"'
6484
--format full
6485
6486
To generate the newline character `^M', type the following depending
6487
on your shell:
6488
6489
`csh'
6490
`_control_-V _control_-M'
6491
6492
`tcsh'
6493
`_control_-V _control_-J'
6494
6495
`sh (_or_ bash)'
6496
Use the <RETURN> key, as in
6497
6498
(.|
6499
)
6500
6501
Again, see *Note Regular Expression Syntax: (regex)Regular
6502
Expression Syntax, for a much more complete discussion on regular
6503
expression syntax.
6504
6505
6506
File: gnats.info, Node: dbconfig recipes, Next: Support, Prev: Regexps, Up: Top
6507
6508
Appendix E `dbconfig' recipes
6509
*****************************
6510
6511
The `dbconfig' file (*Note The `dbconfig' file: dbconfig file.) is the
6512
heart of any GNATS installation. It contains some very powerful
6513
machinery, something which this appendix tries to illustrate.
6514
6515
We provide a range of examples that are both intended to be useful in
6516
their own right and to serve as starting points or building blocks for
6517
your own modifications.
6518
6519
Provide Gnatsweb URL in initial response
6520
........................................
6521
6522
Sites that have Gnatsweb installed may wish to modify the response
6523
e-mail which is sent to the submitter of a PR so that it includes a URL
6524
where the status of the PR can be monitored. In order to allow this,
6525
you should first create an entry in `gnatsd.user_access' which allows
6526
viewing of PRs in your database (*Note The `gnatsd.user_access' file:
6527
gnatsd.user_access.)
6528
6529
Next, locate the entry `mail-format "initial-response-to-submitter"'
6530
in the `dbconfig' file of your database and add the following _before_
6531
the line reading "The individual assigned..." in the `body' section:
6532
6533
6534
\nYou can follow the status of this report on\n\
6535
http://hostname/cgi-bin/scriptname?\n\
6536
cmd=view&database=dbname&user=username&\n\
6537
password=passwd&pr=%s\n\n\
6538
6539
Substitute `hostname', `cgi-bin' and `scriptname' as appropriate for
6540
the setup of your web server. The part before the `?' would typically
6541
look something like `http://www.example.com/cgi-bin/gnatsweb.pl'.
6542
Substitute the name of your database for `dbname', and the username and
6543
password of the user with `view' rights for `username' and `passwd'.
6544
6545
Next, add a `Number' to the `fields' list statement inside the `body'
6546
so it reads as follows:
6547
6548
6549
fields { "Category" "Number" "Number" "Responsible"
6550
"Category" "Responsible" "Synopsis"
6551
"Arrival-Date" }
6552
6553
State full name of responsible in initial response
6554
..................................................
6555
6556
The initial e-mail response to the submitter of a PR identifies the
6557
responsible person assigned to the PR as follows: "The individual
6558
assigned to look at your report is: GNATS USERNAME". Some sites may
6559
wish to modify this so that the full name of the responsible person is
6560
used instead of the GNATS user name.
6561
6562
The full name is contained in the `fullname' subfield of the user's
6563
entry in the `responsible' file and can be accessed as
6564
`Responsible[fullname]' (*note Enumerated field administrative files:
6565
administrative files.)
6566
6567
The change is achieved by editing the `dbconfig' item `mail-format
6568
"initial-response-to-submitter"' and changing the `fields' part of the
6569
`Body' from
6570
6571
6572
fields { "Category" "Number" "Responsible"
6573
"Category" "Responsible" "Synopsis"
6574
"Arrival-Date" }
6575
6576
to
6577
6578
6579
fields { "Category" "Number" "Responsible[fullname]"
6580
"Category" "Responsible" "Synopsis"
6581
"Arrival-Date" }
6582
6583
Append-only Audit-Trail
6584
.......................
6585
6586
The Audit-Trail of a PR is by default editable. For some applications,
6587
one might want to make the Audit-Trail append-only, so it provides a
6588
full and unchangeable case history. Also by default, only certain
6589
changes, such as change of state and change of responsible gets
6590
recorded in the Audit-Trail. In some cases, it might also be
6591
convenient to have a way of inserting comments directly into the
6592
Audit-Trail.
6593
6594
The following procedure creates such an append-only Audit-Trail and
6595
adds a PR field which makes it possible to register comments in the
6596
Audit-Trail.
6597
6598
First, add the keyword `read-only' to the Audit-Trail field definition
6599
in `dbconfig'.
6600
6601
Then, add the following field definition to `dbconfig':
6602
6603
6604
field "Add-To-Audit-Trail" {
6605
description "Add a log entry to the Audit Trail"
6606
multitext { default "\n" }
6607
on-change {
6608
add-audit-trail
6609
audit-trail-format {
6610
format "**** Comment added by %s on %s ****\n %s\n\n"
6611
fields { "$EditUserEmailAddr" "$CurrentDate" "$NewValue"
6612
}
6613
}
6614
}
6615
on-change {
6616
set-field "Add-To-Audit-Trail" { "\n" }
6617
}
6618
}
6619
6620
Supporting GNATS "release-based" fields
6621
.......................................
6622
6623
When installing GNATS version 3.x, it was possible to choose whether to
6624
enable three optional fields: `Quarter', `Keywords' and
6625
`Date-Required'. Default installations had these fields switched off,
6626
and installations which had them were called "release-based".
6627
6628
The default `dbconfig' shipped with GNATS version 4 or newer does
6629
not have these fields, so if you are upgrading from an old
6630
release-based system, you need to add the following field definitions to
6631
your `dbconfig' file:
6632
6633
6634
field "Quarter" {
6635
description "What quarter does the PR fall into?"
6636
text
6637
query-default inexact-regexp
6638
textsearch
6639
}
6640
6641
field "Keywords" {
6642
description "Keywords used to index this PR"
6643
text
6644
query-default inexact-regexp
6645
textsearch
6646
}
6647
6648
field "Date-Required" {
6649
description "Date that the PR must be fixed by"
6650
date
6651
}
6652
6653
A side note: Pre-release versions of GNATS 4 also had a field named
6654
`Cases'. For those who may need it, here is the field definition of
6655
`Cases':
6656
6657
6658
field "Cases" {
6659
text
6660
query-default inexact-regexp
6661
textsearch
6662
}
6663
6664
6665
File: gnats.info, Node: Support, Next: Index, Prev: dbconfig recipes, Up: Top
6666
6667
Appendix F GNATS support
6668
************************
6669
6670
The GNATS home page is located at `http://www.gnu.org/software/gnats'.
6671
It contains all the important references to the available information
6672
about GNATS and the related software.
6673
6674
There is also a special page dedicated to the GNATS development at
6675
`http://savannah.gnu.org/projects/gnats'.
6676
6677
There are several GNATS mailing lists. The most important ones are:
6678
6679
<info-gnats@gnu.org>
6680
Announcements and other important information about GNATS and the
6681
related software. This is a very low volume moderated list.
6682
6683
<bug-gnats@gnu.org>
6684
The bug reporting mailing list on the GNATS itself. Please note
6685
that the preferred way to report GNATS bugs is to submit them via
6686
the web interface at
6687
`http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=gnats'. New bug
6688
reports submitted via the web interface are copied to the mailing
6689
list automatically.
6690
6691
<help-gnats@gnu.org>
6692
General discussion about GNATS. Anything related to GNATS (user
6693
questions, development, suggestions, etc.) can be discussed there.
6694
6695
The complete list of GNATS related mailing lists is available from
6696
the web page at `http://savannah.gnu.org/project/gnats'.
6697
6698
When you report problems concerning GNATS itself, please do not
6699
forget to provide especially the following information:
6700
6701
* The GNATS version you are using.
6702
6703
* The _exact_ way how to reproduce the bug.
6704
6705
* Your configuration.
6706
6707
* If you encounter a compilation or build problem, it is especially
6708
important to mention the operating system, compiler and possibly
6709
other build utilities you use.
6710
6711
Providing this information in the initial report avoids further
6712
unnecessary communication, saves our limited development resources and
6713
helps to track down and fix the problem soon.
6714
6715
6716
File: gnats.info, Node: Index, Prev: Support, Up: Top
6717
6718
Index
6719
*****
6720
6721
[index ]
6722
* Menu:
6723
6724
* -with-gnats-dblist-file: Configure and make. (line 112)
6725
* -with-gnats-default-db: Configure and make. (line 117)
6726
* -with-gnats-service: Configure and make. (line 91)
6727
* -with-gnats-user: Configure and make. (line 95)
6728
* -with-gnatsd-host-access-file: Configure and make. (line 106)
6729
* -with-gnatsd-user-access-file: Configure and make. (line 99)
6730
* -with-kerberos: Configure and make. (line 123)
6731
* -with-krb4: Configure and make. (line 126)
6732
* >Submitter-Id: PR template. (line 108)
6733
* _analyzed_ state: States. (line 19)
6734
* _change-request_ class: Problem Report fields.
6735
(line 108)
6736
* _closed_ state: States. (line 30)
6737
* _critical_ severity problems: Problem Report fields.
6738
(line 63)
6739
* _doc-bug_ class: Problem Report fields.
6740
(line 105)
6741
* _duplicate_ class: Problem Report fields.
6742
(line 114)
6743
* _feedback_ state: States. (line 25)
6744
* _high_ priority problems: Problem Report fields.
6745
(line 83)
6746
* _low_ priority problems: Problem Report fields.
6747
(line 89)
6748
* _medium_ priority problems: Problem Report fields.
6749
(line 86)
6750
* _mistaken_ class: Problem Report fields.
6751
(line 118)
6752
* _non-critical_ severity problems: Problem Report fields.
6753
(line 74)
6754
* _open_ state: States. (line 15)
6755
* _serious_ severity problems: Problem Report fields.
6756
(line 68)
6757
* _support_ class: Problem Report fields.
6758
(line 111)
6759
* _suspended_ state: States. (line 35)
6760
* _sw-bug_ class: Problem Report fields.
6761
(line 102)
6762
* adding a problem category <1>: mkcat. (line 6)
6763
* adding a problem category: Management. (line 40)
6764
* adding and removing maintainers: Management. (line 60)
6765
* adding another database: Management. (line 34)
6766
* addresses file <1>: addresses file. (line 6)
6767
* addresses file: GNATS configuration. (line 71)
6768
* admin files: Admin files. (line 6)
6769
* administering GNATS: Management. (line 6)
6770
* administrative utilities: Admin utils. (line 6)
6771
* age of PR: pr-age. (line 6)
6772
* alias for incoming Problem Reports: Aliases. (line 21)
6773
* aliases: Aliases. (line 6)
6774
* appended-email-response: Outgoing email formats.
6775
(line 57)
6776
* arrival-date: Individual field configuration.
6777
(line 38)
6778
* Arrival-Date field: Problem Report fields.
6779
(line 203)
6780
* at: Setting up the default database.
6781
(line 53)
6782
* at-pr: at-pr. (line 6)
6783
* audit-mail: Outgoing email formats.
6784
(line 61)
6785
* audit-trail: Individual field configuration.
6786
(line 41)
6787
* Audit-Trail field: Problem Report fields.
6788
(line 212)
6789
* Audit-trail format: Audit-trail formats. (line 6)
6790
* autoload commands: Installing utils. (line 28)
6791
* automatic notification <1>: at-pr. (line 6)
6792
* automatic notification: States. (line 8)
6793
* BACK UP YOUR DATA: Management. (line 77)
6794
* bad Problem Reports: PR template. (line 113)
6795
* bug alias: Aliases. (line 21)
6796
* bug reporting: Support. (line 34)
6797
* building a new index: Management. (line 65)
6798
* building GNATS: Installation. (line 6)
6799
* building in a different directory: Configure and make. (line 136)
6800
* builtin-name: Individual field configuration.
6801
(line 29)
6802
* bury-buffer: Emacs querying. (line 45)
6803
* business-day-hours: Overall database configuration.
6804
(line 46)
6805
* business-week-days: Overall database configuration.
6806
(line 53)
6807
* categories file <1>: rmcat. (line 6)
6808
* categories file <2>: mkcat. (line 6)
6809
* categories file <3>: categories file. (line 6)
6810
* categories file: GNATS configuration. (line 48)
6811
* category: Individual field configuration.
6812
(line 44)
6813
* Category field: Problem Report fields.
6814
(line 92)
6815
* category-dir-perms: Overall database configuration.
6816
(line 67)
6817
* check-db: check-db. (line 6)
6818
* Class field: Problem Report fields.
6819
(line 98)
6820
* classes file <1>: classes file. (line 6)
6821
* classes file: GNATS configuration. (line 82)
6822
* closed-date: Individual field configuration.
6823
(line 47)
6824
* command line options: send-pr from the shell.
6825
(line 6)
6826
* comment section in the PR template: PR template. (line 25)
6827
* compiling the software: Configure and make. (line 6)
6828
* confidential: Individual field configuration.
6829
(line 50)
6830
* Confidential field: Problem Report fields.
6831
(line 42)
6832
* confidentiality in PRs: Problem Report fields.
6833
(line 42)
6834
* configure: Configure and make. (line 6)
6835
* configuring GNATS: Installation. (line 6)
6836
* configuring and compiling the software: Configure and make. (line 6)
6837
* configuring GNATS for remote users: Installing tools. (line 59)
6838
* configuring GNATS on a local network: Installing tools. (line 30)
6839
* configuring GNATS on a network: Installing tools. (line 6)
6840
* create-category-dirs: Overall database configuration.
6841
(line 61)
6842
* creating an account for the GNATS user: Configure and make. (line 31)
6843
* cron: Setting up the default database.
6844
(line 53)
6845
* crontab: Setting up periodic jobs.
6846
(line 14)
6847
* current file: current file. (line 6)
6848
* daemon: Installing the daemon.
6849
(line 6)
6850
* database paradigm: Paradigm. (line 6)
6851
* database rationale: Introduction. (line 6)
6852
* database similarities: Fields. (line 6)
6853
* databases: GNATS configuration. (line 20)
6854
* databases file: databases file. (line 6)
6855
* datatype: Field datatypes. (line 10)
6856
* date: Field datatypes. (line 134)
6857
* Date-Required: Problem Report fields.
6858
(line 207)
6859
* Date-Required field: Problem Report fields.
6860
(line 207)
6861
* dbconfig: dbconfig recipes. (line 6)
6862
* dbconfig file <1>: dbconfig file. (line 6)
6863
* dbconfig file: GNATS configuration. (line 44)
6864
* dbconfig mode: dbconfig mode. (line 6)
6865
* dbconfig recipes: dbconfig recipes. (line 6)
6866
* debug-mode: Overall database configuration.
6867
(line 17)
6868
* default installation locations <1>: defaults. (line 6)
6869
* default installation locations: Locations. (line 6)
6870
* defaults: GNATS configuration. (line 26)
6871
* deleted-pr-mail: Outgoing email formats.
6872
(line 65)
6873
* description: Individual field configuration.
6874
(line 53)
6875
* Description field: Problem Report fields.
6876
(line 134)
6877
* diff-prs: diff-prs. (line 6)
6878
* Direct e-mail: Submitting via e-mail.
6879
(line 6)
6880
* disabling SUBMITTER-ID: submitters file. (line 68)
6881
* driver for edit-pr: pr-edit. (line 6)
6882
* duties for gnats-admin: Management. (line 6)
6883
* edit controls: Edit controls. (line 6)
6884
* edit-pr <1>: Emacs editing. (line 6)
6885
* edit-pr: edit-pr. (line 6)
6886
* edit-pr driver: pr-edit. (line 6)
6887
* edit-pr from the shell: edit-pr from the shell.
6888
(line 6)
6889
* effective problem reporting: Helpful hints. (line 6)
6890
* Emacs: Emacs. (line 6)
6891
* Emacs functions: Installing utils. (line 28)
6892
* Emacs lisp file installation: Configure and make. (line 20)
6893
* emptying the pending directory: Management. (line 12)
6894
* enum: Field datatypes. (line 31)
6895
* enumerated-in-file: Field datatypes. (line 73)
6896
* Environment field: Problem Report fields.
6897
(line 129)
6898
* environment variables and GNATS tools: Environment. (line 6)
6899
* errors: PR template. (line 113)
6900
* example Problem Report: Fields. (line 34)
6901
* example queries: Example queries. (line 6)
6902
* EXEC-PREFIX <1>: exec-prefix. (line 6)
6903
* EXEC-PREFIX: Configure and make. (line 86)
6904
* Field datatypes: Field datatypes. (line 6)
6905
* field format: Problem Report fields.
6906
(line 6)
6907
* fields: Fields. (line 6)
6908
* fields - list: Problem Report fields.
6909
(line 18)
6910
* file-pr: file-pr. (line 6)
6911
* files used for GNATS administration: Admin files. (line 6)
6912
* final state ("closed"): States. (line 30)
6913
* Fix field: Problem Report fields.
6914
(line 149)
6915
* flowchart of GNATS activities: Flowchart. (line 6)
6916
* follow-up via email <1>: follow-up via email. (line 6)
6917
* follow-up via email: Problem Report fields.
6918
(line 234)
6919
* foreword: Top. (line 6)
6920
* format: Fields. (line 6)
6921
* format parameters: Audit-trail formats. (line 31)
6922
* format-name: Outgoing email formats.
6923
(line 42)
6924
* From header: Mail header fields. (line 23)
6925
* gen-index <1>: gen-index. (line 6)
6926
* gen-index: Management. (line 65)
6927
* GNATS administrator: Paradigm. (line 48)
6928
* GNATS configuration: GNATS configuration. (line 6)
6929
* GNATS database fields: Problem Report fields.
6930
(line 6)
6931
* GNATS fields - list: Problem Report fields.
6932
(line 18)
6933
* GNATS management: Management. (line 6)
6934
* GNATS support: Support. (line 6)
6935
* GNATS-ADM: gnats-adm. (line 6)
6936
* gnats-admin alias: Aliases. (line 15)
6937
* gnats-apply-or-submit: Emacs editing buffer.
6938
(line 47)
6939
* gnats-change-database <1>: Emacs and databases. (line 6)
6940
* gnats-change-database: Emacs querying. (line 41)
6941
* gnats-dbconfig-mode: dbconfig mode. (line 6)
6942
* gnats-dbconfig-mode-hook: dbconfig mode. (line 11)
6943
* GNATS-DEFAULT-ORGANIZATION: Emacs submitting. (line 19)
6944
* GNATS-DEFAULT-SUBMITTER: Emacs submitting. (line 23)
6945
* gnats-edit-mode-hook: Emacs editing buffer.
6946
(line 53)
6947
* gnats-next-field: Emacs editing buffer.
6948
(line 23)
6949
* gnats-previous-field: Emacs editing buffer.
6950
(line 23)
6951
* gnats-pwconv: gnats-pwconv. (line 6)
6952
* gnats-query-edit-pr: Emacs querying. (line 26)
6953
* gnats-query-mode-hook: Emacs querying. (line 57)
6954
* gnats-query-reread: Emacs querying. (line 30)
6955
* GNATS-QUERY-REVERSE-LISTING: Emacs querying. (line 50)
6956
* gnats-query-view-pr: Emacs querying. (line 20)
6957
* gnats-show-connection: Other Emacs commands.
6958
(line 16)
6959
* gnats-view-edit-pr: Emacs viewing. (line 9)
6960
* gnats-view-mode-hook: Emacs viewing. (line 13)
6961
* gnatsd: gnatsd. (line 6)
6962
* gnatsd command protocol: gnatsd command protocol.
6963
(line 6)
6964
* gnatsd commands: gnatsd commands. (line 6)
6965
* gnatsd description: Description of gnatsd.
6966
(line 6)
6967
* gnatsd environment variables: gnatsd environment variables.
6968
(line 6)
6969
* gnatsd options: gnatsd options. (line 6)
6970
* gnatsd startup options: gnatsd options. (line 12)
6971
* gnatsd, Emacs: Emacs and databases. (line 11)
6972
* gnatsd.host_access <1>: gnatsd.host_access. (line 6)
6973
* gnatsd.host_access: GNATS configuration. (line 31)
6974
* gnatsd.user_access <1>: gnatsd.user_access. (line 6)
6975
* gnatsd.user_access: GNATS configuration. (line 36)
6976
* gnatsd.user_access file: GNATS configuration. (line 88)
6977
* GNATSDB <1>: gnatsd environment variables.
6978
(line 6)
6979
* GNATSDB: Environment. (line 6)
6980
* handling incoming traffic: queue-pr. (line 6)
6981
* helpful hints: Helpful hints. (line 6)
6982
* How-To-Repeat field: Problem Report fields.
6983
(line 137)
6984
* incoming alias for Problem Reports: Aliases. (line 21)
6985
* incoming PRs that GNATS cannot parse: Paradigm. (line 62)
6986
* index file <1>: gen-index. (line 6)
6987
* index file: index file. (line 6)
6988
* Index file description: Index file description.
6989
(line 6)
6990
* Individual field configuration: Individual field configuration.
6991
(line 6)
6992
* information to submit: Helpful hints. (line 6)
6993
* Initial PR input fields: Initial PR input fields.
6994
(line 6)
6995
* initial state ("open"): States. (line 15)
6996
* initial-pr-notification: Outgoing email formats.
6997
(line 49)
6998
* initial-pr-notification-pending: Outgoing email formats.
6999
(line 53)
7000
* initial-response-to-submitter: Outgoing email formats.
7001
(line 43)
7002
* initializing a database: mkdb. (line 6)
7003
* installing GNATS: Installation. (line 6)
7004
* installing the utilities: Installing utils. (line 6)
7005
* integer: Field datatypes. (line 141)
7006
* interactive interface: send-pr in Emacs. (line 6)
7007
* internal utilities: Internal utils. (line 6)
7008
* Internet standard RFC-822: Mail header fields. (line 6)
7009
* introduction to GNATS: Introduction. (line 6)
7010
* invalid Problem Reports: PR template. (line 113)
7011
* invoking edit-pr: edit-pr. (line 6)
7012
* invoking query-pr: query-pr. (line 6)
7013
* invoking send-pr: send-pr. (line 6)
7014
* invoking send-pr from Emacs: send-pr in Emacs. (line 6)
7015
* invoking send-pr from the shell: send-pr from the shell.
7016
(line 6)
7017
* invoking the GNATS user tools: GNATS user tools. (line 6)
7018
* keep-all-received-headers: Overall database configuration.
7019
(line 23)
7020
* kinds of helpful information: Helpful hints. (line 6)
7021
* last-modified: Individual field configuration.
7022
(line 56)
7023
* libexecdir: Overall database configuration.
7024
(line 40)
7025
* life-cycle of a Problem Report: States. (line 8)
7026
* lisp file installation: Configure and make. (line 20)
7027
* loading .el files: Installing utils. (line 28)
7028
* locations: Locations. (line 6)
7029
* locks: pr-edit. (line 29)
7030
* mail aliases: Aliases. (line 6)
7031
* mail header fields: Mail header fields. (line 6)
7032
* mail header section: PR template. (line 48)
7033
* mailing lists: Support. (line 13)
7034
* maintenance: Paradigm. (line 6)
7035
* make: Configure and make. (line 6)
7036
* managing GNATS: Management. (line 6)
7037
* mkcat <1>: mkcat. (line 6)
7038
* mkcat: Management. (line 40)
7039
* mkdb <1>: mkdb. (line 6)
7040
* mkdb: Management. (line 34)
7041
* multi-enumerated-in-file: Field datatypes. (line 116)
7042
* multienum: Field datatypes. (line 52)
7043
* multitext: Field datatypes. (line 24)
7044
* Named query definitions: Named query definitions.
7045
(line 6)
7046
* networks: Installing tools. (line 6)
7047
* new database: mkdb. (line 6)
7048
* new problem categories: mkcat. (line 6)
7049
* notification of overdue PRs: at-pr. (line 6)
7050
* notify-about-expired-prs: Overall database configuration.
7051
(line 28)
7052
* Notify-List field: Problem Report fields.
7053
(line 29)
7054
* number: Individual field configuration.
7055
(line 59)
7056
* Number field: Problem Report fields.
7057
(line 157)
7058
* OBJDIR: Configure and make. (line 136)
7059
* Organization field: Problem Report fields.
7060
(line 39)
7061
* originator: Individual field configuration.
7062
(line 62)
7063
* Originator field: Problem Report fields.
7064
(line 35)
7065
* Outgoing email formats: Outgoing email formats.
7066
(line 6)
7067
* Overall database configuration: Overall database configuration.
7068
(line 6)
7069
* Overview of GNATS configuration: GNATS configuration. (line 6)
7070
* overview to GNATS: Top. (line 6)
7071
* paradigm: Paradigm. (line 6)
7072
* password, Emacs: Emacs and databases. (line 16)
7073
* pending directory: Paradigm. (line 62)
7074
* pending file: categories file. (line 77)
7075
* PR confidentiality: Problem Report fields.
7076
(line 42)
7077
* PR locks: pr-edit. (line 29)
7078
* pr-age: pr-age. (line 6)
7079
* pr-edit: pr-edit. (line 6)
7080
* PREFIX <1>: prefix. (line 6)
7081
* PREFIX: Configure and make. (line 80)
7082
* prepare send-pr.conf: Installing utils. (line 49)
7083
* priority: Individual field configuration.
7084
(line 65)
7085
* Priority field: Problem Report fields.
7086
(line 79)
7087
* Problem Report format: Fields. (line 6)
7088
* Problem Report states: States. (line 8)
7089
* Problem Report template: Fields. (line 34)
7090
* processing incoming traffic: file-pr. (line 6)
7091
* pruning log files: Management. (line 70)
7092
* query expressions: Query expressions. (line 6)
7093
* query-pr <1>: Emacs querying. (line 6)
7094
* query-pr: query-pr. (line 6)
7095
* query-pr by mail: Invoking query-pr. (line 10)
7096
* query-pr output format: Formatting query-pr output.
7097
(line 6)
7098
* querying individual problem reports: query-pr. (line 6)
7099
* querying using regexps: Regexps. (line 6)
7100
* queue-pr: queue-pr. (line 6)
7101
* queue-pr -q: Aliases. (line 21)
7102
* rationale: Introduction. (line 6)
7103
* Received-By headers: Mail header fields. (line 32)
7104
* regular expressions: Regexps. (line 6)
7105
* related mail <1>: follow-up via email. (line 6)
7106
* related mail: Problem Report fields.
7107
(line 234)
7108
* Release field: Problem Report fields.
7109
(line 125)
7110
* reminder message: at-pr. (line 24)
7111
* removing a problem category <1>: rmcat. (line 6)
7112
* removing a problem category: Management. (line 48)
7113
* Reply-To header: Mail header fields. (line 28)
7114
* Report all the facts!: Helpful hints. (line 6)
7115
* reporting problems with send-pr: send-pr. (line 6)
7116
* responsible: Individual field configuration.
7117
(line 68)
7118
* Responsible field: Problem Report fields.
7119
(line 198)
7120
* responsible file <1>: responsible file. (line 6)
7121
* responsible file: GNATS configuration. (line 57)
7122
* Responsible-Changed-<From>-<To> in Audit-Trail: Problem Report fields.
7123
(line 219)
7124
* Responsible-Changed-By in Audit-Trail: Problem Report fields.
7125
(line 222)
7126
* Responsible-Changed-When in Audit-Trail: Problem Report fields.
7127
(line 226)
7128
* Responsible-Changed-Why in Audit-Trail: Problem Report fields.
7129
(line 230)
7130
* rmcat <1>: rmcat. (line 6)
7131
* rmcat: Management. (line 48)
7132
* sample Problem Report: Fields. (line 34)
7133
* send-pr <1>: Emacs submitting. (line 6)
7134
* send-pr <2>: Emacs querying. (line 38)
7135
* send-pr: send-pr. (line 6)
7136
* send-pr fields <1>: PR template. (line 86)
7137
* send-pr fields: send-pr from the shell.
7138
(line 50)
7139
* send-pr within Emacs: send-pr in Emacs. (line 6)
7140
* send-pr.conf file: send-pr.conf file. (line 6)
7141
* send-submitter-ack: Overall database configuration.
7142
(line 33)
7143
* setting up GNATS: Installation. (line 6)
7144
* severity: Individual field configuration.
7145
(line 71)
7146
* Severity field: Problem Report fields.
7147
(line 59)
7148
* shell invocation: send-pr from the shell.
7149
(line 6)
7150
* Site wide configuration files: GNATS configuration. (line 19)
7151
* so what does it do: Paradigm. (line 6)
7152
* state: Individual field configuration.
7153
(line 74)
7154
* State field: Problem Report fields.
7155
(line 172)
7156
* state--"analyzed": States. (line 19)
7157
* state--"closed": States. (line 30)
7158
* state--"feedback": States. (line 25)
7159
* state--"open": States. (line 15)
7160
* state--"suspended": States. (line 35)
7161
* State-Changed-<From>-<To> in Audit-Trail: Problem Report fields.
7162
(line 216)
7163
* State-Changed-By in Audit-Trail: Problem Report fields.
7164
(line 222)
7165
* State-Changed-When in Audit-Trail: Problem Report fields.
7166
(line 226)
7167
* State-Changed-Why in Audit-Trail: Problem Report fields.
7168
(line 230)
7169
* states file <1>: states file. (line 6)
7170
* states file: GNATS configuration. (line 78)
7171
* states of Problem Reports: States. (line 8)
7172
* Subject header: Mail header fields. (line 19)
7173
* submitter-id: Individual field configuration.
7174
(line 77)
7175
* Submitter-Id field <1>: PR template. (line 108)
7176
* Submitter-Id field: Problem Report fields.
7177
(line 18)
7178
* submitters file <1>: submitters file. (line 6)
7179
* submitters file: GNATS configuration. (line 66)
7180
* Submitting a PR via e-mail: Submitting via e-mail.
7181
(line 6)
7182
* subsequent mail <1>: follow-up via email. (line 6)
7183
* subsequent mail: Problem Report fields.
7184
(line 234)
7185
* support site: Paradigm. (line 6)
7186
* synopsis: Individual field configuration.
7187
(line 80)
7188
* Synopsis field: Problem Report fields.
7189
(line 55)
7190
* syntax of regexps: Regexps. (line 6)
7191
* template: PR template. (line 11)
7192
* template comment section: PR template. (line 25)
7193
* text: Field datatypes. (line 14)
7194
* the section on query-by-mail needs to be relocated: Invoking query-pr.
7195
(line 17)
7196
* timely reminders: at-pr. (line 6)
7197
* To header: Mail header fields. (line 14)
7198
* unformatted: Individual field configuration.
7199
(line 83)
7200
* Unformatted field: Problem Report fields.
7201
(line 240)
7202
* unlock-database: Other Emacs commands.
7203
(line 12)
7204
* unlock-pr: Other Emacs commands.
7205
(line 6)
7206
* unpacking the distribution: Configure and make. (line 6)
7207
* unparseable incoming PRs: Paradigm. (line 62)
7208
* upgrade, procedure: Upgrading. (line 53)
7209
* upgrading from older versions: Upgrading. (line 6)
7210
* upgrading, overview: Upgrading. (line 15)
7211
* usage for the GNATS user tools: GNATS user tools. (line 6)
7212
* Using and Porting GNU CC: Helpful hints. (line 6)
7213
* using edit-pr: edit-pr. (line 6)
7214
* using GNATS over a local network: Installing tools. (line 30)
7215
* using GNATS over a network <1>: Installing tools. (line 6)
7216
* using GNATS over a network: Installing the daemon.
7217
(line 6)
7218
* using GNATS remotely: Installing tools. (line 59)
7219
* using query-pr: query-pr. (line 6)
7220
* using send-pr: send-pr. (line 6)
7221
* using send-pr from within Emacs: send-pr in Emacs. (line 6)
7222
* view-pr: Emacs viewing. (line 6)
7223
* visual map of data flow: Flowchart. (line 6)
7224
* what is a PR: Paradigm. (line 25)
7225
* where GNATS lives: Locations. (line 6)
7226
* why GNATS: Paradigm. (line 6)
7227
7228
31
7229
32
7230
Tag Table:
33
(Indirect)
34
Node: Top851
35
Node: Introduction2831
36
Node: Paradigm3930
37
Node: Flowchart8914
38
Node: States11076
39
Node: Fields12643
40
Node: Field datatypes reference15316
41
Node: Mail header fields16302
42
Node: Problem Report fields17788
43
Node: GNATS user tools27178
44
Node: Environment28300
45
Node: send-pr29146
46
Node: send-pr from the shell29887
47
Node: send-pr in Emacs32135
48
Ref: send-pr in Emacs-Footnote-132804
49
Node: PR template32920
50
Node: Submitting via e-mail38249
51
Node: Helpful hints39325
52
Node: edit-pr42418
53
Node: edit-pr from the shell44778
54
Node: follow-up via email46810
55
Node: query-pr48748
56
Node: Invoking query-pr50222
57
Node: Formatting query-pr output59418
58
Node: Query expressions61939
59
Node: Example queries66232
60
Node: Emacs67275
61
Node: Emacs viewing68728
62
Node: Emacs querying69259
63
Node: Emacs submitting71190
64
Node: Emacs editing72223
65
Node: Emacs editing buffer72850
66
Node: Emacs and databases75420
67
Node: dbconfig mode76422
68
Node: Other Emacs commands76895
69
Node: Emacs customization77810
70
Node: Installation78062
71
Node: Configure and make81014
72
Node: Installing utils87483
73
Node: Setting up the default database89474
74
Ref: Setting up the default database-Footnote-191803
75
Node: Setting up periodic jobs91939
76
Node: Aliases93080
77
Node: Installing the daemon95485
78
Node: Installing tools98524
79
Node: Upgrading104054
80
Node: Management112305
81
Node: GNATS configuration116345
82
Node: databases file120610
83
Node: dbconfig file122701
84
Node: Overall database configuration124931
85
Node: Individual field configuration128193
86
Node: Field datatypes132424
87
Ref: administrative files135401
88
Node: Edit controls138483
89
Node: Named query definitions140951
90
Node: Audit-trail formats142048
91
Node: Outgoing email formats143745
92
Node: Index file description150277
93
Node: Initial PR input fields151630
94
Node: Other config files152361
95
Node: categories file152671
96
Node: responsible file155949
97
Node: submitters file157326
98
Node: states file160318
99
Node: addresses file163229
100
Node: classes file165121
101
Node: send-pr.conf file166054
102
Node: Admin files168445
103
Node: index file168883
104
Node: current file170299
105
Node: Admin utils170554
106
Node: mkdb171130
107
Node: mkcat171735
108
Node: rmcat172385
109
Node: gen-index173183
110
Node: check-db174792
111
Node: gnats-pwconv176114
112
Node: Internal utils177242
113
Node: queue-pr177805
114
Node: file-pr179770
115
Node: at-pr182832
116
Node: pr-edit184453
117
Ref: pr-edit-Footnote-1191211
118
Node: diff-prs191305
119
Node: pr-age191700
120
Node: Locations192317
121
Node: prefix192739
122
Node: exec-prefix193471
123
Node: gnats-adm195951
124
Node: defaults196732
125
Node: gnatsd201103
126
Node: Description of gnatsd201562
127
Node: gnatsd options202867
128
Node: gnatsd command protocol204559
129
Node: gnatsd commands208840
130
Node: gnatsd environment variables231620
131
Node: Access Control232310
132
Node: Overview232659
133
Node: Overall gnatsd access level233547
134
Node: gnatsd.host_access234442
135
Node: gnatsd.user_access236239
136
Ref: gnatsd.user_access-Footnote-1240671
137
Ref: gnatsd.user_access-Footnote-2240758
138
Ref: gnatsd.user_access-Footnote-3240912
139
Node: Privileged gnatsd commands241107
140
Node: Regexps242245
141
Node: dbconfig recipes247343
142
Ref: release-based support251445
143
Node: Support252591
144
Node: Index254482
7231
Node: Top824
7232
Node: Introduction2803
7233
Node: Paradigm3904
7234
Node: Flowchart8894
7235
Node: States11061
7236
Node: Fields12633
7237
Node: Field datatypes reference15305
7238
Node: Mail header fields16300
7239
Node: Problem Report fields17795
7240
Node: GNATS user tools27193
7241
Node: Environment28316
7242
Node: send-pr29167
7243
Node: send-pr from the shell29912
7244
Node: send-pr in Emacs32172
7245
Ref: send-pr in Emacs-Footnote-132850
7246
Node: PR template32966
7247
Node: Submitting via e-mail38301
7248
Node: Helpful hints39386
7249
Node: edit-pr42488
7250
Node: edit-pr from the shell44853
7251
Node: follow-up via email46894
7252
Node: query-pr48842
7253
Node: Invoking query-pr50321
7254
Node: Formatting query-pr output59526
7255
Node: Query expressions62056
7256
Node: Example queries66361
7257
Node: Emacs67416
7258
Node: Emacs viewing68874
7259
Node: Emacs querying69415
7260
Node: Emacs submitting71356
7261
Node: Emacs editing72398
7262
Node: Emacs editing buffer73035
7263
Node: Emacs and databases75614
7264
Node: dbconfig mode76625
7265
Node: Other Emacs commands77107
7266
Node: Emacs customization78034
7267
Node: Installation78295
7268
Node: Configure and make81248
7269
Node: Installing utils87733
7270
Node: Setting up the default database89729
7271
Ref: Setting up the default database-Footnote-192063
7272
Node: Setting up periodic jobs92199
7273
Node: Aliases93345
7274
Node: Installing the daemon95754
7275
Node: Installing tools98798
7276
Node: Upgrading104350
7277
Node: Management112628
7278
Node: GNATS configuration116672
7279
Node: databases file120943
7280
Node: dbconfig file123039
7281
Node: Overall database configuration125274
7282
Node: Individual field configuration128545
7283
Node: Field datatypes132785
7284
Ref: administrative files135772
7285
Node: Edit controls138854
7286
Node: Named query definitions141331
7287
Node: Audit-trail formats142437
7288
Node: Outgoing email formats144143
7289
Node: Index file description150683
7290
Node: Initial PR input fields152046
7291
Node: Other config files152786
7292
Node: categories file153104
7293
Node: responsible file156394
7294
Node: submitters file157781
7295
Node: states file160786
7296
Node: addresses file163710
7297
Node: classes file165615
7298
Node: send-pr.conf file166557
7299
Node: Admin files168953
7300
Node: index file169396
7301
Node: current file170820
7302
Node: Admin utils171084
7303
Node: mkdb171665
7304
Node: mkcat172278
7305
Node: rmcat172937
7306
Node: gen-index173744
7307
Node: check-db175362
7308
Node: gnats-pwconv176693
7309
Node: Internal utils177830
7310
Node: queue-pr178398
7311
Node: file-pr180373
7312
Node: at-pr183438
7313
Node: pr-edit185053
7314
Ref: pr-edit-Footnote-1191954
7315
Node: diff-prs192048
7316
Node: pr-age192452
7317
Node: Locations193079
7318
Node: prefix193520
7319
Node: exec-prefix194258
7320
Node: gnats-adm196745
7321
Node: defaults197531
7322
Node: gnatsd201912
7323
Node: Description of gnatsd202389
7324
Node: gnatsd options203699
7325
Node: gnatsd command protocol205397
7326
Node: gnatsd commands209683
7327
Node: gnatsd environment variables232509
7328
Node: Access Control233204
7329
Node: Overview233575
7330
Node: Overall gnatsd access level234468
7331
Node: gnatsd.host_access235371
7332
Node: gnatsd.user_access237173
7333
Ref: gnatsd.user_access-Footnote-1241609
7334
Ref: gnatsd.user_access-Footnote-2241696
7335
Ref: gnatsd.user_access-Footnote-3241850
7336
Node: Privileged gnatsd commands242045
7337
Node: Regexps243189
7338
Node: dbconfig recipes248306
7339
Ref: release-based support252418
7340
Node: Support253561
7341
Node: Index255470
145
7342
146
7343
End Tag Table
Loggerhead is a web-based interface for Breezy
Version: 2.0.1