2
.\" Copyright (c) 2000 Free Software Foundation, Inc.
3
.\" See section COPYING for conditions for redistribution
4
.TH dbconfig 5 "January 2000" "GNATS @VERSION@" "GNATS Admininstration Files"
6
dbconfig \- GNATS database configuration file
8
The dbconfig configuration file is, oddly enough, used to control
9
the configuration of a GNATS database. Each database has its own
10
individual copy of the file, which is located in the \fBgnats-adm\fR
11
administrative subdirectory of the database.
13
The file contains 6 major sections, which must appear in this order:
17
Overall database configuration
19
Individual field configuration
21
Named query definitions
23
Audit-trail and outgoing email formats
25
Index file description
27
Initial \fIPR\fR input fields
30
Individual descriptions of each section will appear below. (It is
31
helpful to refer to the supplied default configuration, which contains
32
examples of most of the available configuration options.)
34
It is very helpful if the administrator has a reasonably good
35
understanding of the overall GNATS \fIPR\fR process before trying to
36
create or edit a database configuration.
38
The file is a free-form ASCII file. Whitespace is completely
39
optional, and is ignored. Braces ({}) are used to delimit sections
40
within the file. Non-keyword values must generally be surrounded with
41
double quotes. Newline characters within double quotes must be
42
proceeded with a backslash (`\\') character, and are not included in
43
the final resulting string; to include a newline character in a value,
44
use the \fB\\n\fR combination instead.
45
.SH "Overall Database Configuration"
46
The overall database options are controlled with the \fBdatabase-info\fR
56
The following options may be present:
58
\fBdebug-mode\fR \fItrue\fR|\fIfalse\fR
59
If set to true, the database is placed into \fIdebug mode\fR. This
60
causes all outgoing email to be sent to the \fIgnats-admin\fR user
61
listed in the \fBresponsible\fR adm file.
64
The default value is \fIfalse\fR.
67
\fBkeep-all-received-headers\fR \fItrue\fR|\fIfalse\fR
68
If set to true, all of the Received: headers for \fIPR\fRs submitted via
69
email are kept in the PR; otherwise, only the first one is kept.
72
The default value is \fIfalse\fR.
75
\fBnotify-about-expired-prs\fR \fItrue\fR|\fIfalse\fR
76
If set to true, notification email about expired \fIPR\fRs is sent via
77
the at-pr command. Otherwise, required times for \fIPR\fR fixes
81
The default value is \fIfalse\fR.
84
\fBsend-submitter-ack\fR \fItrue\fR|\fIfalse\fR
85
When new \fIPRs\fR are submitted to the database, an acknowledgement
86
email will be sent to the submitter if \fBsend-submitter-ack\fR is set
87
to true. This is in addition to the normal notification mail to the
88
person(s) responsible for the new \fIPR\fR.
91
The default value is \fIfalse\fR.
94
\fBlibexecdir\fR "\fIpath\fR"
95
Used to specify the directory where the GNATS adminstrative
96
executables can be found; in particular, \fBat\-pr\fR and
97
\fBmail\-pr\fR are invoked from this directory.
100
The default value is the empty string, which is unlikely to be useful.
103
\fBbusiness-day-hours\fR \fIday-start\fR \- \fIday-end\fR
104
Used to specify the hours that define a business day in 24-hour
105
format; the times are inclusive. A single dash separates the two
106
values. The values are used to determine if a \fIPR\fR required
107
completion time has expired.
110
The default values are 8 for \fIday-start\fR, and 17 for \fIday-end\fR.
113
\fBbusiness-week-days\fR \fIweek-start\fR \- \fIweek-end\fR
115
Used to specify the start and ending days of the business week, where
116
0 is Sunday, 1 is Monday, etc; the days are inclusive. These values
117
are used to determine if a \fIPR\fR required completion time has
121
The default values are 1 for \fIweek-start\fR, and 5 for \fIweek-end\fR.
124
\fBcreate-category-dirs\fR \fItrue\fR|\fIfalse\fR
126
If set to true, database directories for categories are automatically
127
created as needed; otherwise, they must be created manually (usually
128
with the \fBmkcat\fR script). It is suggested that the value be left
132
The default value is \fItrue\fR.
135
.SH "Individual field configuration"
136
Each field in a PR is described with a field entry. It has the general
139
\fBfield\fR "\fIfieldname\fR" {
141
\fBdescription\fR "\fIstring\fR"
143
[ \fIfield-options\fR ... ]
145
\fIdatatype\fR [ \fIdatatype-options\fR ... ]
147
[ \fBon-change\fR { \fIedit-options\fR ... } ]
152
\fIfieldname\fR is used as the field header in the \fIPR\fR. The
153
\fB>\fR and \fB:\fR field markers should not be present in the name.
155
The order in which the field configurations appear in the
156
configuration file determines the order that they appear in the PR
157
text. There is no required order, unlike previous versions of GNATS;
158
multitext and the Unformatted fields can appear anywhere in the PR.
160
The following options may be present within the \fBfield\fR section:
162
\fBbuiltin-name\fR "\fRname\fR"
163
Indicates that this field corresponds to one of the GNATS builtin
167
GNATS has several fields which are required to be present in a
168
\fIPR\fR, and this option is used to map their external descriptions
169
to their internal usage. The internal fieldnames are:
175
number The PR's unique numeric identifier
176
category The category that the PR falls into
177
synopsis The one-line description of the PR
178
confidential If "yes", the PR is confidential
179
severity How severe is the PR?
180
priority What's the PR's priority?
181
responsible Who's responsible for the PR?
182
state What's the frequency, Kenneth?
183
submitter The user that submitted the PR
184
arrival-date When did the PR arrive?
185
last-modified The date of the last PR modification
186
audit-trail The audit-trail of various changes to the PR
189
For these builtin fields, a matching field description must appear in
190
the database configuration. Otherwise, the configuration will be
191
considered invalid, and errors will be generated from the GNATS
192
clients and \fBgnatsd\fR.
195
\fBdescription\fR "\fIdescription text\fR"
196
A one-line human-readable description of the field. Clients
197
can use this string to describe the field in a help dialog; the
198
string is returned from the \fBFDSC\fR command in \fBgnatsd\fR,
199
and is also available via the \fB\-\-field-description\fR option
203
This entry must be present in the field description; there is no default
207
\fBquery-default\fR \fIexact-regexp\fR|\fIinexact-regexp\fR
208
Used to specify the default type of searches performed on this field.
209
This is used when the \fB^\fR search operator appears in a query, and
210
is also used for queries in \fBquery\-pr\fR that use the old \fI\-\-field\fR
214
If the option is not given, the default search is \fIexact\-regexp\fR).
218
If this option is present, the field will be searched when the user
219
performs a --text search from \fBquery-pr\fR. The field is also
220
flagged as a \fItextsearch\fR field in the set of field flags returned
221
by the \fBFIELDFLAGS\fR command in \fBgnatsd\fR.
224
By default, fields are not marked as \fItextsearch\fR fields.
228
The field contents may not be edited; they must be set when the PR
229
is initially created. In general, this should only be used for fields that
230
are given internal values rather than fields supplied by the user.
233
By default, fields are editable by the user.
237
\fIdatatype\fR [ \fIoptions\fR ... ]
238
Describes the type of data to be stored in the field, and must be present
239
in each field description.
242
The available datatypes are:
245
\fBtext\fR [ \fBmatching\fR { "\fIregexp\fR" [ "\fIregexp\fR" ... ] } ]
246
The text datatype is the most commonly used type; it is a one-line
250
If the \fBmatching\fR qualfifier is present, the data in the field
251
must match at least one of the specified regexps. Otherwise, no
252
restriction is placed on what values may appear in the field.
256
\fBmultitext\fR [ { \fBdefault\fR "\fIstring\fR" } ]
257
The field can contain multiple lines of text.
260
If the \fBdefault\fR option is present, the field will default to the
261
specified \fIstring\fR if the field is not given a value when the
262
\fIPR\fR is initially created. Otherwise, the field will be left
271
"\fIstring\fR" [ "\fIstring\fR" ... ]
275
[ \fBdefault\fR "\fIstring\fR" ]
280
Defines an enumerated field, where the value in the PR field must
281
match an entry from a list of specified values.
283
The list of allowed values is given with the \fBvalues\fR option,
284
which must be present.
286
If a \fBdefault\fR option is present, it is used to determine the
287
initial value of the field if no entry for the field appears in an
288
initial PR (or if the value in the initial PR is not one of the
289
acceptable values). However, the value in the \fBdefault\fR
290
statement is not required to be one of the accepted values; this can
291
be used to allow the field to be initially empty, for example.
293
If no \fBdefault\fR option is specified, the default value for the
294
field is the first value in the \fBvalues\fR section.
301
"\fIstring\fR" [ "\fIstring\fR" ... ]
305
[ \fBseparators\fR "\fIstring\fR" ]
307
[ \fBdefault\fR "\fIstring\fR" ]
312
The \fBmultienum\fR datatype is similar to the \fBenum\fR datatype,
313
except that the field can contain multiple values, separated by one or
314
more characters from the \fIseparators\fR list.
316
If no \fBseparators\fR option is present, the default separators are
317
space (` ') and colon (':').
321
\fBenumerated-in-file\fR {
323
\fBpath\fR "\fIfilename\fR"
327
"\fIname\fR" [ "\fIname\fR" ... ]
329
} \fBkey\fR "\fIname\fR"
331
[ \fBallow-any-value\fR ]
335
The \fBenumerated-in-file\fR type is used to describe an enumerated
336
field with an associated \fIadministrative file\fR, which lists the
337
legal values for the field, and may optionally contain additional
338
fields that can be examined by query clients or used for other
339
internal purposes. It is similar to the \fBenum\fR datatype, except
340
that the list of legal values is stored in a separate file.
342
\fIfilename\fR is the name of a file in the \fBgnats-adm\fR administrative
343
directory for the database.
345
The format of the administrative file is a simple ASCII text file.
346
Fields within the file are separated with colons (`:'). Lines
347
beginning with an octothorpe ('#') are ignored as comments. Records
348
within the file are separated with newlines.
350
The \fBfield\fR option is used to name the fields in the
351
administrative file. There must be at least one field, which is used
352
to list the legal values for the field. If the administrative file is
353
empty (or does not contain any non-empty non-comment lines) then the
354
PR field must be empty.
356
The \fBkey\fR option is used to designate which field in the
357
administrative file should be used to list the legal values for the PR
358
field. The value must match one of the field names in the \fBfield\fR
361
If the \fBallow-any-value\fR option is present, then the value of the
362
PR field is not required to appear in the administrative file; any
363
value will be accepted.
367
The date datatype is used to hold dates. Date fields may be empty, or
368
must contain a correctly-formatted date.
371
No defaults or other options are available. The field is left empty if
372
no value for the field is given in the initial PR.
375
\fBinteger\fR [ { \fBdefault\fR "\fIinteger\fR" } ]
376
Integer fields are used to hold numbers. They may be empty, or must
377
contain a value composed entirely of digits, with an optional leading
381
If the \fBdefault\fR option is present, the field will have the
382
value of \fIinteger\fR if the field is not given a value when the
383
\fIPR\fR is initially created. Otherwise, the field will be left
387
The \fBon-change\fR section is used to specify one or more actions
388
to be performed when the field value is edited by the user. It
391
\fBon-change\fR [ "\fIquery-expression\fR" ] {
394
[ \fBadd-audit-trail\fR ]
396
[ \fBaudit-trail-format {
398
\fBformat\fR "\fIformatstring\fR"
400
[ fields { "\fIfieldname\fR" ... } ]
404
[ \fBrequire-change-reason\fR ]
406
[ \fBset-field\fR|\fBappend-to-field\fR "\fIfieldname\fR" {
408
"\fIformat-string\fR" [ \fIfieldlist\fR ]
415
The optional \fIquery-expression\fR controls whether or not the
416
actions in the \fBon-change\fR section are taken. If the expression
417
fails to match, the actions are skipped.
419
The \fBadd-audit-trail\fR option indicates that an entry should be
420
appended to the builtin audit-trail field when this field is changed.
421
The format of the entry is controlled by the optional
422
\fBaudit-trail-format\fR section within the field, or by the global
423
\fBaudit-trail-format\fR section. (See the \fBAudit-trail and
424
outgoing email formats\fR section for more information.)
426
The \fBrequire-change-reason\fR option specifies that a change reason
427
must be present in the PR when this field is edited. This option only
428
makes sense if an audit-trail entry is required, as the change reason
431
The \fBset-field\fR and \fBappend-to-field\fR options are used to
432
change the value of the field \fIfieldname\fR in the PR. The supplied
433
\fBformat\fR is used to format the value that will be placed in the
434
field (for more information, see the \fBAudit-trail and outgoing email
435
formats\fR section of this manual). \fBappend-to-field\fR appends the
436
resulting formatted string to the existing field contents, while
437
\fBset-field\fR completely replaces the contents.
439
Any field may be edited by the \fBset-field\fR or
440
\fBappend-to-field\fR option (the \fBread-only\fR option on a field is
441
ignored). However, the changes are subject to the usual field content
444
There is a global \fBon-change\fR section that is executed once for
446
.SH "Named query definitions"
447
When queries are performed via \fBquery\-pr\fR, they can refer to
448
a query format described via the \fBquery\fR section:
450
\fBquery\fR "\fIqueryname\fR" {
452
\fBformat\fR "\fIformatstring\fR"
454
[ \fBfields\fR { "\fIfieldname\fR" [ "\fIfieldname\fR" ... ] } ]
458
\fIformatstring\fR is as described in the \fBquery-pr\fR(1) manpage;
459
it contains a string with \fBprintf\fR(3)-like % escapes. The output
460
of the query is then formatted as specified by the format string.
462
The \fBfields\fR option lists the fields to be used with the
463
\fBformat\fR string. If the \fBfields\fR option is present without a
464
\fBformat\fR option is, then the listed fields are printed out as just
465
their contents separated by newlines.
467
The named query formats \fIfull\fR, \fIstandard\fR and \fIsummary\fR
468
must be present in the database configuration. \fBfull\fR and
469
\fBsummary\fR correspond to the \fBquery\-pr\fR options \fB--full\fR
470
and \fB--summary\fR, while \fIstandard\fR is used when no format
471
option is given to \fBquery\-pr\fR.
472
.SH "Audit-trail and outgoing email formats"
473
These formats are smilar to the named query formats, but they include
474
more options. They are used for formatting audit-trail entries and
475
for outgoing email messages.
477
There is currently only one audit-trail format, defined by the
478
\fBaudit-trail-format\fR option:
480
\fBaudit-trail-format\fR {
482
\fBformat\fR "\fIformatstring\fR"
484
[\fBfields\fR { "\fIfieldname\fR" [ "\fIfieldname\fR" ... ] } ]
488
For those fields that require an audit-trail entry, the audit-trail
489
text to be appended is formatted as described by this format. The
490
per-field \fBaudit-trail-format\fR is used in preference to this one,
493
\fIformatstring\fR and \fIfieldname\fR are similar to those used by
494
the named query format. \fIfieldname\fR may also be a \fIformat
495
parameter\fR, which is a context-specific value. [Format parameters
496
are distinguished from fieldnames by a leading dollarsign (`$').]
498
The following format parameters are defined for
499
\fBaudit-trail-format\fR entries:
502
The name of the field for which an audit-trail entry is being created.
505
The old value of the field.
510
\fB$EditUserEmailAddr\fR
511
The email address of the user editing the field.
517
The reason for the change; may be blank if no reason was supplied.
519
These parameters may be used anywhere a \fIfieldname\fR can appear.
523
.I Keeping Track: Managing Messages With GNATS
524
(also installed as the GNU Info file
527
.I Reporting Problems Using send-pr
528
(also installed as the GNU Info file
541
Copyright (c) 2000 Free Software Foundation, Inc.
543
Permission is granted to make and distribute verbatim copies of
544
this manual provided the copyright notice and this permission notice
545
are preserved on all copies.
547
Permission is granted to copy and distribute modified versions of this
548
manual under the conditions for verbatim copying, provided that the
549
entire resulting derived work is distributed under the terms of a
550
permission notice identical to this one.
552
Permission is granted to copy and distribute translations of this
553
manual into another language, under the above conditions for modified
554
versions, except that this permission notice may be included in
555
translations approved by the Free Software Foundation instead of in
556
the original English.
added
removed
gnats/man/dbconfig.man
