This is gnats.info, produced by makeinfo version 4.2 from gnats.texi.

START-INFO-DIR-ENTRY
* Keeping Track: (gnats).	GNU Problem Report Management System
END-INFO-DIR-ENTRY

   Copyright (C) 2002 Milan Zamazal Copyright (C) 1993, 1995, 2001 Free
Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: gnats.info,  Node: Invoking query-pr,  Next: Formatting query-pr output,  Up: query-pr

Invoking `query-pr'
-------------------

   From the shell, simply type `query-pr', followed by any search
parameters you wish to exercise.  From Emacs, type `M-x query-pr'.
`query-pr' prompts you for search parameters in the minibuffer.

   `query-pr' can also be accessed by electronic mail, if your version
of GNATS is configured for this.  To use this feature, simply send mail
to the address `query-pr@YOUR-SITE' with command line arguments or
options in the `Subject' line of the mail header.  GNATS replies to
your mail with the results of your query.  The default settings for the
`query-pr' mail server are

     --restricted --state="open|analyzed|feedback|suspended"

To override the `--state' parameter, specify `--state=STATE' in the
`Subject' line of the mail header.  You can not query on confidential
Problem Reports by mail.

   The usage for `query-pr' is:

     query-pr [--debug | -D] [--help | -h] [--version | -V]
              [--output FILE | -o FILE] [--list-databases]
              [--list-fields] [--list-input-fields]
              [--responsible-address NAME] [--field-type FIELD]
              [--field-description FIELD]
              [--field-flags FIELD]
              [--adm-field FIELD] [--adm-subfield SUBFIELD]
              [--adm-key KEY]
              [--valid-values FIELD]
              [--format FORMAT | -f FORMAT]
              [--full | -F] [--summary | -q]
              [--database DATABASE | -d DATABASE] [--and | -&]
              [--or | -|] [--expr EXPR] [PR Number]

   Non-network-mode options:

              [--print-sh-vars] [--print-directory-for-database]

   Network-mode-only options:

              [--host HOST | -H HOST] [--port PORT]
              [--user USER | -v USER] [--passwd PASSWD | -w PASSWD]
              [--print-server-addr]

   Deprecated Options:
              [--list-categories | -j] [--list-states | -T]
              [--list-responsible | -k] [--list-submitters | -l]
              [--category CATEGORY | -c CATEGORY]
              [--synopsis SYNOPSIS | -y SYNOPSIS]
              [--confidential CONFIDENTIAL | -C CONFIDENTIAL]
              [--multitext MULTITEXT | -m MULTITEXT]
              [--originator ORIGINATOR | -O ORIGINATOR]
              [--release RELEASE | -A RELEASE]
              [--class CLASS | -L CLASS] [--cases CASES | -E CASES]
              [--quarter QUARTER | -Q QUARTER]
              [--keywords KEYWORDS | -K KEYWORDS]
              [--priority PRIORITY | -p PRIORITY]
              [--responsible RESPONSIBLE | -r RESPONSIBLE]
              [--restricted | -R] [--severity SEVERITY | -e SEVERITY]
              [--skip-closed | -x] [--sql | -i] [--sql2 | -I]
              [--state STATE | -s STATE]
              [--submitter SUBMITTER | -S SUBMITTER]
              [--text TEXT | -t TEXT]
              [--required-before DATE | -u DATE]
              [--required-after DATE | -U DATE]
              [--arrived-before DATE | -b DATE]
              [--arrived-after DATE | -a DATE]
              [--modified-before DATE | -B DATE]
              [--modified-after DATE | -M DATE]
              [--closed-before DATE | -z DATE]
              [--closed-after DATE | -Z DATE]

   The options have the following meaning:
`--help, -h'
     Prints a help message.

`--version, -V'
     Displays the program version to stdout.

