DNSCAP(1)

NAME
dnscap - DNS network traffic capture utility

SYNOPSIS
dnscap [-pd1g?6fT] [-i if ...] [-r file ...] [-l vlan ...] [-L vlan ...] [-x pat ...] [-X pat ...] [ -m [qun]] [ -s [ir]] [ -h [ir]] [ -e [nytfsxir]] [-a host ...] [-z host ...] [-A host ...] [-Z host ...] [-Y host ...] [-u port] [ -w base [-k cmd]] [-t lim] [-c lim]

DESCRIPTION
dnscap is a network capture utility designed specifically for DNS traffic. It normally produces binary data in pcap(3) format, either on standard output or in successive dump files (based on the -w command line option). This utility is similar to tcpdump(1), but has finer grained packet recognition tailored to DNS transactions and protocol options. dnscap is expected to be used for gathering continuous research or audit traces.

The following options are available:

-p  Asks that the interface not be put into promiscuous mode. Note that even without this option, the interface could be in promiscuous mode for some other reason.

-d  Tells a verbose story of options and patterns chosen, files opened, and so on. (Multiple -d options can be given to increase verbosity and frequency of trace messages.)

-1  Flush the pcap(3) packet dump after every packet. Mostly this is useful when the packet dump is standard output, and has been piped to tcpdump(1).

-g  Produce output on diagnostic output, showing the presentation form of DNS messages which passed through all of the filters. If -w is also used, then every message will be dumped in both binary and presentation form.

-?  Prints some text to stdout describing the command line options, so that you won't have to refer back to this man page as often. Probably you will have to say "-\?" to get this option past your shell.

-6  Suppress the use of packet filter patterns that are known (as of 2007) to cause problems when processing IPv6 packets. Recommended when IPv6 traffic is expected to be present.

-f  Selects fragments (which could include unrelated flows since fragments do not contain port numbers), and includes fragments in the binary output. Necessary if you intend to do IP Reassembly. Note that all fragments will be collected, not just those using the DNS port number, since fragments don't have port numbers. Beware this option if you also handle a lot of NFS traffic.

-T  Selects TCP packets. SYN, FIN, and RST packets are collected if they pass the layer 2, port, and host filters (although hosts need not be in the correct direction); they are not tested against filter options that require a DNS header such as -m, -s, and -e. The first DNS header in the stream is captured if it passes all filter options. All subsequent non-empty packets in the stream, regardless of DNS message boundaries, will be captured if and only if the first DNS header passed all filter options. TCP packets will usually not be printable with -g.

-i if
    Select an interface to be monitored. On BSD systems, the default is the first interface that was configured at system boot time. On Linux systems, the default is to monitor all interfaces. More than one interface may be selected which will cause output to be interleaved from all selected interfaces.

-r file
    Select an offline pcap(3) file produced by this utility or by tcpdump(1) as the input packet source. Can be given as "-" to indicate standard input.

-l vlan
    Captures only 802.1Q encapsulated packets, and selects specific vlans to be monitored. Can be specified more than once to select multiple vlans. -l 0 means "all vlans".

-L vlan
    Captures 802.1Q encapsulated packets matching the specified vlans AND packets without VLAN tags. Can be specified more than one to select multiple vlans. -L 0 means "all vlans".

-u port
    Capture only packets on this UDP port, and treat as DNS traffic. The default port is 53. Note that there is no way to select multiple UDP ports, as would be necessary to capture both DNS (port 53) and mDNS (port 5353) traffic.

-x pat
    If one or more -x options are provided, then DNS messages will only be selected if the printable representation of the QNAME or any RR matches at least one of the provided pat patterns. See regex(3) and re_format(7) for more information about extended regular expression syntax.

-X pat
    If one or more -X options are provided, then DNS messages matching these patterns will not be selected. See the description of -x above.

-m [qun]
    Capture only messages of designated types (query, update, and notify). Default is query.

-s [ir]
    Select messages which are initiations and/or responses. Default is both.

-h [ir]
    Hide initiator or responder of each captured transaction. Hiding an initiator means wiping out the address and port number. Hiding a responder means to wipe out the address only. This wiping occurs on the copy of the packet sent to the pcap(3) dump output, and both the IP and UDP checksums will be recomputed in that case.

-e [nytfsxir]
    Among responses, consider nonzero DNS TC or DNS RCODE to indicate an error, and select only responses which do not have (n), or which have (y), these conditions. The default is to only select nonerrors among responses. If both nonerror and error responses are to be selected, specify both the n and y options here. To be more specific, use one or more condition-specific options, as follows:

    n   no error
    y   some error
    t   truncated response (TC bit)
    f   format error (rcode 1)
    s   server failure (rcode 2)
    x   no such name (rcode 3)
    i   not implemented (rcode 4)
    r   refusal (rcode 5)

