1 files changed, 507 insertions, 0 deletions

diff --git a/tutorial-macos.html.j2 b/tutorial-macos.html.j2
new file mode 100644
index 00000000..fec2850b
--- /dev/null
+++ b/tutorial-macos.html.j2
@@ -0,0 +1,507 @@
+{% extends "common/base.j2" %}
+{% block body_content %}
+<div class="container">
+
+  <h2>{{ _("Tutorial: GNUnet on macOS 10.14 (Mojave)") }}</h2>
+
+  <h3>{{ _("Introduction") }}</h3>
+
+  <p>
+    Welcome to the hopefully painless GNUnet tutorial for macOS Mojave! It provides
+    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>
+
+  <h3>{{ _("Requirements") }}</h3>
+
+  <p>
+    First, install <a href="https://brew.sh">homebrew</a> and <a href="https://developer.apple.com/xcode/">XCode</a>.
+    Then install the following packages:
+  </p>
+
+  <code>
+    $ sudo brew install git autoconf automake gcc gettext gnutls jansson libextractor libgcrypt libffi libidn2 libmicrohttpd libmpc libtool libunistring pkg-config unbound
+  </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
+  </code>
+
+  <h3>{{ _("Get the source code") }}</h3>
+
+  <code>
+    $ cd ~<br>
+    $ git clone --depth 1 https://gnunet.org/git/gnunet.git gnunet_src<br>
+  </code>
+  <p>
+    In order to have a gnutls with DANE support, you need to edit the formula:
+  </p>
+  <code>
+  $ brew edit gnutls
+  </code>
+  <p>
+    Add the line "depends_on 'unbound'" to the dependencies in the formula.
+    Then in the install function before the configure add:
+  </p>
+  <code>
+    ENV['CFLAGS']='-I/usr/local/Cellar/unbound/1.9.0/include'<br/>
+    ENV['LDFLAGS']='-L/usr/local/Cellar/unbound/1.9.0/lib'
+  </code>
+  <p>
+    Reinstall gnutls from source:
+  </p>
+  <code>
+    $ brew reinstall -s gnutls
+  </code>
+
+  <h3>{{ _("Compile and Install") }}</h3>
+
+
+  <p>
+    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_src<br>
+  $ ./bootstrap<br>
+  $ export CC=gcc-8
+  $ export GNUNET_PREFIX=~/gnunet<br>
+  $ ./configure --prefix=$GNUNET_PREFIX --disable-documentation<br>
+  </code>
+  <p>
+  You might see configure failing telling you that it ``cannot run C compiled programs.''.
+  In this case, you might need to open/run Xcode once and you will be prompted to
+  install additonal packages.
+  Then, you might have to manually install the command line tools from here https://developer.apple.com/download/more/ (you need an Apple ID for this).
+  Install those and execute
+  </p>
+  <code>
+  $ open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
+  </code>
+  <p>
+    After configure passes, you need to add a 'gnunetdns' group using the macOS system preferences.
+  Further, you need to add a user 'gnunet'. Then:
+  </p>
+  <code>
+  $ make<br>
+  $ sudo make install
+  </code>
+
+  <h4>{{ _("Option 2: GNUnet for development") }}</h4>
+
+  <p>
+  Perform the same steps as for Option 1, but add the configure flat '--enable-experimental'
+  </p>
+  <!--
+  <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>
+  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 `~/.gnunet/gnunet.conf`. We can
+  start with an empty file for now:
+  </p>
+
+  <code>
+  $ touch ~/.config/gnunet.conf
+  </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 %}