`--output FILE, -o FILE'
     The results of the query will be placed in this file.

`--database DATABASE, -d DATABASE'
     Specifies the database to be used for the query.  If no database is
     specified, the database named default is assumed.  (This option
     overrides the database specified in the `GNATSDB' environment
     variable; see *Note Environment:: for more information.)

`--list-categories, -j'
     Lists the available PR categories for the selected database.

`--list-states, -T'
     Lists the valid PR states for PRs in this database.

`--list-responsible, -k'
     Lists the users that appear in the database's responsible list.

`--list-submitters, -l'
     Lists the valid submitters for this database.

   The previous -list-* options are deprecated and may be removed in
future releases of GNATS; their functionality can be replaced with

     query-pr --valid-values FIELD

where FIELD is one of `Category', `Class', `Responsible',
`Submitter-Id', or `State'.

`--list-databases'
     Lists the known databases.

`--list-fields'
     Lists the entire set of field names for PRs in the selected
     database.

`--list-input-fields'
     Lists the fields that should be provided when creating a new PR
     for the currently-specified database.  The fields are listed in an
     order that would make sense when used in a template or form.

`--field-type FIELD'
     Returns the data type contained in PR field FIELD.  The current
     set of data types includes `text', `multitext', `enum',
     `multienum', `enumerated-in-file', `multi-enumerated-in-file',
     `date' and `integer'.

`--field-description FIELD'
     Returns a human-readable description of the intended purpose of
     FIELD.

`--field-flags FIELD'
     Returns the flags set for the field in the `dbconfig' file
     associated with the database, such as `textsearch' and `readonly'.
     *Note Individual field configuration::.

`--adm-field FIELD'
     Used together with the `--adm-key' option, this returns a record
     from the administrative file (if any) associated with the field.
     For more material on administrative files, see *Note Enumerated
     field administrative files: administrative files.

`--adm-subfield SUBFIELD'
     Used together with the `--adm-field' and `--adm-key' options, this
     returns the contents of a particular subfield from the record
     specified by `--adm-field' and `--adm-key'.  Subfields are treated
     in *Note Enumerated field administrative files: administrative
     files.

`--adm-key KEY'
     Used together with `--adm-field' to select a record from the
     administrative file associated with the field specified by
     `--adm-field'.  *Note Enumerated field administrative files:
     administrative files.

`--valid-values FIELD'
     For fields of type `enum', a list of valid values (one per line) is
     returned.  Otherwise, a regular expression is returned that
     describes the legal values in FIELD.

`--responsible-address NAME'
     The mail address of NAME is returned; NAME is assumed to be a name
     either appearing in the database's responsible list, or is
     otherwise a user on the system.

`--print-sh-vars'
     A set of `/bin/sh' variables is returned that describe the selected
     database.  They include:

    `GNATSDB'
          The name of the currently-selected database.

    `GNATSDB_VALID'
          Set to 1 if the selected database is valid.

    `GNATSDBDIR'
          The directory  where  the  database  contents  are stored.

    `DEBUG_MODE'
          Set to 1 if debug mode has been  enabled  for  the database.

    `DEFAULTCATEGORY'
          The default category for PRs in the database.

    `DEFAULTSTATE'
          The default state for PRs in the database.

`--print-server-addr'
     Prints the information about a remote server database in the format
     suitable for the `GNATSDB' environment variable.  This option
     works only in the network mode.

`--print-directory-for-database'
     Returns the directory where the selected database is located.

`--format FORMAT, -f FORMAT'
     Used to specify the format of the output PRs, See *Note Formatting
     query-pr output:: for a complete description.

`--full, -F'
     When printing PRs, the entre PR is displayed.  This is exactly
     equivalent to

          query-pr --format full

`--summary, -q'
     When printing PRs, a summary format is used.  This is exactly
     equivalent to

          query-pr --format SUMMARY

`--debug, -D'
     Enables debugging output for network queries.

`--host HOST, -H HOST'
     Specifies the hostname of the gnatsd server to communicate with.
     This overrides the value in the `GNATSDB' environment variable.

`--port PORT'
     Specifies the port number of the gnatsd server to communicate with.
     This overrides the value in the `GNATSDB' environment variable.

`--user USER, -v USER'
     Specifies the username to login with when connecting to the gnatsd
     server.  This overrides the value in the `GNATSDB' environment
     variable.

`--passwd PASSWD, -w PASSWD'
     Specifies the password to login with when connecting to the gnatsd
     server.  This overrides the value in the `GNATSDB' environment
     variable.

`--and, -&, --or, -|'
     These options are used when connecting multiple query operators
     together.  They specify whether the previous and subsequent
     options are to be logically ANDed or logically ORed.

`--expr EXPR'
     Specifies a query expression to use when searching for PRs.  *Note
     Query expressions::.

   The remaining deprecated options are not described here, since their
use is fairly obvious and their functionality is completely replaced by
the use of the `--expr' option.


File: gnats.info,  Node: Formatting query-pr output,  Next: Query expressions,  Prev: Invoking query-pr,  Up: query-pr

Formatting `query-pr' output
----------------------------

   Printing formats for PRs are in one of three forms:

FORMATNAME
     This is a named format which is described by the database
     (specifically, these formats are described in the `dbconfig' file
     associated with the database).  The default configuration contains
     five such formats: `standard', `full', `summary', `sql', and
     `sql2'.

     The first three are the ones most commonly used when performing
     queries.  standard is the format used by default if no other
     format is specified.

     Use of the latter two are discouraged; they are merely kept for
     historical purposes.  Other named formats may have been added by
     the database administrator.

FIELDNAME
     A single field name may appear here.  Only the contents of this
     field will be displayed.

