Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DNSCAP(1)		FreeBSD	General	Commands Manual		     DNSCAP(1)

NAME
     dnscap -- DNS network traffic capture utility

SYNOPSIS
     dnscap [-?VbNpd1g6fTIySMD]	[-o option=value] [-i if ...] [-r file ...]
	    [-l	vlan ...] [-L vlan ...]	[-u port] [-m [qun]] [-e [nytfsxirMD]]
	    [-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] [-P plugin.so ...]

DESCRIPTION
     dnscap is a network capture utility designed specifically for DNS traf-
     fic.  It normally produces	binary data in pcap(3) format, either on stan-
     dard output or in successive dump files (based on the -w command line op-
     tion).  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:

     -?		 Prints	some text to stdout describing the command line	op-
		 tions,	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.

     -V		 Print version and exit.

     -o		 See EXTENDED OPTIONS.

     -b		 Run in	background as daemon.

     -N		 Do not	attempt	to drop	privileges, this is implicit if	only
		 reading offline pcap files.

     -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 in-
		 crease	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.

     -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 frag-
		 ments 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.  All DNS messages in the stream is cap-
		 tured if it passes all	filter options.

		 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.	 Ongo-
		 ing TCP connections can be inspected by using extended	option
		 -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	re-
		 cover from these scenarios.

     -I		 Select	ICMP and ICMPv6	packets.

     -i	if	 Select	an interface to	be monitored.  On BSD systems, the de-
		 fault 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 inter-
		 faces.

     -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	spe-
		 cific vlans to	be monitored.  Can be specified	more than once
		 to select multiple vlans.  -l 4095 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	4095 means "all
		 vlans".

     -u	port	 Capture only packets on this UDP port,	and treat as DNS traf-
		 fic.  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.

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

     -e	[nytfsxir]
		 Among responses, consider nonzero DNS TC or DNS RCODE to in-
		 dicate	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 condi-
		 tion-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)

     -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.

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

     -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.%s.%06u" where the first %s is base,
		 second	%s is the time as hours, minutes and seconds (%H%M%S),
		 and %06u is the 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	cap-
		 ture, and not merely the size and time	limits of each indi-
		 vidual	dump file.

     -W	suffix	 The provided suffix is	added to the dump file name, e.	g.:
		 ".pcap".  If the suffix ends with ".gz" then files will be
		 automatically gzip compressed.	 If gzip compression is	re-
		 quested but not supported (i.e. because of lack of system
		 support) an error will	be generated.

     -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 op-
		 tion.	When writing to	a file,	the packet dump	file will be
		 closed	when time() % lim is zero and the first	file will usu-
		 ally 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.

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

     -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 pat-
		 terns.	 For negative matching see -X below.  See regex(3) and
		 re_format(7) for more information about extended regular ex-
		 pression syntax.

     -X	pat	 If one	or more	-X options are provided, then DNS messages
		 matching these	patterns will not be selected.	See also the
		 description of	-x above.  If both options are used then the
		 message must first be matched by -x and then not matched by
		 all -X	regex.

     -y		 Enable	Linux seccomp-bpf sandbox if available (compile	op-
		 tion).

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

     -B	datetime
		 Tell 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,	or it will skip	all packets
		 related to an earlier time if used with an offline pcap(3)
		 file, and then	begin capturing	packets.

     -E	datetime
		 Tell 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 (live or offline pcap(3) file)
		 with timestamp	greater	than datetime.

     -M		 Enable	monitor	mode on	interfaces.

     -D		 Enable	immediate mode on interfaces.

     -U	str	 Append	"and str " to the pcap filter.

     -P	plugin.so ...
		 Load and use the specified plugin. Any	options	given after
		 this are sent to the plugin.

     If	started	with no	options, dnscap	will exit with a complaint that	with-
     out 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 col-
     lection.  Assuming	a shell	script called dnscap-upload whose function is
     to	transfer a pcap(3) - format file to an analytics system	and then re-
     move 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 se-
     lected, the output	stream from the	first dnscap will also be tagged, thus
     we	need -l	0 on both dnscap commands.

