summaryrefslogtreecommitdiffstats
path: root/src/dnscap.1.in
diff options
context:
space:
mode:
Diffstat (limited to 'src/dnscap.1.in')
-rw-r--r--src/dnscap.1.in1011
1 files changed, 1011 insertions, 0 deletions
diff --git a/src/dnscap.1.in b/src/dnscap.1.in
new file mode 100644
index 0000000..82a44fd
--- /dev/null
+++ b/src/dnscap.1.in
@@ -0,0 +1,1011 @@
+.\" Copyright (c) 2016-2021, 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 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 is to monitor all interfaces.
+More than one interface may be selected which 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 one 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