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