Commit | Line | Data |
---|---|---|
d19862cd | 1 | .\" Copyright (c) 2009-2023 Roy Marples |
8382a10e AL |
2 | .\" All rights reserved |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" | |
13 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | |
14 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
15 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
16 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |
17 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
18 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
19 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
20 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
21 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
22 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
23 | .\" SUCH DAMAGE. | |
24 | .\" | |
d19862cd | 25 | .Dd May 23, 2023 |
8382a10e AL |
26 | .Dt RESOLVCONF.CONF 5 |
27 | .Os | |
28 | .Sh NAME | |
29 | .Nm resolvconf.conf | |
30 | .Nd resolvconf configuration file | |
31 | .Sh DESCRIPTION | |
32 | .Nm | |
33 | is the configuration file for | |
34 | .Xr resolvconf 8 . | |
35 | The | |
36 | .Nm | |
37 | file is a shell script that is sourced by | |
38 | .Xr resolvconf 8 , | |
39 | meaning that | |
40 | .Nm | |
41 | must contain valid shell commands. | |
42 | Listed below are the standard | |
43 | .Nm | |
44 | variables that may be set. | |
45 | If the values contain whitespace, wildcards or other special shell characters, | |
46 | ensure they are quoted and escaped correctly. | |
47 | See the | |
48 | .Sy replace | |
49 | variable for an example on quoting. | |
50 | .Pp | |
51 | After updating this file, you may wish to run | |
52 | .Nm resolvconf -u | |
53 | to apply the new configuration. | |
54 | .Pp | |
55 | When a dynamically generated list is appended or prepended to, the whole | |
56 | is made unique where left-most wins. | |
57 | .Sh RESOLVCONF OPTIONS | |
58 | .Bl -tag -width indent | |
59 | .It Sy resolvconf | |
60 | Set to NO to disable | |
61 | .Nm resolvconf | |
62 | from running any subscribers. | |
63 | Defaults to YES. | |
e5b589ad RM |
64 | .It Sy allow_interfaces |
65 | If set, only these interfaces will be processed. | |
66 | .It Sy deny_interfaces | |
67 | If set, these interfaces will not be processed. | |
8382a10e AL |
68 | .It Sy interface_order |
69 | These interfaces will always be processed first. | |
70 | If unset, defaults to the following:- | |
a37440ee RM |
71 | .Bd -compact -literal -offset indent |
72 | lo lo[0-9]* | |
73 | .Ed | |
8382a10e AL |
74 | .It Sy dynamic_order |
75 | These interfaces will be processed next, unless they have a metric. | |
76 | If unset, defaults to the following:- | |
a37440ee | 77 | .Bd -compact -literal -offset indent |
e5b589ad | 78 | tap[0-9]* tun[0-9]* vpn vpn[0-9]* wg[0-9]* ppp[0-9]* ippp[0-9]* |
a37440ee | 79 | .Ed |
8382a10e | 80 | .It Sy inclusive_interfaces |
a37440ee | 81 | Ignore any exclusive marking for these interfaces. |
8382a10e AL |
82 | This is handy when 3rd party integrations force the |
83 | .Nm resolvconf -x | |
84 | option and you want to disable it easily. | |
85 | .It Sy local_nameservers | |
86 | If unset, defaults to the following:- | |
a37440ee RM |
87 | .Bd -compact -literal -offset indent |
88 | 127.* 0.0.0.0 255.255.255.255 ::1 | |
89 | .Ed | |
8382a10e AL |
90 | .It Sy search_domains |
91 | Prepend search domains to the dynamically generated list. | |
92 | .It Sy search_domains_append | |
93 | Append search domains to the dynamically generated list. | |
94 | .It Sy domain_blacklist | |
95 | A list of domains to be removed from consideration. | |
96 | To remove a domain, you can use foo.* | |
97 | To remove a sub domain, you can use *.bar | |
98 | .It Sy name_servers | |
99 | Prepend name servers to the dynamically generated list. | |
100 | You should set this to 127.0.0.1 if you use a local name server other than | |
101 | libc. | |
102 | .It Sy name_servers_append | |
103 | Append name servers to the dynamically generated list. | |
104 | .It Sy name_server_blacklist | |
105 | A list of name servers to be removed from consideration. | |
106 | The default is 0.0.0.0 as some faulty routers send it via DHCP. | |
107 | To remove a block, you can use 192.168.* | |
108 | .It Sy private_interfaces | |
109 | These interfaces name servers will only be queried for the domains listed | |
110 | in their resolv.conf. | |
111 | Useful for VPN domains. | |
112 | Setting | |
113 | .Sy private_interfaces Ns ="*" | |
114 | will stop the forwarding of the root zone and allows the local resolver to | |
115 | recursively query the root servers directly. | |
116 | Requires a local nameserver other than libc. | |
117 | This is equivalent to the | |
118 | .Nm resolvconf -p | |
119 | option. | |
120 | .It Sy public_interfaces | |
121 | Force these interface to be public, overriding the private marking. | |
122 | This is handy when 3rd party integrations force the | |
123 | .Nm resolvconf -p | |
124 | option and you want to disable it easily. | |
125 | .It Sy replace | |
126 | Is a space separated list of replacement keywords. | |
127 | The syntax is this: | |
128 | .Va $keyword Ns / Ns Va $match Ns / Ns Va $replacement | |
129 | .Pp | |
130 | Example, given this resolv.conf: | |
a37440ee RM |
131 | .Bd -compact -literal -offset indent |
132 | domain foo.org | |
133 | search foo.org dead.beef | |
134 | nameserver 1.2.3.4 | |
135 | nameserver 2.3.4.5 | |
136 | .Ed | |
d19862cd | 137 | and this configuration: |
a37440ee RM |
138 | .Bd -compact -literal -offset indent |
139 | replace="search/foo*/bar.com" | |
140 | replace="$replace nameserver/1.2.3.4/5.6.7.8" | |
141 | replace="$replace nameserver/2.3.4.5/" | |
142 | .Ed | |
8382a10e | 143 | you would get this resolv.conf instead: |
a37440ee RM |
144 | .Bd -compact -literal -offset indent |
145 | domain foo.org | |
146 | search bar.com | |
147 | nameserver 5.6.7.8 | |
148 | .Ed | |
8382a10e AL |
149 | .It Sy replace_sub |
150 | Works the same way as | |
151 | .Sy replace | |
152 | except it works on each space separated value rather than the whole line, | |
153 | so it's useful for the replacing a single domain within the search directive. | |
154 | Using the same example resolv.conf and changing | |
155 | .Sy replace | |
156 | to | |
157 | .Sy replace_sub , | |
158 | you would get this resolv.conf instead: | |
a37440ee RM |
159 | .Bd -compact -literal -offset indent |
160 | domain foo.org | |
161 | search bar.com dead.beef | |
162 | nameserver 5.6.7.8 | |
163 | .Ed | |
8382a10e AL |
164 | .It Sy state_dir |
165 | Override the default state directory of | |
166 | .Pa @VARDIR@ . | |
167 | This should not be changed once | |
168 | .Nm resolvconf | |
169 | is in use unless the old directory is copied to the new one. | |
170 | .El | |
171 | .Sh LIBC OPTIONS | |
172 | The following variables affect | |
173 | .Xr resolv.conf 5 | |
174 | directly:- | |
175 | .Bl -tag -width indent | |
176 | .It Sy resolv_conf | |
177 | Defaults to | |
178 | .Pa /etc/resolv.conf | |
179 | if not set. | |
180 | .It Sy resolv_conf_options | |
181 | A list of libc resolver options, as specified in | |
182 | .Xr resolv.conf 5 . | |
183 | .It Sy resolv_conf_passthrough | |
184 | When set to YES the latest resolv.conf is written to | |
185 | .Sy resolv_conf | |
186 | without any alteration. | |
187 | When set to /dev/null or NULL, | |
188 | .Sy resolv_conf_local_only | |
189 | is defaulted to NO, | |
190 | .Sy local_nameservers | |
191 | is unset unless overridden and only the information set in | |
192 | .Nm | |
193 | is written to | |
194 | .Sy resolv_conf . | |
195 | .It Sy resolv_conf_sortlist | |
196 | A libc resolver sortlist, as specified in | |
197 | .Xr resolv.conf 5 . | |
198 | .It Sy resolv_conf_local_only | |
199 | If a local name server is configured then the default is just to specify that | |
200 | and ignore all other entries as they will be configured for the local | |
201 | name server. | |
202 | Set this to NO to also list non-local nameservers. | |
203 | This will give you working DNS even if the local nameserver stops functioning | |
204 | at the expense of duplicated server queries. | |
205 | .It Sy append_nameservers | |
206 | Append name servers to the dynamically generated list. | |
207 | .It Sy prepend_nameservers | |
208 | Prepend name servers to the dynamically generated list. | |
209 | .It Sy append_search | |
210 | Append search domains to the dynamically generated list. | |
211 | .It Sy prepend_search | |
212 | Prepend search domains to the dynamically generated list. | |
d19862cd RM |
213 | .It Sy resolv_conf_mv |
214 | Defaults to NO. | |
215 | Defines if | |
216 | .Pa /etc/resolv.conf | |
217 | is updated by writing to a temporary file and then moving it | |
218 | vs writing directly to it. | |
8382a10e AL |
219 | .El |
220 | .Sh SUBSCRIBER OPTIONS | |
221 | openresolv ships with subscribers for the name servers | |
222 | .Xr dnsmasq 8 , | |
223 | .Xr named 8 , | |
a37440ee | 224 | .Xr pdnsd 8 , |
e5b589ad | 225 | .Xr pdns_recursor 1 , |
8382a10e AL |
226 | and |
227 | .Xr unbound 8 . | |
228 | Each subscriber can create configuration files which should be included in | |
e5b589ad | 229 | the subscribers main configuration file. |
8382a10e | 230 | .Pp |
d19862cd | 231 | To disable a subscriber, simply set its name to NO. |
8382a10e | 232 | For example, to disable the libc subscriber you would set: |
a37440ee RM |
233 | .Bd -compact -literal -offset indent |
234 | libc=NO | |
235 | .Ed | |
8382a10e AL |
236 | .Bl -tag -width indent |
237 | .It Sy dnsmasq_conf | |
238 | This file tells dnsmasq which name servers to use for specific domains. | |
239 | .It Sy dnsmasq_resolv | |
240 | This file tells dnsmasq which name servers to use for global lookups. | |
241 | .Pp | |
242 | Example resolvconf.conf for dnsmasq: | |
a37440ee RM |
243 | .Bd -compact -literal -offset indent |
244 | name_servers=127.0.0.1 | |
245 | dnsmasq_conf=/etc/dnsmasq-conf.conf | |
246 | dnsmasq_resolv=/etc/dnsmasq-resolv.conf | |
247 | .Ed | |
8382a10e AL |
248 | .Pp |
249 | Example dnsmasq.conf: | |
a37440ee RM |
250 | .Bd -compact -literal -offset indent |
251 | listen-address=127.0.0.1 | |
252 | # If dnsmasq is compiled for DBus then we can take | |
253 | # advantage of not having to restart dnsmasq. | |
254 | enable-dbus | |
255 | conf-file=/etc/dnsmasq-conf.conf | |
256 | resolv-file=/etc/dnsmasq-resolv.conf | |
257 | .Ed | |
8382a10e AL |
258 | .It Sy named_options |
259 | Include this file in the named options block. | |
260 | This file tells named which name servers to use for global lookups. | |
261 | .It Sy named_zones | |
262 | Include this file in the named global scope, after the options block. | |
263 | This file tells named which name servers to use for specific domains. | |
264 | .Pp | |
265 | Example resolvconf.conf for named: | |
a37440ee RM |
266 | .Bd -compact -literal -offset indent |
267 | name_servers=127.0.0.1 | |
268 | named_options=/etc/named-options.conf | |
269 | named_zones=/etc/named-zones.conf | |
270 | .Ed | |
8382a10e AL |
271 | .Pp |
272 | Example named.conf: | |
a37440ee RM |
273 | .Bd -compact -literal -offset indent |
274 | options { | |
275 | listen-on { 127.0.0.1; }; | |
276 | include "/etc/named-options.conf"; | |
277 | }; | |
278 | ||
279 | include "/etc/named-zones.conf"; | |
280 | .Ed | |
8382a10e AL |
281 | .It Sy pdnsd_conf |
282 | This is the main pdnsd configuration file which we modify to add our | |
283 | forward domains to. | |
284 | If this variable is not set then we rely on the pdnsd configuration file | |
285 | setup to read | |
286 | .Pa pdnsd_resolv | |
287 | as documented below. | |
288 | .It Sy pdnsd_resolv | |
289 | This file tells pdnsd about global name servers. | |
290 | If this variable is not set then it's written to | |
291 | .Pa pdnsd_conf . | |
292 | .Pp | |
293 | Example resolvconf.conf for pdnsd: | |
a37440ee RM |
294 | .Bd -compact -literal -offset indent |
295 | name_servers=127.0.0.1 | |
296 | pdnsd_conf=/etc/pdnsd.conf | |
297 | # pdnsd_resolv=/etc/pdnsd-resolv.conf | |
298 | .Ed | |
8382a10e AL |
299 | .Pp |
300 | Example pdnsd.conf: | |
a37440ee RM |
301 | .Bd -compact -literal -offset indent |
302 | global { | |
303 | server_ip = 127.0.0.1; | |
304 | status_ctl = on; | |
305 | } | |
306 | server { | |
307 | # A server definition is required, even if empty. | |
308 | label="empty"; | |
309 | proxy_only=on; | |
310 | # file="/etc/pdnsd-resolv.conf"; | |
311 | } | |
312 | .Ed | |
313 | .It Sy pdns_zones | |
314 | This file tells pdns_recursor about specific and global name servers. | |
315 | .Pp | |
316 | Example resolvconf.conf for pdns_recursor: | |
317 | .Bd -compact -literal -offset indent | |
318 | name_servers=127.0.0.1 | |
319 | pdns_zones=/etc/pdns/recursor-zones.conf | |
320 | .Ed | |
321 | .Pp | |
322 | Example recursor.conf: | |
323 | .Bd -compact -literal -offset indent | |
324 | allow-from=127.0.0.0/8, ::1/128 | |
325 | forward-zones-file=/etc/pdns/recursor-zones.conf | |
326 | .Ed | |
8382a10e AL |
327 | .It Sy unbound_conf |
328 | This file tells unbound about specific and global name servers. | |
329 | .It Sy unbound_insecure | |
330 | When set to YES, unbound marks the domains as insecure, thus ignoring DNSSEC. | |
d19862cd RM |
331 | .It Sy unbound_forward_zone_options |
332 | Options appended to each forward zone. | |
333 | Each option should be separated by an embedded new line. | |
8382a10e AL |
334 | .Pp |
335 | Example resolvconf.conf for unbound: | |
a37440ee RM |
336 | .Bd -compact -literal -offset indent |
337 | name_servers=127.0.0.1 | |
338 | unbound_conf=/etc/unbound-resolvconf.conf | |
339 | .Ed | |
8382a10e AL |
340 | .Pp |
341 | Example unbound.conf: | |
a37440ee RM |
342 | .Bd -compact -literal -offset indent |
343 | include: /etc/unbound-resolvconf.conf | |
344 | .Ed | |
8382a10e AL |
345 | .El |
346 | .Sh SUBSCRIBER INTEGRATION | |
347 | Not all distributions store the files the subscribers need in the same | |
348 | locations. | |
349 | For example, named service scripts have been called named, bind and rc.bind | |
350 | and they could be located in a directory called /etc/rc.d, /etc/init.d or | |
351 | similar. | |
352 | Each subscriber attempts to automatically configure itself, but not every | |
353 | distribution has been catered for. | |
354 | Also, users could equally want to use a different version from the one | |
355 | installed by default, such as bind8 and bind9. | |
356 | To accommodate this, the subscribers have these files in configurable | |
357 | variables, documented below. | |
8382a10e AL |
358 | .Bl -tag -width indent |
359 | .It Sy dnsmasq_service | |
360 | Name of the dnsmasq service. | |
361 | .It Sy dnsmasq_restart | |
362 | Command to restart the dnsmasq service. | |
363 | .It Sy dnsmasq_pid | |
364 | Location of the dnsmasq pidfile. | |
365 | .It Sy libc_service | |
366 | Name of the libc service. | |
367 | .It Sy libc_restart | |
368 | Command to restart the libc service. | |
369 | .It Sy named_service | |
370 | Name of the named service. | |
371 | .It Sy named_restart | |
372 | Command to restart the named service. | |
373 | .It Sy pdnsd_restart | |
374 | Command to restart the pdnsd service. | |
a37440ee RM |
375 | .It Sy pdns_service |
376 | Command to restart the pdns_recursor service. | |
377 | .It Sy pdns_restart | |
378 | Command to restart the pdns_recursor service. | |
8382a10e AL |
379 | .It Sy unbound_service |
380 | Name of the unbound service. | |
381 | .It Sy unbound_restart | |
382 | Command to restart the unbound service. | |
383 | .It Sy unbound_pid | |
384 | Location of the unbound pidfile. | |
385 | .El | |
386 | .Sh SEE ALSO | |
387 | .Xr sh 1 , | |
388 | .Xr resolv.conf 5 , | |
389 | .Xr resolvconf 8 | |
390 | .Sh AUTHORS | |
391 | .An Roy Marples Aq Mt roy@marples.name | |
392 | .Sh BUGS | |
393 | Each distribution is a special snowflake and likes to name the same thing | |
394 | differently, namely the named service script. | |
395 | .Pp | |
396 | Please report them to | |
d19862cd | 397 | .Lk https://roy.marples.name/projects/openresolv |