dnstap

README

dnstap

Name

dnstap - enables logging to dnstap.

Description

dnstap is a flexible, structured binary log format for DNS software; see https://dnstap.info. With this plugin you make CoreDNS output dnstap logging.

Every message is sent to the socket as soon as it comes in, the dnstap plugin has a buffer of 10000 messages, above that number dnstap messages will be dropped (this is logged).

Syntax

dnstap SOCKET [full]

• SOCKET is the socket (path) supplied to the dnstap command line tool.
• full to include the wire-format DNS message.

Examples

Log information about client requests and responses to /tmp/dnstap.sock.

dnstap /tmp/dnstap.sock

Log information including the wire-format DNS message about client requests and responses to /tmp/dnstap.sock.

dnstap unix:///tmp/dnstap.sock full

Log to a remote endpoint.

dnstap tcp://127.0.0.1:6000 full

Command Line Tool

Dnstap has a command line tool that can be used to inspect the logging. The tool can be found at Github: https://github.com/dnstap/golang-dnstap. It's written in Go.

The following command listens on the given socket and decodes messages to stdout.

$ dnstap -u /tmp/dnstap.sock

The following command listens on the given socket and saves message payloads to a binary dnstap-format log file.

$ dnstap -u /tmp/dnstap.sock -w /tmp/test.dnstap

Listen for dnstap messages on port 6000.

$ dnstap -l 127.0.0.1:6000

Using Dnstap in your plugin

In your setup function, check to see if the dnstap plugin is loaded:

c.OnStartup(func() error {
    if taph := dnsserver.GetConfig(c).Handler("dnstap"); taph != nil {
        if tapPlugin, ok := taph.(dnstap.Dnstap); ok {
            f.tapPlugin = &tapPlugin
        }
    }
    return nil
})

And then in your plugin:

func (x RandomPlugin) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error) {
    if tapPlugin != nil {
        q := new(msg.Msg)
        msg.SetQueryTime(q, time.Now())
        msg.SetQueryAddress(q, w.RemoteAddr())
        if tapPlugin.IncludeRawMessage {
            buf, _ := r.Pack() // r has been seen packed/unpacked before, this should not fail
            q.QueryMessage = buf
        }
        msg.SetType(q, tap.Message_CLIENT_QUERY)
        tapPlugin.TapMessage(q)
    }
    // ...
}

See Also

The website dnstap.info has info on the dnstap protocol. The forward plugin's dnstap.go uses dnstap to tap messages sent to an upstream.

Documentation

Index

• type Dnstap
  • func (h Dnstap) Name() string
  • func (h Dnstap) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
  • func (h Dnstap) TapMessage(m *tap.Message)
• type ResponseWriter
  • func (w *ResponseWriter) WriteMsg(resp *dns.Msg) error

Types

type Dnstap

type Dnstap struct {
	Next plugin.Handler

	// IncludeRawMessage will include the raw DNS message into the dnstap messages if true.
	IncludeRawMessage bool
	// contains filtered or unexported fields
}

Dnstap is the dnstap handler.

func (Dnstap) Name

func (h Dnstap) Name() string

Name implements the plugin.Plugin interface.

func (Dnstap) ServeDNS

func (h Dnstap) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS logs the client query and response to dnstap and passes the dnstap Context.

func (Dnstap) TapMessage

func (h Dnstap) TapMessage(m *tap.Message)

TapMessage sends the message m to the dnstap interface.

type ResponseWriter

type ResponseWriter struct {
	dns.ResponseWriter
	Dnstap
	// contains filtered or unexported fields
}

ResponseWriter captures the client response and logs the query to dnstap.

func (*ResponseWriter) WriteMsg

func (w *ResponseWriter) WriteMsg(resp *dns.Msg) error

WriteMsg writes back the response to the client and THEN works on logging the request and response to dnstap.