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