\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename gnats-faq

@ifinfo
@format
START-INFO-DIR-ENTRY
* GNATS FAQ: (gnats-faq).	FAQ for the GNU Problem Report Management System
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@settitle @sc{gnats} Frequently Asked Questions
@c %**end of header

@c @setchapternewpage odd

@ifinfo
Copyright @copyright{} 2002 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.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``@sc{gnu} General Public License''
are included exactly as in the original, and provided
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,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.
@end ifinfo

@titlepage
@title @sc{gnats} Frequently Asked Questions
@c @subtitle whatever
@author Hans-Albert Schneider

@page
@c Copyright notice
@vskip 0pt plus 1filll
Copyright @copyright{} 2002, 2005 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 sections
     entitled ``Copying'' and ``@sc{gnu} General Public License''
     are included exactly as in the original, and provided
     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,
     except that this permission notice may be stated in a
     translation approved by the Free Software Foundation.

@end titlepage

@contents

@node    Top
@comment node-name, next,    previous, up
@top @sc{gnats} Frequently Asked Questions

This document answers some frequently asked questions concerning
@sc{gnats}, the @sc{gnu} problem report management system, and related
software.
The most recent version of this FAQ can be found at
@uref{http://www.gnu.org/software/gnats/doc/faq/gnats-faq.html}.


The questions and answers have been compiled by
@email{Gnats-FAQ@@HA-Schneider.de,Hans-Albert Schneider}, mainly
using the help-gnats mailing list and the @sc{gnats} documentation as
input.  Please report any errors and suggestions to him.


@menu
* General::                     General questions
* Installation::                Problems during installation
* Configuration::               Problems with @sc{gnats} configuration
* Clients::                     Ways to access a @sc{gnats} system
* Glossary::                    Abbreviations and definitions
* Index::                       Important things and where they are referenced
@end menu

@node    General
@comment node-name, next, previous, up
@chapter General Questions

@menu
* What is GNATS::               A very short overview
* How to pronounce it::         Pronunciation: with or without the "G"?
* Get it::                      Where to get @sc{gnats}
* Versions::                    Which versions are available?
* Mailing Lists::               E-mail discussion lists
* Bug Reporting::               How to report a bug
* Upgrading::                   Considerations for the 3.x to 4.0 transition
@end menu

@node     What is GNATS
@comment  node-name,     next,   previous,  up
@section  What is @sc{gnats}?

@sc{gnats} is the @sc{gnu} problem report management system.  Problem
report management systems are also known as "bug-tracking systems",
though the entries need not be bugs (e.g., think of change requests).
The acronym stands for "GNats: A Tracking System".

@sc{gnats} stores all information about the problem reports at a central
site, and enables users to access this site by various means, including
e-mail, WWW, and a network daemon.  New problem reports can be created,
and existing reports can be queried and updated, by most of these means.

@sc{gnats} is widely customizable: Of course you can define report
categories (is the report about tool A or service B?), responsibles
(who takes care of this report?), and submitters (is it from customer1
or from the sales department?).  You can also define possible states
of a report (open, analyzed, closed, etc.) and classes (software bug,
documentation bug, change request, @dots{}).

Starting with @sc{gnats} 4.0, you can define your own custom fields, and
customize many of the built-in fields; you can have fields automatically
set to a certain value when another field changes its contents (e.g.,
set a "Closed-Date" field to the current date when the report goes to
state "closed", and unset it when it goes back from "closed" to
something else), or when the report is changed at all (e.g., to maintain
a "Last-Modified" field).


@menu
* User view::                   Short overview for users
* Administrator View::          Short overview for system administrators
@end menu

@node User view
@comment  node-name,  next,  previous,  up
@subsection How it Works---User's View

Users enter their problem reports (PRs) via some front-end.  This
front-end either directly contacts the @sc{gnats} server, or sends the
report via e-mail.  (The server is available since about version 3.90
of @sc{gnats}).  For an incomplete list of front-ends see @ref{Clients}.

Some front-ends (like TkGnats, see @ref{TkGnats}) are capable of
contacting several @sc{gnats} servers, or several problem report
databases managed by the same @sc{gnats} server.


@node Administrator View
@comment  node-name,  next,  previous,  up
@subsection How it Works---Administrator's View

@cindex starting gnatsd
@cindex gnatsd, starting

The server is started by a super-server like inetd or xinetd.  It has
a built-in access control mechanism based on IP addresses and
username/password.

For users sending their PRs via e-mail, some mail addresses must be
configured.


@node     How to pronounce it
@comment  node-name,     next,   previous,  up
@section  How is "@sc{gnats}" pronounced?

Q: So, How can I pronounce "@sc{gnats}?"  Should I pronounce "G"?

It has been reported that the original developers pronounced the "G".
(This is unlike the little insect called "gnat" where the "G" is not
pronounced.)


@node     Get it
@comment  node-name,  next,     previous,      up
@section Where do I get it?

See the @sc{gnats} home page at @uref{http://www.gnu.org/software/gnats/}.

The current development version is available via CVS only, see the
@uref{http://savannah.gnu.org/projects/gnats,@sc{gnu} savannah
@sc{gnats} project page} for the instructions how to get it.


@node     Versions
@comment  node-name,  next,  previous,  up
@section  What is the latest version?

The version numbers of @sc{gnats} 3.x is somewhat confusing, because
3.1xx is newer than 3.2.

Version 3.2 was released in 1993 (I never tried it, but it is said to be
"really broken").  A lot of new features have been added since 3.2,
including multiple database support and customized fields.  Among the
contributed software are comprehensive WWW and Tk based front-ends.

The latest 3.x release is 3.113.1.  It is deprecated due to security
concerns and lack of maintenance.

@sc{gnats} 4.0 was released in August 2003, and 4.1 was released in March 2005.
All released versions are available for download at
@uref{http://ftp.gnu.org/pub/gnu/gnats/}.


@node Mailing Lists
@comment  node-name,  next,  previous,  up
@section Is there a Mailing List?

Currently, the following @sc{gnats} mailing lists exist:

@itemize
@item @uref{http://lists.gnu.org/mailman/listinfo/info-gnats,info-gnats@@gnu.org}
This is a low volume moderated mailing lists for @sc{gnats} related
announcements, like new releases or important information.

@item @uref{http://lists.gnu.org/mailman/listinfo/help-gnats,help-gnats@@gnu.org}
A low-to-middle volume mailing list where anything related to @sc{gnats}
can be discussed (development, help, questions, suggestions, etc.).

@item @uref{http://lists.gnu.org/mailman/listinfo/bug-gnats,bug-gnats@@gnu.org}
Bug reports can be sent there.  Please note that it's preferred to
submit bug reports via the bug tracking system (@pxref{Bug Reporting}),
which automatically mirrors them to this list.
@end itemize

Lists that are of interest mainly for the @sc{gnats} developers:

@itemize
@item @uref{http://lists.gnu.org/mailman/listinfo/gnats-prs,gnats-prs@@gnu.org}
Copies of the bug tracking system messages are sent there.  Contrast to
bug-gnats@@gnu.org which only gets new bug reports, this list also gets
the follow-ups (Whatever goes into @sc{gnats}' @code{>Audit-Trail:} field).

@item @uref{http://lists.gnu.org/mailman/listinfo/gnats-commit,gnats-commit@@gnu.org}
CVS commit messages are sent there.

@item @uref{http://lists.gnu.org/mailman/listinfo/gnats-diffs,gnats-diffs@@gnu.org}
Diffs of committed files are sent automatically to this address.
@end itemize


@node Bug Reporting
@comment  node-name,  next,  previous,  up
@section How do I Report a Bug?
@cindex bug reporting

Before reporting a bug, make sure it really is a bug, not a simple
misunderstanding or a misconfiguration.  Please check the manual and
this FAQ.  You may also ask for help on the
@uref{http://lists.gnu.org/mailman/listinfo/help-gnats,help-gnats@@gnu.org}
mailing list (you may want to search the list archive first; it is
available from @uref{http://lists.gnu.org/mailman/listinfo/help-gnats}).

If it is a bug, please report it via the bug tracking system.  It
resides at
@uref{http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=gnats}.
This is a common bug database for @sc{gnats}, Gnatsweb and TkGnats.
(And, yes, of course: It uses @sc{gnats} and Gnatsweb.)

When you report problems concerning @sc{gnats} itself, please do not
forget to provide especially the following information:

@itemize @bullet
@item
The @sc{gnats} version you are using.  If your problem involves
Gnatsweb or TkGnats, please also report their versions.

@item
The @emph{exact} way how to reproduce the bug.

@item
Your configuration.

@item
If you encounter a compilation or build problem, it is especially
important to mention the operating system, compiler and possibly other
build utilities you use.
@end itemize

Providing this information in the initial report avoids further
unnecessary communication, saves the limited resources of the
developers (keep in mind that they are working on @sc{gnats} and
friends in their spare time) and helps to track down and fix the
problem soon.


@node Upgrading
@comment  node-name,  next,  previous,  up
@section Upgrading Considerations

See @ref{Upgrading,,Upgrading from older versions,gnats,Keeping
Track} for the upgrade process from 3.x to 4.x.

If you are running a 3.x version, @emph{please consider upgrading to 4.0.}
There are some security concerns about the 3.1xx code that have gone
with 4.0.  Furthermore, the @sc{gnats} 3 branch is not maintained
anymore due to lack of capacity.


The default format of the reports has not changed during the transition
from 3.113.1 to 4.0, though you may add more fields to 4.0 reports (and
leave out others).  The format of the index file is now binary.


However, you have to change the e-mail aliases because the meaning of
the @samp{-d} option to the client programs has changed: It took the
@emph{directory} of the @sc{gnats} database in 3.1xx, and now takes its
@emph{name} (plus, it is now installed into the @file{libexec} directory
instead of the @file{lib} directory).  I.e., you must change the aliases:

@smallexample
# GNATS 3 aliases:
ourdb-query: "|/usr/local/lib/gnats/mail-query -d /usr/local/gnats/db2"
ourdb-bugs:  "|/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -q"
@end smallexample
to
@smallexample
# GNATS 4 aliases:
ourdb-query: "|/usr/local/libexec/gnats/mail-query -d ourdb"
ourdb-bugs:  "|/usr/local/libexec/gnats/queue-pr -d ourdb -q"
@end smallexample


Also note that the client/server protocol has changed from 3.1xx to
4.0; you cannot run clients from one version with the server from the
other version.


@ignore
One consideration is to migrate by running 4.x in parallel to 3.x,
as a sort of mirror of the 3.x version.
To the best of my knowledge, this has not yet been done practically.

The idea is to have the mail
aliases on the 3.x server also send the mails to the 4.x server.  To
avoid confusing submitters and responsibles by duplicate emails (one
from 3.x and one from 4.x), the 4.x server could send its mails to the
@sc{gnats} admin, or even to @code{nobody} (usually aliased to
@w{@file{/dev/null}}).  As the mail text sent by the 4.x server is
configurable, another option is to include an explanatory statement.

@smallexample
# On the @sc{gnats} 3 server:
GreatNewDB-bugs: GreatNewDB-bugs-3, GreatNewDB-bugs-4
GreatNewDB-query:  "|/usr/local/lib/gnats/mail-query -d /usr/local/gnats/db2"
GreatNewDB-bugs-3: "|/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -q"
# If the @sc{gnats} 4 server is different:
GreatNewDB-bugs-4: GreatNewDB-bugs-4@@gnats4-server
@end smallexample

@smallexample
# On the @sc{gnats} 4 server:
GreatNewDB-bugs-4: "|/usr/local/libexec/gnats/queue-pr -d GreatNewDB -q"
nobody:            /dev/null
@end smallexample
@end ignore


@node     Installation
@comment  node-name,  next,  previous,  up
@chapter  Problems during Installation

As installation and configuration problems often overlap,
please check also @ref{Configuration}.

@menu
* Gnatsweb and GNATS::          Cooperation problems between @sc{gnats} and Gnatsweb
@end menu


@node     Gnatsweb and GNATS,  , Installation, Installation
@comment  node-name,  next,  previous,  up
@section  Gnatsweb and @sc{gnats} do not like each other.

@b{Q:} I have installed @sc{gnats} 3.999.x and Gnatsweb 2.9.x, and I
cannot get them work together.

Symptoms are that "make test" fails; if Gnatsweb is installed
nevertheless, it hangs when trying to login into the @sc{gnats} server.


@b{A:} The versions are incompatible.
Gnatsweb 2.9.x is for use with @sc{gnats} 3.113.1.
With @sc{gnats} 3.999.x, you must use Gnatsweb 3.99.x; it is in the
contrib subdirectory of the @sc{gnats} distribution.
(@sc{gnats} 3.999.x/Gnatsweb 3.99.x were pre-releases of the 4.0
releases.  As 4.0 is out now, you may consider to upgrade to the
non-pre versions.)

For @sc{gnats} 4.x, use Gnatsweb 4.0 or greater.


@node     Configuration
@comment  node-name,  next,  previous,  up
@chapter  Configuration Issues

@menu
* General configuration::       General questions about @sc{gnats} configuration
* Gnatsd::                      Configuration of the @sc{gnats} daemon
* E-Mail::                      Problems with the e-mail interface
* Miscellaneous::               Other configuration problems
@end menu


@node General configuration
@comment  node-name,  next,  previous,  up
@section General Configuration Questions

@menu
* Add a database::              How to create a new database
* Renaming a Category::         How to rename categories
* Changing Fields::             Add, remove, or rename a PR field
@end menu

@node Add a database
@comment node-name, next, previous, up
@subsection How do I add a new database?

@noindent
@b{A: (@sc{gnats} 3.1xx)} 
(Please consider upgrading to @sc{gnats} 4.0 or greater.)

@enumerate
@item
Create the base directory for the new database, say
@w{@file{/usr/local/gnats/db2}}, and make sure it is owned by the
@sc{gnats} user.

@item
In there, create subdirectories @w{@file{gnats-adm}},
@w{@file{gnats-adm/locks}}, and @w{@file{gnats-queue}},
and make sure they is owned by the @sc{gnats} user.

@item
Now you need to populate the new @w{@file{gnats-adm}} directory.  The
easiest way is to copy all files from @w{@file{gnats-db/gnats-adm}} to
@w{@file{/usr/local/gnats/db2/gnats-adm}}, and edit them to reflect the
needs of your new database.  Again, make sure they are owned by the
gnats user.

Note that there @emph{must} be a category named @code{pending}.  It is
used when no category is given in a report, and when a report names an
invalid category.

Also note that each database needs its own mail address for submissions
(see also step 8 below), and that you must enter it in the file
@file{config}.

@item
As the @sc{gnats} user, 
run @samp{mkcat --directory=/usr/local/gnats/db2} to create the
directories for the categories.  Remove the files @file{current} and
@file{index}, if they exist.

@item
If the new database is split off of another one, move or copy the
existing reports to their new location.  This is easiest if the
categories have the same names as in the original database.  (See
@ref{Renaming a Category} if some of them changed names.)

Run the program @code{gen-index} to create the index file
(@pxref{gen-index,,Regenerating the index,gnats,Keeping Track}).

Find the greatest report number and put it (or any larger number)
into @file{/usr/local/gnats/db2/gnats-adm/current}.

@strong{Caution:} E-mail updates to the PRs you moved to the new
database may still arrive at the old database.  You may want to
contact everybody who knows about these PRs, asking them to use
the mail address of the new database when sending a follow-up.

@item
Now add a line for the new database to @w{@file{gnats-db.conf}}, like
this:

	@code{/usr/local/gnats/db2:GreatNewDB}

Gnatsd reads it on startup (and as it is started by inetd, this means
it becomes effective with the next connection to gnatsd).  Gnatsweb
(see @ref{Gnatsweb}) learns the database list from gnatsd, so it will offer
you the new database "GreatNewDB" when it is invoked next time.

If you do not know where @w{@file{gnats-db.conf}} lives, run:

@samp{strings /where/ever/gnatsd | grep gnats-db.conf}

@item
Don't forget to setup a cron job to run through the additional
@w{@file{gnats-queue}}.  Note that you need to specify the database
directory to @file{queue-pr}, i.e.,

@samp{/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -r}

or, if you prefer the long options,

@samp{/usr/local/lib/gnats/queue-pr --directory=/usr/local/gnats/db2 --run}


@item
Don't forget to create mail aliases for your new database
(@pxref{Aliases,,Setting up mail aliases,gnats,Keeping Track}).
Take care that the aliases have the right database, e.g.,

@smallexample
GreatNewDB-bugs:  "|/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -q"
GreatNewDB-query: "|/usr/local/lib/gnats/mail-query -d /usr/local/gnats/db2"
@end smallexample

If you do not want to allow querying the database by mail, omit the
@samp{GreatNewDB-query} alias.

You usually need the cooperation of a system administrator for this step
(if you are not a system administrator yourself, of course).


Make sure that @file{/usr/local/gnats/db2/gnats-adm/config} gives the
correct mail addresses for @var{GNATS_ADDR} (this @emph{must} be
different for each database) and for @var{GNATS_ADMIN} (this is probably
the same for all databases).

@smallexample
GNATS_ADDR="GreatNewDB-bugs@@bugs.example.com"
GNATS_ADMIN="gnats-admin@@bugs.example.com"
@end smallexample

If your @sc{gnats} sits behind a firewall and needs to exchange mails
with the outside world, see also @ref{Outgoing mail bounces}.

@end enumerate

@noindent
@b{A: (@sc{gnats} 4.x)} With version 4, this has become much easier
(@pxref{mkdb,,Adding another database,gnats,Keeping Track}):
@enumerate
@item
Add a line for the new database to @w{@file{databases}}, like this:

	@code{GreatNewDB:Our great tools:/usr/local/gnats/db2}

Then, as the @sc{gnats} user, run @samp{mkdb GreatNewDB} to create the
database.  Make sure that the directory (in our example,
@w{@file{/usr/local/gnats/db2}}) can be created by the @sc{gnats} user.

(Note that there @emph{must} be a database named @code{default}.  It
is used as a fallback by some tools if no database is specified.  You
need not use it actively, but you should have run @samp{mkdb default}.)


Gnatsd reads the file @w{@file{databases}} on startup (and as it is
started by inetd, this means it becomes effective with the next
connection to gnatsd).  Gnatsweb (see @ref{Gnatsweb}) learns the
database list from gnatsd, so it will offer you the new database
"GreatNewDB" when it is invoked next time.

If you do not know where @w{@file{databases}} lives, run:

@samp{strings /where/ever/gnatsd | grep databases}

@item
Now, as the @sc{gnats} user, edit the files in directory
@w{@file{/usr/local/gnats/db2/gnats-adm}} to reflect the needs of
your new database.

@item
Depending on the settings in the @w{@file{dbconfig}} file of the new
database, you need not run @code{mkcat} anymore in order to
create new category directories in your database---@sc{gnats} 4
creates them automatically when they are missing.  @xref{dbconfig
file,,The @code{dbconfig} file,gnats,Keeping Track}, for details.

@item
Don't forget to setup a cron job to run through the additional
@w{@file{gnats-queue}}.  Note that you need to specify the database to
@file{queue-pr}, i.e.,

@samp{/usr/local/libexec/gnats/queue-pr -d GreatNewDB -r}

or, if you prefer the long options,

@samp{/usr/local/libexec/gnats/queue-pr --database=GreatNewDB --run}


@item
Don't forget to create mail aliases for your new database
(@pxref{Aliases,,Setting up mail aliases,gnats,Keeping Track}).
Take care that the aliases have the right database, e.g.,

@smallexample
GreatNewDB-bugs:  "|/usr/local/libexec/gnats/queue-pr -d GreatNewDB -q"
GreatNewDB-query: "|/usr/local/libexec/gnats/mail-query -d GreatNewDB"
@end smallexample

If you are updating from @sc{gnats} 3.1xx, note that the @samp{-d}
option has changed its meaning: it does not give the directory of the
database, but its name.  (In case you prefer the long form of the
option, it is now @samp{--database} instead of @samp{--directory}.)

If your @sc{gnats} sits behind a firewall and needs to exchange mails
with the outside world, see also @ref{Outgoing mail bounces}.

@end enumerate


@node Renaming a Category
@comment  node-name,  next,  previous,  up
@subsection How do I rename a category?

Renaming a category requires to touch every PR in that category,
because each report contains the name of its category.

To rename category @code{A} to @code{B}, proceed as follows:

@enumerate
@item
Create a new category @code{B}.

@item
Edit every report in category @code{A}, changing its category to
@code{B}.
This can be done with any @sc{gnats} client; check the archives
of the @sc{help-gnats} mailing list for hints about automating
this step.

@item
Run @code{gen-index} (@pxref{gen-index,,Regenerating the
index,gnats,Keeping Track}) to refresh the @file{index} file.

@item
If you are using @sc{gnats} 4 (or planning to upgrade soon), you
should not remove the category @code{A}.  When a follow-up to an
existing PR arrives via e-mail, @sc{gnats} 4.x checks that both
the category and the PR number indicated in the mail exist (this
is a sanity check).

To reduce the risk of new reports being filed to category
@code{A}, change its description in the @file{categories} file to
something like @samp{obsolete, use category @code{B} instead}.

@end enumerate

@node Changing Fields
@comment  node-name,  next,  previous,  up
@subsection How do I add, remove, or rename a PR field?

@noindent
@b{A: (@sc{gnats} 3.1xx)} The fields and their names are fixed in
@sc{gnats} 3.1xx, so this is not possible.

@noindent
@b{A: (@sc{gnats} 4.x)} Edit the file @file{dbconfig} to reflect your
changes.

Note that the PR fields with the builtin-names @code{severity},
@code{priority} and @code{state} are required if you want automatic
reminders (@code{notify-about-expired-prs = true}).  In this case, the
file @file{submitters} must also contain a response time.
@c The reminder is filed if:
@c - "response time" is not -1, and
@c - @code{notify-about-expired-prs} = true, and
@c - (@code{severity} = @code{critical})
@c   or ( @code{severity} = @code{serious}
@c        and @code{priority} = @code{high} )
The @code{severity} field is checked for values @code{critical} and
@code{serious}, and @code{priority} for value @code{high}.
This is currently not configurable.


@node Gnatsd
@comment  node-name,  next,  previous,  up
@section Gnatsd, the @sc{gnats} Daemon

@cindex server, see gnatsd
@cindex @sc{gnats} server, see gnatsd
@cindex gnatsd

@menu
* Port Number::                 How to connect to gnatsd
* Starting gnatsd::             How to make gnatsd accept connections
* Gnatsd messages::             Some error messages and what they mean
@end menu

@node Port Number
@comment  node-name,  next,  previous,  up
@subsection Gnatsd Port Number

@cindex port
@cindex server port

In 3.xxx versions, gnatsd uses port 1529 by default; as this port is
officially assigned to another application (see the
@uref{http://www.iana.org/assignments/port-numbers,list of port numbers}
maintained by the @uref{http://www.iana.org/,Internet Assigned Numbers
Authority})
@c there is no default port
@c anymore in 4.x (you have to create an entry in @w{@file{/etc/services}}).
it will probably change in 4.x.

If you want/need to run gnatsd on another port, you can change the
default port at compile time (call @code{configure --help} to learn
about compile time configuration options).  Most clients also accept
an option or configuration variable to change the port.  Don't forget
to tell inetd (or xinetd, or whatever super-server you use) to start
gnatsd on the other port.


@node Starting gnatsd
@comment  node-name,  next,  previous,  up
@subsection How to Start Gnatsd

Gnatsd is intended to be started by some "super server", like
@code{inetd} or @code{xinetd}.  ("Super servers" are sometimes also
called "super daemons".)

This is also described in the @sc{gnats} manual; see @ref{Installing the
daemon,,Installing the daemon,gnats,Keeping Track}.

@menu
* inetd configuration::         The traditional super server
* xinetd configuration::        Another widespread super server
@end menu

@node inetd configuration
@comment  node-name,  next,  previous,  up
@subsubheading How to configure inetd to start gnatsd

@cindex inetd

If your gnatsd will be started by inetd (the "internet daemon"),
add the following entry to your @w{@file{/etc/inetd.conf}}:

@smallexample
# port                    userid program
support stream tcp nowait gnats /usr/local/libexec/gnats/gnatsd gnatsd
@end smallexample

@noindent
and to @w{@file{/etc/services}}:
@smallexample
support		1529/tcp		# GNATS
@end smallexample

@noindent
(You may need to use tabulator characters to separate the fields of
@w{@file{/etc/services}}.)  Then send inetd a hangup signal
(@w{@code{kill -HUP @emph{pid-of-inetd}}}).

You may want to use another port instead of 1529 (@pxref{Port Number}).



@node xinetd configuration
@comment  node-name,  next,  previous,  up
@subsubheading How to configure xinetd to start gnatsd

@cindex xinetd

If your gnatsd will be started by xinetd (the "extended internet
daemon"), create a file @w{@file{/etc/xinetd.d/support}} with the
following lines (@pxref{Installing the daemon,,Installing the
daemon,gnats,Keeping Track}):

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

@noindent
or add theses lines to your @w{@file{xinetd.conf}} file, whatever is
appropriate.  The equal signs seem to need spaces around them with
some versions of xinetd.

You need to add
@smallexample
support		1529/tcp		# GNATS
@end smallexample

@noindent
to @w{@file{/etc/services}} (it may be necessary to use tabulator
characters to separate the fields), and to tell xinetd to reread its
configuration (@code{kill -HUP @emph{pid-of-xinetd}}).


@node Gnatsd messages
@comment  node-name,  next,  previous,  up
@subsection Gnatsd Messages

@menu
* No host access for stdin::    Error when starting gnatsd manually
* No host access for remote::   Cannot connect from another machine
@end menu

@node No host access for stdin
@comment  node-name,  next,  previous,  up
@subsubheading You are not on the host access list: stdin (stdin)

@b{Q:} When starting gnatsd manually (on the command line), I get
@samp{520 You are not on the host access list: stdin (stdin)}.

@b{A: (@sc{gnats} 3.1xx)}
Gnatsd is not intended to be started manually, but via inetd,
xinetd, or a similar "super server".  When gnatsd is started this way,
its stdin and stdout (standard input and standard output streams) are
connected to a so called "TCP socket" (one end of the network
connection), and from this socket gnatsd learns the IP address of the
remote end (and from this it derives the remote host name).  When you
start gnatsd from the command line, its stdin and stdout are connected
to the terminal, and thus gnatsd gets a nonsense value.

You usually need @samp{root} privileges in order to change the
configuration of your "super server".  If you don't have them, contact
your system administrator.

See @ref{Starting gnatsd} for inetd and xinetd configuration.


@b{A: (@sc{gnats} 4.0)}
This error message should not occur with gnatsd 4.0 anymore, because
gnatsd can be started from the command line.
However, this probably only makes sense for debugging and diagnosing
problems.  Furthermore, you need to play the part of the client
program yourself (i.e., you must "speak" the gnatsd client protocol).



@node No host access for remote
@comment  node-name,  next,  previous,  up
@subsubheading You are not on the host access list

@b{Q:} Gnatsd rejects connections from a remote host with the error
message @samp{520 You are not on the host access list}.

@b{A:} Check the file @w{@file{gnatsd.host_access}}; if you are using
the default locations, this is
@w{@file{/usr/local/etc/gnats/gnatsd.host_access}}.
(If you are still using @sc{gnats} 3.xxx, the file is named
@w{@file{gnatsd.conf}}; its default place is
@w{@file{/usr/local/etc/gnatsd.conf}}.)

Each line of the file names a host and its access level, separated by
colons.  Gnatsd tries the lines in turn to match the remote host, and
the first line that matches wins.

The first field specifies the host(s); it may be a host name (like
@samp{goedel.example.com}), a partial domain (like
@samp{*.example.com}), an IP address (like @samp{192.168.1.5}), or a
partial IP address (like @samp{192.168.*}).  If it is only @samp{*}, it
matches all hosts.

Depending on how IP addresses are mapped to hostnames on your gnatsd
machine, you may be able to omit the domain (like in @samp{goedel}).
You may even @emph{need} to omit the domain for some hosts.

The second field is the access level granted to the remote host.  This
is usually increased by the access level granted to the user as soon
as (s)he logs in.

The third field is currently not used; just leave it empty (but supply
the colon between the second and the third field).

Example:

@example
@cartouche
#
# This is a comment
#
# Grant view access to all hosts with IP addresses
# ranging from 192.168.0.0 to 192.168.255.255:
192.168.*:view:
# Users on host goedel.example.com get (at least) edit access:
goedel.example.com:edit:
# Users from escher.example.com may view all reports, even
# confidential ones:
escher.example.com:viewconf:
# Users from bach.example.com may only view all non-confidential
# reports:
bach.example.com:view:
# Users from other example.com hosts
# only get the access specified for them in gnatsd.user_access:
*.example.com:none:
# Same for domain our-users.example:
*.our-users.example:none:
# All other hosts are rejected
# without even asking for username and password:
*:deny:
@end cartouche
@end example

The format is described in detail in the comments at the beginning of
the file.


@node E-Mail, Miscellaneous, Gnatsd, Configuration
@comment  node-name,  next,  previous,  up
@section E-Mail Issues

@menu
* queue-pr not available::      Sendmail refuses to run queue-pr
* Outgoing mail bounces::       Mail system complains on outgoing mail
@end menu

@node queue-pr not available, Outgoing mail bounces, E-Mail, E-Mail
@comment  node-name,  next,  previous,  up
@subsubheading queue-pr not available for sendmail programs

Your sendmail installation uses @samp{smrsh} to check programs that are
invoked from a mail alias.  @samp{smrsh} only allows the execution of
programs of which it is told that they are save.  To tell it that
@file{queue-pr} is save, create a symbolic link in the directory
@w{@file{/etc/smrsh}} to @file{queue-pr}, like this:

@smallexample
mkdir /etc/smrsh	@r{# if it does not yet exist}
cd /etc/smrsh
ln -s /usr/local/libexec/gnats/queue-pr queue-pr
@end smallexample

@noindent
Replace @w{@file{/usr/local/libexec/gnats/queue-pr}} by the real path to
@file{queue-pr}.


@node Outgoing mail bounces,  , queue-pr not available, E-Mail
@comment  node-name,  next,  previous,  up
@subsubheading Mail from @sc{gnats} bounces

You are getting bounce mails like this:

@example
   ----- Transcript of session follows -----
... while talking to mail.example.com.:
>>> MAIL From:<gnats@@mymachine.subdomain.example.com> SIZE=334
<<< 501 5.1.8 <gnats@@mymachine.subdomain.example.com>...
      Domain of sender address gnats@@mymachine.subdomain.example.com does not exist
@end example

Probably your @sc{gnats} sits behind a firewall, but it needs to
exchange mails with the world outside the firewall.  Make sure that
@var{GNATS_ADDR} is valid outside.

This is what probably happens behind the scenes: On its way to the
outside world, the sender address of the mail gets rewritten to
something "official" (like @code{Hans-Albert.Schneider@@example.com}, as
opposed to @code{me@@mymachine.subdomain.example.com}).  This is
especially necessary if the internal hosts are not visible outside.  If
your outgoing mail gateway still sees the internal address, it complains
with a message like the above (it has probably checked
@code{mymachine.subdomain.example.com} with your organization's external
DNS server, which does not know @code{mymachine}).

To solve this problem, get an "official" address for your @sc{gnats}
system, e.g., tool-bugs@@example.com, and use that one for
@var{GNATS_ADDR}.



@node Miscellaneous
@comment  node-name,  next,  previous,  up
@section Miscellaneous Configuration Issues

@menu
* No New Reports::              New reports do not show up in the database
* Initially Assign Field Values::  If you want to set additional fields when
                                   entering a report
@end menu

@node No New Reports, Initially Assign Field Values, Miscellaneous, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsubheading New reports do not show up in the database

@enumerate
@item
Make sure you have set up the mail aliases for your database(s).  (See
@ref{Add a database} and @ref{mkdb,,Adding another
database,gnats,Keeping Track}.)

@item
Try to send a PR using @samp{send-pr}.  If you get error replies,
investigate the causes.  See @ref{E-Mail}.

@item
Does a new file show up in the @w{@file{gnats-queue}} directory of your
database, with the report as its contents?
If it does, make sure you have created the cron job for this database.

@item
If the report does not show up in the @w{@file{gnats-queue}} of the desired
database, does it show up in the @w{@file{gnats-queue}} directory of another
database?
In this case, make sure your mail aliases are set up correctly;
especially, make sure that you have specified the correct
@samp{--directory} option (@samp{--database} for @sc{gnats} 4.x)
for each @file{queue-pr}.

@end enumerate


@node     Initially Assign Field Values,  , No New Reports, Miscellaneous
@comment  node-name,  next,  previous,  up
@subsubheading Assigning responsible etc. when entering a report

@b{Q:} When entering a new PR, I want to assign a value to some field
(e.g., @code{Responsible}) which is normally assigned by @sc{gnats}.

@b{A: (@sc{gnats} 3.1xx)}
This is not possible in @sc{gnats} 3.1xx.

@b{A: (@sc{gnats} 4.x)} This is done by adding the field name (in this
example, @code{Responsible}) to the @w{@code{initial-entry}} item at
the very end of the @file{dbconfig} file.  Gnatsweb will pick this up
and add a @code{Responsible} field to the Create PR form.



@node     Clients
@comment  node-name,  next,  previous,  up
@chapter  Client Software

Several client applications can be found in the @sc{gnats} distribution.
The most important are Gnatsweb (a WWW interface to @sc{gnats}), TkGnats (a
Tcl/Tk based interface), a @sc{gnats} mode for Emacs and XEmacs, and send-pr
(the traditional command line interface that sends a PR by e-mail).


@menu
* Gnatsweb::                    a WWW interface to @sc{gnats}
* TkGnats::                     a Tcl/Tk based client
* Emacs mode::                  for (X)Emacs enthusiasts
* send-pr::                     traditional command line interface
@end menu

@node     Gnatsweb
@comment  node-name,  next,  previous,  up
@section Gnatsweb

See also @ref{Gnatsweb and GNATS} in the chapter on @ref{Installation}.

@menu
* Gnatsweb Login Questions::    Problems logging in to Gnatsweb
@end menu

@c @node General Gnatsweb Questions
@comment  node-name,  next,  previous,  up
@c @subsection General Gnatsweb Questions


@node Gnatsweb Login Questions
@comment  node-name,  next,  previous,  up
@subsection Login Questions

@menu
* What to enter::               What to enter at login
* Login Not Remembered::        Reasons why Gnatsweb forgets your login
* Cookies::                     What Gnatsweb stores in its cookies
@end menu

@node What to enter
@comment  node-name,  next,  previous,  up
@subsubheading What should be entered as login information?

@b{A:} If you get an HTML form asking you to enter username, password,
and database, use what your gnats administrator has told you.  In this
case, your authentication data is checked with gnatsd's own user
database.

If your browser gives you a window asking for username and password (or
for "credentials"), the authentication is done by the WWW server.  You
should have got the necessary data either from your gnats administrator,
or from the webmaster of the site offering Gnatsweb access.


@node Login Not Remembered
@comment  node-name,  next,  previous,  up
@subsubheading Login data are not remembered

@b{Q:} After logging in via Gnatsweb, the main screen is displayed,
but whatever action is selected (whatever button is clicked), the login
screen gets displayed again.

@b{A:} This is usually a problem of cookies getting ignored.  Gnatsweb
uses cookies to store the login information (see "Gnatsweb and Cookies"
below).  Configure your web browser to allow the cookies Gnatsweb tries
to set.


@b{Q:} There is not even the main screen, the user immediately gets
the login screen when trying to log in.  The login data entered is
correct.  It works fine on another machine and for other users.

@b{A:} This has actually been reported only once; but as the effect is
similar to the previous one, it is included in the FAQ.  It apparently
was related to very strict security settings, but has not been
investigated in detail.


@node Cookies
@comment  node-name,  next,  previous,  up
@subsubheading Gnatsweb and Cookies

@cindex cookies

@b{Q:} Wait a moment!  Cookies?  Can I eat them?

@b{A:} No, not these.  The cookies about which we are talking here are
little data packages that a web-server sends to your browser (in our
case, on behalf of Gnatsweb) and your browser sends them back to the
server next time.  Modern browsers give you the option to generally
accept or reject cookies, or to be asked whenever a cookie arrives (some
even can make this decision based on the web-server).  To learn more
about cookies, visit, e.g., @uref{http://www.cookiecentral.com/,the
Cookie Central}.


@b{Q:} So, which cookies does Gnatsweb send, and why?

@b{A:} Gnatsweb uses a cookie @code{gnatsweb-db-}@emph{database_name} to
store your login information (username, password), and a cookie
@code{gnatsweb-global} to store the @sc{gnats} database you are working on,
your e-mail address (to fill it in for you when you create a new report
or reply to an existing report), a default list of fields to display in
search results, and defaults for @code{Submitter-Id} and
@code{Originator} fields.

Gnatsweb also sets a cookie for each "saved query" (named
@code{gnatsweb-query-}@emph{queryname}).

It is therefore essential that you allow Gnatsweb to set its cookies.
For a typical effect of rejecting them, see @ref{Login Not Remembered}.


@node     TkGnats
@comment  node-name,  next,  previous,  up
@section TkGnats

To be completed.


@node     Emacs mode
@comment  node-name,  next,  previous,  up
@section  @sc{gnats} Mode for Emacs

The Emacs mode is in the file gnats.el

@menu
* XEmacs::                      Does it also work for XEmacs?
@end menu


@node XEmacs,  , Emacs mode, Emacs mode
@comment  node-name,  next,  previous,  up
@subsubheading Does it also work for XEmacs?

@b{A: (@sc{gnats} 3.1xx)} Yes.

@b{A: (@sc{gnats} 4.x)} Still to be tested.


@node     send-pr
@comment  node-name,  next,  previous,  up
@section send-pr

A simple command line tool that sends a report via electronic mail.
This is not contributed software, but part of @sc{gnats} itself.

The 3.xxx versions do not support multiple databases.

@c You can try to work around this by installing a separate send-pr for
@c each database, with the appropriate e-mail address and category list.


To be completed.


@node     Glossary
@comment  node-name,  next,  previous,  up
@appendix Glossary

@table @dfn
@item cookie
A chunk of data that a WWW server stores in your browser.  It is sent
back to the server when you contact it again.  Gnatsweb (see
@ref{Gnatsweb}) uses cookies to store your login information,
preferences, and named queries.

@item gnats.el
@sc{gnats} mode for (X)Emacs.

@item gnatsd
The @sc{gnats} daemon (server program).

@item Gnatsweb
A WWW interface to @sc{gnats}.

@item port
A communication endpoint of various IP based protocols, notably TCP and
UDP.  A server program waits for connections ("listens") on a port, and
a client program connects to this port.
@uref{http://www.iana.org/,IANA} (the Internet Assigned Numbers
Authority) maintains a
@uref{http://www.iana.org/assignments/port-numbers,list of port numbers}
registered for certain purposes.

@item PR
Short for ``Problem Report''.  An entry in a @sc{gnats} database.

@item send-pr
A command line tool that sends a new report by e-mail.

@item super server
A super server (sometimes also called "super daemon") is a daemon (=
UNIX server process) that waits for connections on the ports of various
server programs and starts the corresponding server when a connection is
made.  This way, there is only one server process for a set of services
(instead of one for each service), but each service in the set is
available to its clients.

The most common super servers are @code{inetd} (the "InterNET Daemon"
that comes with many UNIX installations) and
@uref{http://www.xinetd.org,xinetd} (the "eXtended InterNET Daemon").

@item TkGnats
A Tcl/Tk based interface to @sc{gnats}.
@end table


@node    Index
@comment node-name,    next,  previous,      up
@unnumbered Index

@printindex cp

@bye
@c  LocalWords:  ifinfo savannah
