DNS & BIND

DNS & BINDSearch this book
Previous: 7.4 Changing BIND 8 System File LocationsChapter 7
Maintaining BIND
Next: 7.6 Keeping Everything Running Smoothly
 

7.5 BIND 8 Logging

BIND 4 had an extensive logging system, writing information to a debug file and sending information to syslog. But, BIND 4 gave you limited control over this logging process - you could turn debugging on to a certain level. That's it. BIND 8 has the same logging system as BIND 4, but BIND 8 gives you control you didn't get with BIND 4.

This control has its cost though - there's a lot to learn before you can be effective configuring this subsystem. If you don't have some time you can spend to experiment with logging, use the defaults and come back to this topic later. Most of you do not need to change the default logging behavior.

Logging has two major topics you need to understand: channels and categories. A channel specifies where the logging data goes: to syslog, to a file, to stderr, or to the bit bucket. A category specifies what data is logged.

Each category of data can be sent to a single channel or to multiple channels. In Figure 7.1, queries are logged to a file, statistics data is logged to a file and logged to syslog.

Figure 7.1: Logging categories to channels

Figure 7.1

Channels allow you to filter by message severity. Here is the list of severities:

critical
error
warning
notice
info
debug [level]
dynamic

The top five severities (critical, error, warning, notice, and info) are the familiar severity levels used by syslog. The other two (debug and dynamic) are unique to BIND 8.

debug is name server debugging for which you can specify a debug level. If you omit the debug level, then the level is assumed to be one. If you specify a debug level, you will see messages of that level when name server debugging is turned on (i.e., if you specify "debug 3", then you will see level three debugging messages even when you only send one USR1 signal to the name server). If you specify dynamic severity, then the name server will log messages that match its debug level (i.e., if you send one USR1 signal to the name server, it will log messages from level one. If you send three USR1 signals to the name server, it will log messages from levels one through three.) The default severity is info, which means you won't see debug messages unless you specify the severity.

NOTE: You can configure a channel to log both debug messages and syslog messages to a file. However the converse is not true - you cannot configure a channel to log both debug messages and syslog messages with syslog - only syslog messages can be sent to syslog.

Let's configure a couple of channels to show you how this works. The first channel will go to syslog and will log with facility daemon, sending those messages of severity info and above. The second channel will go to a file, logging debug messages at any level as well as syslog messages. Here is the logging statement for the BIND 8 configuration file:

logging {
  channel my_syslog {
     syslog daemon;
     // Debug messages will not be sent to syslog, so
     // there is no point to setting the severity to
     // debug or dynamic; use the lowest syslog level: info.
     severity info;
  };
  channel my_file {
     file "log.msgs";
     // Set the severity to dynamic to see all the debug messages.
     severity dynamic;
  };
};

Now that we've configured a couple of channels, we have to tell the name server exactly what to send to those channels. Let's implement what was pictured in Figure 7.1 with statistics going to syslog and to the file, and queries going to the file. The category specification is part of the logging statement, so we'll build on the previous logging statement:

logging {
  channel my_syslog {
     syslog daemon;
     severity info;
  };
  channel my_file {
     file "log.msgs";
     severity dynamic;
  };

  category statistics { my_syslog; my_file; };
  category queries { my_file; };
};

With this logging statement in your configuration file, start your name server and send it a few queries. But nothing is written to log.msgs! (Well, if you wait long enough, the name server's statistics will show up in log.msgs.) You had expected those queries to be logged. Alas, you have to turn on name server debugging to get queries logged:

# kill -USR1 `cat /etc/named.pid`

Now send your name server some queries and they are logged in log.msgs. But look around: there's a new file called named.run. It has all the other debugging information written to it. You didn't want all this other debugging, though; you just wanted the statistics and queries. How do you get rid of named.run?

There's a special category we haven't told you about: default. If you don't specify any channels for a category, the default category is used. Let's change the default category to discard all logging messages (there's a channel called null for this purpose):

logging {
  channel my_syslog {
     syslog daemon;
     severity info;
  };
  channel my_file {
     file "log.msgs";
     severity dynamic;
  };

  category default { null; };
  category statistics { my_syslog; my_file; };
  category queries { my_file; };
};

Now, start your server, turn on debugging to level one, and send some queries. The queries end up in log.msgs and named.run was created but the file is empty. Great! We're getting the hang of this after all.

A few days pass. One of your co-workers notices that the name server is sending many fewer messages to syslog than it used to. In fact, the only syslog messages are statistics messages. The ones your co-worker watched, the zone transfer messages, are gone. What happened?

Well, the default category is set up, by default, to send messages to both syslog and to the debug file (named.run). When the default category was configured to the null channel, the other syslog messages were turned off. Here's what we should have used:

category default { my_syslog; };

This sends the syslog messages to syslog, but does not write debug or syslog messages to a file.

Remember, we said you'd have to experiment for a while with logging to get exactly what you want. We hope this example gives you a clue what you might run into. Now, let's go over the details of logging.

7.5.1 The Logging Statement

Here's the syntax of the logging statement. It's rather intimidating. We'll go over some more examples as we explain what each clause means:

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; ... ]
  }; ]
  ...
};

Here are the default channels. The name server will make these channels even if you do not want them. You cannot redefine these channels. You can only add more channels:

channel default_syslog {
    syslog daemon;        // send to syslog's daemon facility
    severity info;        // only send priority info and higher
};

channel default_debug {
    file "named.run";     // write to named.run 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
};

If you do not assign channels to the categories default, panic, packet, and eventlib, the name server will assign these channels by default:

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

As we mentioned earlier, the default category logs to both syslog and to the debug file (which by default is named.run). This means that all syslog messages of severity info and above are sent to syslog, and when debugging is turned on, the syslog messages and debug messages are written to named.run. This more or less matches the BIND 4 behavior.

