Sphinx: Add mention of dnstap as possible input format to documentation

parent cd256323
Pipeline #75513 passed with stage
in 3 minutes and 18 seconds
......@@ -50,6 +50,10 @@ and destination IP addresses, source and destination ports, and
transport protocol. The packet is then assigned to one of the RX queues
based on this hash value.
Unix sockets for `dnstap <https://dnstap.info/>`_ input are uniformly
distributed among available worker threads and all traffic from a given
socket is then processed by its assigned worker thread.
Backends
========
......
......@@ -24,6 +24,7 @@ DNS Probe uses local file in YAML format to load configuration at startup. Its s
+--rw <instance-id>?
+--rw coremask? <uint64>
+--rw dnstap-socket-list?* <string>
+--rw dns-ports?* <uint16>
+--rw export
| +--rw cdns-blocks-per-file? <uint64>
......@@ -157,6 +158,17 @@ Bitmask indicating which CPU cores should DNS Probe use. At least 3 CPU cores ar
The default value of 7 indicates that DNS Probe should use the first 3 CPU cores with IDs of 0, 1 and 2.
.. _dnstap-socket-list:
dnstap-socket-list
^^^^^^^^^^^^^^^^^^
:data node: ``<instance-id>/dnstap-socket-list``
:default: empty
List of unix sockets to process dnstap data from in addition to sockets passed with '-d'
command line parameter.
.. _dns-ports:
dns-ports
......
......@@ -89,6 +89,8 @@ distribution repositories:
- libpcap
- yaml-cpp
- OpenSSL (libssl-dev)
- fstrm
- Protocol Buffers (libprotobuf-dev, protobuf-compiler)
- DPDK (only for DPDK version)
Optionally, to build this user documentation (``make doc``) or manual pages (``make man``)
......@@ -164,6 +166,7 @@ DNS Probe
# For disabling DPDK BACKEND remove `-DDPDK_BACKEND=On`
# For building without IP anonymization support add `-DPROBE_CRYPTOPANT=Off`
# For building without support for one of the export formats add `-DPROBE_PARQUET=Off` or `-DPROBE_CDNS=Off`
# For building without support for dnstap input add `-DPROBE_DNSTAP=Off`
cmake <GIT_REPO> -DCMAKE_INSTALL_PREFIX="$DEP_DIR" -DCMAKE_BUILD_TYPE=Release -DAF_PACKET_BACKEND=On -DDPDK_BACKEND=On -DBUILD_COLLECTOR=On
make -j
make install
......@@ -4,7 +4,7 @@ Overview
DNS Probe is a high-speed DNS monitoring software developed as a part of the `ADAM <https://adam.nic.cz/en/>`_ project by CZ.NIC Laboratories in cooperation with Brno University of Technology, Faculty of Information Technology.
DNS Probe is able to extract DNS packets either from live network traffic or `pcap <https://en.wikipedia.org/wiki/Pcap>`_ traces, match client queries with the corresponding server responses and export consolidated records about individual DNS transactions.
DNS Probe is able to extract DNS packets from live network traffic, `pcap <https://en.wikipedia.org/wiki/Pcap>`_ traces or `dnstap <https://dnstap.info/>`_ data supplied by unix sockets, match client queries with the corresponding server responses and export consolidated records about individual DNS transactions.
DNS Probe is typically deployed together with a DNS server (autoritative or recursive), capturing and processing the traffic received and sent by the server.
......
......@@ -15,6 +15,13 @@ For changes in software see `version descriptions <https://gitlab.nic.cz/adam/dn
- Edition
- Segment
- Change description
* - **0.7.1**
- **1.0**
- :doc:`Architecture <Architecture>`, :doc:`Configuration <Configuration>`,
:doc:`Installation <Installation>`, :doc:`Overview <Overview>`,
:doc:`Default YAML file <YAMLfile>`, :doc:`AF manual pages <manpages/dns-probe-af>`,
:doc:`DPDK manual pages <manpages/dns-probe-dpdk>`
- Add dnstap as another input data format
* - **0.7**
- **1.0**
- :doc:`Architecture <Architecture>`, :doc:`Configuration <Configuration>`,
......
......@@ -9,7 +9,7 @@ It is also included in the project repository (`data-model/dns-probe.yml <https:
.. code-block:: yaml
# Last revision: 2020-09-22
# Last revision: 2021-01-27
#
# Default instance configuration.
# This configuration is always loaded before other configuration specified by given instance's ID.
......@@ -24,6 +24,10 @@ It is also included in the project repository (`data-model/dns-probe.yml <https:
# List of PCAPs to process in addition to PCAPs passed with '-p' command line parameter.
pcap-list: []
# List of unix sockets to process dnstap data from in addition to sockets passed with '-d'
# command line parameter.
dnstap-socket-list: []
# Indicates RAW PCAPs as input in 'pcap-list' or from command line with '-p' parameter.
# Might get overriden by '-r' command line parameter.
# MUST be set to 'false' if 'interface-list' or '-i' command line parameter are used.
......
......@@ -8,14 +8,14 @@ dns-probe-af
Synopsis
--------
:program:`dns-probe-af` [-i *interface* | -p *pcap* [-r]] [-l *logfile*] [-n *instance*] [-c *config_file*] [-h]
:program:`dns-probe-af` [-i *interface* | -p *pcap* [-r] | -d *socket*] [-l *logfile*] [-n *instance*] [-c *config_file*] [-h]
Description
-----------
:program:`dns-probe-af` is a network traffic probe that captures DNS queries and corresponding responses and exports them as configurable records about individual DNS transactions.
:program:`dns-probe-af` can either listen on an interface or read packets from a PCAP file. The :option:`-i` and :option:`-p` options are mutually incompatible but either of them can be used repeatedly.
:program:`dns-probe-af` can either listen on an interface or read packets from a PCAP file or read dnstap data from a unix socket. The :option:`-i`, :option:`-p` and :option:`-d` options are mutually incompatible but either of them can be used repeatedly.
Depending on the configuration, :program:`dns-probe-af` exports the transaction records in either Parquet or C-DNS format.
......@@ -34,6 +34,10 @@ Options
Indicates raw PCAP format.
.. option:: -d socket
Read dnstap input from given unix socket.
.. option:: -l logfile
Write logging messages to *logfile* instead of standard output.
......
......@@ -8,14 +8,14 @@ dns-probe-dpdk
Synopsis
--------
:program:`dns-probe-dpdk` [-i *interface* | -p *pcap* [-r]] [-l *logfile*] [-n *instance*] [-c *config_file*] [-h]
:program:`dns-probe-dpdk` [-i *interface* | -p *pcap* [-r] | -d *socket*] [-l *logfile*] [-n *instance*] [-c *config_file*] [-h]
Description
-----------
:program:`dns-probe-dpdk` is a network traffic probe that captures DNS queries and corresponding responses and exports them as configurable records about individual DNS transactions.
:program:`dns-probe-dpdk` can either listen on an interface or read packets from a PCAP file. The :option:`-i` and :option:`-p` options are mutually incompatible but either of them can be used repeatedly.
:program:`dns-probe-dpdk` can either listen on an interface or read packets from a PCAP file or read dnstap data from a unix socket. The :option:`-i`, :option:`-p` and :option:`-d` options are mutually incompatible but either of them can be used repeatedly.
Depending on the configuration, :program:`dns-probe-dpdk` exports the transaction records in either Parquet or C-DNS format.
......@@ -34,6 +34,10 @@ Options
Indicates raw PCAP format.
.. option:: -d socket
Read dnstap input from given unix socket.
.. option:: -l logfile
Write logging messages to *logfile* instead of standard output.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment