|-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 wont 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 dont 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.|
|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.|
|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".|
|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.|
|Capture only messages of designated types (query, update, and notify). Default is query.|
|Select messages which are initiations and/or responses. Default is both.|
|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.|
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
To be more specific, use one or more condition-specific options, as follows:
|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)|
|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 hosts addresses whether IPv4 or IPv6 are added to the recognition pattern.|
|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 hosts addresses whether IPv4 or IPv6 are added to the recognition pattern.|
|Capture only transactions NOT having these initiators.|
|Capture only transactions NOT having these responders.|
|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. Its 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 .|
|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.|
|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, its 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 whos 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, were looking for all messages having a QNAME or RR beginning with the decimal digit "7", but we dont 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, its probably due to some kind of bug in your kernels 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.
dnscap was written by Paul Vixie (ISC) with help from Duane Wessels, Kevin Brintnall, and others too numerous to mention.
Ought to handle fragmented UDP.
Ought to be re-implented as a ncap client.
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.