'"PRINTF STRING" FIELDNAME FIELDNAME ...'
     This provides a very flexible mechanism for formatting PR output.
     (The formatting is identical to that provided by the named formats
     described by the database configuration, *Note Named query
     definitions::.  The PRINTF STRING can contain the following %
     sequences:

     `%[positionalspecifiers]s': Prints the field as a string.  The
     positional specifiers are similar to those of printf, as +, - and
     digit qualifiers can be used to force a particular alignment of
     the field contents.

     `%[positionalspecifiers]S': Similar to `%s', except that the field
     contents are terminated at the first space character.

     `%[positionalspecifiers]d': Similar to `%s', except that the field
     contents are written as a numeric value.  For integer fields, the
     value is written as a number.  For enumerated fields, the field is
     converted into a numeric equivalent (i.e. if the field can have two
     possible values, the result will be either 1 or 2).  For date
     fields, the value is written as seconds since Jan 1, 1970.

     `%F': The field is written as it would appear within a PR, complete
     with field header.

     `%D': For date fields, the date is written in a standard GNATS
     format.

     `%Q': For date fields, the date is written in an arbitrary "SQL"
     format.

   An example formatted query looks as follows (note that the whole
format specification should be quoted):

     query-pr --format '"%s, %s" Synopsis State'


File: gnats.info,  Node: Query expressions,  Next: Example queries,  Prev: Formatting query-pr output,  Up: query-pr

Query expressions
-----------------

Query expressions are used to select specific PRs based on their field
contents.  The general form is

     fieldname|"value" operator fieldname|"value" [booleanop ...]

   VALUE is a literal string or regular expression; it must be
surrounded by double quotes, otherwise it is interpreted as a fieldname.

   FIELDNAME is the name of a field in the PR.

   OPERATOR is one of:

`='
     The value of the left-hand side of the expression must exactly
     match the regular expression on the right-hand side of the
     expression.  *Note Querying using regular expressions: Regexps.

`~'
     Some portion of the left-hand side of the expression must match the
     regular expression on the right-hand side.

`=='
     The value of the left-hand side must be equal to the value on the
     right-hand side of the expression.

     The equality of two values depends on what type of data is stored
     in the field(s) being queried.  For example, when querying a field
     containing integer values, literal strings are interpreted as
     integers.  The query expression

          Number == "0123"

     is identical to

          Number == "123"

     as the leading zero is ignored.  If the values were treated as
     strings instead of integers, then the two comparisons would return
     different results.

`!='
     The not-equal operator. Produces the opposite result of the ==
     operator.

`<,>'
     The left-hand side must have a value less than or greater than the
     right-hand side.  Comparisons are done depending on the type of
     data being queried; in particular, integer fields and dates use a
     numeric comparison, and enumerated fields are ordered depending on
     the numeric equivalent of their enumerated values.

   BOOLEANOP is either `|' (logical or), or `&' (logical and).  The
query expression

     Category="baz" | Responsible="blee"

selects all PRs with a Category field of `baz' or a Responsible field
of `blee'.

   The not operator `!' may be used to negate a test:

     ! Category="foo"

searches for PRs where the category is not equal to the regular
expression foo.

   Parentheses may be used to force a particular interpretation of the
expression:

     !(Category="foo" & Submitter-Id="blaz")

skips PRs where the Category field is equal to `foo' and the
Submitter-Id field is equal to `blaz'.  Parentheses may be nested to
any arbitrary depth.

   Fieldnames can be specified in several ways.  The simplest and most
obvious is just a name:

     Category="foo"

which checks the value of the category field for the value FOO.

   A fieldname qualifier may be prepended to the name of the field; a
colon is used to separate the qualifier from the name.  To refer
directly to a builtin field name:

     builtin:Number="123"

   In this case, `Number' is interpreted as the builtin name of the
field to check.  (This is useful if the fields have been renamed.  For
further discussion of builtin field names, see *Note The `dbconfig'
file: dbconfig file.

   To scan all fields of a particular type, the FIELDTYPE qualifier may
be used:

     fieldtype:Text="bar"

This searches all text fields for the regular expression `bar'.

   Note that it is not required that the right-hand side of the
expression be a literal string.  To query all PRs where the PR has been
modified since it was closed, the expression

     Last-Modified != Closed-Date

will work; for each PR, it compares the value of its Last-Modified field
against its Closed-Date field, and returns those PRs where the values
differ.  However, this query will also return all PRs with empty
Last-Modified or Closed-Date fields.  To further narrow the search:

     Last-Modified != Closed-Date & Last-Modified != "" & Closed-Date != ""

In general, comparing fields of two different types (an integer field
against a date field, for example) will probably not do what you want.

   Also, a field specifier may be followed by the name of a subfield in
braces:

     State[type] != "closed"

or even

     builtin:State[type] != "closed"

Subfields are further discussed in *Note The `dbconfig' file: dbconfig
file.


File: gnats.info,  Node: Example queries,  Prev: Query expressions,  Up: query-pr

Example queries
---------------

The following simple query:

     query-pr --expr 'Category~"rats" & State~"analyzed"
                      & Responsible~"fred"'

yields all PRs in the database which contain the field values:

     >Category:     rats         _and_
     >Responsible:  fred         _and_
     >State:        analyzed

   The following query:

     query-pr --expr 'State~"open|analyzed"'

yields all PRs in the database whose `State' values match either `open'
or `analyzed' (*note Querying using regular expressions: Regexps..
This search is useful as a daily report that lists all Problem Reports
which require attention.

   The following query:

     query-pr --expr 'fieldtype:Text="The quick.*brown fox"'

yields all PRs whose TEXT fields contain the text `The quick' followed
by `brown fox' within the same field.  *Note Querying using regular
expressions: Regexps, which also contains further useful examples of
query expressions.


File: gnats.info,  Node: Emacs,  Prev: query-pr,  Up: GNATS user tools

The Emacs interface to GNATS
============================

   Emacs interface to GNATS provides basic access to GNATS databases,
i.e. sending, editing, and querying Problem Reports.  It also defines a
simple major mode for editing `dbconfig' files.

   This section provides an overview of using GNATS with Emacs.  It
does not describe the use of Emacs itself, for detailed instructions on
using Emacs, see *Note Top: (emacs)Top.  For installation instructions
of the GNATS Emacs mode, see *Note Installing utils::.

   Please note the Emacs interface was completely rewritten between
GNATS 3 and GNATS 4.  It now uses `gnatsd', *Note gnatsd::, exclusively
for its operations and uses modern Emacs features like faces.  Its
features are not complete though, you can send your suggestions and
patches to the appropriate GNATS mailing list, *Note Support::.

* Menu:

* Emacs viewing::               Viewing PRs by their number.
* Emacs querying::              Querying the database.
* Emacs submitting::            Submitting new PRs.
* Emacs editing::               Editing PRs.
* Emacs editing buffer::        The editing buffer.
* Emacs and databases::         Changing the working database.
* dbconfig mode::               Major mode for dbconfig files.
* Other Emacs commands::        Miscellaneous commands.
* Emacs customization::         Customizing the Emacs interface.


File: gnats.info,  Node: Emacs viewing,  Next: Emacs querying,  Up: Emacs

Viewing Problem Reports
-----------------------

   To view a particular Problem Report, use the command `M-x view-pr'.
It asks for a Problem Report number and displays that Problem Report.

   The displayed buffer is put in the view mode, *Note Misc File Ops:
(emacs)Misc File Ops.  If you decide to edit the displayed Problem
Report, use the command `e' (`gnats-view-edit-pr').

`gnats-view-mode-hook'
     Hook run when `gnats-view-mode' is entered.


File: gnats.info,  Node: Emacs querying,  Next: Emacs submitting,  Prev: Emacs viewing,  Up: Emacs

Querying Problem Reports
------------------------

   Querying the database is performed by the `M-x query-pr' command.
The command prompts for the query expression, *Note Query expressions::,
and displays a buffer with the list of the matching Problem Reports.

   The list of the Problem Reports is displayed in the `summary' query
format, *Note Formatting query-pr output::.  Currently, the display
format cannot be changed and it must output each Problem Report's
number in the first column.

   The Problem Report list buffer is put in the view mode, *Note Misc
File Ops: (emacs)Misc File Ops.  You can use most of the standard view
mode commands in it.  Additionally, the following special commands are
available:

`v'
`RET'
`mouse-2'
     View the current Problem Report (`gnats-query-view-pr'), *Note
     Emacs viewing::.

`e'
     Edit the current Problem Report (`gnats-query-edit-pr'), *Note
     Emacs editing::.

`g'
     Update the Problem Report list (`gnats-query-reread').  The last
     performed query is executed again and the buffer is filled with the
     new results.

`G'
     Perform new query (`query-pr').

`s'
     Send new Problem Report (`send-pr'), *Note Emacs submitting::.

`D'
     Change the current database (`gnats-change-database'), *Note Emacs
     and databases::.

`q'
     Bury buffer, the buffer is put at the end of the list of all
     buffers.  This is useful for quick escape of the buffer, without
     killing it.

   If the value of the variable GNATS-QUERY-REVERSE-LISTING is
non-`nil', the listing appears in the reversed order, i.e. with the
Problem Reports of the highest number first, in the buffer.

   Similarly to other GNATS Emacs modes, there is a hook available for
the Problem Report list.

`gnats-query-mode-hook'
     Hook run when `gnats-query-mode' is entered.


File: gnats.info,  Node: Emacs submitting,  Next: Emacs editing,  Prev: Emacs querying,  Up: Emacs

Submitting new Problem Reports
------------------------------

   You can submit new Problem Reports with the command `M-x send-pr'.
The command puts you to the problem editing buffer, *Note Emacs
editing::.  The buffer is prefilled with the initial report fields and
their default values, if defined.  You can use the usual Problem Report
editing commands, *Note Emacs editing::.  When you have filled in all
the fields, you can send the Problem Report by presing `C-c C-c'.

   If you run `M-x send-pr' with a prefix argument, it runs the
`gnats-change-database' command before putting you to the editing
buffer, *Note Emacs and databases::.

   You can set the following variables to get some fields pre-filled:

GNATS-DEFAULT-ORGANIZATION
     Default value of the `Organization' field used in new Problem
     Reports.

GNATS-DEFAULT-SUBMITTER
     Default value of the `Submitter-Id' field used in new Problem
     Reports.


File: gnats.info,  Node: Emacs editing,  Next: Emacs editing buffer,  Prev: Emacs submitting,  Up: Emacs

Editing Problem Reports
-----------------------

   To edit a particular Problem Report, use the command `M-x edit-pr'.
It asks for a Problem Report number and puts the given Problem Report
in the editing buffer.  *Note Emacs editing buffer::, for information
how to edit the Problem Report in the buffer and how to submit your
changes.

   Note you can also start editing of a selected Problem Report directly
from within the viewing buffer, *Note Emacs viewing::, or the query
result buffer, *Note Emacs querying::.


File: gnats.info,  Node: Emacs editing buffer,  Next: Emacs and databases,  Prev: Emacs editing,  Up: Emacs

The Problem Report editing buffer
---------------------------------

   When you invoke a Problem Report editing command, the Problem Report
is put into a special editing buffer.  The Problem Report is formatted
similarly to the `query-pr -F' output, *Note Formatting query-pr
output::.  Field identifiers are formatted as

     >Field:

   with the text of the field following the identifier on the same line
for single-line fields or starting on the next line for multi-line
fields.

   The Problem Report editing mode tries to prevent you from violating
the Problem Report format and the constraints put on the possible field
values.  Generally, you can use usual editing commands, some of them
have a slightly modified behavior though.  (If you encounter a very
strange behavior somewhere, please report it as a bug, *Note Support::.)

   You can move between fields easily by pressing the `TAB'
(`gnats-next-field') or `M-TAB' (`gnats-previous-field') keys.

   The field tags are read-only and you cannot edit them nor delete
them.  If you want to "remove" a field, just make its value empty.

   Editing a field value depends on the type of the edited field, *Note
Field datatypes::.  For text fields, you can edit the value directly,
assuming you preserve the rule about single-line and multi-line values
mentioned above.

   For enumerated fields, you cannot edit the value directly.  You can
choose it from the list of the allowed values, either from the menu
popped up by pressing the middle mouse button or from within minibuffer
by pressing any key on the field's value.  If the pressed key matches
any of the allowed field values, that value is put as the default value
after the minibuffer prompt.  You can also cycle through the allowed
field values directly in the editing buffer using the `SPACE' key.
Enumerated field values are marked by a special face to not confuse
you; you must have enabled font lock mode to benefit from this feature,
*Note Font Lock: (emacs)Font Lock.

   Some field values can be read-only, you cannot edit them at all.

   Once you have edited the Problem Report as needed, you can send it to
the server with the `C-c C-c' command (`gnats-apply-or-submit').
Successful submission is reported by a message and the buffer
modification flag in mode line is cleared.  Then you can either kill
the buffer or continue with further modifications.

`gnats-edit-mode-hook'
     Hook run when `gnats-edit-mode' is entered.


File: gnats.info,  Node: Emacs and databases,  Next: dbconfig mode,  Prev: Emacs editing buffer,  Up: Emacs

Changing the database
---------------------

   By default, the Emacs interface connects to the default database,
*Note databases file::.  If you want to connect to another database, use
the command `M-x gnats-change-database'.  It will ask you for the
database name to use, server and port it can be accessed on, and your
login name.

   If you want to use the `gnatsd' command, *Note gnatsd::, directly,
without connecting to a remote server or the localhost connection port,
provide your local file system full path to `gnatsd' as the server
name.  Port number does not matter in this case.

   If the database requires a password to allow you the access to it,
you are prompted for the password the first time you connect to the
database.  If you provide an invalid password, you cannot connect to
the database anymore and you have to run the `M-x
gnats-change-database' command again.


File: gnats.info,  Node: dbconfig mode,  Next: Other Emacs commands,  Prev: Emacs and databases,  Up: Emacs

dbconfig mode
-------------

   The Emacs interface defines a simple major mode
`gnats-dbconfig-mode' for editing `dbconfig' files, *Note dbconfig
file::.  It defines basic mode attributes like character syntax and
font lock keywords, it does not define any special commands now.

`gnats-dbconfig-mode-hook'
     Hook run when `gnats-dbconfig-mode' is entered.


File: gnats.info,  Node: Other Emacs commands,  Next: Emacs customization,  Prev: dbconfig mode,  Up: Emacs

Other commands
--------------

`M-x unlock-pr'
     Ask for a Problem Report number and unlock that Problem Report.
     This function is useful if connection to a GNATS server was
     interrupted during an editing operation and further modifications
     of the Problem Report are blocked by a stealth lock.

`M-x unlock-database'
     Unlock the whole GNATS database.  This function is useful in
     situations similar to when `unlock-pr' is used.

`M-x gnats-show-connection'
     Show the connection buffer associated with the current buffer.  You
     can view the Emacs communication with GNATSD in it.  This is
     useful when something strange happens during the communication with
     the server, e.g. when sending a Problem Report with `C-c C-c' from
     a Problem Report editing buffer.


File: gnats.info,  Node: Emacs customization,  Prev: Other Emacs commands,  Up: Emacs

Customization
-------------

   All the user variables can be customized in the customization group
`gnats', *Note Easy customization: (emacs)Easy customization.


File: gnats.info,  Node: Installation,  Next: Management,  Prev: GNATS user tools,  Up: Top

Installing GNATS
****************

   See also *Note Where the tools and utilities reside: Locations.

   There are several steps you need to follow to fully configure and
install GNATS on your system.  You need `root' access in order to
create a new account for `gnats' and to install the GNATS utilities.
You may need `root' access on some systems in order to set up mail
aliases and to allow this new account access to `cron' and `at'.

   If you are updating an older version of GNATS rather than installing
from scratch, see *Note Upgrading from older versions: Upgrading.

   GNATS installation relies on two other freely available software
packages, which should be installed before you go on to configure and
build GNATS.  These are GNU `make' and `Texinfo' (version 4.2 or
higher).  Both are available from the GNU FTP site at
<ftp://ftp.gnu.org>.

   To build and install GNATS, you must:

   * Run `configure', with correct options if the defaults are
     unsuitable for your site.  *Note Configuring and compiling the
     software: Configure and make.  Default installation locations are
     in *Note Where GNATS lives: Locations.

   * Compile the GNATS programs on your system.  *Note Configuring and
     compiling the software: Configure and make.

   * Create an initial database by using the `mkdb' command.  *Note
     Setting up the default database::.

   * Set up periodic jobs, using cron, to handle Problem Reports
     arriving by mail.  *Note Setting up periodic jobs::.

   * Set up mail aliases for GNATS.  *Note Setting up mail aliases:
     Aliases.

   * Install the GNATS tools and utilities locally, and install the user
     tools (`query-pr', `edit-pr', `send-pr') on every machine in your
     local network.  *Note Installing the user tools: Installing tools.

   * Install the GNATS daemon `gnatsd'.  *Note Installing the daemon::.

   * If there are people outside your organization who will be
     submitting PRs or who are supposed to be able to query and/or edit
     PRs, you may need to instruct them to obtain and build the GNATS
     tools `query-pr', `edit-pr' and `send-pr' for their systems.
     However, for many sites, setting up a remote access interface to
     GNATS, such as Gnatsweb is a better solution since this requires
     no configuration on the remote side.

* Menu:

* Configure and make::               Configuring and compiling the software
* Installing utils::                 Installing the utilities
* Setting up the default database::  Setting up the default database
* Setting up periodic jobs::         Setting up periodic jobs
* Aliases::                          Setting up mail aliases
* Installing the daemon::            Installing the daemon
* Installing tools::                 Installing the user tools
* Upgrading::                        Upgrading from older versions


File: gnats.info,  Node: Configure and make,  Next: Installing utils,  Up: Installation

Configuring and compiling the software
======================================

  1. First, unpack your distribution.  We provide source code in a `tar'
     file which was compressed using `gzip'.  The code can be extracted
     into a directory UNPACKDIR using

          cd UNPACKDIR
          gunzip gnats-4.0-beta2.tar.gz
          tar xvf gnats-4.0-beta2.tar

     The sources reside in a directory called `gnats-4.0-beta2' when
     unpacked.  We call this the "top level" of the source directory,
     or "srcdir".  The sources for the GNATS tools are in the
     subdirectory `gnats-4.0-beta2/gnats/*'.  Lists of files included
     in the distribution are in each directory in the file `MANIFEST'.

  2. As of GNATS version 4, having Emacs installed on the GNATS server
     is no longer a requirement.  If you do not have Emacs installed,
     disregard this step altogether.

     You may wish to alter the installation directory for the Emacs lisp
     files.  If your Emacs lisp library is not in
     `PREFIX/share/emacs/site-lisp', edit the file
     `SRCDIR/gnats/Makefile.in'.  Change the variable `lispdir' from
     `PREFIX/emacs/site-lisp' to the directory containing your Emacs
     lisp library.  For information on PREFIX, see *Note PREFIX: prefix.

  3. Create an account for the `gnats' user.  You can actually name this
     user whatever you want to, as long as it is a valid username on
     your system, but we strongly recommend that you call the user
     `gnats'.  If you do decide to give it some other name, remember to
     use the option `--with-gnats-user' when running `configure' below.
     Below, we will anyway refer to this user by the name `gnats'.

     This user must have an entry in the file `/etc/passwd'.  As for
     ordinary users, create a standard home directory for the `gnats'
     user.  The default `PATH' for this user should contain
     `EXEC-PREFIX/bin' and `EXEC-PREFIX/libexec/gnats'.  The
     EXEC-PREFIX value is configurable with the `--exec-prefix'
     configure option described below, but for standard installations,
     these two directories correspond to `/usr/local/bin' and
     `/usr/local/libexec/gnats'.

  4. Run `configure'.  You can nearly always run `configure' with the
     simple command

          ./configure

     and the "Right Thing" happens:

        * GNATS is configured in the same directory you unpacked it in;

        * when built, GNATS runs on the machine you're building it on;

        * when installed, files are installed under `/usr/local' (*note
          Where GNATS lives: Locations.).

        * all GNATS utilities operate on the "default database", assumed
          to be named _default_ and to be located in
          `/usr/local/com/default', unless you invoke the utilities with
          `-d' DATABASENAME or `--directory='DATABASENAME, or set the
          GNATSDB environment variable to point to some other database.

     The most common options to `configure' are listed below:

          configure [ --prefix=PREFIX ]
                    [ --exec-prefix=EXEC-PREFIX ]
                    [ --with-gnats-service=SERVICE-NAME ]
                    [ --with-gnats-user=USERNAME ]
                    [ --with-gnatsd-user-access-file=PATH ]
                    [ --with-gnatsd-host-access-file=PATH ]
                    [ --with-gnats-dblist-file=PATH ]
                    [ --with-gnats-default-db=PATH ]
                    [ --with-kerberos ] [ --with-krb4 ]
                    [ --verbose ]

    `--prefix=PREFIX'
          All host-independent programs and files are to be installed
          under PREFIX.  (Host-dependent programs and files are also
          installed in PREFIX by default.)  The default for PREFIX is
          `/usr/local'.  *Note Where GNATS lives: Locations.

    `--exec-prefix=EXEC-PREFIX'
          All host-dependent programs and files are to be installed
          under EXEC-PREFIX.  The default for EXEC-PREFIX is PREFIX.
          *Note Where GNATS lives: Locations.

    `--with-gnats-service=SERVICE-NAME'
          Set SERVICE-NAME to be the GNATS network service.  Default
          name is SUPPORT.

    `--with-gnats-user=USERNAME'
          Set USERNAME to be the user name for GNATS.  Default username
          is GNATS.

    `--with-gnatsd-user-access-file=PATH'
          Set global (across all databases) gnatsd user access file to
          PATH. Default is `/USR/LOCAL/ETC/GNATS/GNATSD.USER_ACCESS'.
          Per-database user access permissions are set in a
          `gnatsd.user_access' file in the `gnats-adm' subdirectory of
          each database.

    `--with-gnatsd-host-access-file=PATH'
          Set global (across all databases) gnatsd host access file to
          PATH. Default is `/usr/local/etc/gnats/gnatsd_host.access'.
          There is currently no way to specify host access permissions
          on a per-database basis.

    `--with-gnats-dblist-file=PATH'
          Specify the file containing the list of databases.

          Default is `PREFIX/etc/gnats/databases'.

    `--with-gnats-default-db=PATH'
          Specify the default database to use when GNATS tools are
          invoked without the `-d' or `--databasename' option, and when
          the GNATSDB envrionment variable hasn't been set. Default is
          `/PREFIX/com/gnatsdb'.

    `--with-kerberos'
          Include code for Kerberos authentication.

    `--with-krb4'
          Support Kerberos 4.

    `--verbose'
          Give verbose output while `configure' runs.

     `configure' supports several more options which allow you to
     specify in great detail where files are installed. For a complete
     list of options, run `./configure --help' in the source directory.

     You can build GNATS in a different directory (OBJDIR) from the
     source code by calling the `configure' program from the new
     directory, as in

          mkdir OBJDIR
          cd OBJDIR
          SRCDIR/configure ...

     By default, `make' compiles the programs in the same directory as
     the sources (SRCDIR).

  5. Make sure you have GNU `make', then run

          make all info

     from the directory where `configure' created a `Makefile' (this is
     OBJDIR if you used it, otherwise SRCDIR.)  These targets indicate:

    `all'
          Compile all programs

    `info'
          Create `info' files using `makeinfo'.


File: gnats.info,  Node: Installing utils,  Next: Setting up the default database,  Prev: Configure and make,  Up: Installation

Installing the utilities
========================

   The following steps are necessary for a complete installation.  You
may need `root' access for these.

  1. Install the utilities by invoking

          make install install-info

     These targets indicate:

    `install'
          Installs all programs into their configured locations (*note
          Where GNATS lives: Locations.).

    `install-info'
          Installs `info' files into their configured locations (*note
          Where GNATS lives: Locations.).

     After you have installed GNATS, you can remove the object files
     with

          make clean

  2. If you do not have Emacs installed on your GNATS server, this step
     should be skipped.

     Place the following lines in the file `default.el' in your Emacs
     lisp library, or instruct your local responsible parties to place
     the lines in their `.emacs':

          (autoload 'send-pr "gnats"
             "Command to create and send a problem report." t)
          (autoload 'edit-pr "gnats"
             "Command to edit a problem report." t)
          (autoload 'view-pr "gnats"
             "Command to view a problem report." t)
          (autoload 'query-pr "gnats"
             "Command to query information about problem reports." t)
          (autoload 'unlock-pr "gnats"
             "Unlock a problem report." t)
          (autoload 'gnats-dbconfig-mode "gnats"
            "Major mode for editing the `dbconfig' GNATS configuration file." t)
          (add-to-list 'auto-mode-alist '("\\<dbconfig$" . gnats-dbconfig-mode))

  3. If you want people who are logged into the GNATS server itself to
     be able to use the `send-pr' tool to submit problem reports, you
     need to create a configuration file for `send-pr' on the server.
     *Note The send-pr.conf configuration file: send-pr.conf file.



