roy.marples.name Git - openresolv/blob - 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).