Provided by: dnscap_2.1.3-2_amd64 bug

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 [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 plugin.so ...]
       dnscap -g ...
       dnscap -w ...

DESCRIPTION

       dnscap  is  a  network capture utility designed specifically for DNS traffic.  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 continuous
       research or audit traces.

OPTIONS

       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.

       •      GENERIC section shows how to display help and version, and enable debugging.

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

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

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

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

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

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

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

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

   RUNTIME
       -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 pid_file=...
              Specify the file to write the PID to when running as a daemon (default none).

       -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 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/processing packets.

       -E datetime
              Stop  collecting  at  a specific time.  datetime should be specified 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.

   INPUT
       -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 default is the first interface that was  configured  at  system
              boot time.

              On  Linux systems, the default might be to monitor all interfaces but most commonly
              it will also capture on the first interface.  This depends on the libpcap version.

              If you want to make sure you're capturing on all interfaces then  use  the  special
              "any" or "all" (depends on system).

              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 promiscuous 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 defrag_ipv4=yes and -o
              defrag_ipv6=yes), TCP reassembly (see -o reassemble_tcp=yes)  and  parsing  ongoing
              TCP sessions (see -o parse_ongoing_tcp=yes).

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

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

              By  default, dnscap will close its packet dump file only when interrupted.  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  automatically  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 tcpdump(1).

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

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

       -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  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, 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_tcpstate=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 select multiple vlans.  VLAN id 4095
              can be used to specify 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.   VLAN
              id 4095 can be used to specify 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 use_layers=yes.

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

   DNS
       -m [qun]
              Capture only messages of designated types; query, update,  and  notify).   Multiple
              types can be given at the same time, for example -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 indicate an error, and
              select only responses which do not have (n), or which have (y),  these  conditions.
              The  default  is  to only select non-errors among responses.  If both non-error and
              error responses are to be selected, specify both the n and y options here.

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

       -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 matching 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 expression 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 specified type.  Can not
              be used together with -q.

   PLUGINS
       -P /path/to/plugin.so ...
              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/plugin_one.so -a opt -- -P /path/to/plugin_two.so -b opt

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

                -P /path/to/plugin_one.so -?

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

              These bundled plugins are installed in /usr/lib/x86_64-linux-gnu/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  (College  of
                     Computing, Georgia Tech) made by David Stott (Lucent).

              cryptopant.so
                     Anonymize IP addresses  using  cryptopANT,  a  different  implementation  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.

OUTPUT FORMATS

       Beside  diagnostic  and  PCAP output, other output formats might be available 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
              https://github.com/DNS-OARC/dnscap/blob/master/CBOR_DNS_STREAM.md for  details  and
              below for all extended options related to this format.

       pcap   This uses the pcap library to output the captured DNS packets. (default)

       diagnostic
              This  is the output produced by -g, and is meant to be parse-able.  It is broken up
              into multiple lines with a backslash at the end to indicate 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 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, second has just one answer and the  last  has  also
              authority 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.

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

   CBOR DNS STREAM (CDS)
       -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 resource 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 reverse index.

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

EXAMPLES

       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 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 -z f.root-servers.net \
                -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  responder  is  f.root-
       servers.net  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 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.

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

SEE ALSO

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

AUTHORS

       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 Lundström, DNS-OARC.

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

BUGS

       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