FlowMon DNS parser plugin v1.0.0 for flowmon-exporter 4.x



Introduction

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 

Parameters

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 

Source code important constants

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 doc

Doxygen documentation can be generated by typing following command in source directory of plugin.
 $ make doc

Plugin output

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.

Author

Michal Kováčik     <ikovacik@fit.vutbr.cz>

License

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.