EXTENDED OPTIONS
     The following extended options exists and some of them might also exist
     as	a short	option.

     cbor_chunk_size=<bytes>
		 Specify the number of bytes of	CBOR to	construct before
		 flushing the output, must be a	non zero positive number.

     cds_cbor_size=<bytes>
		 Number	of bytes of memory to use before flushing to file.

     cds_message_size=<bytes>
		 Number	of bytes of memory to use for each DNS packet.

     cds_max_rlabels=<num>
		 Number	of labels to keep in the reverse label index.

     cds_min_rlabel_size=<num>
		 The minimum size of a label to	be able	to use the reverse la-
		 bel index.

     cds_use_rdata_index=yes
		 Use the resource data index, default no.

     cds_rdata_index_min_size=<num>
		 The minimum size of the data to be able to use	the resource
		 data index.

     cds_use_rdata_rindex=yes
		 Use the resource data reverse index, default no.

     cds_rdata_rindex_size=<num>
		 Number	of resource data to keep in the	resource data reverse
		 index.

     cds_rdata_rindex_min_size=<num>
		 The minimum size of the data to be able to use	the resource
		 data reverse index.

     dump_format=<format>
		 Specify the output format to use, see OUTPUT FORMATS.

     user=<user>
		 Specify the user to drop privileges to	(default nobody).

     group=<group>
		 Specify the group to drop privileges to (default nobody).

     pcap_buffer_size=<num>
		 Set the pcap(3pcap) buffer size to use	when capturing pack-
		 ets, can be used too not miss packets during processing.

     use_layers=yes
		 Enable	pcap-thread layers, this will let pcap-thread parse
		 the network layers and	call back with UDP, TCP	or ICMP	traf-
		 fic.

     defrag_ipv4=yes
		 Enable	IPv4 defragmentation in	pcap-thread, requires
		 use_layers=yes.

     max_ipv4_fragments=<num>
		 Set the maximum fragmented IPv4 packets to track for reassem-
		 bly, if the limit is reach then all other fragmented packets
		 will not be reassembled.

     max_ipv4_fragments_per_packet=<num>
		 Set the maximum fragments per tracked IPv4 packet to keep for
		 reassembly.

     defrag_ipv6=yes
		 Enable	IPv6 defragmentation in	pcap-thread, requires
		 use_layers=yes.

     max_ipv6_fragments=<num>
		 Set the maximum fragmented IPv6 packets to track for reassem-
		 bly, if the limit is reach then all other fragmented packets
		 will not be reassembled.

     max_ipv6_fragments_per_packet=<num>
		 Set the maximum fragments per tracked IPv6 packet to keep for
		 reassembly.

     parse_ongoing_tcp=yes
		 Enable	state tracking when a new TCP stream is	found but no
		 SYN/ACK has been seen.	 Each TCP packet with payload will be
		 tagged	as DNS.

     allow_reset_tcpstate=yes
		 Allow the TCP state to	be reseted, this is used in diagnostic
		 output	and plugins when parsing the DNS in a TCP packet fails
		 to try	and recover from missing or unaligned data.

     reassemble_tcp=yes
		 Enable	reassembly of TCP packets, this	will not parse each
		 packet	as an own DNS message but will store TCP segments un-
		 til they can be reassembled.  It will expect the DNS message
		 length	to come	first and then wait for	the full length	of
		 data to arrive	until passing to outputs and plugins.  Since
		 the number of saved segments are limited and fixed, if	the
		 TCP steam becomes corrupt then	processing may stop.  Recover-
		 ing from this can be done by enabling
		 allow_reset_tcpstate=yes which	will reset state and free all
		 saved segments	to try and start over.

     reassemble_tcp_faultreset=<num>
		 This controls the number of faults that can happen before the
		 state is reseted (as described	above),	faults are if the seg-
		 ments buffer are full or if the sequence is outside the TCP
		 window.  The default is zero which means it will reset	the
		 state as soon as the segment buffer is	full.

     reassemble_tcp_bfbparsedns=yes
		 Enable	an experimental	additional layer of reassemble that
		 uses libbind to parse the payload before accepting it.	 If
		 the DNS is invalid it will move 2 bytes within	the payload
		 and treat it as a new payload,	taking the DNS length again
		 and restart the process.  Requires that dnscap	was compiled
		 with libbind and reassemble_tcp=yes.

     bpf_hosts_apply_all=yes
		 This changes the BPF generation so that any host restriction
		 will come after ICMP, fragments, ports	or DNS section to al-
		 low it	to apply for ICMP and fragments	also.  The default be-
		 havior	is to only apply hosts to the ports or DNS section.

