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