| dnscap(1) | General Commands Manual | dnscap(1) |
dnscap - DNS network traffic capture utility
dnscap |
[-?VbNpd1g6fTIySMD] [-o option=value] [-i if] [-r file] [-l vlan] [-L vlan] [-u port] [-m [qun]] [-e [nytfsxir]] [-h [ir]] [-s [ir]] [-a host] [-z host] [-A host] [-Z host] [-Y host] [-w base] [-W suffix] [-k cmd] [-t lim] [-c lim] [-C lim] [-x pat] [-X pat] [-B datetime] [-E datetime] [-U str] [-q num|str] [-Q num|str] [-P plugin.so ...] |
dnscap |
-g ... |
dnscap |
-w ... |
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 from files. 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.
dnscap has a large array of command line options and extended options (-o option=value), and to make it easier to understand their usage they are categorized.
The only required options are -g and -w, at least one of them must be supplied to run.
If neither -r or -i is used then the default is to capture on the first or all interfaces (depends on system, see -i for more information).
On BSD systems, the default is the first interface that was configured at system boot time.
On Linux systems, the default might be to monitor all interfaces but most commonly it will also capture on the first interface. This depends on the libpcap version.
If you want to make sure you're capturing on all interfaces then use the special "any" or "all" (depends on system).
More than one interface may be selected which will cause output to be interleaved from all selected interfaces.
Option -p, -M and -D are libpcap specific options, see pcap(3) for more information on their meaning.
This options is required for IP defragmentation (see -o defrag_ipv4=yes and -o defrag_ipv6=yes), TCP reassembly (see -o reassemble_tcp=yes) and parsing ongoing TCP sessions (see -o parse_ongoing_tcp=yes).
For details on the diagnostic output and the different dump formats that exists, please see OUTPUT FORMATS below. Some formats have their own extended options, these are also listed in that section.
By default, dnscap will close its packet dump file only when interrupted. You can change that behavior with options -t, -c, and -C.
When using the above options -t, -c, and -C together, the order of applying them are 1) time interval, 2) number of packets and 3) number of bytes.
If this option is used together with -c or -C and the output is a packet dump file, then it will be reopened (creating a new dump file) before continuing.
Each TCP packet with payload will be tagged as DNS, unless -o reassemble_tcp=yes is used, with the support of having the DNS length arrive before the message in an own packet. Ongoing TCP connections can be inspected by using -o parse_ongoing_tcp=yes. TCP packets are processed as they arrive so missing, unaligned data or DNS message split over multiple packets will produce parsing errors. Using extended option -o allow_reset_tcpstate=yes may allow dnscap to recover from these scenarios.
When enabled, the following options are also available:
Since the number of saved segments are limited and fixed, if the TCP steam becomes corrupt then processing may stop. Recovering from this can be done by enabling which will reset state and free all saved segments to try and start over.
To be more specific, use one or more condition-specific options, as follows:
If both options are used then the message must first be matched by -x and then not matched by all -X regex. See regex(3) and re_format(7) for more information about extended regular expression syntax.
Once a double dash, "--", is encountered after -P, processing of the command line options will go back to dnscap.
Using this you can chain and use multiple plugins at once:
-P /path/to/plugin_one.so -a opt -- -P /path/to/plugin_two.so -b opt
To show the plugins option help, run it with -?:
-P /path/to/plugin_one.so -?
Plugins are loaded, executed and given the packets to process in the order given on command line.
These bundled plugins are installed in /usr/lib/x86_64-linux-gnu/dnscap:
Beside diagnostic and PCAP output, other output formats might be available depending on compile time support.
Recognized formats are:
First line contains packet and capturing information:
[<pktsize>] <date> <timestamp> [<pktnum> <file|interface> <vlanid>]
Second line shows IP information or if the packet is a fragment:
[<srcip>].<srcport> -> [<dstip>].<dstport>
;: [<srcip>] -> [<dstip>] (frag)
If the packet contains DNS information then the next line will show the DNS header information:
dns <opcode>,<rcode>,<id>,<flags>
Next are the 4 sections of the DNS, each section is prefixed by the number of records and each record and section are separated by space. Below are a few example, first is just a query, second has just one answer and the last has also authority and additional records.
1 example.com.,IN,A 0 0 0
1 example.com.,IN,A \
1 example.com.,IN,A,47,127.0.0.1 0 0
1 example.com.,IN,A \
1 example.com.,IN,A,263,127.0.0.1 \
4 example.com.,IN,NS,157794,ns1.example.com. \
example.com.,IN,NS,157794,ns4.example.com. \
example.com.,IN,NS,157794,ns3.example.com. \
example.com.,IN,NS,157794,ns2.example.com. \
4 ns2.example.com.,IN,A,157794,127.0.0.1 \
ns1.example.com.,IN,A,331796,127.0.0.1 \
ns3.example.com.,IN,A,157794,127.0.0.1 \
ns4.example.com.,IN,A,157794,127.0.0.1
Each DNS record contains the following:
<fqdn>,<class>,<type>[,<ttl>[,<additional information>]]
Additional information will be displayed for SOA, A, AAAA, MX, NS, PTR, CNAME and OPT records containing EDNS0.
In dnscap's 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 diagnostic output resulting from -d goes to standard error rather than standard output.
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 -z f.root-servers.net \
-w /var/local/dnscaps/f-root -t 1800 \
-k /usr/local/sbin/dnscap-upload
This will capture all query, update and notify messages where the responder is f.root-servers.net and the initiators will be hidden. The dump files will be saved in /var/local/dnscaps/ on a 30 minute (1800 seconds) interval. After each interval the dnscap-upload script will be executed.
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.
If dnscap produces no output, it's probably due to some kind of bug in the kernel's bpf(4) module or in the pcap(3) library.
You may need the -l 0 , -l 4095 or -L 4095 options.
To diagnose "no output", use the -d and -g options to find out what BPF program is being internally generated, and then cut/paste this BPF program and use tcpdump(1) to see if it likewise produces no output.
You can also run tcpdump(1) with -e to see the link-level headers in order to see if the traffic is encapsulated.
dnscap was written by Paul Vixie (ISC) with help from Duane Wessels, Kevin Brintnall, and others too numerous to mention. It's currently maintained by Jerry Lundström, DNS-OARC.
For issues and feature requests please use:
For question and help please use:
| 2.1.1 | dnscap |