1.\" Copyright (c) 2007-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 April 27, 2015 26.Dt RESOLVCONF 8 27.Os 28.Sh NAME 29.Nm resolvconf 30.Nd a framework for managing multiple DNS configurations 31.Sh SYNOPSIS 32.Nm 33.Fl I 34.Nm 35.Op Fl m Ar metric 36.Op Fl p 37.Op Fl x 38.Fl a Ar interface Ns Op Ar .protocol 39.No < Ns Pa file 40.Nm 41.Op Fl f 42.Fl d Ar interface Ns Op Ar .protocol 43.Nm 44.Op Fl x 45.Fl il Ar pattern 46.Nm 47.Fl u 48.Sh DESCRIPTION 49.Nm 50manages 51.Xr resolv.conf 5 52files from multiple sources, such as DHCP and VPN clients. 53Traditionally, the host runs just one client and that updates 54.Pa /etc/resolv.conf . 55More modern systems frequently have wired and wireless interfaces and there is 56no guarantee both are on the same network. 57With the advent of VPN and other 58types of networking daemons, many things now contend for the contents of 59.Pa /etc/resolv.conf . 60.Pp 61.Nm 62solves this by letting the daemon send their 63.Xr resolv.conf 5 64file to 65.Nm 66via 67.Xr stdin 3 68with the argument 69.Fl a Ar interface Ns Op Ar .protocol 70instead of the filesystem. 71.Nm 72then updates 73.Pa /etc/resolv.conf 74as it thinks best. 75When a local resolver other than libc is installed, such as 76.Xr dnsmasq 8 77or 78.Xr named 8 , 79then 80.Nm 81will supply files that the resolver should be configured to include. 82.Pp 83.Nm 84assumes it has a job to do. 85In some situations 86.Nm 87needs to act as a deterrent to writing to 88.Pa /etc/resolv.conf . 89Where this file cannot be made immutable or you just need to toggle this 90behaviour, 91.Nm 92can be disabled by adding 93.Sy resolvconf Ns = Ns NO 94to 95.Xr resolvconf.conf 5 . 96.Pp 97.Nm 98can mark an interfaces 99.Pa resolv.conf 100as private. 101This means that the name servers listed in that 102.Pa resolv.conf 103are only used for queries against the domain/search listed in the same file. 104This only works when a local resolver other than libc is installed. 105See 106.Xr resolvconf.conf 5 107for how to configure 108.Nm 109to use a local name server. 110.Pp 111.Nm 112can mark an interfaces 113.Pa resolv.conf 114as exclusive. 115Only the latest exclusive interface is used for processing, otherwise all are. 116.Pp 117When an interface goes down, it should then call 118.Nm 119with 120.Fl d Ar interface.* 121arguments to delete the 122.Pa resolv.conf 123file(s) for all the 124.Ar protocols 125on the 126.Ar interface . 127.Pp 128Here are some more options that 129.Nm 130has:- 131.Bl -tag -width indent 132.It Fl I 133Initialise the state directory 134.Pa @VARDIR@ . 135This only needs to be called if the initial system boot sequence does not 136automatically clean it out; for example the state directory is moved 137somewhere other than 138.Pa /var/run . 139If used, it should only be called once as early in the system boot sequence 140as possible and before 141.Nm 142is used to add interfaces. 143.It Fl f 144Ignore non existant interfaces. 145Only really useful for deleting interfaces. 146.It Fl i Ar pattern 147List the interfaces and protocols, optionally matching 148.Ar pattern , 149we have 150.Pa resolv.conf 151files for. 152.It Fl l Ar pattern 153List the 154.Pa resolv.conf 155files we have. 156If 157.Ar pattern 158is specified then we list the files for the interfaces and protocols 159that match it. 160.It Fl m Ar metric 161Set the metric of the interface when adding it, default of 0. 162Lower metrics take precedence. 163This affects the default order of interfaces when listed. 164.It Fl p 165Marks the interface 166.Pa resolv.conf 167as private. 168.It Fl u 169Force 170.Nm 171to update all its subscribers. 172.Nm 173does not update the subscribers when adding a resolv.conf that matches 174what it already has for that interface. 175.It Fl x 176Mark the interface 177.Pa resolv.conf 178as exclusive when adding, otherwise only use the latest exclusive interface. 179.El 180.Pp 181.Nm 182also has some options designed to be used by its subscribers:- 183.Bl -tag -width indent 184.It Fl v 185Echo variables DOMAINS, SEARCH and NAMESERVERS so that the subscriber can 186configure the resolver easily. 187.It Fl V 188Same as 189.Fl v 190except that only the information configured in 191.Xr resolvconf.conf 5 192is set. 193.El 194.Sh INTERFACE ORDERING 195For 196.Nm 197to work effectively, it has to process the resolv.confs for the interfaces 198in the correct order. 199.Nm 200first processes interfaces from the 201.Sy interface_order 202list, then interfaces without a metic and that match the 203.Sy dynamic_order 204list, then interfaces with a metric in order and finally the rest in 205the operating systems lexical order. 206See 207.Xr resolvconf.conf 5 208for details on these lists. 209.Sh PROTOCOLS 210Here are some suggested protocol tags to use for each 211.Pa resolv.conf 212file registered on an 213.Ar interface Ns No :- 214.Bl -tag -width indent 215.It dhcp 216Dynamic Host Configuration Protocol. 217Initial versions of 218.Nm 219did not recommend a 220.Ar protocol 221tag be appended to the 222.Ar interface 223name. 224When the protocol is absent, it is assumed to be the DHCP protocol. 225.It ppp 226Point-to-Point Protocol. 227.It ra 228IPv6 Router Advertisement. 229.It dhcp6 230Dynamic Host Configuration Protocol, version 6. 231.El 232.Sh IMPLEMENTATION NOTES 233If a subscriber has the executable bit then it is executed otherwise it is 234assumed to be a shell script and sourced into the current environment in a 235subshell. 236This is done so that subscribers can remain fast, but are also not limited 237to the shell language. 238.Pp 239Portable subscribers should not use anything outside of 240.Pa /bin 241and 242.Pa /sbin 243because 244.Pa /usr 245and others may not be available when booting. 246Also, it would be unwise to assume any shell specific features. 247.Sh ENVIRONMENT 248.Bl -ohang 249.It Va IF_METRIC 250If the 251.Fl m 252option is not present then we use 253.Va IF_METRIC 254for the metric. 255.It Va IF_PRIVATE 256Marks the interface 257.Pa resolv.conf 258as private. 259.It Va IF_EXCLUSIVE 260Marks the interface 261.Pa resolv.conf 262as exclusive. 263.El 264.Sh FILES 265.Bl -ohang 266.It Pa /etc/resolv.conf.bak 267Backup file of the original resolv.conf. 268.It Pa @SYSCONFDIR@/resolvconf.conf 269Configuration file for 270.Nm . 271.It Pa @LIBEXECDIR@ 272Directory of subscribers which are run every time 273.Nm 274adds, deletes or updates. 275.It Pa @LIBEXECDIR@/libc.d 276Directory of subscribers which are run after the libc subscriber is run. 277.It Pa @VARDIR@ 278State directory for 279.Nm . 280.El 281.Sh HISTORY 282This implementation of 283.Nm 284is called openresolv and is fully command line compatible with Debian's 285resolvconf, as written by Thomas Hood. 286.Sh SEE ALSO 287.Xr resolv.conf 5 , 288.Xr resolvconf.conf 5 , 289.Xr resolver 3 , 290.Xr stdin 3 291.Sh AUTHORS 292.An Roy Marples Aq Mt roy@marples.name 293.Sh BUGS 294Please report them to 295.Lk http://roy.marples.name/projects/openresolv 296.Pp 297.Nm 298does not validate any of the files given to it. 299.Pp 300When running a local resolver other than libc, you will need to configure it 301to include files that 302.Nm 303will generate. 304You should consult 305.Xr resolvconf.conf 5 306for instructions on how to configure your resolver. 307