[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. 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 section 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 section 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 section 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 section 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 section 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 section 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 section 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 section Where GNATS lives.

3.1 Managing GNATS over a network  
3.2 Changing your local configuration  
3.3 Administrative data files  
3.4 Administrative utilities  
3.5 Internal utilities  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 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/share/gnats/site', where site is the name tag for your local site, as specified in the `config' file as `GNATS_SITE' (see section 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/share/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 section Installing the user tools.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 Changing your local configuration

See section Where GNATS lives.

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

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

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 responsibility for a category changes, or if a maintainer is no longer valid. See section 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 section 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.

addresses
Mappings between submitter IDs and submitters' e-mail addresses. Use of this file is optional. If you get Problem reports where the `>Submitter' field is not filled in, GNATS will use entries in this file to try to derive the submitter ID from the e-mail headers.

3.2.1 Default behavior  
3.2.2 The config file  
3.2.3 The categories file  
3.2.4 The responsible file  
3.2.5 The submitters file  
3.2.6 The states file  
3.2.7 The addresses file  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.1 Default behavior

The default behavior for GNATS is as follows:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.2 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 section 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 section 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/share/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 section 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 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 fowards 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).

DEFINE_CATEGORY="category"
Defines the category where problem reports are placed when they come in without a category. The category you choose must be listed in the categories file.

This line does not appear in the config file when you install GNATS, so you must add it to the config file if you want to set a default category. If there is no default category listed, problem reports will be put into the "pending" category.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.3 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 section 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 section 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 section Configuring and compiling the software).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.4 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.)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.5 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 section 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 section 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. They need not be listed in the `responsible' file.

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 section The config file), and instruct your submitters to ignore the field.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.6 The states file

This file lists the possible states for Problem Reports. Each line consists of a state, followed optionally by colon and a one-line description of what the state means. Lines beginning with `#' will be ignored.

 
state: optional descriptive text

State names can contain any alphanumeric character, "-" (hyphen), "_" (underscore), or "." (period), but no other characters. The state name ends with a newline, or else with a colon followed by optional descriptive text. The descriptive text, if present, can contain any character except newline, which marks the end of the description. Empty or all-whitespace descriptions are allowed (though it's hard to imagine why one would want such a thing). Even though GNATS does not currently use this descriptive text, other external tools may, so you probably still want to include it.

The first state listed will be the state automatically assigned to Problem Reports when they arrive; by default this is named "open". The last state listed is the end state for Problem Reports -- one should usually assume that a PR in this state is not being actively worked on; by default this state is named "closed".

It is probably best to leave "open" as the first state and "closed" as the last, otherwise some external tools looking for those two states by name may be fooled.

If the `states' file cannot be read, or contains formatting errors, GNATS uses the states described in States.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.7 The addresses file

This file contains mappings between submitter IDs and corresponding e-mail addresses.

When a PR comes in without a submitter ID (if someone sends unformatted e-mail to the "bugs" address), GNATS will try to derive the submitter ID from the address in the "From:" header. The entries in this file consist of two fields, separated by a colon:

 
submitter-id:address-fragment

submitter-id
A valid submitter ID

address-fragment
Part of all of the e-mail address to be matched

Here is an example of an addresses file:

 
# Addresses for Yoyodine Inc
yoyodine:yoyodine.com
yoyodine:yoyodine.co.uk
# Addresses for Foobar Inc.
foobar1:sales.foobar.com
foobar2:admin.foobar.com
foobar3:clark@research.foobar.com

GNATS checks each line in the addresses file, comparing address-fragment to the end of the "From:" header, until it finds a match. If no match is found, GNATS uses the default submitter ID.

You can only have one address fragment per line, but you can have more than one line for a given submitter ID. An address fragment can be a domain (i.e. yoyodine.com), a machine location (admin.foobar.com), or a full e-mail address (clark@research.foobar.com).

GNATS can match addresses in three e-mail formats:

From: name@address.com
The address by itself without a full name, not enclosed in brackets

From: Real Person <name@address.com>
A full name (optional, with or without quotation marks), followed by the address enclosed in angle brackets

From: name@address.com (Real Person)
An address, followed by a name or comment in parentheses

If GNATS sees other e-mail address formats, it uses the default submitter ID. Future version of this feature will account for other valid e-mail address formats.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 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.

3.3.1 The index file  The `index' file
3.3.2 The current file  The `current' file


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.1 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.

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 all PR fields except for the multitext fields such as Description, How-To-Repeat, etc. Fields are separated by bars (`|') except for `>Category:' and `>Number:', which are separated by a slash (`/').

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.2 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 Administrative utilities

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

3.4.1 Adding a problem category  
3.4.2 Removing a problem category  
3.4.3 Regenerating the index  
3.4.4 Configuring send-pr for the outside world  Configuring send-pr for the outside world


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.1 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 section 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/share/gnats/dist' (see section 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 section 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/share/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 section Configuring send-pr for the outside world).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.2 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/share/gnats/dist' (see section Where GNATS lives).

Note: rmcat does not update the categories list for other machines on your network which have send-pr installed. See section 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/share/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 section Configuring send-pr for the outside world).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.3 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 section 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.4 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 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.

3.5.1 Handling incoming traffic  
3.5.2 Processing incoming traffic  
3.5.3 Timely reminders  
3.5.4 The edit-pr driver  The edit-pr driver
3.5.5 Address retrieval  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.1 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 section 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 section 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2 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 section The categories file), the PR is assigned to the default category, as set in the config file. If there is no default category defined, 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 the default, if the `>Category:' field contains an invalid category), and sends acknowledgements to appropriate parties. The person responsible for that category of problem (see section The categories file) and the person responsible for the submitter site where the PR originated (see section 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 section 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.3 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 section 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 section 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)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.4 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 usable 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(4). 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.5 Address retrieval

pr-addr returns an electronic mail address when given a valid nametag, as it appears in the `responsible' file (see section 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


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]