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