dnscap has a large array of command line options and extended options (-ooption=value), and to make it
easier to understand their usage they are categorized.
• GENERIC section shows how to display help and version, and enable debugging.
• RUNTIME section handles sandbox, privileges, start/stop and other runtime actions.
• INPUT section deals with what interface to capture on, how to do it or if you want to read from a
file.
• OUTPUT section gives you options to do packet dumps, or get a diagnostic output, and to set limits
or run external actions on intervals.
• NETWORK section tweaks how and what is captured on the network and the individual layers.
• DNS section lets you do filtering and modifications on the DNS message, along with pattern
matching on the domain names.
• Lastly, PLUGINS section gives you an overview on how dnscap can be extended by plugins and which
plugins are bundled.
The only required options are -g and -w, at least one of them must be supplied to run.
If neither -r or -i is used then the default is to capture on the first or all interfaces (depends on
system, see -i for more information).
GENERIC-? Display short form help text about command line options and exit.
-V Print version and exit.
-d Tells a verbose story of options and patterns chosen, files opened, and so on. Multiple -d
options can be given to increase verbosity and frequency of trace messages.
RUNTIME-y Enable Linux seccomp-bpf sandbox if available (compile option).
-b Run in background as daemon and drop privileges, using set*uid(), set*gid() functions, unless
options -N is given or only reading from files.
-opid_file=...
Specify the file to write the PID to when running as a daemon (default none).
-ouser=...
Specify the user to drop privileges to (default nobody).
-ogroup=...
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).
-Bdatetime
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.
-Edatetime
Stop collecting at a specific time. datetime should be specified as "YYYY-MM-DD HH:MM:SS".
dnscap will exit when it sees a packet (live or offline pcap(3) file) with timestamp greater or
equal to it.
INPUT-rfile
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.
-iif 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.
-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.
-opcap_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.
-ouse_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 -odefrag_ipv4=yes and -odefrag_ipv6=yes),
TCP reassembly (see -oreassemble_tcp=yes) and parsing ongoing TCP sessions (see -oparse_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.
-odump_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.
-wbase
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.
-Wsuffix
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).
-tlim 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.
-clim 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 notused (see below) or the
packet dump file is standard output, or if -g is used, then dnscap will exit after reaching the
limit.
-Clim Set a size limit, measured in bytes. When writing to a file, the packet dump file will be closed
when lim number of bytes (or larger then) has been written. If option -k is notused 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.
-kcmd 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-Ustr Append "and str" to the BPF/pcap filter.
-obpf_hosts_apply_all=yes
This changes the BPF generation so that any host restriction will come after ICMP, fragments,
ports or DNS section to allow it to apply for ICMP and fragments also. The default behavior is to
only apply hosts to the ports or DNS section.
-6 Used to suppress the use of packet filter patterns that cause problems when processing IPv6
packets. As of version 2.0.0 this option is deprecated and filters have been reworked to only
match IPv4 packets, IPv6 filtering are processed at a higher level.
-f Selects fragments (which could include unrelated flows since fragments do not contain port
numbers), and includes fragments in the binary output. Necessary if you intend to do IP
Reassembly. Note that all fragments will be collected, not just those using the DNS port number,
since fragments don't have port numbers. Beware this option if you also handle a lot of NFS
traffic.
-T Selects TCP packets. SYN, FIN, and RST packets are collected if they pass the layer 2, port, and
host filters (although hosts need not be in the correct direction); they are not tested against
filter options that require a DNS header such as -m, -s, or -e. All DNS messages in the stream is
captured if it passes all filter options.
Each TCP packet with payload will be tagged as DNS, unless -oreassemble_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 -oparse_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 -oallow_reset_tcpstate=yes may allow dnscap to recover from these
scenarios.
-I Select ICMP and ICMPv6 packets.
-lvlan
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.
-Lvlan
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.
-uport
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.
-odefrag_ipv4=yes-odefrag_ipv6=yes
Enable IPv4/IPv6 defragmentation in pcap-thread, requires -ouse_layers=yes.
When enabled, the following options are also available:
-omax_ipv4_fragments=num
Set the maximum fragmented IPv4 packets (num) to track for reassembly, if the limit is
reach then all other fragmented packets will not be reassembled.
-omax_ipv4_fragments_per_packet=num
Set the maximum fragments (num) per tracked IPv4 packet to keep for reassembly.
-omax_ipv6_fragments=num
Set the maximum fragmented IPv6 packets (num) to track for reassembly, if the limit is
reach then all other fragmented packets will not be reassembled.
-omax_ipv6_fragments_per_packet=num
Set the maximum fragments (num) per tracked IPv6 packet to keep for reassembly.
-oparse_ongoing_tcp=yesdnscap 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.
-oallow_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.
-oreassemble_tcp=yes
Enable reassembly of TCP packets, this will not parse each packet as an own DNS message but will
store TCP segments until they can be reassembled. It will expect the DNS message length to come
first and then wait for the full length of data to arrive until passing to outputs and plugins.
Since the number of saved segments are limited and fixed, if the TCP steam becomes corrupt then
processing may stop. Recovering from this can be done by enabling which will reset state and free
all saved segments to try and start over.
-oreassemble_tcp_faultreset=num
This controls the number of faults (num) that can happen before the state is reseted (as described
above), faults are if the segments buffer are full or if the sequence is outside the TCP window.
The default is zero which means it will reset the state as soon as the segment buffer is full.
-oreassemble_tcp_bfbparsedns=yes
Enable an additional layer (experimental) of reassembly that uses LDNS to parse the payload before
accepting it. If the DNS is invalid it will move 2 bytes within the payload and treat it as a new
payload, taking the DNS length again and restart the process.
DNS-m[qun]
Capture only messages of designated types; query, update, and notify). Multiple types can be
given at the same time, for example -mqn will select query and notify messages. Multiple -m can
not be used to specify multiple types. Default is query.
-e[nytfsxir]
Among responses, consider nonzero DNS TC or DNS RCODE to indicate an error, and select only
responses which do not have (n), or which have (y), these conditions. The default is to only
select non-errors among responses. If both non-error and error responses are to be selected,
specify both the n and y options here.
To be more specific, use one or more condition-specific options, as follows:
n no error
y some error
t truncated response (TC bit)
f format error (rcode 1)
s server failure (rcode 2)
x no such name (rcode 3)
i not implemented (rcode 4)
r refusal (rcode 5)
-hir Hide initiator or responder of each captured transaction. Hiding an initiator means wiping out
the address and port number. Hiding a responder means to wipe out the address only. This wiping
occurs on the copy of the packet sent to the pcap(3) dump output, and both the IP and UDP
checksums will be recomputed in that case.
-sir Select messages which are initiations and/or responses. This is done by checking the DNS header
flag QR and source/destination port against the DNS port (see -u). Default is both.
-ahost
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.
-zhost
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.
-Ahost
Capture only transactions NOT having these initiators.
-Zhost
Capture only transactions NOT having these responders.
-Yhost
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.
-xpat 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.
-Xpat 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.
-qnum|str
Only select DNS messages where QTYPE matches the specified type. Can not be used together with
-Q.
-Qnum|str
Only select DNS messages where QTYPE does not matches the specified type. Can not be used
together with -q.
PLUGINS-P/path/to/plugin.so...
Load and use the specified plugin, full path to plugin must be supplied. Any options given after
this are sent to the plugin.
Once a double dash, "--", is encountered after -P, processing of the command line options will go
back to dnscap.
Using this you can chain and use multiple plugins at once:
-P /path/to/plugin_one.so -a opt -- -P /path/to/plugin_two.so -b opt
To show the plugins option help, run it with -?:
-P /path/to/plugin_one.so -?
Plugins are loaded, executed and given the packets to process in the order given on command line.
These bundled plugins are installed in /usr/lib/x86_64-linux-gnu/dnscap:
anonaes128.so
Anonymize IP addresses using AES128.
anonmask.so
Pseudo-anonymize IP addresses by masking them.
cryptopan.so
Anonymize IP addresses using an extension to Crypto-PAn (College of Computing, Georgia
Tech) made by David Stott (Lucent).
cryptopant.so
Anonymize IP addresses using cryptopANT, a different implementation of Crypto-PAn made by
the ANT project at USC/ISI.
eventlog.so
Output DNS activity as log events, including IP addresses from query responses.
ipcrypt.so
Anonymize IP addresses using ipcrypt create by Jean-Philippe Aumasson.
pcapdump.so
Dump DNS into a PCAP with some filtering options.
royparse.so
Splits a PCAP into two streams; queries in PCAP format and responses in ASCII format.
rssm.so
Root Server Scaling Measurement plugin.
rzkeychange.so
RFC8145 key tag signal collection and reporting plugin.
txtout.so
Dump DNS as one-line text.
Install Now
PNG Icons
Emojis