1DNSCAP(1) BSD General Commands Manual DNSCAP(1)
2
4 dnscap — DNS network traffic capture utility
5
7 dnscap [-pd1g?6fT] [-i if ...] [-r file ...] [-l vlan ...] [-L vlan ...]
8 [-x pat ...] [-X pat ...] [-m [qun]] [-s [ir]] [-h [ir]] [-e
9 [nytfsxir]] [-a host ...] [-z host ...] [-A host ...]
10 [-Z host ...] [-Y host ...] [-u port] [-w base [-k cmd]] [-t lim]
11 [-c lim]
12
14 dnscap is a network capture utility designed specifically for DNS traf‐
15 fic. It normally produces binary data in pcap(3) format, either on stan‐
16 dard output or in successive dump files (based on the -w command line
17 option). This utility is similar to tcpdump(1), but has finer grained
18 packet recognition tailored to DNS transactions and protocol options.
19 dnscap is expected to be used for gathering continuous research or audit
20 traces.
21 The following options are available:
23 -p Asks that the interface not be put into promiscuous mode.
25 Note that even without this option, the interface could be in
26 promiscuous mode for some other reason.
27 -d Tells a verbose story of options and patterns chosen, files
29 opened, and so on. (Multiple -d options can be given to
30 increase verbosity and frequency of trace messages.)
31 -1 Flush the pcap(3) packet dump after every packet. Mostly
33 this is useful when the packet dump is standard output, and
34 has been piped to tcpdump(1).
35 -g Produce output on diagnostic output, showing the presentation
37 form of DNS messages which passed through all of the filters.
38 If -w is also used, then every message will be dumped in both
39 binary and presentation form.
40 -? Prints some text to stdout describing the command line
42 options, so that you won't have to refer back to this man
43 page as often. Probably you will have to say "-\?" to get
44 this option past your shell.
45 -6 Suppress the use of packet filter patterns that are known (as
47 of 2007) to cause problems when processing IPv6 packets.
48 Recommended when IPv6 traffic is expected to be present.
49 -f Selects fragments (which could include unrelated flows since
51 fragments do not contain port numbers), and includes frag‐
52 ments in the binary output. Necessary if you intend to do IP
53 Reassembly. Note that all fragments will be collected, not
54 just those using the DNS port number, since fragments don't
55 have port numbers. Beware this option if you also handle a
56 lot of NFS traffic.
57 -T Selects TCP packets. SYN, FIN, and RST packets are collected
59 if they pass the layer 2, port, and host filters (although
60 hosts need not be in the correct direction); they are not
61 tested against filter options that require a DNS header such
62 as -m, -s, and -e. The first DNS header in the stream is
63 captured if it passes all filter options. All subsequent
64 non-empty packets in the stream, regardless of DNS message
65 boundaries, will be captured if and only if the first DNS
66 header passed all filter options. TCP packets will usually
67 not be printable with -g.
68 -i if Select an interface to be monitored. On BSD systems, the
70 default is the first interface that was configured at system
71 boot time. On Linux systems, the default is to monitor all
72 interfaces. More than one interface may be selected which
73 will cause output to be interleaved from all selected inter‐
74 faces.
75 -r file Select an offline pcap(3) file produced by this utility or by
77 tcpdump(1) as the input packet source. Can be given as "-"
78 to indicate standard input.
79 -l vlan Captures only 802.1Q encapsulated packets, and selects spe‐
81 cific vlans to be monitored. Can be specified more than once
82 to select multiple vlans. -l 0 means "all vlans".
83 -L vlan Captures 802.1Q encapsulated packets matching the specified
85 vlans AND packets without VLAN tags. Can be specified more
86 than one to select multiple vlans. -L 0 means "all vlans".
87 -u port Capture only packets on this UDP port, and treat as DNS traf‐
89 fic. The default port is 53. Note that there is no way to
90 select multiple UDP ports, as would be necessary to capture
91 both DNS (port 53) and mDNS (port 5353) traffic.
92 -x pat If one or more -x options are provided, then DNS messages
94 will only be selected if the printable representation of the
95 QNAME or any RR matches at least one of the provided pat pat‐
96 terns. See regex(3) and re_format(7) for more information
97 about extended regular expression syntax.
98 -X pat If one or more -X options are provided, then DNS messages
100 matching these patterns will not be selected. See the
101 description of -x above.
102 -m [qun] Capture only messages of designated types (query, update, and
104 notify). Default is query.
105 -s [ir] Select messages which are initiations and/or responses.
107 Default is both.
108 -h [ir] Hide initiator or responder of each captured transaction.
110 Hiding an initiator means wiping out the address and port
111 number. Hiding a responder means to wipe out the address
112 only. This wiping occurs on the copy of the packet sent to
113 the pcap(3) dump output, and both the IP and UDP checksums
114 will be recomputed in that case.
115 -e [nytfsxir]
117 Among responses, consider nonzero DNS TC or DNS RCODE to
118 indicate an error, and select only responses which do not
119 have (n), or which have (y), these conditions. The default
120 is to only select nonerrors among responses. If both non‐
121 error and error responses are to be selected, specify both
122 the n and y options here. To be more specific, use one or
123 more condition-specific options, as follows:
124 n no error
126 y some error
127 t truncated response (TC bit)
128 f format error (rcode 1)
129 s server failure (rcode 2)
130 x no such name (rcode 3)
131 i not implemented (rcode 4)
132 r refusal (rcode 5)
133 -a host Capture only transactions having these initiators. Can be
135 specified more than once to select multiple initiators. If a
136 host name is used, then all of that host's addresses whether
137 IPv4 or IPv6 are added to the recognition pattern.
138 -z host Capture only transactions having these responders. Can be
140 specified more than once to select multiple responders. If a
141 host name is used, then all of that host's addresses whether
142 IPv4 or IPv6 are added to the recognition pattern.
143 -A host Capture only transactions NOT having these initiators.
145 -Z host Capture only transactions NOT having these responders.
147 -Y host Drop responses having these responders. Similar to -Z in
149 spirit. However, -Y applies only to responses and does not
150 cause any additions to the BPF filter string.
151 -w base Dump the captured packets to successive binary files in
153 pcap(3) format with DLT_RAW datalink type. Each file will
154 have a name like "%s.%u.%06u" where %s is base, %u is the
155 time in seconds, and %06u is the time in microseconds. The
156 argument "-" may be given to send the binary output to stan‐
157 dard output. In that case, the -c and -t options affect the
158 total duration of the capture, and not merely the size and
159 time limits of each individual dump file.
160 -k cmd After each dump file specified by -w is closed, this command
162 will be executed in a nonblocking subprocess with the file
163 name as its one argument. It's expected that this command
164 will be a shell script that submits the finished file to a
165 batch processing analytics system. Note that without -k, the
166 program will exit at the first output closure due to -c or
167 -t.
168 -t lim By default, dnscap will close its packet dump file only when
170 interrupted. A time limit can be specified with the -t
171 option. When writing to a file, the packet dump file will be
172 closed when time() % lim is zero and the first file will usu‐
173 ally be shorter than lim seconds. If the packet dump file is
174 standard output, then after closing this file, dnscap exits.
175 This option is inclusive with -c.
176 -c lim By default, dnscap will close its packet dump file only when
178 interrupted. A dump file size, measured in packets, can be
179 specified with the -c option. If the packet dump file is
180 standard output, then after closing this file, dnscap exits.
181 This option is inclusive with -t.
182 -B datetime
184 When using -w, the -B option tells dnscap to start collecting
185 at a specific time. datetime should be specified as YYYY-MM-
186 DD HH:MM:SS. The program will sleep(3) until the start time,
187 and then begin capturing packets.
188 -E datetime
190 When using -w and -t, the -E option tells dnscap to stop col‐
191 lecting at a specific time. datetime should be specified as
192 YYYY-MM-DD HH:MM:SS. The program will exit when it sees a
193 packet with timestamp greater than datetime.
194 -S Causes dnscap to print pcap_stats() counters on stderr when
196 -t or -c limits are reached.
197 If started with no options, dnscap will exit with a complaint that with‐
199 out either the -w or -g options, it's pointless to run the program at
200 all. In its simplest form, the output can be piped to tcpdump(1) as in:
201 dnscap -w - | tcpdump -r -
203 You can safely add the -d option since the output resulting from -d goes
205 to diagnostic output rather than standard output. And since everybody
206 who's anybody always uses the -n option to tcpdump(1), the minimum useful
207 incantation is probably:
208 dnscap -w - | tcpdump -r - -n
210 The more interesting use for dnscap is long term or continuous data col‐
212 lection. Assuming a shell script called dnscap-upload whose function is
213 to transfer a pcap(3) - format file to an analytics system and then
214 remove the local copy of it, then a name server operating system startup
215 could invoke dnscap for continuous DNS auditing using a command like:
216 dnscap -m qun -h i -r f.root-servers.net \
218 -b /var/local/dnscaps/f-root -t 1800 \
219 -k /usr/local/sbin/dnscap-upload
220 A bizarre but actual example which combines almost all features of dnscap
222 is:
223 dnscap -d -w - -1 -i em0 -l 0 -x ^7 | \
225 dnscap -d -r - -X spamhaus -g -l 0
226 Here, we're looking for all messages having a QNAME or RR beginning with
228 the decimal digit "7", but we don't want to see anything containing
229 "spamhaus". The interface is tagged, and since only one interface is
230 selected, the output stream from the first dnscap will also be tagged,
231 thus we need -l 0 on both dnscap commands.
232
234 If dnscap produces no output, it's probably due to some kind of bug in
235 your kernel's bpf(4) module or in your pcap(3) library. You may need the
236 -6 or -l 0 options. To diagnose your way out of "no output" hell, use
237 the -d and -g options to find out what BPF program is being internally
238 generated, and then cut/paste this BPF program onto a tcpdump(1) command
239 line to see if it likewise produces no output.
240
242 The dnscap utility exits 0 on success, and >0 if an error occurs.
243
245 tcpdump(1), ncaptool(1), pcap(3), bpf(4)
246
248 dnscap was written by Paul Vixie (ISC) with help from Duane Wessels,
249 Kevin Brintnall, and others too numerous to mention.
250
252 Ought to handle fragmented UDP.
253 Ought to be re-implented as a ncap client.
255 Too many design botches within bpf(4) and pcap(3) are made visible to the
257 user of this utility.
258
260 Copyright (c) 2007 by Internet Systems Consortium, Inc. ("ISC")
261 Permission to use, copy, modify, and/or distribute this software for any
263 purpose with or without fee is hereby granted, provided that the above
264 copyright notice and this permission notice appear in all copies.
265 THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
267 REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABIL‐
268 ITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL,
269 DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
270 RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CON‐
271 TRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNEC‐
272 TION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
273BSD April 25, 2007 BSD