1DNSCAP(1) BSD General Commands Manual
2DNSCAP(1)
3NNAAMMEE
5 ddnnssccaapp ‐ DNS network traffic capture utility
6SSYYNNOOPPSSIISS
8 ddnnssccaapp [‐‐aadd11gg??66vvss] [‐‐ii _i_f _._._.] [‐‐oo _f_i_l_e] [‐‐ll _v_l_a_n _._._.] [‐‐pp
9_p_o_r_t]
10 [‐‐xx _p_a_t _._._.] [‐‐mm [quir]] [‐‐hh [ir]] [‐‐ee [ny]] [‐‐qq _h_o_s_t
11_._._.]
12 [‐‐rr _h_o_s_t _._._.] [‐‐bb _b_a_s_e [‐‐kk _c_m_d]] [‐‐tt _l_i_m] [‐‐cc _l_i_m]
13DDEESSCCRRIIPPTTIIOONN
15 ddnnssccaapp is a network capture utility designed specifically
16for DNS traf‐
17 fic. It normally produces binary data in pcap(3) format,
18either on stan‐
19 dard output or in successive dump files (based on the ‐‐bb
20command line
21 option.) This utility is similar to tcpdump(1), but has
22finer grained
23 packet recognition tailored to DNS transactions and protocol
24options.
25 ddnnssccaapp is expected to be used for gathering continuous re‐
26search or audit
27 traces.
28 The following options are available:
30 ‐‐aa Puts the interface into promiscuous mode. Note
32that even
33 without this option, the interface could be in
34promiscuous
35 mode for some other reason.
36 ‐‐dd Tells a verbose story of options and patterns
38chosen, files
39 opened, and so on. (Multiple ‐‐dd options can be
40given to
41 increase verbosity and frequency of trace mes‐
42sages.)
43 ‐‐11 Flush the pcap(3) packet dump after every pack‐
45et. Mostly
46 this is useful when the packet dump is standard
47output, and
48 has been piped to tcpdump(1).
49 ‐‐gg Produce dig(1) ‐like output on diagnostic out‐
51put, showing the
52 presentation form of DNS messages which passed
53through all of
54 the filters. If ‐‐bb is also used, then every
55message will be
56 dumped in both binary and presentation form.
57 ‐‐? Prints some text to stdout describing the com‐
59mand line
60 options, so that you won’t have to refer back to
61this man
62 page as often. Probably you will have to say "‐
63this option past your shell.
64 ‐‐66 Suppress the use of packet filter patterns that
66are known (as
67 of 2007) to cause problems when processing IPv6
68packets.
69 Recommended when IPv6 traffic is expected to be
70present.
71 ‐‐vv Invert the sense of ‐‐xx, such that only nonmatch‐
73ing messages
74 are selected.
75 ‐‐ss Synchronize the dump files to begin at the top
77of their
78 interval. So, ‐‐ss ‐‐tt _3_6_0_0 would make every dump
79file start at
80 the beginning of a wall clock hour, even if the
81first dump
82 file was therefore shorter than the rest.
83 ‐‐ii _i_f Select an interface to be monitored. On BSD
85systems, the
86 default is the first interface that was config‐
87ured at system
88 boot time. On Linux systems, the default is to
89monitor all
90 interfaces. More than one interface may be se‐
91lected which
92 will cause output to be interleaved from all se‐
93lected inter‐
94 faces. If multiple interfaces are selected hav‐
95ing disparite
96 datalink types (framing), then the output
97datalink will be
98 demoted to DLT_LOOP (protocol family only, no
99link layer
100 source/destination addresses or other framing
101information.)
102 ‐‐oo _f_i_l_e Select an offline pcap(3) file produced by this
104utility or by
105 tcpdump(1) as the input packet source. Can be
106given as "‐"
107 to indicate standard input.
108 ‐‐ll _v_l_a_n Captures only 802.1Q encapsulated packets, and
110selects spe‐
111 cific vlans to be monitored. Can be specified
112more than once
113 to select multiple vlans. ‐‐ll _0 means "all
114vlans".
115 ‐‐pp _p_o_r_t Capture only packets on this UDP port, and treat
117as DNS traf‐
118 fic. The default port is 53.
119 ‐‐xx _p_a_t If one or more ‐‐xx options are provided, then DNS
121messages
122 will only be selected if the printable represen‐
123tation of the
124 QNAME or any RR matches at least one of the pro‐
125vided _p_a_t pat‐
126 terns. See regex(3) and re_format(7) for more
127information
128 about extended regular expression syntax.
129 ‐‐mm [quir] Capture only packets containing designated mes‐
131sage types
132 (query, update, initiation, response, and er‐
133ror). Default is
134 query initiation and responses. An "error"
135means a non‐zero
136 RCODE or a truncation (TC) flag.
137 ‐‐hh [ir] Hide initiator or responder of each captured
139transaction.
140 Hiding an initiator means wiping out the address
141and port
142 number. Hiding a responder means to wipe out
143the address
144 only. This wiping occurs on the copy of the
145packet sent to
146 the pcap(3) dump output, and both the IP and UDP
147checksums
148 will be recomputed in that case.
149 ‐‐ee [ny] Among responses, consider nonzero DNS TC or DNS
151RCODE to
152 indicate an error, and select only responses
153which do not
154 have, or which have, this condition. The de‐
155fault is to only
156 select nonerrors among responses. If both non‐
157error and error
158 responses are to be selected, specify both the _n
159and _y
160 options here.
161 ‐‐qq _h_o_s_t Capture only transactions having these initia‐
163tors. Can be
164 specified more than once to select multiple ini‐
165tiators. If a
166 host name is used, then all of that host’s ad‐
167dresses whether
168 IPv4 or IPv6 are added to the recognition pat‐
169tern.
170 ‐‐rr _h_o_s_t Capture only transactions having these respon‐
172ders. Can be
173 specified more than once to select multiple re‐
174sponders. If a
175 host name is used, then all of that host’s ad‐
176dresses whether
177 IPv4 or IPv6 are added to the recognition pat‐
178tern.
179 ‐‐bb _b_a_s_e Dump the captured packets to successive binary
181files in
182 pcap(3) format. Each file will have a name like
183"%s.%u.%06u"
184 where %s is _b_a_s_e, %u is the time in seconds, and
185%06u is the
186 time in microseconds. The argument "‐" may be
187given (so, "‐b
188 ‐") to send the binary output to standard out‐
189put. In that
190 case, the ‐‐cc and ‐‐tt options affect the total du‐
191ration of the
192 capture, and not merely the size and time limits
193of each
194 individual dump file.
195 ‐‐kk _c_m_d After each dump file specified by ‐‐bb is closed,
197this command
198 will be executed in a nonblocking subprocess
199with the file
200 name as its one argument. It’s expected that
201this command
202 will be a shell script that submits the finished
203file to a
204 batch processing analytics system.
205 ‐‐tt _l_i_m By default, ddnnssccaapp will close its packet dump
207file only when
208 interrupted. A time limit can be specified with
209the ‐‐tt
210 option. If the packet dump file is standard
211output, then
212 after closing this file, ddnnssccaapp exits. This op‐
213tion is inclu‐
214 sive with ‐‐cc.
215 ‐‐cc _l_i_m By default, ddnnssccaapp will close its packet dump
217file only when
218 interrupted. A dump file size, measured in
219packets, can be
220 specified with the ‐‐cc option. If the packet
221dump file is
222 standard output, then after closing this file,
223ddnnssccaapp exits.
224 This option is inclusive with ‐‐tt.
225 If started with no options, ddnnssccaapp will exit with a com‐
227plaint that with‐
228 out either the ‐‐bb or ‐‐gg options, it’s pointless to run the
229program at
230 all. In its simplest form, the output can be piped to tcp‐
231dump(1) as in:
232 dnscap ‐b ‐ | tcpdump ‐r ‐
234 You can safely add the ‐‐vv option since the output resulting
236from ‐‐vv goes
237 to diagnostic output rather than standard output. And since
238everybody
239 who’s anybody always uses the ‐‐nn option to tcpdump(1), the
240minimum useful
241 incantation is probably:
242 dnscap ‐v ‐b ‐ | tcpdump ‐r ‐ ‐n
244 The more interesting use for ddnnssccaapp is long term or continu‐
246ous data col‐
247 lection. Assuming a shell script called _d_n_s_c_a_p_‐_u_p_l_o_a_d whose
248function is
249 to transfer a pcap(3) ‐ format file to an analytics system
250and then
251 remove the local copy of it, then a name server operating
252system startup
253 could invoke ddnnssccaapp for continuous DNS auditing using a com‐
254mand like:
255 dnscap ‐m quire ‐h i ‐r f.root‐servers.net
257‐b /var/local/dnscaps/f‐root ‐t 1800 ‐k
258/usr/local/sbin/dnscap‐upload
259 A bizarre but actual example which combines almost all fea‐
261tures of ddnnssccaapp
262 is:
263 dnscap ‐d ‐b ‐ ‐1 ‐i em0 ‐l 0 ‐x ^7 |
265dnscap ‐d ‐o ‐ ‐x spamhaus ‐g ‐l 0 ‐v
266 Here, we’re looking for all messages having a QNAME or RR
268beginning with
269 the decimal digit "7", but we don’t want to see anything
270containing
271 "spamhaus". The interface is tagged, and since only one in‐
272terface is
273 selected, the output stream from the first ddnnssccaapp will also
274be tagged,
275 thus we need ‐‐ll _0 on both ’’ss..
276CCOOMMPPAATTIIBBIILLIITTYY NNOOTTEESS
278 If ddnnssccaapp produces no output, it’s probably due to some kind
279of bug in
280 your kernel’s bpf(4) module or in your pcap(3) library. You
281may need the
282 ‐‐66 or ‐‐ll _0 options. To diagnose your way out of "no output"
283hell, use
284 the ‐‐dd and ‐‐gg options to find out what BPF program is being
285internally
286 generated, and then cut/paste this program onto a tcpdump(1)
287command line
288 to see if it likewise produces no output.
289DDIIAAGGNNOOSSTTIICCSS
291 The ddnnssccaapp utility exits 0 on success, and >0 if an error
292occurs.
293SSEEEE AALLSSOO
295 tcpdump(1), pcap(3), bpf(4)
296HHIISSTTOORRYY
298 ddnnssccaapp was written by Paul Vixie (ISC) and Duane Wessels
299(Measurement
300 Factory).
301BBUUGGSS
303 Ought to handle fragmented UDP.
304 Ought to handle TCP.
306 Too many design botches within bpf(4) and pcap(3) are made
308visible to the
309 user of this utility.
310LLIICCEENNSSEE
312 Copyright (c) 2007 by Internet Systems Consortium, Inc.
313("ISC")
314 Permission to use, copy, modify, and/or distribute this
316software for any
317 purpose with or without fee is hereby granted, provided that
318the above
319 copyright notice and this permission notice appear in all
320copies.
321 THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WAR‐
323RANTIES WITH
324 REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
325MERCHANTABIL‐
326 ITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY
327SPECIAL,
328 DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
329WHATSOEVER
330 RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
331ACTION OF CON‐
332 TRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
333OR IN CONNEC‐
334 TION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
335BSD April 25, 2007
337BSD
338