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