Microsoft DNS Server (xm_msdns)

This module provides support for parsing Windows DNS Server logs. An InputType is registered using the name of the extension module instance. For special cases, the parse_msdns() procedure can be used instead for parsing individual events or strings.

The xm_msdns module does not support the detailed format enabled via the Details option in the DNS Server Debug Logging configuration. NXLog Agent could be configured to parse this format with the xm_multiline module.

Configuration

The xm_msdns module accepts the following directives in addition to the common module directives.

Optional directives

DateFormat

This optional directive allows you to define the format of the date field when parsing DNS Server logs. The directive’s argument must be a format string compatible with the C strptime(3) function. This directive works similarly to the global DateFormat directive, and if not specified, the default format [D|DD]/[M|MM]/YYYY [H|HH]:MM:SS [AM|PM] is used.

EventLine

This boolean directive specifies EVENT lines in the input should be parsed. If set to FALSE, EVENT lines will be discarded. The default is TRUE.

NoteLine

This boolean directive specifies that Note: lines in the input should be parsed. If set to FALSE, Note: lines will be discarded. The default is TRUE.

PacketLine

This boolean directive specifies that PACKET lines in the input should be parsed. If set to FALSE, PACKET lines will be discarded. The default is TRUE.

Procedures

The following procedures are exported by xm_msdns.

parse_msdns();

Parse the $raw_event field and populate the DNS log fields.

parse_msdns(string source);

Parse the given string and populate the DNS log fields.

Fields

The following fields are used by xm_msdns.

$raw_event (type: string)

The raw string from the event.

$AuthoritativeAnswer (type: boolean)

For PACKET events, set to TRUE if the "Authoritative Answer" flag is set.

$Context (type: string)

The event type, one of PACKET, EVENT, or Note.

$EventDescription (type: string)

The description for EVENT type events.

$EventTime (type: datetime)

The timestamp of the event.

$FlagsHex (type: string)

The flags in hexadecimal, for PACKET events only.

$InternalPacketIdentifier (type: string)

For PACKET events, an internal ID corresponding with the event.

$Message (type: string)

The event message in certain PACKET events that include a free-form message contrary to the normal Debug Logging format. In particular, this is for PACKET events that have a message such as Response packet 000001D1B80209E0 does not match any outstanding query.

$Note (type: string)

For "Note" type events, this field contains the note.

$Opcode (type: string)

One of Standard Query, Notify, Update, and Unknown; for PACKET events.

$ParseFailure (type: string)

The remaining unparsed portion of a log message which does not match an expected format.

$Protocol (type: string)

The protocol being used; one of TCP or UDP. This field is added for the PACKET type only.

$QueryResponseIndicator (type: string)

This field indicates whether a PACKET event corresponds with a query or a response, and is set to either Query or Response.

$QuestionName (type: string)

The lookup value for PACKET; for example example.com.

$QuestionType (type: string)

The lookup type for PACKET events; for example, A or AAAA.

$RecursionAvailable (type: boolean)

For PACKET events, set to TRUE if the "Recursion Available" flag is set.

$RecursionDesired (type: boolean)

For PACKET events, set to TRUE if the "Recursion Desired" flag is set.

$RemoteIP (type: string)

The IP address of the requesting client, for PACKET events only.

$ResponseCode (type: string)

For PACKET events, the DNS Server response code.

$SendReceiveIndicator (type: string)

This field indicates the direction for a PACKET event, and is set to either Snd or Rcv.

$ThreadId (type: string)

The ID of the thread that produced the event.

$TruncatedResponse (type: boolean)

For PACKET events, set to TRUE if the "Truncated Response" flag is set.

$Xid (type: string)

For PACKET events, the hexadecimal XID.

Examples

Example 1. Parsing DNS logs With InputType

In this configuration, the DNS log file at C:\dns.log is parsed using the InputType provided by the xm_msdns module. Any Note: lines in the input are discarded (the NoteLine directive is set to FALSE).

nxlog.conf
<Extension dns_parser>
    Module      xm_msdns
    EventLine   TRUE
    PacketLine  TRUE
    NoteLine    FALSE
</Extension>

<Input in>
    Module      im_file
    File        'modules/extension/msdns/xm_msdns1.in'
    InputType   dns_parser
</Input>
Example 2. Parsing DNS logs with parse_msdns()

For cases where parsing via InputType is not possible, individual events can be parsed with the parse_msdns() procedure.

nxlog.conf
<Extension dns_parser>
    Module  xm_msdns
</Extension>

<Input in>
    Module  im_file
    File    'modules/extension/msdns/xm_msdns1.out'
    Exec    dns_parser->parse_msdns();
</Input>