GNATS Administration
********************

In daily usage, GNATS is self-maintaining.  However, there are various administrative duties which need to be performed periodically:

emptying the pending directory
     If a Problem Report arrives with a >Category: value that is unrecognized by the categories file, or if that field is missing, GNATS places the PR in the pending directory (see Where the tools and utilities reside).  GNATS has no way of knowing which subdirectory the PR should be filed under. GNATS sends a notice to the gnats-admin and to the party responsible for that submitter (as listed in the submitters file) when this occurs.

     To file these PRs, simply use edit-pr to repair the problematic fields in each file in the pending directory.  Be sure to change the >Category: field of the PR from pending to an appropriate category.  In many cases the culprit is simply a typographical error, although it may be necessary sometimes to contact the submitter of the PR to decipher her or his intentions.

     Should you run out of disk space, there may be an empty PR in the pending directory.  In that case, look in the file GNATS_ROOT/gnats-adm/bug.log, which should still contain the full message that was submitted.

adding new categories
     To add a new category, simply insert a new line in the categories file and then run the program mkcat.

     Note: this causes all category lists for send-pr (except the one on the local machine) to become outdated.  Copy the new list on to every machine on your network that has send-pr installed, and make sure you advise remote submitters that the category list has changed.  See Adding a problem category.  Also The categories file.

removing categories
     To remove a category, you need to make sure the relevant subdirectory is empty (in other words, make sure no PRs exist for the category you wish to remove).  You can then remove the category listing from the categories file, and invoke

          rmcat CATEGORY...

     to remove CATEGORY (any number of categories may be specified on the command line to rmcat, so long as they abide by the above constraints).

     Note: this causes all category lists for send-pr (except the one on the local machine) to become outdated.  Copy the new list on to every machine on your network that has send-pr installed, and make sure you advise remote submitters that the category list has changed.  See Removing a problem category.  Also The categories file.

adding and removing maintainers
     Edit the responsible file to add a new maintainer or to remove an existing maintainer.  See The responsible file.

building a distribution of send-pr
     You can build a distribution of send-pr which contains valid information for your site by invoking the command mkdist. See Configuring send-pr for the outside world.  You can then distribute your customized send-pr to your customers, friends, relatives, etc., so that they can submit Problem Reports to your database.

building a new index
     If your index becomes corrupted, or if you wish to generate a new one for some reason, use the program gen-index (see Regenerating the index).

pruning log files
     Log files often grow to unfathomable proportions.  As with gardening, it is best to prune these as they grow, lest they take over your disk and leave you with no room to gather more Problem Reports.  If you keep log files, be sure to keep an eye on them.  (see Setting up mail aliases.)

BACKING UP YOUR DATA
     Any database is only useful if its data remains uncorrupted and safe. Performing periodic backups ensures that problems like disk crashes and data corruption are reversible.

See Where GNATS lives.

Managing GNATS over a network
=============================

If you have installed the GNATS user tools on machines around your local network, there are a few things you need to remember.

mkcat and rmcat do not update the categories list for other machines on your network which have send-pr installed, unless those machines share PREFIX with the host machine).  To update these lists, copy the send-pr categories list to each of the other hosts.  This categories list is PREFIX/lib/gnats/SITE, where SITE is the name tag for your local site, as specified in the config file as GNATS_SITE (see The config file).

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in PREFIX/lib/gnats/SUPPORT-SITE from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it.

If you need to use GNATS utilities, like query-pr and edit-pr, on other systems besides the one where GNATS itself resides, see Installing the user tools.

Changing your local configuration
=================================

See Where GNATS lives.

Your local configuration is determined by the data files in the directory GNATS_ROOT/gnats-adm.  These can be altered at any time by editing the pertinent file.

