1.\" Copyright (c) 2007-2009 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 December 3, 2009 26.Dt RESOLVCONF 8 SMM 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.Fl a Ar interface No < Ns Pa file 38.Nm 39.Op Fl f 40.Fl d Ar interface 41.Nm 42.Fl il Ar pattern 43.Nm 44.Fl u 45.Sh DESCRIPTION 46.Nm 47manages 48.Xr resolv.conf 5 49files from multiple sources, such as DHCP and VPN clients. 50Traditionally, the host runs just one client and that updates 51.Pa /etc/resolv.conf . 52More modern systems frequently have wired and wireless interfaces and there is 53no guarantee both are on the same network. 54With the advent of VPN and other 55types of networking daemons, many things now contend for the contents of 56.Pa /etc/resolv.conf . 57.Pp 58.Nm 59solves this by letting the daemon send their 60.Xr resolv.conf 5 61file to 62.Nm 63via 64.Xr stdin 3 65with the argument 66.Fl a Ar interface 67instead of the filesystem. 68.Nm 69then updates 70.Pa /etc/resolv.conf 71as it thinks best. 72When a local resolver other than libc is installed, such as 73.Xr dnsmasq 8 74or 75.Xr named 8 , 76then 77.Nm 78will supply files that the resolver should be configured to include. 79.Pp 80.Nm 81can mark an interfaces 82.Pa resolv.conf 83as private. 84This means that the name servers listed in that 85.Pa resolv.conf 86are only used for queries against the domain/search listed in the same file. 87This only works when a local resolver other than libc is installed. 88See 89.Xr resolvconf.conf 5 90for how to configure 91.Nm 92to use a local name server. 93.Pp 94When an interface goes down, it should then call 95.Nm 96with 97.Fl d Ar interface 98arguments to delete the 99.Pa resolv.conf 100file for the 101.Ar interface . 102.Pp 103Here are some more options that 104.Nm 105has:- 106.Bl -tag -width indent 107.It Fl I 108Initialise the state directory 109.Pa @VARDIR@ . 110This only needs to be called if the initial system boot sequence does not 111automatically clean it out; for example the state directory is moved 112somewhere other than 113.Pa /var/run . 114If used, it should only be called once as early in the system boot sequence 115as possible and before 116.Nm 117is used to add interfaces. 118.It Fl f 119Ignore non existant interfaces. 120Only really useful for deleting interfaces. 121.It Fl i Ar pattern 122List the interfaces, optionally matching 123.Ar pattern , 124we have 125.Pa resolv.conf 126files for. 127.It Fl l Ar pattern 128List the 129.Pa resolv.conf 130files we have. 131If 132.Ar pattern 133is specified then we list the files for the interfaces that match it. 134.It Fl m Ar metric 135Set the metric of the interface when adding it, default of 0. 136Lower metrics take precedence. 137This affects the default order of interfaces when listed. 138.It Fl p 139Marks the interface 140.Pa resolv.conf 141as private. 142.It Fl u 143Force 144.Nm 145to update all it's subscribers. 146.Nm 147does not update the subscribers when adding a resolv.conf that matches 148what it already has for that interface. 149.El 150.Pp 151.Nm 152also has some options designed to be used by it's subscribers:- 153.Bl -tag -width indent 154.It Fl v 155Echo variables DOMAINS, SEARCH and NAMESERVERS so that the subscriber can 156configure the resolver easily. 157.El 158.Sh INTERFACE ORDERING 159For 160.Nm 161to work effectively, it has to process the resolv.confs for the interfaces 162in the correct order. 163.Nm 164first processes interfaces from the 165.Sy interface_order 166list, then interfaces without a metic and that match the 167.Sy dynamic_order 168list, then interfaces with a metric in order and finally the rest in 169the operating systems lexical order. 170See 171.Xr resolvconf.conf 5 172for details on these lists. 173.Sh IMPLEMENTATION NOTES 174If a subscriber has the executable bit then it is executed otherwise it is 175assumed to be a shell script and sourced into the current environment in a 176subshell. 177This is done so that subscribers can remain fast, but are also not limited 178to the shell language. 179.Pp 180Portable subscribers should not use anything outside of 181.Pa /bin 182and 183.Pa /sbin 184because 185.Pa /usr 186and others may not be available when booting. 187Also, it would be unwise to assume any shell specific features. 188.Sh ENVIRONMENT 189.Bl -ohang 190.It Va IF_METRIC 191If the 192.Fl m 193option is not present then we use 194.Va IF_METRIC 195for the metric. 196.It Va IF_PRIVATE 197Marks the interface 198.Pa resolv.conf 199as private. 200.El 201.Sh FILES 202.Bl -ohang 203.It Pa @SYSCONFDIR@/resolvconf.conf 204Configuration file for 205.Nm . 206.It Pa @LIBEXECDIR@ 207Directory of subscribers which are run every time 208.Nm 209adds, deletes or updates. 210.It Pa @LIBEXECDIR@/libc.d 211Directory of subscribers which are run after the libc subscriber is run. 212.It Pa @VARDIR@ 213State directory for 214.Nm . 215.El 216.Sh HISTORY 217This implementation of 218.Nm 219is called openresolv and is fully command line compatible with Debian's 220resolvconf, as written by Thomas Hood. 221.Sh BUGS 222.Nm 223does not validate any of the files given to it. 224.Pp 225When running a local resolver other than libc, you will need to configure it 226to include files that 227.Nm 228will generate. 229You should consult 230.Xr resolvconf.conf 5 231for instructions on how to configure your resolver. 232.Sh SEE ALSO 233.Xr resolv.conf 5 , 234.Xr resolvconf.conf 5 , 235.Xr resolver 3 , 236.Xr stdin 3 237.Sh AUTHORS 238.An Roy Marples Aq roy@marples.name 239.Sh BUGS 240Please report them to http://roy.marples.name/projects/openresolv 241