forked from coredns/coredns
-
Notifications
You must be signed in to change notification settings - Fork 0
/
coredns-hosts.7
175 lines (137 loc) · 4.34 KB
/
coredns-hosts.7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-HOSTS" 7 "March 2021" "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 \fIhosts\fP 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{}\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].