From 6a22c529740e6bfb3b56ab242df1b0a25a3a7c4d Mon Sep 17 00:00:00 2001 From: Jonathan Wright Date: Mon, 29 Aug 2016 20:40:45 +0100 Subject: [PATCH 1/7] Add CHANGELOG --- CHANGELOG.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f8ee76c --- /dev/null +++ b/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. From 25ee65626ddfb92b90b66c3b5ec43fbc58cd29b2 Mon Sep 17 00:00:00 2001 From: Jonathan Wright Date: Mon, 29 Aug 2016 21:19:53 +0100 Subject: [PATCH 2/7] Change the level of the secondary headings in the README --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5ff3386..00ae461 100644 --- a/README.md +++ b/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: @@ -44,7 +44,7 @@ up /etc/openvpn/update-systemd-resolved down-pre /etc/openvpn/update-systemd-resolved ``` -# How to help +## 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 +60,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 From 21f5d43c559cf740d4c3e3e377b43528d2fbd9f3 Mon Sep 17 00:00:00 2001 From: Jonathan Wright Date: Mon, 29 Aug 2016 21:20:33 +0100 Subject: [PATCH 3/7] Add additional example for nsswitch setup and note about preferred setup --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 00ae461..706d467 100644 --- a/README.md +++ b/README.md @@ -29,12 +29,18 @@ 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 publically (i.e. they must fall back). + Finally, update your OpenVPN configuration file and set the `up` and `down-pre` options: From 1d25d655a3dfca81c24693a5ba2ca7236e1b65e1 Mon Sep 17 00:00:00 2001 From: Jonathan Wright Date: Mon, 29 Aug 2016 21:20:47 +0100 Subject: [PATCH 4/7] Add setenv PATH to the example --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 706d467..78b041b 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ options: ``` script-security 2 +setenv PATH /usr/bin up /etc/openvpn/update-systemd-resolved down-pre /etc/openvpn/update-systemd-resolved ``` From 8d96408584f223fb6fe05d0005453d6d08d40def Mon Sep 17 00:00:00 2001 From: Jonathan Wright Date: Mon, 29 Aug 2016 21:21:22 +0100 Subject: [PATCH 5/7] Add Usage section to README to descript understood options via OpenVPN --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/README.md b/README.md index 78b041b..b074878 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,51 @@ up /etc/openvpn/update-systemd-resolved down-pre /etc/openvpn/update-systemd-resolved ``` +## 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`
`::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 and `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`
`no`
`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 From bbaa3389653fe75253e5f6959850846c61458d82 Mon Sep 17 00:00:00 2001 From: Jonathan Wright Date: Mon, 29 Aug 2016 21:26:08 +0100 Subject: [PATCH 6/7] Improve note about fallback --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b074878..0cd0e52 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,8 @@ 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 publically (i.e. they must fall back). +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: From 9e4e5c52475fbb941d3fced04feba8f2f79c9b48 Mon Sep 17 00:00:00 2001 From: Jonathan Wright Date: Mon, 29 Aug 2016 21:32:43 +0100 Subject: [PATCH 7/7] Grammatical fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0cd0e52..ce4815c 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ OpenVPN, either through the server, or the client, configuration: |--:|---|---| | `DNS` | `0.0.0.0`
`::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 and `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-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`
`no`
`default` | Control of DNSSEC should be enabled (`yes`) or disabled (`no`) for any queries over this link only, or use the system default (`default`). |