diff options
Diffstat (limited to 'src/dnscap.1.in')
| -rw-r--r-- | src/dnscap.1.in | 1011 |
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 |