{"id":13558626,"url":"https://github.com/jonathanio/update-systemd-resolved","last_synced_at":"2025-04-03T13:31:43.800Z","repository":{"id":37549416,"uuid":"61155123","full_name":"jonathanio/update-systemd-resolved","owner":"jonathanio","description":"Helper script for OpenVPN to directly update the DNS settings of a link through systemd-resolved via DBus.","archived":false,"fork":false,"pushed_at":"2025-03-22T16:14:47.000Z","size":324,"stargazers_count":784,"open_issues_count":8,"forks_count":94,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-22T17:19:54.195Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonathanio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-14T20:55:18.000Z","updated_at":"2025-03-22T16:31:44.000Z","dependencies_parsed_at":"2023-01-26T13:31:42.080Z","dependency_job_id":"d0a14a30-6f36-4dea-8ed9-7752ebf57d84","html_url":"https://github.com/jonathanio/update-systemd-resolved","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanio%2Fupdate-systemd-resolved","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanio%2Fupdate-systemd-resolved/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanio%2Fupdate-systemd-resolved/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanio%2Fupdate-systemd-resolved/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonathanio","download_url":"https://codeload.github.com/jonathanio/update-systemd-resolved/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247009654,"owners_count":20868584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:05:04.033Z","updated_at":"2025-04-03T13:31:43.524Z","avatar_url":"https://github.com/jonathanio.png","language":"Shell","funding_links":[],"categories":["Shell","others"],"sub_categories":[],"readme":"# update-systemd-resolved\n\n[![Build Status](https://github.com/jonathanio/update-systemd-resolved/actions/workflows/test.yml/badge.svg)](https://github.com/jonathanio/update-systemd-resolved/actions)\n\nThis is a helper script designed to integrate OpenVPN with the\n`systemd-resolved` service via DBus instead of trying to override\n`/etc/resolv.conf`, or manipulate `systemd-networkd` configuration files.\n\nSince systemd-229, the `systemd-resolved` service has an API available via DBus\nwhich allows directly setting the DNS configuration for a link. This script\nmakes use of `busctl` from systemd to send DBus messages to `systemd-resolved`\nto update the DNS for the link created by OpenVPN.\n\n## Prerequisites\n\nThis script requires:\n\n- Bash 4.3 or above.\n- [coreutils](https://www.gnu.org/software/coreutils/) or\n  [busybox](https://www.busybox.net/) (for the `id` command).\n- [iproute2](https://wiki.linuxfoundation.org/networking/iproute2) (for the\n  `ip` command).\n- [systemd](https://systemd.io/) (for the `busctl` and `resolvectl` commands).\n\n### Optional dependencies:\n\n#### IP Parsing and Validation\n\n- [`python`](https://python.org), **or**\n- [`sipcalc`](https://github.com/sii/sipcalc).\n\nIf available, these will be used for IP address parsing and\nvalidation;[^iphandling] otherwise `update-systemd-resolved` will use native\nBash routines for this.\n\n[^iphandling]: Required for translating numerical labels like `1.2.3.4` to the\n               byte arrays recognized by [the `SetLinkDNS()` function on\n               `systemd-resolved`'s `org.freedesktop.resolve1.Manager` D-Bus\n               interface][resolved]).\n\n#### Logging\n\n- [util-linux](https://en.wikipedia.org/wiki/Util-linux)\n\nIf available, the `logger` command included in the `util-linux` distribution\nwill be used for logging.  Otherwise, all logs will go to standard error using\nBash's `printf` builtin.\n\n#### Polkit Rules Generation\n\n- [`jq`](https://jqlang.github.io/jq/), **or**\n- [`perl`](https://www.perl.org/), **or**\n- [`python`](https://python.org).\n\nIf available, these will be used for serializing the [names of the users and\ngroups allowed to call `systemd-resolved`'s DBus methods](#polkit-rules) to\nJSON lists for use within the [generated polkit\nrules](#generating-polkit-rules).  Otherwise, `update-systemd-resolved` will\nfall back to native Bash routines for generating these lists.\n\n## Installation\n\n[aur]:https://aur.archlinux.org/packages/openvpn-update-systemd-resolved/\n\nIf you are using a distribution of Linux with uses the Arch User Repository, the\nsimplest way to install is by using the [openvpn-update-systemd-resolved][aur]\nAUR package as this will take care of any updates through your package manager.\n[Debian](https://packages.debian.org/openvpn-systemd-resolved) and\n[Ubuntu](https://packages.ubuntu.com/openvpn-systemd-resolved) also provide a\n`.deb` package in their distributions.\n\nAlternatively, the package can be manually installed by running the following:\n\n```bash\ngit clone https://github.com/jonathanio/update-systemd-resolved.git\ncd update-systemd-resolved\nmake\n```\n\n### Nix and NixOS\n\n[Nix flake]:https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html\n\n`update-systemd-resolved` exposes a [Nix flake][].  You can incorporate this\nflake into your flake by adding it to your inputs:\n\n```nix\n# Your flake.nix\n{\n  inputs = {\n    # Other inputs here...\n\n    update-systemd-resolved.url = \"github:jonathanio/update-systemd-resolved\";\n    update-systemd-resolved.inputs.nixpkgs.follows = \"nixpkgs\"; # optional\n  };\n\n  # Etc.\n}\n```\n\nThis flake provides the `update-systemd-resolved` package for several Linux\narchitectures.  It also provides the `update-systemd-resolved` NixOS module:\n\n```nix\n# Your flake.nix\n{\n  outputs = {nixpkgs, update-systemd-resolved, ...}: {\n    nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {\n      system = \"x86_64-linux\";\n      modules = [\n        update-systemd-resolved.nixosModules.update-systemd-resolved\n      ];\n    };\n  };\n}\n```\n\nPlease see [the NixOS module documentation](/docs/nixos-modules.md) for\navailable options.\n\nTo view all outputs provided by this flake, run the following command:\n\n```shell-session\n$ nix flake show 'github:jonathanio/update-systemd-resolved'\n```\n\n## How to Enable\n\nMake sure that you have `systemd-resolved` enabled and running. First, make sure\nthat `systemd-resolved.service` is enabled and started:\n\n```bash\nsystemctl enable systemd-resolved.service\nsystemctl start systemd-resolved.service\n```\n\nNext, you can either configure the system libraries to talk to it using NSS, or\nyou can override the `resolv.conf` file to use `systemd-resolved` as a stub\nresolver (or both):\n\n### NSS and nssswitch.conf\n\nUpdate your `/etc/nsswitch.conf` file to look up DNS via the `resolve` service\n(you may need to install the NSS library which connects libnss to\n`systemd-resolved`):\n\n```conf\n# Use /etc/resolv.conf first, then fall back to systemd-resolved\nhosts: files dns resolve myhostname\n# Use systemd-resolved first, then fall back to /etc/resolv.conf\nhosts: files resolve dns myhostname\n# Don't use /etc/resolv.conf at all\nhosts: files resolve myhostname\n```\n\nThe changes will be applied as soon as the file is saved.\n\nNote that [some Linux distributions manage `/etc/nsswitch.conf`](#fedora), so\nmanual edits to `/etc/nsswitch.conf` may disappear.  Please consult your\ndistribution's documentation for how to configure `/etc/nsswitch.conf`.\n\n### Polkit Rules\n\nIf you run the OpenVPN client as an unprivileged user, you may need to add\npolkit rules authorizing that user to perform the various DBus calls that\n`update-systemd-resolved` makes.  Some installation methods bundle these rules;\nfor instance, on Arch Linux, where `openvpn-client@\u003cname\u003e.service` instances\nrun as the unprivileged `openvpn` user, the\n[openvpn-update-systemd-resolved][aur] AUR package ships suitable rules in the\nfile `/etc/polkit-1/rules.d/10-update-systemd-resolved.rules`.\n\n#### Generating Polkit Rules\n\n\u003e [!WARNING]\n\u003e `update-systemd-resolved` strives to generate polkit rules with the smallest\n\u003e scope consistent with its proper functioning.  Nonetheless, in order to avoid\n\u003e security risks, you are encouraged to review the generated polkit rules\n\u003e before installing them.\n\nYou can also generate suitable rules with (some variation on) the following\ncommands:\n\n```shell-session\n$ update-systemd-resolved print-polkit-rules --polkit-allowed-user some-user --polkit-allowed-user another-user \u003e ./10-custom-update-systemd-resolved.rules\n$ sudo install -Dm0640 ./10-custom-update-systemd-resolved.rules /etc/polkit-1/rules.d/10-custom-update-systemd-resolved.rules\n```\n\nThis will allow `update-systemd-resolved` to successfully make its DBus calls\nwhen invoked from OpenVPN client services that run as the users `some-user` or\n`another-user`.\n\nYou can also authorize members of specified groups with:\n\n```shell-session\n$ update-systemd-resolved print-polkit-rules --polkit-allowed-group some-group --polkit-allowed-group another-group \u003e ./10-custom-update-systemd-resolved.rules\n$ sudo install -Dm0640 ./10-custom-update-systemd-resolved.rules /etc/polkit-1/rules.d/10-custom-update-systemd-resolved.rules\n```\n\nThis will allow `update-systemd-resolved` to successfully make its DBus calls\nwhen invoked from OpenVPN client services that run under the groups\n`some-group` or `another-group`.\n\nFinally, you can generate rules that pull appropriate user and group values\nfrom OpenVPN systemd units with:\n\n```shell-session\n$ update-systemd-resolved print-polkit-rules --polkit-systemd-openvpn-unit my-openvpn-client.service\n$ sudo install -Dm0640 ./10-custom-update-systemd-resolved.rules /etc/polkit-1/rules.d/10-custom-update-systemd-resolved.rules\n```\n\nGiven:\n\n```shell-session\n$ systemctl show -P User my-openvpn-client.service\nmyuser\n$ systemctl show -P Group my-openvpn-client.service\nmygroup\n```\n\nThe generated `10-custom-update-systemd-resolved.rules` file will contain rules\nallowing the `myuser` user and members of the `mygroup` group to perform the\nrequisite DBus calls.\n\nYou can run `update-systemd-resolved print-polkit-rules` with any combination\nof `--polkit-allowed-user`, `--polkit-allowed-group`, and\n`--polkit-systemd-openvpn-unit`.  If called without options,\n`update-systemd-resolved print-polkit-rules` will attempt to derive appropriate\nuser and group authorizations from a systemd OpenVPN unit matching\n`openvpn-client@.service`, the [systemd service\ntemplate](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Service%20Templates)\nused for OpenVPN client services on distributions including Arch Linux.\n\n### Stub Resolver\n\nThe `systemd-resolved` service (since systemd-231) also listens on `127.0.0.53`\nvia the `lo` interface, providing a stub resolver which any client can call to\nrequest DNS, whether or not it uses the system libraries to resolve DNS, and\nyou no longer have to worry about trying to manage your `/etc/resolv.conf`\nfile. This set up can be installed by linking to `stub-resolv.conf`:\n\n```bash\nln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf\n```\n\n### OpenVPN Configuration\n\nFinally, update your OpenVPN configuration file and set the `up` and `down`\noptions to point to the script, and `down-pre` to ensure that the script is run\nbefore the device is closed:\n\n```conf\nscript-security 2\nup /usr/local/libexec/openvpn/update-systemd-resolved\nup-restart\ndown /usr/local/libexec/openvpn/update-systemd-resolved\ndown-pre\n\n# If needed, to permit `update-systemd-resolved` to find utilities it depends\n# on.  Adjust to suit your system.\n#setenv PATH /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\n```\n\n#### up-restart\n\nIt is recommended to use `up-restart` in your configuration to ensure that\n`upate-systemd-resolved` is run on restarts - where the connection is\nre-established but the TUN/TAP device remained open (for example, where the\noriginal connection has timed out and `persist-tun` is enabled). If you do not\nhave `persist-tun` set, or you use `ping-exit` instead of `ping-timeout`, you\nmost likely will not need this.\n\n#### down/pre-down with user/group\n\nThe `down` and `down-pre` options here may not work as expected where the\n`openvpn` daemon drops privileges after establishing the connection (i.e.  when\nusing the `user` and `group` options). This is because, by default, only the\n`root` user will have the privileges required to talk to\n`systemd-resolved.service` over DBus. The `openvpn-plugin-down-root.so` plug-in\ndoes provide support for enabling the `down` script to be run as the `root`\nuser, but this has been known to be unreliable.\n\nYou can authorize unprivileged users or groups to revert the OpenVPN link's DNS\nsettings during the \"down\" phase using the methods described in the [\"Polkit\nRules\" section](#polkit-rules).\n\nUltimately, dropping privileges shouldn't affect normal \"down\" operation, since\n`systemd-resolved.service` will remove all settings associated with the link\n(and therefore naturally update `/etc/resolv.conf`, if you have it symlinked)\nwhen the TUN or TAP device is closed. The option for `down` and `down-pre` just\nmake this step explicit before the device is torn down rather than implicit on\nthe change in environment.\n\n### Command Line Settings\n\nAlternatively if you don't want to edit your client configuration, you can add\nthe following options to your `openvpn` command:\n\n```bash\nopenvpn \\\n  --script-security 2 \\\n  --setenv PATH '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' \\\n  --up /usr/local/libexec/openvpn/update-systemd-resolved --up-restart \\\n  --down /usr/local/libexec/openvpn/update-systemd-resolved --down-pre\n```\n\n\u003e [!TIP]\n\u003e The `--setenv PATH` option shown above is intended to allow\n\u003e `update-systemd-resolved` to find [its prerequisites](#prerequisites).\n\u003e Depending on your system's configuration, you may not need `--setenv PATH`,\n\u003e or you may need to specify a different `PATH` value than the one shown above.\n\nOr, you can add the following argument to the command-line arguments of\n`openvpn`, which will use the `update-systemd-resolve.conf` file instead:\n\n```bash\nopenvpn --config /usr/local/share/doc/openvpn/update-systemd-resolved.conf\n```\n\n\u003e [!NOTE]\n\u003e The path to `update-systemd-resolved.conf` may differ depending on how you\n\u003e installed `update-systemd-resolved`.  Additionally, both the file's path and\n\u003e its contents are subject to change in future releases.  Rather than using the\n\u003e example configuration file directory, you may want to copy the file to\n\u003e another location and then run `openvpn --config \u003cother-location\u003e/update-systemd-resolved.conf`.\n\n## :screwdriver: Usage :wrench:\n\n`update-systemd-resolved` works by processing the `dhcp-option` commands set in\nOpenVPN, either through the server, or the client, configuration.  **Note**\nthat there are no local or system options to be configured. All configuration\nfor this script is handled through OpenVPN, including, for example, the name of\nthe interface to be configured.\n\n### :level_slider: Options :control_knobs:\n\n[resolved]:https://www.freedesktop.org/software/systemd/man/org.freedesktop.resolve1.html\n\n#### :gear: `DNS`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eSetting DNS servers\u003c/summary\u003e\n\n##### Examples\n\n- `0.0.0.0`\n- `0.0.0.0:5353`\n- `0.0.0.0#my.resolver.net`\n- `0.0.0.0:5353#my.resolver.net`\n- `::1`\n- `[::1]:5353`\n- `::1#my.resolver.net`\n- `[::1]:5353#my.resolver.net`\n\n##### Description\n\nThis sets the DNS servers for the link and can take any IPv4 or IPv6 address.\n\n##### DBus call\n\n[SetLinkDNS][resolved], [SetLinkDNSEx][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `DNS6`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eSetting IPv6-only DNS servers\u003c/summary\u003e\n\n##### Examples\n\n- `::1`\n- `[::1]:5353`\n- `::1#my.resolver.net`\n- `[::1]:5353#my.resolver.net`\n\n##### Description\n\nThis sets the DNS servers for the link and can take only IPv6 addresses.\n\n##### DBus call\n\n[SetLinkDNS][resolved], [SetLinkDNSEx][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `DOMAIN` or `ADAPTER_DOMAIN_SUFFIX`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eSetting the primary domain\u003c/summary\u003e\n\n##### Examples\n\n- `example.com`\n\n##### Description\n\nThe primary domain for this host. If set multiple times, the first provided is\nused as the primary search domain for bare hostnames. Any subsequent `DOMAIN`\noptions will be added as the equivalent of `DOMAIN-SEARCH` options. All\nrequests for this domain as well will be routed to the `DNS` servers provided\non this link.\n\n##### DBus call\n\n[SetLinkDomains][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `DOMAIN-SEARCH`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eSetting secondary domains\u003c/summary\u003e\n\n##### Examples\n\n- `example.com`\n\n##### Description\n\nSecondary domains which will be used to search for bare hostnames (after any\n`DOMAIN`, if set) and in the order provided. All requests for this domain will\nbe routed to the `DNS` servers provided on this link.\n\n##### DBus call\n\n[SetLinkDomains][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `DOMAIN-ROUTE`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eRouting DNS queries\u003c/summary\u003e\n\n##### Examples\n\n- `example.com`\n\n##### Description\n\nAll requests for these domains will be routed to the `DNS` servers provided on\nthis link. They will *not* be used to search for bare hostnames, only routed. A\n`DOMAIN-ROUTE` option for `.` (single period) will instruct `systemd-resolved`\nto route the entire DNS name-space through to the `DNS` servers configured for\nthis connection (unless a more specific route has been offered by another\nconnection for a selected name/name-space). This is useful if you wish to\nprevent [DNS leakage](#dns-leakage).\n\n##### DBus call\n\n[SetLinkDomains][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `DNSSEC`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eEnabling DNSSEC\u003c/summary\u003e\n\n##### Examples\n\n- `yes`, `true`\n- `no`, `false`\n- `default`\n- `allow-downgrade`\n\n##### Description\n\nControl of DNSSEC should be enabled (`yes`, `true`) or disabled (`no`,\n`false`), or `allow-downgrade` to switch off DNSSEC only if the server doesn't\nsupport it, for any queries over this link only, or use the system default\n(`default`).\n\n##### DBus call\n\n[DNSSEC][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `FLUSH-CACHES`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eFlushing DNS caches\u003c/summary\u003e\n\n##### Examples\n\n- `yes`, `true`\n- `no`, `false`\n\n##### Description\n\nWhether or not to flush all local DNS caches.  Enabled by default.\n\n##### DBus call\n\n[FlushCaches][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `RESET-SERVER-FEATURES`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eResetting learnt DNS server feature levels\u003c/summary\u003e\n\n##### Examples\n\n- `yes`, `true`\n- `no`, `false`\n\n##### Description\n\nWhether or not to forget learnt DNS server feature levels.\n\n##### DBus call\n\n[ResetServerFeatures][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `RESET-STATISTICS`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eResetting resolver statistics\u003c/summary\u003e\n\n##### Examples\n\n- `yes`, `true`\n- `no`, `false`\n\n##### Description\n\nWhether or not to reset resolver statistics.\n\n##### DBus call\n\n[ResetStatistics][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `DEFAULT-ROUTE`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eDefault DNS query routing\u003c/summary\u003e\n\n##### Examples\n\n- `yes`, `true`\n- `no`, `false`\n\n##### Description\n\nIf true, this link's configured DNS servers are used for resolving domain names\nthat do not match any link's configured `Domains=` setting. If false, this\nlink's configured DNS servers are never used for such domains, and are\nexclusively used for resolving names that match at least one of the domains\nconfigured on this link.\n\n##### DBus call\n\n[DNSDefaultRoute][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `DNS-OVER-TLS`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eEnabling DNS-over-TLS\u003c/summary\u003e\n\n##### Examples\n\n- `yes`, `true`\n- `no`, `false` • `opportunistic` • `default`\n\n##### Description\n\nIf true all connections to the server will be encrypted. Note that this mode\nrequires a DNS server that supports DNS-over-TLS and has a valid certificate.\nIf the hostname was specified in `DNS=` by using the format\n`address#server_name` it is used to validate its certificate and also to enable\nServer Name Indication (SNI) when opening a TLS connection. Otherwise the\ncertificate is checked against the server's IP. If the DNS server does not\nsupport DNS-over-TLS all DNS requests will fail. When set to `opportunistic`\nDNS request are attempted to send encrypted with DNS-over-TLS. If the DNS\nserver does not support TLS, DNS-over-TLS is disabled. Note that this mode\nmakes DNS-over-TLS vulnerable to \"downgrade\" attacks, where an attacker might\nbe able to trigger a downgrade to non-encrypted mode by synthesizing a response\nthat suggests DNS-over-TLS was not supported. If set to false, DNS lookups are\nsend over UDP. If set to `default`, uses the system default.\n\n##### DBus call\n\n[SetLinkDNSOverTLS][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `LLMNR`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eEnabling Link-Local Multicast Name Resolution\u003c/summary\u003e\n\n##### Examples\n\n- `yes`, `true`\n- `no`, `false` • `resolve` • `default`\n\n##### Description\n\nWhen true, enables Link-Local Multicast Name Resolution on the link. When set\nto `resolve`, only resolution is enabled, but not host registration and\nannouncement. If set to `default`, uses the system default.\n\n##### DBus call\n\n[SetLinkLLMNR][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `MULTICAST-DNS`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eEnabling Multicast DNS\u003c/summary\u003e\n\n##### Examples\n\n- `yes`, `true`\n- `no`, `false` • `resolve` • `default`\n\n##### Description\n\nWhen true, enables Multicast DNS support on the link. When set to `resolve`,\nonly resolution is enabled, but not host or service registration and\nannouncement. If set to `default`, uses the system default.\n\n##### DBus call\n\n[SetLinkMulticastDNS][resolved]\n\n\u003c/details\u003e\n\n#### :gear: `DNSSEC-NEGATIVE-TRUST-ANCHORS`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eConfiguring DNSSEC Negative Trust Anchors\u003c/summary\u003e\n\n##### Examples\n\n- `trusted.org`\n\n##### Description\n\nIf specified and DNSSEC is enabled, look-ups done via the interface's DNS\nserver will be subject to the list of negative trust anchors, and not require\nauthentication for the specified domains, or anything below it. Use this to\ndisable DNSSEC authentication for specific private domains, that cannot be\nproven valid using the Internet DNS hierarchy. By default,\n`update-systemd-resolved` does not set any negative trust anchors.\n\n##### DBus call\n\n[SetLinkDNSSECNegativeTrustAnchors][resolved]\n\n\u003c/details\u003e\n\n### Example\n\n```conf\npush \"dhcp-option DNS 10.62.3.2\"\npush \"dhcp-option DNS 10.62.3.3\"\npush \"dhcp-option DNS6 2001:db8::a3:c15c:b56e:619a\"\npush \"dhcp-option DNS6 2001:db8::a3:ffec:f61c:2e06\"\npush \"dhcp-option DOMAIN example.office\"\npush \"dhcp-option DOMAIN example.lan\"\npush \"dhcp-option DOMAIN-SEARCH example.com\"\npush \"dhcp-option DOMAIN-ROUTE example.net\"\npush \"dhcp-option DOMAIN-ROUTE example.org\"\npush \"dhcp-option DNSSEC yes\"\n```\n\nThis, added to the OpenVPN server's configuration file will set two IPv4 DNS\nservers and two IPv6 and will set the primary domain for the link to be\n`example.office`. Therefore if you try to look up the bare address `mail` then\n`mail.example.office` will be attempted first. The domains `example.lan` and\n`example.com` are also added as an additional search domain, so if\n`mail.example.office` fails, then `mail.example.lan` will be tried next,\nfollowed by `mail.example.com`.\n\nRequests for `example.net` and `example.org` will also be routed through to the\nfour DNS servers listed, but they will *not* be appended (i.e.\n`mail.example.net` will not be attempted, nor `mail.example.org`, if\n`mail.example.office` or `mail.example.com` do not exist).\n\nFinally, DNSSEC has been enabled for this link (and this link only).\n\n## DNS Leakage\n\n[resolved-vpns]: https://systemd.io/RESOLVED-VPNS\n\n\u003e [!IMPORTANT]\n\u003e Required reading: [`systemd-resolved.service` and VPNs][resolved-vpns].  This\n\u003e document includes, among other things, an overview of search domains, routing\n\u003e domains, and `systemd-resolved`'s `default-route` boolean settings.\n\u003e Understanding these concepts will help you configure your local\n\u003e `systemd-resolved` instance to ensure that DNS queries go where you want them\n\u003e to go.\n\nDNS Leakage is something to be careful of when using any VPN or untrusted\nnetwork, and it can heavily depend on how you configure your normal DNS\nsettings as well as how you configure the DNS on your VPN connection.\n\nBy default, `systemd-resolved` will send **all** DNS queries to at least one\nDNS server on **every** link configured with DNS servers. The first to reply\nback with a valid query is the one returned to the client, and the last to\nreturn back a failure (assuming all other queries also failed) will also be\nreturned to the client.\n\nThe changes in this handling come in when you start using the `DOMAIN`,\n`DOMAIN-SEARCH` and `DOMAIN-ROUTE` options.  The three differ in how domains\nare treated for searching bare domains, but all three work exactly the same\nwhen it comes to how it routes domains to specific DNS servers.\n\nAny domain added using `DOMAIN`, `DOMAIN-SEARCH`, or `DOMAIN-ROUTE` will be\nadded explicitly to the VPN link and therefore any queries for domain suffixes\nwhich match these will be routed through this link, and only this link.  Any\nother domains which do not match these will revert back to distributing the\nqueries across all links.\n\nThere are two ways to override this:\n\n### Preventing Leakage in on untrusted networks\n\nIf you want to prevent DNS queries leaking over untrusted networks (for\nexample, over public WiFi hotspots), then you need to tell `systemd-resolved`\nto send **all** DNS queries over the VPN link. To do this, add the following to\nyour server or client VPN configurations respectively:\n\n```\n# Server Configuration\npush \"dhcp-option DOMAIN-ROUTE .\"\n```\n\n```\n# Client Configuration\ndhcp-option DOMAIN-ROUTE .\n```\n\nAll DNS queries (which do not match a more explicit entry on another link) will\nnow be routed over the VPN only.\n\n### Preventing Leakage to Corporate networks\n\nIn an alternate situation, you may want to have DNS queries specifically routed\nover the VPN for corporate or private network access, but you don't want your\ngeneral DNS queries to be visible to anyone who has access to the logs of the\ncorporate DNS servers.\n\nThis option cannot be directly managed by `update-systemd-resolved` as you need\nto configure the network settings of other links to send all queries by default\nto your nominated DNS server (e.g. over `ens0` or `wlp2s0` for your Ethernet or\nWireless network cards). This needs to be configured under the `[Network]`\nsection of your `.network` file for your interface in `/etc/systemd/network`.\nFor example:\n\n```\n[Network]\nDHCP=yes\nDNS=8.8.8.8\nDNS=8.8.4.4\nDomains=.\n```\n\nWhen you connect, all domains except those explicitly listed using the `DOMAIN`,\n`DOMAIN-SEARCH`, or `DOMAIN-ROUTE` options of your VPN link will be sent to the\nDNS server of your nominated link.\n\n### Concurrent Configuration\n\nNote that these two options are mutually exclusive, as if you establish a VPN\nlink with `DOMAIN-ROUTE` set to `.` while you have also configured it inside a\n`.network` file via `systemd-networkd`, then you will have two links\nresponsible for routing all queries, and so both links will get all requests.\n\nHow to manage the DNS settings of other links while the VPN is operational is\noutside the scope of this script at this time.\n\n## Known Issues\n\nThere are a number of known issues relating to some third-party servers and\nservices:\n\n### NetworkManager\n\n#### Compatibility with this script\n\n[nm-helper]:https://git.launchpad.net/ubuntu/+source/network-manager-openvpn/tree/src/nm-openvpn-service-openvpn-helper.c?h=debian/sid\n\nThis script may not be compatible with certain versions of NetworkManager. It\nseems that NetworkManager overrides the `up` command to use its own helper\nscript ([nm-openvpn-service-openvpn-helper][nm-helper]). The script that ships\nwith NetworkManager only supports `DNS` and `DOMAIN` options (not `DNS6`,\n`DOMAIN-SEARCH` and `DOMAIN-ROUTE`, nor `DNSSEC` overrides). It may also be\nliable to set the other network interfaces to route `~.` DNS queries (i.e the\nwhole name-space) to the LAN or ISP DNS servers, making it difficult to\noverride using `DOMAIN` - see [the DNS leakage section](#managed-interface-dns-leakage).\n\n#### Managed interface DNS leakage\n\n[LP1671606]:https://bugs.launchpad.net/ubuntu/+source/network-manager/+bug/1671606\n[LP1688018]:https://bugs.launchpad.net/ubuntu/+source/network-manager/+bug/1688018\n\nThere is a regression with versions of NetworkManager 1.2.6 through 1.26.4 (see\n[LP#1671606][LP1671606] and [LP#1688018][LP1688018]) which means that it will\nautomatically set all normal network interfaces with `~.` for DNS routing.\nThis means that even if you set `dhcp-option DOMAIN-ROUTE .` for your VPN\nconnection, you will still leak DNS queries over potentially insecure networks.\n\n[issue-59]:https://github.com/jonathanio/update-systemd-resolved/issues/59\n\nIf you are concerned by potentially leaking DNS on systems which use\nNetworkManager, you may need to configure an [additional script][issue-59]\ninto NetworkManager which change the domain routing settings on all non-VPN\ninterfaces.\n\n[fix-1.26.6]:https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/blob/nm-1-26/NEWS#L23-24\n\nThis issue was [fixed in NetworkManager version 1.26.6][fix-1.26.6]; now,\nNetworkManager only enables the `DefaultRoute` option on managed interfaces.\n\n### DNSSEC Issues\n\n```shell\n$ resolvectl query eu-central-1.console.aws.amazon.com\neu-central-1.console.aws.amazon.com: resolve call failed: DNSSEC validation failed: no-signature\n# or\n$ resolvectl query eu-central-1.console.aws.amazon.com\neu-central-1.console.aws.amazon.com: resolve call failed: DNSSEC validation failed: incompatible-server\n```\n\nIf you are seeing failed queries in your logs due to DNSSEC issues, support may be\npartially or fully enabled and you are now working with a server which does not\nsupport this extension. You may therefore need to set `DNSSEC` to `no` (or\nmaybe just `allow-downgrade`) in your VPN configuration.\n\n```\ndhcp-option DNSSEC allow-downgrade\n```\n\n### Issues with Ubuntu and Fedora\n\n#### Ubuntu\n\n[LP1685045]:https://bugs.launchpad.net/ubuntu/+source/systemd/+bug/1685045\n\nThe NSS interface for `systemd-resolved` may be deprecated and has already been\nflagged for deprecation in Ubuntu (see [LP#1685045][LP1685045] for details). In\nthis case, you should use the [Stub Resolver](#stub-resolver) method now.\n\n#### Fedora\n\n[authselect]:https://github.com/authselect/authselect\n\nFedora 28 makes use of `authselect` to manage the NSS settings on the system.\nDirectly editing `nsswitch.conf` is not recommended as it may be overwritten at\nany time if `authselect` is run. Proper overrides may not yet be possible - see\n[the authselect project repository][authselect] for details. However, like\nUbuntu, the [Stub Resolver](#stub-resolver) method is recommended here too.\n\n[f33-changes-systemd-resolved]:https://fedoraproject.org/wiki/Changes/systemd-resolved\n\nNote that Fedora 33 enables `systemd-resolved` by default and configures\n`/etc/nsswitch.conf` to use the `systemd-resolved` NSS interface; see [the\nFedora changelog entry](f33-changes-systemd-resolved) for details.\n\n## How to help\n\nIf you can help with any of these areas, or have bug fixes, please fork and\nraise a Pull Request for me.\n\nI have built a basic test framework around the script which can be used to\nmonitor and validate the calls made by the script based on the environment\nvariables available to it at run-time. Please add a test for any new features\nyou may wish to add, or update any which are wrong, and test your code by\nrunning `./run-tests` from the root of the repository. There are no dependencies\non `run-tests` - it runs 100% bash and doesn't call out to any other program or\nlanguage.\n\nGitHub Actions are enabled on this repository: Click the link at the top of this\nREADME to see the current state of the code and its tests.\n\n## Development notes\n\nPlease see [`HACKING.md`](./HACKING.md) for notes on developing\n`update-systemd-resolved`.\n\n## Licence\n\nGPL\n\n## Author\n\nJonathan Wright \u003cjon@than.io\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanio%2Fupdate-systemd-resolved","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonathanio%2Fupdate-systemd-resolved","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanio%2Fupdate-systemd-resolved/lists"}