| Previous | Contents | Index |
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.
5.3.1.1 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:
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 5.3.1.2 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.
5.3.1.2 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;
default_syslog;
default_debug;
};
|
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 ...". |
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 }; ]
};
|
Table 5-3 lists the 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]";
dump-file "TCPIP$BIND_SERVER_ZONES_DUMP.DB";
memstatistics-file "TCPIP$BIND_SERVER_MEMSTATISTICS.LOG";
pid-file "TCPIP$BIND_SERVER.PID";
statistics-file "TCPIP$BIND_SERVER_STATISTICS.LOG"
};
|
Table 5-4 lists the 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;
};
|
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.
| Option | Description | ||||
|---|---|---|---|---|---|
| forward |
This option is meaningful only if the
forwarders
list is not empty.
|
||||
| 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 {
1.2.3.4;
5.6.7.8;
};
forward first;
};
|
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.
| 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:
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 |