File: gnats.info,  Node: Setting up the default database,  Next: Setting up periodic jobs,  Prev: Installing utils,  Up: Installation

Installing the default database
===============================

   For the following steps, log in as the user `gnats'.

   We are now going to initialize the default GNATS database.  Run the
following command:

     mkdb default

   This creates a database named `default', with all its data stored
below the directory `PREFIX/com/gnatsdb', in a default installation
this corresponds to `/usr/local/com/gnatsdb'.  If you specified the
`--with-gnats-default-db' option when running configure, the default
database will be created under the directory you specified instead.
`mkdb' creates the database directory itself, together with three
different subdirectories(1):

   * A directory for the mandatory GNATS category PENDING.

   * A `gnats-queue' directory for queueing new messages to GNATS
     before they are processed by `file-pr'.

   * The administrative directory `gnats-adm'. This directory is
     populated with default configuration files from the
     `PREFIX/etc/gnats/defaults' directory.

   The next configuration step is to edit the default files copied to
the database's `gnats-adm' directory by `mkdb'.

   The default `dbconfig' file installed by `mkdb' provides a good
basis for many GNATS databases. The default file causes similar
behaviour to the 3.x versions of GNATS. However, even if this might be
precisely what you want, you should still go through the file and check
that the default settings suit your needs.  *Note The `dbconfig' file:
dbconfig file.

   Then edit the files `categories', `responsible', and `submitters' in
the `gnats-adm' directory (*note Other database-specific config files:
Other config files.) to reflect your local needs.  For special
configurations, you may also have to edit the `states' and `classes'
files.

   If you used the `--with-gnats-default-db' option in the pre-build
configure to change the location of the default database, you need to
edit the `databases' config file, see *Note The `databases file':
databases file.  This file is by default located in the
`PREFIX/etc/gnats' directory, but may have been changed by the option
`--with-gnats-dblist-file' option during configure.

   ---------- Footnotes ----------

   (1) Upgraders from older versions of GNATS should note that category
