path: root/template/use.html.j2

{% extends "common/base.j2" %}
{% block body_content %}
<article class="container">

  <header>
    <h1>{{ _("How to use GNUnet - in a nutshell") }}</h1>
  </header>

  <div class="row">
    <div class="col-2 d-none d-lg-block"><!-- for large viewports show menu for better orientation -->
      <nav class="nav subnav position-fixed flex-column border-right" style="position:fixed">
      <a class="nav-link" href="#filesharing">{{ _("Filesharing") }}</a>
      <a class="nav-link" href="#cadet">{{ _("CADET") }}</a>
      <a class="nav-link" href="#groupchat">{{ _("Minimal Groupchat") }}</a>
      <a class="nav-link" href="#gns_cli">{{ _("GNS with CLI") }}</a>
      <a class="nav-link" href="#gns_browser">{{ _("GNS with Browser") }}</a>
      <a class="nav-link" href="#vpn">{{ _("VPN") }}</a>
      <!-- <a class="nav-link" href="#conversation">{{ _("Conversation") }}</a> -->
      <a class="nav-link" href="#trouble">{{ _("Trouble Shooting") }}</a>
      </nav>
    </div>

    <div class="col">
      <section>
        <p>
         This document is just a brief introduction on what can be done with GNUnet. Find out much more in our <a ref="https://docs.gnunet.org/">documentation</a>, e.g. in the section <a href="https://docs.gnunet.org/handbook/gnunet.html#toc-Using-GNUnet-1">"using GNUnet"</a> in the handbook.

          Please note that the handbook / reference manual uses the graphical user interface (UI) gnunet-gtk to configure GNUnet. In this introduction, we use the command line interface (CLI).
        </p>
      </section>

