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