Add WireGuard interfaces to dynamic_order
[openresolv] / README.md
index fabbafa94715a4c0049657f6733f9831d62bcc32..739cc73356cb1c082ee820c49a78461919fc0b71 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # openresolv
 
-openresolv is a resolvconf(8) implementation which manages `/etc/resolv.conf`.
+openresolv is a [resolvconf](https://en.wikipedia.org/wiki/Resolvconf)
+implementation which manages `/etc/resolv.conf`.
 
 `/etc/resolv.conf` is a file that holds the configuration for the local
 resolution of domain names.
@@ -19,12 +20,45 @@ resolvconf itself is just a script that stores, removes and lists a full
 it knows about so it can configure the real `/etc/resolv.conf` and optionally
 any local nameservers other than libc.
 
-## Why openresolv?
+## Reasons for using openresolv
 
-This resolvconf implementation, along with its subscribers, work with a
-POSIX compliant shell and userland utilities. It is designed to work without
-tools such as sed as it *has* to work without /usr being available.
+Why openresolv over the
+[Debian implementation](http://qref.sourceforge.net/Debian/reference/ch-gateway.en.html#s-dns-resolvconf)?
+Here's some reasons:
+  *  Works with
+  [POSIX shell and userland](http://www.opengroup.org/onlinepubs/009695399)
+  *  Does not need awk, grep or sed which means we can work without `/usr`
+  mounted
+  *  Works with other init systems than Debians' out of the box
+  *  Available as a 2 clause
+  [BSD license](http://www.freebsd.org/copyright/freebsd-license.html)
+  *  Prefer configs via IF_METRIC for dynamic ordering
+  *  Configures zones for local resolvers other than libc
 
-On systems where resolvconf is expected to be used before /var/run is available
-for writing, you can configure openresolv to write somewhere else, like say a
-ramdisk.
+The last point is quite important, especially when running VPN systems.
+Take the following resolv.conf files which have been generated by a
+[DHCP client](../dhcpcd) and sent to resolvconf:
+
+```
+# resolv.conf from bge0
+search foo.com
+nameserver 1.2.3.4
+
+# resolv.conf from tap0
+domain bar.org
+nameserver 5.6.7.8
+```
+
+In this instance, queries for foo.com will go to 1.2.3.4 and queries for
+bar.org will go to 5.6.7.8.
+This does require the resolvers to be configured to pickup the resolvconf
+generated configuration for them though.
+openresolv ships with helpers for:
+  *  [unbound](http://www.unbound.net/)
+  *  [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html)
+  *  [ISC BIND](http://www.isc.org/software/bind)
+  *  [PowerDNS Recursor](http://wiki.powerdns.com/trac)
+
+See the
+[configuration section](https://roy.marples.name/projects/openresolv/config)
+for more details.