1 .\" Copyright 2007-2008 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
25 .Dd September 17, 2008
29 .Nd a framework for managing multiple DNS configurations
33 .Fl a Ar interface No < Ns Pa file
45 files from multiple sources, such as DHCP and VPN clients.
46 Traditionally, the host runs just one client and that updates
47 .Pa /etc/resolv.conf .
48 More modern systems frequently have wired and wireless interfaces and there is
49 no guarantee both are on the same network.
50 With the advent of VPN and other
51 types of networking daemons, many things now contend for the contents of
52 .Pa /etc/resolv.conf .
55 solves this by letting the daemon send their
63 instead of the filesystem.
68 When a local resolver other than libc is installed, such as
74 will supply files that the resolver should be configured to include.
77 to configure the local resolver such that
79 files specifiying a domain only query the listed nameservers when resolving
81 Otherwise the nameservers are treated as global nameservers.
82 This in turn means, that you can trivially configure nameservers for say
85 .Bd -literal -offset indent
86 # resolv.conf from bge0
90 # resolv.conf from tap0
95 In this instance, nameserver 5.6.7.8 will only handle requests for bar.org
96 and nameserver 1.2.3.4 will handle everything else.
98 When an interface goes down, it should then call
102 arguments to delete the
107 Here are some more options that
110 .Bl -tag -width indent
112 Ignore non existant interfaces.
113 Only really useful for deleting interfaces.
115 List the interfaces, optionally matching
126 is specified then we list the files for the interfaces that match it.
128 Set the metric of the interface when adding it, default of 0.
129 Lower metrics take precedence.
130 This affects the default order of interfaces when listed.
134 to update all it's helpers.
136 does not update the helpers when adding a reslov.conf that matches
137 what it already has for that interface.
141 also has some options designed to be used by it's helpers:-
142 .Bl -tag -width indent
143 .It Fl s Ar service Ar command ...
148 Normally this is something like
149 .Ar resolvconf -s named restart .
150 We have this command, so the helpers don't have to know too much about the
151 operating system on the host.
153 Echo variables NEWDOMAIN, NEWSEARCH and NEWNS so that the helper can configure
161 option is not present then we use
167 .It Pa @VARBASE@/run/resolvconf
168 Directory that holds the data for
170 .It Pa @SYSCONFDIR@/update.d
171 Directory of the helper scripts which are run every time
173 adds, deletes or updates.
174 .It Pa @SYSCONFDIR@/update-libc.d
175 Directory of helper scripts which are run after the libc helper script is run.
176 .It Pa @SYSCONFDIR@/interface-order
177 Determines the order in which nameserver information records are processed
179 .It Pa @SYSCONFDIR@/resolv.conf.d/base
180 Contains basic resolver information which is included in
182 even when no interfaces are configured.
183 .It Pa @SYSCONFDIR@/resolv.conf.d/head
184 File to be prepended to
185 .Pa /etc/resolv.conf .
186 Normally this is just a comment line.
187 .It Pa @SYSCONFDIR@/resolv.conf.d/tail
188 File to be appended to
189 .Pa /etc/resolv.conf .
192 This implementation of
194 is called openresolv and is fully command line compatible with Debians
195 resolvconf, as written by Thomas Hood, on which openresolv is based.
196 openresolv also shares a similar directory structure with the Debian version,
197 but the included helpers are not compatible.
199 The Debian version only works with bash and other GNU userland tools, whereas
200 openresolv works with a POSIX shell and userland tools.
203 does not validate any of the files given to it.
205 When running a local resolver other than libc, you will need to configure it
206 to include files that
209 You should consult the comment section in the helper script
210 for your resolver found in @SYSCONFDIR@/update.d for instructions
219 .An Roy Marples <roy@marples.name>
221 Please report them to http://bugs.marples.name