mirror of
https://github.com/coredns/coredns.git
synced 2025-10-29 01:04:15 -04:00
dcff271480
Update the docs (mechanical change). Also run: go generate (no changes, good!) Signed-off-by: Miek Gieben <miek@miek.nl>
176 lines
4.3 KiB
Groff
176 lines
4.3 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-HOSTS" 7 "January 2020" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.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
|
|
If you want to pass the request to the rest of the plugin chain if there is no match in the \fIhosts\fP
|
|
plugin, you must specify the \fB\fCfallthrough\fR option.
|
|
|
|
.PP
|
|
This plugin can only be used once per Server Block.
|
|
|
|
.SH "THE HOSTS FILE"
|
|
.PP
|
|
Commonly the entries are of the form \fB\fCIP_address canonical_hostname [aliases...]\fR as explained by
|
|
the hosts(5) man page.
|
|
|
|
.PP
|
|
Examples:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
127.0.0.1 localhost
|
|
192.168.1.10 example.com example
|
|
|
|
::1 localhost ip6\-localhost ip6\-loopback
|
|
fdfc:a744:27b5:3b0e::1 example.com example
|
|
|
|
.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
|
|
reload DURATION
|
|
fallthrough [ZONES...]
|
|
}
|
|
|
|
.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
|
|
plugin 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 disables the
|
|
feature. Examples of valid durations: "300ms", "1.5h" or "2h45m". See Go's
|
|
time
|
|
\[la]https://godoc.org/time\[ra]. package.
|
|
.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 "METRICS"
|
|
.PP
|
|
If monitoring is enabled (via the \fIprometheus\fP plugin) then the following metrics are exported:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_hosts_entries_count{}\fR - The combined number of entries in hosts and Corefile.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_hosts_reload_timestamp_seconds{}\fR - The timestamp of the last reload of hosts file.
|
|
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Load \fB\fC/etc/hosts\fR file.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
hosts
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Load \fB\fCexample.hosts\fR file in the current directory.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
hosts example.hosts
|
|
}
|
|
|
|
.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
|
|
.RE
|
|
|
|
.PP
|
|
Load hosts file inlined in Corefile.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
example.hosts example.org {
|
|
hosts {
|
|
10.0.0.1 example.org
|
|
fallthrough
|
|
}
|
|
whoami
|
|
}
|
|
|
|
.fi
|
|
.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].
|
|
|