directories are now created "on-the-fly" as needed by default.


File: gnats.info,  Node: Setting up periodic jobs,  Next: Aliases,  Prev: Setting up the default database,  Up: Installation

Setting up periodic jobs
========================

   Allow the new user `gnats' access to `cron' and `at'.  To do this,
add the name `gnats' to the files `cron.allow' and `at.allow', which
normally reside in the directory `/var/spool/cron'.  If these files do
not exist, make sure `gnats' does not appear in either of the files
`cron.deny' and `at.deny' (in the same directory).  If you changed the
name of the GNATS user during configure, remember to substitute as
appropriate in the previous steps.

   Create a `crontab' entry that periodically runs the program
`queue-pr' with the `--run' option (*note `queue-pr': queue-pr.).  For
example, to run `queue-pr --run' every ten minutes, create a file called
`.mycron' in the home directory of the user `gnats' which contains the
line:

     0,10,20,30,40,50 * * * * EXEC-PREFIX/libexec/gnats/queue-pr --run

(Specify the full path name for `queue-pr'.)  Then run

     crontab .mycron

See the `man' pages for `cron' and `crontab' for details on using
`cron'.


File: gnats.info,  Node: Aliases,  Next: Installing the daemon,  Prev: Setting up periodic jobs,  Up: Installation

Setting up mail aliases
=======================

   The following mail aliases must be added on the machine where the
GNATS server is installed.  The instructions below are for Sendmail or
Sendmail-like mail systems.  If these instructions don't fit your
system, particularly if you do not have an `aliases' file, ask your
mail administrator for advice.

   The following aliases should be placed in the file `/etc/aliases'.
Yoy may need `root' access to add these aliases:

   * Create an alias for the GNATS administrator.  This address should
     point to the address of the person in charge of administrating
     GNATS:

          gnats-admin:  ADDRESS

   * Create an alias to redirect incoming Problem Reports.  This alias
     should redirect incoming mail via a "pipe" to the program
     `queue-pr -q'.  For example, if Problem Reports coming to your
     site are to arrive at the address `bugs@your.company.com', create
     an alias to the effect of:

          bugs:  "| EXEC-PREFIX/libexec/gnats/queue-pr -q"

     This places incoming Problem Reports in the `GNATS-QUEUE'
     directory of your database.  Remember to fill in the full path of
     the `queue-pr' command as appropriate for your installation.

   * You may also wish to forward a copy of each incoming Problem
     Report to a log.  This can be accomplished with something like:

          bug-q: "| EXEC-PREFIX/libexec/gnats/queue-pr -q"
          bug-log:  /some/path/bugs.log
          bugs:      bug-q, bug-log

     This configuration archives incoming Problem Reports in the file
     `bug.log', and also feeds them to the program `queue-pr'.
     (Remember, `bug.log' needs to be world-writable, and should be
     pruned regularly; *note GNATS Administration: Management..)  In
     order for the log file to protect fully against data loss in case
     a disk runs full, try to place it on a different disk volume than
     the GNATS database.

   * If you want your users to be able to query the database by mail,
     use the following alias:

          query-pr: "| EXEC-PREFIX/libexec/gnats/mail-query"

     The `mail-query' program uses `--restricted' to search on the
     database, and by default only searches for PRs that aren't closed
     (*note Querying the database: query-pr.).



File: gnats.info,  Node: Installing the daemon,  Next: Installing tools,  Prev: Aliases,  Up: Installation

Installing the daemon
=====================

   By default, the daemon and clients are set to use port 1529.  Add
the line

     support		1529/tcp			# GNATS

to your `/etc/services' file.  If you want a different service name,
configure GNATS with

     --with-gnats-service=SERVICENAME

   In your `inetd.conf' file, add the line

     support	stream	tcp	nowait	gnats	/usr/local/libexec/gnats/gnatsd gnatsd

adjusting the path accordingly if you used configure options to make
changes to the defaults.  To make `inetd' start spawning the GNATS
daemon when connected on that port, send it a hangup signal (`HUP').

   Some operating systems have replaced `inetd' with the more modern
`xinetd'. Instead of editing `inetd.conf', you should create the file
`/etc/xinetd.d/support', containing something like the following:

     service support
     {
        disable = no
        socket_type = stream
        protocol = tcp
        wait = no
        user = gnats
        server = /usr/local/libexec/gnats/gnatsd
     }

   If you specified a different service name when running `configure',
you need to give the file the same name as the service name, and you
need to adjust the `service' line above.  If the `--prefix' or
`--exec-prefix' options were passed to `configure', adjust the `server'
line above, and if you used the `--with-gnats-user' option, adjust the
`user' line.

   Then restart `xinetd' to make the new configuration current.

   If you use an Internet superserver different from `inetd' or
`xinetd', please refer to its documentation for information how to
configure it.

   At this point, you will probably want to set the access permissions
of the different hosts that are going to be accessing your databases.
The access permissions can currently only be set on a global scale
(that is, across all the databases on a GNATS server).  The location
and name of the global host access configuration file can be set during
the pre-build configure as shown above, but by default the file is
`/usr/local/etc/gnats/gnatsd_host.access'.  It lists the hosts allowed
to access your server, and what their default access levels are.  Each
line in the file denotes one server, or one part of a network domain.
There are three fields on each line, but only two are currently used.
To grant all hosts from the domain SITE.COM edit access, use this line:

   SITE.COM:EDIT

If you run a GNATS web interface or similar tool on the same machine as
the server is running on, you probably want to grant LOCALHOST edit
access:

   LOCALHOST:EDIT

   If you are using Kerberos, the `gnatsd_host.access' file shows the
sites that don't require Kerberos authentication.

   The third field might in the future be used for things like
controlling what categories, submitter-id's PRs, etc., can be accessed
from that site.  Access attempts that are denied are logged to the
syslog messages file (`/var/adm/messages' on many systems).

