1 .\" Copyright (c) 2007-2016 Roy Marples
2 .\" All rights reserved
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
30 .Nd a framework for managing multiple DNS configurations
38 .Fl a Ar interface Ns Op Ar .protocol
42 .Fl d Ar interface Ns Op Ar .protocol
54 files from multiple sources, such as DHCP and VPN clients.
55 Traditionally, the host runs just one client and that updates
56 .Pa /etc/resolv.conf .
57 More modern systems frequently have wired and wireless interfaces and there is
58 no guarantee both are on the same network.
59 With the advent of VPN and other
60 types of networking daemons, many things now contend for the contents of
61 .Pa /etc/resolv.conf .
64 solves this by letting the daemon send their
71 .Fl a Ar interface Ns Op Ar .protocol
72 instead of the filesystem.
77 When a local resolver other than libc is installed, such as
83 will supply files that the resolver should be configured to include.
86 assumes it has a job to do.
89 needs to act as a deterrent to writing to
90 .Pa /etc/resolv.conf .
91 Where this file cannot be made immutable or you just need to toggle this
94 can be disabled by adding
95 .Sy resolvconf Ns = Ns NO
97 .Xr resolvconf.conf 5 .
100 can mark an interfaces
103 This means that the name servers listed in that
105 are only used for queries against the domain/search listed in the same file.
106 This only works when a local resolver other than libc is installed.
108 .Xr resolvconf.conf 5
111 to use a local name server and how to remove the private marking.
114 can mark an interfaces
117 Only the latest exclusive interface is used for processing, otherwise all are.
119 When an interface goes down, it should then call
123 arguments to delete the
130 Here are some options for the above commands:-
131 .Bl -tag -width pattern_opt
133 Ignore non existent interfaces.
134 Only really useful for deleting interfaces.
136 Set the metric of the interface when adding it, default of 0.
137 Lower metrics take precedence.
138 This affects the default order of interfaces when listed.
146 as exclusive when adding, otherwise only use the latest exclusive interface.
150 has some more commands for general usage:-
151 .Bl -tag -width pattern_opt
153 List the interfaces and protocols, optionally matching
164 is specified then we list the files for the interfaces and protocols
169 to update all its subscribers.
171 does not update the subscribers when adding a resolv.conf that matches
172 what it already has for that interface.
174 Echo the resolvconf version to
179 also has some commands designed to be used by it's subscribers and
181 .Bl -tag -width pattern_opt
183 Initialise the state directory
185 This only needs to be called if the initial system boot sequence does not
186 automatically clean it out; for example the state directory is moved
189 If used, it should only be called once as early in the system boot sequence
190 as possible and before
192 is used to add interfaces.
194 Echo the command used to restart a service.
198 is running then restart it.
199 If the service does not exist or is not running then zero is returned,
200 otherwise the result of restarting the service.
202 Echo variables DOMAINS, SEARCH and NAMESERVERS so that the subscriber can
203 configure the resolver easily.
207 except that only the information configured in
208 .Xr resolvconf.conf 5
211 .Sh INTERFACE ORDERING
214 to work effectively, it has to process the resolv.confs for the interfaces
215 in the correct order.
217 first processes interfaces from the
219 list, then interfaces without a metic and that match the
221 list, then interfaces with a metric in order and finally the rest in
222 the operating systems lexical order.
224 .Xr resolvconf.conf 5
225 for details on these lists.
227 Here are some suggested protocol tags to use for each
229 file registered on an
230 .Ar interface Ns No :-
231 .Bl -tag -width pattern_opt
233 Dynamic Host Configuration Protocol.
238 tag be appended to the
241 When the protocol is absent, it is assumed to be the DHCP protocol.
243 Point-to-Point Protocol.
245 IPv6 Router Advertisement.
247 Dynamic Host Configuration Protocol, version 6.
249 .Sh IMPLEMENTATION NOTES
250 If a subscriber has the executable bit then it is executed otherwise it is
251 assumed to be a shell script and sourced into the current environment in a
253 This is done so that subscribers can remain fast, but are also not limited
254 to the shell language.
256 Portable subscribers should not use anything outside of
262 and others may not be available when booting.
263 Also, it would be unwise to assume any shell specific features.
269 option is not present then we use
283 .It Pa /etc/resolv.conf.bak
284 Backup file of the original resolv.conf.
285 .It Pa @SYSCONFDIR@/resolvconf.conf
286 Configuration file for
289 Directory of subscribers which are run every time
291 adds, deletes or updates.
292 .It Pa @LIBEXECDIR@/libc.d
293 Directory of subscribers which are run after the libc subscriber is run.
302 .Xr resolvconf.conf 5
304 This implementation of
306 is called openresolv and is fully command line compatible with Debian's
307 resolvconf, as written by Thomas Hood.
309 .An Roy Marples Aq Mt roy@marples.name
311 Please report them to
312 .Lk http://roy.marples.name/projects/openresolv
315 does not validate any of the files given to it.
317 When running a local resolver other than libc, you will need to configure it
318 to include files that
322 .Xr resolvconf.conf 5
323 for instructions on how to configure your resolver.