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: exec-prefix,  Next: gnats-adm,  Prev: prefix,  Up: Locations

EXEC-PREFIX
===========

   EXEC-PREFIX corresponds to the variable `exec-prefix' for
`configure', which passes it on to the `Makefile' it creates.
EXEC-PREFIX sets the root installation for "host-dependent" files as
follows:

GNATS user tools
     `EXEC-PREFIX/bin'

administrative and support utilities
     `EXEC-PREFIX/libexec/gnats'

compiled libraries
     `EXEC-PREFIX/lib'
_etc..._
   `configure' supports several more options which allow you to specify
in great detail where different files are installed.  The locations
given in this appendix do not take into account highly customized
installations, but fairly ordinary GNATS installations should be
covered by the material here.  For a complete list of options accepted
by `configure', run `./configure --help' in the `gnats' subdirectory of
the distribution.

   Since most installations are not intended to be distributed around a
network, the default value for EXEC-PREFIX is the value of `prefix',
i.e., `/usr/local'.  However, using EXEC-PREFIX saves space when you
are installing a package on several different platforms for which many
files are identical; rather than duplicate them for each host, these
files can be shared in a common repository, and you can use symbolic
links on each host to find the host-dependent files.

   Use EXEC-PREFIX in conjunction with PREFIX to share host-independent
files, like libraries and `info' documents.  For example:

        _for each host:_
     configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-HOST
     make all install ...

Using this paradigm, all host-dependent binary files are installed into
`/usr/gnu/H-HOST/bin', while files which do not depend on the host type
for which they were configured are installed into `/usr/gnu'.

   You can then use a different symbolic link for `/usr/gnu' on each
host (`/usr' is usually specific to a particular machine; it is always
specific to a particular architecture).

       _on host-1:_
     ln -s /usr/gnu/H-HOST-1 /usr/gnu
       _on host-2:_
     ln -s /usr/gnu/H-HOST-2 /usr/gnu

To the end user, then, placing `/usr/gnu/bin' in her or his `PATH'
simply works transparently for each HOST type.

   You can change EXEC-PREFIX on the command line to `configure' using

     configure --exec-prefix=EXEC-PREFIX ...

   We recommend that you consult *Note Using `configure':
(configure)Using configure, before attempting this.


File: gnats.info,  Node: gnats-adm,  Next: defaults,  Prev: exec-prefix,  Up: Locations

The `gnats-adm' directory
=========================

   Each GNATS database located on a server has its own directory, as
listed in the `databases' (*note The `databases' file: databases file.
and given when the `mkdb' utility is invoked to initialize the database
(*note Initializing a new database: mkdb.).  This directory has several
subdirectories, one of which is named `gnats-adm'.  This directory
contains all configuration files related to this specific database,
including the `categories', `submitters', `responsible', `states',
`classes', `dbconfig', `addresses', `states' and `gnatsd.user_access',
as well as two files generated and maintained by GNATS, `index' and
`current'.


File: gnats.info,  Node: defaults,  Prev: gnats-adm,  Up: Locations

Default installation locations
==============================

PREFIX
     defaults to `/usr/local'; change using `configure' (*note
     Configuring and compiling the software: Configure and make.).

EXEC-PREFIX
     defaults to PREFIX; change using `configure' (*note Configuring
     and compiling the software: Configure and make.).

GNATS installs tools, utilities, and files into the following locations.

`EXEC-PREFIX/bin'

    `send-pr'
          *Note Submitting Problem Reports: send-pr.

    `edit-pr'
          *Note Editing existing Problem Reports: edit-pr.

    `query-pr'
          *Note Querying the database: query-pr.

`EXEC-PREFIX/libexec/gnats'

    `at-pr'
          *Note Timely reminders: at-pr.

    `check-db'
          *Note Checking database health: check-db.

    `delete-pr'
          Tool for deleting PRs.  Deprecated.  Use the -delete-pr
          option of `pr-edit' instead (*note The edit-pr driver:
          pr-edit.).

    `diff-prs'
          *Note The `diff-prs' tool: diff-prs.

    `file-pr'
          *Note Interface to pr-edit for filing new PRs: file-pr.

    `gen-index'
          *Note Regenerating the index: gen-index.

    `gnatsd'
          The GNATS daemon.

    `gnats-pwconv'
          *Note Converting old password files: gnats-pwconv.

    `mail-query'
          *Note Setting up mail aliases: Aliases.

    `mkcat'
          *Note Adding a problem category: mkcat.

    `mkdb'
          *Note Script for creating new databases: mkdb.

    `pr-age'
          *Note The `pr-age' tool: pr-age.

    `pr-edit'
          *Note The main PR processor: pr-edit.

    `queue-pr'
          *Note Handling incoming traffic: queue-pr.

    `rmcat'
          *Note Removing categories: rmcat.

`EXEC-PREFIX/lib/libiberty.a'
     The GNU `libiberty' library.

`PREFIX/etc/gnats'

    `databases'
          *Note The `databases' file: databases file.

    `defaults'
          *Note Overview of GNATS configuration: GNATS configuration.

    `gnatsd.host_access'
          *Note The `gnatsd.host_access' file: gnatsd.host_access.

    `gnatsd.user_access'
          *Note The `gnatsd.user_access' file: gnatsd.user_access.

