4.3 The dbconfig file

The ‘dbconfig’ configuration file controls the configuration of a GNATS database. Each database has its own individual copy of this file, which is located in the ‘gnats-adm’ subdirectory of the database.

The file consists of standard plain text. Whitespace is completely optional and is ignored. Sets of braces ‘@’ are used to delimit the different sections, and all non-keyword values must be surrounded with double quotes. The values in ‘dbconfig’ can be changed at any time; the new values take effect for all subsequent iterations of GNATS tools.

The ‘dbconfig’ file contains 6 major sections, which must appear in the following order:

• Overall database configuration
• Individual field configuration
• Named query definitions
• Audit-trail and outgoing email formats
• Index file description
• Initial Problem Report input fields

The different sections are described below. While reading the following sections, it will be useful to refer to the sample ‘dbconfig’ file which is installed when a new database is initialized with the mkdb tool. In fact, the sample file provides a configuration that should be usable for a great range of sites, since it reproduces the behaviour of the older, less customizable 3.x versions of GNATS.

4.3.1 Overall database configuration

The overall database options are controlled by settings in the database-info section of the ‘dbconfig’ file. The following is the general format of this section:

database-info {
  [options]
}

The following options and values may be used in the database-info section:

debug-mode  true | false

If set to true, the database is placed into debug mode. This causes all outgoing email to be sent to the gnats-admin user listed in the ‘responsible’ file of the database. The default value is false.

keep-all-received-headers  true | false

If set to true, all of the Received: headers for PRs submitted via email are kept in the PR. Otherwise, only the first one is kept. The default value is false.

notify-about-expired-prs  true | false

If set to true, notification email about expired PRs is sent via the at-pr command. Otherwise, required times for PR fixes are not used. The default value is false.

send-submitter-ack  true | false

When new PRs are submitted to the database, an acknowledgment email will be sent to the submitter of send-submitter-ack is set to true. This is in addition to the normal notification mail to the person(s) responsible for the new PR. The default value is false.

libexecdir  "directory"

Specifies the directory where the GNATS administrative executables are located. In particular, at-pr and mail-pr are invoked from this directory. The default value is the empty string, which is unlikely to be useful.

business-day-hours  day-start - day-end

Used to specify the hours that define a business day. The values are inclusive and should be given in 24-hour format, with a dash separating them. GNATS uses these values to determine whether the required completion time for a PR has passed. The default values are 8 for day-start and 17 for day-end.

business-week-days  week-start - week-end

Specifies the start and ending days of the business week, where 0 is Sunday, 1 is Monday, etc. The days are inclusive, and the values should be given with a dash separating them. GNATS uses these values to determine whether the required completion time for a PR has passed. The default values are 1 for week-start and 5 for week-end.

create-category-dirs  true | false

If set to true, database directories for categories are automatically created as needed. Otherwise, they must be created manually (usually with the mkcat script). It is recommended that the default value of true be kept.

category-dir-perms  mode

Standard octal mode-specification specifying the permissions to be set on auto-created category directories. Default is 0750, yielding user read, write and execute, and group read and execute. Note that if you have local users on the GNATS server itself, running for instance query-pr, you may need to change the permissions to 0755.

4.3.2 Individual field configuration

Each type of field in a PR must be described with a field section in the ‘dbconfig’ file. These sections have the following general structure:

field "fieldname" {
  description "string"
  [ field-options ... ]
  datatype [ datatype-options ... ]
  [ on-change { edit-options ... } ]
}

fieldname is used as the field header in the PR. The characters > and : are used internally as field markers by GNATS, so they must not be used in fieldnames.

The order in which the field sections appear in the ‘dbconfig’ file determines the order in which they appear in the PR text. There is no required order, unlike previous versions of GNATS — the Unformatted field and multitext fields may appear anywhere in the PR.

The following field-options may be present within a field section:

builtin-name  "name"

Indicates that this field corresponds to one of the GNATS built-in fields.

