mirror of
https://github.com/coredns/coredns.git
synced 2025-12-01 08:04:14 -05:00
docs: Regenerate all manpages using mmark (#2762)
Mmark recently became able to create manual pages. This removed the dependency on 'ronn' and just uses mmark (Go program). Re-hookup Makefile.doc to generate the correct header mmark needs to see and regenate them all. Spot checking a few pages suggest they look good and actually better than rendered with ronn, esp. lists in lists. Fixes #2757 Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben
GitHub
@@ -1,279 +1,253 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-LOG" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIlog\fR \- enables query logging to standard output\.
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
By just using \fIlog\fR you dump all queries (and parts for the reply) on standard output\. Options exist to tweak the output a little\. The date/time prefix on log lines is RFC3339 formatted with milliseconds\.
|
||||
.
|
||||
.P
|
||||
Note that for busy servers logging will incur a performance hit\.
|
||||
.
|
||||
.SH "SYNTAX"
|
||||
.
|
||||
.nf
|
||||
.\" Generated by Mmark Markdown Processer - mmark.nl
|
||||
.TH "COREDNS-LOG" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
|
||||
|
||||
.SH LOG
|
||||
.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. The date/time prefix on log lines is RFC3339 formatted with
|
||||
milliseconds.
|
||||
|
||||
.PP
|
||||
Note that for busy servers logging will incur a performance hit.
|
||||
|
||||
.SH SYNTAX
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
log
|
||||
.
|
||||
|
||||
.fi
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
With no arguments, a query log entry is written to \fIstdout\fR in the common log format for all requests
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
.RE
|
||||
|
||||
.IP \(bu 4
|
||||
With no arguments, a query log entry is written to \fIstdout\fP in the common log format for all requests
|
||||
|
||||
|
||||
.PP
|
||||
Or if you want/need slightly more control:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
log [NAMES\.\.\.] [FORMAT]
|
||||
.
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
log [NAMES...] [FORMAT]
|
||||
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBNAMES\fR is the name list to match in order to be logged
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBFORMAT\fR is the log format to use (default is Common Log Format), \fB{common}\fR is used as a shortcut for the Common Log Format\. You can also use \fB{combined}\fR for a format that adds the query opcode \fB{>opcode}\fR to the Common Log Format\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
.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:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
log [NAMES\.\.\.] [FORMAT] {
|
||||
class CLASSES\.\.\.
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
log [NAMES...] [FORMAT] {
|
||||
class CLASSES...
|
||||
}
|
||||
.
|
||||
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBCLASSES\fR is a space\-separated list of classes of responses that should be logged
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
.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
|
||||
\fBsuccess\fR: successful response
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBdenial\fR: either NXDOMAIN or nodata responses (Name exists, type does not)\. A nodata response sets the return code to NOERROR\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBerror\fR: SERVFAIL, NOTIMP, REFUSED, etc\. Anything that indicates the remote server is not willing to resolve the request\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBall\fR: the default \- nothing is specified\. Using of this class means that all messages will be logged whatever we mix together with "all"\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
If no class is specified, it defaults to \fIall\fR\.
|
||||
.
|
||||
.SH "LOG FORMAT"
|
||||
You can specify a custom log format with any placeholder values\. Log supports both request and response placeholders\.
|
||||
.
|
||||
.P
|
||||
|
||||
.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 \fIall\fP.
|
||||
|
||||
.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{type}\fR: qtype of the request
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{name}\fR: qname of the request
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{class}\fR: qclass of the request
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{proto}\fR: protocol used (tcp or udp)
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{remote}\fR: client\'s IP address, for IPv6 addresses these are enclosed in brackets: \fB[::1]\fR
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{local}\fR: server\'s IP address, for IPv6 addresses these are enclosed in brackets: \fB[::1]\fR
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{size}\fR: request size in bytes
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{port}\fR: client\'s port
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{duration}\fR: response duration
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{rcode}\fR: response RCODE
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{rsize}\fR: raw (uncompressed), response size (a client may receive a smaller response)
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{>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{>bufsize}\fR: the EDNS0 buffer size advertised in the query
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{>do}\fR: is the EDNS0 DO (DNSSEC OK) bit set in the query
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{>id}\fR: query ID
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{>opcode}\fR: query OPCODE
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{common}\fR: the default Common Log Format\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{combined}\fR: the Common Log Format with the query opcode\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fB{/LABEL}\fR: any metadata label is accepted as a place holder if it is enclosed between \fB{/\fR and \fB}\fR, the place holder will be replaced by the corresponding metadata value or the default value \fB\-\fR if label is not defined\. See the \fImetadata\fR plugin for more information\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
|
||||
.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:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
`{remote}:{port} \- {>id} "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Each of these logs will be outputted with \fBlog\.Infof\fR, so a typical example looks like this:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
2018\-10\-30T19:10:07\.547Z [INFO] [::1]:50759 \- 29008 "A IN example\.org\. udp 41 false 4096" NOERROR qr,rd,ra,ad 68 0\.037990251s
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Each of these logs will be outputted with \fB\fClog.Infof\fR, so a typical example looks like this:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
2018\-10\-30T19:10:07.547Z [INFO] [::1]:50759 \- 29008 "A IN example.org. udp 41 false 4096" NOERROR qr,rd,ra,ad 68 0.037990251s
|
||||
~~~~
|
||||
|
||||
## Examples
|
||||
|
||||
Log all requests to stdout
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
~~~ corefile
|
||||
\&. {
|
||||
log
|
||||
whoami
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Custom log format, for all zones (\fB\.\fR)
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
log \. "{proto} Request: {name} {type} {>id}"
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Custom log format, for all zones (\fB\fC.\fR)
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
log . "{proto} Request: {name} {type} {>id}"
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Only log denials (NXDOMAIN and nodata) for example\.org (and below)
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
log example\.org {
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Only log denials (NXDOMAIN and nodata) for example.org (and below)
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
log example.org {
|
||||
class denial
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Log all queries which were not resolved successfully in the Combined Log Format\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
log \. {combined} {
|
||||
.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
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Log all queries on which we did not get errors
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
log \. {
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Log all queries on which we did not get errors
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
log . {
|
||||
class denial success
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Also the multiple statements can be OR\-ed, for example, we can rewrite the above case as following:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
log \. {
|
||||
.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
|
||||
.
|
||||
.IP "" 0
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
|
||||
Reference in New Issue
Block a user