`PREFIX/share/emacs/site-lisp'

    `gnats.el'
    `gnats.elc'
          The Emacs versions of the programs `send-pr', `query-pr',
          `edit-pr', and `view-pr'.  *Note The GNATS user tools: GNATS
          user tools.  To change this directory you must change the
          `lispdir' variable in `Makefile.in'; see *Note Configuring
          and compiling the software: Configure and make.

`PREFIX/info'

    `gnats.info'
    `send-pr.info'
          The GNATS manuals, in a form readable by `info' (the GNU
          hypertext browser).  *Note Reading GNU Online Documentation:
          (infoman)Info.

`PREFIX/man/man1'
`PREFIX/man/man8'

    `man' pages for all the GNATS tools and utilities.
          *Note The GNATS user tools: GNATS user tools.

`Per-database directory'

    `gnats-adm'
          Administration and configuration data files that define
          behaviour of the particular database.  The files

         `categories'

         `submitters'

         `responsible'

         `states'

         `classes'

         `dbconfig'

         `addresses'

         `states'

         `gnatsd.user_access'

         `index'
               (_This file is created by GNATS._)

         `current'
               (_This file is created by GNATS._)

          exist here.  *Note Other database-specific config files:
          Other config files, *Note Administrative data files: Admin
          files and *Note Controlling access to databases: Access
          Control.

    `gnats-queue'
          Incoming Problem Reports are queued here until the next
          iteration of `queue-pr -r' (*note Handling incoming traffic:
          queue-pr.).

    `pending'
          If no default category is set, problem reports without a
          category are reassigned to the category `pending' and placed
          here pending intervention by GNATS administrators.  *Note
          GNATS administration: Management.

    `CATEGORY'
          Each valid category has a corresponding subdirectory in the
          database.  All Problem Reports associated with that category
          are kept in that subdirectory.


File: gnats.info,  Node: gnatsd,  Next: Access Control,  Prev: Locations,  Up: Top

The GNATS network server - `gnatsd'
***********************************

   This section describes in details how the GNATS network daemon
works.  This information is mainly assumed to be useful for developers
of GNATS client software.

* Menu:

* Description of gnatsd::
* gnatsd options::
* gnatsd command protocol::
* gnatsd commands::
* gnatsd environment variables::


File: gnats.info,  Node: Description of gnatsd,  Next: gnatsd options,  Up: gnatsd

Description of `gnatsd'
=======================

   The `gnatsd' network daemon is used to service remote GNATS requests
such as querying PRs, PR creation, deletion, and editing, and
miscellaneous database queries.  It uses a simple ASCII-based command
protocol (similar to SMTP or POP3) for communicating with remote
clients.

   It also provides a security model based either on IP-based
authentication (generally considered very weak) or username/passwords,
where passwords may be in cleartext, UNIX crypt or MD5 hash format.
Access through `gnatsd' is granted according to certain predefined
"access levels".  Access levels are further discussed in *Note
Controlling access to databases: Access Control.  It should be
emphasized that security has not been a focus of development until now,
but future versions are expected to address this more thoroughly.

   All of the GNATS clients are capable of communicating via the GNATS
remote protocol to perform their functions.

   `gnatsd' is usually started from the inetd facility and should run as
the `gnats' user (the actual username of this user is configurable
during installation, *note Configuring and compiling the software:
Configure and make. for details.)


File: gnats.info,  Node: gnatsd options,  Next: gnatsd command protocol,  Prev: Description of gnatsd,  Up: gnatsd

`gnatsd' options
================

   The daemon supports the following command-line options:

     gnatsd [--database database | -d database]
            [--not-inetd | -n] [--max-access-level LEVEL | -m LEVEL]
            [--version | -V] [--help | -h]

`-V, --version'
     Prints the program version to stdout and exits.

`-h, --help'
     Prints a short help text to stdout and exits.

`-d, --database'
     Specifies the default database which is to be serviced by this
     invocation of `gnatsd'. (The selected database may be changed via
     the `CHDB' command; the name set with this option is simply the
     default if no `CHDB' command is issued.)  If no database is
     specified, the database named default is assumed. This option
     overrides the database specified in the `GNATSDB' environment
     variable.

`-n, --not-inetd'
     As its name suggests, indicates that `gnatsd' is not being invoked
     from inetd. This can be used when testing `gnatsd', or if it is
     being run via ssh or some other mechanism.

     This has the effect of using the local hostname where `gnatsd' is
     being invoked for authentication purposes, rather than the remote
     address of the connecting client.

`--max-access-level, -m'
     Specifies the maximum access level that the connecting client can
     authenticate to.  Authentication is as normal but if the user or
     host authenticates at a higher level, access level is still forced
     to this level.  See *Note Controlling access to databases: Access
     Control for details on access levels.


File: gnats.info,  Node: gnatsd command protocol,  Next: gnatsd commands,  Prev: gnatsd options,  Up: gnatsd

`gnatsd' command protocol
=========================

   Commands are issued to `gnatsd' as one or more words followed by a
