.. _gns-integration: Using GNS names in applications =============================== ``gnunet-gns`` resolves GNS names on the command line. This page explains how to make GNS names work in ordinary applications such as web browsers, ``curl`` or ``ssh``, which only know how to use DNS. There are two kinds of applications: - **GNS-aware applications** use GNS directly through its API. Examples are GNUnet's own :doc:`re:claimID ` and the :doc:`messenger `. They need no configuration. - **GNS-unaware applications** expect names to be resolved by the operating system or by DNS. For these, you put GNS in the path of their name lookups, using one of the methods below. .. list-table:: :header-rows: 1 :widths: 22 39 39 * - Method - Works for - Notes * - `DNS2GNS`_ (recommended) - every application that uses the system's resolver - answers DNS queries for GNS names and forwards all other queries to a DNS resolver of your choice * - `NSS plugin`_ - applications that resolve names through glibc - not available on systems that generate ``/etc/nsswitch.conf`` automatically, or on non-glibc systems * - `SOCKS proxy for browsers`_ - one browser at a time - can validate TLS certificates via GNS records, but is brittle .. _DNS2GNS: DNS2GNS ------- ``gnunet-dns2gns`` is a small DNS server. It answers queries for GNS names using GNS and passes every other query on to an ordinary DNS resolver. Pointing your system's resolver at it makes GNS names work everywhere. By default it listens on ``127.0.0.1`` and ``::1``, port ``15353``, and forwards non-GNS queries to ``9.9.9.9``. To use a different upstream resolver, for example your router: .. code-block:: console $ gnunet-config -s dns2gns -o OPTIONS -V "-d 192.168.1.1" Start the service and check that it works: .. code-block:: console $ gnunet-arm -i dns2gns $ dig +short @127.0.0.1 -p 15353 www.myzone 192.0.2.1 To start it automatically with your peer, set ``IMMEDIATE_START = YES`` in its configuration section: .. code-block:: console $ gnunet-config -s dns2gns -o IMMEDIATE_START -V YES Now tell your system to use it. How to do that depends on your system. **With systemd-resolved** (most current GNU/Linux desktops), set it as the DNS server of your network interface, here ``wlan0``: .. code-block:: console $ sudo resolvectl dns wlan0 127.0.0.1:15353 This lasts until the interface is reconfigured. Some distribution packages, for example Fedora's, ship a NetworkManager dispatcher script that does this automatically each time an interface comes up; it is activated by setting ``ENABLE_RESOLVECTL_NMDISPATCHER = YES`` in the ``[dns2gns]`` section of ``/etc/gnunet.conf``. **With a plain /etc/resolv.conf**, you cannot specify a port, so DNS2GNS must listen on the standard DNS port 53. This requires running it with the necessary privileges, typically as part of a :ref:`system-wide installation `. Set ``PORT = 53`` in the ``[dns2gns]`` section and add this line at the top of ``/etc/resolv.conf``:: nameserver 127.0.0.1 Test the result with any application: .. code-block:: console $ curl http://www.myzone/ .. note:: Using DNS2GNS breaks the end-to-end verification of GNS for the application: the application trusts whatever the local DNS2GNS server tells it. This is fine as long as DNS2GNS runs on your own machine. Do not use a DNS2GNS server run by somebody else. .. _NSS plugin: NSS plugin ---------- On systems with the GNU C library, GNS can be added to the *name service switch* (NSS), which most programs use to look up host names. Distribution packages install the plugin ``libnss_gns.so.2`` for you. When building from source, it is installed into the library directory of your installation prefix; glibc only finds it there if that directory is in the dynamic linker's search path (run ``sudo ldconfig`` after installing to ``/usr/local``). To activate the plugin, edit ``/etc/nsswitch.conf``. Find the line starting with ``hosts:``, for example:: hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 and insert ``gns [NOTFOUND=return]`` after ``files``:: hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 On some systems, in particular those using systemd-resolved, ``/etc/nsswitch.conf`` is generated automatically and must not be edited. Use `DNS2GNS`_ there. .. warning:: In GNUnet 0.29, the NSS plugin fails to resolve names: it parses the output of ``gnunet-gns -r``, which now contains a progress indicator. Use `DNS2GNS`_ until this is fixed. .. _SOCKS proxy for browsers: SOCKS proxy for browsers ------------------------ ``gnunet-gns-proxy`` is a SOCKS5 proxy that resolves GNS names for a browser. Unlike DNS2GNS, it can use GNS records (``LEHO``, ``BOX``/``TLSA``) to validate TLS certificates of sites hosted under GNS names, by acting as a local certificate authority. It is, however, still brittle: expect subtle failures with some sites, and switch it off again if a page behaves oddly. First, create and install the proxy's certificate authority. The script supports Firefox and Chromium, and needs the ``certutil`` (from NSS) and ``openssl`` programs: .. code-block:: console $ gnunet-gns-proxy-setup-ca Then start the proxy and check that it is running: .. code-block:: console $ gnunet-arm -i gns-proxy $ gnunet-arm -I | grep gns-proxy The proxy listens on ``localhost``, port ``7777``. Configure your browser to use it: Chromium Start the browser with ``chromium --proxy-server=socks5://localhost:7777``. Type URLs including the ``http://`` or ``https://`` prefix; otherwise Chromium may run a web search instead. Firefox In *Settings*, *Network Settings*, choose *Manual proxy configuration*, enter ``localhost`` and port ``7777`` as *SOCKS Host*, select *SOCKS v5*, and enable *Proxy DNS when using SOCKS v5*. Then open ``about:config`` and set ``browser.fixup.alternate.enabled`` to ``false``, so that Firefox does not rewrite a name like ``www.myzone`` into ``www.myzone.com``. Note that accessing ordinary websites through GNS is experimental and not the primary goal of GNS at this time. We welcome help with testing.