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