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

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