aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNils Gillmann <ng0@n0.is>2018-11-10 16:21:24 +0000
committerNils Gillmann <ng0@n0.is>2018-11-10 16:21:24 +0000
commitc6f471d16aa9f6a15a636a34d74cc322e2f9d5af (patch)
tree746b2f75c39828136051fc5fe4b5f00ddb6140e3
parent65c7b8ae061963b0ccedc15e46bea7cfb4edd81a (diff)
parentfbb30437326b703d08ba9e2b1f3dca306586246e (diff)
downloadwww-c6f471d16aa9f6a15a636a34d74cc322e2f9d5af.tar.gz
www-c6f471d16aa9f6a15a636a34d74cc322e2f9d5af.zip
Merge branch 'master' of gnunet.org:www
-rw-r--r--common/navigation.j2.inc1
-rw-r--r--tutorial-archpi.html.j2150
-rw-r--r--tutorial-debian9.html.j2339
-rw-r--r--tutorial.html.j226
4 files changed, 516 insertions, 0 deletions
diff --git a/common/navigation.j2.inc b/common/navigation.j2.inc
index 66c070d1..6b1e1292 100644
--- a/common/navigation.j2.inc
+++ b/common/navigation.j2.inc
@@ -27,6 +27,7 @@
27 <li class="dropdown"> 27 <li class="dropdown">
28 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">{{ _("Documentation") }} <span class="caret"></span></a> 28 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">{{ _("Documentation") }} <span class="caret"></span></a>
29 <ul class="dropdown-menu"> 29 <ul class="dropdown-menu">
30 <li><a href="tutorial.html">{{ _("Tutorial") }}</a></li>
30 <li><a href="glossary.html">{{ _("Glossary") }}</a></li> 31 <li><a href="glossary.html">{{ _("Glossary") }}</a></li>
31 <li><a href="https://docs.gnunet.org">{{ _("Handbook") }}</a></li> 32 <li><a href="https://docs.gnunet.org">{{ _("Handbook") }}</a></li>
32 <li><a href="faq.html">{{ _("FAQ") }}</a></li> 33 <li><a href="faq.html">{{ _("FAQ") }}</a></li>
diff --git a/tutorial-archpi.html.j2 b/tutorial-archpi.html.j2
new file mode 100644
index 00000000..cf5eb28c
--- /dev/null
+++ b/tutorial-archpi.html.j2
@@ -0,0 +1,150 @@
1{% extends "common/base.j2" %}
2{% block body_content %}
3<div class="container">
4
5<h2>{{ _("Tutorial: GNUnet on Archlinux/Pi") }}</h2>
6
7Welcome to this GNUnet tutorial for Archlinux on a Raspberry Pi 3. If you want
8to run a GNUnet node on a separte System, permanently online, with low energy
9consumption, this might be the thing for you. This tutorial shows you how to
10install, run, and operate it.
11
12<h3>{{ _("Requirements") }}</h3>
13
14<p>First you need the hardware. This tutorial works with a Raspberry Pi 3. The
15other Pi versions I haven't tested, but they should probably work, too. To
16install Archlinux on the Pi3, follow the instructions from <a
17href="https://archlinuxarm.org/platforms/armv8/broadcom/raspberry-pi-3">archlinuxarm.org</a>.</p>
18
19<p>That was easy, right? Our goal now is to build GNUnet from source. So, let's
20install the tools for building new software.</p>
21
22<p><code>
23> sudo pacman -S base-devel
24</code></p>
25
26<p>Now we can continue to install the following Archlinux dependencies to
27compile GNUnet on our Pi.</p>
28
29<p><code>
30$ pacman -Su libmicrohttpd libgcrypt gnurl libunistring gnutls libidn
31libextractor openssl libltdl sqlite texinfo which gettext zlib
32pkg-config git miniupnpc libextractor jansson nim
33</code></p>
34
35<h3>{{ _("Get the Source Code") }}</h3>
36
37<p>We are getting closer. Download the GNUnet source code which we will build
38in the next step:<p>
39
40<p><code>
41> git clone https://gnunet.org/git/gnunet.git<br>
42</code></p>
43
44<p>Now it's time to compile GNUnet.</p>
45
46<p><code>
47> cd gnunet<br>
48> ./bootstrap # Run this to generate the configure files.<br>
49> ./configure # Use --help to see the various flags available to you.<br>
50> make -j$(nproc || echo -n 1)<br>
51> sudo make install<br>
52</code></p>
53
54<p>Congrats! GNUnet is now installed!</p>
55
56<h3>{{ _("Run") }}</h3>
57
58<p>By default GNUnet looks in our home directory for the file
59~/.gnunet/gnunet.conf. We can start with an empty file for now:</p>
60
61<p><code>
62> touch ~/.config/gnunet.conf
63</code></p>
64
65<p>Now we can start it with the commandline tool gnunet-arm (Automatic Restart
66Manager).</p>
67
68<p><code>
69> gnunet-arm -s
70</code></p>
71
72<p>It starts the default GNUnet services. We can list them with the -I option:</p>
73
74<p><code>
75> gnunet-arm -I<br>
76Running services:<br>
77ats (gnunet-service-ats)<br>
78revocation (gnunet-service-revocation)<br>
79set (gnunet-service-set)<br>
80nat (gnunet-service-nat)<br>
81transport (gnunet-service-transport)<br>
82peerstore (gnunet-service-peerstore)<br>
83hostlist (gnunet-daemon-hostlist)<br>
84identity (gnunet-service-identity)<br>
85namecache (gnunet-service-namecache)<br>
86peerinfo (gnunet-service-peerinfo)<br>
87datastore (gnunet-service-datastore)<br>
88zonemaster (gnunet-service-zonemaster)<br>
89zonemaster-monitor (gnunet-service-zonemaster-monitor)<br>
90nse (gnunet-service-nse)<br>
91cadet (gnunet-service-cadet)<br>
92dht (gnunet-service-dht)<br>
93core (gnunet-service-core)<br>
94gns (gnunet-service-gns)<br>
95statistics (gnunet-service-statistics)<br>
96topology (gnunet-daemon-topology)<br>
97fs (gnunet-service-fs)<br>
98namestore (gnunet-service-namestore)<br>
99vpn (gnunet-service-vpn)<br>
100</code></p>
101
102<p>For stopping GNUnet again we can use the -e option.</p>
103
104<p><code>
105> gnunet-arm -e
106</code></p>
107
108<h3>{{ _("Make sure, it works!") }}</h3>
109
110After starting GNUnet you should make sure, that your peer is connecting to the
111P2P-network. By typing gnunet-core you should see something like this:
112
113<p><code>
114> gnunet-core<br>
115Tue Oct 30 19:58:48 2018: connection established DSTJ (timeout in 293 s)<br>
116Tue Oct 30 19:58:48 2018: connection established A4MK (timeout in 292 s)<br>
117Tue Oct 30 19:58:48 2018: connection established 7WRD (timeout in 299 s)<br>
118Tue Oct 30 19:58:48 2018: connection established 5WBG (timeout in 299 s)<br>
119</code></p>
120
121<h3>{{ _("Chat the cat") }}</h3>
122
123<p>To be able to chat, we need to install and compile additional
124software.</p>
125
126<p><code>
127> git clone https://gnunet.org/git/gnunet-nim.git
128> cd gnunet-nim/examples
129> nim c groupchat.nim
130</code></p>
131
132<p>Fine! We can now try to enter a chat server running on another GNUnet node.
133
134<p><code>
135> LD_LIBRARY_PATH=/path/to/gnunetlibs ./groupchat --config=/path/to/gnunet.conf --server=YV6G9EP9K3X41BM3FJ3D29BDZR6358XNZ6KDZVV7DFW729YB0KCG --port=welcome --nick=YOURNICK
136</code></p>
137
138<p>You should now see something like this:</p>
139
140<p><code>
141> 2018-10-30 19:50:10 Welcome 8Q2T! participants: @[] <br>
142Hello GNUnet!<br>
1432018-10-30 19:52:53 [8Q2T] Hello GNUnet!
144</code></p>
145
146<p>Here we have typed "Hello gnunet!" to standard in which is then written out
147to standard out after having been sent back from GNUnet.</p>
148
149</div>
150{% endblock body_content %}
diff --git a/tutorial-debian9.html.j2 b/tutorial-debian9.html.j2
new file mode 100644
index 00000000..bab12e73
--- /dev/null
+++ b/tutorial-debian9.html.j2
@@ -0,0 +1,339 @@
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>Welcome to the hopefully painless GNUnet tutorial for Debian 9! It provides
10very concrete instructions on how to compile, install and configure a current
11version of GNUnet. The goal is to support newcomers, either end users or
12developers, who want to get in touch with GNUnet for the first time. After
13installing GNUnet we will make sure that out new GNUnet installation is working
14correctly.</p>
15
16<p><b>Attention: If you came across the official gnunet package for Debian 9,
17ignore it! It is ancient and not compatible with current GNUnet
18installations.</b></p>
19
20<p>Now let's start!</p>
21
22<h3>{{ _("Requirements") }}</h3>
23
24<p>First let's install the following Debian 9 packages to use GNUnet
25painlessly. Optional dependencies are listed in Appendix A. They are required
26for some experimental GNUnet features.</p>
27
28<p><code>
29$ 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
30</code></p>
31
32<h3>{{ _("Make an installatino directory") }}</h3>
33
34<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>
35
36<p><code>
37$ mkdir ~/gnunet_installation
38</code></p>
39
40<h3>{{ _("Get the source code") }}</h3>
41
42<p>We download the GNUnet source code using git. On Debian 9 we need the
43sources of another library (libmicrohttpd). There exists a Debian 9 package for
44libmicrohttpd too, but it is too old.</p>
45
46<p><code>
47$ cd ~/gnunet_installation<br>
48$ git clone --depth 1 https://gnunet.org/git/gnunet.git<br>
49$ git clone --depth 1 https://gnunet.org/git/libmicrohttpd.git
50</code></p>
51
52<h3>{{ _("Compile and Install") }}</h3>
53
54<p>Installing GNUnet is not hard, it only requires one little nasty step which
55involves modifying an important config file of the operating system. So we'll
56pay extra attention while doing this.</p>
57
58<p>Before we can compile GNUnet, we compile and install libmicrohttpd.</p>
59
60<p><code>
61$ cd ~/gnunet_installation/libmicrohttpd<br>
62$ autoreconf -fi<br>
63$ sudo apt install libgnutls28-dev<br>
64$ ./configure --disable-doc --prefix=/opt/libmicrohttpd<br>
65$ make -j$(nproc || echo -n 1)<br>
66$ sudo make install<br>
67</code></p>
68
69<p>Now it's finally time to compile and install GNUnet. We have two options:
70installing a *production version* and installing a *development version*. If
71you want to start writing GNUnet applications or join the GNUnet development
72choose the development version (it will print more debug output and contains
73debug symbols that can be displayed with a debugger). Otherwise choose the
74production version.</p>
75
76<h4>{{ _("Option 1: GNUnet for production / usage") }}</h4>
77<p><code>
78 $ cd ~/gnunet_installation/gnunet<br>
79 $ ./bootstrap<br>
80 $ export GNUNET_PREFIX=/usr<br>
81 $ ./configure --prefix=$GNUNET_PREFIX --disable-documentation --with-microhttpd=/opt/libmicrohttpd<br>
82 $ sudo addgroup gnunetdns<br>
83 $ sudo adduser --system --group --disabled-login --home /var/lib/gnunet gnunet<br>
84 $ make -j$(nproc || echo -n 1)<br>
85 $ sudo make install<br>
86</code></p>
87
88<h4>{{ _("Option 2: GNUnet for development") }}</h4>
89<p><code>
90$ cd ~/gnunet_installation/gnunet<br>
91$ ./bootstrap<br>
92$ export GNUNET_PREFIX=/usr<br>
93$ export CFLAGS="-g -Wall -O0"<br>
94$ ./configure --prefix=$GNUNET_PREFIX --disable-documentation --enable-logging=verbose --with-microhttpd=/opt/libmicrohttpd<br>
95$ make -j$(nproc || echo -n 1)<br>
96$ sudo make install<br>
97</p></code>
98
99<h4>{{ _("Install GNUnet plugin for name resolution") }}</h4>
100So 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
101
102<p><code>
103$ sudo cp /usr/lib/gnunet/nss/libnss_gns.so.2 /lib/$(uname -m)-linux-gnu/
104</p></code>
105
106<p>The next step is activating the GNUnet plugin we just copied in the NSS
107config. It is located in `/etc/nsswitch.conf`. It should contain a line
108starting with "hosts" similar to this (at least "files" and "dns" should be
109there):</p>
110
111<p><code>
112$ cat /etc/nsswitch.conf<br>
113hosts: files mdns4_minimal [NOTFOUND=return] dns
114</p></code>
115
116<p><b>Attention: Once we modified `etc/nsswitch.conf` DNS resolution will only
117be possible as long as is GNUnet is running. We can leave the next step out,
118but then we will not be able to use GNUnet's name resolution in external
119applications.</b></p>
120
121<p>We save a copy of the original file and then modify the line using sed:</p>
122
123<p><code>
124$ sudo cp /etc/nsswitch.conf /etc/nsswitch.conf.original<br>
125$ sudo sed -i -E 's/^(hosts:.*) dns/\1 gns [NOTFOUND=return] dns/' /etc/nsswitch.conf
126</p></code>
127
128<p>Now in the line starting with "hosts" should contain an entry "gns [NOTFOUND=return]" before the "dns" entry like this:</p>
129
130<p><code>
131hosts: files mdns4_minimal [NOTFOUND=return] gns [NOTFOUND=return] dns
132</p></code>
133
134<p>That's it. It wasn't that nasty, was it?</p>
135
136<h3>{{ _("Configuration") }}</h3>
137Congratulations! 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:
138
139<p><code>
140$ touch ~/.config/gnunet.conf
141</p></code>
142
143<p>Now we can start it with the command line tool `gnunet-arm` (Automatic Restart Manager).</p>
144
145<p><code>
146$ gnunet-arm -s
147</p></code>
148
149<p>It starts the default GNUnet services. We can list them with the `-I` option:</p>
150
151<p><code>
152$ gnunet-arm -I<br>
153Running services:<br>
154ats (gnunet-service-ats)<br>
155revocation (gnunet-service-revocation)<br>
156set (gnunet-service-set)<br>
157nat (gnunet-service-nat)<br>
158transport (gnunet-service-transport)<br>
159peerstore (gnunet-service-peerstore)<br>
160hostlist (gnunet-daemon-hostlist)<br>
161identity (gnunet-service-identity)<br>
162namecache (gnunet-service-namecache)<br>
163peerinfo (gnunet-service-peerinfo)<br>
164datastore (gnunet-service-datastore)<br>
165zonemaster (gnunet-service-zonemaster)<br>
166zonemaster-monitor (gnunet-service-zonemaster-monitor)<br>
167nse (gnunet-service-nse)<br>
168cadet (gnunet-service-cadet)<br>
169dht (gnunet-service-dht)<br>
170core (gnunet-service-core)<br>
171gns (gnunet-service-gns)<br>
172statistics (gnunet-service-statistics)<br>
173topology (gnunet-daemon-topology)<br>
174fs (gnunet-service-fs)<br>
175namestore (gnunet-service-namestore)<br>
176vpn (gnunet-service-vpn)
177</p></code>
178
179<p>For stopping GNUnet again we can use the `-e` option.</p>
180
181<p><code>
182$ gnunet-arm -e
183</p></code>
184
185<h3>{{ _("Make sure it works") }}</h3>
186
187<p>Let's try some of GNUnet's components: gns, filesharing, CADET and VPN.</p>
188
189<h4>{{ _("GNS") }}</h4>
190
191<p>First let's try out GNS, the GNU name service. We'll publish an IP address
192in a GNS record and try to resolve it using our browser. First we need an
193identity which is the equivalent to a zone in DNS. We'll call it "myself" and
194create it using the `gnunet-identity` command line tool.
195Instead of "myself" you can surely use your nick or any other name. </p>
196
197<p><code>
198$ gnunet-identity -C myself
199</p></code>
200
201<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>
202
203<p><code>
204$ gnunet-identity -d<br>
205myself - HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG
206</p></code>
207
208<p>Now we add a public `A` record to our zone. It has the name "ccc", a value
209of "195.54.164.39" and it never expires.</p>
210<p><code>
211$ gnunet-namestore -z myself -a -e never -p -t A -n ccc -V 195.54.164.39
212</p></code>
213
214<p>Now we can query that record using the command line tool `gnunet-gns`.</p>
215
216<p><code>
217$ gnunet-gns -u ccc.myself<br>
218ccc.myself:<br>
219Got `A' record: 195.54.164.39
220</p></code>
221
222<p>So it worked! Now you can try to type "ccc.myself" into your browser and see
223what website is behind the IP address. (If it doesnt work use the IP directly
224;p)</p>
225
226<h4>{{ _("filesharing") }}</h4>
227
228<p>Let's publish a file in the GNUnet filesharing network. We use tow keywords
229("commons" and "state") so other people will be able to search for the file.
230</p>
231
232<p>We can choose any file and describe it with meaningful keywords (using the
233`-k` command line option).</p>
234
235<p><code>
236$ gnunet-publish -k commons -k state ostrom.pdf<br>
237Publishing `/home/myself/ostrom.pdf' done.<br>
238URI is `gnunet://fs/chk/M57SXDJ72EWS25CT6307KKJ8K0GCNSPTAZ649NA1NS10MJB4A1GZ9EN4Y02KST9VA5BHE8B335RPXQVBWVZ587Y83WQ7J3DHMBX30Q8.DHNGBN4CB2DBX1QRZ1R0B1Q18WTEAK4R94S9D57C9JMJJ3H7SSQDCV4D1218C4S2VP085AMQQSMG18FCP6NQMZQZJ91XR5NBX7YF0V0.42197237'.
239</p></code>
240
241<p>Finding the file by keyword works with `gnunet-search`.</p>
242
243<p><code>
244$ gnunet-search commons<br>
245#1:<br>
246gnunet-download -o "ostrom.pdf" gnunet://fs/chk/M57SXDJ72EWS25CT6307KKJ8K0GCNSPTAZ649NA1NS10MJB4A1GZ9EN4Y02KST9VA5BHE8B335RPXQVBWVZ587Y83WQ7J3DHMBX30Q8.DHNGBN4CB2DBX1QRZ1R0B1Q18WTEAK4R94S9D57C9JMJJ3H7SSQDCV4D1218C4S2VP085AMQQSMG18FCP6NQMZQZJ91XR5NBX7YF0V0.42197237
247</p></code>
248
249<p>It gives us the command line call to download the file (and store it as
250ostrom.pdf)!</p>
251
252
253<h4>{{ _("CADET (and Chat)") }}</h4>
254
255<p>We can use the `gnunet-cadet` command line tool to open a port and from
256another machine connect to this port and chat or transfer data. First we need
257our *peer ID* of the GNUnet peer opening the port.</p>
258
259<p><code>
260$ gnunet-peerinfo -s<br>
261I am peer `P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG'.
262</p></code>
263
264<p>Now we open the port (it can be any string!):</p>
265
266<p><code>
267$ gnunet-cadet -o my-secret-port
268</p></code>
269
270<p>On the other machine we can connect using the peer ID and the port and start chatting!</p>
271
272<p><code>
273$ gnunet-cadet P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG my-secret-port
274</p></code>
275
276<h4>{{ _("VPN") }}</h4>
277
278<p>TBD</p>
279
280<h3>{{ _("Uninstall GNUnet and its dependencies") }}</h3>
281
282<p><code>
283$ cd ~/gnunet_installation/gnunet<br>
284$ sudo make uninstall<br>
285$ cd ~/gnunet_installation/libmicrohttpd<br>
286$ sudo make uninstall<br>
287$ 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>
288$ sudo apt autoremove<br>
289$ sudo userdel -r gnunet<br>
290$ sudo groupdel gnunet<br>
291$ sudo groupdel gnunetdns<br>
292$ sudo mv /etc/nsswitch.conf.original /etc/nsswitch.conf<br>
293$ sudo rm /lib/$(uname -m)-linux-gnu/libnss_gns.so.2<br>
294</p></code>
295
296
297<h3>{{ _("Appendix A: Optional GNUnet features") }}</h3>
298
299<p>TBD</p>
300
301<h3>{{ _("Troubleshooting") }}</h3>
302
303<h4>{{ _("You can't reach other people's nodes") }}</h4>
304
305<p>Should our computer not have reached the open GNUnet network automatically,
306we can manually instruct our node how to reach the nodes of our friends. This
307works by exchanging HELLO strings. This is how we get a hello string for our
308computer.</p>
309
310<p><code>
311$ gnunet-peerinfo -gn
312</p></code>
313
314<p>We can now pass this string to our friends "out of band" (using whatever
315existing chat or messaging technology). If the string contains some private IP
316networks we don't want to share, we can carefully edit them out.</p>
317
318<p>Once we receive such strings from our friends, we can add them like
319this:</p>
320
321<p><code>
322gnunet-peerinfo -p <string>
323 </p></code>
324
325<p>Now our GNUnet nodes can attempt reaching each other directly. This may
326still fail due to NAT traversal issues.</p>
327
328<h4>{{ _("OMG you guys broke my internet") }}</h4>
329
330<p>We can replace `/etc/nsswitch.conf` with the backup we made earlier
331(`/etc/nsswitch.conf.original`). Now DNS resolution should work again without a
332running GNUnet.</p>
333
334<p><code>
335$ cp /etc/nsswitch.conf.original /etc/nsswitch.conf
336</p></code>
337
338</div>
339{% endblock body_content %}
diff --git a/tutorial.html.j2 b/tutorial.html.j2
new file mode 100644
index 00000000..5501af00
--- /dev/null
+++ b/tutorial.html.j2
@@ -0,0 +1,26 @@
1{% extends "common/base.j2" %}
2{% block body_content %}
3<div class="container">
4
5<h2>{{ _("Tutorial") }}</h2>
6
7
8<div class="container-fluid adorn_h3_bracket c_acronym">
9 <div class="container">
10 <div class="row">
11 <div class="col-lg-3">
12 <a href="">GNUnet on Ubuntu</a>
13 </div>
14 <div class="col-lg-3">
15 <a href="tutorial-archpi.html">GNUnet on Arch-Pi</a>
16 </div>
17 <div class="col-lg-3">
18 <a href="tutorial-debian9.html">GNUnet on Debian</a>
19 </div>
20 </div>
21 </div>
22</div>
23
24
25</div>
26{% endblock body_content %}