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