7.5.2 Channel Details

A channel may be defined to go to a file, to syslog, or to null.

7.5.2.1 File channels

If a channel goes to a file, you must specify the file's path name. Optionally, you can specify how many versions of the file can exist at one time and how big the file may grow.

If you specify that there can be three versions, BIND 8 will keep around file, file.0, file.1, and file.2. After the name server starts or after it is restarted by a HUP signal, it will move file.1 to file.2, file.0 to file.1, file to file.0, and start a new copy of file. If you specify unlimited versions, BIND 8.1.2 will keep 99 versions.

If you specify a maximum file size, BIND 8 will stop writing to the file after it reaches the specified size. Unlike the versions clause (mentioned in the last paragraph), the file will not be rolled over and a new file opened when the specified size is reached. The name server just stops writing to the file. If you do not specify a file size, the file will grow indefinitely.

Here is an example file channel using the versions and size clauses:

logging{
  channel my_file {
     file "log.msgs" versions 3 size 10k;
     severity dynamic;
  };
};

The size can include a scaling factor as in the example. K or k is kilobytes. M or m is megabytes. G or g is gigabytes.

It's important to specify the severity as either debug or dynamic if you want to see debug messages. The default severity is info, which will only show you syslog messages.

7.5.2.2 Syslog channels

If a channel goes to syslog, you can specify the facility to be any of the following: kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, local0, local1, local2, local3, local4, local5, local6, local7. The default is daemon. We recommend that you use the default.

Here's an example syslog channel using the facility local0 instead of daemon:

logging {
    channel my_syslog {
        syslog local0;        // send to syslog's local0 facility
        severity info;        // only send priority info and higher
    };
};

7.5.2.3 Null channel

There is a predefined channel called null for those messages you want to throw away.

7.5.2.4 Stderr channel

There is a predefined channel called default_stderr for any messages you'd like written to the stderr file descriptor of the name server. You cannot configure any other file descriptors.

7.5.2.5 Data formatting for all channels

The BIND 8 logging facility also allows you some control over the formatting of messages. You can add to the messages: a time stamp, the category, or the severity.

Here's an example debug message that has all the extra goodies:

01-Feb-1998 13:19:18.889 config: debug 1: source = db.127.0.0

The category for this message is config and the severity is debug level one.

Here's an example channel configuration that includes all three additions:

logging {
  channel my_file {
     file "log.msgs";
     severity debug;
     print-category yes;
     print-severity yes;
     print-time yes;
  };
};

There is not much point in adding the time stamp for messages to a syslog channel since syslog adds the time and date itself.

7.5.3 Category Details

There are lots of categories - lots! We'll list them here so you can see them all. Rather than trying to figure out which you want to see, we recommend that you configure your name server to print out all of its log messages, with their category and severity, and then pick out the ones you want to see. We'll show you how to do this after telling you about the categories:

default

If you don't specify any channels for a category, the default category is used instead. In that sense, default is synonymous with all categories. However, there are some messages that didn't end up in a category. So, even if you specify channels for each category individually, you'll still want to specify a channel for the default category for all the uncategorized messages.

If you do not specify a channel for the default category, one will be specified for you:

        category default { default_syslog; default_debug; };
cname

CNAME errors (e.g., "... has CNAME and other data")

config

Configuration file processing

db

Database operations

eventlib

System events; must point to a file channel

insist

Internal consistency check failures

lame-servers

Detection of bad delegation

load

Zone loading messages

maintenance

Maintenance events (e.g., system queries)

ncache

Negative caching events

notify

Asynchronous change notifications

os

Problems with the operating system

packet

Decodes of packets received and sent; must point to a file channel

panic

Problems that cause the shutdown of the server

parser

Parsing of the configuration file

queries

Analogous to BIND 4's query logging

response-checks

Malformed responses, unrelated additional information, etc.

security

Approved/unapproved requests

statistics

Periodic reports of activities

update

Dynamic update events

xfer-in

Zone transfers from remote name servers to the local name server

xfer-out

Zone transfers from the local name server to remote name servers

7.5.3.1 Viewing all category messages

A good activity to start your foray into logging is to configure your name server to log all of its messages to a file, with the category and severity, and then pick out which messages you are interested in.

Earlier we listed the categories that are configured by default:

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

By default, the category and severity are not included with messages written to the default_debug channel. In order for you to see all the log messages, with their category and severity, you'll have to configure each of these categories yourself.

Here is a logging statement that does just that:

logging {
  channel my_file {
     file "log.msgs";
     severity dynamic;
     print-category yes;
     print-severity yes;
  };

  category default  { default_syslog; my_file; };
  category panic    { default_syslog; my_file; };
  category packet   { my_file; };
  category eventlib { my_file; };
  category queries  { my_file; };
};

Notice that we've defined each category to include the channel my_file. We also added one category that wasn't in the default logging statement above - queries. Queries aren't printed unless you configure the queries category.

Start your server and turn on debugging to level one. You'll see messages in log.msgs that look like the following:

queries: info: XX /192.253.253.4/foo.movie.edu/A
default: debug 1: req: nlookup(foo.movie.edu) id 4 type=1 class=1
default: debug 1: req: found 'foo.movie.edu' as 'foo.movie.edu' (cname=0)
default: debug 1: ns_req: answer -> [192.253.253.4].2338 fd=20 id=4 size=87

Once you see the messages that interest you, configure your server to log only those messages.


Previous: 7.4 Changing BIND 8 System File LocationsDNS & BINDNext: 7.6 Keeping Everything Running Smoothly
7.4 Changing BIND 8 System File LocationsBook Index7.6 Keeping Everything Running Smoothly