GNATS has several fields which are required to be present in a PR, and this option is used to map their external descriptions to their internal usage. The external field names are:

arrival-date

The arrival date of the PR

audit-trail

The audit-trail recording changes to the PR

category

The category that the PR falls into

closed-date

The date that the PR was closed

confidential

If set to yes, the PR is confidential

description

A description of the problem

last-modified

The date the PR was last modified

number

The PR’s unique numeric identifier

originator

The originator of the PR

priority

Priority of the PR

responsible

The person responsible for handling the PR

severity

Severity of the problem described by the PR

state

The current state of the PR

submitter-id

The user that submitted the PR

synopsis

The one-line description of the PR

unformatted

PR text which cannot be parsed and associated with other fields.

For these built-in fields, a matching field description must appear in the ‘dbconfig’ file. Otherwise, the configuration will be considered invalid, and errors will be generated from the GNATS clients and gnatsd. We also recommend that you leave the actual fieldnames of these fields at their default values (i.e. capitalized versions of their built-in names), since some clients may depend on these names.

description  "description text"

A one-line human-readable description of the field. Clients can use this string to describe the field in a help dialog. The string is returned from the FDSC command in gnatsd and is also available via the --field-description option in query-pr.

This entry must be present in the field description, and there is no default value.

query-default  exact-regexp | inexact-regexp

Used to specify the default type of searches performed on this field. This is used when the ^ search operator appears in a query, and is also used for queries in query-pr that use the old --field query options.

If the option is not given, the default search is exact-regexp.

textsearch

If this option is present, the field will be searched when the user performs a --text search from query-pr. The field is also flagged as a textsearch field in the set of field flags returned by the FIELDFLAGS command in gnatsd.

By default, fields are not marked as textsearch fields.

read-only

When this option is present, the field contents may not be edited — they must be set when the PR is initially created. In general, this should only be used for fields that are given as internal values rather than fields supplied by the user.

By default, editing is allowed.

4.3.3 Field datatypes

Each field description has to contain a datatype declaration which describes what data are to be store in the field. The general format for such a declaration is

datatype  [ options ... ]

The available datatypes are:

text  [ matching { "regexp" [ "regexp" ... ] } ]

The text datatype is the most commonly used type; it is a one-line text string.

If the matching qualifier is present, the data in the field must match at least one of the specified regexps. This provides an easy and flexible way to limit what text is allowed in a field. If no matching qualifier is present, no restriction is placed on what values may appear in the field.

multitext  [ { default "string" } ]

The field can contain multiple lines of text.

If the default option is present, the field will default to the specified string if the field is not given a value when the PR is initially created. Otherwise, the field will be left empty.

enum  {

  values {

    "string" [ "string" ... ]

  }

  [ default "string" ]

}

Defines an enumerated field, where the values in the PR field must match an entry from a list of specified values. The list of allowed values is given with the values option. The values option is required for an enumerated field.

If a default option is present, it is used to determine the initial value of the field if no entry for the field appears in an initial OR (or if the value in the initial PR is not one of the acceptable values). However, the value in the default statement is not required to be one of the accepted values; this can be used to allow the field to be initially empty, for example.

If no default option is specified, the default value for the field is the first value in the values section.

multienum  {

  values {

    "string" [ "string" ... ]

  }

  [ separators "string" ]

  [ default "string" ]

}

The multienum datatype is similar to the enum datatype, except that the field can contain multiple values, separated by one or more characters from the separators list. If no separators option is present, the default separators are space (‘ ’) and colon (‘:’).

The values in the default string for this field type should be separated by one of the defined separators. An example clarifies this. If we have a field named ingredients where the default values should be ‘sugar’, ‘flour’ and ‘baking powder’ and the separator is a colon ‘:’, the following sets these defaults:

default "sugar:flour:baking powder"

enumerated-in-file {

  path "filename"

  fields {

    "name" [ "name" ... ]

  } key "name"

  [ allow-any-value ]

}

