DNS BIND9 logging Clause

[NickTheGreek 160]

DNS BIND9 logging Clause

This section describes the logging clause which prior to BIND 9 needed to appear first in the named.conf file. This no longer the case and it may appear anywhere convenient. BIND uses syslogd before a valid logging clause is available so named.conf parse errors and other information will appear in /var/log/messages (depending on syslog.conf) prior to, or in the absence of, a valid logging clause. In the case of windows parse errors are written to the Event Log. Only one logging clause can be defined but multiple channels may be defined to stream logs.

logging Clause Syntax

BIND provides comprehensive logging features. Values in bold type below are keywords;

logging {
   [ channel channel_name {
     ( file path name
         [ versions ( number | unlimited ) ]
         [ size size_spec ]
       | syslog syslog_facility
       | stderr
       | null );
     [ severity (critical | error | warning | notice |
                 info | debug [ level ] | dynamic ); ]
     [ print-category yes | no; ]
     [ print-severity yes | no; ]
     [ print-time yes | no; ]
   }; ]
   [ category category_name {
     channel_name ; [ channel_name ; ... ]
   }; ]
   ...
};

The following notes describe the various fields and values:

channel channel_name	BIND will accept multiple channel definitions in a single logging statement. 'channel_name' is normally written as a non-space name, for instance, my_channel but it can be written as a quoted string, for instance, "my channel". It is an arbitrary but unique name used to associate the category statement with this channel definition or it may take one of the standard (pre-defined) values below: "default_syslog" log everything to syslog (default logging destination) "default_debug"   "default_stderr" output to stderr (normally the console) "null" discard all log entries (write to /dev/null)
file	'path_name' is a quoted string defining the absolute path to the logging file, for example, "/var/log/named/namedlog.log". From the grammar above 'file', 'syslog', 'stderr' and 'null' are mutually exclusive for a 'channel'.
versions	'versions' may take the parameter 'number' or 'unlimited' and defines the number of file versions that should be kept by BIND. Version files are created by BIND by appending .0, .1 etc to the file named defined by the file parameter. Files are 'rolled' (renamed or overwritten) so .0 will always contain the last log information prior to commencing the new log., .1 the next and so on. 'unlimited' currently implies 'versions 99'. Unless a sizeparameter is used new log versions will only be 'rolled' when BIND is restarted. If no versions statement is defined a single log file of unlimited size is used and on restart new data is appended to the defined file. This can get to be a very big file.
size size_spec	'size' allows you to define a limit to the file size created. A numeric only size_spec value is assumed to be the size in bytes, you may use the short forms k or K, m or M, g or G e.g. 25m = 25000000. size and versions are related in the following way: If you specify a size value and NO versions parameter when the size limit is reached BIND will stop logging until the file size is reduced to below the threshold defined i.e. by deleting or truncating the file. If you specify a size AND a versions parameter the log files will be 'rolled' (renamed and overwritten as defined in the versions section above) when the size limit is reached. If you specify NO size AND a versions parameter the log files will be 'rolled' (renamed and overwritten as defined in the versions section above) only when BIND is restarted.
syslog syslog_facility	'syslog' indicates that this channel will use syslogd logging features (as defined in syslog.conf). The syslog_facility is the facility definition for 'syslog' and may be found in syslog's man pages. From the grammar above 'file', 'syslog', 'stderr' and 'null' are mutually exclusive for a 'channel'.
stderr	'stderr' writes to the current standard out and would typically be only used for debug purposes. From the grammar above 'file', 'syslog', 'stderr' and 'null' are mutually exclusive for a 'channel'.
null	'null' writes to /dev/null - the bit bucket, nowhere. It does not produce a log. From the grammar above 'file', 'syslog', 'stderr' and 'null' are mutually exclusive for a 'channel'.
severity	Controls the logging levels and may take the values defined. Logging will occur for any message equal to or higher than the level specified (=>) lower levels will not be logged. Severity Description critical only critical errors. error error and above. warning warning and above. notice notice and above. info info and above - log starting to get chatty. debug debug and above. Various debug levels can be defined with 'debug 0' meaning no debugging. dynamic debug and above. Means assume the global debug level defined by either the command line parameter -d or by running rndc trace
print-time yes | no	Controls whether the date and time are written to the output channel (yes) or not (no). The default is 'no'.
print-severity yes | no	Controls whether the severity level is written to the output channel (yes) or not (no). The default is 'no'.
print-category yes | no	Controls whether the severity level is written to the output channel (yes) or not (no). The default is 'no'.
categorycategory_name	Controls what categories are logged to the various defined or default 'channel_names'. The category_name (a quoted string, for example, "default") may take one of the following values: Category Description client Processing of client requests. config Configuration file parsing and processing. database Messages relating to the databases used internally by the name server to store zone and cache data. default Logs all values which are not explicitly defined in category statements i.e. if this is the only category defined it will log all categories listed in this table with the exception of queries which are not turned on by default. delegation-only Logs queries that have returned NXDOMAIN as the result of a delegation-only zone or a delegation-only statement in a hint or stub zone declaration. dispatch Dispatching of incoming packets to the server modules where they are to be processed. dnssec DNSSEC and TSIG protocol processing. general Anything that is not classified as any other item in this list defaults to this category.. lame-servers Lame servers. Mis-configuration in the delegation of domains discovered by BIND 9 when trying to authoritative answers. If the volume of these messages is high many users elect to send them to the null channel e.g. category lame-servers {null;}; statement. network Logs all network operations. notify Logs all NOTIFY operations. queries Logs all query transactions. The querylog statement may be used to override this category statement. This entry can generate a substantial volume of data very quickly. This category is not turned on by default and hence the default type above will not log this information. resolver Name resolution including recursive lookups performed on behalf of clients by a caching name server. rpz All operations related to Response Policy Zone (RPZ) processing. Even when RPZ zones are disabled (using policy disabled parameter in the response-policy statement) the operation is completed, logged then discarded (the real response is returned to the user). rate-limit All operations related to one or more rate-limit statements in the options or view clauses. security Approval and denial of requests. unmatched No matching view clause or unrecognized class value. A one line summary is also logged to the client category. By default this category is sent to the null channel. update Logging of all dynamic update (DDNS) transactions. update-security Approval and denial of update requests used with DDNS. xfer-in Details of zone transfers the server is receiving. xfer-out Details of zone transfers the server is sending.

Examples

The first example shows a minimal logging configuration that will work and generate modest log volumes.

logging{
  channel simple_log {
    file "/var/log/named/bind.log" versions 3 size 5m;
    severity warning;
    print-time yes;
    print-severity yes;
    print-category yes;
  };
  category default{
    simple_log;
  };
};

---

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.

 

http://www.zytrax.com/books/dns/ch7/logging.html