path: root/src/dnscap.1.in

.\" Copyright (c) 2016-2024 OARC, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, 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 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT 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.
.TH dnscap 1 "@PACKAGE_VERSION@" "dnscap"
.SH NAME
dnscap \- DNS network traffic capture utility
.SH SYNOPSIS
.SY dnscap
.OP \-?VbNpd1g6fTIySMD
.OP \-o option=value
.OP \-i if
.OP \-r file
.OP \-l vlan
.OP \-L vlan
.OP \-u port
.OP \-m [qun]
.OP \-e [nytfsxir]
.OP \-h [ir]
.OP \-s [ir]
.OP \-a host
.OP \-z host
.OP \-A host
.OP \-Z host
.OP \-Y host
.OP \-w base
.OP \-W suffix
.OP \-k cmd
.OP \-t lim
.OP \-c lim
.OP \-C lim
.OP \-x pat
.OP \-X pat
.OP \-B datetime
.OP \-E datetime
.OP \-U str
.OP \-q num|str
.OP \-Q num|str
.OP \-P "plugin.so ..."
.SY dnscap
.BR \-g " ..."
.SY dnscap
.BR \-w " ..."
.YS
.SH DESCRIPTION
.B dnscap
is a network capture utility designed specifically for DNS traffic.
It normally produces binary data in
.BR pcap (3)
format, either on standard output or from files.
This utility is similar to
.BR tcpdump (1),
but has finer grained packet recognition tailored to DNS transactions and
protocol options.
.B dnscap
is expected to be used for gathering continuous research or audit traces.
.SH OPTIONS
.B dnscap
has a large array of command line options and extended options
.RB ( \-o
.IR option=value ),
and to make it easier to understand their usage they are categorized.
.IP \(bu
.I GENERIC
section shows how to display help and version, and enable debugging.
.IP \(bu
.I RUNTIME
section handles sandbox, privileges, start/stop and other runtime actions.
.IP \(bu
.I INPUT
section deals with what interface to capture on, how to do it or if you want
to read from a file.
.IP \(bu
.I OUTPUT
section gives you options to do packet dumps, or get a diagnostic output,
and to set limits or run external actions on intervals.
.IP \(bu
.I NETWORK
section tweaks how and what is captured on the network and the individual
layers.
.IP \(bu
.I DNS
section lets you do filtering and modifications on the DNS message, along
with pattern matching on the domain names.
.IP \(bu
Lastly,
.I PLUGINS
section gives you an overview on how
.B dnscap
can be extended by plugins and which plugins are bundled.
.RE

The only required options are
.B \-g
and
.BR \-w ,
at least one of them must be supplied to run.

If neither
.B \-r
or
.B \-i
is used then the default is to capture on the first or all interfaces
(depends on system, see
.B \-i
for more information).
.\"
.\"
.\"
.SS GENERIC
.TP
.B \-?
Display short form help text about command line options and exit.
.TP
.B \-V
Print version and exit.
.TP
.B \-d
Tells a verbose story of options and patterns chosen, files opened, and so on.
Multiple
.B \-d
options can be given to increase verbosity and frequency of trace messages.
.\"
.\"
.\"
.SS RUNTIME
.TP
.B \-y
Enable Linux seccomp\-bpf sandbox if available (compile option).
.TP
.B \-b
Run in background as daemon and drop privileges, using
.IR set*uid() ,
.I set*gid()
functions, unless options
.B \-N
is given or only reading from files.
.TP
.BI "\-o pid_file" =...
Specify the file to write the PID to when running as a daemon (default none).
.TP
.BI "\-o user" =...
Specify the user to drop privileges to (default nobody).
.TP
.BI "\-o group" =...
Specify the group to drop privileges to (default nobody).
.TP
.B \-N
Do not attempt to drop privileges, this is implicit if only reading
offline pcap files.
.TP
.B \-S
Print stats counters on standard error when closed the packet dump file
(see
.BR \-w ).
.TP
.BI "\-B " datetime
Start collecting at a specific time.
.I datetime
should be specified as "YYYY\-MM\-DD HH:MM:SS".
The program will
.BR sleep (3)
until the start time, or it will skip all packets related to an earlier
time if used with an offline
.BR pcap (3)
file, and then begin capturing/processing packets.
.TP
.BI "\-E " datetime
Stop collecting at a specific time.
.I datetime
should be specified as "YYYY\-MM\-DD HH:MM:SS".
.B dnscap
will exit when it sees a packet (live or offline
.BR pcap (3)
file) with timestamp greater or equal to it.
.\"
.\"
.\"
.SS INPUT
.TP
.BI "\-r " file
Select an offline
.BR pcap (3)
file produced by this utility or by
.BR tcpdump (1)
(or simiar tools) as the input packet source.
Can be given as "\-" to indicate standard input.
.TP
.BI "\-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).

Can be specified more than once to select multiple interfaces, this will
cause output to be interleaved from all selected interfaces.
.TP
.B \-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.
.TP
.B \-M
Enable monitor mode on interfaces.
.TP
.B \-D
Enable immediate mode on interfaces.

Option
.BR \-p ,
.B \-M
and
.B \-D
are libpcap specific options, see
.BR pcap (3)
for more information on their meaning.
.TP
.BI "\-o " pcap_buffer_size=num
Set the
.BR pcap (3)
buffer size to
.I 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.
.TP
.BI "\-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
.BI "\-o " defrag_ipv4=yes
and
.B \-o
.IR defrag_ipv6=yes ),
TCP reassembly (see
.B \-o
.IR reassemble_tcp=yes )
and parsing ongoing TCP sessions (see
.B \-o
.IR parse_ongoing_tcp=yes ).
.\"
.\"
.\"
.SS 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.
.TP
.BI "\-o " dump_format=format
Specify the output
.I format
to use.
Default is
.IR pcap .
.TP
.B \-g
Produce diagnostic output to standard error, showing the presentation form
of DNS messages which passed through all of the filters.
If
.B \-w
is also used, then every message will be dumped in both binary and
presentation form.
.TP
.BI "\-w " base
Dump the captured packets to successive binary files in
.BR pcap (3)
format with DLT_RAW datalink type.
Each file will have a name like "%s.%s.%06u" where the first %s is
.IR 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,
.B dnscap
will close its packet dump file only when interrupted.
You can change that behavior with options
.BR \-t ,
.BR \-c ,
and
.BR \-C .
.TP
.BI "\-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.
.TP
.B \-1
Flush the output after every packet.
Mostly this is useful when the packet dump is standard output, and has been
piped to
.BR tcpdump (1).
.TP
.BI "\-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() %
.I lim
is zero.
Note that the first file will usually be shorter than
.I lim
seconds.
If the packet dump file is standard output or if
.B \-g
is used, then
.B dnscap
will exit after the first interval.
.TP
.BI "\-c " lim
Set a size limit, measured in packets.
When writing to a file, the packet dump file will be closed when
.I lim
number of packets has been written.
If option
.B \-k
is
.I "not used"
(see below) or the packet dump file is standard output, or if
.B \-g
is used, then
.B dnscap
will exit after reaching the limit.
.TP
.BI "\-C " lim
Set a size limit, measured in bytes.
When writing to a file, the packet dump file will be closed when
.I lim
number of bytes (or larger then) has been written.
If option
.B \-k
is
.I "not used"
or the packet dump file is standard output, or if
.B \-g
is used, then
.B dnscap
will exit after reaching the limit.

When using the above options
.BR \-t ,
.BR \-c ,
and
.B \-C
together, the order of applying them are
.I 1)
time interval,
.I 2)
number of packets and
.I 3)
number of bytes.
.TP
.BI "\-k " cmd
After each dump file specified by
.B \-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
.B \-c
or
.B \-C
and the output is a packet dump file, then it will be reopened (creating
a new dump file) before continuing.
.\"
.\"
.\"
.SS NETWORK
.TP
.BI "\-U " str
Append "and
.IR str """"
to the BPF/pcap filter.
.TP
.BI "\-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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
.BR \-m ,
.BR \-s ,
or
.BR \-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
.BI "\-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
.B \-o
.IR 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
.BI "\-o " allow_reset_tcpstate=yes
may allow
.B dnscap
to recover from these scenarios.
.TP
.B \-I
Select ICMP and ICMPv6 packets.
.TP
.BI "\-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.
.TP
.BI "\-L " vlan
Captures 802.1Q encapsulated packets matching the specified vlans AND
packets without VLAN tags.
Can be specified more than once to select multiple vlans.
VLAN id 4095 can be used to specify all vlans.
.TP
.BI "\-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.

.TP
.BI "\-o " defrag_ipv4=yes
.TQ
.BI "\-o " defrag_ipv6=yes
Enable IPv4/IPv6 defragmentation in pcap-thread, requires
.B \-o
.IR use_layers=yes .

When enabled, the following options are also available:
.RS
.TP
.BI "\-o " max_ipv4_fragments=num
Set the maximum fragmented IPv4 packets
.RI ( num )
to track for reassembly, if the limit is reach then all other fragmented
packets will not be reassembled.
.TP
.BI "\-o " max_ipv4_fragments_per_packet=num
Set the maximum fragments
.RI ( num )
per tracked IPv4 packet to keep for reassembly.
.TP
.BI "\-o " max_ipv6_fragments=num
Set the maximum fragmented IPv6 packets
.RI ( num )
to track for reassembly, if the limit is reach then all other fragmented
packets will not be reassembled.
.TP
.BI "\-o " max_ipv6_fragments_per_packet=num
Set the maximum fragments
.RI ( num )
per tracked IPv6 packet to keep for reassembly.
.RE
.TP
.BI "\-o " parse_ongoing_tcp=yes
.B 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.
.TP
.BI "\-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.
.TP
.BI "\-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
.Ar allow_reset_tcpstate=yes
which will reset state and free all saved segments to try and start over.
.TP
.BI "\-o " reassemble_tcp_faultreset=num
This controls the number of faults
.RI ( 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.
.TP
.BI "\-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.
.\"
.\"
.\"
.SS DNS
.TP
.BI "\-m " [qun]
Capture only messages of designated types;
.IR q uery,
.IR u pdate,
and
.IR n otify).
Multiple types can be given at the same time, for example
.B "\-m qn"
will select query and notify messages.
Multiple
.B \-m
can not be used to specify multiple types.
Default is query.
.TP
.BI "\-e " [nytfsxir]
Among responses, consider nonzero DNS TC or DNS RCODE to indicate an error,
and select only responses which do not have
.RI ( n ),
or which have
.RI ( 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
.I n
and
.I y
options here.

To be more specific, use one or more condition\-specific options, as follows:
.RS
.TP
.B n
no error
.TP
.B y
some error
.TP
.B t
truncated response (TC bit)
.TP
.B f
format error (rcode 1)
.TP
.B s
server failure (rcode 2)
.TP
.B x
no such name (rcode 3)
.TP
.B i
not implemented (rcode 4)
.TP
.B r
refusal (rcode 5)
.RE
.TP
.BI "\-h " ir
Hide
.IR i nitiator
or
.IR r esponder
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
.BR pcap (3)
dump output, and both the IP and UDP checksums will be recomputed in that case.
.TP
.BI "\-s " ir
Select messages which are
.IR i nitiations
and/or
.IR r esponses.
This is done by checking the DNS header flag QR and source/destination port
against the DNS port (see
.BR \-u ).
Default is both.
.TP
.BI "\-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.
.TP
.BI "\-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.
.TP
.BI "\-A " host
Capture only transactions NOT having these initiators.
.TP
.BI "\-Z " host
Capture only transactions NOT having these responders.
.TP
.BI "\-Y " host
Drop responses having these responders.
Similar to
.B \-Z
in spirit.
However,
.B \-Y
applies only to responses and does not cause any additions to the BPF filter
string.
.TP
.BI "\-x " pat
If one or more
.B \-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
.I pat
patterns.
.TP
.BI "\-X " pat
If one or more
.B \-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
.B \-x
and then not matched by all
.B \-X
regex.
See
.BR regex (3)
and
.BR re_format (7)
for more information about extended regular expression syntax.
.TP
.BI "\-q " num|str
Only select DNS messages where QTYPE matches the specified type.
Can not be used together with
.BR \-Q .
.TP
.BI "\-Q " num|str
Only select DNS messages where QTYPE does not matches the specified type.
Can not be used together with
.BR \-q .
.\"
.\"
.\"
.SS PLUGINS
.TP
.BI "\-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
.BR \-P ,
processing of the command line options will go back to
.BR dnscap .

Using this you can chain and use multiple plugins at once:

.EX
  \-P /path/to/plugin_one.so \-a opt \-\- \-P /path/to/plugin_two.so \-b opt
.EE

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

.EX
  \-P /path/to/plugin_one.so \-?
.EE

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

These bundled plugins are installed in @pkglibdir@:
.RS
.TP
.B anonaes128.so
Anonymize IP addresses using AES128.
.TP
.B anonmask.so
Pseudo\-anonymize IP addresses by masking them.
.TP
.B cryptopan.so
Anonymize IP addresses using an extension to Crypto\-PAn (College of
Computing, Georgia Tech) made by David Stott (Lucent).
.TP
.B cryptopant.so
Anonymize IP addresses using cryptopANT, a different implementation of
Crypto\-PAn made by the ANT project at USC/ISI.
.TP
.B eventlog.so
Output DNS activity as log events, including IP addresses from query responses.
.TP
.B ipcrypt.so
Anonymize IP addresses using ipcrypt create by Jean\-Philippe Aumasson.
.TP
.B pcapdump.so
Dump DNS into a PCAP with some filtering options.
.TP
.B royparse.so
Splits a PCAP into two streams; queries in PCAP format and responses in
ASCII format.
.TP
.B rssm.so
Root Server Scaling Measurement plugin.
.TP
.B rzkeychange.so
RFC8145 key tag signal collection and reporting plugin.
.TP
.B txtout.so
Dump DNS as one\-line text.
.RE
.\"
.\"
.\"
.SH OUTPUT FORMATS
Beside diagnostic and PCAP output, other output formats might be available
depending on compile time support.

Recognized formats are:
.TP
.B cbor
Uses tinycbor library to write CBOR objects that are based on DNS\-in\-JSON
draft by Paul Hoffman.
.TP
.B cds
CBOR DNS Stream format, see
.I https://github.com/DNS\-OARC/dnscap/blob/master/CBOR_DNS_STREAM.md
for details and below for all extended options related to this format.
.TP
.B pcap
This uses the pcap library to output the captured DNS packets. (default)
.TP
.B diagnostic
This is the output produced by
.BR \-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:

.EX
  [<pktsize>] <date> <timestamp> [<pktnum> <file|interface> <vlanid>]
.EE

Second line shows IP information or if the packet is a fragment:

.EX
  [<srcip>].<srcport> \-> [<dstip>].<dstport>
.EE
.EX
  ;: [<srcip>] \-> [<dstip>] (frag)
.EE

If the packet contains DNS information then the next line will show the DNS
header information:

.EX
  dns <opcode>,<rcode>,<id>,<flags>
.EE

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.

.EX
  1 example.com.,IN,A 0 0 0
.EE

.EX
  1 example.com.,IN,A \\
  1 example.com.,IN,A,47,127.0.0.1 0 0
.EE

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

Each DNS record contains the following:

.EX
  <fqdn>,<class>,<type>[,<ttl>[,<additional information>]]
.EE

Additional information will be displayed for SOA, A, AAAA, MX, NS, PTR,
CNAME and OPT records containing EDNS0.
.SS CBOR
.TP
.BI "\-o " cbor_chunk_size=bytes
Specify the number of
.I bytes
of CBOR to construct before flushing the output, must be a non zero
positive number.
.SS CBOR DNS STREAM (CDS)
.TP
.BI "\-o " cds_cbor_size=bytes
Number of
.I bytes
of memory to use before flushing to file.
.TP
.BI "\-o " cds_message_size=bytes
Number of
.I bytes
of memory to use for each DNS packet.
.TP
.BI "\-o " cds_max_rlabels=num
Number of labels
.RI ( num )
to keep in the reverse label index.
.TP
.BI "\-o " cds_min_rlabel_size=num
The minimum size of a label
.RI ( num )
to be able to use the reverse label index.
.TP
.BI "\-o " cds_use_rdata_index=yes
Use the resource data index, default is no.
.TP
.BI "\-o " cds_rdata_index_min_size=num
The minimum size of the data
.RI ( num )
to be able to use the resource data index.
.TP
.BI "\-o " cds_use_rdata_rindex=yes
Use the resource data reverse index, default is no.
.TP
.BI "\-o " cds_rdata_rindex_size=num
Number of resource data
.RI ( num )
to keep in the resource data reverse index.
.TP
.BI "\-o " cds_rdata_rindex_min_size=num
The minimum size of the data
.RI ( num )
to be able to use the resource data reverse index.
.SH EXAMPLES
In
.BR dnscap 's
simplest form, the output can be piped to
.BR tcpdump (1)
as in:

.EX
  dnscap -w - | tcpdump -r -
.EE

You can safely add the
.B \-d
option since the diagnostic output resulting from
.B \-d
goes to standard error rather than standard output.

The more interesting use for
.B dnscap
is long term or continuous data collection.
Assuming a shell script called
.I dnscap-upload
whose function is to transfer a
.BR 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
.B dnscap
for continuous DNS auditing using a command like:

.EX
  dnscap -m qun -h i -z f.root-servers.net \\
         -w /var/local/dnscaps/f-root -t 1800 \\
         -k /usr/local/sbin/dnscap-upload
.EE

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
.I dnscap-upload
script will be executed.

A bizarre but actual example which combines almost all features of
.B dnscap
is:

.EX
  dnscap -d -w - -1 -i em0 -l 0 -x ^7 | \\
    dnscap -d -r - -X spamhaus -g -l 0
.EE

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
.B dnscap
will also be tagged, thus we need
.BI "\-l " 0
on both
.B dnscap
commands.
.SH COMPATIBILITY NOTES
If
.B dnscap
produces no output, it's probably due to some kind of bug in the kernel's
.BR bpf (4)
module or in the
.BR pcap (3)
library.

You may need the
.BI "\-l " 0
,
.BI "\-l " 4095
or
.BI "\-L " 4095
options.

To diagnose "no output", use the
.B \-d
and
.B \-g
options to find out what BPF program is being internally generated, and
then cut/paste this BPF program and use
.BR tcpdump (1)
to see if it likewise produces no output.

You can also run
.BR tcpdump (1)
with
.B \-e
to see the link-level headers in order to see if the traffic is encapsulated.
.SH SEE ALSO
.BR tcpdump (1),
.BR pcap (3),
.BR regex (3),
.BR bpf (4),
.BR re_format (7)
.SH AUTHORS
.B 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.
.LP
.RS
.I https://www.dns\-oarc.net/
.RE
.LP
.SH BUGS
For issues and feature requests please use:
.LP
.RS
\fI@PACKAGE_URL@\fP
.RE
.LP
For question and help please use:
.LP
.RS
\fI@PACKAGE_BUGREPORT@\fP
.RE
.LP