config
     Variables which control certain behavior.  See The config file.  Behaviors you can change here include

       * The address where your site receives Problem Reports.

       * The address of the GNATS administrator.

       * The nametag for your Support Site (your organization, company, group, etc.).

       * The nametag for your local Submitter Site.

       * The default release for your site.

       * The default value for the >Organization: field (this value appears as the default when you run send-pr).

       * Whether or not to remind maintainers if a requisite time period has passed before they change the state of a Problem Report to analyzed.  (Also see The submitters file, and Timely Reminders.

       * Whether or not to send an automatic acknowledgement to the originator of a problem report when the GNATS first receives the PR.

       * The value GNATS assigns to PRs which come in with missing or unknown values for the >Submitter-Id: field.

       * Whether or not GNATS should retain Received: mail headers from incoming mail.

       * Whether or not GNATS is in a mode for debugging.

       * The values which define business hours.

categories
     The list of categories that GNATS accepts as valid for the >Category: field, and the maintainers responsible for each category.  Update this file whenever you have a new category, or whenever a category is no longer valid.  You must also update this file whenever responsiblility for a category changes, or if a maintainer is no longer valid.  See The categories file.  Also see Adding a new problem category, and Removing a problem category.

responsible
     The list of maintainers.  Update this file whenever you have a new maintainer, or whenever a maintainer is no longer valid. See The responsible file.

submitters
     The list of Submitter Sites from whom GNATS accepts Problem Reports. This file is mandatory, although the feature it provides is not; see The submitters file.

Default behavior
----------------

The default behavior for GNATS is as follows:

  * The address where your site receives Problem Reports is bugs (a local address).

  * The address of the GNATS administrator is gnats-admin (a local address).

  * The nametag for your Support Site (your organization, company, group, etc.) is the second-to-last field in your domain name.

  * The nametag for your local Submitter Site is the nametag for your Support Site.

  * The default release for your site is unknown-1.0.

  * The default value for the >Organization: field (this value appears as the default when you run send-pr) is the nametag for your Support Site.

  * GNATS reminds maintainers if a requisite time period has passed before they change the state of a Problem Report to analyzed.

  * An automatic acknowledgement is sent to the originator of a problem report when the GNATS first receives the PR.

  * The value GNATS assigns to the >Submitter-Id: field in PRs which arrive with missing or unknown values for that field is unknown.

  * Received... mail headers are retained.

  * GNATS is not in a debugging mode.

  * business hours are defined as 8:00am to 5:00pm, Monday through Friday.

The config file
---------------

Much of the behavior GNATS exhibits depends on the values of fields in the file GNATS_ROOT/gnats-adm/config.  The config file contains a list of variables (using Bourne-shell syntax) which control the following behavior.  These values can be changed at any time; the new values take effect for all subsequent iterations of the tools.

GNATS_ADDR="ADDRESS"
     The address where your site receives Problem Reports.  This address is aliased in the file /etc/aliases so that it directs incoming mail into queue-pr (see Installing the utilities).

     The default is bugs (a local address).

GNATS_ADMIN="ADDRESS"
     The address of the GNATS administrator.  Normally this is set to gnats-admin, which is an alias in /etc/aliases that points toward the person responsible for administrating GNATS. See Installing the utilities.

     The default is gnats-admin (a local address).

GNATS_SITE="SITE"
     The nametag for your Support Site (your organization, company, group, etc.).  This nametag should also appear in the submitters file, so that users at your site can submit Problem Reports locally.

     SITE is also used as the name of the file containing a valid category list for your site.  This file is installed locally as PREFIX/lib/gnats/SITE.  Warning: if you change this variable after GNATS is installed, you must also change the name of this file, as well as the name of the alias for your local submitters (see Setting up mail aliases).

     The default is the second-to-last field in your domain name.  For example, if your domain name is unleaded.truckstop.org, your default SITE is truckstop.

SUBMITTER="SUBMITTER-ID"
     The nametag for your local Submitter Site (this value appears as the default value for >Submitter-Id when you run send-pr). Even though you are a Support Site, if you submit Problem Reports to your own organization you become a Submitter Site.  The value SUBMITTER-ID is the default value for the >Submitter-Id: field that your maintainers see when they submit Problem Reports locally.

     The default is the value of GNATS_SITE.

DEFAULT_RELEASE="RELEASE"
     The default release for your site (this value appears as the default value for >Release: when you run send-pr).

     The default is unknown-1.0.

DEFAULT_ORGANIZATION="TEXT"
     The default value for the >Organization: field (this value appears as the default when you run send-pr).

     The default is the value of GNATS_SITE.

NOTIFY=BOOLEAN
     Determines whether or not to remind maintainers if a requisite time period has passed before they change the state of a Problem Report to analyzed.  This feature uses the program at-pr; see Timely Reminders.

     This requisite time is determined for each submitter individually; see The submitters file.  The time is measured in business hours, which by default are 8:00am to 5:00pm, Monday through Friday.  Business hours can be redefined by changing the variables BDAY_START, BDAY_END, BWEEK_START, and BWEEK_END in the config file (see below).

     If BOOLEAN is 1, this feature is active.  If BOOLEAN is 0, the feature is turned off.  The default value for NOTIFY is 1.

ACKNOWLEDGE=BOOLEAN
     Determines whether or not to send an automatic acknowledgement to the originator of a problem report when the GNATS first receives the PR.

     If BOOLEAN is 1, this feature is active.  If BOOLEAN is 0, the feature is turned off.  The default for ACKNOWLEDGE is 1.

     The acknowledgment is of the form:

          To: YOUR-ADDRESS
          From: gnats
          Subject: Re: CATEGORY/GNATS-ID:SYNOPSIS
          In-Reply-To: Your message of DATE

          Thank you very much for your problem report.
          It has the internal identification: CATEGORY/GNATS-ID
          The individual assigned to look at your bug is:
               RESPONSIBLE

          Category:     CATEGORY OF THE PR
          Responsible:  RESPONSIBLE
          Synopsis:     SYNOPSIS FROM SUBMITTED PR
          Arrival-Date: ARRIVAL DATE

DEFAULT_SUBMITTER="submitter-id"
     The value GNATS assigns to PRs which come in with missing or unknown values for the >Submitter-Id: field.  This value must also appear in the submitters file; see The submitters file.

     To disable the feature of GNATS which tracks the >Submitter-Id:, simply alter the submitters file to only contain the SUBMITTER-ID value which appears in DEFAULT_SUBMITTER, and instruct your submitters to ignore the field.

     The default value for DEFAULT_SUBMITTER is unknown.

KEEP_RECEIVED_HEADERS=BOOLEAN
     Determines whether or not GNATS should retain the Received: mail headers from incoming mail.  These headers often take up a lot of space, and they are seldom used.

     If BOOLEAN is 1, this feature is active.  If BOOLEAN is 0, the feature is turned off.  The default value for KEEP_RECEIVED_HEADERS is 1.

DEBUG_MODE=BOOLEAN
     Determines whether or not GNATS is operating in a mode for debugging.  When BOOLEAN is 1, GNATS forwards all mail to the GNATS administrator, gnats-admin.

BDAY_START=INTEGER
BDAY_END=INTEGER
BWEEK_START=INTEGER
BWEEK_END=INTEGER
     The definition of business hours.  These values are only used if NOTIFY is set to 1 in the config file (see above).

     By default, business hours are 8:00am to 5:00pm Monday through Friday, local time.

     BDAY_START=INTEGER
          Defines the hour of the day when business hours begin.  INTEGER values must fall between 0 (midnight) and 23 (11:00pm). The default is 8 (8:00am).

     BDAY_END=INTEGER
          Defines the hour of the day when business hours end.  INTEGER values must fall between 0 (midnight) and 23 (11:00pm). The default is 17 (5:00pm).

     BWEEK_START=INTEGER
          Defines the beginning day of the business week.  INTEGER values must fall between 0 (Sunday) and 6 (Saturday).  The default is 1 (Monday).

     BWEEK_END=INTEGER
          Defines the ending day of the business week.  INTEGER values must fall between 0 (Sunday) and 6 (Saturday).  The default is 5 (Friday).

The categories file
-------------------

The categories file contains a list of problem categories, specific to your site, which GNATS tracks.  This file also matches responsible people with these categories.  You must edit this file initially, creating valid categories and then running mkcat to create the corresponding subdirectories of GNATS_ROOT and update the valid categories list for send-pr.  For instructions on running mkcat, see Adding a problem category.

To create a new category, log in as GNATS, add a line to this file, and run mkcat.  Lines beginning with # are ignored.

A line in the categories file consists of four fields delimited by colons, as follows:

     CATEGORY:DESCRIPTION:RESPONSIBLE:NOTIFY

category
     A unique category name, made up of text characters.  This name cannot contain spaces or any of the following characters:

          ! $ & * ( ) { } [ ] ` ' " ; : < > ~

     Ideally, category names should not contain commas or begin with periods. Each line has a corresponding subdirectory in the main GNATS directory (GNATS_ROOT).

description
     A terse textual description of the category.

responsible
     The name tag of the party responsible for this category of problems, as listed in the responsible file (see The responsible file).

notify
     One or more other parties which should be notified when a Problem Report with this category arrives, such as a project manager, other members of the same project, other interested parties, or even log files.  These should be separated with commas.

A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for, or perhaps with sub-categories within each category. For instance, if you wish to track documentation problems in a variety of areas, you could have entries such as

     doc:General Doc Questions:myboss:me,barney
     doc-rock:Doc for ROCK program:me:myboss
     doc-stone:Docs for STONE utils:barney:fred
     doc-local:in-house documentation:me:doc-local-log

In the above example, the nametags myboss, me, fred, and barney must be defined in the responsible file (see The responsible file).

Problem Reports with a category of doc are sent to the local mail address (or alias) myboss, and also sent to the addresses me and barney.  PRs with a category of doc-rock are sent to the local addresses me and myboss only, while PRs with the category doc-stone are sent to fred as well as to barney.  PRs with a category of doc-local are sent only to me, and are also filed in doc-local-log (in this case, an alias should be set up in /etc/aliases to reflect a location for the log file, such as doc-local-log: /users/me/local-log).

Whenever you add a new category, be sure to run mkcat to create a subdirectory for it and update the local categories list.

Only one category must be present for GNATS to function:

     pending:Category for faulty PRs: gnats-admin:

The pending directory is created automatically when you run make install (see Configuring and compiling the software).

The responsible file
--------------------

This file contains a list of the responsible parties.  Lines beginning with # are ignored.  Each entry contains three fields, separated by colons:

     RESPONSIBLE:FULL-NAME:MAIL-ADDRESS

responsible
     A name-tag description of the party in question, such as her or his user name, or the name of the group.  This name is listed in the PR in the >Responsible: field.

full-name
     The full name of the party (``Charlotte Bronte''; ``Compiler Group'').

mail-address
     The full, valid mail address of the party.  This field is only necessary if the responsible party has no local mail address or alias.

A sample responsible listing might be:

     ren:Ren Hoek:
     stimpy:Stimpson J. Cat:stimpy@lederhosen.org

Here, ren is a local user.  stimpy is remote, so his full address must be specified.

The following entry must be present for GNATS to function:

     gnats-admin: GNATS administrator:

(gnats-admin is a mail alias, so for this purpose gnats-admin is a local address.)

The submitters file
-------------------

This is a database of sites which submit bugs to your support site.  It contains six fields delineated by colons.  Lines beginning with # will be ignored.

Entries are of the format:

     SUBMITTER-ID:NAME:TYPE:RESP-TIME:CONTACT:NOTIFY

submitter-id
     A unique identifier for a specific site or other entity who submits Problem Reports.

name
     A textual description of this entity.

type
     Optional description for the type of relationship this submitter to your support site.  This could indicate a contract type, a level of expertise, etc., or it can remain blank.

resp-time
     Optional quoted response time, in business hours.  GNATS is capable of reminding responsible parties when Problem Reports marked with a >Severity value of critical, or those with a >Severity of serious and a >Priority value of high, are neglected for a certain period.  This argument defines that response period for each SUBMITTER-ID.  Business hours are defined by default as 8:00am to 5:00pm, Monday through Friday.  For example, three business days would be equal to 24 business hours.

     This function is active if the NOTIFY field is defined as 1 in the config file (see Changing your local configuration).  If NOTIFY is 0, this field is ignored.  For information on at-pr, the program which sends out this reminder, see Timely Reminders.

contact
     The name tag of the main contact at the Support Site for this submitter.  This contact should be in the responsible file (see The responsible file).  Incoming bugs from SUBMITTER are sent to this contact.  Optionally, this field can be left blank.

notify
     Any other parties who should receive copies of Problem Reports sent in by SUBMITTER.

A few example entries in the submitters file:

     univ-hell: University of Hades:eternal:3:beelzebub:lucifer
     tta: Telephones and Telegraphs of America:support:720:dave:

In this example, when a PR comes in from the University of Hades (who has an eternal contract), it should have univ-hell in its Submitter-Id field.  This Problem Report goes to beelzebub (who should be in the responsible file), and if it is not analyzed within three business hours a reminder message is sent. lucifer also receives a copy of the bug, and a copy of the reminder message as well (if it is sent).  When Telephones and Telegraphs of America utilizes their support contract and submits a bug, a copy is sent only to dave, who has 720 business hours to return an analysis before a reminder is sent.

To disable the feature of GNATS which tracks the >Submitter-Id:, simply alter the submitters file to only contain the SUBMITTER-ID value which appears as the DEFAULT_SUBMITTER value in the config file (see The config file), and instruct your submitters to ignore the field.

Administrative data files
=========================

The following files are located in GNATS_ROOT/gnats-adm, where GNATS_ROOT is the resident directory of GNATS.  These files are maintained by GNATS; you should never touch them.

The index file
--------------

The index is used to accelerate searches on the database by query-pr and edit-pr.  This file is not created until the first PR comes in.  It is then kept up to date by GNATS; you should never touch this file.

Any searches on subjects contained in the index are much faster than searches which depend on data not in the index.  The index contains single-line entries for the following fields, in order, separated by colons (:) except for >Category: and >Number:, which are separated by a slash (/) (the > and : Problem Report fieldname delimiters have been removed for the sake of brevity and readability)::

     Category       Number         Submitter-Id
     Responsible    State          Confidential
     Severity       Priority

To see an example index, run gen-index without any options (see Regenerating the index).

The current file
----------------

This file contains the last serial number assigned to an incoming PR. It is used internally by GNATS; you need never touch this file.

Administrative utilities
========================

These tools are used by the GNATS administrator as part of the periodic maintenance and configuration of GNATS. See GNATS Administration.

Adding a problem category
-------------------------

To add new categories to the database:

 1. Add a line to the categories file under GNATS_ROOT/gnats-adm for each new category. See The categories file.

 2. Run mkcat.  mkcat creates a directory under GNATS_ROOT for any new categories which appear in the categories file.  mkcat also recreates the list of valid categories for both your locally installed send-pr and for the send-pr distribution template in PREFIX/lib/gnats/dist (see Where GNATS lives.

Note: mkcat does not update the categories list for other machines on your network which have send-pr installed (unless the two machines share the directory PREFIX). See Managing GNATS over a network.

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in PREFIX/lib/gnats/SUPPORT-SITE (Note: the value for PREFIX may be different from yours) from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it (see Configuring send-pr for the outside world).

Removing a problem category
---------------------------

To remove a category from the database:

 1. Remove the Problem Reports from the subdirectories corresponding to the categories you wish to remove, or assign the PRs to new categories.  All PRs for a given category reside in GNATS_ROOT/CATEGORY.  Make sure you do this for each category you wish to remove.

 2. Run rmcat using

          rmcat CATEGORY [ CATEGORY... ]

     where CATEGORY is the category you wish to remove.  You can specify as many categories as you wish as long as each category has no PRs associated with it.  rmcat removes the directory under GNATS_ROOT where the Problem Reports for that category had been stored.  rmcat also deletes the category from the list of valid categories for both your locally installed send-pr and for the send-pr distribution template in PREFIX/lib/gnats/dist (see Where GNATS lives).

Note: rmcat does not update the categories list for other machines on your network which have send-pr installed. See Managing GNATS over a network.

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in PREFIX/lib/gnats/SUPPORT-SITE (Note: the value for PREFIX may be different from yours) from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it (see Configuring send-pr for the outside world).

Regenerating the index
----------------------

If your index file becomes corrupted, or if you need a copy of the current index for some reason, use

     gen-index [ -n | --numeric ]
               [ -d DIRECTORY | --directory=DIRECTORY ]
     	  [ -c FILENAME | --catfile=FILENAME ]
               [ -o FILENAME | --outfile=FILENAME ]
               [ -h | --help] [ -V | --version ]

With no options, gen-index generates an index that is ordered the same as the order of the categories as they appear in the categories file, and prints it to standard output.  The options are:

-n
--numeric
     Sorts index entries numerically.

-d DIRECTORY
--directory=DIRECTORY
     Uses DIRECTORY as the directory containing the database, by default GNATS_ROOT (see Where GNATS lives).

-o FILENAME
--outfile=FILENAME
     Places output in FILENAME rather than sending it to standard output.

-c FILENAME
--catfile=FILENAME
     Point to FILENAME, the file listing the valid categories.

-h
--help
     Prints the usage for gen-index.

-V
--version
     Prints the version number for gen-index.

Configuring send-pr for the outside world
-----------------------------------------

Now that GNATS is up and running on your system, you probably want to distribute send-pr to all your friends, relatives, enemies, etc. so they can more easily submit bugs to your organization.  To do this, create a new directory DIST-DIRECTORY to hold the distribution.  Then run the program

     mkdist --release=RELEASE DIST-DIRECTORY

This populates DIST-DIRECTORY with a full distribution of the program send-pr, including a Makefile and all the send-pr documentation.  You can then simply package up this directory and send it to your bug report submitters.  For example, when logged in as gnats you can do the following:

     mkdir new-dist
     mkdist --release=tools-1.2 new-dist
     tar cvf send-pr.tar new-dist

This creates a file called send-pr.tar which contains a full distribution of send-pr customized for your site, with a default release number of tools-1.2.  You can then place this onto a disk or tape and send it to your submitters, or instruct your submitters to download it using ftp.

If you only have one submitter, you can set the Submitter ID in the send-pr script by specifying the --submitter option to mkdist.  If you do this, the submitter will not have to run install-sid.

Internal utilities
==================

These tools are used internally by GNATS.  You should never need to run these by hand; however, a complete understanding may help you locate problems with the GNATS tools or with your local implementation.

Handling incoming traffic
-------------------------

The program queue-pr handles traffic coming into GNATS. queue-pr queues incoming Problem Reports in the directory GNATS_ROOT/gnats-queue, and then periodically (via cron) passes them on to file-pr to be filed in the GNATS database.  See Installing GNATS.

The usage for queue-pr is as follows:

     queue-pr [ -q | --queue ] [ -r | --run ]
              [ -f FILENAME | --file=FILENAME ]
              [ -d DIRECTORY | --directory=DIRECTORY ]

One of -q or -r (or their longer-named counterparts) must be present upon each call to queue-pr.  These options provide different functions, as described below.

-q
--queue
     Accepts standard input as an incoming mail message, placing this message in an incrementally numbered file in the gnats-queue directory under GNATS_ROOT (see Where GNATS lives).

-r
--run
     Redirects files in the gnats-queue directory into the program file-pr one by one.

-f FILENAME
--file=FILENAME
     Used with -q (or --queue), accepts the file denoted by FILENAME as input rather than reading from standard input.

-d DIRECTORY
--directory=DIRECTORY
     Resets the default DIRECTORY value, which is by default GNATS_ROOT/gnats-queue.  When -d DIRECTORY is used in conjunction with the -q (or --queue) option, queue-pr files incoming messages into DIRECTORY rather than the gnats-queue directory.  When -d DIRECTORY is used in conjunction with the -r (or --run) option, queue-pr redirects into file-pr files from DIRECTORY rather than from the gnats-queue directory.

Processing incoming traffic
---------------------------

queue-pr hands off queued Problem Reports to file-pr one at a time.  file-pr checks each Problem Report for correct information in its fields (particularly a correct >Category:), assigns it an identification number, and files it in the database under the appropriate category.

If the >Category: field does not contain a valid category value (i.e., matching a line in the categories file; see The categories file), the PR is given a >Category: value of pending and is placed in the pending directory.  The GNATS administrator is notified of the unplaceable PR.

file-pr assigns the Problem Report an identification number, files it in the GNATS database (under pending, if the >Category: field contains an invalid category), and sends acknowledgements to appropriate parties.  The person responsible for that category of problem (see The categories file) and the person responsible for the submitter site where the PR originated (see The submitters file) receive a copy of the PR in its entirety.  Optionally, the originator of the PR receives an acknowledgement that the PR arrived and was filed (see Changing your local configuration).

The usage for file-pr is as follows:

     file-pr [ -f FILENAME | --file=FILENAME ]
             [ -d DIRECTORY | --directory=DIRECTORYb ]
     	[ -D | --debug ] [ -h | --help ] [ -V | --version ]

file-pr requires no options in order to operate, and takes input from standard input (normally, the output of queue-pr -r) unless otherwise specified.  The options include:

-f FILENAME
--filename=FILENAME
     Uses FILENAME as input rather than standard input.

-d DIRECTORY
--directory=DIRECTORY
     Performs refiling operations in DIRECTORY rather than in GNATS_ROOT.

-D
--debug
     Give debugging output while file-pr is running.

-h
--help
     Prints the usage for file-pr.

-V
--version
     Prints the version number for file-pr.

Timely reminders
----------------

at-pr creates a queued job using at which, after an allotted response time is past, checks the PR to see if its state has changed from open.

The submitters file contains the response time for each >Submitter-Id: (see The submitters file). The time is determined in business hours, which are defined by default as 8:00am to 5:00pm Monday through Friday, local time.  These hours are defined in the config file (see The config file).

If the PR is still open after the requisite time period has passed, at-pr sends a reminder to the GNATS administrator, to the maintainer responsible for that submitter, and to the maintainer responsible for the PR with the following message:

     To: SUBMITTER-CONTACT RESPONSIBLE GNATS-ADMIN
     Subject: PR GNATS-ID not analyzed in #HOURS hours

     PR GNATS-ID was not analyzed within the acknowledgment period
     of #HOURS business hours.  The pertinent information is:

      Submitter-Id: SUBMITTER
      Originator: FULL NAME OF THE SUBMITTER
      Synopsis: SYNOPSIS
      Person responsible for the PR: RESPONSIBLE

     --
     The GNU Problem Report Management System (GNATS)

The edit-pr driver
------------------

pr-edit does the background work for edit-pr, including error-checking and refiling newly edited Problem Reports and handling file locks.  It can be called interactively, though it has no useable editing interface.

The usage for pr-edit is:

     pr-edit [ -l MAINTAINER --lock=MAINTAINER ]
             [ -u | --unlock ] [ -c | --check ] [ -F ]
     	[ -L | --lockdb ] [ -U | --unlockdb ]
             [ -f FILENAME | --filename=FILENAME ]
             [ -d DIRECTORY | --directory=DIRECTORY ]
             [ -h | --help ] [ -V | --version ]
             [ GNATS-ID ]

A lock is placed on a Problem Report while the PR is being edited. The lock is simply a file in the same directory as the PR, with the name GNATS-ID.lock, which contains the name of the maintainer who created the lock.  MAINTAINER then ``owns'' the lock, and must remove it before the PR can be locked again, even by the same MAINTAINER (This approach may seem heavy-handed, but it ensures that changes are not overwritten.).  If a PR is already locked when you attempt to edit it, pr-edit prints an error message giving the name of the maintainer who is currently editing the PR.

If you do not specify GNATS-ID, pr-edit reads from standard input.  You must specify GNATS-ID for the functions which affect PR locks, --lock=MAINTAINER and --unlock.

-l MAINTAINER
--lock=MAINTAINER
     Locks Problem Report GNATS-ID, failing (and returning an error message) if GNATS-ID is already locked, or if GNATS-ID does not exist.  pr-edit requires that you specify GNATS-ID when using this option.

-u
--unlock
     Unlocks Problem Report GNATS-ID.  pr-edit requires that you specify GNATS-ID when using this option.  You must own a file lock to remove it.

-L
--lockdb
     Locks the GNATS database as a whole.  This will prevent any modification to any part of the system while it's locked.

-U
--unlockdb
     Unlocks the GNATS database as a whole, allowing modification of its files.

-c
--check
     Checks the Problem Report in GNATS-ID (or standard input, if GNATS-ID is not present) for correct information in its ENUMERATED fields.  pr-edit complains about any bogus information in the Problem Report.

-F
     Forces the PR to be submitted to the database, even if there is no current index entry for it (i.e., even if the PR did not exist in the database previously).

     Warning: using this option may corrupt your index.  If you use it, be sure you know what you are doing.

-f FILENAME
--filename=FILENAME
     Reads FILENAME rather than standard input.

-d DIRECTORY
--directory=DIRECTORY
     Resets the operating directory (GNATS_ROOT).

-h
--help
     Prints the usage for pr-edit.

-V
--version
     Prints the version number for pr-edit.

Address retrieval
-----------------

Returns an electronic mail address when given a valid nametag, as it appears in the responsible file (see The responsible file).  If NAMETAG is not valid, pr-addr will tell the user that it could not find the requested address.

Usage is simply:

     pr-addr NAME