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.
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.
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.
A channel may be defined to go to a file, to syslog, or to null.
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.
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 }; };
There is a predefined channel called
null
for those messages you want to throw
away.
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.
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.
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:
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; };
Decodes of packets received and sent; must point to a file channel
Zone transfers from remote name servers to the local name server
Zone transfers from the local name server to remote name servers
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.