dnscache
Log File FormatThese notes are incomplete.
dnscache
is part of thedjbdns
package, written by Daniel J. Bernstein, aka djb. I couldn't find any documentation on its log file format, other than this explanation of one field of thestats
log entry. This file contains my notes on what the log entries mean. If there are any errors here, they are mine and not djb's.
dnscache
logs IP addresses as 8 digit hexadecimal strings. For example, 127.0.0.1 is logged as 7f000001.
dnscache
logs UDP ports and query IDs as 4 digit hexadecimal strings.
dnscache
logs all time intervals (including TTLs) as decimal strings, in units of seconds.
dnscache
logs record types numerically. For a list of record types, see RFC 1700, page 79. The common ones are 1 = A, 12 = PTR, and 15 = MX.RFC 1035 specifies the implementation of DNS.
You can find some programs for analyzing
dnscache
logs at http://www.fibrespeed.net/~mbabcock/code/.Log entry types:
cached type name
cached cname name cname
cached ns control server
cached nxdomain name
drop serial error
lame serverip name control
nodata serverip ttl type name
nxdomain serverip ttl name
query serial clientip:clientport:id type name
rr serverip ttl type name data
rr serverip ttl cname name cname
rr serverip ttl mx name preference exchanger
rr serverip ttl ns name server
rr serverip ttl ptr name pname
rr serverip ttl soa server email serial refresh retry expire minimum
sent serial length
servfail name error
starting
stats query-count cache-motion udp-active tcp-active
tcpopen clientip:clientport
tcpclose clientip:clientport error
tx gluelessness type name control serverips...
dnscache
needs some records and found them in the cache. It may have needed the records because the client requested them, or it may have needed the addresses of a name server in order to look up some other records.The actual cached data is not recorded with this log entry. The cached data may include several records, but
dnscache
makes only one log entry.
Field Meaning type
The type of records needed. name
The domain name for which records were needed.
dnscache
found the answer to a client query in its cache, and the answer was a CNAME record. In this case,dnscache
starts over, looking for the same record type but with the "canonical name".
Field Meaning name
The domain name for which the client wants records. cname
The "canonical name" for name
. meaning thatname
should be treated as an alias forcname
.
dnscache
needed to know the authoritative nameservers for some domain, and found a set of nameservers for the domain, or some ancestor of it, in the cache.dnscache
creates one log entry for each nameserver in the set. The actual name for whichdnscache
needed to find nameservers is on thequery
log entry preceding the set ofcached ns
log entries.For example:
query 673 7f000001:09b6:7c48 1 www.windows.com. cached ns com. a.root-servers.net. cached ns com. e.gtld-servers.net. cached ns com. f.gtld-servers.net. cached ns com. j.gtld-servers.net. cached ns com. k.gtld-servers.net. cached ns com. a.gtld-servers.net. cached ns com. m.gtld-servers.net. cached ns com. g.gtld-servers.net. cached ns com. c.gtld-servers.net. cached ns com. i.gtld-servers.net. cached ns com. b.gtld-servers.net. cached ns com. d.gtld-servers.net.
dnscache
needed to know the authoritative nameservers forwww.windows.com
, and the nearest set of nameservers in its cache was the set of nameservers that are authoritative forcom
.
Field Meaning control
The domain name for which server
is authoritative.server
The name of a server that is authoritative for control
.
dnscache
needed to find records forname
and found a cachednxdomain
entry in the cache.
Field Meaning name
The domain name for which records were requested.
dnscache
decided not to try to respond to a client query.
Field Meaning serial
The serial number of the client request. See query
for an explanation of client request serial numbers.error
The reason dnscache
dropped the request:
timed out
dnscache
had MAXUDP (200) active UDP queries and received another UDP query. It dropped the oldest active query.permission denied
dnscache
received an AXFR request.permission denied
dnscache
received an AXFR request.out of memory
dnscache
could not allocate memory for parsing a query packet or building a response.- XXX more errors...
dnscache
found a lame delegation. This means that the server is supposed to be authoritative for some domain, but isn't.
Field Meaning serverip
The IP address of the lame server. name
The domain name for which records were requested. control
The domain for which the server is supposed to be authoritative, but isn't.
dnscache
received a "no data" response. This means that the server has records for the requested name, but no records of the requested type.
Field Meaning serverip
The IP address of the responding server. ttl
The time-to-live of the SOA record in the response. This is how long dnscache
is allowed to cache the negative response.dnscache
will not cache a negative response for more than one hour in any case.type
The requested record type. name
The domain name for which records were requested.
dnscache
received a "Name Error" response. This means that the server has no records of any type for the requested name.
Field Meaning serverip
The IP address of the responding server. ttl
The time-to-live of the SOA record in the response. This is how long dnscache
is allowed to cache the negative response.dnscache
will not cache a negative response for more than one hour in any case.name
The domain name for which records were requested.
query serial clientip:clientport:id type name
dnscache
received a packet containing a query and intends to try to answer it.
Field Meaning serial
The number of queries dnscache
received prior to this query since starting, plus one. In other words, serial number 1 is assigned to the first query received, serial number 2 is assigned to the second query received, and so on. The counter is stored using 64 bits, so chances of it wrapping are unlikely.clientip
The source IP address of the packet. Presumably this is the IP address from which the packet was sent, though it could have been spoofed. clientport
The source UDP port of the packet. id
The id from the packet. The id is chosen by the client, and the server will include it in the response. type
The type of records the client wants. name
The domain name for which the client wants records.
dnscache
finished constructing a response to a query. If the query came over UDP, thendnscache
also sent the response. If the query came over TCP, thendnscache
did not send the response before making this log entry. (Sending over TCP may block sodnscache
trickles the data out as part of its main loop.)
Field Meaning serial
The serial number of the client request to which dnscache
responded. Seequery
for an explanation of client request serial numbers.length
The number of bytes in the response.
dnscache
sent a packet with rcode 2, "Server failure", because it encountered an error.Some of the errors that can make dnscache do this:
- failure to allocate storage for a received DNS packet
- failure to create a UDP socket
- failure to set the O_NONBLOCK flag on the UDP socket
- failure to bind the UDP socket to a port
- failure to transmit a packet to any of up to 16 nameservers and receive a response packet with an rcode of 0 (no error) or 3 (NXDOMAIN), with four attempts per nameserver
- failure to create a TCP socket
- failure to set the O_NONBLOCK flag on the TCP socket
- failure to bind the TCP socket to a port
- failure to connect the TCP socket to any of up to 16 nameservers (one attempt per nameserver), transmit a query to the nameserver, and receive a response packet with an rcode of 0 (no error) or 3 (NXDOMAIN)
There may be other ways for dnscache to log/send servfail, but these are all the ones I have found from inspecting the source code.
Field Meaning name
The domain name for which the dnscache was trying to find records. error
As of djbdns
version 1.05, the error message will always be "input/output error", because the only call tolog_servfail
is indoit
inquery.c
, like this:errno = error_io; if (state == 1) goto HAVEPACKET; if (state == -1) { log_servfail(z->name[z->level]); goto SERVFAIL; }
dnscache
logs this entry when it starts up.
stats query-count cache-motion udp-active tcp-active
- This entry contains statistics about
dnscache
's behavior, both since startup and at the moment the entry was logged.
Field Meaning query-count
The total number of queries received by dnscache
since startup.cache-motion
The total number of bytes dnscache
has stored in its cache since startup. This says nothing about the maximum size of the cache or how much data has been evicted from the cache. See djb's explanation of cache motion for more information.udp-active
The number of queries that dnscache
has received via UDP but not yet responded to or dropped.tcp-active
The number of queries that dnscache
has received via TCP but not yet responded to or dropped.
tx gluelessness type name control serverips...
- This line indicates that dnscache transmitted a query.
Field Meaning gluelessness
The amount of gluelessness that generated this query. Read djb's explanation of gluelessness.
For the case of www.monty.de, the queries
dnscache
sent for www.monty.de have gluelessness 0. The query sent for ns.norplex.net has gluelessness 1. The query for vserver.neptun11.de has gluelessness 2. The query sent for ns.germany.net has gluelessness 3. And so on.type
The requested record type. name
The domain name for which records are being requested. control
dnscache
sends a query to a server because it has been told that the server is authoritative for the domain in question, or some ancestor thereof. Thecontrol
field shows the domain for whichdnscache
thinks the server is authoritative.For example, suppose the cache is empty, and you ask
dnscache
for the A records for example.com. First,dnscache
will send a query to a root server, because the root server is authoritative for the root domain (written "."). So thetx
line for the query will have "." in thecontrol
field.The root server will give
dnscache
a list of servers that are authoritative for thecom
domain.dnscache
will ask one of thecom
servers for the A records forexample.com
, and the log entry will havecom.
in thecontrol
field.Suppose the
com
server says thatns.example.net
is authoritative forexample.com
. Then whendnscache
asksns.example.net
for A records forexample.com
, the log entry will haveexample.com
in thecontrol
field.serverips
The IP addresses of all the authoritative servers for the control
domain, in random order.dnscache
transmits the query to the first server in the list. If the server doesn't respond,dnscache
moves on to the next server in the list.
tx
named anchor to appear at the top of your window.)