DOC: Update instructions on GNS integration and use

1 files changed, 102 insertions, 7 deletions

diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi
index d30c94c9b..714336228 100644
--- a/doc/handbook/chapters/user.texi
+++ b/doc/handbook/chapters/user.texi
@@ -56,7 +56,8 @@ $ gnunet-arm -e
 * The GNS Tab::
 * Creating a Record::
 * Resolving GNS records::
-* Integration with Browsers::
+* Integration with Browsers (DNS2GNS service)::
+* Integration with Browsers (SOCKS proxy)::
 * Creating a Business Card::
 * Be Social::
 * Backup of Identities and Egos::
@@ -67,8 +68,16 @@ $ gnunet-arm -e
 @node Preliminaries
 @subsection Preliminaries
 
+In the default configuration, there are two zones defined and shipped with
+GNUnet:
+
+The first is ``gnunet.org'', which points to the authoritate zone of the
+GNUnet project. It can be used to resolve, for example, ``www.gnunet.org''.
+
+``.pin'' is another default zone which points to a special zone also  managed
+by gnunet.org. Users may register submodomains on a first-come first-served-basis
+at @url{https://fcfs.gnunet.org}.
 
-``.pin'' is a default zone which points to a zone managed by gnunet.org.
 Use @code{gnunet-config -s gns} to view the GNS configuration, including
 all configured zones that are operated by other users.  The respective
 configuration entry names start with a ``.'', e.g. ``.pin''.
@@ -190,13 +199,99 @@ Got `A' record: 217.92.15.146
 That shows that resolution works, once GNS is integrated with
 the application.
 
-@node Integration with Browsers
-@subsection Integration with Browsers
+@node Integration with Browsers (DNS2GNS service)
+@subsection Integration with Browsers (DNS2GNS service)
+
+Most OSes allow you to either modify your @code{/etc/resolv.conf} directly or
+through @code{resolvectl}.
+We are going to configure the @code{dns2gns} service in order to translate DNS name
+queries by applications to GNS name queries where applicable and else fall back
+to DNS.
+
+Optionally, you may want to configure your @code{dns2gns} service to run on a
+non-priviledged port like 5353.
+But, in case you are going to edit @code{/etc/resolv.conf} directly, the
+@code{dns2gns} service MUST run on port 53 as you cannot specify the port number.
+A $FALLBACK_DNS variable should be a DNS server you trust such as your local router:
+
+@example
+$ gnunet-config -s dns2gns -o OPTIONS -V "-d $FALLBACK_DNS -p 5252"
+$ gnunet-arm -i dns2gns # Make sure the service is started
+@end example
+
+If you edit your resolv.conf directly, it should contain and entry like this:
+
+@example
+nameserver 127.0.0.1
+@end example
+
+In any case, it is very likely that the method of modification of your
+resolver is OS specific.
+Recently, the combination of NetworkManager and systemd-resolved is becoming
+increasingly popular.
+
+If you use resolvectl and systemd-resolved you can temporarily
+set the nameserver like this:
+
+@example
+$ resolvectl $INTERFACE 127.0.0.1:5353
+@end example
+
+Where @code{$INTERFACE} is your network interface such as ``eth0''.
+
+In order to automatically set the DNS2GNS server if it is running already you
+can use NetworkManager-dispatcher. First, enable it:
+
+@example
+$ sudo systemctl enable NetworkManager-dispatcher.service
+$ sudo systemctl start NetworkManager-dispatcher.service
+@end example
+
+Then, create a script /etc/NetworkManager/dispatch.h/10-dns2-gns.sh:
+
+@example
+#!/bin/sh
+interface=$1
+status=$2
+
+if [ "$interface" = "eth0" ]; then
+  case $status in
+    up)
+      if nc -u -z 127.0.0.1 5353; then
+      resolvectl dns $interface 127.0.0.1:5353
+    fi
+    ;;
+    down)
+    ;;
+  esac
+fi
+@end example
+
+Make sure the script is owned by root and executable:
+
+@example
+$ sudo root:root /etc/NetworkManager/dispatch.d/10-dns2gns.sh
+$ sudo +x /etc/NetworkManager/dispatch.d/10-dns2gns.sh
+@end example
+
+You can test accessing this website using your browser or curl:
+
+@example
+$ curl www.gnunet.org
+@end example
+
+Note that ``gnunet.org'' is a domain that also exists in DNS and for which the
+GNUnet project webservers can provide trusted TLS certificates.
+When using non-DNS names with GNS or aliases, this may result in issues
+when accessing HTTPS websites with browsers.
+In order learn how to provide relief for this issue, read on.
 
+@node Integration with Browsers (SOCKS proxy)
+@subsection Integration with Browsers (SOCKS proxy)
 
-While we recommend integrating GNS using the NSS module in the
-GNU libc Name Service Switch, you can also integrate GNS
-directly with your browser via the @code{gnunet-gns-proxy}.
+While we recommend integrating GNS using the DNS2GNS service or the
+NSSwitch plugin, you can also
+integrate GNS directly with your browser via the @code{gnunet-gns-proxy}.
 This method can have the advantage that the proxy can validate
 TLS/X.509 records and thus strengthen web security; however, the proxy
 is still a bit brittle, so expect subtle failures. We have had reasonable