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