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