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

FreeBSD Manual Pages


home | help
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 ...]
       dnscap -g ...
       dnscap -w ...

       dnscap is a network capture utility designed specifically for DNS traf-
       fic.   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 con-
       tinuous 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.

       o      GENERIC  section	shows how to display help and version, and en-
	      able debugging.

       o      RUNTIME section  handles	sandbox,  privileges,  start/stop  and
	      other runtime actions.

       o      INPUT section deals with what interface to capture on, how to do
	      it or if you want	to read	from a file.

       o      OUTPUT section gives you options to do packet dumps,  or	get  a
	      diagnostic  output, and to set limits or run external actions on

       o      NETWORK section tweaks how and what is captured on  the  network
	      and the individual layers.

       o      DNS  section  lets you do	filtering and modifications on the DNS
	      message, along with pattern matching on the domain names.

       o      Lastly, PLUGINS section gives you	an overview on how dnscap  can
	      be extended by plugins and which plugins are bundled.

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

       -?     Display  short  form  help  text	about command line options and

       -V     Print version and	exit.

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

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

       -b     Run  in  background  as  daemon  and  drop   privileges,	 using
	      set*uid(),  set*gid()  functions,	 unless	options	-N is given or
	      only reading from	files.

       -o user=...
	      Specify the user to drop privileges to (default nobody).

       -o group=...
	      Specify the group	to drop	privileges to (default nobody).

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

       -S     Print  stats  counters  on standard error	when closed the	packet
	      dump file	(see -w).

       -B datetime
	      Start collecting at a specific time.  datetime should be	speci-
	      fied  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  ear-
	      lier  time  if used with an offline pcap(3) file,	and then begin
	      capturing/processing packets.

       -E datetime
	      Stop collecting at a specific time.  datetime should  be	speci-
	      fied  as "YYYY-MM-DD HH:MM:SS".  dnscap will exit	when it	sees a
	      packet (live or offline pcap(3) file) with timestamp greater  or
	      equal to it.

       -r file
	      Select  an  offline  pcap(3) file	produced by this utility or by
	      tcpdump(1) (or simiar tools) as the input	packet source.	Can be
	      given as "-" to indicate standard	input.

       -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	inter-
	      faces.  More than	one interface may be selected which will cause
	      output to	be interleaved from all	selected interfaces.

       -p     Asks  that the interface not be put into promiscuous mode.  Note
	      that even	without	this option, the interface could be in promis-
	      cuous mode for some other	reason.

       -M     Enable monitor mode on interfaces.

       -D     Enable immediate mode on interfaces.

	      Option  -p,  -M and -D are libpcap specific options, see pcap(3)
	      for more information on their meaning.

       -o pcap_buffer_size=num
	      Set the pcap(3) buffer size to num bytes when capturing packets.
	      This  can	be used	to increase the	buffer so that packets are not
	      missed/dropped while processing or rotating packet dumps.

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

	      This  options  is	 required  for	IP defragmentation (see	-o de-
	      frag_ipv4=yes and	-o defrag_ipv6=yes), TCP  reassembly  (see  -o
	      reassemble_tcp=yes)  and	parsing	 ongoing  TCP sessions (see -o

       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.

       -o dump_format=format
	      Specify the output format	to use.	 Default is pcap.

       -g     Produce diagnostic output	to standard error, showing the presen-
	      tation form of DNS messages which	passed through all of the fil-
	      ters.  If	-w is also used, then every message will be dumped  in
	      both binary and presentation form.

       -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 mi-
	      croseconds.   The	 argument  "-" may be given to send the	binary
	      output to	standard output.

	      By default, dnscap will close its	packet dump file only when in-
	      terrupted.   You	can  change that behavior with options -t, -c,
	      and -C.

       -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 auto-
	      matically	gzip compressed.  If gzip compression is requested but
	      not  supported (i.e. because of lack of system support) an error
	      will be generated.

       -1     Flush the	output after every packet.  Mostly this	is useful when
	      the  packet  dump	is standard output, and	has been piped to tcp-

       -t lim Set a time interval, specified in	seconds.  When	writing	 to  a
	      file, the	packet dump file will be closed	and reopened (creating
	      a	new dump file) when time() % lim is zero.  Note	that the first
	      file  will  usually  be shorter than lim seconds.	 If the	packet
	      dump file	is standard output or if -g is used, then dnscap  will
	      exit after the first interval.

       -c lim Set  a size limit, measured in packets.  When writing to a file,
	      the packet dump file will	be closed when lim number  of  packets
	      has  been	 written.  If option -k	is not used (see below)	or the
	      packet dump file is standard output, or  if  -g  is  used,  then
	      dnscap will exit after reaching the limit.

       -C lim Set  a  size  limit, measured in bytes.  When writing to a file,
	      the packet dump file will	be closed when lim number of bytes (or
	      larger  then) has	been written.  If option -k is not used	or the
	      packet dump file is standard output, or  if  -g  is  used,  then
	      dnscap will exit after reaching the limit.

	      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.

       -k cmd After  each  dump	 file  specified by -w is closed, this command
	      will be executed in a non-blocking subprocess with the file name
	      as  its  one  argument.  This can	be used	to submit the finished
	      file to other processing systems.

	      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.

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

       -o 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 allow
	      it to apply for ICMP and fragments also.	The  default  behavior
	      is to only apply hosts to	the ports or DNS section.

       -6     Used  to	suppress  the use of packet filter patterns that cause
	      problems when processing IPv6 packets.  As of version 2.0.0 this
	      option  is  deprecated  and  filters  have been reworked to only
	      match IPv4 packets, IPv6 filtering are  processed	 at  a	higher

       -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 Reassem-
	      bly.  Note that all fragments will be collected, not just	 those
	      using  the DNS port number, since	fragments don't	have port num-
	      bers.  Beware this option	if you also handle a lot of NFS	 traf-

       -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,
	      or  -e.  All DNS messages	in the stream is captured 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.  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_tcp-
	      state=yes	may allow dnscap to recover from these scenarios.

       -I     Select ICMP and ICMPv6 packets.

       -l vlan
	      Captures	only 802.1Q encapsulated packets, and selects specific
	      vlans to be monitored.  Can be specified more than once  to  se-
	      lect  multiple  vlans.   VLAN id 4095 can	be used	to specify all

       -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.  VLAN id 4095 can be used to spec-
	      ify all vlans.

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

       -o defrag_ipv4=yes
       -o defrag_ipv6=yes
	      Enable IPv4/IPv6 defragmentation	in  pcap-thread,  requires  -o

	      When enabled, the	following options are also available:

	      -o max_ipv4_fragments=num
		     Set  the  maximum	fragmented IPv4	packets	(num) to track
		     for reassembly, if	the limit  is  reach  then  all	 other
		     fragmented	packets	will not be reassembled.

	      -o max_ipv4_fragments_per_packet=num
		     Set  the  maximum fragments (num) per tracked IPv4	packet
		     to	keep for reassembly.

	      -o max_ipv6_fragments=num
		     Set the maximum fragmented	IPv6 packets  (num)  to	 track
		     for  reassembly,  if  the	limit  is reach	then all other
		     fragmented	packets	will not be reassembled.

	      -o max_ipv6_fragments_per_packet=num
		     Set the maximum fragments (num) per tracked  IPv6	packet
		     to	keep for reassembly.

       -o parse_ongoing_tcp=yes
	      dnscap will normally not look at TCP unless it sees the start of
	      it.  This	enables	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.

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

       -o reassemble_tcp=yes
	      Enable reassembly	of TCP	packets,  this	will  not  parse  each
	      packet  as  an own DNS message but will store TCP	segments until
	      they can be reassembled.	It will	expect the DNS message	length
	      to  come	first and then wait for	the full length	of data	to ar-
	      rive 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.  Recovering
	      from this	can be done by enabling	which  will  reset  state  and
	      free all saved segments to try and start over.

       -o reassemble_tcp_faultreset=num
	      This  controls the number	of faults (num)	that can happen	before
	      the state	is reseted (as described above),  faults  are  if  the
	      segments	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.

       -o reassemble_tcp_bfbparsedns=yes
	      Enable  an  additional  layer  (experimental) of reassembly that
	      uses LDNS	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

       -m [qun]
	      Capture  only  messages  of designated types; query, update, and
	      notify).	Multiple types can be given at the same	time, for  ex-
	      ample  -m	qn will	select query and notify	messages.  Multiple -m
	      can not be used to specify multiple types.  Default is query.

       -e [nytfsxir]
	      Among responses, consider	nonzero	DNS TC or DNS RCODE  to	 indi-
	      cate  an error, and select only responses	which do not have (n),
	      or which have (y), these conditions.  The	default	is to only se-
	      lect  non-errors	among  responses.  If both non-error and error
	      responses	are to be selected, specify both the n and  y  options

	      To be more specific, use one or more condition-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.	  Hid-
	      ing  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.  This is
	      done by checking the DNS header flag QR  and  source/destination
	      port against the DNS port	(see -u).  Default is both.

       -a host
	      Capture only transactions	having these initiators.  Can be spec-
	      ified 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 spec-
	      ified  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.

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

       -X pat If one or	more -X	options	are provided, then DNS messages	match-
	      ing these	patterns will not be selected.

	      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 expres-
	      sion syntax.

       -q num|str
	      Only select DNS messages where QTYPE matches the specified type.
	      Can not be used together with -Q.

       -Q num|str
	      Only select DNS messages where QTYPE does	not matches the	speci-
	      fied type.  Can not be used together with	-q.

       -P /path/to/ ...
	      Load  and	 use the specified plugin, full	path to	plugin must be
	      supplied.	 Any options given after this are sent to the plugin.

	      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/ -a opt -- -P /path/to/ -b opt

	      To show the plugins option help, run it with -?:

		-P /path/to/ -?

	      Plugins are loaded, executed and given the packets to process in
	      the order	given on command line.

	      These bundled plugins are	installed in /usr/local/lib/dnscap:
		     Anonymize IP addresses using AES128.
		     Pseudo-anonymize IP addresses by masking them.
		     Anonymize IP addresses using an extension	to  Crypto-PAn
		     (College  of Computing, Georgia Tech) made	by David Stott
		     Anonymize IP addresses using cryptopANT, a	different  im-
		     plementation  of  Crypto-PAn  made	 by the	ANT project at
		     Output DNS	activity as log	events,	including IP addresses
		     from query	responses.
		     Anonymize	 IP   addresses	  using	  ipcrypt   create  by
		     Jean-Philippe Aumasson.
		     Dump DNS into a PCAP with some filtering options.
		     Splits a PCAP into	two streams; queries  in  PCAP	format
		     and responses in ASCII format.
		     Root Server Scaling Measurement plugin.
		     RFC8145 key tag signal collection and reporting plugin.
		     Dump DNS as one-line text.

       Beside diagnostic and PCAP output, other	output formats might be	avail-
       able depending on compile time support.

       Recognized formats are:

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

       cds    CBOR	     DNS	  Stream	  format,	   see
	      ter/  for  details  and	below for all extended
	      options related to this format.

       pcap   This uses	the pcap library to output the captured	 DNS  packets.

	      This  is	the  output  produced  by  -g,	and  is	 meant	to  be
	      parse-able.  It is broken	up into	multiple lines	with  a	 back-
	      slash  at	 the  end  to  indicate	that the line continues	on the

	      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, sec-
	      ond has just one answer and the last has also authority and  ad-
	      ditional records.

		1,IN,A 0 0	0

		1,IN,A \
		1,IN,A,47, 0 0

		1,IN,A \
		1,IN,A,263, \
		4,IN,NS,157794, \,IN,NS,157794, \,IN,NS,157794, \,IN,NS,157794, \
		4,IN,A,157794, \,IN,A,331796, \,IN,A,157794, \,IN,A,157794,

	      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.

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

       -o cds_cbor_size=bytes
	      Number of	bytes of memory	to use before flushing to file.

       -o cds_message_size=bytes
	      Number of	bytes of memory	to use for each	DNS packet.

       -o cds_max_rlabels=num
	      Number of	labels (num) to	keep in	the reverse label index.

       -o cds_min_rlabel_size=num
	      The  minimum size	of a label (num) to be able to use the reverse
	      label index.

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

       -o cds_rdata_index_min_size=num
	      The minimum size of the data (num) to be able  to	 use  the  re-
	      source data index.

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

       -o cds_rdata_rindex_size=num
	      Number  of  resource data	(num) to keep in the resource data re-
	      verse index.

       -o cds_rdata_rindex_min_size=num
	      The minimum size of the data (num) to be able  to	 use  the  re-
	      source data reverse index.

       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 func-
       tion 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

	 dnscap	-m qun -h i -z \
		-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 re-
       sponder is 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 contain-
       ing "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 pro-
       gram 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.

       tcpdump(1), pcap(3), regex(3), bpf(4), re_format(7)

       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 LundstrA<paragraph>m, DNS-OARC.

       For issues and feature requests please use:

       For question and	help please use:

dnscap				     2.0.1			     dnscap(1)


Want to link to this manual page? Use this URL:

home | help