whitespace
[openresolv] / resolvconf.8.in
1 .TH RESOLVCONF 8 "9 Nov 2007" "openresolv" "openresolv"
2 .SH NAME
3 resolvconf \- manage nameserver information
4 .SH SYNOPSIS
5 cat \fIFILE\fR |
6 .B resolvconf
7 \fB\-a\fR \fIINTERFACE\fR
8 .PP
9 .B resolvconf
10 \fB\-d\fR \fIINTERFACE\fR
11 .PP
12 .B resolvconf
13 \fB\-u\fR
14 .PP
15 .B resolvconf
16 \fB\-l\fR \fIPATTERN\fR
17 .PP
18 .B resolvconf
19 \fB\-i\fR \fIPATTERN\fR
20 .PP
21 .B resolvconf
22 \fB\-v\fR \fIPATTERN\fR
23 .PP
24 .B resolvconf
25 \fB\-s\fR \fISERVICE COMMAND [args]\fR
26 .SH DESCRIPTION
27 Overwrite (\fB\-a\fR) or delete (\fB\-d\fR) the nameserver information
28 record for network interface \fIINTERFACE\fR
29 and run the update scripts in \fI%%PREFIX%%/etc/resolvconf/update.d/\fR.
30 .PP
31 With \fB\-u\fR, just run the update scripts.
32 .PP
33 With \fB\-l\fR, list the resolv files for each interface, optionally
34 with patterns to match interface names.
35 .PP
36 With \fB\-i\fR, list the interfaces we have resolv files for, optionally
37 with patterns to match interface names.
38 .PP
39 With \fB\-v\fR, we echo variables NEWDOMAIN, NEWSEARCH and NEWNS to the
40 console which can be used to make it easer writing scripts which configure
41 DNS resolvers.
42 .PP
43 With \fB\-s\fR, we work out if the service is running by finding its pidfile
44 and if it is we restart it. This means that only resolvconf needs to know this
45 for supported platforms and subscribers can just call this resolvconf function.
46 .SH SERVERS
47 Normally
48 .B resolvconf
49 is run only by hook scripts attached to network interface configurers
50 such as
51 .BR pppd (8) 
52 (for ppp interfaces),
53 to DHCP clients such as
54 .BR dhcpcd (8),
55 to
56 .BR /etc/init.d/net.eth0 
57 and
58 .BR openvpn ,
59 and
60 to DNS caches such as
61 .BR dnsmasq (8)
62 (for the loopback interface).
63 However, the administrator can also run
64 .B resolvconf
65 from the command line to add or delete auxiliary nameserver information.
66 .SH CLIENTS
67 Nameserver information provided to
68 .B resolvconf
69 is stored for use by subscribers to \fBresolvconf\fR's notification service.
70 Subscribers that need to know when nameserver information has changed
71 should install a script in \fI%%PREFIX%%/etc/resolvconf/update.d/\fR
72 (... or in \fI%%PREFIX%%/etc/resolvconf/update-libc.d/\fR: see below).
73 For example, DNS caches such as
74 .BR dnsmasq (8)
75 and
76 .BR pdnsd (8)
77 subscribe to the notification service so that they know
78 whither to forward queries.
79 .PP
80 The most important piece of
81 software that subscribes to the notification service is the set of functions
82 that make up the GNU C Library
83 .BR resolver (3).
84 When nameserver information is updated the script
85 \fI%%PREFIX%%/etc/resolvconf/update.d/libc\fR writes a new resolver configuration
86 file to \fI%%PREFIX%%/etc/resolvconf/run/resolv.conf\fR and then runs the scripts in
87 %%PREFIX%%/etc/resolvconf/update-libc.d/.
88 To make the resolver use the dynamically generated resolver configuration
89 file the administrator should ensure that \fI/etc/resolv.conf\fR is a symbolic
90 link to \fI%%PREFIX%%/etc/resolvconf/run/resolv.conf\fR.
91 This link is never modified by \fB/sbin/resolvconf\fR.
92 If you find that \fI/etc/resolv.conf\fR is not being updated,
93 check to see that the link is intact.
94 .PP
95 The C Library resolver library isn't the only resolver library available.
96 However, any resolver library that reads /etc/resolv.conf
97 (and most of them do, in order to be compatible with the C Library resolver)
98 should work with \fBresolvconf\fR.
99 .PP
100 \fBopenresolv\fR ships with subscribers for
101 .BR dnsmasq (8)
102 and
103 .BR named (8)
104 wwhich handle resolv.conf a bit differently. If they handle search AND domain
105 options then the nameservers listed with the domain are only used when
106 querying for that domain.
107 .TP
108 Example
109 .nf
110 # resolv.conf from bge0
111 # search foo.com
112 # nameserver 1.2.3.4
113
114 # resolv.conf from tap0
115 # domain bar.org
116 # nameserver 5.6.7.8
117 .fi
118 .PP
119 In this instance, nameserver 5.6.7.8 will only handle requests for bar.org
120 and nameserver 1.2.3.4 will handle everything else.
121 .PP
122 Subscribers that need to know only when the resolver configuration file
123 has changed should install a script in \fI/etc/resolvconf/update-libc.d/\fR
124 rather than in \fI%%PREFIX%%/etc/resolvconf/update.d/\fR.
125 (This is important for synchronization purposes:
126 scripts in \fIupdate-libc.d/\fR are run after resolv.conf has been updated;
127 the same is not necessarily true of scripts in update.d/.)
128 .SH OPTIONS
129 .TP
130 \fB\-a\fR \fIINTERFACE\fR
131 Add or overwrite the record for network interface \fIINTERFACE\fR.
132 When this option is used the information must be provided to
133 .B resolvconf
134 on its standard input in the format of the
135 .BR resolv.conf (5)
136 file.
137 Each line in the file must be terminated by a newline.
138 .TP
139 \fB\-d\fR \fIINTERFACE\fR
140 Delete the record for network interface \fIINTERFACE\fR.
141 .PP
142 The \fIINTERFACE\fR name may not contain spaces, slashes, asterisks or
143 initial dots, hyphens or tildes.
144 .PP
145 Following the addition or deletion of the record, resolvconf runs
146 the update scripts as described in the CLIENTS section.
147 .TP
148 \fB\-u\fR
149 Just run the update scripts.
150 .TP
151 \fB\-l\fR \fIPATTERN\fR
152 List the resolv.conf files for the interfaces that match the pattern,
153 otherwise all the interfaces.
154 .TP
155 \fB\-i\fR \fIPATTERN\fR
156 List the interfaces that match the pattern otherwise all the interfaces.
157 .TP
158 \fB\-v\fR \fIPATTERN\fR
159 Echo variables NEWDOMAIN, NEWSEARCH and NEWNS to the console.
160 .SH FILES
161 .TP
162 .I %%PREFIX%%/etc/resolvconf/run
163 This is either a directory where nameserver information can be stored
164 or a symbolic link to such a directory.
165 Clients should not make any assumptions about the canonical location
166 of this directory or the hierarchy that is constructed under it.
167 .TP
168 .I %%PREFIX%%/etc/resolvconf/interface-order
169 Determines the order in which nameserver information records are processed
170 by resolvconf -l.
171 .TP
172 .I %%PREFIX%%/etc/resolvconf/resolv.conf.d/base
173 File containing basic resolver information.
174 The lines in this file are included in the resolver configuration file
175 even when no interfaces are configured.
176 .TP
177 .I %%PREFIX%%/etc/resolvconf/resolv.conf.d/head
178 File to be prepended to the dynamically generated resolver configuration file.
179 Normally this is just a comment line.
180 .TP
181 .I %%PREFIX%%/etc/resolvconf/reslov.conf.d/tail
182 File to be appended to the dynamically generated resolver configuration file.
183 To append nothing, make this an empty file.
184 .SH BUGS
185 Currently
186 .B resolvconf
187 does not check the sanity of the information provided to it.
188 .SH AUTHOR
189 Written by Roy Marples <roy@marples.name>.
190 .br
191 Heavily based on Debians resolvconf by Thomas Hood <jdthood_AT_yahoo.co.uk>
192 .SH COPYRIGHT
193 Copyright \(co 2006 Gentoo Foundation
194 .br
195 Copyright \(co 2007 Roy Marples
196 .SH "SEE ALSO"
197 .BR resolv.conf (5),
198 .BR resolver (3).