systemd-resolved: provide documentation/simple shell script example for use by VPN implementations

[DemiMarie]

Is your feature request related to a problem? Please describe.
Many VPN tools are not aware of systemd-resolved, but they often can run a command after the VPN is connected. #6076 was not a bug in systemd-resolved, but rather a consequence of the correct commands to run being obscure and undocumented.

Describe the solution you'd like

There is a simple and documented command (perhaps an option to resolvectl) for use by VPNs.

Describe alternatives you've considered
Expecting users to use busctl directly is a bad idea.

[poettering]

What are you missing in "resolvectl"? i.e. resolvectl dns … allows you to set the DNS server for an iface. resolvectl domain … allows setting the search domains, and so on.

Moreover we provide compat with Debian's and Ubuntu's resolveconf tool, if "resolvectl" is symlinked to that. In that case yu don't have to acknowledge systemd-resolved's existance at all, it should just all work.

What precisely are you missing?

[DemiMarie]

What I would like to see is a high-level document answering, “My VPN isn’t based on NetworkManager. What do I put in its up/down scripts?”. For instance, the following shell script looks like it solves the problem, but I would like to confirm that.

#!/bin/sh --
set -eu
if [ $# -lt 3 ]; then
    printf "Usage: %s INTERFACE DOMAIN SERVER [MORE-SERVERS]\\n\
Specify DOMAIN as the empty string to select all domains\\n">&2
    exit 1
fi
unset interface domain
interface=$1 domain=$2
shift 2
resolvectl -- dns "$interface" "$@"
if [ "$2" = '' ]; then
    exec resolvectl -- domain "$interface" '~.'
else
    exec resolvectl -- domain "$interface" "~$2."
fi

[poettering]

well, I don't know your VPN. But this will preferably route all lookups via the VPN if no search domain is specified, and if one is specified only traffic to that domain is going via VPN. Is that what you want? (i.e. there are two usecases for VPN: the corporate VPN where you really only want to route corporate DNS lookups to the VPN; and the privacy VPN where you want to definitely route all DNS via the VPN).

In the shell script above if a search domain is specified you go for the "corporate VPN scenario", and if none is specified you go for the "privacy VPN scenario". To me, that appears like a surprising choice.

Also, many VPNs allow propagating multiple search domains, not just one. The script will fall apart if multiple search domains shall be configured.

But anyway, I understand you are looking for more docs on this, specifically from the angle of VPN implementations, and what they should do?

[DemiMarie]

That is correct. Examples for major VPN implementations would also be greatly appreciated.