carriage-return/linefeed pair.  For example, the `CHDB' (change
database) command is sent as `CHDB database<CR><LF>' (the `CRLF' will
not be explicitly written for future examples.)

   Replies from `gnatsd' are returned as one or more response lines
containing a 3-digit numeric code followed by a human-readable string;
the line is terminated with a `<CR><LF>' pair.  For example, one
possible response to the `CHDB' command above would be:

     210 Now accessing GNATS database 'database'.

   The three-digit code is normally followed by a single ASCII space
(character 0x20).  However, if additional response lines are to be
returned from the server, there will be a single dash `-' instead of
the space character after the three-digit code.

   Response code values are divided into ranges.  The first digit
reflects the general type of response (such as "successful" or
"error"), and the subsequent digits identify the specific type of
response.

CODES 200-299
     Positive response indicating that the command was successful.  No
     subsequent data will be transmitted with the response.  In
     particular, code 210 (`CODE_OK') is used as the positive result
     code for most simple commands.

     Commands that expect additional data from the client (such as
     `SUBM' or `VFLD') use a two-step mechanism for sending the data.
     The server will respond to the initial command with either a 211
     (`CODE_SEND_PR') or 212 (`CODE_SEND_TEXT') response line, or an
     error code if an error occurred with the initial command.  The
     client is then expected to send the remaining data using the same
     quoting mechanism as described for server responses in the 300-349
     range.  The server will then send a final response line to the
     command.

CODES 300-399
     Positive response indicating that the query request was
     successful, and that a PR or other data will follow.  Codes
     300-349 are used when transmitting PRs, and 350-399 are used for
     other responses.

     Codes in the 300-349 range are followed by a series of
     `CRLF'-terminated lines containing the command response, usually a
     PR.  The final line of the result is a single period `.'.  Result
     lines that begin with a period have an extra period prepended to
     them.

     Codes in the 350-399 range use a different scheme for sending their
     responses. The three-digit numeric code will be followed by either
     a dash `-' or a single space.  If the code is followed by a dash,
     that indicates that another response line will follow.  The final
     line of the response has a single space after the three-digit code.

     In previous versions of the protocol the first line of a
     `CODE_INFORMATION' (310) response was to be ignored.  This is no
     longer the case.  Instead, any lines marked with code
     `CODE_INFORMATION_FILLER' (351) are to be ignored.  This allows the
     server to transmit additional headers or other human-readable text
     that can be safely ignored by the clients.

CODES 400-599
     An error occurred, usually because of invalid command parameters or
     invalid input from the client, missing arguments to the command,
     or a command was issued out of sequence.  The human-readable
     message associated with the response line describes the general
     problem encountered with the command.

     Multiple error messages may be returned from a command; in this
     case the `-' continuation character is used on all but the last
     response line.

CODES 600-799
     An internal error occurred on the server, a timeout occurred
     reading data from the client, or a network failure occurred.
     These errors are of the "this should not occur" nature, and
     retrying the operation may resolve the problem.  Fortunately, most
     GNATS transactions are idempotent; unfortunately, locking the
     database or a PR are not repeatable actions (we cannot determine
     if an existing lock is the one we originally requested, or someone
     else's).


File: gnats.info,  Node: gnatsd commands,  Next: gnatsd environment variables,  Prev: gnatsd command protocol,  Up: gnatsd

`gnatsd' commands
=================

   Note that the set of GNATS commands and their responses is somewhat
inconsistent and is very much in flux.  At present the GNATS clients
are rather simple-minded and not very strict about processing
responses.  For example, if the server were to issue a code 300
(`CODE_PR_READY') response to a `CHDB' command, the client would
happily expect to see a PR appear (and would print it out if one was
sent).

   It is thus suggested that any clients that use the GNATS protocol be
equally flexible about the way received responses are handled; in
particular, only the first digit of the response code should be assumed
to be meaningful, although subsequent digits are needed in some cases
(codes 300-399).  No attempt should be made to parse the message strings
on error response lines; they are only intended to be read by humans,
and will be changed on a regular basis.

   Almost every command may result in the response 440
(`CODE_CMD_ERROR').  This indicates that there was a problem with the
command arguments, usually because of insufficient or too many
arguments being specified.

   Access to most `gnatsd' commands requires a certain "access level".
For details of this, see *Note Privileged `gnatsd' commands: Privileged
gnatsd commands.

`USER [USERID PASSWORD]'
     Specifies the userid and password for database access.  Either
     both a username and password must be specified, or they both may
     be omitted; in the latter case, the current access level is
     returned.

     The possible server responses are:

     `350 (CODE_INFORMATION)'
     The current access level is specified.

     `422 (CODE_NO_ACCESS)'
     A matching username and password could not be found.

     `200 (CODE_OK)'
     A matching username and password was found, and the login was
     successful.

`QUIT'
     Requests that the connection be closed. Possible responses:

     `201 (CODE_CLOSING)'
     Normal exit.

     The `QUIT' command has the dubious distinction of being the only
     command that cannot fail.

`LIST LIST TYPE'
     Describes various aspects of the database.  The lists are returned
     as a list of records, one per line.  Each line may contain a
     number of colon-separated fields.

     Possible values for LIST TYPE include

     `Categories'
     Describes the legal categories for the database.

     `Submitters'
     Describes the set of submitters for the database.

     `Responsible'
     Lists the names in the responsible administrative file, including
     their full names and email addresses.

     `States'
     Lists the states listed in the state administrative file, including
     the state type (usually blank for most states; the closed state
     has a special type).

     `FieldNames'
     Lists the entire set of PR fields.

     `InitialInputFields'
     Lists the fields that _should_ be present when a PR is initially
     entered.

     `InitialRequiredFields'
     Lists fields that _have_ to be present and nonempty when a PR is
     initially entered (fields containing only blank characters such as
     spaces or newlines are considered empty.)

     `Databases'
     Lists the set of databases.

     The possible responses are:

     `301 (CODE_TEXT_READY)'
     Normal response, followed by the records making up the list as
     described above.

     `416 (CODE_INVALID_LIST)'
     The requested list does not exist.

`FTYP FIELD [FIELD ...]'
     Describes the type of data held in the field(s) specified with the
     command.  The currently defined data types are:

     `Text'
     A plain text field, containing exactly one line.

     `MultiText'
     A text field possibly containing multiple lines of text.

     `Enum'
     An enumerated data field; the value is restricted to one entry out
     of a list of values associated with the field.

     `MultiEnum'
     The field contains one or more enumerated values.  Values are
     separated with spaces or colons `:'.

     `Integer'
     The field contains an integer value, possibly signed.

     `Date'
     The field contains a date.

     `TextWithRegex'
     The value in the field must match one or more regular expressions
     associated with the field.

     The possible responses are:

     `350 (CODE_INFORMATION)'
     The normal response; the supplied text is the data type.

     `410 (CODE_INVALID_FIELD_NAME)'
     The specified field does not exist.

     If multiple field names were given, multiple response lines will be
     sent, one for each field, using the standard continuation
     protocol; each response except the last will have a dash `-'
     immedately after the response code.

`FTYPINFO FIELD PROPERTY'
     Provides field-type-related information.  Currently, only the
     property `separators' for MultiEnum fields is supported.  When
     `separators' is specified, the possible return codes are:

     `350 (CODE_INFORMATION)' A proper MultiEnum FIELD was specified
     and the returned text is the string of separators specified for
     the field in the dbconfig file (*note Field datatypes::) quoted in
     `'''s.

     `435 (CODE_INVALID_FTYPE_PROPERTY)' The `separators' property is
     not defined for this field, i.e.  the specified FIELD is not of
     type MultiEnum.

     Currently, specifying a different property than `separators'
     results in return code 435 as above.

`FDSC FIELD [FIELD ... ]'
     Returns a human-readable description of the listed field(s).  The
     possible responses are:

     `350 (CODE_INFORMATION)' The normal response; the supplied text is
     the field description.

     `410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.

     Like the `FVLD' command, the standard continuation protocol will be
     used if multiple fields were specified with the command.

`FIELDFLAGS FIELD [FIELD ... ]'
     Returns a set of flags describing the specified field(s).  The
     possible responses are either

     `410 (CODE_INVALID_FIELD_NAME)'
     meaning that the specified field is invalid or nonexistent, or

     `350 (CODE_INFORMATION)'
     which contains the set of flags for the field.  The flags may be
     blank, which indicate that no special flags have been set for this
     field.

     Like the `FDSC' and `FTYP' commands, multiple field names may be
     listed with the command, and a response line will be returned for
     each one in the order that the fields appear on the command line.

     The flags include:

     `textsearch'
     The field will be searched when a text field search is requested.

     `allowAnyValue'
     For fields that contain enumerated values, any legal value may be
     used in the field, not just ones that appear in the enumerated
     list.

     `requireChangeReason'
     If the field is edited, a reason for the change must be supplied in
     the new PR text describing the reason for the change. The reason
     must be supplied as a multitext PR field in the new PR whose name
     is `field-Changed-Why' (where `field' is the name of the field
     being edited).

     `readonly'
     The field is read-only, and cannot be edited.

`FVLD FIELD'
     Returns one or more regular expressions or strings that describe
     the valid types of data that can be placed in field.  Exactly what
     is returned is dependent on the type of data that can be stored in
     the field.  For most fields a regular expression is returned; for
     enumerated fields, the returned values are the list of legal
     strings that can be held in the field.

     The possible responses are:

     `301 (CODE_TEXT_READY)'
     The normal response, which is followed by the list of regexps or
     strings.

     `410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.

`VFLD FIELD'
     `VFLD' can be used to validate a given value for a field in the
     database.  The client issues the `VFLD' command with the name of
     the field to validate as an argument.  The server will either
     respond with `212 (CODE_SEND_TEXT)', or `410
     (CODE_INVALID_FIELD_NAME)' if the specified field does not exist.

     Once the `212' response is received from the server, the client
     should then send the line(s) of text to be validated, using the
     normal quoting mechanism described for PRs.  The final line of
     text is followed by a line containing a single period, again as
     when sending PR text.

     The server will then either respond with `210 (CODE_OK)',
     indicating that the text is acceptable, or one or more error codes
     describing the problems with the field contents.

`INPUTDEFAULT FIELD [FIELD ... ]'
     Returns the suggested default value for a field when a PR is
     initially created.  The possible responses are either `410
     (CODE_INVALID_FIELD_NAME)', meaning that the specified field is
     invalid or nonexistent, or `350 (CODE_INFORMATION)' which contains
     the default value for the field.

     Like the `FDSC' and `FTYP' commands, multiple field names may be
     listed with the command, and a response line will be returned for
     each one in the order that the fields appear on the command line.

`RSET'
     Used to reset the internal server state.  The current query
     expression is cleared, and the index of PRs may be reread if it
     has been updated since the start of the session.  The possible
     responses are:

     `200 (CODE_OK)'
     The state has been reset.

     `440 (CODE_CMD_ERROR)'
     One or more arguments were supplied to the command.

     `6xx (internal error)'
     There were problems resetting the state (usually because the index
     could not be reread).  The session will be immediately terminated.

`LKDB'
     Locks the main GNATS database.  No subsequent database locks will
     succeed until the lock is removed.  Sessions that attempt to write
     to the database will fail.  The possible responses are:

     `200 (CODE_OK)' The lock has been established.

     `440 (CODE_CMD_ERROR)' One or more arguments were supplied to the
     command.

     `431 (CODE_GNATS_LOCKED)' The database is already locked, and the
     lock could not be obtained after 10 seconds.

     `6xx (internal error)' An internal error occurred, usually because
     of permission or other filesystem-related problems. The lock may
     or may not have been established.

`UNDB'
     Unlocks the database.  Any session may steal a database lock; no
     checking of any sort is done.  The possible responses are:

     `200 (CODE_OK)'
     The lock has been removed.

     `432 (CODE_GNATS_NOT_LOCKED)'
     The database was not locked.

     `440 (CODE_CMD_ERROR)'
     One or more arguments were supplied to the command.

     `6xx (internal error)'
     The database lock could not be removed, usually because of
     permissions or other filesystem-related issues.

`LOCK PR USER [PID]'
     Locks the specified PR, marking the lock with the USER name and
     the optional PID. (No checking is done that the USER or PID
     arguments are valid or meaningful; they are simply treated as
     strings.)

     The `EDIT' command requires that the PR be locked before it may be
     successfully executed.  However, it does not require that the lock
     is owned by the editing session, so the usefulness of the lock is
     simply as an advisory measure.

     The `APPN' and `REPL' commands lock the PR as part of the editing
     process, and they do not require that the PR be locked before they
     are invoked.

     The possible responses are:

     `440 (CODE_CMD_ERROR)'
     Insufficient or too many arguments were specified to the command.

     `300 (CODE_PR_READY)'
     The lock was successfully obtained; the text of the PR (using the
     standard quoting mechanism for PRs) follows.

     `400 (CODE_NONEXISTENT_PR)'
     The PR specified does not exist.

     `430 (CODE_LOCKED_PR)'
     The PR is already locked by another session.

     `6xx (internal error)'
     The PR lock could not be created, usually because of permissions or
     other filesystem-related issues.

`UNLK PR'
     Unlocks PR.  Any user may unlock a PR, as no checking is done to
     determine if the requesting session owns the lock.

     The possible responses are:

     `440 (CODE_CMD_ERROR)'
     Insufficient or too many arguments were specified to the command.

     `200 (CODE_OK)'
     The PR was successfully unlocked.

     `433 (CODE_PR_NOT_LOCKED)'
     The PR was not locked.

     `6xx (internal error)'
     The PR could not be unlocked, usually because of permission or
     other filesystem-related problems.

`DELETE PR'
     Deletes the specified PR. The user making the request must have
     admin privileges (*note Controlling access to databases: Access
     Control.).  If successful, the PR is removed from the filesystem
     and the index file; a gap will be left in the numbering sequence
     for PRs.  No checks are made that the PR is closed.

     The possible responses are:

     `200 (CODE_OK)'
     The PR was successfully deleted.

     `422 (CODE_NO_ACCESS)'
     The user requesting the delete does not have admin privileges.

     `430 (CODE_LOCKED_PR)'
     The PR is locked by another session.

     `431 (CODE_GNATS_LOCKED)'
     The database has been locked, and no PRs may be updated until the
     lock is cleared.

     `6xx (internal error)'
     The PR could not be successfully deleted, usually because of
     permission or other filesystem-related problems.

`CHEK [initial]'
     Used to check the text of an entire PR for errors.  Unlike the
     `VFLD' command, it accepts an entire PR at once instead of the
     contents of an individual field.

     The `initial' argument indicates that the PR text to be checked is
     for a PR that will be newly created, rather than an edit or
     replacement of an existing PR.

     After the `CHEK' command is issued, the server will respond with
     either a `440 (CODE_CMD_ERROR)' response indicating that the
     command arguments were incorrect, or a `211 (CODE_SEND_PR)'
     response code will be sent.

     Once the `211' response is received from the server, the client
     should send the PR using the normal PR quoting mechanism; the
     final line of the PR is then followed by a line containing a
     single period, as usual.

     The server will then respond with either a `200 (CODE_OK)'
     response, indicating there were no problems with the supplied
     text, or one or more error codes listing the problems with the PR.

`EDIT PR'
     Verifies the replacement text for PR.  If the command is
     successful, the contents of PR are completely replaced with the
     supplied text.  The PR must previously have been locked with the
     `LOCK' command.

     The possible responses are:

     `431 (CODE_GNATS_LOCKED)'
     The database has been locked, and no PRs may be updated until the
     lock is cleared.

     `433 (CODE_PR_NOT_LOCKED)'
     The PR was not previously locked with the `LOCK' command.

     `400 (CODE_NONEXISTENT_PR)'
     The specified PR does not currently exist.  The `SUBM' command
     should be used to create new PRs.

     `211 (CODE_SEND_PR)'
     The client should now transmit the replacement PR text using the
     normal PR quoting mechanism.  After the PR has been sent, the
     server will respond with either `200 (CODE_OK)' indicating that
     the edit was successful, or one or more error codes listing
     problems either with the replacement PR text or errors encountered
     while updating the PR file or index.

`EDITADDR ADDRESS'
     Sets the e-mail address of the person communicating with `gnatsd'.
     The command requires at least the `edit' access level.

     The possible responses are:

     `200 (CODE_OK)'
     The address was successfully set.

     `440 (CODE_CMD_ERROR)'
     Invalid number of arguments were supplied.

`APPN PR FIELD'
`REPL PR FIELD'
     Appends to or replaces the contents of FIELD in PR with the
     supplied text.  The command returns a `201 (CODE_SEND_TEXT)'
     response; the client should then transmit the new field contents
     using the standard PR quoting mechanism.  After the server has
     read the new contents, it then attempts to make the requested
     change to the PR.

     The possible responses are:

     `200 (CODE_OK)'
     The PR field was successfully changed.

     `400 (CODE_NONEXISTENT_PR)'
     The PR specified does not exist.

     `410 (CODE_INVALID_FIELD_NAME)'
     The specified field does not exist.

     `402 (CODE_UNREADABLE_PR)'
     The PR could not be read.

     `431 (CODE_GNATS_LOCKED)'
     The database has been locked, and no PRs may be updated until the
     lock is cleared.

     `430 (CODE_LOCKED_PR)'
     The PR is locked, and may not be altered until the lock is cleared.

     `413 (CODE_INVALID_FIELD_CONTENTS)'
     The supplied (or resulting) field contents are not valid for the
     field.

     `6xx (internal error)'
     An internal error occurred, usually because of permission or other
     filesystem-related problems.  The PR may or may not have been
     altered.

`SUBM'
     Submits a new PR into the database.  The supplied text is verified
     for correctness, and if no problems are found a new PR is created.

     The possible responses are:

     `431 (CODE_GNATS_LOCKED)'
     The database has been locked, and no PRs may be submitted until the
     lock is cleared.

     `211 (CODE_SEND_PR)'
     The client should now transmit the new PR text using the normal
     quoting mechanism.  After the PR has been sent, the server will
     respond with either a `200 (CODE_OK)' response indicating that the
     new PR has been created (and mail sent to the appropriate
     persons), or one or more error codes listing problems with the new
     PR text.

`CHDB DATABASE'
     Switches the current database to the name specified in the command.

     The possible responses are:

     `422 (CODE_NO_ACCESS)'
     The user does not have permission to access the requested database.

     `417 (CODE_INVALID_DATABASE)'
     The database specified does not exist, or one or more configuration
     errors in the database were encountered.

     `220 (CODE_OK)'
     The current database is now DATABASE.  Any operations performed
     will now be applied to DATABASE.

`DBLS'
     Lists the known set of databases.

     The possible responses are:

     `6xx (internal error)'
     An internal error was encountered while trying to obtain the list
     of available databases, usually due to lack of permissions or other
     filesystem-related problems, or the list of databases is empty.

     `301 (CODE_TEXT_READY)'
     The list of databases follows, one per line, using the standard
     quoting mechanism.  Only the database names are sent.

     The `gnatsd' access level `listdb' denies access until the user
     has authenticated with the USER command.  The only other command
     available at this access level is `DBLS'.  This access level
     provides a way for a site to secure its GNATS databases while still
     providing a way for client tools to obtain a list of the databases
     for use on login screens etc.  *Note Controlling access to
     databases: Access Control.

`DBDESC DATABASE'
     Returns a human-readable description of the specified DATABASE.

     Responses include:

     `6xx (internal error)'
     An internal error was encountered while trying to read the list of
     available databases, usually due to lack of permissions or other
     filesystem-related problems, or the list of databases is empty.

     `350 (CODE_INFORMATION)'
     The normal response; the supplied text is the database description.

     `417 (CODE_INVALID_DATABASE)'
     The specified database name does not have an entry.

`EXPR QUERY EXPRESSION'
     Specifies a QUERY EXPRESSION used to limit which PRs are returned
     from the `QUER' command.  The expression uses the normal query
     expression syntax, (*note Query expressions::).

     Multiple `EXPR' commands may be issued; the expressions are boolean
     ANDed together.

     Expressions are cleared by the `RSET' command.

     Possible responses include:

     `415 (CODE_INVALID_EXPR)'
     The specified expression is invalid, and could not be parsed.

     `200 (CODE_OK)'
     The expression has been accepted and will be used to limit the
     results returned from `QUER'.

`QFMT QUERY FORMAT'
     Use the specified QUERY FORMAT to format the output of the `QUER'
     command.  The query format may be either the name of a query
     format known to the server (*note Named query definitions::), or an
     actual query format (*note Formatting query-pr output::).  The
     possible responses are:

     `200 (CODE_OK)'
     The normal response, which indicates that the query format is
     acceptable.

     `440 (CODE_CMD_ERROR)'
     No query format was supplied.

     `418 (CODE_INVALID_QUERY_FORMAT)'
     The specified query format does not exist, or could not be parsed.

`QUER [PR] [PR] [...]'
     Searches the contents of the database for PRs that match the
     (optional) specified expressions with the `EXPR' command. If no
     expressions were specified with `EXPR', the entire set of PRs is
     returned.

     If one or more PRs are specified on the command line, only those
     PRs will be searched and/or output.

     The format of the output from the command is determined by the
     query format selected with the `QFMT' command.

     The possible responses are:

     `418 (CODE_INVALID_QUERY_FORMAT)'
     A valid format was not specified with the `QFMT' command prior to
     invoking `QUER'.

     `300 (CODE_PR_READY)'
     One or more PRs will be output using the requested query format.
     The PR text is quoted using the normal quoting mechanisms for PRs.

     `220 (CODE_NO_PRS_MATCHED)'
     No PRs met the specified criteria.

`ADMV FIELD KEY [SUBFIELD]'
     Returns an entry from an administrative data file associated with
     FIELD. KEY is used to look up the entry in the data file. If
     SUBFIELD is specified, only the value of that subfield is
     returned; otherwise, all of the fields in the adm data file are
     returned, separated by colons `:'.

     The responses are:

     `410 (CODE_INVALID_FIELD_NAME)' The specified field does not exist.

     `221 (CODE_NO_ADM_ENTRY)' An adm entry matching the key was not
     found, or the field does not have an adm file associated with it.

     `350 (CODE_INFORMATION)' The normal response; the supplied text is
     the requested field(s).


File: gnats.info,  Node: gnatsd environment variables,  Prev: gnatsd commands,  Up: gnatsd

`gnatsd' environment variables
==============================

   `gnatsd' supports the `GNATSDB' environment varable, *Note
Environment::, in almost the same way as the GNATS tools do.  This
variable is used to determine which database to use.  For a local
database, it contains the name of the database to access. `gnatsd'
cannot service remote databases (though it might be interesting if it
could) so the database is always assumed to be local.

   If `GNATSDB' is not set and the `--database' option is not supplied,
it is assumed that the database is local and that its name is `default'.


File: gnats.info,  Node: Access Control,  Next: Regexps,  Prev: gnatsd,  Up: Top

Controlling access to databases
*******************************

* Menu:

* Overview::
* Overall gnatsd access level::
* gnatsd.host_access::           Per-host access settings
* gnatsd.user_access::           Access levels per user
* Privileged gnatsd commands::


File: gnats.info,  Node: Overview,  Next: Overall gnatsd access level,  Up: Access Control

Overview
========

   GNATS supports granting various levels of access to the GNATS
databases served by the network daemon, `gnatsd'.

   GNATS access can be controlled at these levels:

`deny'
     gnatsd closes the connection

`none'
     no further access until userid and password given

`listdb'
     only listing of available databases is allowed

`view'
     query and view PRs with Confidential=no only

`viewconf'
     query and view PRs with Confidential=yes

`edit'
     full edit access

`admin'
     full admin access

These access levels are used in the following settings:

   * overall gnatsd access level

   * overall access level set by host name or IP address

   * overall access level set by userid and password

   * per-database access level set by userid and password


File: gnats.info,  Node: Overall gnatsd access level,  Next: gnatsd.host_access,  Prev: Overview,  Up: Access Control

Overall `gnatsd' access level
=============================

The overall `gnatsd' access level is set by starting `gnatsd' with the
option

     `-m' LEVEL or `--maximum-access-level'=LEVEL,

where LEVEL is one of the six access levels listed above.  This
restricts any access to the GNATS daemon to levels up to and including
LEVEL, regardless of the settings in the access control files discussed
below.  If this option is left out, any access levels set in the access
control files will be allowed.

   The discussion below assumes that the pre-build configure of GNATS
was done without altering the default values for the
`--with-gnatsd-user-access-file' and `--with-gnatsd-host-access-file'
options.  If non-default values were given, substitute as appropriate
below.


File: gnats.info,  Node: gnatsd.host_access,  Next: gnatsd.user_access,  Prev: Overall gnatsd access level,  Up: Access Control

Overall access levels per host
==============================

   The host access file (by default
`/usr/local/etc/gnats/gnatsd.host_access') controls overall access
levels on a per-host basis, meaning that settings in this file apply
across all databases on the server.  Entries in this file are in the
following format:

   HOST:ACCESS-LEVEL:WHATEVER

HOST is the hostname or IP address of the host contacting gnatsd.
Wildcard characters are supported: `*' matches anything; `?' matches
any single character.  By using wildcards, you can specify access
levels for entire network subnets and domains.

   The second field is the access level of HOST.  The default is
`deny'.  If the user's hostname isn't in the file or its access level
is set to `deny', the connection is closed immediately.

   GNATS currently doesn't make use of the third field. Remember to
still include the second `:' on the line if you choose to leave the
third field empty.

   Whenever a `CHDB' command is processed (or defaulted), the user's
access level is set to the level for their host, as determined by the
values in the `gnatsd.host_access' file.  However, even if a host is
given the `none' access level, an individual can still give the `USER'
command to possibly gain a higher (but never lower) access than is set
for their host.  The gnatsd `USER' command takes two arguments: `USER
<userid> <passwd>'.


File: gnats.info,  Node: gnatsd.user_access,  Next: Privileged gnatsd commands,  Prev: gnatsd.host_access,  Up: Access Control

Access levels per user
======================

   Access levels per user can be set both across all databases on the
server or on a per-database basis.  The `gnatsd.user_access' file in a
database's `gnats-adm' directory specifies the user access rules for
that database.  If it doesn't exist, or doesn't contain the user name
given to `gnatsd', then the overall user access file (by default
`/usr/local/etc/gnats/gnatsd.user_access') specifying the per-user
access levels across all the databases on the server is checked.

   The user access files can only _increase_ the access level defined
in the host access files for the given host, they can never lower it.

   If the access level is `none' after processing the userid and
password, the connection is closed.

   The `gnatsd.user_access' files can contain plain text passwords, in
such a case they should be owned by the GNATS user with file permission
600.

   Wildcard characters are supported for the userid and password with
plain text passwords.  A null string or `*' matches anything; `?'
matches any one character.

   Entries in the database-specific `gnatsd.user_access' user access
file in the `gnats-adm' directory of the database have the following
general format:

   USERID:PASSWORD:ACCESS-LEVEL

   The overall `gnatsd.user_access' user access file adds a fourth
DATABASES field:

   USERID:PASSWORD:ACCESS-LEVEL:DATABASES

PASSWORD should either be in plain text, DES `crypt()'(1) or MD5 hash
format(2).

   If the password is in plain text format, it must be prefixed by
`$0$' and if it is in MD5 format, it needs to be prefixed by the string
`$1$'.(3) Passwords encrypted by `crypt()' should have no prefix. If no
password is given then users can login with an empty password string.

   A `gnats-passwd' tool to manage `gnatsd.user_access' files is
planned.  In the meantime, `crypt()' passwords can be generated by
using standard UNIX passwords tools, while MD5 passwords can be
generated with the following little Perl snippet:

     perl -e 'use Crypt::PasswdMD5 ; print Crypt::PasswdMD5::unix_md5_crypt
     "PASSWORD" , time() % 100000000'

If your Perl installation doesn't have the Crypt module installed, you
need to install it.  On most systems, the following command achieves
this:

     perl -MCPAN -e 'install Crypt::PasswdMD5'

   A tool for conversion of pre-version 4 `gnatsd.user_access' files is
distributed with GNATS 4.  *Note Converting old password files:
gnats-pwconv.

The ACCESS-LEVEL field should contain one of the values listed at the
beginning of this appendix.  This overrides (increases but never
lowers) the access level given as the default for the user's host in the
global gnatsd.host_access file.

   The following shows an example `gnatsd.user_access' file with plain
text passwords:

     rickm:$0$ruckm:edit
     pablo:$0$pueblo:view
     *::none

And this is the same file with MD5-encrypted passwords:
     rickm:$1$92388613$D7ZIYikzTUqd./dODTFrI.:edit
     pablo:$1$92388652$QRfAhIBG5elT.FQjQKhj80:view
     *::none

In these examples, anybody other than rickm and pablo get denied
access, assuming that the host access level is also `none'.  You could
set the catch-all rule at the end to be `*::view' to allow view access
to anyone who does not supply a password.  Note the important detail
that such a rule would allow view access only to persons who do not
supply a password at all, i.e. if rickm or pablo tries to log in but
mistypes his password, this rule would not apply and they would be
denied access entirely.  This is by design, since people might be
surprised if they suddenly found themselves logged in, but with a lower
access level than they usually have.

   The DATABASES field contains a comma-separated list of database
names, as defined in the `databases' file (*note The `databases' file:
databases file..  Wildcard characters are supported. The databases
listed in this field are the ones to which the other settings on the
same line will be applied.

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

   (1) DES crypt is the standard password encryption format used by
most UNIX systems

   (2) MD5 is only supported on platforms that have a `crypt()'
function that supports MD5. Among others, this currently includes GNU
Linux and OpenBSD.

   (3) Some systems support even more encryption methods.  In FreeBSD,
for instance, a prefix of `$2$' implies Blowfish encoding.  GNATS will
happily accept any encryption that the OS supports.


File: gnats.info,  Node: Privileged gnatsd commands,  Prev: gnatsd.user_access,  Up: Access Control

Privileged `gnatsd' commands
============================

   Every `gnatsd' command has a minimum access level attached to it.
If your access level is too low for a command, you get this response:

       LOCK 12
       422 You are not authorized to perform this operation (LOCK).

The commands `CHDB', `USER' and `QUIT' are unrestricted.

The `DBLS' command requires at least `listdb' access.

A user must have at least `edit' access for these commands:

`LKDB'
     lock the main GNATS database.

`UNDB'
     unlock the main GNATS database.

`LOCK PR USER PID'
     lock PR for USER and optional PID and return PR text.

`UNLK PR'
     unlock PR.

`EDIT PR'
     check in edited PR.

`APPN PR FIELD, REPL PR FIELD'
     Appends to or replaces the contents of FIELD in PR.

   The `DELETE' PR command is special in that it requires `admin'
access.

All other commands require `view' access.

   `edit-pr' and `query-pr' accept the command line arguments
`-v|--user' and `-w|--passwd'.  *Note The GNATS User Tools: GNATS user
tools.

