gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

integration.rst (6359B)


      1 .. _gns-integration:
      2 
      3 Using GNS names in applications
      4 ===============================
      5 
      6 ``gnunet-gns`` resolves GNS names on the command line.  This page explains
      7 how to make GNS names work in ordinary applications such as web browsers,
      8 ``curl`` or ``ssh``, which only know how to use DNS.
      9 
     10 There are two kinds of applications:
     11 
     12 - **GNS-aware applications** use GNS directly through its API.  Examples are
     13   GNUnet's own :doc:`re:claimID </users/reclaim>` and the
     14   :doc:`messenger </users/messenger>`.  They need no configuration.
     15 - **GNS-unaware applications** expect names to be resolved by the operating
     16   system or by DNS.  For these, you put GNS in the path of their name
     17   lookups, using one of the methods below.
     18 
     19 .. list-table::
     20    :header-rows: 1
     21    :widths: 22 39 39
     22 
     23    * - Method
     24      - Works for
     25      - Notes
     26    * - `DNS2GNS`_ (recommended)
     27      - every application that uses the system's resolver
     28      - answers DNS queries for GNS names and forwards all other queries to
     29        a DNS resolver of your choice
     30    * - `NSS plugin`_
     31      - applications that resolve names through glibc
     32      - not available on systems that generate ``/etc/nsswitch.conf``
     33        automatically, or on non-glibc systems
     34    * - `SOCKS proxy for browsers`_
     35      - one browser at a time
     36      - can validate TLS certificates via GNS records, but is brittle
     37 
     38 .. _DNS2GNS:
     39 
     40 DNS2GNS
     41 -------
     42 
     43 ``gnunet-dns2gns`` is a small DNS server.  It answers queries for GNS names
     44 using GNS and passes every other query on to an ordinary DNS resolver.
     45 Pointing your system's resolver at it makes GNS names work everywhere.
     46 
     47 By default it listens on ``127.0.0.1`` and ``::1``, port ``15353``, and
     48 forwards non-GNS queries to ``9.9.9.9``.  To use a different upstream
     49 resolver, for example your router:
     50 
     51 .. code-block:: console
     52 
     53    $ gnunet-config -s dns2gns -o OPTIONS -V "-d 192.168.1.1"
     54 
     55 Start the service and check that it works:
     56 
     57 .. code-block:: console
     58 
     59    $ gnunet-arm -i dns2gns
     60    $ dig +short @127.0.0.1 -p 15353 www.myzone
     61    192.0.2.1
     62 
     63 To start it automatically with your peer, set ``IMMEDIATE_START = YES`` in
     64 its configuration section:
     65 
     66 .. code-block:: console
     67 
     68    $ gnunet-config -s dns2gns -o IMMEDIATE_START -V YES
     69 
     70 Now tell your system to use it.  How to do that depends on your system.
     71 
     72 **With systemd-resolved** (most current GNU/Linux desktops), set it as the
     73 DNS server of your network interface, here ``wlan0``:
     74 
     75 .. code-block:: console
     76 
     77    $ sudo resolvectl dns wlan0 127.0.0.1:15353
     78 
     79 This lasts until the interface is reconfigured.  Some distribution
     80 packages, for example Fedora's, ship a NetworkManager dispatcher script
     81 that does this automatically each time an interface comes up; it is
     82 activated by setting ``ENABLE_RESOLVECTL_NMDISPATCHER = YES`` in the
     83 ``[dns2gns]`` section of ``/etc/gnunet.conf``.
     84 
     85 **With a plain /etc/resolv.conf**, you cannot specify a port, so DNS2GNS
     86 must listen on the standard DNS port 53.  This requires running it with
     87 the necessary privileges, typically as part of a :ref:`system-wide
     88 installation <The-Multi_002dUser-Setup>`.  Set ``PORT = 53`` in the
     89 ``[dns2gns]`` section and add this line at the top of
     90 ``/etc/resolv.conf``::
     91 
     92    nameserver 127.0.0.1
     93 
     94 Test the result with any application:
     95 
     96 .. code-block:: console
     97 
     98    $ curl http://www.myzone/
     99 
    100 .. note::
    101 
    102    Using DNS2GNS breaks the end-to-end verification of GNS for the
    103    application: the application trusts whatever the local DNS2GNS server
    104    tells it.  This is fine as long as DNS2GNS runs on your own machine.  Do
    105    not use a DNS2GNS server run by somebody else.
    106 
    107 .. _NSS plugin:
    108 
    109 NSS plugin
    110 ----------
    111 
    112 On systems with the GNU C library, GNS can be added to the *name service
    113 switch* (NSS), which most programs use to look up host names.
    114 
    115 Distribution packages install the plugin ``libnss_gns.so.2`` for you.  When
    116 building from source, it is installed into the library directory of your
    117 installation prefix; glibc only finds it there if that directory is in the
    118 dynamic linker's search path (run ``sudo ldconfig`` after installing to
    119 ``/usr/local``).
    120 
    121 To activate the plugin, edit ``/etc/nsswitch.conf``.  Find the line
    122 starting with ``hosts:``, for example::
    123 
    124    hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
    125 
    126 and insert ``gns [NOTFOUND=return]`` after ``files``::
    127 
    128    hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
    129 
    130 On some systems, in particular those using systemd-resolved,
    131 ``/etc/nsswitch.conf`` is generated automatically and must not be edited.
    132 Use `DNS2GNS`_ there.
    133 
    134 .. warning::
    135 
    136    In GNUnet 0.29, the NSS plugin fails to resolve names: it parses the
    137    output of ``gnunet-gns -r``, which now contains a progress indicator.
    138    Use `DNS2GNS`_ until this is fixed.
    139 
    140 .. _SOCKS proxy for browsers:
    141 
    142 SOCKS proxy for browsers
    143 ------------------------
    144 
    145 ``gnunet-gns-proxy`` is a SOCKS5 proxy that resolves GNS names for a
    146 browser.  Unlike DNS2GNS, it can use GNS records (``LEHO``, ``BOX``/``TLSA``)
    147 to validate TLS certificates of sites hosted under GNS names, by acting as
    148 a local certificate authority.  It is, however, still brittle: expect
    149 subtle failures with some sites, and switch it off again if a page behaves
    150 oddly.
    151 
    152 First, create and install the proxy's certificate authority.  The script
    153 supports Firefox and Chromium, and needs the ``certutil`` (from NSS) and
    154 ``openssl`` programs:
    155 
    156 .. code-block:: console
    157 
    158    $ gnunet-gns-proxy-setup-ca
    159 
    160 Then start the proxy and check that it is running:
    161 
    162 .. code-block:: console
    163 
    164    $ gnunet-arm -i gns-proxy
    165    $ gnunet-arm -I | grep gns-proxy
    166 
    167 The proxy listens on ``localhost``, port ``7777``.  Configure your browser
    168 to use it:
    169 
    170 Chromium
    171    Start the browser with
    172    ``chromium --proxy-server=socks5://localhost:7777``.  Type URLs including
    173    the ``http://`` or ``https://`` prefix; otherwise Chromium may run a web
    174    search instead.
    175 
    176 Firefox
    177    In *Settings*, *Network Settings*, choose *Manual proxy configuration*,
    178    enter ``localhost`` and port ``7777`` as *SOCKS Host*, select *SOCKS v5*,
    179    and enable *Proxy DNS when using SOCKS v5*.  Then open ``about:config``
    180    and set ``browser.fixup.alternate.enabled`` to ``false``, so that Firefox
    181    does not rewrite a name like ``www.myzone`` into ``www.myzone.com``.
    182 
    183 Note that accessing ordinary websites through GNS is experimental and not
    184 the primary goal of GNS at this time.  We welcome help with testing.