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