Merge pull request #11 from jonathanio/feature/more-documentation

Improve Documentation

CHANGELOG.md

@@ -0,0 +1,78 @@
+## 1.2.0 (2016.08.29)
+
+NOTES:
+Add support for DNSSEC processing, improve logic around `DOMAIN` and
+`DOMAIN-SEARCH` handling, add support for `DOMAIN-ROUTE`, and improve
+documentation.
+
+BACKWARDS INCOMPATIBILITIES:
+- Due to (probably) an incorrect assumption on my part (@jonathanio) in the
+  purpose of `DOMAIN-SEARCH` verses `DOMAIN`, domains added via `DOMAIN` were
+  marked as searchable, and so would be appended to bare domain names, while
+  those added via `DOMAIN-SEARCH` would not. This was a divergance from how
+  older OpenVPN handler scripts (such as `update-resolv-conf` and
+  `update-systemd-network`) processed them (i.e. in all cases they were just
+  made searchable). Note that both scripts didn't really have the concept of
+  `domain` in the same way as `/etc/resolv.conf` understood it. This script now
+  (hopefully) properly handles `DOMAIN` and `DOMAIN-SEARCH` (single of the
+  former, and is primary, multiple of the latter and secondary).
+
+FEATURES:
+- Add support for `DNSSEC` option which allows you to enable or disable (or
+  leave to system default) the `DNSSEC` setting for any DNS queries made to the
+  DNS servers provided for this link. (@jonathanio)
+- Add support for `DOMAIN-ROUTE` which, through `systemd-resolved`, allows you
+  to set domain names which should be routed over this link to the DNS servers
+  provided. (@jonathanio)
+
+IMPROVEMENTS:
+- Correct the logic around the handling of `DOMAIN` and `DOMAIN-SEARCH` to be
+  more compatible with previous versions of these handlers. (@jonathanio)
+
+BUG FIXES:
+- None.
+
+## 1.1.1 (2016.08.10)
+
+NOTES:
+Thanks to the help from @pid1 for this release. The documentation mistakenly
+noted to use pre-down for the script now (compared to down originally, which
+failed as the tun or tap device would have been removed before the script
+ran). However, this should have in fact been down-pre.
+
+FEATURES:
+- None.
+
+IMPROVEMENTS:
+- None.
+
+BUG FIXES:
+- Fix `pre-down` to `down-pre` in the documentation else you'll break your
+  OpenVPN configuration. (@pid1)
+
+## 1.1.0 (2016.08.08)
+
+NOTES:
+Thanks to the work by @BaxterStockman, the script has been refactored, hopefully
+making it easier to read and follow, while additional tests around IPv6
+processing have been added.
+
+FEATURES:
+- None.
+
+IMPROVEMENTS:
+- Refactor the codebase to make it easier to read and expand. (@BaxterStockman)
+- Improve run-tests so multiple tests can be run within a file, and can expect
+  failures within a test. (@BaxterStockman)
+- Add tests for invalid IPv6 addresses. (@BaxterStockman)
+
+BUG FIXES:
+- None.
+
+## 1.0.0 (2016.06.23)
+
+NOTES:
+First release of `update-systemd-resolved`. Should fully support the three
+standard DHCP options in OpenVPN (`DNS`, `DOMAIN`, and `DOMAIN-SEARCH`) with
+integration tests around the code to manage and monitor regressions. Also
+supports multiple (and combined) IPv4 and IPv6 DNS addresses.

README.md

@@ -16,7 +16,7 @@ iproute2, and have at least version 229 of systemd, then it should work.
 Nonetheless, if you do come across problems, fork and fix, or raise an issue.
 All are most welcome.
 
-# How to use?
+## How to Enable
 
 Make sure that you have `systemd-resolved` enabled and running:
 
