aboutsummaryrefslogtreecommitdiff
path: root/template/tutorial-debian9.html.j2
diff options
context:
space:
mode:
Diffstat (limited to 'template/tutorial-debian9.html.j2')
-rw-r--r--template/tutorial-debian9.html.j2557
1 files changed, 557 insertions, 0 deletions
diff --git a/template/tutorial-debian9.html.j2 b/template/tutorial-debian9.html.j2
new file mode 100644
index 00000000..2f128333
--- /dev/null
+++ b/template/tutorial-debian9.html.j2
@@ -0,0 +1,557 @@
1{% extends "common/base.j2" %}
2{% block body_content %}
3<div class="container">
4
5 <h2>{{ _("Tutorial: GNUnet on Debian 9") }}</h2>
6
7 <h3>{{ _("Introduction") }}</h3>
8
9 <p>
10 Welcome to the hopefully painless GNUnet tutorial for Debian 9! It provides
11 very concrete instructions on how to compile, install and configure a current
12 version of GNUnet. The goal is to support newcomers, either end users or
13 developers, who want to get in touch with GNUnet for the first time. After
14 installing GNUnet we will make sure that out new GNUnet installation is working
15 correctly.
16 </p>
17
18 <p>
19 <b>Attention: If you came across the official gnunet package for Debian 9,
20 ignore it! It is ancient and not compatible with current GNUnet
21 installations.</b>
22 </p>
23
24 <p>
25 Now let's start!
26 </p>
27
28 <h3>{{ _("Requirements") }}</h3>
29
30 <p>
31 First let's install the following Debian 9 packages to use GNUnet
32 painlessly. Optional dependencies are listed in Appendix A. They are required
33 for some experimental GNUnet features.
34 </p>
35
36 <code>
37 $ sudo apt install 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 openssl libnss3-tools
38 </code>
39
40 <h3>{{ _("Make an installation directory") }}</h3>
41
42 <p>
43 Next we create a directory in our home directory where we store
44 the source code later. We should keep this directory after
45 installation because it contains Makefiles that can be used for
46 uninstalling GNUnet again (see chapter *Uninstall GNUnet and its
47 dependencies*).
48 </p>
49
50 <code>
51 $ mkdir ~/gnunet_installation
52 </code>
53
54 <h3>{{ _("Get the source code") }}</h3>
55
56 <p>
57 We download the GNUnet source code using git. On Debian 9 we need the
58 sources of another library (libmicrohttpd).
59 </p>
60
61 <p>
62 <b>Attention: The official libmicrohttpsd package for Debian 9 is too old, we need
63 at least version 0.9.52.</b>
64 </p>
65
66 <code>
67 $ cd ~/gnunet_installation<br>
68 $ git clone --depth 1 https://gnunet.org/git/gnunet.git<br>
69 $ git clone --depth 1 https://gnunet.org/git/libmicrohttpd.git
70 </code>
71
72 <h3>{{ _("Compile and Install") }}</h3>
73
74
75 <p>
76 Before we can compile GNUnet on Debian 9, we compile and install libmicrohttp
77 </p>
78
79 <code>
80 $ cd ~/gnunet_installation/libmicrohttpd<br>
81 $ autoreconf -fi<br>
82 $ sudo apt install libgnutls28-dev<br>
83 $ ./configure --disable-doc --prefix=/opt/libmicrohttpd<br>
84 $ make -j$(nproc || echo -n 1)<br>
85 $ sudo make install<br>
86 </code>
87
88 <p>
89 Installing GNUnet is not hard. We have two options:
90 installing a *production version* and installing a *development version*. If
91 you want to start writing GNUnet applications or join the GNUnet development
92 choose the development version (it will print more debug output and contains
93 debug symbols that can be displayed with a debugger). Otherwise choose the
94 production version.
95 </p>
96
97 <h4>{{ _("Option 1: GNUnet for production / usage") }}</h4>
98
99 <code>
100 $ cd ~/gnunet_installation/gnunet<br>
101 $ ./bootstrap<br>
102 $ export GNUNET_PREFIX=/usr<br>
103 $ ./configure --prefix=$GNUNET_PREFIX --disable-documentation --with-microhttpd=/opt/libmicrohttpd<br>
104 $ sudo addgroup gnunetdns<br>
105 $ sudo adduser --system --group --disabled-login --home /var/lib/gnunet gnunet<br>
106 $ make -j$(nproc || echo -n 1)<br>
107 $ sudo make install
108 </code>
109
110 <h4>{{ _("Option 2: GNUnet for development") }}</h4>
111
112 <code>
113 $ cd ~/gnunet_installation/gnunet<br>
114 $ ./bootstrap<br>
115 $ export GNUNET_PREFIX=/usr<br>
116 $ export CFLAGS="-g -Wall -O0"<br>
117 $ ./configure --prefix=$GNUNET_PREFIX --disable-documentation --enable-logging=verbose --with-microhttpd=/opt/libmicrohttpd<br>
118 $ make -j$(nproc || echo -n 1)<br>
119 $ sudo make install
120 </code>
121
122<!--
123 <h4>{{ _("Install GNUnet plugin for name resolution") }}</h4>
124 <p>
125 So now it gets a bit nasty. It's not so bad. All we have to do
126 is copy a file and edit another one. The file we need to copy
127 is GNUnet's plugin for the Name Service Switch (NSS) in unix
128 systems. Different unixes expect it in different locations and
129 GNUnet's build system does not try to guess. On Debian 9 we
130 have to do
131 <code>
132 $ sudo cp /usr/lib/gnunet/nss/libnss_gns.so.2 /lib/$(uname -m)-linux-gnu/
133 </code>
134 </p>
135
136 <p>
137 The next step is activating the GNUnet plugin we just copied
138 in the NSS config. It is located in `/etc/nsswitch.conf`. It should
139 contain a line starting with "hosts" similar to this (at least "files"
140 and "dns" should be there):
141 </p>
142
143 <p>
144 <code>
145 $ cat /etc/nsswitch.conf<br>
146 hosts: files mdns4_minimal [NOTFOUND=return] dns
147 </code>
148 </p>
149
150 <p>
151 <b>Attention: Once we modified `etc/nsswitch.conf` DNS resolution will only
152 be possible as long as is GNUnet is running. We can leave the next step out,
153 but then we will not be able to use GNUnet's name resolution in external
154 applications.</b>
155 </p>
156
157 <p>We save a copy of the original file and then modify the line using sed:</p>
158
159 <p>
160 <code>
161 $ sudo cp /etc/nsswitch.conf /etc/nsswitch.conf.original<br>
162 $ sudo sed -i -E 's/^(hosts:.*) dns/\1 gns [NOTFOUND=return] dns/' /etc/nsswitch.conf
163 </code>
164 </p>
165
166 <p>Now in the line starting with "hosts" should contain an entry "gns [NOTFOUND=return]" before the "dns" entry like this:</p>
167
168 <p>
169 <code>
170 hosts: files mdns4_minimal [NOTFOUND=return] gns [NOTFOUND=return] dns
171 </code>
172 </p>
173
174 <p>That's it. It wasn't that nasty, was it?</p>
175-->
176
177 <h3>{{ _("Configuration") }}</h3>
178
179 <p>
180 Congratulations! GNUnet is now installed! Before we start it we
181 need to create a configuration file. By default GNUnet looks in
182 our home directory for the file `~/.gnunet/gnunet.conf`. We can
183 start with an empty file for now:
184 </p>
185
186 <code>
187 $ touch ~/.config/gnunet.conf
188 </code>
189
190 <p>
191 Now we can start it with the command line tool
192 `gnunet-arm` (Automatic Restart Manager).
193 </p>
194
195 <code>
196 $ gnunet-arm -s
197 </code>
198
199 <p>
200 It starts the default GNUnet services. We can list them with the
201 `-I` option:
202 </p>
203
204 <code>
205 $ gnunet-arm -I<br>
206 Running services:<br>
207 ats (gnunet-service-ats)<br>
208 revocation (gnunet-service-revocation)<br>
209 set (gnunet-service-set)<br>
210 nat (gnunet-service-nat)<br>
211 transport (gnunet-service-transport)<br>
212 peerstore (gnunet-service-peerstore)<br>
213 hostlist (gnunet-daemon-hostlist)<br>
214 identity (gnunet-service-identity)<br>
215 namecache (gnunet-service-namecache)<br>
216 peerinfo (gnunet-service-peerinfo)<br>
217 datastore (gnunet-service-datastore)<br>
218 zonemaster (gnunet-service-zonemaster)<br>
219 zonemaster-monitor (gnunet-service-zonemaster-monitor)<br>
220 nse (gnunet-service-nse)<br>
221 cadet (gnunet-service-cadet)<br>
222 dht (gnunet-service-dht)<br>
223 core (gnunet-service-core)<br>
224 gns (gnunet-service-gns)<br>
225 statistics (gnunet-service-statistics)<br>
226 topology (gnunet-daemon-topology)<br>
227 fs (gnunet-service-fs)<br>
228 namestore (gnunet-service-namestore)<br>
229 vpn (gnunet-service-vpn)
230 </code>
231
232 <p>
233 For stopping GNUnet again we can use the `-e` option.
234 </p>
235
236 <code>
237 $ gnunet-arm -e
238 </code>
239
240
241 <h3>{{ _("Make sure it works") }}</h3>
242
243 <p>
244 Let's try out some of GNUnet's use cases. Some should be done
245 before others:
246 </p>
247
248 <ul>
249 <li>filesharing</li>
250 <li>A simple chat using CADET</li>
251 <li>Name resolution using GNS on the command line</li>
252 <li>Name resolution using GNS with a browser (do it on the command line first)</li>
253 <li>Serving a website using VPN (do name resolution with a browser first)</li>
254 </ul>
255
256 <h4>{{ _("filesharing") }}</h4>
257
258 <p>
259 Let's publish a file in the GNUnet filesharing network. We use the keywords
260 ("commons" and "state") so other people will be able to search for the file.
261 </p>
262
263 <p>
264 We can choose any file and describe it with meaningful keywords (using the
265 `-k` command line option).
266 </p>
267
268 <code>
269 $ gnunet-publish -k commons -k state ostrom.pdf<br>
270 Publishing `/home/myself/ostrom.pdf' done.<br>
271 URI is `gnunet://fs/chk/M57SXDJ72EWS25CT6307KKJ8K0GCNSPTAZ649NA1NS10MJB4A1GZ9EN4Y02KST9VA5BHE8B335RPXQVBWVZ587Y83WQ7J3DHMBX30Q8.DHNGBN4CB2DBX1QRZ1R0B1Q18WTEAK4R94S9D57C9JMJJ3H7SSQDCV4D1218C4S2VP085AMQQSMG18FCP6NQMZQZJ91XR5NBX7YF0V0.42197237'.
272 </code>
273
274
275 <p>Finding the file by keyword works with `gnunet-search`.</p>
276
277 <code>
278 $ gnunet-search commons<br>
279 #1:<br>
280 gnunet-download -o "ostrom.pdf" gnunet://fs/chk/M57SXDJ72EWS25CT6307KKJ8K0GCNSPTAZ649NA1NS10MJB4A1GZ9EN4Y02KST9VA5BHE8B335RPXQVBWVZ587Y83WQ7J3DHMBX30Q8.DHNGBN4CB2DBX1QRZ1R0B1Q18WTEAK4R94S9D57C9JMJJ3H7SSQDCV4D1218C4S2VP085AMQQSMG18FCP6NQMZQZJ91XR5NBX7YF0V0.42197237
281 </code>
282
283 <p>
284 It gives us the command line call to download the file (and store it as
285 ostrom.pdf)!
286 </p>
287
288 <h4>{{ _("CADET (and Chat)") }}</h4>
289
290 <p>
291 We can use the `gnunet-cadet` command line tool to open a port and from
292 another machine connect to this port and chat or transfer data. First we need
293 our *peer ID* of the GNUnet peer opening the port.
294 </p>
295
296 <code>
297 $ gnunet-peerinfo -s<br>
298 I am peer `P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG'.
299 </code>
300
301
302 <p>
303 Now we open the port (it can be any string!):
304 </p>
305
306 <code>
307 $ gnunet-cadet -o my-secret-port
308 </code>
309
310 <p>
311 On the other machine we can connect using the peer ID and the port
312 and start chatting!
313 </p>
314
315 <code>
316 $ gnunet-cadet P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG my-secret-port
317 </code>
318
319 <h4>{{ _("Name resolution using GNS on the command line") }}</h4>
320
321 <p>
322 GNS is the GNU name service, a fully decentralized alternatice to
323 DNS. We'll publish an IP address in a GNS record try to resolve it
324 on the command line. First we need an identity which is the
325 equivalent to a zone in DNS. We'll call it "myself" and create it
326 using the `gnunet-identity` command line tool. Instead of "myself"
327 you can surely use your nick or any other name.
328 </p>
329
330 <code>
331 $ gnunet-identity -C myself
332 </code>
333
334 <p>
335 We can check if it worked using the same tool. We expect the name
336 of our identity and the corresponding public key to be
337 displayed.
338 </p>
339
340 <code>
341 $ gnunet-identity -d<br>
342 myself - HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG
343 </code>
344
345 <p>
346 Now we add a public `A` record to our zone. It has the name "ccc", a value
347 of "195.54.164.39" and it expires after one day.
348 </p>
349
350 <code>
351 $ gnunet-namestore -z myself -a -e "1 d" -p -t A -n ccc -V 195.54.164.39
352 </code>
353
354 <p>
355 Now we can query that record using the command line tool `gnunet-gns`.
356 </p>
357
358 <code>
359 $ gnunet-gns -t A -u ccc.myself<br>
360 ccc.myself:<br>
361 Got `A' record: 195.54.164.39
362 </code>
363
364 <p>
365 So it worked! But only resolving our own records is boring. So we
366 can give our identity (the public key of it to be precise) to
367 someone else so they can try to resolve our records, too. The
368 other person (Bob) has to add it to his namestore like this:
369 <p>
370
371 <code>
372 $ gnunet-namestore -z myself -a -e never -p -t PKEY -n alice -V HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG
373 </code>
374
375 <p>
376 Our identity in Bobs namestore is a public record (-p) and never
377 expires (-e never). Now Bob (let's assume he has called his identity
378 myself, too) should be able to resolve our "ccc" record, too!
379 </p>
380
381 <code>
382 $ gnunet-gns -t A -u ccc.alice.myself<br>
383 ccc.alice.myself:<br>
384 Got `A' record: 195.54.164.39
385 </code>
386
387 <p>
388 It can continue like this. A friend of Bob would be able to
389 resolve our records too because Bob published our identity in a
390 public record. Bobs friend would simply use "ccc.alice.bob.myself"
391 to resolve our "ccc" record.
392 </p>
393
394
395 <h4>{{ _("Name resolution using GNS with a browser") }}</h4>
396
397 <p>
398 In the previous use case "Name resolution using GNS on the
399 command line" we got an idea about what GNS is about, but now
400 let's use it with a browser, to make it actually useful. Currently
401 Firefox and Chromium are known to work.
402 </p>
403
404 <p>
405 Many websites enforce HTTPS and thus provide certificates for
406 their hostnames (and not our GNS names). Browsers don't like wrong
407 hostnames in certificates and will present error messages. So
408 GNUnet has to trick them by generating own certificates for our
409 GNS names. This means we need to create our own certificate
410 authority and tell our browser about it. Luckily there's a script
411 for it:
412 </p>
413
414 <code>
415 $ gnunet-gns-proxy-setup-ca
416 </code>
417
418 <p>
419 After executing this script the Browser has to be restarted.
420 </p>
421
422 <p>
423 GNUnet provides a proxy service (gnunet-gns-proxy) that the
424 browser can send DNS and HTTP traffic to. It will try to resolve
425 names with GNS first and forward the rest of the DNS traffic to
426 the system's DNS resolver. It will also take care of the HTTP
427 traffic, so the browser gets valid certificates and the web server
428 will not be confused by our GNS hostnames. Our GNS namestore
429 doesn't know about any DNS hostnames yet, so we have to store
430 them, too. For our "ccc" A record, we have to store a LEHO (legacy
431 hostname) record, too. It must contain the website's original DNS
432 hostname:
433 </p>
434
435 <code>
436 $ gnunet-namestore -z myself -a -e "1 d" -p -t LEHO -n ccc -V www.ccc.de
437 </code>
438
439 <p>
440 Now let's start gnunet-gns-proxy.
441 </p>
442
443 <code>
444 $ /usr/lib/gnunet/libexec/gnunet-gns-proxy
445 </code>
446
447 <p>
448 Our browser has to be configured so it uses our proxy. In Firefox
449 we have to set these options under "about:config":
450 </p>
451
452 <code>
453 network.proxy.socks: localhost<br>
454 network.proxy.socks_port: 7777<br>
455 network.proxy.socks_remote_dns true<br>
456 network.proxy.type: 1
457 </code>
458
459 <p>
460 To tell Chromium to use the proxy, it has to be started with the
461 "--proxy-server" command line option:
462 </p>
463
464 <code>
465 $ chromium --proxy-server="socks5://127.0.0.1:7777"
466 </code>
467
468 <p>
469 Now we should be able to resolve our GNS names in the browser! We
470 just have to type "https://ccc.myself" into the address bar. If
471 our friend Bob prepared his system, too, he can resolve our record
472 by typing "ccc.alice.myself".
473 </p>
474
475
476 <h4>{{ _("VPN") }}</h4>
477
478 <p>
479 TBD
480 </p>
481
482 <h3>{{ _("Uninstall GNUnet and its dependencies") }}</h3>
483
484 <code>
485 $ cd ~/gnunet_installation/gnunet<br>
486 $ sudo make uninstall<br>
487 $ cd ~/gnunet_installation/libmicrohttpd<br>
488 $ sudo make uninstall<br>
489 $ 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>
490 $ sudo apt autoremove<br>
491 $ sudo userdel -r gnunet<br>
492 $ sudo groupdel gnunet<br>
493 $ sudo groupdel gnunetdns<br>
494 $ sudo mv /etc/nsswitch.conf.original /etc/nsswitch.conf<br>
495 $ sudo rm /lib/$(uname -m)-linux-gnu/libnss_gns.so.2
496 </code>
497
498 <h3>{{ _("Appendix A: Optional GNUnet features") }}</h3>
499
500 <p>
501 TBD
502 </p>
503
504 <h3>{{ _("Troubleshooting") }}</h3>
505
506 <h4>{{ _("You can't reach other people's nodes") }}</h4>
507
508 <p>
509 Should our computer not have reached the open GNUnet network automatically,
510 we can manually instruct our node how to reach the nodes of our friends. This
511 works by exchanging HELLO strings. This is how we get a hello string for our
512 computer.
513 </p>
514
515 <code>
516 $ gnunet-peerinfo -gn
517 </code>
518
519 <p>
520 We can now pass this string to our friends "out of band" (using
521 whatever existing chat or messaging technology). If the string
522 contains some private IP networks we don't want to share, we can
523 carefully edit them out.
524 </p>
525
526 <p>
527 Once we receive such strings from our friends, we can add them
528 like this:
529 </p>
530
531 <code>
532 gnunet-peerinfo -p <string>
533 </code>
534
535
536 <p>
537 Now our GNUnet nodes can attempt reaching each other directly. This may
538 still fail due to NAT traversal issues.
539 </p>
540
541
542<!--
543 <h4>{{ _("OMG you guys broke my internet") }}</h4>
544
545 <p>
546 We can replace `/etc/nsswitch.conf` with the backup we made earlier
547 (`/etc/nsswitch.conf.original`). Now DNS resolution should work again without a
548 running GNUnet.
549 </p>
550
551 <code>
552 $ cp /etc/nsswitch.conf.original /etc/nsswitch.conf
553 </code>
554-->
555
556</div>
557{% endblock body_content %}