README.md

   1 # openresolv
   2
   3 openresolv is a [resolvconf](https://en.wikipedia.org/wiki/Resolvconf)
   4 implementation which manages `/etc/resolv.conf`.
   5
   6 `/etc/resolv.conf` is a file that holds the configuration for the local
   7 resolution of domain names.
   8 Normally this file is either static or maintained by a local daemon,
   9 normally a DHCP daemon. But what happens if more than one thing wants to
  10 control the file?
  11 Say you have wired and wireless interfaces to different subnets and run a VPN
  12 or two on top of that, how do you say which one controls the file?
  13 It's also not as easy as just adding and removing the nameservers each client
  14 knows about as different clients could add the same nameservers.
  15
  16 Enter resolvconf, the middleman between the network configuration services and
  17 `/etc/resolv.conf`.
  18 resolvconf itself is just a script that stores, removes and lists a full
  19 `resolv.conf` generated for the interface. It then calls all the helper scripts
  20 it knows about so it can configure the real `/etc/resolv.conf` and optionally
  21 any local nameservers other than libc.
  22
  23 ## Reasons for using openresolv
  24
  25 Why openresolv over the
  26 [Debian implementation](http://qref.sourceforge.net/Debian/reference/ch-gateway.en.html#s-dns-resolvconf)?
  27 Here's some reasons:
  28   *  Works with
  29   [POSIX shell and userland](http://www.opengroup.org/onlinepubs/009695399)
  30   *  Does not need awk, grep or sed which means we can work without `/usr`
  31   mounted
  32   *  Works with other init systems than Debians' out of the box
  33   *  Available as a 2 clause
  34   [BSD license](http://www.freebsd.org/copyright/freebsd-license.html)
  35   *  Prefer configs via IF_METRIC for dynamic ordering
  36   *  Configures zones for local resolvers other than libc
  37
  38 The last point is quite important, especially when running VPN systems.
  39 Take the following resolv.conf files which have been generated by a
  40 [DHCP client](../dhcpcd) and sent to resolvconf:
  41
  42 ```
  43 # resolv.conf from bge0
  44 search foo.com
  45 nameserver 1.2.3.4
  46
  47 # resolv.conf from tap0
  48 domain bar.org
  49 nameserver 5.6.7.8
  50 ```
  51
  52 In this instance, queries for foo.com will go to 1.2.3.4 and queries for
  53 bar.org will go to 5.6.7.8.
  54 This does require the resolvers to be configured to pickup the resolvconf
  55 generated configuration for them though.
  56 openresolv ships with helpers for:
  57   *  [unbound](http://www.unbound.net/)
  58   *  [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html)
  59   *  [ISC BIND](http://www.isc.org/software/bind)
  60   *  [PowerDNS Recursor](http://wiki.powerdns.com/trac)
  61
  62 See the
  63 [configuration section](https://roy.marples.name/projects/openresolv/config)
  64 for more details.