openresolv no longer applies any semantics to resolv.conf for
[openresolv] / resolvconf.8.in
1 .\" Copyright 2007-2008 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 October 01, 2008
26 .Dt RESOLVCONF 8 SMM
27 .Sh NAME
28 .Nm resolvconf
29 .Nd a framework for managing multiple DNS configurations
30 .Sh SYNOPSIS
31 .Nm
32 .Op Fl m Ar metric
33 .Op Fl p
34 .Fl a Ar interface No < Ns Pa file
35 .Nm
36 .Op Fl f
37 .Fl d Ar interface
38 .Nm
39 .Fl il Ar pattern
40 .Nm
41 .Fl u
42 .Sh DESCRIPTION
43 .Nm
44 manages
45 .Xr resolv.conf 5
46 files from multiple sources, such as DHCP and VPN clients.
47 Traditionally, the host runs just one client and that updates
48 .Pa /etc/resolv.conf .
49 More modern systems frequently have wired and wireless interfaces and there is
50 no guarantee both are on the same network.
51 With the advent of VPN and other
52 types of networking daemons, many things now contend for the contents of
53 .Pa /etc/resolv.conf .
54 .Pp
55 .Nm
56 solves this by letting the daemon send their
57 .Xr resolv.conf 5
58 file to
59 .Nm
60 via
61 .Xr stdin 3
62 with the argument
63 .Fl a Ar interface
64 instead of the filesystem.
65 .Nm
66 then updates
67 .Pa /etc/resolv.conf
68 as it thinks best.
69 When a local resolver other than libc is installed, such as
70 .Xr dnsmasq 8
71 or
72 .Xr named 8
73 then
74 .Nm
75 will supply files that the resolver should be configured to include.
76 .Pp
77 .Nm
78 can mark an interfaces
79 .Pa resolv.conf
80 as private.
81 This means that any queries for a host in the private domain or search
82 paths are only send to the nameservers in the same
83 .Pa resolv.conf .
84 If only private
85 .Pa resolv.conf
86 files exist then
87 .Nm installs them as global ones too.
88 This only works when a local resolver other than libc is installed.
89 Doing this, you would probably want
90 .Nm
91 to always configure
92 .Pa /etc/resolv.conf
93 with the local nameserver.
94 See
95 .Pa @SYSCONFDIR@/resolv.conf.d/base
96 below on how to do this.
97 .Pp
98 When an interface goes down, it should then call
99 .Nm
100 with
101 .Fl d Ar interface
102 arguments to delete the
103 .Pa resolv.conf
104 file for the
105 .Ar interface .
106 .Pp
107 Here are some more options that
108 .Nm
109 has:-
110 .Bl -tag -width indent
111 .It Fl f
112 Ignore non existant interfaces.
113 Only really useful for deleting interfaces.
114 .It Fl i Ar pattern
115 List the interfaces, optionally matching
116 .Ar pattern ,
117 we have
118 .Pa resolv.conf
119 files for.
120 .It Fl l Ar pattern
121 List the
122 .Pa resolv.conf
123 files we have.
124 If
125 .Ar pattern
126 is specified then we list the files for the interfaces that match it.
127 .It Fl m Ar metric
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.
131 .It Fl p
132 Marks the interface
133 .Pa resolv.conf
134 as private.
135 .It Fl u
136 Force
137 .Nm
138 to update all it's helpers.
139 .Nm
140 does not update the helpers when adding a reslov.conf that matches
141 what it already has for that interface.
142 .El
143 .Pp
144 .Nm
145 also has some options designed to be used by it's helpers:-
146 .Bl -tag -width indent
147 .It Fl s Ar service Ar command ...
148 Try and send the
149 .Ar command
150 to the system
151 .Ar service .
152 Normally this is something like
153 .Ar resolvconf -s named restart .
154 We have this command, so the helpers don't have to know too much about the
155 operating system on the host.
156 .It Fl v
157 Echo variables DOMAINS, SEARCH and NAMESERVERS so that the helper can configure
158 the resolver easily.
159 .El
160 .Sh ENVIRONMENT
161 .Bl -ohang
162 .It Va IF_METRIC
163 If the
164 .Fl m
165 option is not present then we use
166 .Va IF_METRIC
167 for the metric.
168 .It Va IF_PRIVATE
169 Marks the interface
170 .Pa resolv.conf
171 as private.
172 .El
173 .Sh FILES
174 .Bl -ohang
175 .It Pa @VARBASE@/run/resolvconf
176 Directory that holds the data for
177 .Nm .
178 .It Pa @SYSCONFDIR@/update.d
179 Directory of the helper scripts which are run every time
180 .Nm
181 adds, deletes or updates.
182 .It Pa @SYSCONFDIR@/update-libc.d
183 Directory of helper scripts which are run after the libc helper script is run.
184 .It Pa @SYSCONFDIR@/interface-order
185 Determines the order in which nameserver information records are processed
186 by resolvconf -l.
187 .It Pa @SYSCONFDIR@/private-interfaces
188 A list of interfaces who should be marked as private by default.
189 .It Pa @SYSCONFDIR@/resolv.conf.d/base
190 Contains basic resolver information which is included in
191 .Pa /etc/resolv.conf
192 even when no interfaces are configured.
193 This is a good place to set libc to always use your local nameserver like so:
194 .Bd -literal -offset indent
195 nameserver 127.0.0.1
196 .Ed
197 .It Pa @SYSCONFDIR@/resolv.conf.d/head
198 File to be prepended to
199 .Pa /etc/resolv.conf .
200 Normally this is just a comment line.
201 .It Pa @SYSCONFDIR@/resolv.conf.d/tail
202 File to be appended to
203 .Pa /etc/resolv.conf .
204 .El
205 .Sh HISTORY
206 This implementation of
207 .Nm
208 is called openresolv and is fully command line compatible with Debians
209 resolvconf, as written by Thomas Hood, on which openresolv is based.
210 openresolv also shares a similar directory structure with the Debian version,
211 but the included helpers are not compatible.
212 .Pp
213 The Debian version only works with bash and other GNU userland tools, whereas
214 openresolv works with a POSIX shell and userland tools.
215 .Sh BUGS
216 .Nm
217 does not validate any of the files given to it.
218 .Pp
219 When running a local resolver other than libc, you will need to configure it
220 to include files that
221 .Nm
222 will generate.
223 You should consult the comment section in the helper script
224 for your resolver found in @SYSCONFDIR@/update.d for instructions
225 on this.
226 .Sh SEE ALSO
227 .Xr dnsmasq 8 ,
228 .Xr named 8 ,
229 .Xr resolv.conf 5 ,
230 .Xr resolver 3 ,
231 .Xr stdin 3
232 .Sh AUTHORS
233 .An Roy Marples <roy@marples.name>
234 .Sh BUGS
235 Please report them to http://bugs.marples.name