external/bsd/openresolv/dist/resolvconf.8.in

   1 .\" Copyright (c) 2007-2015 Roy Marples
   2 .\" All rights reserved
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd April 27, 2015
  26 .Dt RESOLVCONF 8
  27 .Os
  28 .Sh NAME
  29 .Nm resolvconf
  30 .Nd a framework for managing multiple DNS configurations
  31 .Sh SYNOPSIS
  32 .Nm
  33 .Fl I
  34 .Nm
  35 .Op Fl m Ar metric
  36 .Op Fl p
  37 .Op Fl x
  38 .Fl a Ar interface Ns Op Ar .protocol
  39 .No < Ns Pa file
  40 .Nm
  41 .Op Fl f
  42 .Fl d Ar interface Ns Op Ar .protocol
  43 .Nm
  44 .Op Fl x
  45 .Fl il Ar pattern
  46 .Nm
  47 .Fl u
  48 .Sh DESCRIPTION
  49 .Nm
  50 manages
  51 .Xr resolv.conf 5
  52 files from multiple sources, such as DHCP and VPN clients.
  53 Traditionally, the host runs just one client and that updates
  54 .Pa /etc/resolv.conf .
  55 More modern systems frequently have wired and wireless interfaces and there is
  56 no guarantee both are on the same network.
  57 With the advent of VPN and other
  58 types of networking daemons, many things now contend for the contents of
  59 .Pa /etc/resolv.conf .
  60 .Pp
  61 .Nm
  62 solves this by letting the daemon send their
  63 .Xr resolv.conf 5
  64 file to
  65 .Nm
  66 via
  67 .Xr stdin 3
  68 with the argument
  69 .Fl a Ar interface Ns Op Ar .protocol
  70 instead of the filesystem.
  71 .Nm
  72 then updates
  73 .Pa /etc/resolv.conf
  74 as it thinks best.
  75 When a local resolver other than libc is installed, such as
  76 .Xr dnsmasq 8
  77 or
  78 .Xr named 8 ,
  79 then
  80 .Nm
  81 will supply files that the resolver should be configured to include.
  82 .Pp
  83 .Nm
  84 assumes it has a job to do.
  85 In some situations
  86 .Nm
  87 needs to act as a deterrent to writing to
  88 .Pa /etc/resolv.conf .
  89 Where this file cannot be made immutable or you just need to toggle this
  90 behaviour,
  91 .Nm
  92 can be disabled by adding
  93 .Sy resolvconf Ns = Ns NO
  94 to
  95 .Xr resolvconf.conf 5 .
  96 .Pp
  97 .Nm
  98 can mark an interfaces
  99 .Pa resolv.conf
 100 as private.
 101 This means that the name servers listed in that
 102 .Pa resolv.conf
 103 are only used for queries against the domain/search listed in the same file.
 104 This only works when a local resolver other than libc is installed.
 105 See
 106 .Xr resolvconf.conf 5
 107 for how to configure
 108 .Nm
 109 to use a local name server.
 110 .Pp
 111 .Nm
 112 can mark an interfaces
 113 .Pa resolv.conf
 114 as exclusive.
 115 Only the latest exclusive interface is used for processing, otherwise all are.
 116 .Pp
 117 When an interface goes down, it should then call
 118 .Nm
 119 with
 120 .Fl d Ar interface.*
 121 arguments to delete the
 122 .Pa resolv.conf
 123 file(s) for all the
 124 .Ar protocols
 125 on the
 126 .Ar interface .
 127 .Pp
 128 Here are some more options that
 129 .Nm
 130 has:-
 131 .Bl -tag -width indent
 132 .It Fl I
 133 Initialise the state directory
 134 .Pa @VARDIR@ .
 135 This only needs to be called if the initial system boot sequence does not
 136 automatically clean it out; for example the state directory is moved
 137 somewhere other than
 138 .Pa /var/run .
 139 If used, it should only be called once as early in the system boot sequence
 140 as possible and before
 141 .Nm
 142 is used to add interfaces.
 143 .It Fl f
 144 Ignore non existant interfaces.
 145 Only really useful for deleting interfaces.
 146 .It Fl i Ar pattern
 147 List the interfaces and protocols, optionally matching
 148 .Ar pattern ,
 149 we have
 150 .Pa resolv.conf
 151 files for.
 152 .It Fl l Ar pattern
 153 List the
 154 .Pa resolv.conf
 155 files we have.
 156 If
 157 .Ar pattern
 158 is specified then we list the files for the interfaces and protocols
 159 that match it.
 160 .It Fl m Ar metric
 161 Set the metric of the interface when adding it, default of 0.
 162 Lower metrics take precedence.
 163 This affects the default order of interfaces when listed.
 164 .It Fl p
 165 Marks the interface
 166 .Pa resolv.conf
 167 as private.
 168 .It Fl u
 169 Force
 170 .Nm
 171 to update all its subscribers.
 172 .Nm
 173 does not update the subscribers when adding a resolv.conf that matches
 174 what it already has for that interface.
 175 .It Fl x
 176 Mark the interface
 177 .Pa resolv.conf
 178 as exclusive when adding, otherwise only use the latest exclusive interface.
 179 .El
 180 .Pp
 181 .Nm
 182 also has some options designed to be used by its subscribers:-
 183 .Bl -tag -width indent
 184 .It Fl v
 185 Echo variables DOMAINS, SEARCH and NAMESERVERS so that the subscriber can
 186 configure the resolver easily.
 187 .It Fl V
 188 Same as
 189 .Fl v
 190 except that only the information configured in
 191 .Xr resolvconf.conf 5
 192 is set.
 193 .El
 194 .Sh INTERFACE ORDERING
 195 For
 196 .Nm
 197 to work effectively, it has to process the resolv.confs for the interfaces
 198 in the correct order.
 199 .Nm
 200 first processes interfaces from the
 201 .Sy interface_order
 202 list, then interfaces without a metic and that match the
 203 .Sy dynamic_order
 204 list, then interfaces with a metric in order and finally the rest in
 205 the operating systems lexical order.
 206 See
 207 .Xr resolvconf.conf 5
 208 for details on these lists.
 209 .Sh PROTOCOLS
 210 Here are some suggested protocol tags to use for each
 211 .Pa resolv.conf
 212 file registered on an
 213 .Ar interface Ns No :-
 214 .Bl -tag -width indent
 215 .It dhcp
 216 Dynamic Host Configuration Protocol.
 217 Initial versions of
 218 .Nm
 219 did not recommend a
 220 .Ar protocol
 221 tag be appended to the
 222 .Ar interface
 223 name.
 224 When the protocol is absent, it is assumed to be the DHCP protocol.
 225 .It ppp
 226 Point-to-Point Protocol.
 227 .It ra
 228 IPv6 Router Advertisement.
 229 .It dhcp6
 230 Dynamic Host Configuration Protocol, version 6.
 231 .El
 232 .Sh IMPLEMENTATION NOTES
 233 If a subscriber has the executable bit then it is executed otherwise it is
 234 assumed to be a shell script and sourced into the current environment in a
 235 subshell.
 236 This is done so that subscribers can remain fast, but are also not limited
 237 to the shell language.
 238 .Pp
 239 Portable subscribers should not use anything outside of
 240 .Pa /bin
 241 and
 242 .Pa /sbin
 243 because
 244 .Pa /usr
 245 and others may not be available when booting.
 246 Also, it would be unwise to assume any shell specific features.
 247 .Sh ENVIRONMENT
 248 .Bl -ohang
 249 .It Va IF_METRIC
 250 If the
 251 .Fl m
 252 option is not present then we use
 253 .Va IF_METRIC
 254 for the metric.
 255 .It Va IF_PRIVATE
 256 Marks the interface
 257 .Pa resolv.conf
 258 as private.
 259 .It Va IF_EXCLUSIVE
 260 Marks the interface
 261 .Pa resolv.conf
 262 as exclusive.
 263 .El
 264 .Sh FILES
 265 .Bl -ohang
 266 .It Pa /etc/resolv.conf.bak
 267 Backup file of the original resolv.conf.
 268 .It Pa @SYSCONFDIR@/resolvconf.conf
 269 Configuration file for
 270 .Nm .
 271 .It Pa @LIBEXECDIR@
 272 Directory of subscribers which are run every time
 273 .Nm
 274 adds, deletes or updates.
 275 .It Pa @LIBEXECDIR@/libc.d
 276 Directory of subscribers which are run after the libc subscriber is run.
 277 .It Pa @VARDIR@
 278 State directory for
 279 .Nm .
 280 .El
 281 .Sh HISTORY
 282 This implementation of
 283 .Nm
 284 is called openresolv and is fully command line compatible with Debian's
 285 resolvconf, as written by Thomas Hood.
 286 .Sh SEE ALSO
 287 .Xr resolv.conf 5 ,
 288 .Xr resolvconf.conf 5 ,
 289 .Xr resolver 3 ,
 290 .Xr stdin 3
 291 .Sh AUTHORS
 292 .An Roy Marples Aq Mt roy@marples.name
 293 .Sh BUGS
 294 Please report them to
 295 .Lk http://roy.marples.name/projects/openresolv
 296 .Pp
 297 .Nm
 298 does not validate any of the files given to it.
 299 .Pp
 300 When running a local resolver other than libc, you will need to configure it
 301 to include files that
 302 .Nm
 303 will generate.
 304 You should consult
 305 .Xr resolvconf.conf 5
 306 for instructions on how to configure your resolver.