HP OpenVMS Systems Documentation

Content starts here

Compaq TCP/IP Services for OpenVMS

Previous Contents Index

5.3.1 BIND Configuration Logging Statement

The logging statement configures a wide variety of logging options for the name server. Its channel phrase associates output methods, format options, and severity levels with a name that can then be used with the category phrase to select how various classes of messages are logged. The logging statement has the following syntax:

logging {
   [ channel channel_name {
     ( file path_name
       [ versions ( number | unlimited ) ]
       [ size size_spec ]
       | syslog ( kern | user | mail | daemon | auth | syslog | lpr |
                  news | uucp | cron | authpriv | ftp |
                local0 | local1 | local2 | local3 |
                local4 | local5 | local6 | local7 )
       | null;

   [ severity ( critical | error | warning | notice |
                   info  | debug [ level ] | dynamic ); ]
   [ print-category yes_or_no; ]
   [ print-severity yes_or_no; ]
   [ print-time yes_or_no; ]
}; ]

   [ category category_name {
     channel_name; [ channel_name; ... ]
}; ]

Only one logging statement is used to define as many channels and categories as you want. If there are multiple logging statements in a configuration file, the first one that is defined determines the logging, and warnings are issued for the others. If there is no logging statement, the logging configuration is:

    logging {
        category default { default_syslog; default_debug; };
        category panic { default_syslog; default_stderr; };
        category packet { default_debug; };
        category eventlib { default_debug; };

All logged statements channeled to syslog facilities are directed to the TCPIP$BIND_RUN.LOG file. Channel Phrase

All log output goes to one or more channels. You can create as many channels as you want.

Every channel definition must include a clause that says whether messages selected for the channel go to a file or to a particular syslog facility, or are discarded. Optionally, it can also limit the message severity level that is accepted by the channel (default is info ), and whether to include a name server-generated timestamp, the category name, and severity level (default is not to include any).

The word null as the destination option for the channel causes all messages sent to it to be discarded; other options for the channel are meaningless.

There is a severity clause that allows you to specify the level of diagnostic messages to be logged.

The server can supply extensive debugging information when it is in debugging mode. If the server's global debugging level is greater than zero, then debugging mode is active. The global debugging level is set by one of the following:

  • Starting the server with the "-d" flag, followed by a positive integer
  • Sending the server the SIGUSR1 signal (for example, by entering SYS$SYSTEM:TCPIP$BIND_SERVER_CONTROL.EXE TRACE)

The global debugging level can be set to zero, and the debugging mode turned off, by sending the server the SIGUSR2 signal (by entering SYS$SYSTEM:TCPIP$BIND_SERVER_CONTROL.EXE NOTRACE). All debugging messages in the server have a debugging level; the higher debugging levels provide more detailed output. Channels that specify a particular debugging severity will get debugging output of level 3 or less any time the server is in debugging mode, regardless of the global debugging level. Channels with dynamic severity use the server's global level to determine what messages to display, as shown in the following example:

    channel specific_debug_level {
        file "foo";
        severity debug 3;

If print-time is turned on, the date and time are logged. print-time can be specified for a syslog channel, but that is usually pointless since syslog also prints the date and time. If print-category is requested, then the category of the message is logged as well. Finally, if print-severity is on, then the severity level of the message is logged. The print- options can be used in any combination and are always displayed in the following order: time, category, severity. In the following example, all three print- options are on:

    28-Apr-1997 15:05:32.863 default: notice: Ready to answer queries.

There are four predefined channels that are used for the BIND server's default logging, as shown in the following example. Section describes how these channels are used.

channel default_syslog {
    syslog daemon;      # send to syslog's daemon facility
    severity info;      # only send priority info and higher
channel default_debug {
    file "TCPIP$BIND_RUN.LOG";   # write to TCPIP$BIND_RUN.LOG in the
                                 # working directory
    severity dynamic;            # log at the server's current debug level
channel default_stderr {# writes to stderr
    file "stderr";      # this is illustrative only; there's currently
                        # no way of specifying an internal file
                        # descriptor in the configuration language.
    severity info;      # only send priority info and higher

channel null {
    null;               # toss anything sent to this channel

Once a channel is defined, it cannot be redefined. Thus you cannot alter the built-in channels directly, but you can modify the default logging by pointing categories at channels you have defined. Category Phrase

There are many categories, so you can send the logs you want to see anywhere, without seeing logs you do not want. If you do not specify a list of channels for a category, then log messages in that category are sent to the default category instead. If you do not specify a default category, the following "default default" is used:

category default { default_syslog; default_debug; };

For example, if you want to log security events to a file but you also want to keep the default logging behavior, specify the following:

channel my_security_channel {
    file "my_security_file";
    severity info;
category security { my_security_channel;

To discard all messages in a category, specify the null channel:

category lame-servers { null; };
category cname { null; };

The following categories are available:

default The catch-all. Many things are not categorized, and they end up here. Also, if you do not specify any channels for a category, the default category is used instead. If you do not define the default category, the following definition is used:
category default { default_syslog; default_debug; };

config High-level configuration file processing.
parser Low-level configuration file processing.
queries A short log message is generated for every query the server receives.
lame-servers Messages like "Lame server on ..." .
statistics Statistics.
panic If the server has to shut itself down because of an internal problem, it logs the problem in this category as well as in the problem's native category. If you do not define the panic category, the following definition is used:
category panic { default_syslog; default_stderr; };

update Dynamic updates.
ncache Negative caching.
xfer-in Zone transfers the server is receiving.
xfer-out Zone transfers the server is sending.
db All database operations.
eventlib Debugging information from the event system. Only one channel can be specified for this category, and it must be a file channel. If you do not define the eventlib category, the following definition is used:
category eventlib { default_debug; };

packet Dumps of packets received and sent. Only one channel can be specified for this category, and it must be a file channel. If you do not define the packet category, the following definition is used:
category packet { default_debug; };

notify The NOTIFY protocol.
cname Messages like "... points to a CNAME".
security Approved and unapproved requests.
os Operating system problems.
insist Internal consistency check failures.
maintenance Periodic maintenance events.
load Zone loading messages.
response-checks Messages arising from response checking, such as "Malformed response ...", "wrong ans. name ...", "unrelated additional info ...", "invalid RR type ...", and "bad referral ...".

5.3.2 BIND Configuration Options Statement

The options statement sets up global options to be used by BIND. This statement can appear only once in a configuration file; if more than one occurrence is found, the first occurrence determines the actual options used, and a warning is generated. If there is no options statement, an options block with each option set to its default is used. The options statement has the following syntax:

options {
[ directory path_name; ]
[ named-xfer path_name; ]
[ dump-file path_name; ]
[ pid-file path_name; ]
[ statistics-file path_name; ]
[ auth-nxdomain yes_or_no; ]
[ fake-iquery yes_or_no; ]
[ fetch-glue yes_or_no; ]
[ multiple-cnames yes_or_no; ]
[ notify yes_or_no; ]
[ recursion yes_or_no; ]
[ forward ( only | first ); ]
[ forwarders { [ in_addr ; [ in_addr ; ... ] ] }; ]
[ check-names ( master | slave | response ) ( warn | fail | ignore); ]
[ allow-query { address_match_list }; ]
[ allow-transfer { address_match_list }; ]
[ listen-on [ port ip_port ] { address_match_list }; ]
[ query-source [ address ( ip_addr | * ) ] [ port ( ip_port | * ) ] ; ]
[ max-transfer-time-in number; ]
[ transfer-format ( one-answer | many-answers ); ]
[ transfers-in  number; ]
[ transfers-out number; ]
[ transfers-per-ns number; ]
[ coresize size_spec ; ]
[ datasize size_spec ; ]
[ files size_spec ; ]
[ stacksize size_spec ; ]
[ cleaning-interval number; ]
[ interface-interval number; ]
[ statistics-interval number; ]
[ topology { address_match_list }; ]

}; Path Names

Table 5-3 lists the path name options.

Table 5-3 Path Name Options
Option Description
directory The working directory of the server specified as an absolute path. Any nonabsolute path names in the configuration file are relative to this directory. The default location for most server output files (such as, TCPIP$BIND_RUN.LOG) is this directory. If you do not specify a directory, the working directory defaults to SYS$SPECIFIC:[TCPIP$BIND]. If you are configuring a BIND failover environment, the working directory is defined by the logical TCPIP$BIND_COMMON.
dump-file The path name of the file the server dumps the database to when it receives a SIGINT signal (TCPIP$BIND_SERVER_CONTROL.EXE dumpdb). If not specified, the default is TCPIP$BIND_SERVER_ZONES_DUMP.DB.
memstatistics-file The path name of the file the server writes memory usage statistics to on exit, if deallocate-on-exit is yes. If not specified, the default is TCPIP$BIND_SERVER_MEMSTATISTICS.LOG.
pid-file The path name of the file in which the server writes its process ID. If not specified, the default is TCPIP$BIND_SERVER.PID. The pid-file is used by programs like TCPIP$BIND_SERVER_CONTROL.EXE that want to send signals to the running name server.
statistics-file The path name of the file the server appends statistics to when it receives a SIGILL signal (TCPIP$BIND_SERVER_CONTROL.EXE stats). If not specified, the default is TCPIP$BIND_SERVER_STATISTICS.LOG.

Example 5-1 shows how to specify path name options with the options statement.

Example 5-1 Path Name Options

options {
 directory   "SYS$SPECIFIC:[TCPIP$BIND]";
}; Boolean Options

Table 5-4 lists the Boolean options.

Table 5-4 Boolean Options
Option Description
auth-nxdomain If yes, then the AA bit is always set on NXDOMAIN responses, even if the server is not actually authoritative. The default is yes. Do not turn off auth-nxdomain unless you are knowledgeable about the option, as some older versions of software may respond unpredictably.
deallocate-on-exit If yes, then when the server exits, it deallocates every object it allocated, and then writes a memory-usage report to the memstatistics-file . The default is no, because it is faster to let the operating system clean up. The deallocate-on-exit option is useful for detecting memory leaks.
fake-iquery If yes, the server simulates the obsolete DNS query type IQUERY. The default is no.
fetch-glue If yes (the default), the server fetches "glue" resource records it does not have when constructing the additional data section of a response. no-fetch-glue can be used with no-recursion to prevent the server's cache from growing or becoming corrupted (at the cost of requiring more work from the client).
host-statistics If yes, then statistics are kept for every host that the name server interacts with. The default is no. Note that turning on host-statistics can consume huge amounts of memory.
multiple-cnames If yes, then multiple CNAME resource records allow for a domain name. The default is no. Allowing multiple CNAME records is against standards and is not recommended. Multiple CNAME support is available because previous versions of BIND allowed multiple CNAME records, and these records have been used for load balancing by a number of sites.
notify If yes (the default), DNS NOTIFY messages are sent when a zone for which the server is authoritative changes. The use of NOTIFY speeds convergence between the master and its slaves. Slave servers that receive a NOTIFY message and understand it contact the master server for the zone to see if they need to do a zone transfer; if they do, the servers initiate the zone transfer immediately. The notify option can also be specified in the zone statement, in which case it overrides the options notify statement.
recursion If yes, and a DNS query requests recursion, then the server attempts to do all the work required to answer the query. If recursion is not on, the server returns a referral to the client if it doesn't know the answer. The default is yes. See also fetch-glue above.

Example 5-2 shows how to specify Boolean options in an options statement.

Example 5-2 Boolean Options

options {
 auth-nxdomain  yes;
 deallocate-on-exit no;
 fake-iquery  no;
 fetch-glue  yes;
 host-statistics  no;
 multiple-cnames  no;
 notify   yes;
 recursion  yes;
}; Forwarding

You can use the forwarding facility to create a large sitewide cache on a few servers, reducing traffic over links to external name servers. You can also use the forwarding facility to allow queries by servers that do not have direct access to the Internet, but wish to look up exterior names anyway. Forwarding occurs on only those queries for which the server is not authoritative and does not have the answer in its cache. Table 5-5 lists the forwarding options.

Table 5-5 Forwarding Options
Option Description
forward This option is meaningful only if the forwarders list is not empty.
first Causes the server to query the forwarders first. If that does not answer the question, the server looks for the answer itself. A ROOT.HINT file must be present. This is the default.
only The server queries only the forwarders. A ROOT.HINT file is not necessary.
forwarders Specifies the IP addresses to be used for forwarding. The default is the empty list (no forwarding).

Example 5-3 shows how to specify an options statement to invoke forwarding.

Example 5-3 Forwarding Options

options {
 forwarders {;;
 forward first;
}; Name Checking

The server can check domain names based on their expected client contexts. For example, a domain name used as a host name can be checked for compliance with the RFCs defining valid host names. Table 5-6 describes the three name-checking methods.

Table 5-6 Name Checking Options
Option Description
ignore No checking is done.
warn Names are checked against their expected client contexts. Invalid names are logged, but processing continues normally.
fail Names are checked against their expected client contexts. Invalid names are logged, and the offending data is rejected.

The server can check names in three areas: master zone files, slave zone files to queries the server has initiated. If check-names response fail has been specified, and answering the client's question would require sending an invalid name to the client, the server sends a REFUSED response code to the client. The defaults are:

  • check-names master fail
  • check-names slave warn
  • check-names response ignore

The check-names option can also be specified in the zone statement, in which case it overrides the options check-names statement. When used in a zone statement, the area is not specified (because it can be deduced from the zone type).

Example 5-4 shows how to specify an options statement for name checking. The statement specifies that nonconforming names coming from a slave are ignored.

Example 5-4 Name Checking Options

options  {
          check-names slave ignore;

Previous Next Contents Index