mirror of
https://github.com/coredns/coredns.git
synced 2025-12-02 00:24:08 -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,146 +1,157 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-HOSTS" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIhosts\fR \- enables serving zone data from a \fB/etc/hosts\fR style file\.
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
The hosts plugin is useful for serving zones from a \fB/etc/hosts\fR file\. It serves from a preloaded file that exists on disk\. It checks the file for changes and updates the zones accordingly\. This plugin only supports A, AAAA, and PTR records\. The hosts plugin can be used with readily available hosts files that block access to advertising servers\.
|
||||
.
|
||||
.P
|
||||
The plugin reloads the content of the hosts file every 5 seconds\. Upon reload, CoreDNS will use the new definitions\. Should the file be deleted, any inlined content will continue to be served\. When the file is restored, it will then again be used\.
|
||||
.
|
||||
.P
|
||||
This plugin can only be used once per Server Block\.
|
||||
.
|
||||
.SH "THE HOSTS FILE"
|
||||
Commonly the entries are of the from \fBIP_address canonical_hostname [aliases\.\.\.]\fR as explained by the hosts(5) man page\.
|
||||
.
|
||||
.P
|
||||
.\" Generated by Mmark Markdown Processer - mmark.nl
|
||||
.TH "COREDNS-HOSTS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
|
||||
|
||||
.SH HOSTS
|
||||
.SH NAME
|
||||
.PP
|
||||
\fIhosts\fP - enables serving zone data from a \fB\fC/etc/hosts\fR style file.
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The hosts plugin is useful for serving zones from a \fB\fC/etc/hosts\fR file. It serves from a preloaded
|
||||
file that exists on disk. It checks the file for changes and updates the zones accordingly. This
|
||||
plugin only supports A, AAAA, and PTR records. The hosts plugin can be used with readily
|
||||
available hosts files that block access to advertising servers.
|
||||
|
||||
.PP
|
||||
The plugin reloads the content of the hosts file every 5 seconds. Upon reload, CoreDNS will use the new definitions.
|
||||
Should the file be deleted, any inlined content will continue to be served. When the file is restored, it will then again be used.
|
||||
|
||||
.PP
|
||||
This plugin can only be used once per Server Block.
|
||||
|
||||
.SH THE HOSTS FILE
|
||||
.PP
|
||||
Commonly the entries are of the from \fB\fCIP_address canonical_hostname [aliases...]\fR as explained by the hosts(5) man page.
|
||||
|
||||
.PP
|
||||
Examples:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
# The following lines are desirable for IPv4 capable hosts
|
||||
127.0.0.1 localhost
|
||||
192.168.1.10 example.com example
|
||||
|
||||
# THE FOLLOWING LINES ARE DESIRABLE FOR IPV4 CAPABLE HOSTS
|
||||
127\.0\.0\.1 localhost
|
||||
192\.168\.1\.10 example\.com example
|
||||
|
||||
# THE FOLLOWING LINES ARE DESIRABLE FOR IPV6 CAPABLE HOSTS
|
||||
# The following lines are desirable for IPv6 capable hosts
|
||||
::1 localhost ip6\-localhost ip6\-loopback
|
||||
fdfc:a744:27b5:3b0e::1 example\.com example
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SS "PTR RECORDS"
|
||||
PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually\.
|
||||
.
|
||||
.SH "SYNTAX"
|
||||
.
|
||||
.nf
|
||||
fdfc:a744:27b5:3b0e::1 example.com example
|
||||
|
||||
hosts [FILE [ZONES\.\.\.]] {
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.SS PTR RECORDS
|
||||
.PP
|
||||
PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually.
|
||||
|
||||
.SH SYNTAX
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
hosts [FILE [ZONES...]] {
|
||||
[INLINE]
|
||||
ttl SECONDS
|
||||
no_reverse
|
||||
no\_reverse
|
||||
reload DURATION
|
||||
fallthrough [ZONES\.\.\.]
|
||||
fallthrough [ZONES...]
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBFILE\fR the hosts file to read and parse\. If the path is relative the path from the \fIroot\fR directive will be prepended to it\. Defaults to /etc/hosts if omitted\. We scan the file for changes every 5 seconds\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBINLINE\fR the hosts file contents inlined in Corefile\. If there are any lines before fallthrough then all of them will be treated as the additional content for hosts file\. The specified hosts file path will still be read but entries will be overridden\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBttl\fR change the DNS TTL of the records generated (forward and reverse)\. The default is 3600 seconds (1 hour)\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBreload\fR change the period between each hostsfile reload\. A time of zero seconds disable the feature\. Examples of valid durations: "300ms", "1\.5h" or "2h45m" are valid duration with units "ns" (nanosecond), "us" (or "µs" for microsecond), "ms" (millisecond), "s" (second), "m" (minute), "h" (hour)\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBno_reverse\fR disable the automatic generation of the \fBin\-addr\.arpa\fR or \fBip6\.arpa\fR entries for the hosts
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBfallthrough\fR If zone matches and no record can be generated, pass request to the next plugin\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
Load \fB/etc/hosts\fR file\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.IP \(bu 4
|
||||
\fBFILE\fP the hosts file to read and parse. If the path is relative the path from the \fIroot\fP
|
||||
directive will be prepended to it. Defaults to /etc/hosts if omitted. We scan the file for changes
|
||||
every 5 seconds.
|
||||
.IP \(bu 4
|
||||
\fBZONES\fP zones it should be authoritative for. If empty, the zones from the configuration block
|
||||
are used.
|
||||
.IP \(bu 4
|
||||
\fBINLINE\fP the hosts file contents inlined in Corefile. If there are any lines before fallthrough
|
||||
then all of them will be treated as the additional content for hosts file. The specified hosts
|
||||
file path will still be read but entries will be overridden.
|
||||
.IP \(bu 4
|
||||
\fB\fCttl\fR change the DNS TTL of the records generated (forward and reverse). The default is 3600 seconds (1 hour).
|
||||
.IP \(bu 4
|
||||
\fB\fCreload\fR change the period between each hostsfile reload. A time of zero seconds disable the feature. Examples of valid durations: "300ms", "1.5h" or "2h45m" are valid duration with units "ns" (nanosecond), "us" (or "µs" for microsecond), "ms" (millisecond), "s" (second), "m" (minute), "h" (hour).
|
||||
.IP \(bu 4
|
||||
\fB\fCno_reverse\fR disable the automatic generation of the \fB\fCin-addr.arpa\fR or \fB\fCip6.arpa\fR entries for the hosts
|
||||
.IP \(bu 4
|
||||
\fB\fCfallthrough\fR If zone matches and no record can be generated, pass request to the next plugin.
|
||||
If \fB[ZONES...]\fP is omitted, then fallthrough happens for all zones for which the plugin
|
||||
is authoritative. If specific zones are listed (for example \fB\fCin-addr.arpa\fR and \fB\fCip6.arpa\fR), then only
|
||||
queries for those zones will be subject to fallthrough.
|
||||
|
||||
|
||||
.SH EXAMPLES
|
||||
.PP
|
||||
Load \fB\fC/etc/hosts\fR file.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
hosts
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Load \fBexample\.hosts\fR file in the current directory\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
hosts example\.hosts
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Load \fB\fCexample.hosts\fR file in the current directory.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
hosts example.hosts
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Load example\.hosts file and only serve example\.org and example\.net from it and fall through to the next plugin if query doesn\'t match\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
hosts example\.hosts example\.org example\.net {
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Load example.hosts file and only serve example.org and example.net from it and fall through to the
|
||||
next plugin if query doesn't match.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
hosts example.hosts example.org example.net {
|
||||
fallthrough
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Load hosts file inlined in Corefile\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
hosts example\.hosts example\.org {
|
||||
10\.0\.0\.1 example\.org
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Load hosts file inlined in Corefile.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
hosts example.hosts example.org {
|
||||
10.0.0.1 example.org
|
||||
fallthrough
|
||||
}
|
||||
}
|
||||
.
|
||||
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "SEE ALSO"
|
||||
The form of the entries in the \fB/etc/hosts\fR file are based on IETF RFC 952 \fIhttps://tools\.ietf\.org/html/rfc952\fR which was updated by IETF RFC 1123 \fIhttps://tools\.ietf\.org/html/rfc1123\fR\.
|
||||
.RE
|
||||
|
||||
.SH SEE ALSO
|
||||
.PP
|
||||
The form of the entries in the \fB\fC/etc/hosts\fR file are based on IETF RFC 952
|
||||
\[la]https://tools.ietf.org/html/rfc952\[ra] which was updated by IETF RFC 1123
|
||||
\[la]https://tools.ietf.org/html/rfc1123\[ra].
|
||||
|
||||
|
||||
Reference in New Issue
Block a user