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

4.8.1 Handling incoming traffic

The program queue-pr handles traffic coming into GNATS. queue-pr queues incoming Problem Reports in the ‘gnats-queue’ directory of the database, 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 ]
         [ -m kbytes | --max-size=kbytes ]
         [ -d databasename | --database=databasename ]
         [ -h | --help] [ -V | --version ]

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 the database directory (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.

-m kbytes

--max-size=kbytes

Do not process messages larger then kbytes kilobytes. Files larger than the limit are left for human intervention.

-d databasename

--directory=databasename

Specifies database to operate on. If this option is left out, the value of the GNATSDB environment variable is used, and if that is undefined, the default database name set when GNATS was built is used (usually default).

-h

--help

Prints the usage for gen-index.

-V

--version

Prints the version number for gen-index.

4.8.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 dbconfig 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 acknowledgments to appropriate parties. For the default GNATS configuration, 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 acknowledgment that the PR arrived and was filed (see section Changing your GNATS configuration).

The usage for file-pr is as follows:

file-pr [ -f filename | --file=filename ]
        [ -d databasename | --database=databasename ]
	    [ -h | --help ] [ -V | --version ]
 
       network options:
        [ -H host | --host=host ]
        [ -P port | --port=port ]
        [ -v username | --user=username ]
        [ -w password | --passwd=password ]

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 databasename

--database=databasename

Performs refiling operations on database. If this option is left out, the value of the GNATSDB environment variable is used, and if that is undefined, the default database name set when GNATS was built is used (usually default).

-h

--help

Prints the usage for file-pr.

-V

--version

Prints the version number for file-pr.

file-pr can file PRs across a network, talking to a remote gnatsd. The following options relate to network access:

-H host

--host=host

Hostname of the GNATS server.

-P port

--port=port

The port that the GNATS server runs on.

-v username

--username=username

Username used to log into the GNATS server.

-w password

--passwd=password

Password used to log into the GNATS server.

4.8.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’. When the PR is originally filed, file-pr checks the notify-about-expired-prs parameter in the ‘dbconfig’ file. If this parameter is set to true, file-pr calls at-pr, which sets up the expiry check.

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 in the database’s ‘dbconfig’ file (see section Overall database configuration).

If the PR is urgent and 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 PR is urgent if its priority is ‘critical’ or if its priority is ‘serious’ and the severity is ‘high’.

4.8.4 The edit-pr driver

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

The usage for pr-edit is:

pr-edit   [ -l username | --lock=username ] [ -u | --unlockdb ]
          [ -L | --lockdb ] [ -U | --unlockdb ] [ -c | --check ]
          [ -C | --check-initial ] [ -s | --submit [ --show-prnum ] ]
          [ -a field | --append field=field ]
          [ -r field | --replace=field ] [ --delete-pr ]
          [ -R reason | --reason=reason ]
          [ -p process-id | --process=process-id ]
          [ -d databasename | --database=databasename ]
          [ -f filename | --filename=filename ]
          [ -V | --version ]
          [ -h | --help ] [ -v username | --user=username ]
          [ -w passwd | --passwd=passwd ]
          [ -H host | --host=host ]
          [ -P port | --port=port ]
          [ -D | --debug ] [ PR number ]

A lock is placed on a Problem Report while the PR is being edited. The lock is simply a file in the ‘locks’ subdirectory of the ‘gnats-adm’ directory of the database, with the name ‘gnats-id.lock’, which contains the name of the user who created the lock. user then “owns” the lock, and must remove it before the PR can be locked again, even by the same user(3). If a PR is already locked when you attempt to edit it, pr-edit prints an error message giving the name of the user who is currently editing the PR.

If you do not specify PR number, pr-edit reads from standard input. You must specify PR number for the functions which affect PR locks, ‘--lock=username’ and ‘--unlock’.

-L

--lockdb

Locks the database specified with the --database or -d option. No PRs may be edited, created or deleted while the database is locked. This option is generally used when editing the index file.

-U

--unlockdb

Unlocks the specified database. No check is made that the invoking user actually had locked the database in the first place; hence, it is possible for anyone to steal a database lock.

-c

--check

-C

--check-initial

The --check options are used to verify that a proposed PR’s field contents are valid. The PR is read in (either from stdin or a file specified with --filename), and its fields are compared against the rules specified by the database configuration of the selected database. Warnings are given for enumerated fields whose contents do not contain one of the required values or fields that do not match required regexps. --check-initial is used to verify initial PRs, rather than proposed edits of existing PRs.

-s

--submit

Used to submit a new PR to the database. The PR is read in and verified for content; if the PR is valid as an initial PR, it is then added to the database. If the submission is successful a zero exit code is returned. Otherwise, the reason(s) for the PR being rejected are printed, and a non-zero exit code is returned.

--show-prnum

This option is used with the --submit option to display the PR number associated with the submitted PR.

The following options require a PR number to be given.

--delete-pr

Deletes the specified PR from the database. The PR must be in a closed state, and not locked. Only the user gnats (or the user name specified instead of gnats during the building of GNATS) is permitted to delete PRs.

-l username

--lock=username

Locks the PR. username is associated with the lock, so the system administrator can determine who actually placed the lock on the PR. However, anyone is permitted to remove locks on a PR. If the optional --process or -p option is also given, that process-id is associated with the lock.

-u

--unlock

Unlocks the specified PR.

-a field

--append=field

-r field

--replace=field

--append and --replace are used to append or replace content of a specific field within a PR. The new field content is read in from stdin (or from the file specified with the --filename option), and either appended or replaced to the specified field. The field contents are verified for correctness before the PR is rewritten. If the edit is successful, a zero exit status is returned. If the edit failed, a non-zero exit status is returned, and the reasons for the failure are printed to stdout.

-R reason

--reason=reason

Certain PR fields are configured in the database configuration to require a short text describing the reason of every change that happens to them, See section The dbconfig file. If you edit a problem and change any of such fields, you must issue a short text, the reason of the change, through this option. If the option is used and no change-reason requiring field is actually changed, the option has no effect.

PR number

If only a PR number is specified with no other options, a replacement PR is read in (either from stdin or the file specified with --filename). If the PR contents are valid and correct, the existing PR is replaced with the new PR contents. If the edit is successful, a zero exit status is re turned. If the edit failed, a non-zero exit status is returned, and the reasons for the failure are printed to stdout.

-d database

--database=database

Specifies the database which is to be manipulated. If no database is specified, the default database name set when GNATS was built is used (usually default). This option overrides the database specified in the GNATSDB environment variable.

-f filename

--filename=filename

For actions that require reading in a PR or field content, this specifies the name of a file to read. If --filename is not specified, the PR or field content is read in from stdin.

-h

--help

Prints the usage for pr-edit.

-V

--version

Prints the version number for pr-edit.

pr-edit can edit PRs across a network, talking to a remote gnatsd. The following options relate to network access:

-H host

--host=host

Hostname of the GNATS server.

-P port

--port=port

The port that the GNATS server runs on.

-v username

--username=username

Username used to log into the GNATS server.

-w password

--passwd=password

Password used to log into the GNATS server.

-D

--debug

Used to debug network connections.

4.8.5 The diff-prs tool

The diff-prs tool is invoked as follows:

diff-prs prfile1 prfile2

diff-prs simply reads the PRs contained in prfile1 and prfile2 and returns a list of the fields that are different between the two. No output is produced if the PRs are identical.

4.8.6 The pr-age tool

The pr-age tool reports the time, in days and hours, since the PR arrived. Usage is

pr-age  [ -d databasename | --database=databasename ]
        [ -H host | --host=host ]
        [ -P port | --port=port ]
        [ -v username | --user=username ]
        [ -w password | --passwd=password ]
        [ -h | --help ] [ -V | --version ]

For an explanation of the arguments listed above, please refer to the usage description for file-pr (file-pr).

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.