1
This is gnats.info, produced by makeinfo version 4.2 from gnats.texi.
4
* Keeping Track: (gnats). GNU Problem Report Management System
7
Copyright (C) 2003 Milan Zamazal Copyright (C) 1993, 1995, 2001,
8
2003 Free Software Foundation, Inc.
10
Permission is granted to make and distribute verbatim copies of this
11
manual provided the copyright notice and this permission notice are
12
preserved on all copies.
14
Permission is granted to copy and distribute modified versions of
15
this manual under the conditions for verbatim copying, provided also
16
that the entire resulting derived work is distributed under the terms
17
of a permission notice identical to this one.
19
Permission is granted to copy and distribute translations of this
20
manual into another language, under the above conditions for modified
24
File: gnats.info, Node: Invoking query-pr, Next: Formatting query-pr output, Up: query-pr
29
From the shell, simply type `query-pr', followed by any search
30
parameters you wish to exercise. From Emacs, type `M-x query-pr'.
31
`query-pr' prompts you for search parameters in the minibuffer.
33
`query-pr' can also be accessed by electronic mail, if your version
34
of GNATS is configured for this. To use this feature, simply send mail
35
to the address `query-pr@YOUR-SITE' with command line arguments or
36
options in the `Subject' line of the mail header. GNATS replies to
37
your mail with the results of your query. The default settings for the
38
`query-pr' mail server are
40
--restricted --state="open|analyzed|feedback|suspended"
42
To override the `--state' parameter, specify `--state=STATE' in the
43
`Subject' line of the mail header. You can not query on confidential
44
Problem Reports by mail.
46
The usage for `query-pr' is:
48
query-pr [--debug | -D] [--help | -h] [--version | -V]
49
[--output FILE | -o FILE] [--list-databases]
50
[--list-fields] [--list-input-fields]
51
[--responsible-address NAME] [--field-type FIELD]
52
[--field-description FIELD]
54
[--adm-field FIELD] [--adm-subfield SUBFIELD]
56
[--valid-values FIELD]
57
[--format FORMAT | -f FORMAT]
58
[--full | -F] [--summary | -q]
59
[--database DATABASE | -d DATABASE] [--and | -&]
60
[--or | -|] [--expr EXPR] [PR Number]
62
Non-network-mode options:
64
[--print-sh-vars] [--print-directory-for-database]
66
Network-mode-only options:
68
[--host HOST | -H HOST] [--port PORT]
69
[--user USER | -v USER] [--passwd PASSWD | -w PASSWD]
73
[--list-categories | -j] [--list-states | -T]
74
[--list-responsible | -k] [--list-submitters | -l]
75
[--category CATEGORY | -c CATEGORY]
76
[--synopsis SYNOPSIS | -y SYNOPSIS]
77
[--confidential CONFIDENTIAL | -C CONFIDENTIAL]
78
[--multitext MULTITEXT | -m MULTITEXT]
79
[--originator ORIGINATOR | -O ORIGINATOR]
80
[--release RELEASE | -A RELEASE]
81
[--class CLASS | -L CLASS] [--cases CASES | -E CASES]
82
[--quarter QUARTER | -Q QUARTER]
83
[--keywords KEYWORDS | -K KEYWORDS]
84
[--priority PRIORITY | -p PRIORITY]
85
[--responsible RESPONSIBLE | -r RESPONSIBLE]
86
[--restricted | -R] [--severity SEVERITY | -e SEVERITY]
87
[--skip-closed | -x] [--sql | -i] [--sql2 | -I]
88
[--state STATE | -s STATE]
89
[--submitter SUBMITTER | -S SUBMITTER]
90
[--text TEXT | -t TEXT]
91
[--required-before DATE | -u DATE]
92
[--required-after DATE | -U DATE]
93
[--arrived-before DATE | -b DATE]
94
[--arrived-after DATE | -a DATE]
95
[--modified-before DATE | -B DATE]
96
[--modified-after DATE | -M DATE]
97
[--closed-before DATE | -z DATE]
98
[--closed-after DATE | -Z DATE]
100
The options have the following meaning:
102
Prints a help message.
105
Displays the program version to stdout.
107
`--output FILE, -o FILE'
108
The results of the query will be placed in this file.
110
`--database DATABASE, -d DATABASE'
111
Specifies the database to be used for the query. If no database is
112
specified, the database named default is assumed. (This option
113
overrides the database specified in the `GNATSDB' environment
114
variable; see *Note Environment:: for more information.)
116
`--list-categories, -j'
117
Lists the available PR categories for the selected database.
120
Lists the valid PR states for PRs in this database.
122
`--list-responsible, -k'
123
Lists the users that appear in the database's responsible list.
125
`--list-submitters, -l'
126
Lists the valid submitters for this database.
128
The previous -list-* options are deprecated and may be removed in
129
future releases of GNATS; their functionality can be replaced with
131
query-pr --valid-values FIELD
133
where FIELD is one of `Category', `Class', `Responsible',
134
`Submitter-Id', or `State'.
137
Lists the known databases.
140
Lists the entire set of field names for PRs in the selected
143
`--list-input-fields'
144
Lists the fields that should be provided when creating a new PR
145
for the currently-specified database. The fields are listed in an
146
order that would make sense when used in a template or form.
149
Returns the data type contained in PR field FIELD. The current
150
set of data types includes `text', `multitext', `enum',
151
`multienum', `enumerated-in-file', `multi-enumerated-in-file',
152
`date' and `integer'.
154
`--field-description FIELD'
155
Returns a human-readable description of the intended purpose of
158
`--field-flags FIELD'
159
Returns the flags set for the field in the `dbconfig' file
160
associated with the database, such as `textsearch' and `readonly'.
161
*Note Individual field configuration::.
164
Used together with the `--adm-key' option, this returns a record
165
from the administrative file (if any) associated with the field.
166
For more material on administrative files, see *Note Enumerated
167
field administrative files: administrative files.
169
`--adm-subfield SUBFIELD'
170
Used together with the `--adm-field' and `--adm-key' options, this
171
returns the contents of a particular subfield from the record
172
specified by `--adm-field' and `--adm-key'. Subfields are treated
173
in *Note Enumerated field administrative files: administrative
177
Used together with `--adm-field' to select a record from the
178
administrative file associated with the field specified by
179
`--adm-field'. *Note Enumerated field administrative files:
180
administrative files.
182
`--valid-values FIELD'
183
For fields of type `enum', a list of valid values (one per line) is
184
returned. Otherwise, a regular expression is returned that
185
describes the legal values in FIELD.
187
`--responsible-address NAME'
188
The mail address of NAME is returned; NAME is assumed to be a name
189
either appearing in the database's responsible list, or is
190
otherwise a user on the system.
193
A set of `/bin/sh' variables is returned that describe the selected
194
database. They include:
197
The name of the currently-selected database.
200
Set to 1 if the selected database is valid.
203
The directory where the database contents are stored.
206
Set to 1 if debug mode has been enabled for the database.
209
The default category for PRs in the database.
212
The default state for PRs in the database.
214
`--print-server-addr'
215
Prints the information about a remote server database in the format
216
suitable for the `GNATSDB' environment variable. This option
217
works only in the network mode.
219
`--print-directory-for-database'
220
Returns the directory where the selected database is located.
222
`--format FORMAT, -f FORMAT'
223
Used to specify the format of the output PRs, See *Note Formatting
224
query-pr output:: for a complete description.
227
When printing PRs, the entre PR is displayed. This is exactly
230
query-pr --format full
233
When printing PRs, a summary format is used. This is exactly
236
query-pr --format SUMMARY
239
Enables debugging output for network queries.
241
`--host HOST, -H HOST'
242
Specifies the hostname of the gnatsd server to communicate with.
243
This overrides the value in the `GNATSDB' environment variable.
246
Specifies the port number of the gnatsd server to communicate with.
247
This overrides the value in the `GNATSDB' environment variable.
249
`--user USER, -v USER'
250
Specifies the username to login with when connecting to the gnatsd
251
server. This overrides the value in the `GNATSDB' environment
254
`--passwd PASSWD, -w PASSWD'
255
Specifies the password to login with when connecting to the gnatsd
256
server. This overrides the value in the `GNATSDB' environment
259
`--and, -&, --or, -|'
260
These options are used when connecting multiple query operators
261
together. They specify whether the previous and subsequent
262
options are to be logically ANDed or logically ORed.
265
Specifies a query expression to use when searching for PRs. *Note
268
The remaining deprecated options are not described here, since their
269
use is fairly obvious and their functionality is completely replaced by
270
the use of the `--expr' option.
273
File: gnats.info, Node: Formatting query-pr output, Next: Query expressions, Prev: Invoking query-pr, Up: query-pr
275
Formatting `query-pr' output
276
----------------------------
278
Printing formats for PRs are in one of three forms:
281
This is a named format which is described by the database
282
(specifically, these formats are described in the `dbconfig' file
283
associated with the database). The default configuration contains
284
five such formats: `standard', `full', `summary', `sql', and
287
The first three are the ones most commonly used when performing
288
queries. standard is the format used by default if no other
291
Use of the latter two are discouraged; they are merely kept for
292
historical purposes. Other named formats may have been added by
293
the database administrator.
296
A single field name may appear here. Only the contents of this
297
field will be displayed.
299
'"PRINTF STRING" FIELDNAME FIELDNAME ...'
300
This provides a very flexible mechanism for formatting PR output.
301
(The formatting is identical to that provided by the named formats
302
described by the database configuration, *Note Named query
303
definitions::. The PRINTF STRING can contain the following %
306
`%[positionalspecifiers]s': Prints the field as a string. The
307
positional specifiers are similar to those of printf, as +, - and
308
digit qualifiers can be used to force a particular alignment of
311
`%[positionalspecifiers]S': Similar to `%s', except that the field
312
contents are terminated at the first space character.
314
`%[positionalspecifiers]d': Similar to `%s', except that the field
315
contents are written as a numeric value. For integer fields, the
316
value is written as a number. For enumerated fields, the field is
317
converted into a numeric equivalent (i.e. if the field can have two
318
possible values, the result will be either 1 or 2). For date
319
fields, the value is written as seconds since Jan 1, 1970.
321
`%F': The field is written as it would appear within a PR, complete
324
`%D': For date fields, the date is written in a standard GNATS
327
`%Q': For date fields, the date is written in an arbitrary "SQL"
330
An example formatted query looks as follows (note that the whole
331
format specification should be quoted):
333
query-pr --format '"%s, %s" Synopsis State'
336
File: gnats.info, Node: Query expressions, Next: Example queries, Prev: Formatting query-pr output, Up: query-pr
341
Query expressions are used to select specific PRs based on their field
342
contents. The general form is
344
fieldname|"value" operator fieldname|"value" [booleanop ...]
346
VALUE is a literal string or regular expression; it must be
347
surrounded by double quotes, otherwise it is interpreted as a fieldname.
349
FIELDNAME is the name of a field in the PR.
354
The value of the left-hand side of the expression must exactly
355
match the regular expression on the right-hand side of the
356
expression. *Note Querying using regular expressions: Regexps.
359
Some portion of the left-hand side of the expression must match the
360
regular expression on the right-hand side.
363
The value of the left-hand side must be equal to the value on the
364
right-hand side of the expression.
366
The equality of two values depends on what type of data is stored
367
in the field(s) being queried. For example, when querying a field
368
containing integer values, literal strings are interpreted as
369
integers. The query expression
377
as the leading zero is ignored. If the values were treated as
378
strings instead of integers, then the two comparisons would return
382
The not-equal operator. Produces the opposite result of the ==
386
The left-hand side must have a value less than or greater than the
387
right-hand side. Comparisons are done depending on the type of
388
data being queried; in particular, integer fields and dates use a
389
numeric comparison, and enumerated fields are ordered depending on
390
the numeric equivalent of their enumerated values.
392
BOOLEANOP is either `|' (logical or), or `&' (logical and). The
395
Category="baz" | Responsible="blee"
397
selects all PRs with a Category field of `baz' or a Responsible field
400
The not operator `!' may be used to negate a test:
404
searches for PRs where the category is not equal to the regular
407
Parentheses may be used to force a particular interpretation of the
410
!(Category="foo" & Submitter-Id="blaz")
412
skips PRs where the Category field is equal to `foo' and the
413
Submitter-Id field is equal to `blaz'. Parentheses may be nested to
416
Fieldnames can be specified in several ways. The simplest and most
417
obvious is just a name:
421
which checks the value of the category field for the value FOO.
423
A fieldname qualifier may be prepended to the name of the field; a
424
colon is used to separate the qualifier from the name. To refer
425
directly to a builtin field name:
429
In this case, `Number' is interpreted as the builtin name of the
430
field to check. (This is useful if the fields have been renamed. For
431
further discussion of builtin field names, see *Note The `dbconfig'
434
To scan all fields of a particular type, the FIELDTYPE qualifier may
439
This searches all text fields for the regular expression `bar'.
441
Note that it is not required that the right-hand side of the
442
expression be a literal string. To query all PRs where the PR has been
443
modified since it was closed, the expression
445
Last-Modified != Closed-Date
447
will work; for each PR, it compares the value of its Last-Modified field
448
against its Closed-Date field, and returns those PRs where the values
449
differ. However, this query will also return all PRs with empty
450
Last-Modified or Closed-Date fields. To further narrow the search:
452
Last-Modified != Closed-Date & Last-Modified != "" & Closed-Date != ""
454
In general, comparing fields of two different types (an integer field
455
against a date field, for example) will probably not do what you want.
457
Also, a field specifier may be followed by the name of a subfield in
460
State[type] != "closed"
464
builtin:State[type] != "closed"
466
Subfields are further discussed in *Note The `dbconfig' file: dbconfig
470
File: gnats.info, Node: Example queries, Prev: Query expressions, Up: query-pr
475
The following simple query:
477
query-pr --expr 'Category~"rats" & State~"analyzed"
478
& Responsible~"fred"'
480
yields all PRs in the database which contain the field values:
482
>Category: rats _and_
483
>Responsible: fred _and_
488
query-pr --expr 'State~"open|analyzed"'
490
yields all PRs in the database whose `State' values match either `open'
491
or `analyzed' (*note Querying using regular expressions: Regexps..
492
This search is useful as a daily report that lists all Problem Reports
493
which require attention.
497
query-pr --expr 'fieldtype:Text="The quick.*brown fox"'
499
yields all PRs whose TEXT fields contain the text `The quick' followed
500
by `brown fox' within the same field. *Note Querying using regular
501
expressions: Regexps, which also contains further useful examples of
505
File: gnats.info, Node: Emacs, Prev: query-pr, Up: GNATS user tools
507
The Emacs interface to GNATS
508
============================
510
Emacs interface to GNATS provides basic access to GNATS databases,
511
i.e. sending, editing, and querying Problem Reports. It also defines a
512
simple major mode for editing `dbconfig' files.
514
This section provides an overview of using GNATS with Emacs. It
515
does not describe the use of Emacs itself, for detailed instructions on
516
using Emacs, see *Note Top: (emacs)Top. For installation instructions
517
of the GNATS Emacs mode, see *Note Installing utils::.
519
Please note the Emacs interface was completely rewritten between
520
GNATS 3 and GNATS 4. It now uses `gnatsd', *Note gnatsd::, exclusively
521
for its operations and uses modern Emacs features like faces. Its
522
features are not complete though, you can send your suggestions and
523
patches to the appropriate GNATS mailing list, *Note Support::.
527
* Emacs viewing:: Viewing PRs by their number.
528
* Emacs querying:: Querying the database.
529
* Emacs submitting:: Submitting new PRs.
530
* Emacs editing:: Editing PRs.
531
* Emacs editing buffer:: The editing buffer.
532
* Emacs and databases:: Changing the working database.
533
* dbconfig mode:: Major mode for dbconfig files.
534
* Other Emacs commands:: Miscellaneous commands.
535
* Emacs customization:: Customizing the Emacs interface.
538
File: gnats.info, Node: Emacs viewing, Next: Emacs querying, Up: Emacs
540
Viewing Problem Reports
541
-----------------------
543
To view a particular Problem Report, use the command `M-x view-pr'.
544
It asks for a Problem Report number and displays that Problem Report.
546
The displayed buffer is put in the view mode, *Note Misc File Ops:
547
(emacs)Misc File Ops. If you decide to edit the displayed Problem
548
Report, use the command `e' (`gnats-view-edit-pr').
550
`gnats-view-mode-hook'
551
Hook run when `gnats-view-mode' is entered.
554
File: gnats.info, Node: Emacs querying, Next: Emacs submitting, Prev: Emacs viewing, Up: Emacs
556
Querying Problem Reports
557
------------------------
559
Querying the database is performed by the `M-x query-pr' command.
560
The command prompts for the query expression, *Note Query expressions::,
561
and displays a buffer with the list of the matching Problem Reports.
563
The list of the Problem Reports is displayed in the `summary' query
564
format, *Note Formatting query-pr output::. Currently, the display
565
format cannot be changed and it must output each Problem Report's
566
number in the first column.
568
The Problem Report list buffer is put in the view mode, *Note Misc
569
File Ops: (emacs)Misc File Ops. You can use most of the standard view
570
mode commands in it. Additionally, the following special commands are
576
View the current Problem Report (`gnats-query-view-pr'), *Note
580
Edit the current Problem Report (`gnats-query-edit-pr'), *Note
584
Update the Problem Report list (`gnats-query-reread'). The last
585
performed query is executed again and the buffer is filled with the
589
Perform new query (`query-pr').
592
Send new Problem Report (`send-pr'), *Note Emacs submitting::.
595
Change the current database (`gnats-change-database'), *Note Emacs
599
Bury buffer, the buffer is put at the end of the list of all
600
buffers. This is useful for quick escape of the buffer, without
603
If the value of the variable GNATS-QUERY-REVERSE-LISTING is
604
non-`nil', the listing appears in the reversed order, i.e. with the
605
Problem Reports of the highest number first, in the buffer.
607
Similarly to other GNATS Emacs modes, there is a hook available for
608
the Problem Report list.
610
`gnats-query-mode-hook'
611
Hook run when `gnats-query-mode' is entered.
614
File: gnats.info, Node: Emacs submitting, Next: Emacs editing, Prev: Emacs querying, Up: Emacs
616
Submitting new Problem Reports
617
------------------------------
619
You can submit new Problem Reports with the command `M-x send-pr'.
620
The command puts you to the problem editing buffer, *Note Emacs
621
editing::. The buffer is prefilled with the initial report fields and
622
their default values, if defined. You can use the usual Problem Report
623
editing commands, *Note Emacs editing::. When you have filled in all
624
the fields, you can send the Problem Report by presing `C-c C-c'.
626
If you run `M-x send-pr' with a prefix argument, it runs the
627
`gnats-change-database' command before putting you to the editing
628
buffer, *Note Emacs and databases::.
630
You can set the following variables to get some fields pre-filled:
632
GNATS-DEFAULT-ORGANIZATION
633
Default value of the `Organization' field used in new Problem
636
GNATS-DEFAULT-SUBMITTER
637
Default value of the `Submitter-Id' field used in new Problem
641
File: gnats.info, Node: Emacs editing, Next: Emacs editing buffer, Prev: Emacs submitting, Up: Emacs
643
Editing Problem Reports
644
-----------------------
646
To edit a particular Problem Report, use the command `M-x edit-pr'.
647
It asks for a Problem Report number and puts the given Problem Report
648
in the editing buffer. *Note Emacs editing buffer::, for information
649
how to edit the Problem Report in the buffer and how to submit your
652
Note you can also start editing of a selected Problem Report directly
653
from within the viewing buffer, *Note Emacs viewing::, or the query
654
result buffer, *Note Emacs querying::.
657
File: gnats.info, Node: Emacs editing buffer, Next: Emacs and databases, Prev: Emacs editing, Up: Emacs
659
The Problem Report editing buffer
660
---------------------------------
662
When you invoke a Problem Report editing command, the Problem Report
663
is put into a special editing buffer. The Problem Report is formatted
664
similarly to the `query-pr -F' output, *Note Formatting query-pr
665
output::. Field identifiers are formatted as
669
with the text of the field following the identifier on the same line
670
for single-line fields or starting on the next line for multi-line
673
The Problem Report editing mode tries to prevent you from violating
674
the Problem Report format and the constraints put on the possible field
675
values. Generally, you can use usual editing commands, some of them
676
have a slightly modified behavior though. (If you encounter a very
677
strange behavior somewhere, please report it as a bug, *Note Support::.)
679
You can move between fields easily by pressing the `TAB'
680
(`gnats-next-field') or `M-TAB' (`gnats-previous-field') keys.
682
The field tags are read-only and you cannot edit them nor delete
683
them. If you want to "remove" a field, just make its value empty.
685
Editing a field value depends on the type of the edited field, *Note
686
Field datatypes::. For text fields, you can edit the value directly,
687
assuming you preserve the rule about single-line and multi-line values
690
For enumerated fields, you cannot edit the value directly. You can
691
choose it from the list of the allowed values, either from the menu
692
popped up by pressing the middle mouse button or from within minibuffer
693
by pressing any key on the field's value. If the pressed key matches
694
any of the allowed field values, that value is put as the default value
695
after the minibuffer prompt. You can also cycle through the allowed
696
field values directly in the editing buffer using the `SPACE' key.
697
Enumerated field values are marked by a special face to not confuse
698
you; you must have enabled font lock mode to benefit from this feature,
699
*Note Font Lock: (emacs)Font Lock.
701
Some field values can be read-only, you cannot edit them at all.
703
Once you have edited the Problem Report as needed, you can send it to
704
the server with the `C-c C-c' command (`gnats-apply-or-submit').
705
Successful submission is reported by a message and the buffer
706
modification flag in mode line is cleared. Then you can either kill
707
the buffer or continue with further modifications.
709
`gnats-edit-mode-hook'
710
Hook run when `gnats-edit-mode' is entered.
713
File: gnats.info, Node: Emacs and databases, Next: dbconfig mode, Prev: Emacs editing buffer, Up: Emacs
715
Changing the database
716
---------------------
718
By default, the Emacs interface connects to the default database,
719
*Note databases file::. If you want to connect to another database, use
720
the command `M-x gnats-change-database'. It will ask you for the
721
database name to use, server and port it can be accessed on, and your
724
If you want to use the `gnatsd' command, *Note gnatsd::, directly,
725
without connecting to a remote server or the localhost connection port,
726
provide your local file system full path to `gnatsd' as the server
727
name. Port number does not matter in this case.
729
If the database requires a password to allow you the access to it,
730
you are prompted for the password the first time you connect to the
731
database. If you provide an invalid password, you cannot connect to
732
the database anymore and you have to run the `M-x
733
gnats-change-database' command again.
736
File: gnats.info, Node: dbconfig mode, Next: Other Emacs commands, Prev: Emacs and databases, Up: Emacs
741
The Emacs interface defines a simple major mode
742
`gnats-dbconfig-mode' for editing `dbconfig' files, *Note dbconfig
743
file::. It defines basic mode attributes like character syntax and
744
font lock keywords, it does not define any special commands now.
746
`gnats-dbconfig-mode-hook'
747
Hook run when `gnats-dbconfig-mode' is entered.
750
File: gnats.info, Node: Other Emacs commands, Next: Emacs customization, Prev: dbconfig mode, Up: Emacs
756
Ask for a Problem Report number and unlock that Problem Report.
757
This function is useful if connection to a GNATS server was
758
interrupted during an editing operation and further modifications
759
of the Problem Report are blocked by a stealth lock.
761
`M-x unlock-database'
762
Unlock the whole GNATS database. This function is useful in
763
situations similar to when `unlock-pr' is used.
765
`M-x gnats-show-connection'
766
Show the connection buffer associated with the current buffer. You
767
can view the Emacs communication with GNATSD in it. This is
768
useful when something strange happens during the communication with
769
the server, e.g. when sending a Problem Report with `C-c C-c' from
770
a Problem Report editing buffer.
773
File: gnats.info, Node: Emacs customization, Prev: Other Emacs commands, Up: Emacs
778
All the user variables can be customized in the customization group
779
`gnats', *Note Easy customization: (emacs)Easy customization.
782
File: gnats.info, Node: Installation, Next: Management, Prev: GNATS user tools, Up: Top
787
See also *Note Where the tools and utilities reside: Locations.
789
There are several steps you need to follow to fully configure and
790
install GNATS on your system. You need `root' access in order to
791
create a new account for `gnats' and to install the GNATS utilities.
792
You may need `root' access on some systems in order to set up mail
793
aliases and to allow this new account access to `cron' and `at'.
795
If you are updating an older version of GNATS rather than installing
796
from scratch, see *Note Upgrading from older versions: Upgrading.
798
GNATS installation relies on two other freely available software
799
packages, which should be installed before you go on to configure and
800
build GNATS. These are GNU `make' and `Texinfo' (version 4.2 or
801
higher). Both are available from the GNU FTP site at
804
To build and install GNATS, you must:
806
* Run `configure', with correct options if the defaults are
807
unsuitable for your site. *Note Configuring and compiling the
808
software: Configure and make. Default installation locations are
809
in *Note Where GNATS lives: Locations.
811
* Compile the GNATS programs on your system. *Note Configuring and
812
compiling the software: Configure and make.
814
* Create an initial database by using the `mkdb' command. *Note
815
Setting up the default database::.
817
* Set up periodic jobs, using cron, to handle Problem Reports
818
arriving by mail. *Note Setting up periodic jobs::.
820
* Set up mail aliases for GNATS. *Note Setting up mail aliases:
823
* Install the GNATS tools and utilities locally, and install the user
824
tools (`query-pr', `edit-pr', `send-pr') on every machine in your
825
local network. *Note Installing the user tools: Installing tools.
827
* Install the GNATS daemon `gnatsd'. *Note Installing the daemon::.
829
* If there are people outside your organization who will be
830
submitting PRs or who are supposed to be able to query and/or edit
831
PRs, you may need to instruct them to obtain and build the GNATS
832
tools `query-pr', `edit-pr' and `send-pr' for their systems.
833
However, for many sites, setting up a remote access interface to
834
GNATS, such as Gnatsweb is a better solution since this requires
835
no configuration on the remote side.
839
* Configure and make:: Configuring and compiling the software
840
* Installing utils:: Installing the utilities
841
* Setting up the default database:: Setting up the default database
842
* Setting up periodic jobs:: Setting up periodic jobs
843
* Aliases:: Setting up mail aliases
844
* Installing the daemon:: Installing the daemon
845
* Installing tools:: Installing the user tools
846
* Upgrading:: Upgrading from older versions
849
File: gnats.info, Node: Configure and make, Next: Installing utils, Up: Installation
851
Configuring and compiling the software
852
======================================
854
1. First, unpack your distribution. We provide source code in a `tar'
855
file which was compressed using `gzip'. The code can be extracted
856
into a directory UNPACKDIR using
859
gunzip gnats-4.0.tar.gz
860
tar xvf gnats-4.0.tar
862
The sources reside in a directory called `gnats-4.0' when
863
unpacked. We call this the "top level" of the source directory,
864
or "srcdir". The sources for the GNATS tools are in the
865
subdirectory `gnats-4.0/gnats/*'. Lists of files included in the
866
distribution are in each directory in the file `MANIFEST'.
868
2. As of GNATS version 4, having Emacs installed on the GNATS server
869
is no longer a requirement. If you do not have Emacs installed,
870
disregard this step altogether.
872
You may wish to alter the installation directory for the Emacs lisp
873
files. If your Emacs lisp library is not in
874
`PREFIX/share/emacs/site-lisp', edit the file
875
`SRCDIR/gnats/Makefile.in'. Change the variable `lispdir' from
876
`PREFIX/emacs/site-lisp' to the directory containing your Emacs
877
lisp library. For information on PREFIX, see *Note PREFIX: prefix.
879
3. Create an account for the `gnats' user. You can actually name this
880
user whatever you want to, as long as it is a valid username on
881
your system, but we strongly recommend that you call the user
882
`gnats'. If you do decide to give it some other name, remember to
883
use the option `--with-gnats-user' when running `configure' below.
884
Below, we will anyway refer to this user by the name `gnats'.
886
This user must have an entry in the file `/etc/passwd'. As for
887
ordinary users, create a standard home directory for the `gnats'
888
user. The default `PATH' for this user should contain
889
`EXEC-PREFIX/bin' and `EXEC-PREFIX/libexec/gnats'. The
890
EXEC-PREFIX value is configurable with the `--exec-prefix'
891
configure option described below, but for standard installations,
892
these two directories correspond to `/usr/local/bin' and
893
`/usr/local/libexec/gnats'.
895
4. Run `configure'. You can nearly always run `configure' with the
900
and the "Right Thing" happens:
902
* GNATS is configured in the same directory you unpacked it in;
904
* when built, GNATS runs on the machine you're building it on;
906
* when installed, files are installed under `/usr/local' (*note
907
Where GNATS lives: Locations.).
909
* all GNATS utilities operate on the "default database", assumed
910
to be named _default_ and to be located in
911
`/usr/local/com/default', unless you invoke the utilities with
912
`-d' DATABASENAME or `--directory='DATABASENAME, or set the
913
GNATSDB environment variable to point to some other database.
915
The most common options to `configure' are listed below:
917
configure [ --prefix=PREFIX ]
918
[ --exec-prefix=EXEC-PREFIX ]
919
[ --with-gnats-service=SERVICE-NAME ]
920
[ --with-gnats-user=USERNAME ]
921
[ --with-gnatsd-user-access-file=PATH ]
922
[ --with-gnatsd-host-access-file=PATH ]
923
[ --with-gnats-dblist-file=PATH ]
924
[ --with-gnats-default-db=PATH ]
925
[ --with-kerberos ] [ --with-krb4 ]
929
All host-independent programs and files are to be installed
930
under PREFIX. (Host-dependent programs and files are also
931
installed in PREFIX by default.) The default for PREFIX is
932
`/usr/local'. *Note Where GNATS lives: Locations.
934
`--exec-prefix=EXEC-PREFIX'
935
All host-dependent programs and files are to be installed
936
under EXEC-PREFIX. The default for EXEC-PREFIX is PREFIX.
937
*Note Where GNATS lives: Locations.
939
`--with-gnats-service=SERVICE-NAME'
940
Set SERVICE-NAME to be the GNATS network service. Default
943
`--with-gnats-user=USERNAME'
944
Set USERNAME to be the user name for GNATS. Default username
947
`--with-gnatsd-user-access-file=PATH'
948
Set global (across all databases) gnatsd user access file to
949
PATH. Default is `/USR/LOCAL/ETC/GNATS/GNATSD.USER_ACCESS'.
950
Per-database user access permissions are set in a
951
`gnatsd.user_access' file in the `gnats-adm' subdirectory of
954
`--with-gnatsd-host-access-file=PATH'
955
Set global (across all databases) gnatsd host access file to
956
PATH. Default is `/usr/local/etc/gnats/gnatsd_host.access'.
957
There is currently no way to specify host access permissions
958
on a per-database basis.
960
`--with-gnats-dblist-file=PATH'
961
Specify the file containing the list of databases.
963
Default is `PREFIX/etc/gnats/databases'.
965
`--with-gnats-default-db=PATH'
966
Specify the default database to use when GNATS tools are
967
invoked without the `-d' or `--databasename' option, and when
968
the GNATSDB envrionment variable hasn't been set. Default is
969
`/PREFIX/com/gnatsdb'.
972
Include code for Kerberos authentication.
978
Give verbose output while `configure' runs.
980
`configure' supports several more options which allow you to
981
specify in great detail where files are installed. For a complete
982
list of options, run `./configure --help' in the source directory.
984
You can build GNATS in a different directory (OBJDIR) from the
985
source code by calling the `configure' program from the new
992
By default, `make' compiles the programs in the same directory as
993
the sources (SRCDIR).
995
5. Make sure you have GNU `make', then run
999
from the directory where `configure' created a `Makefile' (this is
1000
OBJDIR if you used it, otherwise SRCDIR.) These targets indicate:
1003
Compile all programs
1006
Create `info' files using `makeinfo'.
1009
File: gnats.info, Node: Installing utils, Next: Setting up the default database, Prev: Configure and make, Up: Installation
1011
Installing the utilities
1012
========================
1014
The following steps are necessary for a complete installation. You
1015
may need `root' access for these.
1017
1. Install the utilities by invoking
1019
make install install-info
1021
These targets indicate:
1024
Installs all programs into their configured locations (*note
1025
Where GNATS lives: Locations.).
1028
Installs `info' files into their configured locations (*note
1029
Where GNATS lives: Locations.).
1031
After you have installed GNATS, you can remove the object files
1036
2. If you do not have Emacs installed on your GNATS server, this step
1039
Place the following lines in the file `default.el' in your Emacs
1040
lisp library, or instruct your local responsible parties to place
1041
the lines in their `.emacs':
1043
(autoload 'send-pr "gnats"
1044
"Command to create and send a problem report." t)
1045
(autoload 'edit-pr "gnats"
1046
"Command to edit a problem report." t)
1047
(autoload 'view-pr "gnats"
1048
"Command to view a problem report." t)
1049
(autoload 'query-pr "gnats"
1050
"Command to query information about problem reports." t)
1051
(autoload 'unlock-pr "gnats"
1052
"Unlock a problem report." t)
1053
(autoload 'gnats-dbconfig-mode "gnats"
1054
"Major mode for editing the `dbconfig' GNATS configuration file." t)
1055
(add-to-list 'auto-mode-alist '("\\<dbconfig$" . gnats-dbconfig-mode))
1057
3. If you want people who are logged into the GNATS server itself to
1058
be able to use the `send-pr' tool to submit problem reports, you
1059
need to create a configuration file for `send-pr' on the server.
1060
*Note The send-pr.conf configuration file: send-pr.conf file.
1064
File: gnats.info, Node: Setting up the default database, Next: Setting up periodic jobs, Prev: Installing utils, Up: Installation
1066
Installing the default database
1067
===============================
1069
For the following steps, log in as the user `gnats'.
1071
We are now going to initialize the default GNATS database. Run the
1076
This creates a database named `default', with all its data stored
1077
below the directory `PREFIX/com/gnatsdb', in a default installation
1078
this corresponds to `/usr/local/com/gnatsdb'. If you specified the
1079
`--with-gnats-default-db' option when running configure, the default
1080
database will be created under the directory you specified instead.
1081
`mkdb' creates the database directory itself, together with three
1082
different subdirectories(1):
1084
* A directory for the mandatory GNATS category PENDING.
1086
* A `gnats-queue' directory for queueing new messages to GNATS
1087
before they are processed by `file-pr'.
1089
* The administrative directory `gnats-adm'. This directory is
1090
populated with default configuration files from the
1091
`PREFIX/etc/gnats/defaults' directory.
1093
The next configuration step is to edit the default files copied to
1094
the database's `gnats-adm' directory by `mkdb'.
1096
The default `dbconfig' file installed by `mkdb' provides a good
1097
basis for many GNATS databases. The default file causes similar
1098
behaviour to the 3.x versions of GNATS. However, even if this might be
1099
precisely what you want, you should still go through the file and check
1100
that the default settings suit your needs. *Note The `dbconfig' file:
1103
Then edit the files `categories', `responsible', and `submitters' in
1104
the `gnats-adm' directory (*note Other database-specific config files:
1105
Other config files.) to reflect your local needs. For special
1106
configurations, you may also have to edit the `states' and `classes'
1109
If you used the `--with-gnats-default-db' option in the pre-build
1110
configure to change the location of the default database, you need to
1111
edit the `databases' config file, see *Note The `databases file':
1112
databases file. This file is by default located in the
1113
`PREFIX/etc/gnats' directory, but may have been changed by the option
1114
`--with-gnats-dblist-file' option during configure.
1116
---------- Footnotes ----------
1118
(1) Upgraders from older versions of GNATS should note that category
1119
directories are now created "on-the-fly" as needed by default.
1122
File: gnats.info, Node: Setting up periodic jobs, Next: Aliases, Prev: Setting up the default database, Up: Installation
1124
Setting up periodic jobs
1125
========================
1127
Allow the new user `gnats' access to `cron' and `at'. To do this,
1128
add the name `gnats' to the files `cron.allow' and `at.allow', which
1129
normally reside in the directory `/var/spool/cron'. If these files do
1130
not exist, make sure `gnats' does not appear in either of the files
1131
`cron.deny' and `at.deny' (in the same directory). If you changed the
1132
name of the GNATS user during configure, remember to substitute as
1133
appropriate in the previous steps.
1135
Create a `crontab' entry that periodically runs the program
1136
`queue-pr' with the `--run' option (*note `queue-pr': queue-pr.). For
1137
example, to run `queue-pr --run' every ten minutes, create a file called
1138
`.mycron' in the home directory of the user `gnats' which contains the
1141
0,10,20,30,40,50 * * * * EXEC-PREFIX/libexec/gnats/queue-pr --run
1143
(Specify the full path name for `queue-pr'.) Then run
1147
See the `man' pages for `cron' and `crontab' for details on using
1151
File: gnats.info, Node: Aliases, Next: Installing the daemon, Prev: Setting up periodic jobs, Up: Installation
1153
Setting up mail aliases
1154
=======================
1156
The following mail aliases must be added on the machine where the
1157
GNATS server is installed. The instructions below are for Sendmail or
1158
Sendmail-like mail systems. If these instructions don't fit your
1159
system, particularly if you do not have an `aliases' file, ask your
1160
mail administrator for advice.
1162
The following aliases should be placed in the file `/etc/aliases'.
1163
Yoy may need `root' access to add these aliases:
1165
* Create an alias for the GNATS administrator. This address should
1166
point to the address of the person in charge of administrating
1169
gnats-admin: ADDRESS
1171
* Create an alias to redirect incoming Problem Reports. This alias
1172
should redirect incoming mail via a "pipe" to the program
1173
`queue-pr -q'. For example, if Problem Reports coming to your
1174
site are to arrive at the address `bugs@your.company.com', create
1175
an alias to the effect of:
1177
bugs: "| EXEC-PREFIX/libexec/gnats/queue-pr -q"
1179
This places incoming Problem Reports in the `GNATS-QUEUE'
1180
directory of your database. Remember to fill in the full path of
1181
the `queue-pr' command as appropriate for your installation.
1183
* You may also wish to forward a copy of each incoming Problem
1184
Report to a log. This can be accomplished with something like:
1186
bug-q: "| EXEC-PREFIX/libexec/gnats/queue-pr -q"
1187
bug-log: /some/path/bugs.log
1188
bugs: bug-q, bug-log
1190
This configuration archives incoming Problem Reports in the file
1191
`bug.log', and also feeds them to the program `queue-pr'.
1192
(Remember, `bug.log' needs to be world-writable, and should be
1193
pruned regularly; *note GNATS Administration: Management..) In
1194
order for the log file to protect fully against data loss in case
1195
a disk runs full, try to place it on a different disk volume than
1198
* If you want your users to be able to query the database by mail,
1199
use the following alias:
1201
query-pr: "| EXEC-PREFIX/libexec/gnats/mail-query"
1203
The `mail-query' program uses `--restricted' to search on the
1204
database, and by default only searches for PRs that aren't closed
1205
(*note Querying the database: query-pr.).
1209
File: gnats.info, Node: Installing the daemon, Next: Installing tools, Prev: Aliases, Up: Installation
1211
Installing the daemon
1212
=====================
1214
By default, the daemon and clients are set to use port 1529. Add
1217
support 1529/tcp # GNATS
1219
to your `/etc/services' file. If you want a different service name,
1220
configure GNATS with
1222
--with-gnats-service=SERVICENAME
1224
In your `inetd.conf' file, add the line
1226
support stream tcp nowait gnats /usr/local/libexec/gnats/gnatsd gnatsd
1228
adjusting the path accordingly if you used configure options to make
1229
changes to the defaults. To make `inetd' start spawning the GNATS
1230
daemon when connected on that port, send it a hangup signal (`HUP').
1232
Some operating systems have replaced `inetd' with the more modern
1233
`xinetd'. Instead of editing `inetd.conf', you should create the file
1234
`/etc/xinetd.d/support', containing something like the following:
1239
socket_type = stream
1243
server = /usr/local/libexec/gnats/gnatsd
1246
If you specified a different service name when running `configure',
1247
you need to give the file the same name as the service name, and you
1248
need to adjust the `service' line above. If the `--prefix' or
1249
`--exec-prefix' options were passed to `configure', adjust the `server'
1250
line above, and if you used the `--with-gnats-user' option, adjust the
1253
Then restart `xinetd' to make the new configuration current.
1255
If you use an Internet superserver different from `inetd' or
1256
`xinetd', please refer to its documentation for information how to
1259
At this point, you will probably want to set the access permissions
1260
of the different hosts that are going to be accessing your databases.
1261
The access permissions can currently only be set on a global scale
1262
(that is, across all the databases on a GNATS server). The location
1263
and name of the global host access configuration file can be set during
1264
the pre-build configure as shown above, but by default the file is
1265
`/usr/local/etc/gnats/gnatsd_host.access'. It lists the hosts allowed
1266
to access your server, and what their default access levels are. Each
1267
line in the file denotes one server, or one part of a network domain.
1268
There are three fields on each line, but only two are currently used.
1269
To grant all hosts from the domain SITE.COM edit access, use this line:
1273
If you run a GNATS web interface or similar tool on the same machine as
1274
the server is running on, you probably want to grant LOCALHOST edit
1279
If you are using Kerberos, the `gnatsd_host.access' file shows the
1280
sites that don't require Kerberos authentication.
1282
The third field might in the future be used for things like
1283
controlling what categories, submitter-id's PRs, etc., can be accessed
1284
from that site. Access attempts that are denied are logged to the
1285
syslog messages file (`/var/adm/messages' on many systems).
added
removed
doc/gnats.info-2
