1 files changed, 590 insertions, 0 deletions

diff --git a/template/install-on-debian9.html.j2 b/template/install-on-debian9.html.j2
new file mode 100644
index 00000000..74bf7f57
--- /dev/null
+++ b/template/install-on-debian9.html.j2
@@ -0,0 +1,590 @@
+{% extends "common/base.j2" %}
+{% block body_content %}
+<div class="container">
+
+  <h2>{{ _("Tutorial: GNUnet on Debian 9") }}</h2>
+
+  <h3>{{ _("Introduction") }}</h3>
+
+  <p>
+    Welcome to the hopefully painless GNUnet tutorial for Debian 9! It provides
+    very concrete instructions on how to compile, install and configure a current
+    version of GNUnet. The goal is to support newcomers, either end users or
+    developers, who want to get in touch with GNUnet for the first time. After
+    installing GNUnet we will make sure that out new GNUnet installation is working
+    correctly.
+  </p>
+
+  <p>
+    <b>Attention: If you came across the official gnunet package for Debian 9,
+      ignore it! It is ancient and not compatible with current GNUnet
+      installations.</b>
+  </p>
+
+  <p>
+    Now let's start!
+  </p>
+
+  <h3>{{ _("Requirements") }}</h3>
+
+  <p>
+    First let's install the following Debian 9 packages to use GNUnet
+    painlessly. Optional dependencies are listed in Appendix A. They are required
+    for some experimental GNUnet features.
+  </p>
+
+  <code>
+      $ sudo apt install git libtool autoconf autopoint \<br>
+      build-essential libgcrypt-dev libidn11-dev zlib1g-dev \<br>
+      libunistring-dev libglpk-dev miniupnpc libextractor-dev \<br>
+      libjansson-dev libcurl4-gnutls-dev gnutls-bin libsqlite3-dev \<br>
+      openssl libnss3-tools libopus-dev libpulse-dev libogg-dev
+  </code>
+
+  <h3>{{ _("Make an installation directory") }}</h3>
+
+  <p>
+    Next we create a directory in our home directory where we store
+    the source code later. We should keep this directory after
+    installation because it contains Makefiles that can be used for
+    uninstalling GNUnet again (see chapter *Uninstall GNUnet and its
+    dependencies*).
+  </p>
+
+  <code>
+    $ mkdir ~/gnunet_installation
+  </code>
+
+  <h3>{{ _("Get the source code") }}</h3>
+
+  <p>
+    We download the GNUnet source code using git. On Debian 9 we need the
+    sources of another library (libmicrohttpd).
+  </p>
+
+  <p>
+    <b>Attention: The official libmicrohttpd package for Debian 9 is too old, we need
+      at least version 0.9.52.</b>
+  </p>
+
+  <code>
+    $ cd ~/gnunet_installation<br>
+    $ git clone --depth 1 https://gnunet.org/git/gnunet.git<br>
+    $ git clone --depth 1 https://gnunet.org/git/gnunet-gtk.git<br>
+    $ git clone --depth 1 https://gnunet.org/git/libmicrohttpd.git
+  </code>
+
+  <h3>{{ _("Compile and Install") }}</h3>
+
+
+  <p>
+    Before we can compile GNUnet on Debian 9, we compile and install libmicrohttpd.
+  </p>
+
+  <code>
+    $ cd ~/gnunet_installation/libmicrohttpd<br>
+    $ autoreconf -fi<br>
+    $ sudo apt install libgnutls28-dev<br>
+    $ ./configure --disable-doc --prefix=/opt/libmicrohttpd<br>
+    $ make -j$(nproc || echo -n 1)<br>
+    $ sudo make install<br>
+  </code>
+
+  <p>
+    Installing GNUnet is not hard. We have two options:
+    installing a *production version* and installing a *development version*. If
+    you want to start writing GNUnet applications or join the GNUnet development
+    choose the development version (it will print more debug output and contains
+    debug symbols that can be displayed with a debugger). Otherwise choose the
+    production version.
+  </p>
+  
+  <h4>{{ _("Option 1: GNUnet for production / usage") }}</h4>
+
+  <code>
+    $ cd ~/gnunet_installation/gnunet<br>
+    $ ./bootstrap<br>
+    $ ./configure --prefix=$GNUNET_PREFIX --disable-documentation --with-microhttpd=/opt/libmicrohttpd<br>
+    $ sudo addgroup gnunetdns<br>
+    $ sudo adduser --system --group --disabled-login --home /var/lib/gnunet gnunet<br>
+    $ make -j$(nproc || echo -n 1)<br>
+    $ sudo make install
+  </code>
+
+  <h4>{{ _("Option 2: GNUnet for development") }}</h4>
+
+  <code>
+    $ cd ~/gnunet_installation/gnunet<br>
+    $ ./bootstrap<br>
+    $ export GNUNET_PREFIX=/usr<br>
+    $ export CFLAGS="-g -Wall -O0"<br>
+    $ ./configure --prefix=$GNUNET_PREFIX --disable-documentation --enable-logging=verbose --with-microhttpd=/opt/libmicrohttpd<br>
+    $ make -j$(nproc || echo -n 1)<br>
+    $ sudo make install
+  </code>
+
+  <h4>{{ _("Option 3: gnunet-gtk") }}</h4>
+  <p>
+    Installing the Gtk+-based graphical user
+    interface can be done on top of either the production or development installation.
+  </p>
+  <code>
+    $ sudo apt install libgtk-3-dev libgladeui-dev libunique-dev libqrencode-dev
+    $ cd ~/gnunet_installation/gnunet-gtk<br>
+    $ ./bootstrap<br>
+    $ export GNUNET_PREFIX=/usr<br>
+    $ export CFLAGS="-g -Wall -O0"<br>
+    $ ./configure --prefix=$GNUNET_PREFIX --with-gnunet=$GNUNET_PREFIX<br>
+    $ make -j$(nproc || echo -n 1)<br>
+    $ sudo make install
+  </code>
+
+<!--
+  <h4>{{ _("Install GNUnet plugin for name resolution") }}</h4>
+      <p>
+        So now it gets a bit nasty. It's not so bad. All we have to do
+        is copy a file and edit another one. The file we need to copy
+        is GNUnet's plugin for the Name Service Switch (NSS) in unix
+        systems. Different unixes expect it in different locations and
+        GNUnet's build system does not try to guess. On Debian 9 we
+        have to do
+        <code>
+          $ sudo cp /usr/lib/gnunet/nss/libnss_gns.so.2 /lib/$(uname -m)-linux-gnu/
+        </code>
+      </p>
+
+  <p>
+    The next step is activating the GNUnet plugin we just copied
+    in the NSS config. It is located in `/etc/nsswitch.conf`. It should
+    contain a line starting with "hosts" similar to this (at least "files"
+    and "dns" should be there):
+  </p>
+
+  <p>
+    <code>
+      $ cat /etc/nsswitch.conf<br>
+      hosts: files mdns4_minimal [NOTFOUND=return] dns
+    </code>
+  </p>
+
+  <p>
+    <b>Attention: Once we modified `/etc/nsswitch.conf` DNS resolution will only
+      be possible as long as is GNUnet is running. We can leave the next step out,
+      but then we will not be able to use GNUnet's name resolution in external
+      applications.</b>
+  </p>
+
+  <p>We save a copy of the original file and then modify the line using sed:</p>
+
+  <p>
+    <code>
+      $ sudo cp /etc/nsswitch.conf /etc/nsswitch.conf.original<br>
+      $ sudo sed -i -E 's/^(hosts:.*) dns/\1 gns [NOTFOUND=return] dns/' /etc/nsswitch.conf
+    </code>
+  </p>
+
+  <p>Now in the line starting with "hosts" should contain an entry "gns [NOTFOUND=return]" before the "dns" entry like this:</p>
+
+  <p>
+    <code>
+      hosts: files mdns4_minimal [NOTFOUND=return] gns [NOTFOUND=return] dns
+    </code>
+  </p>
+
+  <p>That's it. It wasn't that nasty, was it?</p>
+-->
+
+  <h3>{{ _("Configuration") }}</h3>
+
+  <p>
+    Congratulations! GNUnet is now installed! Before we start it we
+    need to create a configuration file. By default GNUnet looks in
+    our home directory for the file `~/.config/gnunet.conf`. We can
+    start with an empty file for now:
+  </p>
+
+  <code>
+    $ touch ~/.config/gnunet.conf
+  </code>
+
+  <p>
+    It's reccomended that you increase your bandwidth restrictions
+    from the acutely 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>
+    Now we can start it with the command line tool
+    `gnunet-arm` (Automatic Restart Manager).
+  </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>
+
+  <p>
+    For stopping GNUnet again we can use the `-e` option.
+  </p>
+
+  <code>
+    $ gnunet-arm -e
+  </code>
+
+
+  <h3>{{ _("Make sure it works") }}</h3>
+
+  <p>
+    Let's try out some of GNUnet's use cases. Some should be done
+    before others:
+  </p>
+
+  <ul>
+    <li>filesharing</li>
+    <li>A simple chat using CADET</li>
+    <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>
+  </ul>
+
+  <h4>{{ _("filesharing") }}</h4>
+
+  <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).
+  </p>
+
+  <code>
+    $ gnunet-publish -k commons -k state ostrom.pdf<br>
+    Publishing `/home/myself/ostrom.pdf' done.<br>
+    URI is `gnunet://fs/chk/M57SXDJ72EWS25CT6307KKJ8K0GCNSPTAZ649NA1NS10MJB4A1GZ9EN4Y02KST9VA5BHE8B335RPXQVBWVZ587Y83WQ7J3DHMBX30Q8.DHNGBN4CB2DBX1QRZ1R0B1Q18WTEAK4R94S9D57C9JMJJ3H7SSQDCV4D1218C4S2VP085AMQQSMG18FCP6NQMZQZJ91XR5NBX7YF0V0.42197237'.
+  </code>
+
+
+  <p>Finding the file by keyword works with `gnunet-search`.</p>
+
+  <code>
+    $ gnunet-search commons<br>
+    #1:<br>
+    gnunet-download -o "ostrom.pdf" gnunet://fs/chk/M57SXDJ72EWS25CT6307KKJ8K0GCNSPTAZ649NA1NS10MJB4A1GZ9EN4Y02KST9VA5BHE8B335RPXQVBWVZ587Y83WQ7J3DHMBX30Q8.DHNGBN4CB2DBX1QRZ1R0B1Q18WTEAK4R94S9D57C9JMJJ3H7SSQDCV4D1218C4S2VP085AMQQSMG18FCP6NQMZQZJ91XR5NBX7YF0V0.42197237
+  </code>
+
+  <p>
+    It gives us the command line call to download the file (and store it as
+    ostrom.pdf)!
+  </p>
+
+  <h4>{{ _("CADET (and Chat)") }}</h4>
+
+  <p>
+    We can use the `gnunet-cadet` command line tool to open a port and from
+    another machine connect to this port and chat or transfer data. First we need
+    our *peer ID* of the GNUnet peer opening the port.
+  </p>
+
+  <code>
+    $ gnunet-peerinfo -s<br>
+    I am peer `P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG'.
+  </code>
+
+
+  <p>
+    Now we open the port (it can be any string!):
+  </p>
+
+  <code>
+    $ gnunet-cadet -o my-secret-port
+  </code>
+
+  <p>
+    On the other machine we can connect using the peer ID and the port
+    and start chatting!
+  </p>
+
+  <code>
+    $ gnunet-cadet P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG my-secret-port
+  </code>
+
+  <h4>{{ _("Name resolution using GNS on the command line") }}</h4>
+
+  <p>
+    GNS is the GNU name service, a fully decentralized alternatice to
+    DNS. We'll publish an IP address in a GNS record try to resolve it
+    on the command line. First we need an identity which is the
+    equivalent to a zone in DNS. We'll call it "myself" and create it
+    using the `gnunet-identity` command line tool. Instead of "myself"
+    you can surely use your nick or any other name.
+  </p>
+
+  <code>
+    $ gnunet-identity -C myself
+  </code>
+
+  <p>
+    We can check if it worked using the same tool. We expect the name
+    of our identity and the corresponding public key to be
+    displayed.
+  </p>
+
+  <code>
+    $ gnunet-identity -d<br>
+    myself - HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG
+  </code>
+
+  <p>
+    Now we add a public `A` record to our zone. It has the name "ccc", a value
+    of "195.54.164.39" and it expires after one day.
+  </p>
+
+  <code>
+    $ gnunet-namestore -z myself -a -e "1 d" -p -t A -n ccc -V 195.54.164.39
+  </code>
+
+  <p>
+    Now we can query that record using the command line tool `gnunet-gns`.
+  </p>
+
+  <code>
+    $ gnunet-gns -t A -u ccc.myself<br>
+    ccc.myself:<br>
+    Got `A' record: 195.54.164.39
+  </code>
+
+  <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>
+
+  <code>
+    $ gnunet-namestore -z myself -a -e never -p -t PKEY -n alice -V HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG
+  </code>
+
+  <p>
+    Our 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 our "ccc" record, too!
+  </p>
+
+  <code>
+    $ gnunet-gns -t A -u ccc.alice.myself<br>
+    ccc.alice.myself:<br>
+    Got `A' record: 195.54.164.39
+  </code>
+
+  <p>
+    It can continue like this. A friend of Bob would be able to
+    resolve our records too because Bob published our identity in a
+    public record. Bobs friend would simply use "ccc.alice.bob.myself"
+    to resolve our "ccc" record.
+  </p>
+
+  
+  <h4>{{ _("Name resolution using GNS with a browser") }}</h4>
+
+  <p>
+    In the previous use case "Name resolution using GNS on the
+    command line" we got an idea about what GNS is about, but now
+    let's use it with a browser, to make it actually useful. Currently
+    Firefox and Chromium are known to work.
+  </p>
+
+  <p>
+    Many websites enforce HTTPS and thus provide certificates for
+    their hostnames (and not our GNS names). Browsers don't like wrong
+    hostnames in certificates and will present error messages. So
+    GNUnet has to trick them by generating own certificates for our
+    GNS names. This means we need to create our own certificate
+    authority and tell our browser about it. Luckily there's a script
+    for it:
+  </p>
+
+  <code>
+    $ gnunet-gns-proxy-setup-ca 
+  </code>
+
+  <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 our GNS hostnames. Our GNS namestore
+    doesn't 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>
+
+  <code>
+    $ gnunet-namestore -z myself -a -e "1 d" -p -t LEHO -n ccc -V www.ccc.de
+  </code>
+
+  <p>
+    Now let's start gnunet-gns-proxy.
+  </p>
+
+  <code>
+    $ /usr/lib/gnunet/libexec/gnunet-gns-proxy
+  </code>
+
+  <p>
+    Our browser has to be configured so it uses our proxy. In Firefox
+    we have to set these options under "about:config":
+  </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>
+    To tell Chromium to use the proxy, it has to be started with the
+    "--proxy-server" command line option:
+  </p>
+
+  <code>
+    $ chromium --proxy-server="socks5://127.0.0.1:7777"
+  </code>
+
+  <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>
+
+
+  <h4>{{ _("VPN") }}</h4>
+
+  <p>
+    TBD
+  </p>
+
+  <h3>{{ _("Uninstall GNUnet and its dependencies") }}</h3>
+
+  <code>
+    $ cd ~/gnunet_installation/gnunet<br>
+    $ sudo make uninstall<br>
+    $ cd ~/gnunet_installation/libmicrohttpd<br>
+    $ sudo make uninstall<br>
+    $ sudo apt remove git libtool autoconf autopoint build-essential libgcrypt-dev libidn11-dev zlib1g-dev libunistring-dev libglpk-dev miniupnpc libextractor-dev libjansson-dev libcurl4-gnutls-dev libsqlite3-dev<br>
+    $ sudo apt autoremove<br>
+    $ sudo userdel -r gnunet<br>
+    $ sudo groupdel gnunet<br>
+    $ sudo groupdel gnunetdns<br>
+    $ sudo mv /etc/nsswitch.conf.original /etc/nsswitch.conf<br>
+    $ sudo rm /lib/$(uname -m)-linux-gnu/libnss_gns.so.2
+  </code>
+
+  <h3>{{ _("Appendix A: Optional GNUnet features") }}</h3>
+
+  <p>
+    TBD
+  </p>
+
+  <h3>{{ _("Troubleshooting") }}</h3>
+
+  <h4>{{ _("You can't reach other people's nodes") }}</h4>
+
+  <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") }}</h4>
+
+  <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>
+-->
+
+</div>
+{% endblock body_content %}