The enumerated-in-file type is used to describe an enumerated field with an associated administrative file which lists the legal values for the field, and may optionally contain additional fields that can be examined by query clients or used for other internal purposes. It is similar to the enum datatype, except that the list of legal values is stored in a separate file. An example of this kind of field is the built-in Category field with its associeted ‘categories’ administrative file.

filename is the name of a file in the ‘gnats-adm’ administrative directory for the database.

The format of the administrative file should be simple ASCII. Subfields within the file are separated with colons (‘:’). Lines beginning with a hash sign (‘#’) are ignored as comments. Records within the file are separated with newlines.

The field option is used to name the subfields in the administrative file. There must be at least one subfield, which is used to list the legal values for the field. If the administrative file is empty (or does not contain any non-empty non-comment lines), the PR field must be empty.

The key option is used to designate which field in the administrative file should be used to list the legal values for the PR field. The value must match one of the field names in the field option.

If the allow-any-value option is present, the value of the PR field is not required to appear in the administrative file — any value will be accepted.

Note that there is no default keyword for enumerated-in-file. These fields get their default value from the first entry in the associated administrative file.

multi-enumerated-in-file {

  path "filename"

  fields {

    "name" [ "name" ... ]

  } key "name"

  [ default "string" ]

  [ allow-any-value ]

  [ separators "string" ]

}

multi-enumerated-in-file is to multienum what enumerated-in-file is to enum. Its options have the same meaning as their counterparts in the multienum and enumerated-in-file fields.

NOTE: Keywords may appear in any sequence, with one exception – the separators keyword, if present, has to come last. This rule only applies to fields of type multi-enumerated-in-file.

date

The date datatype is used to hold dates. Date fields must either be empty or contain a correctly formatted date.

No defaults or other options are available. The field is left empty if no value for the field is given in the initial PR.

integer  [ { default "integer" } ]

Integer fields are used to hold numbers. They must either be empty or contain a value composed entirely of digits, with an optional leading sign.

If the default option is present, the field will have the value of integer if the field is not given a value when the PR is initially created. Otherwise, the field will be left empty.

4.3.4 Edit controls

The on-change subsection of a fields section specifies one or more actions to be performed when the field value is edited by the user. It has the general form

on-change [ "query-expression" ] {
  [ add-audit-trail ]
  [ audit-trail-format {
    format "formatstring"
    [ fields { "fieldname" ... } ]
  } ]
  [ require-change-reason ]
  [ set-field | append-to-field "fieldname" {
    "format-string" [ fieldlist ]
  } ]
  [ require { "fieldname" ... } ]
}

The optional query-expression controls whether or not the actions in the on-change section are taken. If the expression fails to match, the actions are skipped.

The add-audit-trail option indicates that an entry should be appended to the PR’s audit-trail when this field is changed. The format of the entry is controlled by the optional audit-trail-format section within the field, or by the global audit-trail-format section. See Audit-trail formats and Outgoing email formats.

The require-change-reason option specifies that a change reason must be present in the PR when this field is edited. This option only makes sense if an audit-trail entry is required, as the change reason is otherwise unused.

The set-field and append-to-field options are used to change the value of the field fieldname in the PR. The supplied format is used to format the value that will be placed in the field.

append-to-field appends the resulting formatted string to the existing, while set-field completely replaces the contents.

Any field may be edited by the set-field or append-to-field option (the read-only option on a field is ignored). However, the changes are subject to the usual field content checks.

The require option specifies that one or more fields must have a (non-blank) value when this field is changed.

A field may be enforced to have a (non-blank) value at all times by including it in the set of fields required for the initial PR, see Initial PR input fields, as well as in the set of fields required on change of the field itself.

There is also a global on-change section that is executed once for each PR edit. A typical use for such a section is to set the last-modified date of the PR.

4.3.5 Named query definitions

When queries are performed via query-pr, they can refer to a query format described by a query section in the ‘dbconfig’ file:

query "queryname" {
  format "formatstring"
  [fields { "fieldname" [ "fieldname" ... ] } ]
}

formatstring is as described in Formatting query-pr output. It basically contains a string with printf-like % escapes. The output of the query is formatted as specified by this format string.

The fields option lists the fields to be used with the format string. If the fields option is present without a format option, the contents of the listed fields are printed out, separated by newlines.

The named query formats full, standard amd summary must be present in the ‘dbconfig’ file. full and summary correspond to the query-pr options --full and --summary, while standard is used when no format option is given to query-pr.

4.3.6 Audit-trail formats

These formats are similar to the named query formats, but they include more options. They are used for formatting audit-trail entries and for outgoing email messages.

There is currently only one audit-trail format, defined by the audit-trail-format option:

audit-trail-format {
  format "formatstring"
  [ fields { "fieldname" [ "fieldname" ... ] } ]
}

For those fields that require an audit-trail entry, the audit-trail text to be appended is formatted as described by this format. The per-field audit-trail-format is used in preference to this one, if it exists.

formatstring and fieldname are similar to those used by the named query format. fieldname may also be a format parameter, which is a context-specific value. (Format parameters are distinguished from fieldnames by a leading dollar sign (‘$’)).

The following format parameters are defined for audit-trail-format entries:

$Fieldname

The name of the field for which an audit-trail entry is being created.

$OldValue

The old value of the field.

$NewValue

The new field value.

$EditUserEmailAddr

The email address of the user editing the field. Set by the EDITADDR gnatsd command or from the ‘responsible’ file; if not available, user’s local address is used.

$CurrentDate

The current date.

$ChangeReason

The reason for the change; may be blank if no reason was supplied.

These parameters may be used anywhere a fieldname can appear.

4.3.7 Outgoing email formats

During the life of a PR, GNATS can be configured to send out a range of email messages. When a PR first arrives, an acknowledgment message is sent out if the send-submitter-ack parameter above is set to true. Certain edits to the PR may also cause email to be sent out to the various parties, and if a PR is deleted, GNATS may send notification email.

The formats of the email messages are controlled by mail-format sections in the ‘dbconfig’ file. The general structure of a mail-format section is as follows:

mail-format "format-name" {
  from-address {
    [ fixed-address "address" ]
    [ email-header-name | [ mail-header-name | ... ] ]
  }
  to-address {
    [ fixed-address "address" ] 
    [ "email-header-name" | [ "mail-header-name" | ... ] ]
  }
  reply-to {
    [ fixed-address "address" ]
    [ "email-header-name" | ... ] | [ "gnats-field-name" | ... ]
  }
  header {
    format "formatstring"
    [ fields { "fieldname" [ "fieldname" ... ] } ]
  }
  body {
    format "formatstring"
    [ fields { "fieldname" [ "fieldname" ... ] } ]
  }
}

gnats recognizes and uses 6 different format-name values:

initial-response-to-submitter

Format of the message used when mailing an initial response back to the PR submitter. This message will only be sent if send-submitter-ack in the overall database configuration is set to true.

initial-pr-notification

Format of the message sent to the responsible parties when a new PR with category different from “pending” arrives.

initial-pr-notification-pending

Format of the message sent to the responsible parties when a new PR that ends up with category “pending” arrives.

appended-email-response

Format of the notification message sent out when a response to a PR is received via email.

audit-mail

Format of the message sent out when a PR edit generates an Audit-Trail entry.

deleted-pr-mail

Format of the message sent out when a PR is deleted.

The from-address, to-address and reply-to subsections of a mail-format section specify the contents of the To:, From: and Reply-To: headers in outgoing email. There are two ways to specify the contents: by using a fixed-address specification, or by specifying email-header-names or gnats-field-names.

When an email-header-name or gnats-field-name value is given, GNATS will attempt to extract an email address from the specified location. If several values are given on the same line, separated by ‘|’ characters, GNATS will try to extract an address from each location in turn until it finds a header or field which is nonempty. The following example should clarify this:

mail-format "initial-response-to-submitter" {
  from-address {
    fixed-address "gnats-admin"
  }
  to-addresses {
    "Reply-To:" | "From:" | "Submitter-Id"
  } …

This partial mail-format section specifies the format of the address headers in the email message that is sent out as an acknowledgment of a received PR. The From: field of the message will contain the email address of the GNATS administrator, as specified by the gnats-admin line in the ‘responsible’ file. To fill in the To: header, GNATS will first look for the mail header Reply-To: in the PR and use the contents of that, if any. If that header doesn’t exist or is empty, it will look for the contents of the From: email header, and if that yields nothing, it will look for the GNATS Submitter-Id field and use the contents of that.

Other email headers to be included in messages sent out by GNATS can be specified by header subsections of the mail-header section. formatstring and fieldname are similar to those used by the named query format. Each header line must have a newline character (‘\n’) at the end.

The email message body is specified in the body subsection of the mail-format section. Just as for a header section, the body section must contain a formatstring and fieldname values.

For some of the formats that GNATS recognizes, special variables are available for use. The following table lists the formats that provide special variables. See the example below for an illustration of how they are used.

appended-email-response

$MailFrom

The From: line of the original message.

$MailTo

The To: line of the original message.

$MailSubject

The Subject: line of the original message.

$MailCC

The CC: line of the original message.

$NewAuditTrail

The text of the new audit trail entry (corresponds to the body of the message).

audit-mail

$EditUserEmailAddr

The email address of the user editing the PR. Set by the EDITADDR gnatsd command or from the ‘responsible’ file; if not available, user’s local address is used.

$OldResponsible

The previous Responsible field entry, if it was changed.

$NewAuditTrail

The Audit-Trail: entries that have been appended by the edits.

deleted-pr-mail

$EditUserEmailAddr

The email address of the user deleting the PR. Set by the EDITADDR gnatsd command or from the ‘responsible’ file; if not available, user’s local address is used.

$PRNum

The number of the PR that was deleted.

The following example illustrates the use of these special variables:

mail-format "deleted-pr-mail" {
  from-address {
    "$EditUserEmailAddr"
  }
  to-addresses {
    fixed-address "gnats-admin"
  }
  header {
    format "Subject: Deleted PR %s\n"
    fields { "$PRNum" }
  }
  body {
    format "PR %s was deleted by user %s.\n"
    fields { "$PRNum" "$EditUserEmailAddr" }
  }
}

This mail-format section specifies the format of the email message that is sent out when a PR is deleted. The From: field is set to the email address field of the user who deleted the PR, the subject of the message contains the number of the deleted PR, and the message body contains both the PR number and the user’s email address.

4.3.8 Index file description

The index section of the ‘dbconfig’ file lists the fields that appear in the database index. The index is always keyed by PR number. The general format for the index section is

index {
  path "file"
  fields { "fieldname" [ "fieldname" ... ] }
  binary-index true | false
  [ separator "symbol" ]
}

The path parameter gives the name of the index file in the ‘gnats-adm’ directory of the database. Only one index is allowed per database, so only one path entry is allowed.

The fields parameter controls what fields will appear, and in what order, in the index. Fields are listed by their names, separated by spaces (‘ ’). Fields will appear in the order they are listed.

The binary-index parameter controls whether the index is supposed to be in plaintext or binary format. Binary format is recommended, as it avoids potential problems when field separators appear as bona-fide field contents.

When plaintext format is used, by setting binary-index false, the symbol (‘|’) is used as a field separator in the index, unless the optional separator parameter is used to redefine the separator character.

4.3.9 Initial PR input fields

An initial-entry section in the ‘dbconfig’ file is used to describe which fields should be present on initial PR entry; this is used by tools such as send-pr to determine which fields to include in a “blank” PR template. An optional require parameter can be defined to specify a subset of the intial-entry fields which must be assigned a value upon initial creation of the PR.

The general format for the initial-entry section is

initial-entry {
  fields { "fieldname" [ "fieldname" ... ] }
  [ require { "fieldname" [ "fieldname" ... ] } ]
}

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