OUTPUT FORMATS
     The following output format are supported:

     cbor	 Uses tinycbor library to write	CBOR objects that are based on
		 DNS-in-JSON draft by Paul Hoffman.

     cds	 CBOR DNS Stream format.

     pcap	 This uses the pcap library to output the captured DNS pack-
		 ets.

     diagnostic	 This is the output produced by	-g , a backslash at the	end
		 indicates that	the line continues on the next.	 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	frag-
		 ment:

		       [<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 sep-
		 arated	by space.  Below are a few example, first is just a
		 query,	second has just	one answer and the last	has also au-
		 thority 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.

PLUGINS
     dnscap comes bundled with a set of	plugins, see -P	option and the plugins
     help page.

	   dnscap -P /usr/local/lib/dnscap/<plugin>.so -?

     This list of plugins are installed	in /usr/local/lib/dnscap:

     anonaes128.so
		 Anonymize IP addresses	using AES128.

     anonmask.so
		 Pseudo-anonymize IP addresses by masking them.

     cryptopan.so
		 Anonymize IP addresses	using an extension to Crypto-PAn (Col-
		 lege of Computing, Georgia Tech) made by David	Stott (Lu-
		 cent).

     cryptopant.so
		 Anonymize IP addresses	using cryptopANT, a different imple-
		 mentation of Crypto-PAn made by the ANT project at USC/ISI.

     eventlog.so
		 Output	DNS activity as	log events, including IP addresses
		 from query responses.

     ipcrypt.so	 Anonymize IP addresses	using ipcrypt create by	Jean-Philippe
		 Aumasson.

     pcapdump.so
		 Dump DNS into a PCAP with some	filtering options.

     royparse.so
		 Splits	a PCAP into two	streams; queries in PCAP format	and
		 responses in ASCII format.

     rssm.so	 Root Server Scaling Measurement plugin.

     rzkeychange.so
		 RFC8145 key tag signal	collection and reporting plugin.

     txtout.so	 Dump DNS as one-line text.

COMPATIBILITY NOTES
     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
     -6	, -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	gener-
     ated, and then cut/paste this BPF program onto a tcpdump(1) command line
     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.

DIAGNOSTICS
     The dnscap	utility	exits 0	on success, and	>0 if an error occurs.

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

AUTHORS
     Maintained	by DNS-OARC

	   https://www.dns-oarc.net/

     For issues	and feature requests please use:

	   https://github.com/DNS-OARC/dnscap/issues

     For question and help please use:

	   dnscap-users@dns-oarc.net

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

LICENSE
     Copyright (c) 2016-2020, OARC, Inc.  All rights reserved.

     Redistribution and	use in source and binary forms,	with or	without	modi-
     fication, are permitted provided that the following conditions are	met:

     1.	Redistributions	of source code must retain the above copyright
	notice,	this list of conditions	and the	following disclaimer.

     2.	Redistributions	in binary form must reproduce the above	copyright
	notice,	this list of conditions	and the	following disclaimer in
	the documentation and/or other materials provided with the
	distribution.

     3.	Neither	the name of the	copyright holder nor the names of its
	contributors may be used to endorse or promote products	derived
	from this software without specific prior written permission.

     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT	HOLDERS	AND CONTRIBUTORS "AS
     IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,	INCLUDING, BUT NOT LIMITED TO,
     THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     PURPOSE ARE DISCLAIMED. IN	NO EVENT SHALL THE COPYRIGHT HOLDER OR CON-
     TRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,	EXEM-
     PLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCURE-
     MENT OF SUBSTITUTE	GOODS OR SERVICES; LOSS	OF USE,	DATA, OR PROFITS; OR
     BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF	LIABILITY,
     WHETHER IN	CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
     OTHERWISE)	ARISING	IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
     ADVISED OF	THE POSSIBILITY	OF SUCH	DAMAGE.

FreeBSD	13.0			 July 8, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | EXTENDED OPTIONS | OUTPUT FORMATS | PLUGINS | COMPATIBILITY NOTES | DIAGNOSTICS | SEE ALSO | AUTHORS | HISTORY | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dnscap&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help