roy.marples.name Git - openresolv/blob - resolvconf.8

   1 .\" $Id$
   2 .\"
   3 .TH RESOLVCONF 8 "9 Nov 2007" "openresolv"
   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 dhcpcd (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 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 C Library resolver)
  93 should work with \fBresolvconf\fR.
  94 .PP
  95 \fBopenresolv\fR ships with subscribers for
  96 .BR dnsmasq (8)
  97 and
  98 .BR named (8)
  99 wwhich handle resolv.conf a bit differently. If they handle search AND domain
 100 options then the nameservers listed with the domain are only used when
 101 querying for that domain.
 102 .TP
 103 Example
 104 .nf
 105 # resolv.conf from bge0
 106 # search foo.com
 107 # nameserver 1.2.3.4
 108
 109 # resolv.conf from tap0
 110 # domain bar.org
 111 # nameserver 5.6.7.8
 112 .fi
 113 .PP
 114 In this instance, nameserver 5.6.7.8 will only handle requests for bar.org
 115 and nameserver 1.2.3.4 will handle everything else.
 116 .PP
 117 Subscribers that need to know only when the resolver configuration file
 118 has changed should install a script in \fI/etc/resolvconf/update-libc.d/\fR
 119 rather than in \fI/etc/resolvconf/update.d/\fR.
 120 (This is important for synchronization purposes:
 121 scripts in \fIupdate-libc.d/\fR are run after resolv.conf has been updated;
 122 the same is not necessarily true of scripts in update.d/.)
 123 .SH OPTIONS
 124 .TP
 125 \fB\-a\fR \fIINTERFACE\fR
 126 Add or overwrite the record for network interface \fIINTERFACE\fR.
 127 When this option is used the information must be provided to
 128 .B resolvconf
 129 on its standard input in the format of the
 130 .BR resolv.conf (5)
 131 file.
 132 Each line in the file must be terminated by a newline.
 133 .TP
 134 \fB\-d\fR \fIINTERFACE\fR
 135 Delete the record for network interface \fIINTERFACE\fR.
 136 .PP
 137 The \fIINTERFACE\fR name may not contain spaces, slashes, asterisks or
 138 initial dots, hyphens or tildes.
 139 .PP
 140 Following the addition or deletion of the record, resolvconf runs
 141 the update scripts as described in the CLIENTS section.
 142 .TP
 143 \fB\-u\fR
 144 Just run the update scripts.
 145 .TP
 146 \fB\-l\fR \fIPATTERN\fR
 147 List the resolv.conf files for the interfaces that match the pattern,
 148 otherwise all the interfaces.
 149 .TP
 150 \fB\-i\fR \fIPATTERN\fR
 151 List the interfaces that match the pattern otherwise all the interfaces.
 152 .TP
 153 \fB\-v\fR \fIPATTERN\fR
 154 Echo variables NEWDOMAIN, NEWSEARCH and NEWNS to the console.
 155 .SH FILES
 156 .TP
 157 .I /etc/resolvconf/run
 158 This is either a directory where nameserver information can be stored
 159 or a symbolic link to such a directory.
 160 Clients should not make any assumptions about the canonical location
 161 of this directory or the hierarchy that is constructed under it.
 162 .TP
 163 .I /etc/resolvconf/interface-order
 164 Determines the order in which nameserver information records are processed
 165 by resolvconf -l.
 166 .TP
 167 .I /etc/resolvconf/resolv.conf.d/base
 168 File containing basic resolver information.
 169 The lines in this file are included in the resolver configuration file
 170 even when no interfaces are configured.
 171 .TP
 172 .I /etc/resolvconf/resolv.conf.d/head
 173 File to be prepended to the dynamically generated resolver configuration file.
 174 Normally this is just a comment line.
 175 .TP
 176 .I /etc/resolvconf/reslov.conf.d/tail
 177 File to be appended to the dynamically generated resolver configuration file.
 178 To append nothing, make this an empty file.
 179 .SH BUGS
 180 Currently
 181 .B resolvconf
 182 does not check the sanity of the information provided to it.
 183 .SH AUTHOR
 184 Written by Roy Marples <roy@marples.name>.
 185 .br
 186 Heavily based on Debians resolvconf by Thomas Hood <jdthood_AT_yahoo.co.uk>
 187 .SH COPYRIGHT
 188 Copyright \(co 2006 Gentoo Foundation
 189 .br
 190 Copyright \(co 2007 Roy Marples
 191 .SH "SEE ALSO"
 192 .BR resolv.conf (5),
 193 .BR resolver (3).