@@ -29,22 +29,75 @@ Then update your `/etc/nsswitch.conf` file to look up DNS via the `resolve`
 service:
 
 ```
-# Use systemd-resolved first, then fall back to /etc/resolv.conf
-hosts: files resolve dns myhostname
 # Use /etc/resolv.conf first, then fall back to systemd-resolved
 hosts: files dns resolve myhostname
+# Use systemd-resolved first, then fall back to /etc/resolv.conf
+hosts: files resolve dns myhostname
+# Don't use /etc/resolv.conf at all
+hosts: files resolve myhostname
 ```
 
+*Note*: If you intend on using this script, the latter two are preferred
+otherwise the configuration provided by this script will only work on domains
+that cannot be resolved by the currently configured DNS servers (i.e. they must
+fall back after trying the ones set by your LAN's DHCP server).
+
 Finally, update your OpenVPN configuration file and set the `up` and `down-pre`
 options:
 
 ```
 script-security 2
+setenv PATH /usr/bin
 up /etc/openvpn/update-systemd-resolved
 down-pre /etc/openvpn/update-systemd-resolved
 ```
 
-# How to help
+## Usage
+
+`update-systemd-resolved` works by processing the `dhcp-option` commands set in
+OpenVPN, either through the server, or the client, configuration:
+
+| Option | Examples | Notes |
+|--:|---|---|
+| `DNS` | `0.0.0.0`<br />`::1` | This sets the DNS servers for the link and can take any IPv4 or IPv6 address. |
+| `DOMAIN` | `example.com` | The primary domain for this host. If set multiple times, the last provided is used. Will be the primary search domain for bare hostnames. All requests for this domain as well will be routed to the `DNS` servers provided on this link. |
+| `DOMAIN-SEARCH` | `example.com` | Secondary domains which will be used to search for bare hostnames (after any `DOMAIN`, if set) and in the order provided. All requests for this domain will be routed to the `DNS` servers provided on this link. |
+| `DOMAIN-ROUTE` | `example.com` | All requests for these domains will be routed to the `DNS` servers provided on this link. They will *not* be used to search for bare hostnames, only routed. |
+| `DNSSEC` | `yes`<br />`no`</br >`default` | Control of DNSSEC should be enabled (`yes`) or disabled (`no`) for any queries over this link only, or use the system default (`default`). |
+
+*Note*: There are no local or system options to be configured. All configuration
+for this script is handled though OpenVPN, including, for example, the name of
+the interface to be configured.
+
+### Example
+
+```
+push "dhcp-option DNS 10.62.3.2"
+push "dhcp-option DNS 10.62.3.3"
+push "dhcp-option DNS 2001:db8::a3:c15c:b56e:619a"
+push "dhcp-option DNS 2001:db8::a3:ffec:f61c:2e06"
+push "dhcp-option DOMAIN example.office"
+push "dhcp-option DOMAIN-SEARCH example.com"
+push "dhcp-option DOMAIN-ROUTE example.net"
+push "dhcp-option DOMAIN-ROUTE example.org"
+push "dhcp-option DNSSEC yes"
+```
+
+This, added to the OpenVPN server's configuration file will set two IPv4 DNS
+servers and two IPv6 and will set the primary domain for the link to be
+`example.office`. Therefore if you try to look up the bare address `mail` then
+`mail.example.office` will be attempted first. The domain `example.com` is also
+added as an additional search domain, so if `mail.example.office` fails, then
+`mail.example.com` will be tried next.
+
+Requests for `example.net` and `example.org` will also be routed though to the
+four DNS servers listed too, but they will *not* be appended (i.e.
+`mail.example.net` will not be attempted, nor `mail.example.org` if
+`mail.example.office` or `mail.example.com` do not exist).
+
+Finally, DNSSEC has been enabled for this link (and this link only).
+
+## How to help
 
 If you can help with any of these areas, or have bug fixes, please fork and
 raise a Pull Request for me.
@@ -60,10 +113,10 @@ langauge.
 TravisCI is enabled on this repository: Click the link at the top of this README
 to see the current state of the code and its tests.
 
-# Licence
+## Licence
 
 GPL
 
-# Author
+## Author
 
 Jonathan Wright <[email protected]>