1RESOLVCONF.CONF(5)          BSD File Formats Manual         RESOLVCONF.CONF(5)
2

NAME

4     resolvconf.conf — resolvconf configuration file
5

DESCRIPTION

7     resolvconf.conf is the configuration file for resolvconf(8).  The
8     resolvconf.conf file is a shell script that is sourced by resolvconf(8),
9     meaning that resolvconf.conf must contain valid shell commands.  Listed
10     below are the standard resolvconf.conf variables that may be set.  If the
11     values contain whitespace, wildcards or other special shell characters,
12     ensure they are quoted and escaped correctly.  See the replace variable
13     for an example on quoting.
14
15     After updating this file, you may wish to run resolvconf -u to apply the
16     new configuration.
17
18     When a dynamically generated list is appended or prepended to, the whole
19     is made unique where left-most wins.
20

RESOLVCONF OPTIONS

22     resolvconf
23             Set to NO to disable resolvconf from running any subscribers.
24             Defaults to YES.
25
26     allow_interfaces
27             If set, only these interfaces will be processed.
28
29     deny_interfaces
30             If set, these interfaces will not be processed.
31
32     interface_order
33             These interfaces will always be processed first.  If unset,
34             defaults to the following:-
35
36             lo lo[0-9]*
37
38     dynamic_order
39             These interfaces will be processed next, unless they have a met‐
40             ric.  If unset, defaults to the following:-
41
42             tap[0-9]* tun[0-9]* vpn vpn[0-9]* wg[0-9]* ppp[0-9]* ippp[0-9]*
43
44     inclusive_interfaces
45             Ignore any exclusive marking for these interfaces.  This is handy
46             when 3rd party integrations force the resolvconf -x option and
47             you want to disable it easily.
48
49     local_nameservers
50             If unset, defaults to the following:-
51
52             127.* 0.0.0.0 255.255.255.255 ::1
53
54     search_domains
55             Prepend search domains to the dynamically generated list.
56
57     search_domains_append
58             Append search domains to the dynamically generated list.
59
60     domain_blacklist
61             A list of domains to be removed from consideration.  To remove a
62             domain, you can use foo.*  To remove a sub domain, you can use
63             *.bar
64
65     name_servers
66             Prepend name servers to the dynamically generated list.  You
67             should set this to 127.0.0.1 if you use a local name server other
68             than libc.
69
70     name_servers_append
71             Append name servers to the dynamically generated list.
72
73     name_server_blacklist
74             A list of name servers to be removed from consideration.  The
75             default is 0.0.0.0 as some faulty routers send it via DHCP.  To
76             remove a block, you can use 192.168.*
77
78     private_interfaces
79             These interfaces name servers will only be queried for the
80             domains listed in their resolv.conf.  Useful for VPN domains.
81             Setting private_interfaces="*" will stop the forwarding of the
82             root zone and allows the local resolver to recursively query the
83             root servers directly.  Requires a local nameserver other than
84             libc.  This is equivalent to the resolvconf -p option.
85
86     public_interfaces
87             Force these interface to be public, overriding the private mark‐
88             ing.  This is handy when 3rd party integrations force the
89             resolvconf -p option and you want to disable it easily.
90
91     replace
92             Is a space separated list of replacement keywords.  The syntax is
93             this: $keyword/$match/$replacement
94
95             Example, given this resolv.conf:
96
97             domain foo.org search foo.org dead.beef nameserver 1.2.3.4 name‐
98             server 2.3.4.5
99             and this configuaration:
100
101             replace="search/foo*/bar.com" replace="$replace name‐
102             server/1.2.3.4/5.6.7.8" replace="$replace nameserver/2.3.4.5/"
103             you would get this resolv.conf instead:
104
105             domain foo.org search bar.com nameserver 5.6.7.8
106
107     replace_sub
108             Works the same way as replace except it works on each space sepa‐
109             rated value rather than the whole line, so it's useful for the
110             replacing a single domain within the search directive.  Using the
111             same example resolv.conf and changing replace to replace_sub, you
112             would get this resolv.conf instead:
113
114             domain foo.org search bar.com dead.beef nameserver 5.6.7.8
115
116     state_dir
117             Override the default state directory of /run/resolvconf.  This
118             should not be changed once resolvconf is in use unless the old
119             directory is copied to the new one.
120

LIBC OPTIONS

122     The following variables affect resolv.conf(5) directly:-
123
124     resolv_conf
125             Defaults to /etc/resolv.conf if not set.
126
127     resolv_conf_options
128             A list of libc resolver options, as specified in resolv.conf(5).
129
130     resolv_conf_passthrough
131             When set to YES the latest resolv.conf is written to resolv_conf
132             without any alteration.  When set to /dev/null or NULL,
133             resolv_conf_local_only is defaulted to NO, local_nameservers is
134             unset unless overridden and only the information set in
135             resolvconf.conf is written to resolv_conf.
136
137     resolv_conf_sortlist
138             A libc resolver sortlist, as specified in resolv.conf(5).
139
140     resolv_conf_local_only
141             If a local name server is configured then the default is just to
142             specify that and ignore all other entries as they will be config‐
143             ured for the local name server.  Set this to NO to also list non-
144             local nameservers.  This will give you working DNS even if the
145             local nameserver stops functioning at the expense of duplicated
146             server queries.
147
148     append_nameservers
149             Append name servers to the dynamically generated list.
150
151     prepend_nameservers
152             Prepend name servers to the dynamically generated list.
153
154     append_search
155             Append search domains to the dynamically generated list.
156
157     prepend_search
158             Prepend search domains to the dynamically generated list.
159

