dnscap(1)

📦
version 2.5.2 · 7 versions
, in epel 10, epel 9, fedora 43, fedora 44

dnscap 💅 — the General Commands Manual bestie edition ✨

okay so. you opened the manual for dnscap(1) and honestly? you're about to have a good time. grab a strawberry 🍓, we're doing this.

✨ NAME ✨

dnscap — the DNS network traffic capture utility, aka your new main character 👑

🦋 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 💖

okay so dnscap is a network capture utility built specifically for DNS traffic, and she's not like other packet sniffers. Normally she produces binary data in pcap(3) format — either straight to standard output, or from files. Think of her as tcpdump(1)'s cooler cousin: same energy, but with finer grained packet recognition tailored to DNS transactions and protocol options. ✨

dnscap is expected to be used for gathering continuous research or audit traces. she's giving scientist. she's giving auditor. she's giving "I run forever and I'm unbothered". 💅

🌸 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. no cap, this is a lot, but we're gonna go category by category like the organized icon she is:

  • 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. bestie. you have to pick one. 😭

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. the more -ds, the more she yaps 🗣️✨

💜 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. bye bestie 👋

🎀 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. Supports reading compressed PCAPs based on file extension, see below for list of recognized extensions.
  • -o override_compress_extension=ext — Override which compression backend to use when decompressing the PCAP file. Supported compression extensions: gz, xz, lz4, zst, bz2
  • -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. 💫
  • -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. (she's not saying don't, she's saying I didn't do it) 🙈
  • -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. double the slay, double the output ✨
  • -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 (uncompressed) 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. 👀 (she's retired, respect her legacy)
  • -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. fr fr, she warned you 💀
  • -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 gets tagged as DNS, unless you're running -o reassemble_tcp=yes, which comes with support for the DNS length arriving before the message in its very own packet. And if you wanna snoop on connections that are already chugging along, -o parse_ongoing_tcp=yes is your girl. 🫶

Okay so real talk bestie — TCP packets get processed the second they arrive, which means missing data, unaligned data, or a DNS message split across multiple packets will straight up produce parsing errors. The extended option -o allow_reset_tcpstate=yes may let dnscap recover from those scenarios. 💀
  • -I — Selects ICMP and ICMPv6 packets. That's it, that's the whole vibe. 🌈
  • -l vlan — Captures only 802.1Q encapsulated packets, and picks which specific vlans get monitored. Throw it in more than once to select multiple vlans. VLAN id 4095 is the cheat code for all the vlans. ✨
  • -L vlan — Captures 802.1Q encapsulated packets matching the specified vlans AND packets with no VLAN tags at all (she's inclusive like that 💅). Can be specified more than once to select multiple vlans. VLAN id 4095 again means all vlans.
  • -u port — Capture only packets on this UDP port, and treat them 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. So pick a lane, babe. 🎀
  • -o defrag_ipv4=yes, -o defrag_ipv6=yes — Enable IPv4/IPv6 defragmentation in pcap-thread, and it requires -o use_layers=yes. When it's 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 reached, 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 reached, 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 — Normally dnscap won't even look at TCP unless it sees the start of it. This one turns on state tracking when a new TCP stream is found but no SYN/ACK has been seen. Every TCP packet with payload gets tagged as DNS. 👑
  • -o allow_reset_tcpstate=yes — Allows the TCP state to be reseted (yes, "reseted", she said what she said 🍓). This gets used in diagnostic output and plugins when parsing the DNS in a TCP packet fails, so it can try and recover from missing or unaligned data.
  • -o reassemble_tcp=yes — Enables reassembly of TCP packets. This means she will not parse each packet as its own DNS message — instead she stores TCP segments until they can be reassembled. She expects the DNS message length to come first, then waits for the full length of data to arrive before passing it along to outputs and plugins.

Since the number of saved segments is limited and fixed, if the TCP stream 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. (That's literally what the docs say, bestie, I'm just the messenger 😭)

  • -o reassemble_tcp_faultreset=num — Controls the number of faults (num) that can happen before the state is reseted (as described above). Faults are if the segments buffer is 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 — Enables 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 restarting 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 selects query and notify messages. But heads up: multiple -m cannot 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. If you want both non-error and error responses 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 wiping out the address only. This wiping happens 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. She does this by checking the DNS header flag QR and the 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, get added to the recognition pattern. 💖
  • -z host — Capture only transactions having these responders. Can be specified more than once to select multiple responders. Same deal with host names — all that host's IPv4 or IPv6 addresses get 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. Sneaky but effective.
  • -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 match 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 the 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 plugin's 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 the command line. 👑

These bundled plugins are installed in /usr/lib64/dnscap:

  • anonaes128.so — Anonymize IP addresses using AES128.
  • anonmask.so — Pseudo-anonymize IP addresses by masking them.
  • asudp.so — Rewrites outgoing packet, takes the DNS and constructs UDP packets, can be used together with layers and reassembling/defrag'ing packets.
  • 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 ✨

okay so bestie, besides the diagnostic and PCAP output, there might be other output formats available depending on compile time support. 💅

Recognized formats are:

  • cbor — uses the tinycbor library to write CBOR objects that are based on the 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 the extended options related to this format. 🦋
  • pcap — this uses the pcap library to output the captured DNS packets. (default) 🔥
  • tcpdns — this format outputs the DNS as a TCP stream, first 16bit size (network order) then the DNS message. This output is compatible with dnsperf -B. 💜
  • 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 examples, 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>]]

Note: comma characters in fqdn will be quoted with a backslash, for example:

1 exam\,ple.com.,IN,A 0 0 0

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://codeberg.org/DNS-OARC/dnscap/issues

For question and help please use:

admin@dns-oarc.net

💖 That's the whole manual, bestie. This was dnscap 2.5.2, page dnscap(1) — now go be the main character of packet capture. Slay. ✨👑

📦 where this page comes from