FlowMon DNS parser plugin v1.0.0 for flowmon-exporter 4.x
Welcome to the documentation page of FlowMon DNS parser plugin.
Plugin is designed for FlowMon as process type of plugin.*
It parses the DNS data from packets on input and outputs them for next processing or export plugin type.
*Plugin type was changed with the version of flowmonexp from input-filter (flowmonexp 4) to process (flowmonexp 3).
How to run plugin
Plugin file must be loaded in flowmonexp, which is required to be installed.
Plugin can be loaded with parameter
-X, then specified as process plugin type by parameter
-P.
For more information please read the instructions for flowmonexp.
For plugin compilation type "make".
For plugin compilation with option of extended getters (parameter "all") compile with "make parse_all" or "make PFLAG=-DPARSE_ALL"
Example (using ip6tun input and process plugin)
flowmonexp -X /home/local/user/process-dns.so -I input-ip6tun:hanic=255 -P process-ip6tun -P process-dns -E null
| Parameter |
Options |
Description |
| debug |
y/n |
Switch on/off debug mode (default: same as flowmonexp) |
| verbose |
y/n |
Switch on/off verbose mode (default: same as flowmonexp) |
| all |
y/n |
*Switch on/off parsing of ALL of present DNS fields |
*Only available when compiled with "make PFLAG=-DPARSE_ALL"
Example of plugin parameter use
flowmonexp -X /home/local/user/process-dns.so -I input-ip6tun:hanic=255 -P process-dns:debug=y,all=y -E null
These constants directly influence the size of names and rdata beign parsed, along with memory requirements.
Constants can be found in the process-dns.h source file included.
| Constant |
Default value |
Description |
| LEVEL_SIZE |
128* |
Maximum length of 1 level in domain name beign parsed. |
| NAME_SIZE |
128* |
Maximum length of full domain name beign parsed. (Used for hostnames stored in RDATA too.) |
| RESPONSE_SIZE |
256* |
Maximum length of RDATA formatted output. |
*Longer strings are automatically truncated.
Doxygen documentation can be generated by typing following command in source directory of plugin.
$ make doc
Plugin is able to output two sets of DNS data based on the parameter "all" (see section "Parameters").
In default, the parameter "all" is set to off (all=n).
For default output the fields are limited based on the importance of data for monitoring.
Table of output data (default)
| DNS data field name |
Type |
Description |
| DNS_ID |
uint16_t |
Identification. Used to match request/reply packets. |
| DNS_ANSWERS |
uint16_t |
Total Answer RRs. Number of entries in the answer resource record list that were returned. |
| DNS_RCODE |
uint8_t |
Return code. Contains information about the status of a DNS operation. |
| DNS_NAME |
char[40] |
Name. FQDN of the node in the tree extracted from Query (QNAME). |
| DNS_QTYPE |
uint16_t |
Query Type. Type of record request in numeric form from Query. |
| DNS_CLASS |
uint16_t |
Class code. Class code from Query. |
| DNS_RR_TTL |
uint32_t |
Time to live. Count of seconds that the RR stays valid from Answer. |
| DNS_RLENGTH |
uint16_t |
Response data length. Length of RDATA field from Answer. |
| DNS_RDATA |
var char |
Response data. Additional RR-specific data from Answer. * |
| DNS_PSIZE |
uint16_t |
Requested UDP payload size. Additional section. |
| DNS_DO |
uint8_t |
DNSSEC OK bit. Additional section. |
* RDATA formatting is implemented for some base DNS RR Types for human-readable output.
See the list of actually implemented formatting of DNS RR Types in section below.
Table of output data (option all=y)
With this option output also includes the default data fields.
| DNS data name |
Type |
Description |
| DNS_FLAGS |
uint16_t |
Flags. Whole set of DNS flags together in one variable. |
| DNS_QUESTIONS |
uint16_t |
Total Questions. Number of entries in the question list that were returned. |
| DNS_AUTHORITY |
uint16_t |
Total Authority RRs. Number of entries in the authority resource record list that were returned. |
| DNS_ADDITIONAL |
uint16_t |
Total Additional RRs. Number of entries in the additional resource record list that were returned. |
| DNS_QR |
uint8_t |
Query/Response. indicates if the packet is query or response. |
| DNS_OPCODE |
uint8_t |
Operation code. Commands given to the DNS server that tell it to do some action |
| DNS_AA |
char |
Authoritative Answer. Specifies that the responding name server is an authority for the domain name in question section. |
| DNS_TC |
char |
Truncated. Indicates that only the first 512 bytes of the reply was returned. |
| DNS_RD |
char |
Recursion Desired. May be set in a query and is copied into the response. If set, the name server is directed to pursue the query recursively. Recursive query support is optional. |
| DNS_RA |
char |
Recursion Available. Indicates if recursive query support is available in the name server. |
| DNS_Z |
char |
Reserved for future use. Must be zero in all queries and responses. |
| DNS_AD |
char |
Authenticated data. Indicates in a response that all data included in the answer and authority sections of the response have been authenticated by the server according to the policies of that server. |
| DNS_CD |
char |
Checking Disabled. Indicates in a query that non-verified data is acceptable to the resolver sending the query. |
RDATA Formatting
The RDATA formatting is implemented for the DNS RR Types listed in the table below, along with the output format.
RR Types with structured data (contain more variables) have the variables listed in the order divided by separator.
The universal separator that was chosen is white space " ".
The length of RDATA output for formatted types is length of formatted string for the output.
Output of all other RR Types is RAW.
The length of RDATA output for other types is RLENGTH.
| DNS RR Type |
Output format |
| A |
<IPv4 address in dotted decimal representation> |
| AAAA |
<IPv6 address represented as 8 groups of 4 hexadecimal digits separated by colons> |
| NS |
<parsed hostname> |
| CNAME |
<parsed hostname> |
| PTR |
<parsed hostname> |
| DNAME |
<parsed hostname> |
| SOA |
<mname> <rname> <serial> <refresh> <retry> <expire> <minimum ttl> |
| SRV |
<service> <protocol> <name> <target> <priority> <weight> <port> |
| MX |
<priority> <mx hostname> |
| TXT |
<txt string> |
| MINFO |
<rmailbx> <emailbx> |
| HINFO |
<txt string> |
| ISDN |
<txt string> |
| DS |
<keytag> <algorithm> <digest> <publickey> |
| RRSIG |
<type_covered> <algorithm> <labels> <original_ttl> <signature_exp> <signature_inc> <keytag> <signer_signature> |
| DNSKEY |
<flags> <protocol> <algorithm> <publickey> |
| RAW |
<raw data> |
Additional information
If number of ANSWERS in DNS packet is more than 1, first one is parsed and other are skipped.
Whole Authority section of DNS packet is mommentarily being skipped.
Additional section is only being parsed if it contains OPT record type.
Michal Kováčik <ikovacik@fit.vutbr.cz>
Copyright (C) 2014 CESNET
LICENSE TERMS
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 Company nor the names of its contributors
may be used to endorse or promote products derived from this
software without specific prior written permission.
ALTERNATIVELY, provided that this notice is retained in full, this
product may be distributed under the terms of the GNU General Public
License (GPL) version 2 or later, in which case the provisions
of the GPL apply INSTEAD OF those given above.
This software is provided ``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 company 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.