SUBSCRIBER OPTIONS

161     openresolv ships with subscribers for the name servers dnsmasq(8),
162     named(8), pdnsd(8), pdns_recursor(1), and unbound(8).  Each subscriber
163     can create configuration files which should be included in the sub‐
164     scribers main configuration file.
165
166     To disable a subscriber, simply set it's name to NO.  For example, to
167     disable the libc subscriber you would set:
168
169     libc=NO
170
171     dnsmasq_conf
172             This file tells dnsmasq which name servers to use for specific
173             domains.
174
175     dnsmasq_resolv
176             This file tells dnsmasq which name servers to use for global
177             lookups.
178
179             Example resolvconf.conf for dnsmasq:
180
181             name_servers=127.0.0.1 dnsmasq_conf=/etc/dnsmasq-conf.conf dns‐
182             masq_resolv=/etc/dnsmasq-resolv.conf
183
184             Example dnsmasq.conf:
185
186             listen-address=127.0.0.1 # If dnsmasq is compiled for DBus then
187             we can take # advantage of not having to restart dnsmasq.
188             enable-dbus conf-file=/etc/dnsmasq-conf.conf resolv-
189             file=/etc/dnsmasq-resolv.conf
190
191     named_options
192             Include this file in the named options block.  This file tells
193             named which name servers to use for global lookups.
194
195     named_zones
196             Include this file in the named global scope, after the options
197             block.  This file tells named which name servers to use for spe‐
198             cific domains.
199
200             Example resolvconf.conf for named:
201
202             name_servers=127.0.0.1 named_options=/etc/named-options.conf
203             named_zones=/etc/named-zones.conf
204
205             Example named.conf:
206
207             options {      listen-on { 127.0.0.1; };      include
208             "/etc/named-options.conf"; };
209
210             include "/etc/named-zones.conf";
211
212     pdnsd_conf
213             This is the main pdnsd configuration file which we modify to add
214             our forward domains to.  If this variable is not set then we rely
215             on the pdnsd configuration file setup to read pdnsd_resolv as
216             documented below.
217
218     pdnsd_resolv
219             This file tells pdnsd about global name servers.  If this vari‐
220             able is not set then it's written to pdnsd_conf.
221
222             Example resolvconf.conf for pdnsd:
223
224             name_servers=127.0.0.1 pdnsd_conf=/etc/pdnsd.conf #
225             pdnsd_resolv=/etc/pdnsd-resolv.conf
226
227             Example pdnsd.conf:
228
229             global {      server_ip = 127.0.0.1;      status_ctl = on; }
230             server {      # A server definition is required, even if empty.
231                  label="empty";      proxy_only=on;      # file="/etc/pdnsd-
232             resolv.conf"; }
233
234     pdns_zones
235             This file tells pdns_recursor about specific and global name
236             servers.
237
238             Example resolvconf.conf for pdns_recursor:
239
240             name_servers=127.0.0.1 pdns_zones=/etc/pdns/recursor-zones.conf
241
242             Example recursor.conf:
243
244             allow-from=127.0.0.0/8, ::1/128 forward-zones-
245             file=/etc/pdns/recursor-zones.conf
246
247     unbound_conf
248             This file tells unbound about specific and global name servers.
249
250     unbound_insecure
251             When set to YES, unbound marks the domains as insecure, thus
252             ignoring DNSSEC.
253
254             Example resolvconf.conf for unbound:
255
256             name_servers=127.0.0.1 unbound_conf=/etc/unbound-resolvconf.conf
257
258             Example unbound.conf:
259
260             include: /etc/unbound-resolvconf.conf
261

SUBSCRIBER INTEGRATION

263     Not all distributions store the files the subscribers need in the same
264     locations.  For example, named service scripts have been called named,
265     bind and rc.bind and they could be located in a directory called
266     /etc/rc.d, /etc/init.d or similar.  Each subscriber attempts to automati‐
267     cally configure itself, but not every distribution has been catered for.
268     Also, users could equally want to use a different version from the one
269     installed by default, such as bind8 and bind9.  To accommodate this, the
270     subscribers have these files in configurable variables, documented below.
271
272     dnsmasq_service
273             Name of the dnsmasq service.
274
275     dnsmasq_restart
276             Command to restart the dnsmasq service.
277
278     dnsmasq_pid
279             Location of the dnsmasq pidfile.
280
281     libc_service
282             Name of the libc service.
283
284     libc_restart
285             Command to restart the libc service.
286
287     named_service
288             Name of the named service.
289
290     named_restart
291             Command to restart the named service.
292
293     pdnsd_restart
294             Command to restart the pdnsd service.
295
296     pdns_service
297             Command to restart the pdns_recursor service.
298
299     pdns_restart
300             Command to restart the pdns_recursor service.
301
302     unbound_service
303             Name of the unbound service.
304
305     unbound_restart
306             Command to restart the unbound service.
307
308     unbound_pid
309             Location of the unbound pidfile.
310

SEE ALSO

312     sh(1), resolv.conf(5), resolvconf(8)
313

AUTHORS

315     Roy Marples <roy@marples.name>
316

BUGS

318     Each distribution is a special snowflake and likes to name the same thing
319     differently, namely the named service script.
320
321     Please report them to
322           http://roy.marples.name/projects/openresolv
323
324BSD                             October 1, 2020                            BSD
Impressum