-a host
    Capture only transactions having these initiators. Can be specified more than once to select multiple initiators. If a host name is used, then all of that host's addresses whether IPv4 or IPv6 are added to the recognition pattern.

-z host
    Capture only transactions having these responders. Can be specified more than once to select multiple responders. If a host name is used, then all of that host's addresses whether IPv4 or IPv6 are added to the recognition pattern.

-A host
    Capture only transactions NOT having these initiators.

-Z host
    Capture only transactions NOT having these responders.

-Y host
    Drop responses having these responders. Similar to -Z in spirit. However, -Y applies only to responses and does not cause any additions to the BPF filter string.

-w base
    Dump the captured packets to successive binary files in pcap(3) format with DLT_RAW datalink type. Each file will have a name like "%s.%u.%06u" where %s is base, %u is the time in seconds, and %06u is the time in microseconds. The argument "-" may be given to send the binary output to standard output. In that case, the -c and -t options affect the total duration of the capture, and not merely the size and time limits of each individual dump file.

-k cmd
    After each dump file specified by -w is closed, this command will be executed in a nonblocking subprocess with the file name as its one argument. It's expected that this command will be a shell script that submits the finished file to a batch processing analytics system. Note that without -k, the program will exit at the first output closure due to -c or -t.

-t lim
    By default, dnscap will close its packet dump file only when interrupted. A time limit can be specified with the -t option. When writing to a file, the packet dump file will be closed when time() % lim is zero and the first file will usually be shorter than lim seconds. If the packet dump file is standard output, then after closing this file, dnscap exits. This option is inclusive with -c.

-c lim
    By default, dnscap will close its packet dump file only when interrupted. A dump file size, measured in packets, can be specified with the -c option. If the packet dump file is standard output, then after closing this file, dnscap exits. This option is inclusive with -t.

-B datetime
    When using -w, the -B option tells dnscap to start collecting at a specific time. datetime should be specified as YYYY-MM-DD HH:MM:SS. The program will sleep(3) until the start time, and then begin capturing packets.

-E datetime
    When using -w and -t, the -E option tells dnscap to stop collecting at a specific time. datetime should be specified as YYYY-MM-DD HH:MM:SS. The program will exit when it sees a packet with timestamp greater than datetime.

-S  Causes dnscap to print pcap_stats() counters on stderr when -t or -c limits are reached.

If started with no options, dnscap will exit with a complaint that without either the -w or -g options, it's pointless to run the program at all. In its simplest form, the output can be piped to tcpdump(1) as in:

    dnscap -w - | tcpdump -r -

You can safely add the -d option since the output resulting from -d goes to diagnostic output rather than standard output. And since everybody who's anybody always uses the -n option to tcpdump(1), the minimum useful incantation is probably:

    dnscap -w - | tcpdump -r - -n

The more interesting use for dnscap is long term or continuous data collection. Assuming a shell script called dnscap-upload whose function is to transfer a pcap(3) - format file to an analytics system and then remove the local copy of it, then a name server operating system startup could invoke dnscap for continuous DNS auditing using a command like:

    dnscap -m qun -h i -r f.root-servers.net \
           -b /var/local/dnscaps/f-root -t 1800 \
           -k /usr/local/sbin/dnscap-upload

A bizarre but actual example which combines almost all features of dnscap is:

    dnscap -d -w - -1 -i em0 -l 0 -x ^7 | \
           dnscap -d -r - -X spamhaus -g -l 0

Here, we're looking for all messages having a QNAME or RR beginning with the decimal digit "7", but we don't want to see anything containing "spamhaus". The interface is tagged, and since only one interface is selected, the output stream from the first dnscap will also be tagged, thus we need -l 0 on both dnscap commands.

COMPATIBILITY NOTES
If dnscap produces no output, it's probably due to some kind of bug in your kernel's bpf(4) module or in your pcap(3) library. You may need the -6 or -l 0 options. To diagnose your way out of "no output" hell, use the -d and -g options to find out what BPF program is being internally generated, and then cut/paste this BPF program onto a tcpdump(1) command line to see if it likewise produces no output.

DIAGNOSTICS

SEE ALSO
tcpdump(1), ncaptool(1), pcap(3), bpf(4)

HISTORY
dnscap was written by Paul Vixie (ISC) with help from Duane Wessels, Kevin Brintnall, and others too numerous to mention.

BUGS
Ought to handle fragmented UDP.

Ought to be re-implented as a ncap client.

Too many design botches within bpf(4) and pcap(3) are made visible to the user of this utility.

LICENSE
Copyright (c) 2007 by Internet Systems Consortium, Inc. ("ISC")

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.