f2042033e336e9482f4131e2d564c3f15ad19875
[oweals/gnunet.git] / doc / documentation / chapters / installation.texi
1 @node GNUnet Installation Handbook
2 @chapter GNUnet Installation Handbook
3
4 This handbook describes how to install (build, setup, compile) and
5 setup (configure, start) GNUnet @value{VERSION}. After following these
6 instructions you should be able to install and then start user-interfaces
7 to interact with the network.
8
9 Note: This manual is far from complete, and we welcome contributions, be
10 it in the form of new chapters or insightful comments.
11
12 @menu
13 * Dependencies::
14 * Pre-installation notes::
15 * Generic installation instructions::
16 * Build instructions for Ubuntu 12.04 using Git::
17 * Build instructions for software builds from source::
18 * Build Instructions for Microsoft Windows Platforms::
19 * Build instructions for Debian 7.5::
20 * Installing GNUnet from Git on Ubuntu 14.4::
21 * Build instructions for Debian 8::
22 @c * Build instructions for OpenBSD 6.2::
23 * Outdated build instructions for previous revisions::
24 @c * Portable GNUnet::
25 * The graphical configuration interface::
26 * How to start and stop a GNUnet peer::
27 @end menu
28
29 @node Dependencies
30 @section Dependencies
31 @c %**end of header
32
33 This section lists the various known dependencies for
34 GNUnet @value{EDITION}.
35 Suggestions for missing dependencies or wrong version numbers are welcome.
36
37 @menu
38 * External dependencies::
39 * Optional dependencies::
40 * Internal dependencies::
41 @end menu
42
43 @node External dependencies
44 @subsection External dependencies
45 @c %**end of header
46
47 These packages must be installed before a typical GNUnet installation
48 can be performed:
49
50 @itemize @bullet
51 @item autoconf
52 @item automake
53 @item pkg-config
54 @item libltdl
55 @item gstreamer
56 @item gst-plugins-base
57 @item perl
58 @item python (only 2.7 supported)@footnote{tests and gnunet-qr}
59 @item jansson
60 @item nss
61 @item glib
62 @item gmp
63 @item bluez
64 @item miniupnpc
65 @item gettext
66 @item which
67 @item texinfo @geq{} 5.2
68 @item GNU libmicrohttpd @geq{} 0.9.30 @footnote{We recommend to build it
69 with a GnuTLS version that was configured with libunbound}
70 @item GNU libextractor @geq{} 1.0
71 @item GNU libtool @geq{} 2.2
72 @item GNU libunistring @geq{} 0.9.1.1
73 @item GNU libidn @geq{} 1.0.0
74 @item @uref{https://gnupg.org/software/libgcrypt/, GNU libgcrypt} @geq{}
75 @uref{https://gnupg.org/ftp/gcrypt/libgcrypt/, 1.6.0}
76 @item @uref{https://gnutls.org/, GnuTLS} @geq{} 3.2.7
77 @footnote{We recommend to compile with libunbound for DANE support;
78 GnuTLS also requires GNU nettle 2.7 (update: GnuTLS 3.2.7 appears NOT
79 to work against GNU nettle > 2.7, due to some API updatings done by
80 nettle. Thus it should be compiled against nettle 2.7
81 and, in case you get some error on the reference to `rpl_strerror' being
82 undefined, follow the instructions on
83 @uref{http://lists.gnupg.org/pipermail/gnutls-devel/2013-November/006588.html, this}
84 post (and the link inside it)).}
85 @item @uref{https://gnunet.org/gnurl, gnURL} libgnurl @geq{} 7.34.0
86 @footnote{must be compiled after @code{GnuTLS}}
87 @item libglpk @geq{} 4.45
88 @item @uref{http://www.openssl.org/, OpenSSL} @geq{} 1.0
89 @item TeX Live @geq{} 2012, optional (for gnunet-bcd)
90 @item Texinfo @geq{} 5.2 (for documentation)
91 @item libsqlite @geq{} 3.8.0 @footnote{(note that the code will
92 compile and often work with lower version numbers, but you may get subtle
93 bugs with respect to quota management in certain rare cases);
94 alternatively, MySQL or Postgres can also be installed, but those
95 databases will require more complex configurations (not
96 recommended for first-time users)}
97 @item zlib
98 @end itemize
99
100 @node Optional dependencies
101 @subsection Optional dependencies
102
103 These applications must be installed for various experimental or otherwise
104 optional features such as @command{gnunet-conversation},
105 and @command{gnunet-conversation-gtk} (most of these features are only build if you
106 configure GNUnet with @command{--enable-experimental}):
107
108 @itemize @bullet
109 @item libpulse @geq{} 2.0,
110 optional (for @command{gnunet-conversation})
111 @item libopus @geq{} 1.0.1,
112 optional (for @command{gnunet-conversation})
113 @item libogg @geq{} 1.3.0,
114 optional (for @command{gnunet-conversation})
115 @item libnss contained @command{certool} binary,
116 optional for convenient installation of
117 the GNS proxy.
118 @item python-zbar @geq{} 0.10,
119 optional (for @command{gnunet-qr})
120 @item Gtk+ @geq{} 3.0,
121 optional (for @command{gnunet-gtk})
122 @item libgladeui (must match Gtk+ version),
123 optional (for @command{gnunet-gtk})
124 @item libqrencode @geq{} 3.0,
125 optional (for @command{gnunet-namestore-gtk})
126 @item libpbc @geq{} 0.5.14, optional for Attribute-Based Encryption and Identity Provider functionality
127 @item libgabe (https://github.com/schanzen/libgabe), optional for Attribute-Based Encryption and Identity Provider functionality
128 @end itemize
129
130 @node Internal dependencies
131 @subsection Internal dependencies
132
133 This section tries to give an overview of what processes a typical GNUnet
134 peer running a particular application would consist of. All of the
135 processes listed here should be automatically started by
136 @command{gnunet-arm -s}.
137 The list is given as a rough first guide to users for failure diagnostics.
138 Ideally, end-users should never have to worry about these internal
139 dependencies.
140
141 In terms of internal dependencies, a minimum file-sharing system consists
142 of the following GNUnet processes (in order of dependency):
143
144 @itemize @bullet
145 @item gnunet-service-arm
146 @item gnunet-service-resolver (required by all)
147 @item gnunet-service-statistics (required by all)
148 @item gnunet-service-peerinfo
149 @item gnunet-service-transport (requires peerinfo)
150 @item gnunet-service-core (requires transport)
151 @item gnunet-daemon-hostlist (requires core)
152 @item gnunet-daemon-topology (requires hostlist, peerinfo)
153 @item gnunet-service-datastore
154 @item gnunet-service-dht (requires core)
155 @item gnunet-service-identity
156 @item gnunet-service-fs (requires identity, mesh, dht, datastore, core)
157 @end itemize
158
159 @noindent
160 A minimum VPN system consists of the following GNUnet processes (in
161 order of dependency):
162
163 @itemize @bullet
164 @item gnunet-service-arm
165 @item gnunet-service-resolver (required by all)
166 @item gnunet-service-statistics (required by all)
167 @item gnunet-service-peerinfo
168 @item gnunet-service-transport (requires peerinfo)
169 @item gnunet-service-core (requires transport)
170 @item gnunet-daemon-hostlist (requires core)
171 @item gnunet-service-dht (requires core)
172 @item gnunet-service-mesh (requires dht, core)
173 @item gnunet-service-dns (requires dht)
174 @item gnunet-service-regex (requires dht)
175 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
176 @end itemize
177
178 @noindent
179 A minimum GNS system consists of the following GNUnet processes (in
180 order of dependency):
181
182 @itemize @bullet
183 @item gnunet-service-arm
184 @item gnunet-service-resolver (required by all)
185 @item gnunet-service-statistics (required by all)
186 @item gnunet-service-peerinfo
187 @item gnunet-service-transport (requires peerinfo)
188 @item gnunet-service-core (requires transport)
189 @item gnunet-daemon-hostlist (requires core)
190 @item gnunet-service-dht (requires core)
191 @item gnunet-service-mesh (requires dht, core)
192 @item gnunet-service-dns (requires dht)
193 @item gnunet-service-regex (requires dht)
194 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
195 @item gnunet-service-identity
196 @item gnunet-service-namestore (requires identity)
197 @item gnunet-service-gns (requires vpn, dns, dht, namestore, identity)
198 @end itemize
199
200 @node Pre-installation notes
201 @section Pre-installation notes
202
203 Please note that in the code instructions for the installation,
204 @emph{#} indicates commands run as privileged root user and
205 @emph{$} shows commands run as unprivileged ("normal") system user.
206
207
208 @node Generic installation instructions
209 @section Generic installation instructions
210
211 First, in addition to the GNUnet sources you might require downloading the
212 latest version of various dependencies, depending on how recent the
213 software versions in your distribution of GNU/Linux are.
214 Most distributions do not include sufficiently recent versions of these
215 dependencies.
216 Thus, a typically installation on a "modern" GNU/Linux distribution
217 requires you to install the following dependencies (ideally in this
218 order):
219
220 @itemize @bullet
221 @item libgpgerror and libgcrypt
222 @item libnettle and libunbound (possibly from distribution), GnuTLS
223 @item libgnurl (read the README)
224 @item GNU libmicrohttpd
225 @item GNU libextractor
226 @end itemize
227
228 Make sure to first install the various mandatory and optional
229 dependencies including development headers from your distribution.
230
231 Other dependencies that you should strongly consider to install is a
232 database (MySQL, sqlite or Postgres).
233 The following instructions will assume that you installed at least sqlite.
234 For most distributions you should be able to find pre-build packages for
235 the database. Again, make sure to install the client libraries @b{and} the
236 respective development headers (if they are packaged separately) as well.
237
238 You can find specific, detailed instructions for installing of the
239 dependencies (and possibly the rest of the GNUnet installation) in the
240 platform-specific descriptions, which can be found in the Index.
241 Please consult them now.
242 If your distribution is not listed, please study
243 @ref{Build instructions for Debian 8}, the build instructions for
244 Debian stable, carefully as you try to install the dependencies for your
245 own distribution.
246 Contributing additional instructions for further platforms is always
247 appreciated.
248 Please take in mind that operating system development tends to move at
249 a rather fast speed. Due to this you should be aware that some of
250 the instructions could be outdated by the time you are reading this.
251 If you find a mistake, please tell us about it (or even better: send
252 a patch to the documentation to fix it!).
253
254 Before proceeding further, please double-check the dependency list.
255 Note that in addition to satisfying the dependencies, you might have to
256 make sure that development headers for the various libraries are also
257 installed.
258 There maybe files for other distributions, or you might be able to find
259 equivalent packages for your distribution.
260
261 While it is possible to build and install GNUnet without having root
262 access, we will assume that you have full control over your system in
263 these instructions.
264 First, you should create a system user @emph{gnunet} and an additional
265 group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu,
266 type:
267
268 @example
269 # adduser --system --home /var/lib/gnunet --group \
270 --disabled-password gnunet
271 # addgroup --system gnunetdns
272 @end example
273
274 @noindent
275 On other Unixes and GNU systems, this should have the same effect:
276
277 @example
278 # useradd --system --groups gnunet --home-dir /var/lib/gnunet
279 # addgroup --system gnunetdns
280 @end example
281
282 Now compile and install GNUnet using:
283
284 @example
285 $ tar xvf gnunet-@value{VERSION}.tar.gz
286 $ cd gnunet-@value{VERSION}
287 $ ./configure --with-sudo=sudo --with-nssdir=/lib
288 $ make
289 $ sudo make install
290 @end example
291
292 If you want to be able to enable DEBUG-level log messages, add
293 @code{--enable-logging=verbose} to the end of the
294 @command{./configure} command.
295 @code{DEBUG}-level log messages are in English only and
296 should only be useful for developers (or for filing
297 really detailed bug reports).
298
299 Finally, you probably want to compile @command{gnunet-gtk}, which
300 includes @command{gnunet-setup} (a graphical tool for
301 GNUnet configuration) and @command{gnunet-fs-gtk} (a graphical tool for
302 GNUnet file-sharing):
303
304 @example
305 $ tar xvf gnunet-gtk-@value{VERSION}.tar.gz
306 $ cd gnunet-gtk-@value{VERSION}
307 $ ./configure --with-gnunet=/usr/local/
308 $ make
309 $ sudo make install
310 $ cd ..
311 # just to be safe run this:
312 $ sudo ldconfig
313 @end example
314
315 @noindent
316 Next, edit the file @file{/etc/gnunet.conf} to contain the following:
317
318 @example
319 [arm]
320 SYSTEM_ONLY = YES
321 USER_ONLY = NO
322 @end example
323
324 @noindent
325 You may need to update your @code{ld.so} cache to include
326 files installed in @file{/usr/local/lib}:
327
328 @example
329 # ldconfig
330 @end example
331
332 @noindent
333 Then, switch from user @code{root} to user @code{gnunet} to start
334 the peer:
335
336 @example
337 # su -s /bin/sh - gnunet
338 $ gnunet-arm -c /etc/gnunet.conf -s
339 @end example
340
341 You may also want to add the last line in the gnunet user's @file{crontab}
342 prefixed with @code{@@reboot} so that it is executed whenever the system
343 is booted:
344
345 @example
346 @@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s
347 @end example
348
349 @noindent
350 This will only start the system-wide GNUnet services.
351 Type exit to get back your root shell.
352 Now, you need to configure the per-user part. For each
353 $USER that should get access to GNUnet on the system, run:
354
355 @example
356 # adduser $USER gnunet
357 @end example
358
359 @noindent
360 to allow them to access the system-wide GNUnet services. Then, each
361 user should create a configuration file @file{~/.config/gnunet.conf}
362 with the lines:
363
364 @example
365 [arm]
366 SYSTEM_ONLY = NO
367 USER_ONLY = YES
368 DEFAULTSERVICES = gns
369 @end example
370
371 @noindent
372 and start the per-user services using
373
374 @example
375 $ gnunet-arm -c ~/.config/gnunet.conf -s
376 @end example
377
378 @noindent
379 Again, adding a @code{crontab} entry to autostart the peer is advised:
380
381 @example
382 @@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s
383 @end example
384
385 @noindent
386 Note that some GNUnet services (such as SOCKS5 proxies) may need a
387 system-wide TCP port for each user.
388 For those services, systems with more than one user may require each user
389 to specify a different port number in their personal configuration file.
390
391 Finally, the user should perform the basic initial setup for the GNU Name
392 System (GNS) certificate authority. This is done by running:
393
394 @example
395 $ gnunet-gns-proxy-setup-ca
396 @end example
397
398 @noindent
399 The first generates the default zones, wheras the second setups the GNS
400 Certificate Authority with the user's browser. Now, to activate GNS in the
401 normal DNS resolution process, you need to edit your
402 @file{/etc/nsswitch.conf} where you should find a line like this:
403
404 @example
405 hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
406 @end example
407
408 @noindent
409 The exact details may differ a bit, which is fine. Add the text
410 @emph{"gns [NOTFOUND=return]"} after @emph{"files"}.
411 Keep in mind that we included a backslash ("\") here just for
412 markup reasons. You should write the text below on @b{one line}
413 and @b{without} the "\":
414
415 @example
416 hosts: files gns [NOTFOUND=return] mdns4_minimal \
417 [NOTFOUND=return] dns mdns4
418 @end example
419
420 @c FIXME: Document new behavior.
421 You might want to make sure that @file{/lib/libnss_gns.so.2} exists on
422 your system, it should have been created during the installation.
423
424 @node Build instructions for Ubuntu 12.04 using Git
425 @section Build instructions for Ubuntu 12.04 using Git
426
427 @menu
428 * Install the required build tools::
429 * Install libgcrypt 1.6 and libgpg-error::
430 * Install gnutls with DANE support::
431 * Install libgnurl::
432 * Install libmicrohttpd from Git::
433 * Install libextractor from Git::
434 * Install GNUnet dependencies::
435 * Build GNUnet::
436 * Install the GNUnet-gtk user interface from Git::
437 @end menu
438
439 @node  Install the required build tools
440 @subsection  Install the required build tools
441
442 First, make sure Git is installed on your system:
443
444 @example
445 $ sudo apt-get install git
446 @end example
447
448 Install the essential buildtools:
449
450 @example
451 $ sudo apt-get install automake autopoint autoconf libtool
452 @end example
453
454 @node Install libgcrypt 1.6 and libgpg-error
455 @subsection Install libgcrypt 1.6 and libgpg-error
456
457 @ref{generic source installation - libgpg-error}
458
459 @node Install gnutls with DANE support
460 @subsection Install gnutls with DANE support
461
462 @itemize @bullet
463 @item @ref{generic source installation - nettle}
464 @item @ref{generic source installation - ldns}
465 @item @ref{generic source installation - libunbound/unbound}
466 @item @ref{generic source installation - gnutls}
467 @item @ref{generic source installation - libgcrypt}
468 @end itemize
469
470 @node Install libgnurl
471 @subsection Install libgnurl
472
473 Follow the @ref{generic source installation - libgnurl}.
474
475 @node Install libmicrohttpd from Git
476 @subsection Install libmicrohttpd from Git
477
478 @example
479 $ git clone https://gnunet.org/git/libmicrohttpd
480 $ cd libmicrohttpd/
481 $ ./bootstrap
482 $ ./configure
483 $ sudo make install ; cd ..
484 @end example
485
486 @node  Install libextractor from Git
487 @subsection  Install libextractor from Git
488
489 Install libextractor dependencies:
490
491 @example
492 $ sudo apt-get install zlib1g-dev libgsf-1-dev libmpeg2-4-dev \
493  libpoppler-dev libvorbis-dev libexiv2-dev libjpeg-dev \
494  libtiff-dev libgif-dev libvorbis-dev libflac-dev libsmf-dev \
495  g++
496 @end example
497
498 Build libextractor:
499
500 @example
501 $ git clone https://gnunet.org/git/libextractor
502 $ cd libextractor
503 $ ./bootstrap
504 $ ./configure
505 $ sudo make install ; cd ..
506 @end example
507
508 @node Install GNUnet dependencies
509 @subsection Install GNUnet dependencies
510
511 @example
512 $ sudo apt-get install libidn11-dev libunistring-dev libglpk-dev \
513  libpulse-dev libbluetooth-dev libsqlite-dev
514 @end example
515
516 Install libopus:
517
518 @example
519 $ wget http://downloads.xiph.org/releases/opus/opus-1.1.tar.gz
520 $ tar xf opus-1.1.tar.gz
521 $ cd opus-1.1/
522 $ ./configure
523 $ sudo make install ; cd ..
524 @end example
525
526 Choose one or more database backends:
527
528 SQLite3:
529 @example
530 $ sudo apt-get install libsqlite3-dev
531 @end example
532 MySQL:
533 @example
534 $ sudo apt-get install libmysqlclient-dev
535 @end example
536 PostgreSQL:
537 @example
538 $ sudo apt-get install libpq-dev postgresql
539 @end example
540
541
542
543 @node Build GNUnet
544 @subsection Build GNUnet
545
546
547
548 @menu
549 * Configuring the installation path::
550 * Configuring the system::
551 * Installing components requiring sudo permission::
552 * Build::
553 @end menu
554
555 @node Configuring the installation path
556 @subsubsection Configuring the installation path
557
558 You can specify the location of the GNUnet installation by setting the
559 prefix when calling the configure script with @code{--prefix=DIRECTORY}
560
561 @example
562 $ export PATH=$PATH:DIRECTORY/bin
563 @end example
564
565 @node Configuring the system
566 @subsubsection Configuring the system
567
568 Please make sure NOW that you have created a user and group 'gnunet'
569 and additionally a group 'gnunetdns':
570
571 @example
572 $ sudo addgroup gnunet
573 $ sudo addgroup gnunetdns
574 $ sudo adduser gnunet
575 @end example
576
577 Each GNUnet user should be added to the 'gnunet' group (may
578 require fresh login to come into effect):
579
580 @example
581 $ sudo useradd -G  gnunet
582 @end example
583
584 @node Installing components requiring sudo permission
585 @subsubsection Installing components requiring sudo permission
586
587 Some components, like the nss plugin required for GNS, may require root
588 permissions. To allow these few components to be installed use:
589
590 @example
591 $ ./configure --with-sudo
592 @end example
593
594 @node Build
595 @subsubsection Build
596
597 @example
598 $ git clone https://gnunet.org/git/gnunet/
599 $ cd gnunet/
600 $ ./bootstrap
601 @end example
602
603 Use the required configure call including the optional installation prefix
604 @code{PREFIX} or the sudo permissions:
605
606 @example
607 $ ./configure [ --with-sudo | --with-prefix=PREFIX ]
608 @end example
609
610 @example
611 $ make; sudo make install
612 @end example
613
614 After installing it, you need to create an empty configuration file:
615
616 @example
617 mkdir ~/.gnunet; touch ~/.gnunet/gnunet.conf
618 @end example
619
620 And finally you can start GNUnet with:
621
622 @example
623 $ gnunet-arm -s
624 @end example
625
626 @node Install the GNUnet-gtk user interface from Git
627 @subsection Install the GNUnet-gtk user interface from Git
628
629
630 Install depencies:
631
632 @example
633 $ sudo apt-get install libgtk-3-dev libunique-3.0-dev libgladeui-dev \
634  libqrencode-dev
635 @end example
636
637 Build GNUnet (with an optional prefix) and execute:
638
639 @example
640 $ git clone https://gnunet.org/git/gnunet-gtk/
641 $ cd gnunet-gtk/
642 $ ./bootstrap
643 $ ./configure [--prefix=PREFIX] --with-gnunet=DIRECTORY
644 $ make; sudo make install
645 @end example
646
647 @node Build instructions for software builds from source
648 @section Build instructions for software builds from source
649
650 This section describes software builds in case your operating
651 system lacks binary substitutes / binary builds for some dependencies
652 of GNUnet.
653 It is assumed that you have installed common build dependencies
654 and that these instructions are treated as generic without any
655 debugging help.
656 It is furthermore assumed that you use the release tarballs of
657 the software, installation from the respective version control
658 sources might differ in ways that are only minimal different
659 (for example a dependency on autotools etc).
660
661 @menu
662 * generic source installation - nettle::
663 * generic source installation - ldns::
664 * generic source installation - libunbound/unbound::
665 * generic source installation - libav::
666 * generic source installation - libextractor::
667 * generic source installation - libgpg-error::
668 * generic source installation - libgcrypt::
669 * generic source installation - gnutls::
670 * generic source installation - libmicrohttpd::
671 * generic source installation - libgnurl::
672 @end menu
673
674 @node generic source installation - nettle
675 @subsection generic source installation - nettle
676
677 @example
678 $ wget http://www.lysator.liu.se/~nisse/archive/nettle-2.7.1.tar.gz
679 $ tar xf nettle-2.7.1.tar.gz
680 $ cd nettle-2.7.1
681 $ ./configure
682 $ sudo make install ; cd ..
683 @end example
684
685 @node generic source installation - ldns
686 @subsection generic source installation - ldns
687
688 @example
689 $ wget https://www.nlnetlabs.nl/downloads/ldns/ldns-1.6.16.tar.gz
690 $ tar xf ldns-1.6.16.tar.gz
691 $ cd ldns-1.6.16
692 $ ./configure
693 $ sudo make install ; cd ..
694 @end example
695
696 @node generic source installation - libunbound/unbound
697 @subsection generic source installation - libunbound/unbound
698
699 @example
700 $ wget https://unbound.net/downloads/unbound-1.4.21.tar.gz
701 $ tar xf unbound-1.4.21.tar.gz
702 $ cd unbound-1.4.21
703 $ ./configure
704 $ sudo make install ; cd ..
705 @end example
706
707 @node generic source installation - libav
708 @subsection generic source installation - libav
709
710 @example
711 $ wget https://libav.org/releases/libav-9.10.tar.xz
712 $ cd libav-0.9 ; ./configure --enable-shared;
713 $ make; sudo make install; cd ..
714 @end example
715
716 @node generic source installation - libextractor
717 @subsection generic source installation - libextractor
718
719 @example
720 $ wget https://ftp.gnu.org/gnu/libextractor/libextractor-1.3.tar.gz
721 $ tar xvf libextractor-1.3.tar.gz
722 $ cd libextractor-1.3 ; ./configure;
723 $ make ; sudo make install; cd ..
724 @end example
725
726 @node generic source installation - libgpg-error
727 @subsection generic source installation - libgpg-error
728
729 @example
730 $ wget https://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
731 $ tar xvf libgpg-error-1.12.tar.bz2
732 $ cd libgpg-error-1.12; ./configure;
733 $ make ; sudo make install; cd ..
734 @end example
735
736 @node generic source installation - libgcrypt
737 @subsection generic source installation - libgcrypt
738 @example
739 $ wget https://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
740 $ tar xvf libgcrypt-1.6.0.tar.bz2
741 $ cd libgcrypt-1.6.0; ./configure --with-gpg-error-prefix=/usr/local;
742 $ make ; sudo make install ; cd ..
743 @end example
744
745 @node generic source installation - gnutls
746 @subsection generic source installation - gnutls
747
748 @example
749 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.2/gnutls-3.2.7.tar.xz
750 $ tar xvf gnutls-3.2.7.tar.xz
751 $ cd gnutls-3.2.7
752 @end example
753
754 @noindent
755 If you want a GnuTLS with DANE functionality (recommended for GNUnet),
756 you have to compile it against libunbound. Assuming that libunbound
757 is installed on your system:
758
759 @example
760 $ ./configure --enable-libdane
761 @end example
762
763 @noindent
764 Note that the build system of GnuTLS should pick up libunbound without
765 the explicit mention of @code{--enable-libdane}.
766 If you don't want libdane support you should pass @code{--disable-libdane}
767 instead.
768
769 @example
770 $ ./configure
771 $ make ; sudo make install ; cd ..
772 @end example
773
774 @node generic source installation - libmicrohttpd
775 @subsection generic source installation - libmicrohttpd
776
777 @example
778 $ wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.33.tar.gz
779 $ tar xvf libmicrohttpd-0.9.33.tar.gz
780 $ cd libmicrohttpd-0.9.33; ./configure;
781 $ make ; sudo make install ; cd ..
782 @end example
783
784 @node generic source installation - libgnurl
785 @subsection generic source installation - libgnurl
786
787 Example installation of libgnurl version 7.57.0 from source.
788
789 @example
790 $ wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.57.0.tar.xz
791 $ wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.57.0.tar.xz.sig
792 $ gpg --verify gnurl-7.57.0.tar.xz.sig
793 @end example
794
795 @noindent
796 If that command fails because you do not have the required public key,
797 then run this command to import it:
798
799 @example
800 $ gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588
801 @end example
802
803 @noindent
804 and rerun the gpg --verify command.
805
806 @example
807 $ tar xvf gnurl-7.57.0.tar.xz
808 $ cd gnurl-7.57.0
809 $ ./configure --disable-ntlm-wb
810 $ make ; sudo make install; cd ..
811 @end example
812
813 You have now build and installed libgnurl from source.
814
815 @menu
816 * Fixing libgnurl build issues::
817 @end menu
818
819 @node Fixing libgnurl build issues
820 @subsubsection Fixing libgnurl build issues
821
822 @c FIXME: Obviously this subsection should be evaluated and
823 @c if still necessary moved into gnURL itself (README) or
824 @c into a separate section which deals with gnURL.
825 If you have to compile libgnurl from source (for example if the version
826 included in your distribution is too old or it's not included at all)
827 you perhaps might get an error message while running the
828 @command{configure} script:
829
830 @example
831 $ configure
832 ...
833 checking for 64-bit curl_off_t data type... unknown
834 checking for 32-bit curl_off_t data type... unknown
835 checking for 16-bit curl_off_t data type... unknown
836 configure: error: cannot find data type for curl_off_t.
837 @end example
838
839 @noindent
840 Solution:
841
842 Before running the @command{configure} script, set:
843
844 @example
845 CFLAGS="-I. -I$BUILD_ROOT/include"
846 @end example
847
848 @node Build Instructions for Microsoft Windows Platforms
849 @section Build Instructions for Microsoft Windows Platforms
850
851 @menu
852 * Introduction to building on MS Windows::
853 * Requirements::
854 * Dependencies & Initial Setup::
855 * GNUnet Installation::
856 * Adjusting Windows for running and testing GNUnet::
857 * Building the GNUnet Installer::
858 * Using GNUnet with Netbeans on Windows::
859 @end menu
860
861 @node Introduction to building on MS Windows
862 @subsection Introduction to building on MS Windows
863
864
865 This document is a guide to building GNUnet and its dependencies on
866 Windows platforms. GNUnet development is mostly done under GNU/Linux and
867 especially git checkouts may not build out of the box.
868 We regret any inconvenience, and if you have problems, please report
869 them.
870
871 @node Requirements
872 @subsection Requirements
873
874 The Howto is based upon a @strong{Windows Server 2008 32bit}
875 @strong{Installation}, @strong{sbuild} and thus a
876 @uref{http://www.mingw.org/wiki/MSYS, MSYS+MinGW}
877 (W32-GCC-Compiler-Suite + Unix-like Userland) installation. sbuild
878 is a convenient set of scripts which creates a working msys/mingw
879 installation and installs most dependencies required for GNUnet.
880
881 As of the point of the creation of these instructions,
882 GNUnet @strong{requires} a Windows @strong{Server} 2003 or
883 newer for full feature support.
884 Windows Vista and later will also work, but
885 @strong{non-server version can not run a VPN-Exit-Node} as the NAT
886 features have been removed as of Windows Vista.
887
888 @c TODO: We should document Windows 10!
889 @c It seems like the situation hasn't changed with W10
890
891 @node Dependencies & Initial Setup
892 @subsection Dependencies & Initial Setup
893
894
895 @itemize @bullet
896
897 @item
898 Install a fresh version of @strong{Python 2.x}, even if you are using a
899 x64-OS, install a 32-bit version for use with sbuild.
900 Python 3.0 is currently incompatible.
901
902 @item
903 Install your favorite @uref{http://code.google.com/p/tortoisegit/, git} &
904 @uref{http://tortoisesvn.net/, subversion}-clients.
905
906 @item
907 You will also need some archive-manager like
908 @uref{http://www.7-zip.org/, 7zip}.
909
910 @item
911 Pull a copy of sbuild to a directory of your choice, which will be used
912 in the remainder of this guide. For now, we will use
913 @file{c:\gnunet\sbuild\}
914
915 @item
916 in @file{sbuild\src\mingw\mingw32-buildall.sh}, comment out the packages
917 @strong{gnunet-svn} and @strong{gnunet-gtk-svn}, as we don't want sbuild
918 to compile/install those for us.
919
920 @item
921 Follow LRN's sbuild installation instructions.-
922 @end itemize
923
924 Please note that sbuild may (or will most likely) fail during
925 installation, thus you really HAVE to @strong{check the logfiles} created
926 during the installation process.
927 Certain packages may fail to build initially due to missing dependencies,
928 thus you may have to
929 @strong{substitute those with binary-versions initially}. Later on once
930 dependencies are satisfied you can re-build the newer package versions.
931
932 @strong{It is normal that you may have to repeat this step multiple times
933 and there is no uniform way to fix all compile-time issues, as the
934 build-process of many of the dependencies installed are rather unstable
935 on win32 and certain releases may not even compile at all.}
936
937 Most dependencies for GNUnet have been set up by sbuild, thus we now
938 should add the @file{bin/} directories in your new msys and mingw
939 installations to PATH. You will want to create a backup of your finished
940 msys-environment by now.
941
942 @node GNUnet Installation
943 @subsection GNUnet Installation
944
945 First, we need to launch our msys-shell, you can do this via
946
947 @file{C:\gnunet\sbuild\msys\msys.bat}
948
949 You might wish to take a look at this file and adjust some
950 login-parameters to your msys environment.
951
952 Also, sbuild added two pointpoints to your msys-environment, though those
953 might remain invisible:
954
955 @itemize @bullet
956
957 @item
958 /mingw, which will mount your mingw-directory from sbuild/mingw and the
959 other one is
960
961 @item
962 /src which contains all the installation sources sbuild just compiled.
963 @end itemize
964
965 Check out the current GNUnet sources (git HEAD) from the
966 GNUnet repository "gnunet.git", we will do this in your home directory:
967
968 @code{git clone https://gnunet.org/git/gnunet/ ~/gnunet}
969
970 Now, we will first need to bootstrap the checked out installation and then
971 configure it accordingly.
972
973 @example
974 cd ~/gnunet
975 ./bootstrap
976 STRIP=true CPPFLAGS="-DUSE_IPV6=1 -DW32_VEH" CFLAGS="$CFLAGS -g -O2" \
977 ./configure --prefix=/ --docdir=/share/doc/gnunet \
978 --with-libiconv-prefix=/mingw --with-libintl-prefix=/mingw \
979 --with-libcurl=/mingw --with-extractor=/mingw --with-sqlite=/mingw \
980 --with-microhttpd=/mingw --with-plibc=/mingw --enable-benchmarks \
981 --enable-expensivetests --enable-experimental --with-qrencode=/mingw \
982 --enable-silent-rules --enable-experimental 2>&1 | tee -a ./configure.log
983 @end example
984
985 The parameters above will configure for a reasonable GNUnet installation
986 to the your msys-root directory.
987 Depending on which features your would like to build or you may need to
988 specify additional dependencies. Sbuild installed most libs into
989 the /mingw subdirectory, so remember to prefix library locations with
990 this path.
991
992 Like on a unixoid system, you might want to use your home directory as
993 prefix for your own GNUnet installation for development, without tainting
994 the buildenvironment. Just change the "prefix" parameter to point towards
995 ~/ in this case.
996
997 Now it's time to compile GNUnet as usual. Though this will take some time,
998 so you may fetch yourself a coffee or some Mate now...
999
1000 @example
1001 make ; make install
1002 @end example
1003
1004 @node Adjusting Windows for running and testing GNUnet
1005 @subsection Adjusting Windows for running and testing GNUnet
1006
1007 Assuming the build succeeded and you
1008 @strong{added the bin directory of your GNUnet to PATH}, you can now use
1009 your gnunet-installation as usual.
1010 Remember that UAC or the windows firewall may popup initially, blocking
1011 further execution of gnunet until you acknowledge them.
1012
1013 You will also have to take the usual steps to get peer-to-peer (p2p)
1014 software running properly (port forwarding, ...),
1015 and GNUnet will require administrative permissions as it may even
1016 install a device-driver (in case you are using gnunet-vpn and/or
1017 gnunet-exit).
1018
1019 @node Building the GNUnet Installer
1020 @subsection Building the GNUnet Installer
1021
1022 The GNUnet installer is made with
1023 @uref{http://nsis.sourceforge.net/, NSIS}.
1024 The installer script is located in @file{contrib\win} in the
1025 GNUnet source tree.
1026
1027 @node Using GNUnet with Netbeans on Windows
1028 @subsection Using GNUnet with Netbeans on Windows
1029
1030 TODO
1031
1032 @node Build instructions for Debian 7.5
1033 @section Build instructions for Debian 7.5
1034
1035
1036 These are the installation instructions for Debian 7.5. They were tested
1037 using a minimal, fresh Debian 7.5 AMD64 installation without non-free
1038 software (no contrib or non-free).
1039 By "minimal", we mean that during installation, we did not select any
1040 desktop environment, servers or system utilities during the "tasksel"
1041 step. Note that the packages and the dependencies that we will install
1042 during this chapter take about 1.5 GB of disk space.
1043 Combined with GNUnet and space for objects during compilation, you should
1044 not even attempt this unless you have about 2.5 GB free after the minimal
1045 Debian installation.
1046 Using these instructions to build a VM image is likely to require a
1047 minimum of 4-5 GB for the VM (as you will likely also want a desktop
1048 manager).
1049
1050 GNUnet's security model assumes that your @file{/home} directory is
1051 encrypted. Thus, if possible, you should encrypt your home partition
1052 (or per-user home directory).
1053
1054 Naturally, the exact details of the starting state for your installation
1055 should not matter much. For example, if you selected any of those
1056 installation groups you might simply already have some of the necessary
1057 packages installed.
1058 We did this for testing, as this way we are less likely to forget to
1059 mention a required package.
1060 Note that we will not install a desktop environment, but of course you
1061 will need to install one to use GNUnet's graphical user interfaces.
1062 Thus, it is suggested that you simply install the desktop environment of
1063 your choice before beginning with the instructions.
1064
1065
1066
1067 @menu
1068 * Update::
1069 * Stable? Hah!::
1070 * Update again::
1071 * Installing packages::
1072 * Installing dependencies from source::
1073 * Installing GNUnet from source::
1074 * But wait there is more!::
1075 @end menu
1076
1077 @node Update
1078 @subsection Update
1079
1080 After any installation, you should begin by running
1081
1082 @example
1083 # apt-get update ; apt-get upgrade
1084 @end example
1085
1086 to ensure that all of your packages are up-to-date. Note that the "#" is
1087 used to indicate that you need to type in this command as "root"
1088 (or prefix with "sudo"), whereas "$" is used to indicate typing in a
1089 command as a normal user.
1090
1091 @node Stable? Hah!
1092 @subsection Stable? Hah!
1093
1094 Yes, we said we start with a Debian 7.5 "stable" system. However, to
1095 reduce the amount of compilation by hand, we will begin by allowing the
1096 installation of packages from the testing and unstable distributions as
1097 well.
1098 We will stick to "stable" packages where possible, but some packages will
1099 be taken from the other distributions.
1100 Start by modifying @file{/etc/apt/sources.list} to contain the
1101 following (possibly adjusted to point to your mirror of choice):
1102
1103 @example
1104 # These were there before:
1105 deb http://ftp.de.debian.org/debian/ wheezy main
1106 deb-src http://ftp.de.debian.org/debian/ wheezy main
1107 deb http://security.debian.org/ wheezy/updates main
1108 deb-src http://security.debian.org/ wheezy/updates main
1109 deb http://ftp.de.debian.org/debian/ wheezy-updates main
1110 deb-src http://ftp.de.debian.org/debian/ wheezy-updates main
1111
1112 # Add these lines (feel free to adjust the mirror):
1113 deb http://ftp.de.debian.org/debian/ testing main
1114 deb http://ftp.de.debian.org/debian/ unstable main
1115 @end example
1116
1117 The next step is to create/edit your @file{/etc/apt/preferences}
1118 file to look like this:
1119
1120 @example
1121 Package: *
1122 Pin: release a=stable,n=wheezy
1123 Pin-Priority: 700
1124
1125 Package: *
1126 Pin: release o=Debian,a=testing
1127 Pin-Priority: 650
1128
1129 Package: *
1130 Pin: release o=Debian,a=unstable
1131 Pin-Priority: 600
1132 @end example
1133
1134 You can read more about Apt Preferences here and here.
1135 Note that other pinnings are likely to also work for GNUnet, the key
1136 thing is that you need some packages from unstable (as shown below).
1137 However, as unstable is unlikely to be comprehensive (missing packages)
1138 or might be problematic (crashing packages), you probably want others
1139 from stable and/or testing.
1140
1141 @node Update again
1142 @subsection Update again
1143
1144 Now, run again@
1145
1146 @example
1147 # apt-get update@
1148 # apt-get upgrade@
1149 @end example
1150
1151 to ensure that all your new distribution indices are downloaded, and
1152 that your pinning is correct: the upgrade step should cause no changes
1153 at all.
1154
1155 @node Installing packages
1156 @subsection Installing packages
1157
1158 We begin by installing a few Debian packages from stable:@
1159
1160 @example
1161 # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \
1162   libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev \
1163   texlive libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev \
1164   libbz2-dev libexiv2-dev libflac-dev libgif-dev libglib2.0-dev \
1165   libgtk-3-dev libmagic-dev libjpeg8-dev libmpeg2-4-dev libmp4v2-dev \
1166   librpm-dev libsmf-dev libtidy-dev libtiff5-dev libvorbis-dev \
1167   libogg-dev zlib1g-dev g++ gettext libgsf-1-dev libunbound-dev \
1168   libqrencode-dev libgladeui-dev nasm texlive-latex-extra \
1169   libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev
1170 @end example
1171
1172 After that, we install a few more packages from unstable:@
1173
1174 @example
1175 # apt-get install -t unstable nettle-dev libgstreamer1.0-dev \
1176   gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
1177   libgstreamer-plugins-base1.0-dev
1178 @end example
1179
1180 @node Installing dependencies from source
1181 @subsection Installing dependencies from source
1182
1183 Next, we need to install a few dependencies from source.
1184 You might want to do this as a "normal" user and only run the
1185 @code{make install} steps as root (hence the @code{sudo} in the
1186 commands below). Also, you do this from any
1187 directory. We begin by downloading all dependencies, then extracting the
1188 sources, and finally compiling and installing the libraries.
1189
1190 For these steps, follow the instructions given in the
1191 installation from source instruction in this order:
1192
1193 @itemize @bullet
1194 @item @ref{generic source installation - libav}
1195 @item @ref{generic source installation - libextractor}
1196 @item @ref{generic source installation - libgpg-error}
1197 @item @ref{generic source installation - libgcrypt}
1198 @item @ref{generic source installation - gnutls}
1199 @item @ref{generic source installation - libmicrohttpd}
1200 @item @ref{generic source installation - libgnurl}
1201 @end itemize
1202
1203 @node Installing GNUnet from source
1204 @subsection Installing GNUnet from source
1205
1206
1207 For this, simply follow the generic installation instructions from
1208 here.
1209
1210 @node But wait there is more!
1211 @subsection But wait there is more!
1212
1213 So far, we installed all of the packages and dependencies required to
1214 ensure that all of GNUnet would be built.
1215 However, while for example the plugins to interact with the MySQL or
1216 Postgres databases have been created, we did not actually install or
1217 configure those databases. Thus, you will need to install
1218 and configure those databases or stick with the default Sqlite database.
1219 Sqlite is usually fine for most applications, but MySQL can offer better
1220 performance and Postgres better resillience.
1221
1222
1223 @node Installing GNUnet from Git on Ubuntu 14.4
1224 @section Installing GNUnet from Git on Ubuntu 14.4
1225
1226 @strong{Install the required build tools:}
1227
1228 @example
1229 $ sudo apt-get install git automake autopoint autoconf
1230 @end example
1231
1232 @strong{Install the required dependencies}
1233
1234 @example
1235 $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \
1236  libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \
1237  libmicrohttpd-dev libgnutls28-dev
1238 @end example
1239
1240 @strong{Choose one or more database backends}
1241
1242 @itemize @bullet
1243
1244 @item SQLite3:
1245
1246 @example
1247 $ sudo apt-get install libsqlite3-dev
1248 @end example
1249
1250 @item MySQL:
1251
1252 @example
1253 $ sudo apt-get install libmysqlclient-dev
1254 @end example
1255
1256 @item PostgreSQL:
1257
1258 @example
1259 $ sudo apt-get install libpq-dev postgresql
1260 @end example
1261
1262 @end itemize
1263
1264 @strong{Install the optional dependencies for gnunet-conversation:}
1265
1266 @example
1267 $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev
1268 @end example
1269
1270 @strong{Install the libgrypt 1.6.1:}
1271
1272 @itemize @bullet
1273
1274 @item For Ubuntu 14.04:
1275
1276 @example
1277 $ sudo apt-get install libgcrypt20-dev
1278 @end example
1279
1280 @item For Ubuntu older 14.04:
1281
1282 @example
1283 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2
1284 $ tar xf libgcrypt-1.6.1.tar.bz2
1285 $ cd libgcrypt-1.6.1
1286 $ ./configure
1287 $ sudo make install
1288 $ cd ..
1289 @end example
1290
1291 @end itemize
1292
1293 @strong{Install libgnurl}
1294
1295 @example
1296 $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2
1297 $ tar xf gnurl-7.35.0.tar.bz2
1298 $ cd gnurl-7.35.0
1299 $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
1300  --without-libmetalink --without-winidn --without-librtmp \
1301  --without-nghttp2 --without-nss --without-cyassl --without-polarssl \
1302  --without-ssl --without-winssl --without-darwinssl --disable-sspi \
1303  --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \
1304  --disable-telnet --disable-tftp --disable-pop3 --disable-imap \
1305  --disable-smtp --disable-gopher --disable-file --disable-ftp
1306 $ sudo make install
1307 $ cd ..
1308 @end example
1309
1310 @strong{Install GNUnet}
1311
1312 @example
1313 $ git clone https://gnunet.org/git/gnunet/
1314 $ cd gnunet/
1315 $ ./bootstrap
1316 @end example
1317
1318 If you want to:
1319
1320 @itemize @bullet
1321
1322 @item Install to a different directory:
1323
1324 @example
1325 --prefix=PREFIX
1326 @end example
1327
1328 @item
1329 Have sudo permission, but do not want to compile as root:
1330
1331 @example
1332 --with-sudo
1333 @end example
1334
1335 @item
1336 Want debug message enabled:
1337
1338 @example
1339 --enable-logging=verbose
1340 @end example
1341
1342 @end itemize
1343
1344
1345 @example
1346 $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose]
1347 $ make; sudo make install
1348 @end example
1349
1350 After installing it, you need to create an empty configuration file:
1351
1352 @example
1353 touch ~/.config/gnunet.conf
1354 @end example
1355
1356 And finally you can start GNUnet with
1357
1358 @example
1359 $ gnunet-arm -s
1360 @end example
1361
1362 @node Build instructions for Debian 8
1363 @section Build instructions for Debian 8
1364 @c FIXME: I -> we
1365
1366 These are the installation instructions for Debian 8. They were tested
1367 sing a fresh Debian 8 AMD64 installation without non-free software (no
1368 contrib or non-free). During installation, I only selected "lxde" for the
1369 desktop environment.
1370 Note that the packages and the dependencies that we will install during
1371 this chapter take about 1.5 GB of disk space. Combined with GNUnet and
1372 space for objects during compilation, you should not even attempt this
1373 unless you have about 2.5 GB free after the Debian installation.
1374 Using these instructions to build a VM image is likely to require a
1375 minimum of 4-5 GB for the VM (as you will likely also want a desktop
1376 manager).
1377
1378 GNUnet's security model assumes that your @code{/home} directory is
1379 encrypted.
1380 Thus, if possible, you should encrypt your entire disk, or at least just
1381 your home partition (or per-user home directory).
1382
1383 Naturally, the exact details of the starting state for your installation
1384 should not matter much.
1385 For example, if you selected any of those installation groups you might
1386 simply already have some of the necessary packages installed. Thus, it is
1387 suggested that you simply install the desktop environment of your choice
1388 before beginning with the instructions.
1389
1390
1391 @menu
1392 * Update Debian::
1393 * Installing Debian Packages::
1394 * Installing Dependencies from Source2::
1395 * Installing GNUnet from Source2::
1396 * But wait (again) there is more!::
1397 @end menu
1398
1399 @node Update Debian
1400 @subsection Update Debian
1401
1402 After any installation, you should begin by running
1403
1404 @example
1405 # apt-get update
1406 # apt-get upgrade
1407 @end example
1408
1409 to ensure that all of your packages are up-to-date. Note that the "#" is
1410 used to indicate that you need to type in this command as "root" (or
1411 prefix with "sudo"), whereas "$" is used to indicate typing in a command
1412 as a normal user.
1413
1414 @node Installing Debian Packages
1415 @subsection Installing Debian Packages
1416
1417 We begin by installing a few Debian packages from stable:
1418
1419 @example
1420 # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \
1421 libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \
1422 libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \
1423 libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \
1424 libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext \
1425 libgsf-1-dev libunbound-dev libqrencode-dev libgladeui-dev nasm \
1426 texlive-latex-extra libunique-3.0-dev gawk miniupnpc libfuse-dev \
1427 libbluetooth-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
1428 libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev \
1429 libgcrypt20-dev libmicrohttpd-dev
1430 @end example
1431
1432 @node Installing Dependencies from Source2
1433 @subsection Installing Dependencies from Source2
1434
1435 Yes, we said we start with a Debian 8 "stable" system, but because Debian
1436 linked GnuTLS without support for DANE, we need to compile a few things,
1437 in addition to GNUnet, still by hand. Yes, you can run GNUnet using the
1438 respective Debian packages, but then you will not get DANE support.
1439
1440 Next, we need to install a few dependencies from source. You might want
1441 to do this as a "normal" user and only run the @code{make install} steps
1442 as root (hence the @code{sudo} in the commands below). Also, you do this
1443 from any directory. We begin by downloading all dependencies, then
1444 extracting the sources, and finally compiling and installing the
1445 libraries:
1446
1447 @example
1448 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz
1449 $ tar xvf gnutls-3.3.12.tar.xz
1450 $ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd ..
1451 @end example
1452
1453 For the installation and compilation of libgnurl/gnURL refer to
1454 the generic installation section,
1455 @xref{generic source installation - libgnurl}.
1456
1457 @node Installing GNUnet from Source2
1458 @subsection Installing GNUnet from Source2
1459
1460 For this, simply follow the generic installation instructions from@
1461 here.
1462
1463 @node But wait (again) there is more!
1464 @subsection But wait (again) there is more!
1465
1466 So far, we installed all of the packages and dependencies required to
1467 ensure that all of GNUnet would be built. However, while for example the
1468 plugins to interact with the MySQL or Postgres databases have been
1469 created, we did not actually install or configure those databases.
1470 Thus, you will need to install and configure those databases or stick
1471 with the default Sqlite database. Sqlite is usually fine for most
1472 applications, but MySQL can offer better performance and Postgres better
1473 resillience.
1474
1475 @c @node Build instructions for OpenBSD 6.2
1476 @c @section Build instructions for OpenBSD 6.2
1477
1478 @node Outdated build instructions for previous revisions
1479 @section Outdated build instructions for previous revisions
1480
1481 This chapter contains a collection of outdated, older installation guides.
1482 They are mostly intended to serve as a starting point for writing
1483 up-to-date instructions and should not be expected to work for
1484 GNUnet 0.10.x.
1485 A set of older installation instructions can also be found in the
1486 file @file{doc/outdated-and-old-installation-instructions.txt} in the
1487 source tree of GNUnet.
1488
1489 This file covers old instructions which no longer receive security
1490 updates or any kind of support.
1491
1492 @menu
1493 * Installing GNUnet 0.10.1 on Ubuntu 14.04::
1494 * Building GLPK for MinGW::
1495 * GUI build instructions for Ubuntu 12.04 using Subversion::
1496 @c * Installation with gnunet-update::
1497 * Instructions for Microsoft Windows Platforms (Old)::
1498 @end menu
1499
1500
1501 @node Installing GNUnet 0.10.1 on Ubuntu 14.04
1502 @subsection Installing GNUnet 0.10.1 on Ubuntu 14.04
1503
1504 Install the required dependencies:
1505
1506 @example
1507 $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \
1508  libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \
1509  libmicrohttpd-dev libgnutls28-dev
1510 @end example
1511
1512 Choose one or more database backends:
1513
1514 @itemize @bullet
1515
1516 @item SQLite3
1517
1518 @example
1519  $ sudo apt-get install libsqlite3-dev@
1520 @end example
1521
1522 @item MySQL
1523
1524 @example
1525 $ sudo apt-get install libmysqlclient-dev@
1526 @end example
1527
1528 @item PostgreSQL
1529
1530 @example
1531  $ sudo apt-get install libpq-dev postgresql@
1532 @end example
1533
1534 @end itemize
1535
1536 Install the optional dependencies for gnunet-conversation:
1537
1538 @example
1539  $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev
1540 @end example
1541
1542 Install libgcrypt 1.6:
1543
1544 @itemize @bullet
1545
1546 @item For Ubuntu 14.04:
1547
1548 @example
1549 $ sudo apt-get install libgcrypt20-dev
1550 @end example
1551
1552 @item For Ubuntu older than 14.04:
1553
1554 @example
1555 wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2
1556 $ tar xf libgcrypt-1.6.1.tar.bz2
1557 $ cd libgcrypt-1.6.1
1558 $ ./configure
1559 $ sudo make install
1560 $ cd ..
1561 @end example
1562 @end itemize
1563
1564 Install libgnurl:
1565
1566 @pxref{generic source installation - libgnurl}.
1567
1568 Install GNUnet:
1569
1570 @example
1571 $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz
1572 $ tar xf gnunet-0.10.1.tar.gz
1573 $ cd gnunet-0.10.1
1574 @end example
1575
1576 If you want to:
1577
1578 @itemize @bullet
1579
1580 @item
1581 Install to a different directory:
1582
1583 @example
1584 --prefix=PREFIX
1585 @end example
1586
1587 @item
1588 Have sudo permission, but do not want to compile as root:
1589
1590 @example
1591 --with-sudo
1592 @end example
1593
1594 @item
1595 Want debug message enabled:
1596
1597 @example
1598 --enable-logging=verbose
1599 @end example
1600
1601 @end itemize
1602
1603 @example
1604 $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose]
1605 $ make; sudo make install
1606 @end example
1607
1608 After installing it, you need to create an empty configuration file:
1609
1610 @example
1611 touch ~/.config/gnunet.conf
1612 @end example
1613
1614 And finally you can start GNUnet with
1615
1616 @example
1617 $ gnunet-arm -s
1618 @end example
1619
1620 @node Building GLPK for MinGW
1621 @subsection Building GLPK for MinGW
1622
1623 GNUnet now requires the GNU Linear Programming Kit (GLPK).
1624 Since there's is no package you can install with @code{mingw-get} you
1625 have to compile it from source:
1626
1627 @itemize @bullet
1628
1629 @item Download the latest version from
1630 @uref{http://ftp.gnu.org/gnu/glpk/}
1631
1632 @item Unzip the downloaded source tarball using your favourite
1633 unzipper application In the MSYS shell
1634
1635 @item change to the respective directory
1636
1637 @item Configure glpk for "i686-pc-mingw32":
1638
1639 @example
1640 ./configure '--build=i686-pc-mingw32'
1641 @end example
1642
1643 @item run
1644
1645 @example
1646 make install check
1647 @end example
1648
1649 @end itemize
1650
1651 MinGW does not automatically detect the correct buildtype so you have to
1652 specify it manually.
1653
1654
1655 @node GUI build instructions for Ubuntu 12.04 using Subversion
1656 @subsection GUI build instructions for Ubuntu 12.04 using Subversion
1657
1658 After installing GNUnet you can continue installing the GNUnet GUI tools:
1659
1660 First, install the required dependencies:
1661
1662 @example
1663 $ sudo apt-get install libgladeui-dev libqrencode-dev
1664 @end example
1665
1666 Please ensure that the GNUnet shared libraries can be found by the linker.
1667 If you installed GNUnet libraries in a non standard path
1668 (say GNUNET_PREFIX=/usr/local/lib/), you can
1669
1670 @itemize @bullet
1671
1672 @item set the environmental variable permanently to:
1673
1674 @example
1675 LD_LIBRARY_PATH=$GNUNET_PREFIX
1676 @end example
1677
1678 @item or add @code{$GNUNET_PREFIX} to @file{/etc/ld.so.conf}
1679
1680 @end itemize
1681
1682 Now you can checkout and compile the GNUnet GUI tools:
1683
1684 @example
1685 $ git clone https://gnunet.org/git/gnunet-gtk
1686 $ cd gnunet-gtk
1687 $ ./bootstrap
1688 $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/..
1689 $ make install
1690 @end example
1691
1692 @c @node Installation with gnunet-update
1693 @c @subsection Installation with gnunet-update
1694
1695 @c gnunet-update project is an effort to introduce updates to GNUnet
1696 @c installations. An interesting to-be-implemented-feature of gnunet-update
1697 @c is that these updates are propagated through GNUnet's peer-to-peer
1698 @c network. More information about gnunet-update can be found at
1699 @c @c FIXME: Use correct cgit URL
1700 @c @uref{https://gnunet.org/git/gnunet-update.git/tree/plain/README}.
1701
1702 @c While the project is still under development, we have implemented the
1703 @c following features which we believe may be helpful for users and we
1704 @c would like them to be tested:
1705
1706 @c @itemize @bullet
1707
1708 @c @item
1709 @c Packaging GNUnet installation along with its run-time dependencies into
1710 @c update packages
1711
1712 @c @item
1713 @c Installing update packages into compatible hosts
1714
1715 @c @item
1716 @c Updating an existing installation (which had been installed by
1717 @c gnunet-update) to a newer one
1718
1719 @c @end itemize
1720
1721 @c The above said features of gnunet-update are currently available for
1722 @c testing on GNU/Linux systems.
1723
1724 @c The following is a guide to help you get started with gnunet-update.
1725 @c It shows you how to install the testing binary packages of GNUnet
1726 @c 0.9.1 we have at @uref{https://gnunet.org/install/}.
1727
1728 @c gnunet-update needs the following dependencies:
1729
1730 @c @itemize @bullet
1731 @c @item
1732 @c python @geq{} 2.6
1733
1734 @c @item
1735 @c gnupg
1736
1737 @c @item
1738 @c python-gpgme
1739 @c @end itemize
1740
1741
1742 @c Checkout gnunet-update:
1743
1744 @c @c FIXME: git!
1745 @c @example
1746 @c $ svn checkout -r24905 https://gnunet.org/svn/gnunet-update@
1747 @c @end example
1748
1749 @c For security reasons, all packages released for gnunet-update from us are
1750 @c signed with the key at @uref{https://gnunet.org/install/key.txt}.
1751 @c You would need to import this key into your gpg key ring.
1752 @c gnunet-update uses this key to verify the integrity of the packages it
1753 @c installs:
1754
1755 @c @example
1756 @c $ gpg --recv-keys 7C613D78@
1757 @c @end example
1758
1759 @c Download the packages relevant to your architecture (currently I have
1760 @c access to GNU/Linux machines on x86_64 and i686, so only two for now,
1761 @c hopefully more later) from https://gnunet.org/install/.
1762
1763 @c To install the downloaded package into the directory /foo:
1764
1765 @c @example
1766 @c gnunet-update/bin/gnunet-update install downloaded/package /foo
1767 @c @end example
1768
1769 @c The installer reports the directories into which shared libraries and
1770 @c dependencies have been installed. You may need to add the reported shared
1771 @c library installation paths to LD_LIBRARY_PATH before you start running any
1772 @c installed binaries.
1773
1774 @c Please report bugs at https://gnunet.org/bugs/ under the project
1775 @c 'gnunet-update'.
1776
1777 @node Instructions for Microsoft Windows Platforms (Old)
1778 @subsection Instructions for Microsoft Windows Platforms (Old)
1779
1780 This document is a @b{DEPRECATED} installation guide for GNUnet on
1781 Windows.
1782 It will not work for recent GNUnet versions, but maybe it will be of
1783 some use if problems arise.
1784
1785 The Windows build uses a UNIX emulator for Windows,
1786 @uref{http://www.mingw.org/, MinGW}, to build the executable modules.
1787 These modules run natively on Windows and do not require additional
1788 emulation software besides the usual dependencies.
1789
1790 GNUnet development is mostly done under GNU/Linux and especially git
1791 checkouts may not build out of the box.
1792 We regret any inconvenience, and if you have problems, please report them.
1793
1794 @menu
1795 * Hardware and OS requirements::
1796 * Software installation::
1797 * Building libextractor and GNUnet::
1798 * Installer::
1799 * Source::
1800 @end menu
1801
1802 @node Hardware and OS requirements
1803 @subsubsection Hardware and OS requirements
1804
1805 @itemize @bullet
1806
1807 @item Pentium II or equivalent processor, @geq{} 350 MHz
1808
1809 @item 128 MB RAM
1810
1811 @item 600 MB free disk space
1812
1813 @item Windows 2000 or Windows XP are recommended
1814
1815 @end itemize
1816
1817 @node Software installation
1818 @subsubsection Software installation
1819
1820 @itemize @bullet
1821
1822 @item
1823 @strong{Compression software}@
1824
1825 The software packages GNUnet depends on are usually compressed using UNIX
1826 tools like @command{tar}, @command{gzip}, @command{xzip} and
1827 @command{bzip2}.
1828 If you do not already have an utility that is able to extract such
1829 archives, get @uref{http://www.7-zip.org/, 7-Zip}.
1830
1831 @item
1832 @strong{UNIX environment}@
1833
1834 The MinGW project provides the compiler toolchain that is used to build
1835 GNUnet.
1836 Get the following packages from the
1837 @uref{http://sourceforge.net/projects/mingw/files/, MinGW} project:
1838
1839 @itemize @bullet
1840
1841 @item GCC core
1842 @item GCC g++
1843 @item MSYS
1844 @item MSYS Developer Tool Kit (msysDTK)
1845 @item MSYS Developer Tool Kit - msys-autoconf (bin)
1846 @item MSYS Developer Tool Kit - msys-automake (bin)
1847 @item MinGW Runtime
1848 @item MinGW Utilities
1849 @item Windows API
1850 @item Binutils
1851 @item make
1852 @item pdcurses
1853 @item GDB (snapshot)
1854 @end itemize
1855
1856 @itemize @bullet
1857
1858
1859 @item Install MSYS (to c:\mingw, for example.)@
1860 Do @strong{not} use spaces in the pathname.
1861 For example, avoid a location such as @file{c:\program files\mingw}.
1862
1863 @item Install MinGW runtime, utilities and GCC to a subdirectory
1864 (to @file{c:\mingw\mingw}, for example)
1865
1866 @item Install the Development Kit to the MSYS directory
1867 (@file{c:\mingw})
1868
1869 @item Create a batch file bash.bat in your MSYS directory with
1870 the files:
1871
1872 @example
1873 bin\sh.exe --login
1874 @end example
1875
1876 This batch file opens a shell which is used to invoke the build
1877 processes.
1878 MinGW's standard shell (@command{msys.bat}) is not suitable
1879 because it opens a separate console window.
1880 On Vista, @command{bash.bat} needs to be run as Administrator.
1881
1882 @item
1883 Start @command{bash.sh} and rename
1884 @file{c:\mingw\mingw\lib\libstdc++.la} to avoid problems:
1885
1886 @example
1887 mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken
1888 @end example
1889
1890 @item
1891 Unpack the Windows API to the MinGW directory (@file{c:\mingw\mingw\}) and
1892 remove the declaration of DATADIR from
1893 (@file{c:\mingw\mingw\include\objidl.h} (lines 55-58)
1894
1895 @item
1896 Unpack autoconf, automake to the MSYS directory (@file{c:\mingw})
1897
1898 @item
1899 Install all other packages to the MinGW directory (@file{c:\mingw\mingw\})
1900 @end itemize
1901
1902
1903 @item @strong{GNU Libtool}@
1904 GNU Libtool is required to use shared libraries.
1905 Get the prebuilt package from here and unpack it to the
1906 MinGW directory (@file{c:\mingw})
1907
1908 @item @strong{Pthreads}@
1909 GNUnet uses the portable POSIX thread library for multi-threading:
1910
1911 @itemize @bullet
1912
1913 @item Save
1914 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/libpthreadGC2.a, libpthreadGC2.a}
1915 (x86) or
1916 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/libpthreadGC2.a, libpthreadGC2.a}
1917 (x64) as libpthread.a into the @file{lib}
1918 directory (@file{c:\mingw\mingw\lib\libpthread.a}).
1919
1920 @item Save
1921 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/pthreadGC2.dll, pthreadGC2.dll}
1922 (x86) or
1923 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/pthreadGC2.dll, libpthreadGC2.a}
1924 (x64) into the MinGW @file{bin} directory (@file{c:\mingw\mingw\bin}).
1925
1926 @item Download all header files from
1927 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/include/, include/}
1928 to the @file{include} directory (@file{c:\mingw\mingw\include}).
1929 @end itemize
1930
1931
1932 @item @strong{GNU MP}@
1933 GNUnet uses the GNU Multiple Precision library for special cryptographic
1934 operations. Get the GMP binary package from the
1935 @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and
1936 unpack it to the MinGW directory (@file{c:\mingw\mingw})
1937
1938 @item @strong{GNU Gettext}@
1939 GNU gettext is used to provide national language support.
1940 Get the prebuilt package from hereand unpack it to the MinGW
1941 directory (@file{c:\mingw\mingw})
1942
1943 @item @strong{GNU iconv}@
1944 GNU Libiconv is used for character encoding conversion.
1945 Get the prebuilt package from here and unpack it to the MinGW
1946 directory (@file{c:\mingw\mingw}).
1947
1948 @item @strong{SQLite}@
1949 GNUnet uses the SQLite database to store data.
1950 Get the prebuilt binary from here and unpack it to your MinGW directory.
1951
1952 @item @strong{MySQL}@
1953 As an alternative to SQLite, GNUnet also supports MySQL.
1954
1955 @itemize @bullet
1956
1957 @item Get the binary installer from the
1958 @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project}
1959 (version 4.1), install it and follow the instructions in
1960 @file{README.mysql}.
1961
1962 @item  Create a temporary build directory (@file{c:\mysql})
1963
1964 @item Copy the directories @file{include\} and @file{lib\} from the
1965 MySQL directory to the new directory
1966
1967 @item Get the patches from
1968 @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and
1969 @uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the
1970 latter is only required for MySQL
1971
1972 @example
1973 patch -p 0
1974 @end example
1975
1976 @item Move @file{lib\opt\libmysql.dll} to @file{lib\libmysql.dll}
1977
1978 @item  Change to @file{lib\} and create an import library:
1979
1980 @example
1981 dlltool --input-def ../include/libmySQL.def \
1982 --dllname libmysql.dll \
1983 --output-lib libmysqlclient.a -k
1984 @end example
1985
1986 @item  Copy include\* to include\mysql\
1987
1988 @item  Pass @code{--with-mysql=/c/mysql} to
1989 @command{./configure} and copy @file{libmysql.dll}
1990 to your PATH or GNUnet's @file{bin} directory
1991 @end itemize
1992
1993
1994 @item @strong{GTK+}@
1995 @command{gnunet-fs-gtk} and @command{libextractor} depend on GTK.
1996 Get the the binary and developer packages of @command{atk},
1997 @command{glib}, @command{gtk}, @command{iconv},
1998 @command{gettext-runtime}, @command{pango} from
1999 @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack them
2000 to the MinGW directory (@file{c:\mingw\mingw}).
2001 @c FIXME: The URL below for pkg-config seems wrong.
2002 Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and
2003 @command{libpng} and unpack them to the MinGW directory
2004 (@file{c:\mingw\mingw}).
2005 Here is an all-in-one package for the
2006 @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies}
2007 . Do not overwrite any existing files!
2008
2009 @item @strong{Glade}@
2010 @command{gnunet-*-gtk} and @command{gnunet-setup} were created using
2011 this interface builder
2012
2013 @itemize @bullet
2014
2015 @item Get the Glade and libglade (-bin and -devel) packages
2016 (without GTK!) from
2017 @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack them to
2018 the MinGW directory (@file{c:\mingw\mingw}).
2019
2020 @item Get @command{libxml} from here and unpack it to the MinGW
2021 directory (@file{c:\mingw\mingw}).
2022 @end itemize
2023
2024 @c FIXME: URLs
2025 @item @strong{zLib}@
2026 @command{libextractor} requires @command{zLib} to decompress some file
2027 formats. GNUnet uses it to (de)compress meta-data.
2028 Get zLib from here (Signature) and unpack it to the MinGW directory
2029 (@file{c:\mingw\mingw}).
2030
2031 @item @strong{Bzip2}@
2032 @command{libextractor} also requires @command{Bzip2} to
2033 decompress some file formats.
2034 Get the Bzip2 (binary and developer package) from
2035 @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and
2036 unpack it to the MinGW directory (@file{c:\mingw\mingw}).
2037
2038 @item @strong{Libgcrypt}@
2039 @command{Libgcrypt} provides the cryptographic functions used by GNUnet.
2040 Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here},
2041 compile and place it in the MinGW directory
2042 (@file{c:\mingw\mingw}). Currently libgcrypt @geq{} 1.4.2 is required to
2043 compile GNUnet.
2044
2045 @item @strong{PlibC}@
2046 PlibC emulates Unix functions under Windows. Get PlibC from here and
2047 unpack it to the MinGW directory (c:\mingw\mingw)
2048
2049 @item @strong{OGG Vorbis}@
2050 @command{OGG Vorbis} is used to extract meta-data from @file{.ogg} files.
2051 Get the packages
2052 @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg}
2053 and
2054 @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis}
2055 from the
2056 @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build}
2057 and unpack them to the MinGW directory (c:\mingw\mingw).
2058
2059 @item @strong{Exiv2}@
2060 (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data.
2061 Download
2062 @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2}
2063 and unpack it to the MSYS directory (c:\mingw).
2064 @end itemize
2065
2066 @node Building libextractor and GNUnet
2067 @subsubsection Building libextractor and GNUnet
2068
2069 Before you compile @command{libextractor} or @command{GNUnet},
2070 be sure to set @code{PKG_CONFIG_PATH}:
2071
2072 @example
2073 export PKG_CONFIG_PATH=/mingw/lib/pkgconfig
2074 @end example
2075
2076 @noindent
2077 @xref{GNUnet Installation Handbook}, for basic instructions on building
2078 @command{libextractor} and @command{GNUnet}.
2079 By default, all modules that are created in this way contain
2080 debug information and are quite large. To compile release versions
2081 (small and fast) set the variable @code{CFLAGS}:
2082
2083 @example
2084 export CFLAGS='-O2 -march=pentium -fomit-frame-pointer'
2085 ./configure --prefix=$HOME --with-extractor=$HOME
2086 @end example
2087
2088 @node Installer
2089 @subsubsection Installer
2090
2091 The GNUnet installer is made with
2092 @uref{http://nsis.sourceforge.net/, NSIS}. The installer script is
2093 located in @file{contrib\win} in the GNUnet source tree.
2094
2095 @node Source
2096 @subsubsection Source
2097
2098 @c FIXME: URL
2099 The sources of all dependencies are available here.
2100
2101 @c @node Portable GNUnet
2102 @c @section Portable GNUnet
2103
2104 @c Quick instructions on how to use the most recent GNUnet on most GNU/Linux
2105 @c distributions
2106
2107 @c Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian
2108 @c and CentOS 6, but it should work on almost any GNU/Linux distribution.
2109 @c More in-detail information can be found in the handbook.
2110
2111 @c Note 2017-10: Currently this section assumes the old SVN repo of GNUnet
2112 @c which no longer exists.
2113
2114 @c @menu
2115 @c * Prerequisites::
2116 @c * Download & set up gnunet-update::
2117 @c * Install GNUnet::
2118 @c @end menu
2119
2120 @c @node Prerequisites
2121 @c @subsection Prerequisites
2122
2123 @c Open a terminal and paste this line into it to install all required tools
2124 @c needed:
2125
2126 @c @example
2127 @c sudo apt-get install python-gpgme subversion
2128 @c @end example
2129
2130 @c @node Download & set up gnunet-update
2131 @c @subsection Download & set up gnunet-update
2132
2133 @c The following command will download a working version of gnunet-update
2134 @c with the subversion tool and import the public key which is needed for
2135 @c authentication:
2136
2137 @c @example
2138 @c svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update
2139 @c cd ~/gnunet-update
2140 @c gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78
2141 @c @end example
2142
2143 @c @node Install GNUnet
2144 @c @subsection Install GNUnet
2145
2146 @c Download and install GNUnet binaries which can be found here and set
2147 @c library paths:
2148
2149 @c @example
2150 @c wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz
2151 @c ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~
2152 @c echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment
2153 @c echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \
2154 @c  /etc/ld.so.conf.d/gnunet.conf > /dev/null
2155 @c sudo ldconfig
2156 @c @end example
2157
2158 @c You may need to re-login once after executing these last commands
2159
2160 @c That's it, GNUnet is installed in your home directory now. GNUnet can be
2161 @c configured and afterwards started by executing:
2162
2163 @c @example
2164 @c gnunet-arm -s
2165 @c @end example
2166
2167 @node The graphical configuration interface
2168 @section The graphical configuration interface
2169
2170 If you also would like to use @command{gnunet-gtk} and
2171 @command{gnunet-setup} (highly recommended for beginners), do:
2172
2173 @example
2174 wget -P /tmp \
2175 https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz
2176 sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~
2177 sudo ldconfig
2178 @end example
2179
2180 Now you can run @command{gnunet-setup} for easy configuration of your
2181 GNUnet peer.
2182
2183 @menu
2184 * Configuring your peer::
2185 * Configuring the Friend-to-Friend (F2F) mode::
2186 * Configuring the hostlist to bootstrap::
2187 * Configuration of the HOSTLIST proxy settings::
2188 * Configuring your peer to provide a hostlist ::
2189 * Configuring the datastore::
2190 * Configuring the MySQL database::
2191 * Reasons for using MySQL::
2192 * Reasons for not using MySQL::
2193 * Setup Instructions::
2194 * Testing::
2195 * Performance Tuning::
2196 * Setup for running Testcases::
2197 * Configuring the Postgres database::
2198 * Reasons to use Postgres::
2199 * Reasons not to use Postgres::
2200 * Manual setup instructions::
2201 * Testing the setup manually::
2202 * Configuring the datacache::
2203 * Configuring the file-sharing service::
2204 * Configuring logging::
2205 * Configuring the transport service and plugins::
2206 * Configuring the wlan transport plugin::
2207 * Configuring HTTP(S) reverse proxy functionality using Apache or nginx::
2208 * Blacklisting peers::
2209 * Configuration of the HTTP and HTTPS transport plugins::
2210 * Configuring the GNU Name System::
2211 * Configuring the GNUnet VPN::
2212 * Bandwidth Configuration::
2213 * Configuring NAT::
2214 * Peer configuration for distributions::
2215 @end menu
2216
2217 @node Configuring your peer
2218 @subsection Configuring your peer
2219
2220 This chapter will describe the various configuration options in GNUnet.
2221
2222 The easiest way to configure your peer is to use the
2223 @command{gnunet-setup} tool.
2224 @command{gnunet-setup} is part of the @command{gnunet-gtk}
2225 application. You might have to install it separately.
2226
2227 Many of the specific sections from this chapter actually are linked from
2228 within @command{gnunet-setup} to help you while using the setup tool.
2229
2230 While you can also configure your peer by editing the configuration
2231 file by hand, this is not recommended for anyone except for developers
2232 as it requires a more in-depth understanding of the configuration files
2233 and internal dependencies of GNUnet.
2234
2235 @node Configuring the Friend-to-Friend (F2F) mode
2236 @subsection Configuring the Friend-to-Friend (F2F) mode
2237
2238 GNUnet knows three basic modes of operation:
2239 @itemize @bullet
2240 @item In standard "peer-to-peer" mode,
2241 your peer will connect to any peer.
2242 @item In the pure "friend-to-friend"
2243 mode, your peer will ONLY connect to peers from a list of friends
2244 specified in the configuration.
2245 @item Finally, in mixed mode,
2246 GNUnet will only connect to arbitrary peers if it
2247 has at least a specified number of connections to friends.
2248 @end itemize
2249
2250 When configuring any of the F2F ("friend-to-friend") modes,
2251 you first need to create a file with the peer identities
2252 of your friends. Ask your friends to run
2253
2254 @example
2255 $ gnunet-peerinfo -sq
2256 @end example
2257
2258 @noindent
2259 The resulting output of this command needs to be added to your
2260 @file{friends} file, which is simply a plain text file with one line
2261 per friend with the output from the above command.
2262
2263 You then specify the location of your @file{friends} file in the
2264 @code{FRIENDS} option of the "topology" section.
2265
2266 Once you have created the @file{friends} file, you can tell GNUnet to only
2267 connect to your friends by setting the @code{FRIENDS-ONLY} option
2268 (again in the "topology" section) to YES.
2269
2270 If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a
2271 minimum number of friends to have (before connecting to arbitrary peers)
2272 under the "MINIMUM-FRIENDS" option.
2273
2274 If you want to operate in normal P2P-only mode, simply set
2275 @code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO.
2276 This is the default.
2277
2278 @node Configuring the hostlist to bootstrap
2279 @subsection Configuring the hostlist to bootstrap
2280
2281 After installing the software you need to get connected to the GNUnet
2282 network. The configuration file included in your download is already
2283 configured to connect you to the GNUnet network.
2284 In this section the relevant configuration settings are explained.
2285
2286 To get an initial connection to the GNUnet network and to get to know
2287 peers already connected to the network you can use the so called
2288 "bootstrap servers".
2289 These servers can give you a list of peers connected to the network.
2290 To use these bootstrap servers you have to configure the hostlist daemon
2291 to activate bootstrapping.
2292
2293 To activate bootstrapping, edit the @code{[hostlist]}-section in your
2294 configuration file. You have to set the argument @command{-b} in the
2295 options line:
2296
2297 @example
2298 [hostlist]
2299 OPTIONS = -b
2300 @end example
2301
2302 Additionally you have to specify which server you want to use.
2303 The default bootstrapping server is
2304 "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}".
2305 [^] To set the server you have to edit the line "SERVERS" in the hostlist
2306 section. To use the default server you should set the lines to
2307
2308 @example
2309 SERVERS = http://v10.gnunet.org/hostlist [^]
2310 @end example
2311
2312 @noindent
2313 To use bootstrapping your configuration file should include these lines:
2314
2315 @example
2316 [hostlist]
2317 OPTIONS = -b
2318 SERVERS = http://v10.gnunet.org/hostlist [^]
2319 @end example
2320
2321 @noindent
2322 Besides using bootstrap servers you can configure your GNUnet peer to
2323 recieve hostlist advertisements.
2324 Peers offering hostlists to other peers can send advertisement messages
2325 to peers that connect to them. If you configure your peer to receive these
2326 messages, your peer can download these lists and connect to the peers
2327 included. These lists are persistent, which means that they are saved to
2328 your hard disk regularly and are loaded during startup.
2329
2330 To activate hostlist learning you have to add the @command{-e}
2331 switch to the @code{OPTIONS} line in the hostlist section:
2332
2333 @example
2334 [hostlist]
2335 OPTIONS = -b -e
2336 @end example
2337
2338 @noindent
2339 Furthermore you can specify in which file the lists are saved.
2340 To save the lists in the file @file{hostlists.file} just add the line:
2341
2342 @example
2343 HOSTLISTFILE = hostlists.file
2344 @end example
2345
2346 @noindent
2347 Best practice is to activate both bootstrapping and hostlist learning.
2348 So your configuration file should include these lines:
2349
2350 @example
2351 [hostlist]
2352 OPTIONS = -b -e
2353 HTTPPORT = 8080
2354 SERVERS = http://v10.gnunet.org/hostlist [^]
2355 HOSTLISTFILE = $SERVICEHOME/hostlists.file
2356 @end example
2357
2358 @node Configuration of the HOSTLIST proxy settings
2359 @subsection Configuration of the HOSTLIST proxy settings
2360
2361 The hostlist client can be configured to use a proxy to connect to the
2362 hostlist server.
2363 This functionality can be configured in the configuration file directly
2364 or using the @command{gnunet-setup} tool.
2365
2366 The hostlist client supports the following proxy types at the moment:
2367
2368 @itemize @bullet
2369 @item HTTP and HTTP 1.0 only proxy
2370 @item SOCKS 4/4a/5/5 with hostname
2371 @end itemize
2372
2373 In addition authentication at the proxy with username and password can be
2374 configured.
2375
2376 To configure proxy support for the hostlist client in the
2377 @command{gnunet-setup} tool, select the "hostlist" tab and select
2378 the appropriate proxy type.
2379 The hostname or IP address (including port if required) has to be entered
2380 in the "Proxy hostname" textbox. If required, enter username and password
2381 in the "Proxy username" and "Proxy password" boxes.
2382 Be aware that this information will be stored in the configuration in
2383 plain text (TODO: Add explanation and generalize the part in Chapter 3.6
2384 about the encrypted home).
2385
2386 To provide these options directly in the configuration, you can
2387 enter the following settings in the @code{[hostlist]} section of
2388 the configuration:
2389
2390 @example
2391 # Type of proxy server,
2392 # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME
2393 # Default: HTTP
2394 # PROXY_TYPE = HTTP
2395
2396 # Hostname or IP of proxy server
2397 # PROXY =
2398 # User name for proxy server
2399 # PROXY_USERNAME =
2400 # User password for proxy server
2401 # PROXY_PASSWORD =
2402 @end example
2403
2404 @node Configuring your peer to provide a hostlist
2405 @subsection Configuring your peer to provide a hostlist
2406
2407 If you operate a peer permanently connected to GNUnet you can configure
2408 your peer to act as a hostlist server, providing other peers the list of
2409 peers known to him.
2410
2411 Your server can act as a bootstrap server and peers needing to obtain a
2412 list of peers can contact it to download this list.
2413 To download this hostlist the peer uses HTTP.
2414 For this reason you have to build your peer with libgnurl (or libcurl)
2415 and microhttpd support.
2416 How you build your peer with these options can be found here:
2417 @xref{Generic installation instructions}.
2418
2419 To configure your peer to act as a bootstrap server you have to add the
2420 @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section
2421 of your configuration file.
2422 Besides that you have to specify a port number for the http server.
2423 In conclusion you have to add the following lines:
2424
2425 @example
2426 [hostlist]
2427 HTTPPORT = 12980
2428 OPTIONS = -p
2429 @end example
2430
2431 @noindent
2432 If your peer acts as a bootstrap server other peers should know about
2433 that. You can advertise the hostlist your are providing to other peers.
2434 Peers connecting to your peer will get a message containing an
2435 advertisement for your hostlist and the URL where it can be downloaded.
2436 If this peer is in learning mode, it will test the hostlist and, in the
2437 case it can obtain the list successfully, it will save it for
2438 bootstrapping.
2439
2440 To activate hostlist advertisement on your peer, you have to set the
2441 following lines in your configuration file:
2442
2443 @example
2444 [hostlist]
2445 EXTERNAL_DNS_NAME = example.org
2446 HTTPPORT = 12981
2447 OPTIONS = -p -a
2448 @end example
2449
2450 @noindent
2451 With this configuration your peer will a act as a bootstrap server and
2452 advertise this hostlist to other peers connecting to it.
2453 The URL used to download the list will be
2454 @code{@uref{http://example.org:12981/, http://example.org:12981/}}.
2455
2456 Please notice:
2457
2458 @itemize @bullet
2459 @item The hostlist is @b{not} human readable, so you should not try to
2460 download it using your webbrowser. Just point your GNUnet peer to the
2461 address!
2462 @item Advertising without providing a hostlist does not make sense and
2463 will not work.
2464 @end itemize
2465
2466 @node Configuring the datastore
2467 @subsection Configuring the datastore
2468
2469 The datastore is what GNUnet uses for long-term storage of file-sharing
2470 data. Note that long-term does not mean 'forever' since content does have
2471 an expiration date, and of course storage space is finite (and hence
2472 sometimes content may have to be discarded).
2473
2474 Use the @code{QUOTA} option to specify how many bytes of storage space
2475 you are willing to dedicate to GNUnet.
2476
2477 In addition to specifying the maximum space GNUnet is allowed to use for
2478 the datastore, you need to specify which database GNUnet should use to do
2479 so. Currently, you have the choice between sqLite, MySQL and Postgres.
2480
2481 @node Configuring the MySQL database
2482 @subsection Configuring the MySQL database
2483
2484 This section describes how to setup the MySQL database for GNUnet.
2485
2486 Note that the mysql plugin does NOT work with mysql before 4.1 since we
2487 need prepared statements.
2488 We are generally testing the code against MySQL 5.1 at this point.
2489
2490 @node Reasons for using MySQL
2491 @subsection Reasons for using MySQL
2492
2493 @itemize @bullet
2494
2495 @item On up-to-date hardware wher
2496 mysql can be used comfortably, this module
2497 will have better performance than the other database choices (according
2498 to our tests).
2499
2500 @item Its often possible to recover the mysql database from internal
2501 inconsistencies. Some of the other databases do not support repair.
2502 @end itemize
2503
2504 @node Reasons for not using MySQL
2505 @subsection Reasons for not using MySQL
2506
2507 @itemize @bullet
2508 @item Memory usage (likely not an issue if you have more than 1 GB)
2509 @item Complex manual setup
2510 @end itemize
2511
2512 @node Setup Instructions
2513 @subsection Setup Instructions
2514
2515 @itemize @bullet
2516
2517 @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
2518 @code{DATABASE} to @code{mysql}.
2519
2520 @item Access mysql as root:
2521
2522 @example
2523 $ mysql -u root -p
2524 @end example
2525
2526 @noindent
2527 and issue the following commands, replacing $USER with the username
2528 that will be running @command{gnunet-arm} (so typically "gnunet"):
2529
2530 @example
2531 CREATE DATABASE gnunet;
2532 GRANT select,insert,update,delete,create,alter,drop,create \
2533 temporary tables ON gnunet.* TO $USER@@localhost;
2534 SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like');
2535 FLUSH PRIVILEGES;
2536 @end example
2537
2538 @item
2539 In the $HOME directory of $USER, create a @file{.my.cnf} file with the
2540 following lines
2541
2542 @example
2543 [client]
2544 user=$USER
2545 password=$the_password_you_like
2546 @end example
2547
2548 @end itemize
2549
2550 Thats it. Note that @file{.my.cnf} file is a slight security risk unless
2551 its on a safe partition. The @file{$HOME/.my.cnf} can of course be
2552 a symbolic link.
2553 Luckily $USER has only priviledges to mess up GNUnet's tables,
2554 which should be pretty harmless.
2555
2556 @node Testing
2557 @subsection Testing
2558
2559 You should briefly try if the database connection works. First, login
2560 as $USER. Then use:
2561
2562 @example
2563 $ mysql -u $USER
2564 mysql> use gnunet;
2565 @end example
2566
2567 @noindent
2568 If you get the message
2569
2570 @example
2571 Database changed
2572 @end example
2573
2574 @noindent
2575 it probably works.
2576
2577 If you get
2578
2579 @example
2580 ERROR 2002: Can't connect to local MySQL server
2581 through socket '/tmp/mysql.sock' (2)
2582 @end example
2583
2584 @noindent
2585 it may be resolvable by
2586
2587 @example
2588 ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock
2589 @end example
2590
2591 @noindent
2592 so there may be some additional trouble depending on your mysql setup.
2593
2594 @node Performance Tuning
2595 @subsection Performance Tuning
2596
2597 For GNUnet, you probably want to set the option
2598
2599 @example
2600 innodb_flush_log_at_trx_commit = 0
2601 @end example
2602
2603 @noindent
2604 for a rather dramatic boost in MySQL performance. However, this reduces
2605 the "safety" of your database as with this options you may loose
2606 transactions during a power outage.
2607 While this is totally harmless for GNUnet, the option applies to all
2608 applications using MySQL. So you should set it if (and only if) GNUnet is
2609 the only application on your system using MySQL.
2610
2611 @node Setup for running Testcases
2612 @subsection Setup for running Testcases
2613
2614 If you want to run the testcases, you must create a second database
2615 "gnunetcheck" with the same username and password. This database will
2616 then be used for testing (@command{make check}).
2617
2618 @node Configuring the Postgres database
2619 @subsection Configuring the Postgres database
2620
2621 This text describes how to setup the Postgres database for GNUnet.
2622
2623 This Postgres plugin was developed for Postgres 8.3 but might work for
2624 earlier versions as well.
2625
2626 @node Reasons to use Postgres
2627 @subsection Reasons to use Postgres
2628
2629 @itemize @bullet
2630 @item Easier to setup than MySQL
2631 @item Real database
2632 @end itemize
2633
2634 @node Reasons not to use Postgres
2635 @subsection Reasons not to use Postgres
2636
2637 @itemize @bullet
2638 @item Quite slow
2639 @item Still some manual setup required
2640 @end itemize
2641
2642 @node Manual setup instructions
2643 @subsection Manual setup instructions
2644
2645 @itemize @bullet
2646 @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
2647 @code{DATABASE} to @code{postgres}.
2648 @item Access Postgres to create a user:
2649
2650 @table @asis
2651 @item with Postgres 8.x, use:
2652
2653 @example
2654 # su - postgres
2655 $ createuser
2656 @end example
2657
2658 @noindent
2659 and enter the name of the user running GNUnet for the role interactively.
2660 Then, when prompted, do not set it to superuser, allow the creation of
2661 databases, and do not allow the creation of new roles.
2662
2663 @item with Postgres 9.x, use:
2664
2665 @example
2666 # su - postgres
2667 $ createuser -d $GNUNET_USER
2668 @end example
2669
2670 @noindent
2671 where $GNUNET_USER is the name of the user running GNUnet.
2672
2673 @end table
2674
2675
2676 @item
2677 As that user (so typically as user "gnunet"), create a database (or two):
2678
2679 @example
2680 $ createdb gnunet
2681 # this way you can run "make check"
2682 $ createdb gnunetcheck
2683 @end example
2684
2685 @end itemize
2686
2687 Now you should be able to start @code{gnunet-arm}.
2688
2689 @node Testing the setup manually
2690 @subsection Testing the setup manually
2691
2692 You may want to try if the database connection works. First, again login
2693 as the user who will run @command{gnunet-arm}. Then use:
2694
2695 @example
2696 $ psql gnunet # or gnunetcheck
2697 gnunet=> \dt
2698 @end example
2699
2700 @noindent
2701 If, after you have started @command{gnunet-arm} at least once, you get
2702 a @code{gn090} table here, it probably works.
2703
2704 @node Configuring the datacache
2705 @subsection Configuring the datacache
2706 @c %**end of header
2707
2708 The datacache is what GNUnet uses for storing temporary data. This data is
2709 expected to be wiped completely each time GNUnet is restarted (or the
2710 system is rebooted).
2711
2712 You need to specify how many bytes GNUnet is allowed to use for the
2713 datacache using the @code{QUOTA} option in the section @code{[dhtcache]}.
2714 Furthermore, you need to specify which database backend should be used to
2715 store the data. Currently, you have the choice between
2716 sqLite, MySQL and Postgres.
2717
2718 @node Configuring the file-sharing service
2719 @subsection Configuring the file-sharing service
2720
2721 In order to use GNUnet for file-sharing, you first need to make sure
2722 that the file-sharing service is loaded.
2723 This is done by setting the @code{AUTOSTART} option in
2724 section @code{[fs]} to "YES". Alternatively, you can run
2725
2726 @example
2727 $ gnunet-arm -i fs
2728 @end example
2729
2730 @noindent
2731 to start the file-sharing service by hand.
2732
2733 Except for configuring the database and the datacache the only important
2734 option for file-sharing is content migration.
2735
2736 Content migration allows your peer to cache content from other peers as
2737 well as send out content stored on your system without explicit requests.
2738 This content replication has positive and negative impacts on both system
2739 performance and privacy.
2740
2741 FIXME: discuss the trade-offs. Here is some older text about it...
2742
2743 Setting this option to YES allows gnunetd to migrate data to the local
2744 machine. Setting this option to YES is highly recommended for efficiency.
2745 Its also the default. If you set this value to YES, GNUnet will store
2746 content on your machine that you cannot decrypt.
2747 While this may protect you from liability if the judge is sane, it may
2748 not (IANAL). If you put illegal content on your machine yourself, setting
2749 this option to YES will probably increase your chances to get away with it
2750 since you can plausibly deny that you inserted the content.
2751 Note that in either case, your anonymity would have to be broken first
2752 (which may be possible depending on the size of the GNUnet network and the
2753 strength of the adversary).
2754
2755 @node Configuring logging
2756 @subsection Configuring logging
2757
2758 Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options.
2759 Using @code{-L}, a log level can be specified. With log level
2760 @code{ERROR} only serious errors are logged.
2761 The default log level is @code{WARNING} which causes anything of
2762 concern to be logged.
2763 Log level @code{INFO} can be used to log anything that might be
2764 interesting information whereas
2765 @code{DEBUG} can be used by developers to log debugging messages
2766 (but you need to run @code{./configure} with
2767 @code{--enable-logging=verbose} to get them compiled).
2768 The @code{-l} option is used to specify the log file.
2769
2770 Since most GNUnet services are managed by @code{gnunet-arm}, using the
2771 @code{-l} or @code{-L} options directly is not possible.
2772 Instead, they can be specified using the @code{OPTIONS} configuration
2773 value in the respective section for the respective service.
2774 In order to enable logging globally without editing the @code{OPTIONS}
2775 values for each service, @command{gnunet-arm} supports a
2776 @code{GLOBAL_POSTFIX} option.
2777 The value specified here is given as an extra option to all services for
2778 which the configuration does contain a service-specific @code{OPTIONS}
2779 field.
2780
2781 @code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which
2782 is replaced by the name of the service that is being started.
2783 Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences
2784 starting with "$" anywhere in the string are expanded (according
2785 to options in @code{PATHS}); this expansion otherwise is
2786 only happening for filenames and then the "$" must be the
2787 first character in the option. Both of these restrictions do
2788 not apply to @code{GLOBAL_POSTFIX}.
2789 Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX}
2790 disables both of these features.
2791
2792 In summary, in order to get all services to log at level
2793 @code{INFO} to log-files called @code{SERVICENAME-logs}, the
2794 following global prefix should be used:
2795
2796 @example
2797 GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO
2798 @end example
2799
2800 @node Configuring the transport service and plugins
2801 @subsection Configuring the transport service and plugins
2802
2803 The transport service in GNUnet is responsible to maintain basic
2804 connectivity to other peers.
2805 Besides initiating and keeping connections alive it is also responsible
2806 for address validation.
2807
2808 The GNUnet transport supports more than one transport protocol.
2809 These protocols are configured together with the transport service.
2810
2811 The configuration section for the transport service itself is quite
2812 similar to all the other services
2813
2814 @example
2815 AUTOSTART = YES
2816 @@UNIXONLY@@ PORT = 2091
2817 HOSTNAME = localhost
2818 HOME = $SERVICEHOME
2819 CONFIG = $DEFAULTCONFIG
2820 BINARY = gnunet-service-transport
2821 #PREFIX = valgrind
2822 NEIGHBOUR_LIMIT = 50
2823 ACCEPT_FROM = 127.0.0.1;
2824 ACCEPT_FROM6 = ::1;
2825 PLUGINS = tcp udp
2826 UNIXPATH = /tmp/gnunet-service-transport.sock
2827 @end example
2828
2829 Different are the settings for the plugins to load @code{PLUGINS}.
2830 The first setting specifies which transport plugins to load.
2831
2832 @itemize @bullet
2833 @item transport-unix
2834 A plugin for local only communication with UNIX domain sockets. Used for
2835 testing and available on unix systems only. Just set the port
2836
2837 @example
2838 [transport-unix]
2839 PORT = 22086
2840 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2841 @end example
2842
2843 @item transport-tcp
2844 A plugin for communication with TCP. Set port to 0 for client mode with
2845 outbound only connections
2846
2847 @example
2848 [transport-tcp]
2849 # Use 0 to ONLY advertise as a peer behind NAT (no port binding)
2850 PORT = 2086
2851 ADVERTISED_PORT = 2086
2852 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2853 # Maximum number of open TCP connections allowed
2854 MAX_CONNECTIONS = 128
2855 @end example
2856
2857 @item transport-udp
2858 A plugin for communication with UDP. Supports peer discovery using
2859 broadcasts.
2860
2861 @example
2862 [transport-udp]
2863 PORT = 2086
2864 BROADCAST = YES
2865 BROADCAST_INTERVAL = 30 s
2866 MAX_BPS = 1000000
2867 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2868 @end example
2869
2870 @item transport-http
2871 HTTP and HTTPS support is split in two part: a client plugin initiating
2872 outbound connections and a server part accepting connections from the
2873 client. The client plugin just takes the maximum number of connections as
2874 an argument.
2875
2876 @example
2877 [transport-http_client]
2878 MAX_CONNECTIONS = 128
2879 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2880 @end example
2881
2882 @example
2883 [transport-https_client]
2884 MAX_CONNECTIONS = 128
2885 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2886 @end example
2887
2888 @noindent
2889 The server has a port configured and the maximum nunber of connections.
2890 The HTTPS part has two files with the certificate key and the certificate
2891 file.
2892
2893 The server plugin supports reverse proxies, so a external hostname can be
2894 set using the @code{EXTERNAL_HOSTNAME} setting.
2895 The webserver under this address should forward the request to the peer
2896 and the configure port.
2897
2898 @example
2899 [transport-http_server]
2900 EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet
2901 PORT = 1080
2902 MAX_CONNECTIONS = 128
2903 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2904 @end example
2905
2906 @example
2907 [transport-https_server]
2908 PORT = 4433
2909 CRYPTO_INIT = NORMAL
2910 KEY_FILE = https.key
2911 CERT_FILE = https.cert
2912 MAX_CONNECTIONS = 128
2913 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2914 @end example
2915
2916 @item transport-wlan
2917
2918 The next section describes how to setup the WLAN plugin,
2919 so here only the settings. Just specify the interface to use:
2920
2921 @example
2922 [transport-wlan]
2923 # Name of the interface in monitor mode (typically monX)
2924 INTERFACE = mon0
2925 # Real hardware, no testing
2926 TESTMODE = 0
2927 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2928 @end example
2929 @end itemize
2930
2931 @node Configuring the wlan transport plugin
2932 @subsection Configuring the wlan transport plugin
2933
2934 The wlan transport plugin enables GNUnet to send and to receive data on a
2935 wlan interface.
2936 It has not to be connected to a wlan network as long as sender and
2937 receiver are on the same channel. This enables you to get connection to
2938 GNUnet where no internet access is possible, for example during
2939 catastrophes or when censorship cuts you off from the internet.
2940
2941
2942 @menu
2943 * Requirements for the WLAN plugin::
2944 * Configuration::
2945 * Before starting GNUnet::
2946 * Limitations and known bugs::
2947 @end menu
2948
2949
2950 @node Requirements for the WLAN plugin
2951 @subsubsection Requirements for the WLAN plugin
2952
2953 @itemize @bullet
2954
2955 @item wlan network card with monitor support and packet injection
2956 (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org})
2957
2958 @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with
2959 2.6.35 and 2.6.38
2960
2961 @item Wlantools to create the a monitor interface, tested with airmon-ng
2962 of the aircrack-ng package
2963 @end itemize
2964
2965 @node Configuration
2966 @subsubsection Configuration
2967
2968 There are the following options for the wlan plugin (they should be like
2969 this in your default config file, you only need to adjust them if the
2970 values are incorrect for your system)
2971
2972 @example
2973 # section for the wlan transport plugin
2974 [transport-wlan]
2975 # interface to use, more information in the
2976 # "Before starting GNUnet" section of the handbook.
2977 INTERFACE = mon0
2978 # testmode for developers:
2979 # 0 use wlan interface,
2980 #1 or 2 use loopback driver for tests 1 = server, 2 = client
2981 TESTMODE = 0
2982 @end example
2983
2984 @node Before starting GNUnet
2985 @subsubsection Before starting GNUnet
2986
2987 Before starting GNUnet, you have to make sure that your wlan interface is
2988 in monitor mode.
2989 One way to put the wlan interface into monitor mode (if your interface
2990 name is wlan0) is by executing:
2991
2992 @example
2993 sudo airmon-ng start wlan0
2994 @end example
2995
2996 @noindent
2997 Here is an example what the result should look like:
2998
2999 @example
3000 Interface Chipset Driver
3001 wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]
3002 (monitor mode enabled on mon0)
3003 @end example
3004
3005 @noindent
3006 The monitor interface is mon0 is the one that you have to put into the
3007 configuration file.
3008
3009 @node Limitations and known bugs
3010 @subsubsection Limitations and known bugs
3011
3012 Wlan speed is at the maximum of 1 Mbit/s because support for choosing the
3013 wlan speed with packet injection was removed in newer kernels.
3014 Please pester the kernel developers about fixing this.
3015
3016 The interface channel depends on the wlan network that the card is
3017 connected to. If no connection has been made since the start of the
3018 computer, it is usually the first channel of the card.
3019 Peers will only find each other and communicate if they are on the same
3020 channel. Channels must be set manually, i.e. using:
3021
3022 @example
3023 iwconfig wlan0 channel 1
3024 @end example
3025
3026 @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx
3027 @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
3028
3029 The HTTP plugin supports data transfer using reverse proxies. A reverse
3030 proxy forwards the HTTP request he receives with a certain URL to another
3031 webserver, here a GNUnet peer.
3032
3033 So if you have a running Apache or nginx webserver you can configure it to
3034 be a GNUnet reverse proxy. Especially if you have a well-known webiste
3035 this improves censorship resistance since it looks as normal surfing
3036 behaviour.
3037
3038 To do so, you have to do two things:
3039
3040 @itemize @bullet
3041 @item Configure your webserver to forward the GNUnet HTTP traffic
3042 @item Configure your GNUnet peer to announce the respective address
3043 @end itemize
3044
3045 As an example we want to use GNUnet peer running:
3046
3047 @itemize @bullet
3048
3049 @item HTTP server plugin on @code{gnunet.foo.org:1080}
3050
3051 @item HTTPS server plugin on @code{gnunet.foo.org:4433}
3052
3053 @item A apache or nginx webserver on
3054 @uref{http://www.foo.org/, http://www.foo.org:80/}
3055
3056 @item A apache or nginx webserver on https://www.foo.org:443/
3057 @end itemize
3058
3059 And we want the webserver to accept GNUnet traffic under
3060 @code{http://www.foo.org/bar/}. The required steps are described here:
3061
3062 @menu
3063 * Reverse Proxy - Configure your Apache2 HTTP webserver::
3064 * Reverse Proxy - Configure your Apache2 HTTPS webserver::
3065 * Reverse Proxy - Configure your nginx HTTPS webserver::
3066 * Reverse Proxy - Configure your nginx HTTP webserver::
3067 * Reverse Proxy - Configure your GNUnet peer::
3068 @end menu
3069
3070 @node Reverse Proxy - Configure your Apache2 HTTP webserver
3071 @subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver
3072
3073 First of all you need mod_proxy installed.
3074
3075 Edit your webserver configuration. Edit
3076 @code{/etc/apache2/apache2.conf} or the site-specific configuration file.
3077
3078 In the respective @code{server config},@code{virtual host} or
3079 @code{directory} section add the following lines:
3080
3081 @example
3082 ProxyTimeout 300
3083 ProxyRequests Off
3084 <Location /bar/ >
3085 ProxyPass http://gnunet.foo.org:1080/
3086 ProxyPassReverse http://gnunet.foo.org:1080/
3087 </Location>
3088 @end example
3089
3090 @node Reverse Proxy - Configure your Apache2 HTTPS webserver
3091 @subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver
3092
3093 We assume that you already have an HTTPS server running, if not please
3094 check how to configure a HTTPS host. An uncomplicated to use example
3095 is the example configuration file for Apache2/HTTPD provided in
3096 @file{apache2/sites-available/default-ssl}.
3097
3098 In the respective HTTPS @code{server config},@code{virtual host} or
3099 @code{directory} section add the following lines:
3100
3101 @example
3102 SSLProxyEngine On
3103 ProxyTimeout 300
3104 ProxyRequests Off
3105 <Location /bar/ >
3106 ProxyPass https://gnunet.foo.org:4433/
3107 ProxyPassReverse https://gnunet.foo.org:4433/
3108 </Location>
3109 @end example
3110
3111 @noindent
3112 More information about the apache mod_proxy configuration can be found
3113 in the Apache documentation@footnote{@uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass}}
3114
3115 @node Reverse Proxy - Configure your nginx HTTPS webserver
3116 @subsubsection Reverse Proxy - Configure your nginx HTTPS webserver
3117
3118 Since nginx does not support chunked encoding, you first of all have to
3119 install the @code{chunkin} module@footnote{@uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}}
3120
3121 To enable chunkin add:
3122
3123 @example
3124 chunkin on;
3125 error_page 411 = @@my_411_error;
3126 location @@my_411_error @{
3127 chunkin_resume;
3128 @}
3129 @end example
3130
3131 @noindent
3132 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
3133 the site-specific configuration file.
3134
3135 In the @code{server} section add:
3136
3137 @example
3138 location /bar/ @{
3139 proxy_pass http://gnunet.foo.org:1080/;
3140 proxy_buffering off;
3141 proxy_connect_timeout 5; # more than http_server
3142 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout
3143 proxy_http_version 1.1; # 1.0 default
3144 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;
3145 @}
3146 @end example
3147
3148 @node Reverse Proxy - Configure your nginx HTTP webserver
3149 @subsubsection Reverse Proxy - Configure your nginx HTTP webserver
3150
3151 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
3152 the site-specific configuration file.
3153
3154 In the @code{server} section add:
3155
3156 @example
3157 ssl_session_timeout 6m;
3158 location /bar/
3159 @{
3160 proxy_pass https://gnunet.foo.org:4433/;
3161 proxy_buffering off;
3162 proxy_connect_timeout 5; # more than http_server
3163 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout
3164 proxy_http_version 1.1; # 1.0 default
3165 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;
3166 @}
3167 @end example
3168
3169 @node Reverse Proxy - Configure your GNUnet peer
3170 @subsubsection Reverse Proxy - Configure your GNUnet peer
3171
3172 To have your GNUnet peer announce the address, you have to specify the
3173 @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]}
3174 section:
3175
3176 @example
3177 [transport-http_server]
3178 EXTERNAL_HOSTNAME = http://www.foo.org/bar/
3179 @end example
3180
3181 @noindent
3182 and/or @code{[transport-https_server]} section:
3183
3184 @example
3185 [transport-https_server]
3186 EXTERNAL_HOSTNAME = https://www.foo.org/bar/
3187 @end example
3188
3189 @noindent
3190 Now restart your webserver and your peer...
3191
3192 @node Blacklisting peers
3193 @subsection Blacklisting peers
3194
3195 Transport service supports to deny connecting to a specific peer of to a
3196 specific peer with a specific transport plugin using te blacklisting
3197 component of transport service. With@ blacklisting it is possible to deny
3198 connections to specific peers of@ to use a specific plugin to a specific
3199 peer. Peers can be blacklisted using@ the configuration or a blacklist
3200 client can be asked.
3201
3202 To blacklist peers using the configuration you have to add a section to
3203 your configuration containing the peer id of the peer to blacklist and
3204 the plugin@ if required.
3205
3206 Examples:
3207
3208 To blacklist connections to P565... on peer AG2P... using tcp add:
3209
3210 @c FIXME: This is too long and produces errors in the pdf.
3211 @example
3212 [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
3213 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp
3214 @end example
3215
3216 To blacklist connections to P565... on peer AG2P... using all plugins add:
3217
3218 @example
3219 [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
3220 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =
3221 @end example
3222
3223 You can also add a blacklist client usign the blacklist API. On a
3224 blacklist check, blacklisting first checks internally if the peer is
3225 blacklisted and if not, it asks the blacklisting clients. Clients are
3226 asked if it is OK to connect to a peer ID, the plugin is omitted.
3227
3228 On blacklist check for (peer, plugin)
3229 @itemize @bullet
3230 @item Do we have a local blacklist entry for this peer and this plugin?@
3231 @item YES: disallow connection@
3232 @item Do we have a local blacklist entry for this peer and all plugins?@
3233 @item YES: disallow connection@
3234 @item Does one of the clients disallow?@
3235 @item YES: disallow connection
3236 @end itemize
3237
3238 @node Configuration of the HTTP and HTTPS transport plugins
3239 @subsection Configuration of the HTTP and HTTPS transport plugins
3240
3241 The client parts of the http and https transport plugins can be configured
3242 to use a proxy to connect to the hostlist server. This functionality can
3243 be configured in the configuration file directly or using the
3244 gnunet-setup tool.
3245
3246 Both the HTTP and HTTPS clients support the following proxy types at
3247 the moment:
3248
3249 @itemize @bullet
3250 @item HTTP 1.1 proxy
3251 @item SOCKS 4/4a/5/5 with hostname
3252 @end itemize
3253
3254 In addition authentication at the proxy with username and password can be
3255 configured.
3256
3257 To configure proxy support for the clients in the gnunet-setup tool,
3258 select the "transport" tab and activate the respective plugin. Now you
3259 can select the appropriate proxy type. The hostname or IP address
3260 (including port if required) has to be entered in the "Proxy hostname"
3261 textbox. If required, enter username and password in the "Proxy username"
3262 and "Proxy password" boxes. Be aware that these information will be stored
3263 in the configuration in plain text.
3264
3265 To configure these options directly in the configuration, you can
3266 configure the following settings in the @code{[transport-http_client]}
3267 and @code{[transport-https_client]} section of the configuration:
3268
3269 @example
3270 # Type of proxy server,
3271 # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME
3272 # Default: HTTP
3273 # PROXY_TYPE = HTTP
3274
3275 # Hostname or IP of proxy server
3276 # PROXY =
3277 # User name for proxy server
3278 # PROXY_USERNAME =
3279 # User password for proxy server
3280 # PROXY_PASSWORD =
3281 @end example
3282
3283 @node Configuring the GNU Name System
3284 @subsection Configuring the GNU Name System
3285
3286 @menu
3287 * Configuring system-wide DNS interception::
3288 * Configuring the GNS nsswitch plugin::
3289 * Configuring GNS on W32::
3290 * GNS Proxy Setup::
3291 * Setup of the GNS CA::
3292 * Testing the GNS setup::
3293 @end menu
3294
3295
3296 @node Configuring system-wide DNS interception
3297 @subsubsection Configuring system-wide DNS interception
3298
3299 Before you install GNUnet, make sure you have a user and group 'gnunet'
3300 as well as an empty group 'gnunetdns'.
3301
3302 When using GNUnet with system-wide DNS interception, it is absolutely
3303 necessary for all GNUnet service processes to be started by
3304 @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be
3305 sure to run @code{make install} as root (or use the @code{sudo} option to
3306 configure) to grant GNUnet sufficient privileges.
3307
3308 With this setup, all that is required for enabling system-wide DNS
3309 interception is for some GNUnet component (VPN or GNS) to request it.
3310 The @code{gnunet-service-dns} will then start helper programs that will
3311 make the necessary changes to your firewall (@code{iptables}) rules.
3312
3313 Note that this will NOT work if your system sends out DNS traffic to a
3314 link-local IPv6 address, as in this case GNUnet can intercept the traffic,
3315 but not inject the responses from the link-local IPv6 address. Hence you
3316 cannot use system-wide DNS interception in conjunction with link-local
3317 IPv6-based DNS servers. If such a DNS server is used, it will bypass
3318 GNUnet's DNS traffic interception.
3319
3320 Using the GNU Name System (GNS) requires two different configuration
3321 steps.
3322 First of all, GNS needs to be integrated with the operating system. Most
3323 of this section is about the operating system level integration.
3324
3325 The remainder of this chapter will detail the various methods for
3326 configuring the use of GNS with your operating system.
3327
3328 At this point in time you have different options depending on your OS:
3329
3330 @table @asis
3331
3332 @item Use the gnunet-gns-proxy This approach works for all operating
3333 systems and is likely the easiest. However, it enables GNS only for
3334 browsers, not for other applications that might be using DNS, such as SSH.
3335 Still, using the proxy is required for using HTTP with GNS and is thus
3336 recommended for all users. To do this, you simply have to run the
3337 @code{gnunet-gns-proxy-setup-ca} script as the user who will run the
3338 browser (this will create a GNS certificate authority (CA) on your system
3339 and import its key into your browser), then start @code{gnunet-gns-proxy}
3340 and inform your browser to use the Socks5 proxy which
3341 @code{gnunet-gns-proxy} makes available by default on port 7777.
3342 @item Use a nsswitch plugin (recommended on GNU systems)
3343 This approach has the advantage of offering fully personalized resolution
3344 even on multi-user systems. A potential disadvantage is that some
3345 applications might be able to bypass GNS.
3346 @item Use a W32 resolver plugin (recommended on W32)
3347 This is currently the only option on W32 systems.
3348 @item Use system-wide DNS packet interception
3349 This approach is recommended for the GNUnet VPN. It can be used to handle
3350 GNS at the same time; however, if you only use this method, you will only
3351 get one root zone per machine (not so great for multi-user systems).
3352 @end table
3353
3354 You can combine system-wide DNS packet interception with the nsswitch
3355 plugin.
3356 The setup of the system-wide DNS interception is described here. All of
3357 the other GNS-specific configuration steps are described in the following
3358 sections.
3359
3360 @node Configuring the GNS nsswitch plugin
3361 @subsubsection Configuring the GNS nsswitch plugin
3362
3363 The Name Service Switch (NSS) is a facility in Unix-like operating systems
3364 @footnote{More accurate: NSS is a functionality of the GNU C Library}
3365 that provides a variety of sources for common configuration databases and
3366 name resolution mechanisms.
3367 A superuser (system administrator) usually configures the
3368 operating system's name services using the file
3369 @file{/etc/nsswitch.conf}.
3370
3371 GNS provides a NSS plugin to integrate GNS name resolution with the
3372 operating system's name resolution process.
3373 To use the GNS NSS plugin you have to either
3374
3375 @itemize @bullet
3376 @item install GNUnet as root or
3377 @item compile GNUnet with the @code{--with-sudo=yes} switch.
3378 @end itemize
3379
3380 Name resolution is controlled by the @emph{hosts} section in the NSS
3381 configuration. By default this section first performs a lookup in the
3382 @file{/etc/hosts} file and then in DNS.
3383 The nsswitch file should contain a line similar to:
3384
3385 @example
3386 hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4
3387 @end example
3388
3389 @noindent
3390 Here the GNS NSS plugin can be added to perform a GNS lookup before
3391 performing a DNS lookup.
3392 The GNS NSS plugin has to be added to the "hosts" section in
3393 @file{/etc/nsswitch.conf} file before DNS related plugins:
3394
3395 @example
3396 ...
3397 hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4
3398 ...
3399 @end example
3400
3401 @noindent
3402 The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not
3403 found in GNS it will not be queried in DNS.
3404
3405 @node Configuring GNS on W32
3406 @subsubsection Configuring GNS on W32
3407
3408 This document is a guide to configuring GNU Name System on W32-compatible
3409 platforms.
3410
3411 After GNUnet is installed, run the w32nsp-install tool:
3412
3413 @example
3414 w32nsp-install.exe libw32nsp-0.dll
3415 @end example
3416
3417 @noindent
3418 ('0' is the library version of W32 NSP; it might increase in the future,
3419 change the invocation accordingly).
3420
3421 This will install GNS namespace provider into the system and allow other
3422 applications to resolve names that end in '@strong{gnu}'
3423 and '@strong{zkey}'. Note that namespace provider requires
3424 gnunet-gns-helper-service-w32 to be running, as well as gns service
3425 itself (and its usual dependencies).
3426
3427 Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353},
3428 and this is where gnunet-gns-helper-service-w32 should be listening to
3429 (and is configured to listen to by default).
3430
3431 To uninstall the provider, run:
3432
3433 @example
3434 w32nsp-uninstall.exe
3435 @end example
3436
3437 @noindent
3438 (uses provider GUID to uninstall it, does not need a dll name).
3439
3440 Note that while MSDN claims that other applications will only be able to
3441 use the new namespace provider after re-starting, in reality they might
3442 stat to use it without that. Conversely, they might stop using the
3443 provider after it's been uninstalled, even if they were not re-started.
3444 W32 will not permit namespace provider library to be deleted or
3445 overwritten while the provider is installed, and while there is at least
3446 one process still using it (even after it was uninstalled).
3447
3448 @node GNS Proxy Setup
3449 @subsubsection GNS Proxy Setup
3450
3451 When using the GNU Name System (GNS) to browse the WWW, there are several
3452 issues that can be solved by adding the GNS Proxy to your setup:
3453
3454 @itemize @bullet
3455
3456 @item If the target website does not support GNS, it might assume that it
3457 is operating under some name in the legacy DNS system (such as
3458 example.com). It may then attempt to set cookies for that domain, and the
3459 web server might expect a @code{Host: example.com} header in the request
3460 from your browser.
3461 However, your browser might be using @code{example.gnu} for the
3462 @code{Host} header and might only accept (and send) cookies for
3463 @code{example.gnu}. The GNS Proxy will perform the necessary translations
3464 of the hostnames for cookies and HTTP headers (using the LEHO record for
3465 the target domain as the desired substitute).
3466
3467 @item If using HTTPS, the target site might include an SSL certificate
3468 which is either only valid for the LEHO domain or might match a TLSA
3469 record in GNS. However, your browser would expect a valid certificate for
3470 @code{example.gnu}, not for some legacy domain name. The proxy will
3471 validate the certificate (either against LEHO or TLSA) and then
3472 on-the-fly produce a valid certificate for the exchange, signed by your
3473 own CA. Assuming you installed the CA of your proxy in your browser's
3474 certificate authority list, your browser will then trust the
3475 HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy.
3476
3477 @item Finally, the proxy will in the future indicate to the server that it
3478 speaks GNS, which will enable server operators to deliver GNS-enabled web
3479 sites to your browser (and continue to deliver legacy links to legacy
3480 browsers)
3481 @end itemize
3482
3483 @node Setup of the GNS CA
3484 @subsubsection Setup of the GNS CA
3485
3486 First you need to create a CA certificate that the proxy can use.
3487 To do so use the provided script gnunet-gns-proxy-ca:
3488
3489 @example
3490 $ gnunet-gns-proxy-setup-ca
3491 @end example
3492
3493 @noindent
3494 This will create a personal certification authority for you and add this
3495 authority to the firefox and chrome database. The proxy will use the this
3496 CA certificate to generate @code{*.gnu} client certificates on the fly.
3497
3498 Note that the proxy uses libcurl. Make sure your version of libcurl uses
3499 GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled
3500 against OpenSSL.
3501
3502 You can check the configuration your libcurl was build with by
3503 running:
3504
3505 @example
3506 curl --version
3507 @end example
3508
3509 the output will look like this (without the linebreaks):
3510
3511 @example
3512 gnurl --version
3513 curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \
3514 GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4
3515 Release-Date: 2017-10-08
3516 Protocols: http https
3517 Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \
3518 TLS-SRP UnixSockets HTTPS-proxy
3519 @end example
3520
3521 @node Testing the GNS setup
3522 @subsubsection Testing the GNS setup
3523
3524 Now for testing purposes we can create some records in our zone to test
3525 the SSL functionality of the proxy:
3526
3527 @example
3528 $ gnunet-identity -C test
3529 $ gnunet-namestore -a -e "1 d" -n "homepage" \
3530   -t A -V 131.159.74.67 -z test
3531 $ gnunet-namestore -a -e "1 d" -n "homepage" \
3532   -t LEHO -V "gnunet.org" -z test
3533 @end example
3534
3535 @noindent
3536 At this point we can start the proxy. Simply execute
3537
3538 @example
3539 $ gnunet-gns-proxy
3540 @end example
3541
3542 @noindent
3543 Configure your browser to use this SOCKSv5 proxy on port 7777 and visit
3544 this link.
3545 If you use @command{Firefox} (or one of its deriviates/forks such as
3546 Icecat) you also have to go to @code{about:config} and set the key
3547 @code{network.proxy.socks_remote_dns} to @code{true}.
3548
3549 When you visit @code{https://homepage.test/}, you should get to the
3550 @code{https://gnunet.org/} frontpage and the browser (with the correctly
3551 configured proxy) should give you a valid SSL certificate for
3552 @code{homepage.gnu} and no warnings. It should look like this:
3553
3554 @c FIXME: Image does not exist, create it or save it from Drupal?
3555 @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser}
3556
3557
3558 @node Configuring the GNUnet VPN
3559 @subsection Configuring the GNUnet VPN
3560
3561 @menu
3562 * IPv4 address for interface::
3563 * IPv6 address for interface::
3564 * Configuring the GNUnet VPN DNS::
3565 * Configuring the GNUnet VPN Exit Service::
3566 * IP Address of external DNS resolver::
3567 * IPv4 address for Exit interface::
3568 * IPv6 address for Exit interface::
3569 @end menu
3570
3571 Before configuring the GNUnet VPN, please make sure that system-wide DNS
3572 interception is configured properly as described in the section on the
3573 GNUnet DNS setup. @pxref{Configuring the GNU Name System},
3574 if you haven't done so already.
3575
3576 The default options for the GNUnet VPN are usually sufficient to use
3577 GNUnet as a Layer 2 for your Internet connection.
3578 However, what you always have to specify is which IP protocol you want
3579 to tunnel: IPv4, IPv6 or both.
3580 Furthermore, if you tunnel both, you most likely should also tunnel
3581 all of your DNS requests.
3582 You theoretically can tunnel "only" your DNS traffic, but that usually
3583 makes little sense.
3584
3585 The other options as shown on the gnunet-setup tool are:
3586
3587 @node IPv4 address for interface
3588 @subsubsection IPv4 address for interface
3589
3590 This is the IPv4 address the VPN interface will get. You should pick an
3591 'private' IPv4 network that is not yet in use for you system. For example,
3592 if you use @code{10.0.0.1/255.255.0.0} already, you might use
3593 @code{10.1.0.1/255.255.0.0}.
3594 If you use @code{10.0.0.1/255.0.0.0} already, then you might use
3595 @code{192.168.0.1/255.255.0.0}.
3596 If your system is not in a private IP-network, using any of the above will
3597 work fine.
3598 You should try to make the mask of the address big enough
3599 (@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more
3600 mappings of remote IP Addresses into this range.
3601 However, even a @code{255.255.255.0} mask will suffice for most users.
3602
3603 @node IPv6 address for interface
3604 @subsubsection IPv6 address for interface
3605
3606 The IPv6 address the VPN interface will get. Here you can specify any
3607 non-link-local address (the address should not begin with @code{fe80:}).
3608 A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are
3609 currently not using would be a good choice.
3610
3611 @node Configuring the GNUnet VPN DNS
3612 @subsubsection Configuring the GNUnet VPN DNS
3613
3614 To resolve names for remote nodes, activate the DNS exit option.
3615
3616 @node Configuring the GNUnet VPN Exit Service
3617 @subsubsection Configuring the GNUnet VPN Exit Service
3618
3619 If you want to allow other users to share your Internet connection (yes,
3620 this may be dangerous, just as running a Tor exit node) or want to
3621 provide access to services on your host (this should be less dangerous,
3622 as long as those services are secure), you have to enable the GNUnet exit
3623 daemon.
3624
3625 You then get to specify which exit functions you want to provide. By
3626 enabling the exit daemon, you will always automatically provide exit
3627 functions for manually configured local services (this component of the
3628 system is under
3629 development and not documented further at this time). As for those
3630 services you explicitly specify the target IP address and port, there is
3631 no significant security risk in doing so.
3632
3633 Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet.
3634 Being a DNS exit is usually pretty harmless. However, enabling IPv4 or
3635 IPv6-exit without further precautions may enable adversaries to access
3636 your local network, send spam, attack other systems from your Internet
3637 connection and to other mischief that will appear to come from your
3638 machine. This may or may not get you into legal trouble.
3639 If you want to allow IPv4 or IPv6-exit functionality, you should strongly
3640 consider adding additional firewall rules manually to protect your local
3641 network and to restrict outgoing TCP traffic (i.e. by not allowing access
3642 to port 25). While we plan to improve exit-filtering in the future,
3643 you're currently on your own here.
3644 Essentially, be prepared for any kind of IP-traffic to exit the respective
3645 TUN interface (and GNUnet will enable IP-forwarding and NAT for the
3646 interface automatically).
3647
3648 Additional configuration options of the exit as shown by the gnunet-setup
3649 tool are:
3650
3651 @node IP Address of external DNS resolver
3652 @subsubsection IP Address of external DNS resolver
3653
3654 If DNS traffic is to exit your machine, it will be send to this DNS
3655 resolver. You can specify an IPv4 or IPv6 address.
3656
3657 @node IPv4 address for Exit interface
3658 @subsubsection IPv4 address for Exit interface
3659
3660 This is the IPv4 address the Interface will get. Make the mask of the
3661 address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more
3662 mappings of IP addresses into this range. As for the VPN interface, any
3663 unused, private IPv4 address range will do.
3664
3665 @node IPv6 address for Exit interface
3666 @subsubsection IPv6 address for Exit interface
3667
3668 The public IPv6 address the interface will get. If your kernel is not a
3669 very recent kernel and you are willing to manually enable IPv6-NAT, the
3670 IPv6 address you specify here must be a globally routed IPv6 address of
3671 your host.
3672
3673 Suppose your host has the address @code{2001:4ca0::1234/64}, then
3674 using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits,
3675 then change at least one bit in the range before the bitmask, in the
3676 example above we changed bit 111 from 0 to 1).
3677
3678 You may also have to configure your router to route traffic for the entire
3679 subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this
3680 should be automatic with IPv6, but obviously anything can be
3681 disabled).
3682
3683 @node Bandwidth Configuration
3684 @subsection Bandwidth Configuration
3685
3686 You can specify how many bandwidth GNUnet is allowed to use to receive
3687 and send data. This is important for users with limited bandwidth or
3688 traffic volume.
3689
3690 @node Configuring NAT
3691 @subsection Configuring NAT
3692
3693 Most hosts today do not have a normal global IP address but instead are
3694 behind a router performing Network Address Translation (NAT) which assigns
3695 each host in the local network a private IP address.
3696 As a result, these machines cannot trivially receive inbound connections
3697 from the Internet. GNUnet supports NAT traversal to enable these machines
3698 to receive incoming connections from other peers despite their
3699 limitations.
3700
3701 In an ideal world, you can press the "Attempt automatic configuration"
3702 button in gnunet-setup to automatically configure your peer correctly.
3703 Alternatively, your distribution might have already triggered this
3704 automatic configuration during the installation process.
3705 However, automatic configuration can fail to determine the optimal
3706 settings, resulting in your peer either not receiving as many connections
3707 as possible, or in the worst case it not connecting to the network at all.
3708
3709 To manually configure the peer, you need to know a few things about your
3710 network setup. First, determine if you are behind a NAT in the first
3711 place.
3712 This is always the case if your IP address starts with "10.*" or
3713 "192.168.*". Next, if you have control over your NAT router, you may
3714 choose to manually configure it to allow GNUnet traffic to your host.
3715 If you have configured your NAT to forward traffic on ports 2086 (and
3716 possibly 1080) to your host, you can check the "NAT ports have been opened
3717 manually" option, which corresponds to the "PUNCHED_NAT" option in the
3718 configuration file. If you did not punch your NAT box, it may still be
3719 configured to support UPnP, which allows GNUnet to automatically
3720 configure it. In that case, you need to install the "upnpc" command,
3721 enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal
3722 via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the
3723 configuration file).
3724
3725 Some NAT boxes can be traversed using the autonomous NAT traversal method.
3726 This requires certain GNUnet components to be installed with "SUID"
3727 prividledges on your system (so if you're installing on a system you do
3728 not have administrative rights to, this will not work).
3729 If you installed as 'root', you can enable autonomous NAT traversal by
3730 checking the "Enable NAT traversal using ICMP method".
3731 The ICMP method requires a way to determine your NAT's external (global)
3732 IP address. This can be done using either UPnP, DynDNS, or by manual
3733 configuration. If you have a DynDNS name or know your external IP address,
3734 you should enter that name under "External (public) IPv4 address" (which
3735 corresponds to the "EXTERNAL_ADDRESS" option in the configuration file).
3736 If you leave the option empty, GNUnet will try to determine your external
3737 IP address automatically (which may fail, in which case autonomous
3738 NAT traversal will then not work).
3739
3740 Finally, if you yourself are not behind NAT but want to be able to
3741 connect to NATed peers using autonomous NAT traversal, you need to check
3742 the "Enable connecting to NATed peers using ICMP method" box.
3743
3744
3745 @node Peer configuration for distributions
3746 @subsection Peer configuration for distributions
3747
3748 The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be
3749 manually set to "/var/lib/gnunet/data/" as the default
3750 "~/.local/share/gnunet/" is probably not that appropriate in this case.
3751 Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to
3752 "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a
3753 distribution decide to override system defaults, all of these changes
3754 should be done in a custom @file{/etc/gnunet.conf} and not in the files
3755 in the @file{config.d/} directory.
3756
3757 Given the proposed access permissions, the "gnunet-setup" tool must be
3758 run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it
3759 modifies the system configuration). As always, gnunet-setup should be run
3760 after the GNUnet peer was stopped using "gnunet-arm -e". Distributions
3761 might want to include a wrapper for gnunet-setup that allows the
3762 desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account
3763 and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
3764 sequence.
3765
3766 @node How to start and stop a GNUnet peer
3767 @section How to start and stop a GNUnet peer
3768
3769 This section describes how to start a GNUnet peer. It assumes that you
3770 have already compiled and installed GNUnet and its' dependencies.
3771 Before you start a GNUnet peer, you may want to create a configuration
3772 file using gnunet-setup (but you do not have to).
3773 Sane defaults should exist in your
3774 @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice
3775 you could simply start without any configuration. If you want to
3776 configure your peer later, you need to stop it before invoking the
3777 @code{gnunet-setup} tool to customize further and to test your
3778 configuration (@code{gnunet-setup} has build-in test functions).
3779
3780 The most important option you might have to still set by hand is in
3781 [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where
3782 GNUnet should store its data.
3783 It defaults to @code{$HOME/}, which again should work for most users.
3784 Make sure that the directory specified as GNUNET_HOME is writable to
3785 the user that you will use to run GNUnet (note that you can run frontends
3786 using other users, GNUNET_HOME must only be accessible to the user used to
3787 run the background processes).
3788
3789 You will also need to make one central decision: should all of GNUnet be
3790 run under your normal UID, or do you want distinguish between system-wide
3791 (user-independent) GNUnet services and personal GNUnet services. The
3792 multi-user setup is slightly more complicated, but also more secure and
3793 generally recommended.
3794
3795 @menu
3796 * The Single-User Setup::
3797 * The Multi-User Setup::
3798 * Killing GNUnet services::
3799 * Access Control for GNUnet::
3800 @end menu
3801
3802 @node The Single-User Setup
3803 @subsection The Single-User Setup
3804
3805 For the single-user setup, you do not need to do anything special and can
3806 just start the GNUnet background processes using @code{gnunet-arm}.
3807 By default, GNUnet looks in @file{~/.config/gnunet.conf} for a
3808 configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@
3809 @code{$XDG_CONFIG_HOME} is defined). If your configuration lives
3810 elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet
3811 commands.
3812
3813 Assuming the configuration file is called @file{~/.config/gnunet.conf},
3814 you start your peer using the @code{gnunet-arm} command (say as user
3815 @code{gnunet}) using:
3816
3817 @example
3818 gnunet-arm -c ~/.config/gnunet.conf -s
3819 @end example
3820
3821 @noindent
3822 The "-s" option here is for "start". The command should return almost
3823 instantly. If you want to stop GNUnet, you can use:
3824
3825 @example
3826 gnunet-arm -c ~/.config/gnunet.conf -e
3827 @end example
3828
3829 @noindent
3830 The "-e" option here is for "end".
3831
3832 Note that this will only start the basic peer, no actual applications
3833 will be available.
3834 If you want to start the file-sharing service, use (after starting
3835 GNUnet):
3836
3837 @example
3838 gnunet-arm -c ~/.config/gnunet.conf -i fs
3839 @end example
3840
3841 @noindent
3842 The "-i fs" option here is for "initialize" the "fs" (file-sharing)
3843 application. You can also selectively kill only file-sharing support using
3844
3845 @example
3846 gnunet-arm -c ~/.config/gnunet.conf -k fs
3847 @end example
3848
3849 @noindent
3850 Assuming that you want certain services (like file-sharing) to be always
3851 automatically started whenever you start GNUnet, you can activate them by
3852 setting "FORCESTART=YES" in the respective section of the configuration
3853 file (for example, "[fs]"). Then GNUnet with file-sharing support would
3854 be started whenever you@ enter:
3855
3856 @example
3857 gnunet-arm -c ~/.config/gnunet.conf -s
3858 @end example
3859
3860 @noindent
3861 Alternatively, you can combine the two options:
3862
3863 @example
3864 gnunet-arm -c ~/.config/gnunet.conf -s -i fs
3865 @end example
3866
3867 @noindent
3868 Using @code{gnunet-arm} is also the preferred method for initializing
3869 GNUnet from @code{init}.
3870
3871 Finally, you should edit your @code{crontab} (using the @code{crontab}
3872 command) and insert a line@
3873
3874 @example
3875 @@reboot gnunet-arm -c ~/.config/gnunet.conf -s
3876 @end example
3877
3878 to automatically start your peer whenever your system boots.
3879
3880 @node The Multi-User Setup
3881 @subsection The Multi-User Setup
3882
3883 This requires you to create a user @code{gnunet} and an additional group
3884 @code{gnunetdns}, prior to running @code{make install} during
3885 installation.
3886 Then, you create a configuration file @file{/etc/gnunet.conf} which should
3887 contain the lines:@
3888
3889 @example
3890 [arm]
3891 SYSTEM_ONLY = YES
3892 USER_ONLY = NO
3893 @end example
3894
3895 @noindent
3896 Then, perform the same steps to run GNUnet as in the per-user
3897 configuration, except as user @code{gnunet} (including the
3898 @code{crontab} installation).
3899 You may also want to run @code{gnunet-setup} to configure your peer
3900 (databases, etc.).
3901 Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you
3902 run @code{gnunet-setup} as user @code{gnunet}, you might need to change
3903 permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can
3904 write to the file (during setup).
3905
3906 Afterwards, you need to perform another setup step for each normal user
3907 account from which you want to access GNUnet. First, grant the normal user
3908 (@code{$USER}) permission to the group gnunet:
3909
3910 @example
3911 # adduser $USER gnunet
3912 @end example
3913
3914 @noindent
3915 Then, create a configuration file in @file{~/.config/gnunet.conf} for the
3916 $USER with the lines:
3917
3918 @example
3919 [arm]
3920 SYSTEM_ONLY = NO
3921 USER_ONLY = YES
3922 @end example
3923
3924 @noindent
3925 This will ensure that @code{gnunet-arm} when started by the normal user
3926 will only run services that are per-user, and otherwise rely on the
3927 system-wide services.
3928 Note that the normal user may run gnunet-setup, but the
3929 configuration would be ineffective as the system-wide services will use
3930 @file{/etc/gnunet.conf} and ignore options set by individual users.
3931
3932 Again, each user should then start the peer using
3933 @file{gnunet-arm -s} --- and strongly consider adding logic to start
3934 the peer automatically to their crontab.
3935
3936 Afterwards, you should see two (or more, if you have more than one USER)
3937 @code{gnunet-service-arm} processes running in your system.
3938
3939 @node Killing GNUnet services
3940 @subsection Killing GNUnet services
3941
3942 It is not necessary to stop GNUnet services explicitly when shutting
3943 down your computer.
3944
3945 It should be noted that manually killing "most" of the
3946 @code{gnunet-service} processes is generally not a successful method for
3947 stopping a peer (since @code{gnunet-service-arm} will instantly restart
3948 them). The best way to explicitly stop a peer is using
3949 @code{gnunet-arm -e}; note that the per-user services may need to be
3950 terminated before the system-wide services will terminate normally.
3951
3952 @node Access Control for GNUnet
3953 @subsection Access Control for GNUnet
3954
3955 This chapter documents how we plan to make access control work within the
3956 GNUnet system for a typical peer. It should be read as a best-practice
3957 installation guide for advanced users and builders of binary
3958 distributions. The recommendations in this guide apply to POSIX-systems
3959 with full support for UNIX domain sockets only.
3960
3961 Note that this is an advanced topic. The discussion presumes a very good
3962 understanding of users, groups and file permissions. Normal users on
3963 hosts with just a single user can just install GNUnet under their own
3964 account (and possibly allow the installer to use SUDO to grant additional
3965 permissions for special GNUnet tools that need additional rights).
3966 The discussion below largely applies to installations where multiple users
3967 share a system and to installations where the best possible security is
3968 paramount.
3969
3970 A typical GNUnet system consists of components that fall into four
3971 categories:
3972
3973 @table @asis
3974
3975 @item User interfaces
3976 User interfaces are not security sensitive and are supposed to be run and
3977 used by normal system users.
3978 The GTK GUIs and most command-line programs fall into this category.
3979 Some command-line tools (like gnunet-transport) should be excluded as they
3980 offer low-level access that normal users should not need.
3981 @item System services and support tools
3982 System services should always run and offer services that can then be
3983 accessed by the normal users.
3984 System services do not require special permissions, but as they are not
3985 specific to a particular user, they probably should not run as a
3986 particular user. Also, there should typically only be one GNUnet peer per
3987 host. System services include the gnunet-service and gnunet-daemon
3988 programs; support tools include command-line programs such as gnunet-arm.
3989 @item Priviledged helpers
3990 Some GNUnet components require root rights to open raw sockets or perform
3991 other special operations. These gnunet-helper binaries are typically
3992 installed SUID and run from services or daemons.
3993 @item Critical services
3994 Some GNUnet services (such as the DNS service) can manipulate the service
3995 in deep and possibly highly security sensitive ways. For example, the DNS
3996 service can be used to intercept and alter any DNS query originating from
3997 the local machine. Access to the APIs of these critical services and their
3998 priviledged helpers must be tightly controlled.
3999 @end table
4000
4001 @c FIXME: The titles of these chapters are too long in the index.
4002
4003 @menu
4004 * Recommendation - Disable access to services via TCP::
4005 * Recommendation - Run most services as system user "gnunet"::
4006 * Recommendation - Control access to services using group "gnunet"::
4007 * Recommendation - Limit access to certain SUID binaries by group "gnunet"::
4008 * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"::
4009 * Differences between "make install" and these recommendations::
4010 @end menu
4011
4012 @node Recommendation - Disable access to services via TCP
4013 @subsubsection Recommendation - Disable access to services via TCP
4014
4015 GNUnet services allow two types of access: via TCP socket or via UNIX
4016 domain socket.
4017 If the service is available via TCP, access control can only be
4018 implemented by restricting connections to a particular range of IP
4019 addresses.
4020 This is acceptable for non-critical services that are supposed to be
4021 available to all users on the local system or local network.
4022 However, as TCP is generally less efficient and it is rarely the case
4023 that a single GNUnet peer is supposed to serve an entire local network,
4024 the default configuration should disable TCP access to all GNUnet
4025 services on systems with support for UNIX domain sockets.
4026 As of GNUnet 0.9.2, configuration files with TCP access disabled should be
4027 generated by default. Users can re-enable TCP access to particular
4028 services simply by specifying a non-zero port number in the section of
4029 the respective service.
4030
4031
4032 @node Recommendation - Run most services as system user "gnunet"
4033 @subsubsection Recommendation - Run most services as system user "gnunet"
4034
4035 GNUnet's main services should be run as a separate user "gnunet" in a
4036 special group "gnunet".
4037 The user "gnunet" should start the peer using "gnunet-arm -s" during
4038 system startup. The home directory for this user should be
4039 @file{/var/lib/gnunet} and the configuration file should be
4040 @file{/etc/gnunet.conf}.
4041 Only the @code{gnunet} user should have the right to access
4042 @file{/var/lib/gnunet} (@emph{mode: 700}).
4043
4044 @node Recommendation - Control access to services using group "gnunet"
4045 @subsubsection Recommendation - Control access to services using group "gnunet"
4046
4047 Users that should be allowed to use the GNUnet peer should be added to the
4048 group "gnunet". Using GNUnet's access control mechanism for UNIX domain
4049 sockets, those services that are considered useful to ordinary users
4050 should be made available by setting "UNIX_MATCH_GID=YES" for those
4051 services.
4052 Again, as shipped, GNUnet provides reasonable defaults.
4053 Permissions to access the transport and core subsystems might additionally
4054 be granted without necessarily causing security concerns.
4055 Some services, such as DNS, must NOT be made accessible to the "gnunet"
4056 group (and should thus only be accessible to the "gnunet" user and
4057 services running with this UID).
4058
4059 @node Recommendation - Limit access to certain SUID binaries by group "gnunet"
4060 @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet"
4061
4062 Most of GNUnet's SUID binaries should be safe even if executed by normal
4063 users. However, it is possible to reduce the risk a little bit more by
4064 making these binaries owned by the group "gnunet" and restricting their
4065 execution to user of the group "gnunet" as well (4750).
4066
4067 @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
4068 @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
4069
4070 A special group "gnunetdns" should be created for controlling access to
4071 the "gnunet-helper-dns".
4072 The binary should then be owned by root and be in group "gnunetdns" and
4073 be installed SUID and only be group-executable (2750).
4074 @b{Note that the group "gnunetdns" should have no users in it at all,
4075 ever.}
4076 The "gnunet-service-dns" program should be executed by user "gnunet" (via
4077 gnunet-service-arm) with the binary owned by the user "root" and the group
4078 "gnunetdns" and be SGID (2700). This way, @strong{only}
4079 "gnunet-service-dns" can change its group to "gnunetdns" and execute the
4080 helper, and the helper can then run as root (as per SUID).
4081 Access to the API offered by "gnunet-service-dns" is in turn restricted
4082 to the user "gnunet" (not the group!), which means that only
4083 "benign" services can manipulate DNS queries using "gnunet-service-dns".
4084
4085 @node Differences between "make install" and these recommendations
4086 @subsubsection Differences between "make install" and these recommendations
4087
4088 The current build system does not set all permissions automatically based
4089 on the recommendations above. In particular, it does not use the group
4090 "gnunet" at all (so setting gnunet-helpers other than the
4091 gnunet-helper-dns to be owned by group "gnunet" must be done manually).
4092 Furthermore, 'make install' will silently fail to set the DNS binaries to
4093 be owned by group "gnunetdns" unless that group already exists (!).
4094 An alternative name for the "gnunetdns" group can be specified using the
4095 @code{--with-gnunetdns=GRPNAME} configure option.