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