chore(docs): regenerate man pages (#7971)

man/coredns-dnstap.7

@@ -1,5 +1,5 @@
 .\" Generated by Mmark Markdown Processer - mmark.miek.nl
-.TH "COREDNS-DNSTAP" 7 "March 2021" "CoreDNS" "CoreDNS Plugins"
+.TH "COREDNS-DNSTAP" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
 
 .SH "NAME"
 .PP
@@ -20,7 +20,12 @@ Every message is sent to the socket as soon as it comes in, the \fIdnstap\fP plu
 .RS
 
 .nf
-dnstap SOCKET [full]
+dnstap SOCKET [full] [writebuffer] [queue] {
+  [identity IDENTITY]
+  [version VERSION]
+  [extra EXTRA]
+  [skipverify]
+}
 
 .fi
 .RE
@@ -29,6 +34,19 @@ dnstap SOCKET [full]
 \fBSOCKET\fP is the socket (path) supplied to the dnstap command line tool.
 .IP \(bu 4
 \fB\fCfull\fR to include the wire-format DNS message.
+.IP \(bu 4
+\fBwritebuffer\fP sets the TCP write buffer multiplier in MiB. Valid range: [1, 1024].
+.IP \(bu 4
+\fBqueue\fP sets the queue multiplier, applied to 10,000 messages. Valid range: [1, 4096].
+.IP \(bu 4
+\fBIDENTITY\fP to override the identity of the server. Defaults to the hostname.
+.IP \(bu 4
+\fBVERSION\fP to override the version field. Defaults to the CoreDNS version.
+.IP \(bu 4
+\fBEXTRA\fP to define "extra" field in dnstap payload, metadata
+\[la]../metadata/\[ra] replacement available here.
+.IP \(bu 4
+\fB\fCskipverify\fR to skip tls verification during connection. Default to be secure
 
 
 .SH "EXAMPLES"
@@ -44,6 +62,18 @@ dnstap /tmp/dnstap.sock
 .fi
 .RE
 
+.PP
+Log information about client requests and responses with a custom TCP write buffer (1024 MiB) and queue capacity (2048 x 10000).
+
+.PP
+.RS
+
+.nf
+dnstap /tmp/dnstap.sock full 1024 2048
+
+.fi
+.RE
+
 .PP
 Log information including the wire-format DNS message about client requests and responses to \fI/tmp/dnstap.sock\fP.
 
@@ -68,6 +98,78 @@ dnstap tcp://127.0.0.1:6000 full
 .fi
 .RE
 
+.PP
+Log to a remote endpoint by FQDN.
+
+.PP
+.RS
+
+.nf
+dnstap tcp://example.com:6000 full
+
+.fi
+.RE
+
+.PP
+Log to a socket, overriding the default identity and version.
+
+.PP
+.RS
+
+.nf
+dnstap /tmp/dnstap.sock {
+  identity my\-dns\-server1
+  version MyDNSServer\-1.2.3
+}
+
+.fi
+.RE
+
+.PP
+Log to a socket, customize the "extra" field in dnstap payload. You may use metadata provided by other plugins in the extra field.
+
+.PP
+.RS
+
+.nf
+forward . 8.8.8.8
+metadata
+dnstap /tmp/dnstap.sock {
+  extra "upstream: {/forward/upstream}"
+}
+
+.fi
+.RE
+
+.PP
+Log to a remote TLS endpoint.
+
+.PP
+.RS
+
+.nf
+dnstap tls://127.0.0.1:6000 full {
+  skipverify
+}
+
+.fi
+.RE
+
+.PP
+You can use \fIdnstap\fP more than once to define multiple taps. The following logs information including the
+wire-format DNS message about client requests and responses to \fI/tmp/dnstap.sock\fP,
+and also sends client requests and responses without wire-format DNS messages to a remote FQDN.
+
+.PP
+.RS
+
+.nf
+dnstap /tmp/dnstap.sock full
+dnstap tcp://example.com:6000
+
+.fi
+.RE
+
 .SH "COMMAND LINE TOOL"
 .PP
 Dnstap has a command line tool that can be used to inspect the logging. The tool can be found
@@ -112,16 +214,18 @@ $ dnstap \-l 127.0.0.1:6000
 
 .SH "USING DNSTAP IN YOUR PLUGIN"
 .PP
-In your setup function, check to see if the \fIdnstap\fP plugin is loaded:
+In your setup function, collect and store a list of all \fIdnstap\fP plugins loaded in the config:
 
 .PP
 .RS
 
 .nf
+x :=  \&ExamplePlugin{}
+
 c.OnStartup(func() error {
     if taph := dnsserver.GetConfig(c).Handler("dnstap"); taph != nil {
-        if tapPlugin, ok := taph.(dnstap.Dnstap); ok {
-            f.tapPlugin = \&tapPlugin
+        for tapPlugin, ok := taph.(*dnstap.Dnstap); ok; tapPlugin, ok = tapPlugin.Next.(*dnstap.Dnstap) {
+            x.tapPlugins = append(x.tapPlugins, tapPlugin)
         }
     }
     return nil
@@ -137,8 +241,15 @@ And then in your plugin:
 .RS
 
 .nf
-func (x RandomPlugin) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error) {
-    if tapPlugin != nil {
+import (
+  "github.com/coredns/coredns/plugin/dnstap/msg"
+  "github.com/coredns/coredns/request"
+
+  tap "github.com/dnstap/golang\-dnstap"
+)
+
+func (x ExamplePlugin) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error) {
+    for \_, tapPlugin := range x.tapPlugins {
         q := new(msg.Msg)
         msg.SetQueryTime(q, time.Now())
         msg.SetQueryAddress(q, w.RemoteAddr())
@@ -147,7 +258,12 @@ func (x RandomPlugin) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns
             q.QueryMessage = buf
         }
         msg.SetType(q, tap.Message\_CLIENT\_QUERY)
+        
+        // if no metadata interpretation is needed, just send the message
         tapPlugin.TapMessage(q)
+
+        // OR: to interpret the metadata in "extra" field, give more context info
+        tapPlugin.TapMessageWithMetadata(ctx, q, request.Request{W: w, Req: query})
     }
     // ...
 }