1.\" Copyright (c) 2009-2023 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 May 23, 2023 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 configuration: 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.It Sy resolv_conf_mv 214Defaults to NO. 215Defines if 216.Pa /etc/resolv.conf 217is updated by writing to a temporary file and then moving it 218vs writing directly to it. 219.El 220.Sh SUBSCRIBER OPTIONS 221openresolv ships with subscribers for the name servers 222.Xr dnsmasq 8 , 223.Xr named 8 , 224.Xr pdnsd 8 , 225.Xr pdns_recursor 1 , 226and 227.Xr unbound 8 . 228Each subscriber can create configuration files which should be included in 229the subscribers main configuration file. 230.Pp 231To disable a subscriber, simply set its name to NO. 232For example, to disable the libc subscriber you would set: 233.Bd -compact -literal -offset indent 234libc=NO 235.Ed 236.Bl -tag -width indent 237.It Sy dnsmasq_conf 238This file tells dnsmasq which name servers to use for specific domains. 239.It Sy dnsmasq_resolv 240This file tells dnsmasq which name servers to use for global lookups. 241.Pp 242Example resolvconf.conf for dnsmasq: 243.Bd -compact -literal -offset indent 244name_servers=127.0.0.1 245dnsmasq_conf=/etc/dnsmasq-conf.conf 246dnsmasq_resolv=/etc/dnsmasq-resolv.conf 247.Ed 248.Pp 249Example dnsmasq.conf: 250.Bd -compact -literal -offset indent 251listen-address=127.0.0.1 252# If dnsmasq is compiled for DBus then we can take 253# advantage of not having to restart dnsmasq. 254enable-dbus 255conf-file=/etc/dnsmasq-conf.conf 256resolv-file=/etc/dnsmasq-resolv.conf 257.Ed 258.It Sy named_options 259Include this file in the named options block. 260This file tells named which name servers to use for global lookups. 261.It Sy named_zones 262Include this file in the named global scope, after the options block. 263This file tells named which name servers to use for specific domains. 264.Pp 265Example resolvconf.conf for named: 266.Bd -compact -literal -offset indent 267name_servers=127.0.0.1 268named_options=/etc/named-options.conf 269named_zones=/etc/named-zones.conf 270.Ed 271.Pp 272Example named.conf: 273.Bd -compact -literal -offset indent 274options { 275 listen-on { 127.0.0.1; }; 276 include "/etc/named-options.conf"; 277}; 278 279include "/etc/named-zones.conf"; 280.Ed 281.It Sy pdnsd_conf 282This is the main pdnsd configuration file which we modify to add our 283forward domains to. 284If this variable is not set then we rely on the pdnsd configuration file 285setup to read 286.Pa pdnsd_resolv 287as documented below. 288.It Sy pdnsd_resolv 289This file tells pdnsd about global name servers. 290If this variable is not set then it's written to 291.Pa pdnsd_conf . 292.Pp 293Example resolvconf.conf for pdnsd: 294.Bd -compact -literal -offset indent 295name_servers=127.0.0.1 296pdnsd_conf=/etc/pdnsd.conf 297# pdnsd_resolv=/etc/pdnsd-resolv.conf 298.Ed 299.Pp 300Example pdnsd.conf: 301.Bd -compact -literal -offset indent 302global { 303 server_ip = 127.0.0.1; 304 status_ctl = on; 305} 306server { 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 314This file tells pdns_recursor about specific and global name servers. 315.Pp 316Example resolvconf.conf for pdns_recursor: 317.Bd -compact -literal -offset indent 318name_servers=127.0.0.1 319pdns_zones=/etc/pdns/recursor-zones.conf 320.Ed 321.Pp 322Example recursor.conf: 323.Bd -compact -literal -offset indent 324allow-from=127.0.0.0/8, ::1/128 325forward-zones-file=/etc/pdns/recursor-zones.conf 326.Ed 327.It Sy unbound_conf 328This file tells unbound about specific and global name servers. 329.It Sy unbound_insecure 330When set to YES, unbound marks the domains as insecure, thus ignoring DNSSEC. 331.It Sy unbound_forward_zone_options 332Options appended to each forward zone. 333Each option should be separated by an embedded new line. 334.Pp 335Example resolvconf.conf for unbound: 336.Bd -compact -literal -offset indent 337name_servers=127.0.0.1 338unbound_conf=/etc/unbound-resolvconf.conf 339.Ed 340.Pp 341Example unbound.conf: 342.Bd -compact -literal -offset indent 343include: /etc/unbound-resolvconf.conf 344.Ed 345.El 346.Sh SUBSCRIBER INTEGRATION 347Not all distributions store the files the subscribers need in the same 348locations. 349For example, named service scripts have been called named, bind and rc.bind 350and they could be located in a directory called /etc/rc.d, /etc/init.d or 351similar. 352Each subscriber attempts to automatically configure itself, but not every 353distribution has been catered for. 354Also, users could equally want to use a different version from the one 355installed by default, such as bind8 and bind9. 356To accommodate this, the subscribers have these files in configurable 357variables, documented below. 358.Bl -tag -width indent 359.It Sy dnsmasq_service 360Name of the dnsmasq service. 361.It Sy dnsmasq_restart 362Command to restart the dnsmasq service. 363.It Sy dnsmasq_pid 364Location of the dnsmasq pidfile. 365.It Sy libc_service 366Name of the libc service. 367.It Sy libc_restart 368Command to restart the libc service. 369.It Sy named_service 370Name of the named service. 371.It Sy named_restart 372Command to restart the named service. 373.It Sy pdnsd_restart 374Command to restart the pdnsd service. 375.It Sy pdns_service 376Command to restart the pdns_recursor service. 377.It Sy pdns_restart 378Command to restart the pdns_recursor service. 379.It Sy unbound_service 380Name of the unbound service. 381.It Sy unbound_restart 382Command to restart the unbound service. 383.It Sy unbound_pid 384Location 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 393Each distribution is a special snowflake and likes to name the same thing 394differently, namely the named service script. 395.Pp 396Please report them to 397.Lk https://roy.marples.name/projects/openresolv 398