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.\" 25.Dd September 8, 2019 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:- 67.Bd -compact -literal -offset indent 68lo lo[0-9]* 69.Ed 70.It Sy dynamic_order 71These interfaces will be processed next, unless they have a metric. 72If unset, defaults to the following:- 73.Bd -compact -literal -offset indent 74tap[0-9]* tun[0-9]* vpn vpn[0-9]* ppp[0-9]* ippp[0-9]* 75.Ed 76.It Sy inclusive_interfaces 77Ignore any exclusive marking for these interfaces. 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:- 83.Bd -compact -literal -offset indent 84127.* 0.0.0.0 255.255.255.255 ::1 85.Ed 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: 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 133and this configuaration: 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 139you would get this resolv.conf instead: 140.Bd -compact -literal -offset indent 141domain foo.org 142search bar.com 143nameserver 5.6.7.8 144.Ed 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: 155.Bd -compact -literal -offset indent 156domain foo.org 157search bar.com dead.beef 158nameserver 5.6.7.8 159.Ed 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 , 214.Xr pdnsd 8 , 215.Xr pdns_recursor 8 , 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: 223.Bd -compact -literal -offset indent 224libc=NO 225.Ed 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: 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 238.Pp 239Example dnsmasq.conf: 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 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: 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 261.Pp 262Example named.conf: 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 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: 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 289.Pp 290Example pdnsd.conf: 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 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: 323.Bd -compact -literal -offset indent 324name_servers=127.0.0.1 325unbound_conf=/etc/unbound-resolvconf.conf 326.Ed 327.Pp 328Example unbound.conf: 329.Bd -compact -literal -offset indent 330include: /etc/unbound-resolvconf.conf 331.Ed 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. 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. 362.It Sy pdns_service 363Command to restart the pdns_recursor service. 364.It Sy pdns_restart 365Command to restart the pdns_recursor service. 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 385