#

| Chapter 7 Maintaining BIND |

## 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

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.

7.4 Changing BIND 8 System File Locations |  | 7.6 Keeping Everything Running Smoothly