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.