mirror of
https://github.com/coredns/coredns.git
synced 2026-10-09 12:05:22 -04:00
311a9915da
The `tools.ietf.org` site now redirects to `www.rfc-editor.org`. * Update various URLs to the new site. * Make links to `www.rfc-editor.org` consistent. Signed-off-by: SuperQ <superq@gmail.com>
330 lines
7.9 KiB
Groff
330 lines
7.9 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-LOG" 7 "October 2026" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIlog\fP - enables query logging to standard output.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
By just using \fIlog\fP you dump all queries (and parts for the reply) on standard output. Options exist
|
|
to tweak the output a little. Note that for busy servers logging will incur a performance hit.
|
|
|
|
.PP
|
|
Enabling or disabling the \fIlog\fP plugin only affects the query logging, any other logging from
|
|
CoreDNS will show up regardless.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
log
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
With no arguments, a query log entry is written to \fIstdout\fP in the common log format for all requests.
|
|
Or if you want/need slightly more control:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
log [NAMES...] [FORMAT]
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fB\fCNAMES\fR is the name list to match in order to be logged
|
|
.IP \(bu 4
|
|
\fB\fCFORMAT\fR is the log format to use (default is Common Log Format), \fB\fC{common}\fR is used as a shortcut
|
|
for the Common Log Format. You can also use \fB\fC{combined}\fR for a format that adds the query opcode
|
|
\fB\fC{>opcode}\fR to the Common Log Format.
|
|
|
|
|
|
.PP
|
|
You can further specify the classes of responses that get logged:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
log [NAMES...] [FORMAT] {
|
|
class CLASSES...
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fB\fCCLASSES\fR is a space-separated list of classes of responses that should be logged
|
|
|
|
|
|
.PP
|
|
The classes of responses have the following meaning:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCsuccess\fR: successful response
|
|
.IP \(bu 4
|
|
\fB\fCdenial\fR: either NXDOMAIN or nodata responses (Name exists, type does not). A nodata response
|
|
sets the return code to NOERROR.
|
|
.IP \(bu 4
|
|
\fB\fCerror\fR: SERVFAIL, NOTIMP, REFUSED, etc. Anything that indicates the remote server is not willing to
|
|
resolve the request.
|
|
.IP \(bu 4
|
|
\fB\fCall\fR: the default - nothing is specified. Using of this class means that all messages will be
|
|
logged whatever we mix together with "all".
|
|
|
|
|
|
.PP
|
|
If no class is specified, it defaults to \fB\fCall\fR.
|
|
|
|
.SH "LOG FORMAT"
|
|
.PP
|
|
You can specify a custom log format with any placeholder values. Log supports both request and
|
|
response placeholders.
|
|
|
|
.PP
|
|
The following place holders are supported:
|
|
|
|
.IP \(bu 4
|
|
\fB\fC{type}\fR: qtype of the request
|
|
.IP \(bu 4
|
|
\fB\fC{name}\fR: qname of the request
|
|
.IP \(bu 4
|
|
\fB\fC{class}\fR: qclass of the request
|
|
.IP \(bu 4
|
|
\fB\fC{proto}\fR: protocol used (tcp or udp)
|
|
.IP \(bu 4
|
|
\fB\fC{remote}\fR: client's IP address, for IPv6 addresses these are enclosed in brackets: \fB\fC[::1]\fR
|
|
.IP \(bu 4
|
|
\fB\fC{local}\fR: server's IP address, for IPv6 addresses these are enclosed in brackets: \fB\fC[::1]\fR
|
|
.IP \(bu 4
|
|
\fB\fC{size}\fR: request size in bytes
|
|
.IP \(bu 4
|
|
\fB\fC{port}\fR: client's port
|
|
.IP \(bu 4
|
|
\fB\fC{duration}\fR: response duration
|
|
.IP \(bu 4
|
|
\fB\fC{rcode}\fR: response RCODE
|
|
.IP \(bu 4
|
|
\fB\fC{rsize}\fR: raw (uncompressed), response size (a client may receive a smaller response)
|
|
.IP \(bu 4
|
|
\fB\fC{>rflags}\fR: response flags, each set flag will be displayed, e.g. "aa, tc". This includes the qr
|
|
bit as well
|
|
.IP \(bu 4
|
|
\fB\fC{>bufsize}\fR: the EDNS0 buffer size advertised in the query
|
|
.IP \(bu 4
|
|
\fB\fC{>do}\fR: is the EDNS0 DO (DNSSEC OK) bit set in the query
|
|
.IP \(bu 4
|
|
\fB\fC{>id}\fR: query ID
|
|
.IP \(bu 4
|
|
\fB\fC{>opcode}\fR: query OPCODE
|
|
.IP \(bu 4
|
|
\fB\fC{common}\fR: the default Common Log Format.
|
|
.IP \(bu 4
|
|
\fB\fC{combined}\fR: the Common Log Format with the query opcode.
|
|
.IP \(bu 4
|
|
\fB\fC{/LABEL}\fR: any metadata label is accepted as a place holder if it is enclosed between \fB\fC{/\fR and
|
|
\fB\fC}\fR, the place holder will be replaced by the corresponding metadata value or the default value
|
|
\fB\fC-\fR if label is not defined. See the \fImetadata\fP plugin for more information.
|
|
|
|
|
|
.PP
|
|
The default Common Log Format is:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
`{remote}:{port} \- {>id} "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
In the default text mode, each of these logs is output with \fB\fClog.Info\fR, so a typical example looks like this:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
[INFO] [::1]:50759 \- 29008 "A IN example.org. udp 41 false 4096" NOERROR qr,rd,ra,ad 68 0.037990251s
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "JSON OUTPUT"
|
|
.PP
|
|
Start CoreDNS with \fB\fC-log-format=json\fR to select JSON output for the entire process.
|
|
This is a command-line flag, not a Corefile directive. \fB\fC-log-format=text\fR is the default.
|
|
The \fB\fClog\fR plugin's name and response-class filters work identically in both modes.
|
|
|
|
.PP
|
|
Each query produces one JSON record with common fields \fB\fCtime\fR, \fB\fClevel\fR, \fB\fCmsg\fR, and
|
|
\fB\fCplugin\fR (always \fB\fClog\fR for query records), plus these typed fields:
|
|
|
|
.RS
|
|
.TS
|
|
allbox;
|
|
l l l
|
|
l l l .
|
|
\fBField\fP\fB Type\fP\fB Meaning\fP
|
|
\fB\fCclient_ip\fR string Client address, without brackets around IPv6 addresses
|
|
\fB\fCclient_port\fR number Client port
|
|
\fB\fCqname\fR string Lowercase, fully qualified query name, in DNS presentation format
|
|
\fB\fCqtype\fR, \fB\fCqclass\fR string Query type and class, including numeric forms for unknown values
|
|
\fB\fCprotocol\fR string \fB\fCudp\fR or \fB\fCtcp\fR, as for \fB\fC{proto}\fR
|
|
\fB\fCid\fR, \fB\fCopcode\fR number Query ID and opcode
|
|
\fB\fCrequest_size\fR number Request size in bytes, as for \fB\fC{size}\fR
|
|
\fB\fCdnssec_ok\fR boolean Query's DNSSEC OK bit
|
|
\fB\fCbufsize\fR number Effective response buffer size, as for \fB\fC{>bufsize}\fR
|
|
\fB\fCrcode\fR string or null Response RCODE, or null if no DNS response was recorded
|
|
\fB\fCresponse_size\fR number Recorded response size in bytes, as for \fB\fC{rsize}\fR
|
|
\fB\fCduration_seconds\fR number Elapsed handling time in seconds
|
|
.TE
|
|
.RE
|
|
|
|
|
|
.PP
|
|
As in text mode, response sizes describe recorded, uncompressed messages, not
|
|
necessarily the bytes delivered to the client. Deferred errors (such as SERVFAIL)
|
|
use the response CoreDNS will generate after the plugin chain returns. A dropped
|
|
request has \fB\fCrcode: null\fR; it is not logged as a successful response. Raw \fB\fCWrite\fR
|
|
calls contribute to the size but do not provide a decoded response RCODE.
|
|
|
|
.PP
|
|
\fB\fCFORMAT\fR still controls \fB\fCmsg\fR, including custom formats and metadata placeholders.
|
|
It does not replace the JSON schema or define new top-level fields. The DNS fields
|
|
come directly from the request and response, not from parsing \fB\fCmsg\fR. For example,
|
|
with \fB\fClog . "{name} {rcode}"\fR:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
{"time":"2026\-09\-15T08:00:00Z","level":"INFO","msg":"example.org. NOERROR","plugin":"log","client\_ip":"127.0.0.1","client\_port":40212,"qname":"example.org.","qtype":"A","qclass":"IN","protocol":"udp","id":42,"opcode":0,"request\_size":29,"dnssec\_ok":false,"bufsize":512,"rcode":"NOERROR","response\_size":29,"duration\_seconds":0.001}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "ADDITIONAL METADATA"
|
|
.PP
|
|
The log plugin adds the following metadata to allow for granular differentiation of NOERROR denial vs success messages. These are mapped from \fB\fCplugin/pkg/response/classify.go\fR and \fB\fCplugin/pkg/response/typify.go\fR.
|
|
|
|
.IP \(bu 4
|
|
\fB\fC{/log/class}\fR: success, denial
|
|
.IP \(bu 4
|
|
\fB\fC{/log/type}\fR: NODATA, NXDOMAIN, NOERROR
|
|
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
log . "{proto} Request: {name} {type} {/log/class} {/log/type}"
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Log all requests to stdout
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
log
|
|
whoami
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Custom log format, for all zones (\fB\fC.\fR)
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
log . "{proto} Request: {name} {type} {>id}"
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Only log denials (NXDOMAIN and nodata) for example.org (and below)
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
log example.org {
|
|
class denial
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Log all queries which were not resolved successfully in the Combined Log Format.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
log . {combined} {
|
|
class denial error
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Log all queries on which we did not get errors
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
log . {
|
|
class denial success
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Also the multiple statements can be OR-ed, for example, we can rewrite the above case as following:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
log . {
|
|
class denial
|
|
class success
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|