<section>

  <h3>{{ _("Accessing GNUnet") }}</h3>

  <p>
    Now we can start it with the command line tool
    `gnunet-arm` (Automatic Restart Manager) with the -s option; s=start.
  </p>

  <code>
    $ gnunet-arm -s
  </code>

  <p>
    It starts the default GNUnet services. We can list them with the
    `-I` option:
  </p>

  <code>
    $ gnunet-arm -I<br>
    Running services:<br>
    ats (gnunet-service-ats)<br>
    revocation (gnunet-service-revocation)<br>
    set (gnunet-service-set)<br>
    nat (gnunet-service-nat)<br>
    transport (gnunet-service-transport)<br>
    peerstore (gnunet-service-peerstore)<br>
    hostlist (gnunet-daemon-hostlist)<br>
    identity (gnunet-service-identity)<br>
    namecache (gnunet-service-namecache)<br>
    peerinfo (gnunet-service-peerinfo)<br>
    datastore (gnunet-service-datastore)<br>
    zonemaster (gnunet-service-zonemaster)<br>
    zonemaster-monitor (gnunet-service-zonemaster-monitor)<br>
    nse (gnunet-service-nse)<br>
    cadet (gnunet-service-cadet)<br>
    dht (gnunet-service-dht)<br>
    core (gnunet-service-core)<br>
    gns (gnunet-service-gns)<br>
    statistics (gnunet-service-statistics)<br>
    topology (gnunet-daemon-topology)<br>
    fs (gnunet-service-fs)<br>
    namestore (gnunet-service-namestore)<br>
    vpn (gnunet-service-vpn)
  </code>

  <h3>{{ _("Leaving GNUnet") }}</h3>
  <p>
    For stopping GNUnet again we can use the `-e` option; e=end.
  </p>

  <code>
    $ gnunet-arm -e
  </code>

      <section>
        <h3>{{ _("Make sure your GNUnet installation works...") }}</h3>
         <p>After installing and starting GNUnet you should make sure that your peer is connecting
              to the P2P-network. By typing gnunet-core you should see something like this:
        </p>
         <p>
              <code>
              $ gnunet-core <br>
              Tue Oct 30 19:58:48 2018: connection established DSTJ (timeout in 293 s)<br>
              Tue Oct 30 19:58:48 2018: connection established A4MK (timeout in 292 s)<br>
              Tue Oct 30 19:58:48 2018: connection established 7WRD (timeout in 299 s)<br>
              Tue Oct 30 19:58:48 2018: connection established 5WBG (timeout in 299 s)<br>
              </code>
              
            <p>Overtime the list will change as new peers connect or drop out, this is normal.</p>
        </p>
        There are much more options to see if you are connected and how. E.g. 'gnunet-peerinfo' shows you all peers your peer knows, or with "tail -f ~/.cache/gnunet/*" you'll get to see what's going on with your node.
      </section>

      <section>
        <h3>{{ _("... and play around with it.") }}</h3>
        <p>
              So let's try out some of GNUnet's most common use-cases to illustrate it's power. Please be mindful that some should be done in a particular order, one after another:
        </p>

        <ul>
          <li>Filesharing</li>
          <li>A simple chat using CADET</li>
          <li>Another simple chat using a nim client</i>
          <li>Name resolution using GNS on the command line</li>
          <li>Name resolution using GNS with a browser (do it on the command line first)</li>
          <li>Serving a website using VPN (do name resolution with a browser first)</li>
          <!-- <li>Conversation </li> -->
        </ul>
      </section>


      <section>
        <h3><a name="filesharing" class="subnav-anchor"></a>{{ _("Filesharing") }}</h3>

        <p>
          Let's publish a file in the GNUnet filesharing network. We use the keywords
          ("commons" and "state") so other people will be able to search for the file.
        </p>

        <p>
          We can choose any file and describe it with meaningful keywords (using the
          `-k` command line option), in this example these are "commons" and "state".
        </p>
        <p>
        <code>
          $ gnunet-publish -k commons -k state ostrom.pdf<br>
          Publishing `/home/myself/ostrom.pdf' done.<br>
          URI is `gnunet://fs/chk/M57S...
        </code>
        </p>
        <p>
          GNUnet users can find the file by using the <code>gnunet-search</code> command.
        </p>
        <p>
        <code>
          $ gnunet-search commons<br>
          #1:<br>
          gnunet-download -o "ostrom.pdf" gnunet://fs/chk/M57S...
        </code>
        </p>
        <p>
          <code>gnunet-search</code> returns the command line call to download the file (and store it as ostrom.pdf)!
        </p>
        <p>
        <p>
            It's recommended for filesharing that you increase GNUnet's bandwidth restrictions
            from the actually pretty low defaults. The example below sets the WAN
            and LAN limits to the value "unlimited".
        </p>

        <code>
            $ gnunet-config -s ats -o WAN_QUOTA_IN -V unlimited<br />
            $ gnunet-config -s ats -o WAN_QUOTA_OUT -V unlimited<br /> 
            $ gnunet-config -s ats -o LAN_QUOTA_IN -V unlimited<br />
            $ gnunet-config -s ats -o LAN_QUOTA_OUT -V unlimited<br /> 
        </code>
        </p>
        <p>
          Please note that it might take some time (up to some hours) till your peers can see your freshly uploaded files. 
        </p>
        <p> Further reading: Please also refer to the chapter on
    <a href="https://docs.gnunet.org/handbook/gnunet.html#File_002dsharing">filesharing in the handbook</a>.

      </section>

      <section>
        <h3><a name="cadet" class="subnav-anchor"></a>{{ _("CADET (and Chat)") }}</h3>
        <p>The CADET subsystem is at the heart of the GNUnet project because it is responsible for secure end-to-end communications between peers (nodes) in the GNUnet overlay network.</p>        
        <p>
          Users can chat and send files to each other on the GNUnet network using a simple CADET tool. We use the `gnunet-cadet` command line tool to open a port on our local machine and from another peer on the network connect to this port. Users can then chat or transfer files.
         </p>
         
         <p>
          In the following example, Alice will create a CADET session on her laptop. Bob will then connect to Alice from his desktop. Alice will first need her <b>peer ID</b> of the GNUnet and provide it to Bob.
          </p>
        <p>
        <code>
          alice@laptop $ gnunet-peerinfo -s<br>
          I am peer `P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG'.
        </code>
        </p>
        <p>
          Now Alice will open a port using the -o option, giving it a name, in this case Alice calls it 'my-secret-port' (it can be any string!):
        </p>
        <p>
        <code>
          alice@laptop $ gnunet-cadet -o my-secret-port
        </code>
        </p>
        <p>On Bob's machine he can connect to Alice using her <b>peer ID</b> and the port name. Once connected they can start chatting.</p>
        <p>
        <code>
         bob@desktop $ gnunet-cadet P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG my-secret-port
        </code>
        </p>
        
        <p>It's worth noting that the other peers can be a friend's machine which has GNUnet running, or it can also just be another shell on your own machine.</p>
        
        <p>
              If you are interested in the details of CADET, please read the <a href="https://docs.gnunet.org/handbook/gnunet.html#CADET-Subsystem">"Cadet-Subsystem" chapter in the GNUnet handbook</a>. 
        </p>
      </section>



      <section>
        <h3><a name="groupchat" class="subnav-anchor"></a>{{ _("Chatting with a (simple) client") }}</h3>
	<div class="alert" style="background-color: #419edb;">
	     <div class="alert-content">
	     	  Notice: The groupchat code is not working with the actual GNUnet release atm!
	     </div>
	</div>
         <p>
          To make chatting a tiny bit easier and prettier, we need to install and compile additional software.
     </p>
     <p>
          First we have to install the Nim programming language. Please refer to their <a href="https://nim-lang.org/install.html">project site</a> for further details. The preferred method is using you distributions package manager, e.g. for Debian it would look like this: 
      </p>
      <code>
        $ sudo apt install nim<br>
        $ nim --version<br>
        Nim Compiler Version 1.2.2 [Linux: amd64]<br>
        Compiled at 2020-06-16<br>
        Copyright (c) 2006-2020 by Andreas Rumpf<br>
        <br>
        active boot switches: -d:release -d:nativeStackTrace<br>
      </code>
      <p>
       If the displayed version is <b>1.2.2 or newer</b>, we have a compatible version and can continue downloading and compiling the groupchat. If the version is older (like on Ubuntu 18.04) we can install Nim using a tool called <i>choosenim</i>:
      </p>
      <code>
          $ curl https://nim-lang.org/choosenim/init.sh -sSf | sh
      </code>
      <p>
      Then we follow the onscreen instructions. More information can be found in the <a href="https://nim-lang.org/install.html">official documentation</a>.
      </p>
      <p>In the onscreen instructions you'll be ask to add a line to your bashrc - once you've done that, re-read your bash environment to make the change active: 
      </p>
      <code>
        $ source ~/.bashrc
      </code>
      
      <p>
          After we have installed (and maybe upgraded) Nim we download and compile the GNUnet groupchat application:
         </p>
         <p>
         <code>
              $ git clone https://git.gnunet.org/groupchat.git<br>
              $ cd groupchat<br>
              $ make<br>
         </code>
         <p>
         <p>
            We can now try to enter a chat server running on another GNUnet node using the command:
         </p>
         <p>
         <code>
               $ LD_LIBRARY_PATH=/path/to/gnunetlibs ./groupchat --config=/path/to/gnunet.conf --server=88RXABKJNMT426FY81N2DXN0M2X37SW5Q1NR005YPDZ1Q7A22CHG --port=t3ss --nick=YOURNICK<br>
         </code>
         <p>
              The peer key and port name given in this example should work as they are almost always online and running groupchat on port "t3ss".
         <p>
      </section>



      <section>
        <h3><a name="gns_cli" class="subnav-anchor"></a>{{ _("Name resolution using GNS on the command line") }}</h3>
        <p>The GNU Name Service (GNS) is a fully decentralized alternative to the Domain Name System (DNS). Where GNS does not suffer the same major <a href="https://en.wikipedia.org/wiki/Domain_Name_System#Security_issues">security flaws as DNS</a>.
        </p>
        
        <p>
        In this example, Alice will save the IP address (195.54.164.39) of the Chaos Computer Club e.V. (CCC) homepage into a GNUnet namestore record and then try to resolve it using GNUnet GNS.
        
        
         <p> First Alice needs to create a GNUnet identity which is the equivalent to a zone in a DNS. We'll call it "myself" and create it using the `gnunet-identity` command line tool. Instead of "myself" you can use your nickname, or any other name. </p>

        <p>
        <code>
          alice@laptop $ gnunet-identity -C myself
        </code>
        </p>
        
        <p>Alice can check to see if it worked using the same tool. The name of her identity and the corresponding public key are displayed.</p>
        <p>
        <code>
          alice@laptop $ gnunet-identity -d<br>
          myself - HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG
        </code>
        </p>
        <p>
            Now Alice adds a public `A` record to the zone. We'll call it "ccc" with the value "195.54.164.39" and it expires after one day.
        </p>
        <p>
        <code>
          alice@laptop $ gnunet-namestore -z myself -a -e "1 d" -p -t A -n ccc -V 195.54.164.39
        </code>
        </p>
        <p>Now the GNS can be queried using the command line tool `gnunet-gns`.</p>
        <p>
        <code>
          alice@laptop  $ gnunet-gns -t A -u ccc.myself<br>
          ccc.myself:<br>
          Got `A' record: 195.54.164.39
        </code>
        </p>
        <p>
          So it worked! But only resolving our own records is boring. So we
          can give our identity (the public key of it to be precise) to
          someone else so they can try to resolve our records, too. The
          other person (Bob) has to add it to his namestore like this:
        </p>
        <p>
        <code>
          bob@desktop $ gnunet-namestore -z myself -a -e never -p -t PKEY -n alice -V HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG
        </code>
        </p>
        <p>
          Alices identity in Bobs namestore is a public record (-p) and never
          expires (-e never). Now Bob (let's assume he has called his
          identity myself, too) should be able to resolve Alice's "ccc" record,
          too!
        </p>
        <p>
        <code>
          $ gnunet-gns -t A -u ccc.alice.myself<br>
          ccc.alice.myself:<br>
          Got `A' record: 195.54.164.39
        </code>
        </p>
        <p>
          It can continue like this. A friend of Bob would be able to
          resolve Alice's records too because Bob published her identity in a
          public record. Bobs friend would simply use "ccc.alice.bob.myself"
          to resolve Alice's "ccc" record.
        </p>
        <p>
      See the <a href="https://docs.gnunet.org/handbook/gnunet.html#First-steps-_002d-Using-the-GNU-Name-System">chapter "Using the GNU Name System" in our handbook</a> for a more detailed documentation.
        </p>
      </section>



      <section id='gns_proxy'>
        <h3><a name="gns_browser" class="subnav-anchor"></a>{{ _("Name resolution using GNS with a browser") }}</h3>

        <p>
          In the previous use-case "Name resolution using GNS on the command line" we saw how we could retrieve a value (e.g. an IP address) associated with a given named record (e.g. a web address). 
          Now we'll see how GNS can be used with a browser, making it actually useful. Currently Firefox and Chromium are known to work with GNS.
        </p>

        <p>
          Many websites enforce HTTPS by providing TLS certificates for
          their hostnames, with the aim of encrypting the web page content between the clients browser and the hostname server, and authenticating the server and client to each other. This is so 
          that a 3rd party cannot see what is being communicated between the client (browser) and server (website host). This is important, for example, if you are using online banking where you don't want anyone seeing your customer ID and password.
        </p>
          
      <p>
          Unfortunately, if a browser resolves a hostname through the GNS, the TLS certificates will have the original hostname and the browser will present an error message. In the previous example, we resolved "ccc.myself" to 195.54.164.39 but the hostname's TLS certificate refers to the actual hostname as "https://www.ccc.de/"
          
          So GNUnet has to trick the browser by generating it's own certificates for the hostnames GNS
          resolves. This means we need to create our own certificate authority
          and tell our browser to use this instead. Luckily there's a script to fix this problem:
       </p> 
        
          
        <p>
        <code>
          $ gnunet-gns-proxy-setup-ca
        </code>
        </p>
        <p>After executing this script the Browser has to be restarted.</p>

        <p>
          GNUnet provides a proxy service (gnunet-gns-proxy) that the
          browser can send DNS and HTTP traffic to. It will try to resolve
          names with GNS first and forward the rest of the DNS traffic to
          the system's DNS resolver. It will also take care of the HTTP
          traffic, so the browser gets valid certificates and the web server
          will not be confused by the hostnames resolved by GNS instead of the DNS. The GNS namestore
          does not know about any DNS hostnames yet, so we have to store
          them, too. For our "ccc" A record, we have to store a LEHO (LEgacy
          HOstname) record, too. It must contain the website's original DNS
          hostname:
        </p>
        
        <p>
        <code>
          $ gnunet-namestore -z myself -a -e "1 d" -p -t LEHO -n ccc -V www.ccc.de
        </code>
        </p>
        <p>Now lets start gnunet-gns-proxy.</p>
        <p>
        <code>
          $ /usr/lib/gnunet/libexec/gnunet-gns-proxy
        </code>
        </p>
        <p>
          Our browser has to be configured so it uses our proxy. In Firefox
          we have to set these options under "about:config":
        </p>
        <p>
        <code>
          network.proxy.socks:            localhost<br>
          network.proxy.socks_port:       7777<br>
          network.proxy.socks_remote_dns  true<br>
          network.proxy.type:             1
        </code>
        </p>
        <p>
          To tell Chromium to use the proxy, it has to be started with the
          "--proxy-server" command line option:
        </p>
        <p>
        <code>
          $ chromium --proxy-server="socks5://127.0.0.1:7777"
        </code>
        </p>
        <p>
          Now we should be able to resolve our GNS names in the browser! We
          just have to type "https://ccc.myself" into the address bar. If
          our friend Bob prepared his system, too, he can resolve our record
          by typing "ccc.alice.myself".
        </p>
        <p>
         See the <a href="https://docs.gnunet.org/handbook/gnunet.html#Integration-with-Browsers">chapter on Integration with Browsers in our handbook</a> for a more detailed description.
        </p>
      </section>



      <section>
        <h3><a name="vpn" class="subnav-anchor"></a>{{ _("VPN") }}</h3>
        <p>
              VPN can be used to share your Internet connection (yes, this may be dangerous, just as running a Tor exit node) or to provide access to services on your host (this should be less dangerous, as long as those services are secure).
        </p>
        <p>
          In this tutorial we concentrate on providing access to services on your host.
        </p>
        <p>
          For documentation to share your Internet connection have a look into <a href="https://docs.gnunet.org/handbook/gnunet.html#Configuring-the-GNUnet-VPN">chapter "Configuring the GNUnet VPN" in the handbook.</a>
        </p>
        <p>
          First you have to edit your gnunet.conf and add this section.
        </p>
        <p>
          <code>
          [exit]</br>
          START_ON_DEMAND = YES
          </code>
        </p>
        <p>
          This is necessary to start the exit daemon.
        </p>
        <p>
          Furthermore you need to add a section for your service.
        </p>
        <p>
          <code>
          [http.gnunet.]</br>
          TCP_REDIRECTS = 80:169.254.86.1:80
          </code>
        </p>
        <p>
          Here a service named 'http' is configured to be accessed on a remote and local host on port 80. The IP address is the default IP address for the exit interface. If you like to change to another private IP address range you can change the option in section 'exit':
        </p>
        <p>
          <code>
          IPV4ADDR = 169.254.86.1
          </code>
        </p>
        <p>
          Now we have to add a GNS record to the namestore.
        </p>
        <p>
          <code>
          gnunet-namestore -z myself -a -e "1 d" -p -t VPN -n www -V "1 PKEY http"
          </code>
        </p>
        <p>
          Where myself is the name of the zone we already used <a href='#gns_proxy'>above</a>, but now we are adding a record of type VPN, and the value is a string containing three values. A boolean indicating the use of TCP or UDP (TCP in the example above), the public key of your node and the identifier of the service we used <a href='#'>above</a> ([http.gnunet.].
        </p>
        <p>
          After we added this record we should be able to access www.myself like we did ccc.myself via the browser <a href='#gns_proxy'>above</a>.
        </p>
        <p>
          The UI version of this Tutorial can be find in Chapter <a href='https://docs.gnunet.org/handbook/gnunet.html#First-steps-_002d-Using-the-GNUnet-VPN'>Using the GNUnet VPN</a> in the handbook.
        </p>
      </section>

<!--
      <section>
        <h3><a name="conversation" class="subnav-anchor"></a>{{ _("Conversation") }}</h3>
        <p>
          TBD, see <a href="https://docs.gnunet.org/handbook/gnunet.html#First-steps-_002d-Using-GNUnet-Conversation">chapter "Using GNUnet Conversation" in the handbook.</a>
        </p>
      </section>
-->




      <section>
        <h3><a name="trouble" class="subnav-anchor"></a>{{ _("Trouble Shooting") }}</h3>

  <h4>{{ _("You can't reach other people's nodes") }}</h3>

  <p>
    Should our computer not have reached the open GNUnet network automatically,
    we can manually instruct our node how to reach the nodes of our friends. This
    works by exchanging HELLO strings. This is how we get a hello string for our
    computer.
  </p>

  <code>
    $ gnunet-peerinfo -gn
  </code>

  <p>
    We can now pass this string to our friends "out of band" (using
    whatever existing chat or messaging technology). If the string
    contains some private IP networks we don't want to share, we can
    carefully edit them out.
  </p>

  <p>
    Once we receive such strings from our friends, we can add them
    like this:
  </p>

  <code>
    $ gnunet-peerinfo -p <string>
  </code>

  <p>
    Now our GNUnet nodes can attempt reaching each other directly. This may
    still fail due to NAT traversal issues.
  </p>


<!--
  <h4>{{ _("OMG you guys broke my internet") }}</h3>

  <p>
    We can replace `/etc/nsswitch.conf` with the backup we made earlier
    (`/etc/nsswitch.conf.original`). Now DNS resolution should work again without a
    running GNUnet.
  </p>

    <code>
      $ cp /etc/nsswitch.conf.original /etc/nsswitch.conf
    </code>
-->

      </section>


    </div>
  </div>
</article>
{% endblock body_content %}