1.\" Copyright (c) 2007-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 May 7, 2016 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 4 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 options for the above commands:- 129.Bl -tag -width indent 130.It Fl f 131Ignore non existent interfaces. 132Only really useful for deleting interfaces. 133.It Fl m Ar metric 134Set the metric of the interface when adding it, default of 0. 135Lower metrics take precedence. 136This affects the default order of interfaces when listed. 137.It Fl p 138Marks the interface 139.Pa resolv.conf 140as private. 141.It Fl x 142Mark the interface 143.Pa resolv.conf 144as exclusive when adding, otherwise only use the latest exclusive interface. 145.El 146.Pp 147.Nm 148has some more commands for general usage:- 149.Bl -tag -width indent 150.It Fl i Ar pattern 151List the interfaces and protocols, optionally matching 152.Ar pattern , 153we have 154.Pa resolv.conf 155files for. 156.It Fl l Ar pattern 157List the 158.Pa resolv.conf 159files we have. 160If 161.Ar pattern 162is specified then we list the files for the interfaces and protocols 163that match it. 164.It Fl u 165Force 166.Nm 167to update all its subscribers. 168.Nm 169does not update the subscribers when adding a resolv.conf that matches 170what it already has for that interface. 171.El 172.Pp 173.Nm 174also has some commands designed to be used by it's subscribers and 175system startup:- 176.Bl -tag -width indent 177.It Fl I 178Initialise the state directory 179.Pa @VARDIR@ . 180This only needs to be called if the initial system boot sequence does not 181automatically clean it out; for example the state directory is moved 182somewhere other than 183.Pa /var/run . 184If used, it should only be called once as early in the system boot sequence 185as possible and before 186.Nm 187is used to add interfaces. 188.It Fl R 189Echo the command used to restart a service. 190.It Fl r Ar service 191If the 192.Ar service 193is running then restart it. 194If the service does not exist or is not running then zero is returned, 195otherwise the result of restarting the service. 196.It Fl v 197Echo variables DOMAINS, SEARCH and NAMESERVERS so that the subscriber can 198configure the resolver easily. 199.It Fl V 200Same as 201.Fl v 202except that only the information configured in 203.Xr resolvconf.conf 5 204is set. 205.El 206.Sh INTERFACE ORDERING 207For 208.Nm 209to work effectively, it has to process the resolv.confs for the interfaces 210in the correct order. 211.Nm 212first processes interfaces from the 213.Sy interface_order 214list, then interfaces without a metic and that match the 215.Sy dynamic_order 216list, then interfaces with a metric in order and finally the rest in 217the operating systems lexical order. 218See 219.Xr resolvconf.conf 5 220for details on these lists. 221.Sh PROTOCOLS 222Here are some suggested protocol tags to use for each 223.Pa resolv.conf 224file registered on an 225.Ar interface Ns No :- 226.Bl -tag -width indent 227.It dhcp 228Dynamic Host Configuration Protocol. 229Initial versions of 230.Nm 231did not recommend a 232.Ar protocol 233tag be appended to the 234.Ar interface 235name. 236When the protocol is absent, it is assumed to be the DHCP protocol. 237.It ppp 238Point-to-Point Protocol. 239.It ra 240IPv6 Router Advertisement. 241.It dhcp6 242Dynamic Host Configuration Protocol, version 6. 243.El 244.Sh IMPLEMENTATION NOTES 245If a subscriber has the executable bit then it is executed otherwise it is 246assumed to be a shell script and sourced into the current environment in a 247subshell. 248This is done so that subscribers can remain fast, but are also not limited 249to the shell language. 250.Pp 251Portable subscribers should not use anything outside of 252.Pa /bin 253and 254.Pa /sbin 255because 256.Pa /usr 257and others may not be available when booting. 258Also, it would be unwise to assume any shell specific features. 259.Sh ENVIRONMENT 260.Bl -ohang 261.It Va IF_METRIC 262If the 263.Fl m 264option is not present then we use 265.Va IF_METRIC 266for the metric. 267.It Va IF_PRIVATE 268Marks the interface 269.Pa resolv.conf 270as private. 271.It Va IF_EXCLUSIVE 272Marks the interface 273.Pa resolv.conf 274as exclusive. 275.El 276.Sh FILES 277.Bl -ohang 278.It Pa /etc/resolv.conf.bak 279Backup file of the original resolv.conf. 280.It Pa @SYSCONFDIR@/resolvconf.conf 281Configuration file for 282.Nm . 283.It Pa @LIBEXECDIR@ 284Directory of subscribers which are run every time 285.Nm 286adds, deletes or updates. 287.It Pa @LIBEXECDIR@/libc.d 288Directory of subscribers which are run after the libc subscriber is run. 289.It Pa @VARDIR@ 290State directory for 291.Nm . 292.El 293.Sh SEE ALSO 294.Xr resolver 3 , 295.Xr stdin 4 , 296.Xr resolv.conf 5 , 297.Xr resolvconf.conf 5 298.Sh HISTORY 299This implementation of 300.Nm 301is called openresolv and is fully command line compatible with Debian's 302resolvconf, as written by Thomas Hood. 303.Sh AUTHORS 304.An Roy Marples Aq Mt roy@marples.name 305.Sh BUGS 306Please report them to 307.Lk http://roy.marples.name/projects/openresolv 308.Pp 309.Nm 310does not validate any of the files given to it. 311.Pp 312When running a local resolver other than libc, you will need to configure it 313to include files that 314.Nm 315will generate. 316You should consult 317.Xr resolvconf.conf 5 318for instructions on how to configure your resolver. 319