aboutsummaryrefslogtreecommitdiff
path: root/doc/handbook/chapters/installation.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/handbook/chapters/installation.texi')
-rw-r--r--doc/handbook/chapters/installation.texi2496
1 files changed, 0 insertions, 2496 deletions
diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi
deleted file mode 100644
index 54fb3f486..000000000
--- a/doc/handbook/chapters/installation.texi
+++ /dev/null
@@ -1,2496 +0,0 @@
1@node Installing GNUnet
2@chapter Installing GNUnet
3
4This guide is intended for those who want to install Gnunet from
5source. For instructions on how to install GNUnet as a binary package
6please refer to the official documentation of your operating system or
7package manager.
8
9For understanding this guide properly it is important to know that
10there are two different ways of running GNUnet:
11
12@itemize @bullet
13@item the @emph{single-user setup}
14@item the @emph{multi-user setup}
15@end itemize
16
17The latter variant has a better security model and requires extra
18preparation before running @code{make install} and a different
19configuration. Beginners who want to quickly try out GNUnet can
20use the @emph{single-user setup}.
21
22@menu
23* Installing dependencies::
24* Getting the Source Code::
25* Create user and groups for the system services::
26* Preparing and Compiling the Source Code::
27* Installation::
28* Minimal configuration::
29* Checking the Installation::
30* The graphical configuration interface::
31* Config Leftovers::
32@end menu
33
34@c -----------------------------------------------------------------------
35@node Installing dependencies
36@section Installing dependencies
37
38GNUnet needs few libraries and applications for being able to run and
39another few optional ones for using certain features. Preferably they
40should be installed with a package manager.
41
42The mandatory libraries and applications are
43@itemize @bullet
44@item autoconf 2.59 or above
45@item automake 1.11.1 or above
46@item gettext
47@item glibc (read below, other libcs work)
48@item GnuTLS 3.2.12 or above, recommended to be linked against libunbound
49@item GNU make 4.0 or higher (other make implementations do work)
50@item iptables (on Linux systems)
51@item libtool 2.2 or above
52@item libltdl (part of libtool)
53@item libgcrypt 1.6 or above
54@item libidn2 or libidn
55@item libmicrohttpd 0.9.63 or above
56@item libunistring
57@item libgmp
58@item libgnurl or libcurl (libcurl has to be linked to GnuTLS) 7.35.0 or above
59@item Texinfo 5.2 or above (for building the documentation)
60@item Texlive 2012 or above (for building the documentation, and for gnunet-bcd)
61@item makeinfo 4.8 or above
62@item pkgconf (or pkg-config)
63@item zlib
64@end itemize
65
66Glibc is required for certain NSS features:
67
68@example
69One mechanism of integrating GNS with legacy applications via NSS is
70not available if this is disabled. But applications that don't use the
71glibc for NS resolution won't work anyway with this, so little is lost
72on *BSD systems.
73GNS via direct use or via the HTTP or DNS proxies is unaffected.
74@end example
75
76Other libcs should work, the resulting builds just don't include the
77glibc NSS specific code. One example is the build against NetBSD's libc
78as detailed in @uref{https://bugs.gnunet.org/view.php?id=5605}.
79
80In addition GNUnet needs at least one of these three databases
81(at the minimum sqlite3)
82@itemize @bullet
83@item sqlite + libsqlite 3.8 or above (the default, requires no further configuration)
84@item postgres + libpq
85@item mysql + libmysqlclient
86@end itemize
87
88These are the dependencies only required for certain features
89@itemize @bullet
90@item miniupnpc (for traversing NAT boxes more reliably)
91@item libnss
92@item libopus (for running the GNUnet conversation telephony application)
93@item libogg (for running the GNUnet conversation telephony application)
94@item gstreamer OR libpulse (for running the GNUnet conversation telephony application)
95@item bluez (for bluetooth support)
96@item libextractor (optional but highly recommended, read below)
97@item libpbc
98(for attribute-based encryption and the identity provider subsystem)
99@item libgabe
100(for attribute-based encryption and the identity provider subsystem)
101@item texi2mdoc (for automatic mdoc generation)
102@item perl5 for some utilities (which are not installed)
103@item libjanson
104@end itemize
105
106About libextractor being optional:
107@example
108While libextractor ("LE") is optional, it is recommended to build gnunet
109against it. If you install it later, you won't benefit from libextractor.
110If you are a distributor, we recommend to split LE into basis + plugins
111rather than making LE an option as an afterthought by the user. LE
112itself is very small, but its dependency chain on first, second, third
113etc level can be big. There is a small effect on privacy if your LE
114build differs from one which includes all plugins (plugins are build as
115shared objects): if users publish a directory with a mixture of file
116types (for example mpeg, jpeg, png, gif) the configuration of LE could
117leak which plugins are installed for which filetypes are not providing
118more details. However, this leak is just a minor concern.
119@end example
120
121These are the test-suite requirements:
122@itemize @bullet
123@item python3.6 or higher
124@item gnunet (installation first)
125@item some core-utils: which(1), bc(1), curl(1), sed(1), awk(1), etc.
126@item a shell (very few Bash scripts, the majority are POSIX sh scripts)
127@end itemize
128
129These are runtime requirements:
130@itemize @bullet
131@item nss (the certutil binary, for gnunet-gns-proxy-setup-ca)
132@item openssl (openssl binary, for gnunet-gns-proxy-setup-ca)
133@end itemize
134
135@c -----------------------------------------------------------------------
136@node Getting the Source Code
137@section Getting the Source Code
138You can either download the source code using git (you obviously need
139git installed) or as an archive.
140
141Using git type
142@example
143git clone https://git.gnunet.org/gnunet.git
144@end example
145
146The archive can be found at
147@uref{https://ftpmirror.gnu.org/gnu/gnunet/}. Extract it using a graphical
148archive tool or @code{tar}:
149@example
150tar xzvf gnunet-@value{VERSION}.tar.gz
151@end example
152
153In the next chapter we will assume that the source code is available
154in the home directory at @code{~/gnunet}.
155
156@c -----------------------------------------------------------------------
157@node Create user and groups for the system services
158@section Create user and groups for the system services
159
160@cartouche
161For the single-user setup this section can be skipped.
162@end cartouche
163
164The multi-user setup means that there are @emph{system services}, which are
165run once per machine as a dedicated system user (called @code{gnunet}) and
166@emph{user services} which can be started by every user who wants to use
167GNUnet applications. The user services communicate with the system services
168over unix domain sockets. To gain permissions to read and write those sockets
169the users running GNUnet applications will need to be in the @code{gnunet}
170group. In addition the group @code{gnunetdns} may be needed (see below).
171
172Create user @code{gnunet} who is member of the group @code{gnunet}
173(automatically created) and specify a home directory where the GNUnet
174services will store persistent data such as information about peers.
175@example
176$ sudo useradd --system --home-dir /var/lib/gnunet --create-home gnunet
177@end example
178
179Now add your own user to the @code{gnunet} group.
180
181@example
182$ sudo usermod -aG gnunet alice
183@end example
184
185Create a group @code{gnunetdns}. This allows using @code{setgid} in a way
186that only the DNS service can run the @code{gnunet-helper-dns} binary. This
187is only needed if @emph{system-wide DNS interception} will be used. For more
188information see @xref{Configuring system-wide DNS interception}.
189
190@example
191$ sudo groupadd gnunetdns
192@end example
193
194@c -----------------------------------------------------------------------
195@node Preparing and Compiling the Source Code
196@section Preparing and Compiling the Source Code
197For preparing the source code for compilation a bootstrap script and
198@code{configure} has to be run from the source code directory. When
199running @code{configure} the following options can be specified to
200customize the compilation and installation process:
201
202@itemize @bullet
203@item @code{--disable-documentation} - don't build the documentation
204@item @code{--enable-logging=[LOGLEVEL]} - choose a loglevel (@code{debug}, @code{info}, @code{warning} or @code{error})
205@item @code{--prefix=[PATH]} - the directory where the GNUnet libraries and binaries will be installed
206@item @code{--with-extractor=[PATH]} - the path to libextractor
207@item @code{--with-libidn=[PATH]} - the path to libidn
208@item @code{--with-libidn2=[PATH]} - the path to libidn2 (takes priority over libidn if both are found)
209@item @code{--with-microhttpd=[PATH]} - the path to libmicrohttpd
210@item @code{--with-sqlite=[PATH]} - the path to libsqlite
211@item @code{--with-zlib=[PATH]} - the path to zlib
212@end itemize
213
214Note that the list above is not always up to date and you
215should check the output of @code{./configure --help}, read
216the @file{configure.ac} or send an email asking for assistance
217if you are in doubt of any configure options or require fixes
218for your operating system.
219
220The following example configures the installation prefix
221@code{/usr/local} and disables building the documentation
222@example
223$ cd ~/gnunet
224$ ./bootstrap
225$ configure --prefix=/usr/local --disable-documentation
226@end example
227
228After running the bootstrap script and @code{configure} successfully
229the source code can be compiled with make. Here @code{-j5} specifies
230that 5 threads should be used.
231@example
232$ make -j5
233@end example
234
235@c -----------------------------------------------------------------------
236@node Installation
237@section Installation
238The compiled binaries can be installed using @code{make install}. It
239needs to be run as root (or with sudo) because some binaries need the
240@code{suid} bit set. Without that some features (e.g. the VPN service,
241system-wide DNS interception, NAT traversal using ICMP) will not work.
242
243@example
244$ sudo make install
245@end example
246
247@menu
248* NSS plugin (Optional)::
249* Installing the GNS Certificate Authority (Optional)::
250@end menu
251
252@node NSS plugin (Optional)
253@subsection NSS plugin (Optional)
254
255@cartouche
256The installation of the NSS plugin is only necessary if GNS
257resolution shall be used with legacy applications (that only
258support DNS).
259@end cartouche
260
261One important library is the GNS plugin for NSS (the name services
262switch) which allows using GNS (the GNU name system) in the normal DNS
263resolution process. Unfortunately NSS expects it in a specific
264location (probably @code{/lib}) which may differ from the installation
265prefix (see @code{--prefix} option in the previous section). This is
266why the plugin has to be installed manually.
267
268Find the directory where nss plugins are installed on your system, e.g.
269
270@example
271$ ls -l /lib/libnss_*
272/lib/libnss_mymachines.so.2
273/lib/libnss_resolve.so.2
274/lib/libnss_myhostname.so.2
275/lib/libnss_systemd.so.2
276@end example
277
278Copy the GNS NSS plugin to that directory:
279
280@example
281cp ~/gnunet/src/gns/nss/.libs/libnss_gns.so.2 /lib
282@end example
283
284Now, to activate the plugin, you need to edit your
285@code{/etc/nsswitch.conf} where you should find a line like this:
286
287@example
288hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
289@end example
290
291The exact details may differ a bit, which is fine. Add the text
292@code{"gns [NOTFOUND=return]"} after @code{"files"}.
293
294@example
295hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
296@end example
297
298@node Installing the GNS Certificate Authority (Optional)
299@subsection Installing the GNS Certificate Authority (Optional)
300
301@cartouche
302Installing the GNS certificate authority is only necessary if GNS shall
303be used in a browser.
304@end cartouche
305
306The GNS Certificate authority can provide TLS certificates for GNS names while
307downloading webpages from legacy webservers. This allows browsers to use HTTPS
308in combinations with GNS name resolution.
309
310To install it execute the GNS CA-setup script. So far Firefox and Chromium are
311supported.
312
313@example
314$ gnunet-gns-proxy-setup-ca
315@end example
316
317A local proxy server, that takes care of the name resolution and provides
318certificates on-the-fly needs to be started:
319
320@example
321$ /usr/lib/gnunet/libexec/gnunet-gns-proxy
322@end example
323
324Now GNS should work in browsers that are configured to use a SOCKS proxy on
325@code{localhost:7777}.
326
327
328@node Minimal configuration
329@section Minimal configuration
330GNUnet needs a configuration file to start (@pxref{Config file format}).
331For the @emph{single-user setup} an empty file is sufficient:
332
333@example
334$ touch ~/.config/gnunet.conf
335@end example
336
337For the @emph{multi-user setup} we need an extra config file for the system
338services. The default location is @code{/etc/gnunet.conf}. The minimal
339content of that file which activates the system services roll is:
340
341@example
342[arm]
343START_SYSTEM_SERVICES = YES
344START_USER_SERVICES = NO
345@end example
346
347The config file for the user services (@code{~/.config/gnunet.conf}) needs
348the opposite configuration to activate the user services roll:
349
350@example
351[arm]
352START_SYSTEM_SERVICES = NO
353START_USER_SERVICES = YES
354@end example
355
356
357@node Checking the Installation
358@section Checking the Installation
359
360
361This section describes a quick, casual way to check if your GNUnet
362installation works. However, if it does not, we do not cover
363steps for recovery --- for this, please study the instructions
364provided in the developer handbook as well as the system-specific
365instruction in the source code repository.
366Please note that the system specific instructions are not provided
367as part of this handbook!
368
369
370@menu
371* Starting GNUnet::
372* gnunet-gtk::
373* Statistics::
374* Peer Information::
375@end menu
376
377@cindex Starting GNUnet
378@cindex GNUnet GTK
379@cindex GTK
380@cindex GTK user interface
381
382@node Starting GNUnet
383@subsection Starting GNUnet
384The GNUnet services are started and stopped by the ARM service (Automatic
385Restart Manager). For the @emph{single-user setup} a simple
386
387@example
388$ gnunet-arm -s
389@end example
390
391starts a default set of services. Later GNUnet applications can request more
392services to start without additional user interaction. GNUnet can be stopped
393again using the @code{-e} option:
394
395@example
396$ gnunet-arm -e
397@end example
398
399The list of running services can be displayed using the @code{-I} option.
400It should look similar to this example:
401
402@example
403$ gnunet-arm -I
404Running services:
405topology (gnunet-daemon-topology)
406nat (gnunet-service-nat)
407vpn (gnunet-service-vpn)
408gns (gnunet-service-gns)
409cadet (gnunet-service-cadet)
410namecache (gnunet-service-namecache)
411hostlist (gnunet-daemon-hostlist)
412revocation (gnunet-service-revocation)
413ats (gnunet-service-ats)
414peerinfo (gnunet-service-peerinfo)
415zonemaster (gnunet-service-zonemaster)
416zonemaster-monitor (gnunet-service-zonemaster-monitor)
417dht (gnunet-service-dht)
418namestore (gnunet-service-namestore)
419set (gnunet-service-set)
420statistics (gnunet-service-statistics)
421nse (gnunet-service-nse)
422fs (gnunet-service-fs)
423peerstore (gnunet-service-peerstore)
424core (gnunet-service-core)
425rest (gnunet-rest-server)
426transport (gnunet-service-transport)
427datastore (gnunet-service-datastore)
428@end example
429
430For the @emph{multi-user setup} first the system services need to be started
431as the system user, i.e. the user @code{gnunet} needs to execute
432@code{gnunet-arm -s}. This should be done by the system's init system.
433Then the user who wants to start GNUnet applications has to run
434@code{gnunet-arm -s} too. It is recommended to automate this, e.g. using
435the user's crontab.
436
437@node gnunet-gtk
438@subsection gnunet-gtk
439
440
441The @command{gnunet-gtk} package contains several graphical
442user interfaces for the respective GNUnet applications.
443Currently these interfaces cover:
444
445@itemize @bullet
446@item Statistics
447@item Peer Information
448@item GNU Name System
449@item File Sharing
450@item Conversation
451@item Setup
452@end itemize
453
454Previously, many of these interfaces were combined into one application
455called @command{gnunet-gtk}, with different tabs for each interface. This
456combined application has been removed in version 0.11.0, but each of the
457interfaces is still available as a standalone application
458(@command{gnunet-statistics-gtk} for statistics, @command{gnunet-fs-gtk}
459for filesharing, etc).
460
461@node Statistics
462@subsection Statistics
463
464
465We assume that you have started gnunet via @code{gnunet-arm} or via your
466system-provided method for starting services.
467First, you should launch GNUnet's graphical statistics interface.
468You can do this from the command-line by typing
469
470@example
471gnunet-statistics-gtk
472@end example
473
474If your peer is running correctly, you should see a bunch
475of lines, all of which should be ``significantly'' above zero (at
476least if your peer has been running for more than a few seconds). The
477lines indicate how many other peers your peer is connected to (via
478different mechanisms) and how large the entire overlay network is
479currently estimated to be. The X-axis represents time (in seconds
480since the start of @command{gnunet-statistics-gtk}).
481
482You can click on "Traffic" to see information about the amount of
483bandwidth your peer has consumed, and on "Storage" to check the amount
484of storage available and used by your peer. Note that "Traffic" is
485plotted cumulatively, so you should see a strict upwards trend in the
486traffic.
487
488The term ``peer'' is a common word used in
489federated and distributed networks to describe a participating device
490which is connected to the network. Thus, your Personal Computer or
491whatever it is you are looking at the Gtk+ interface describes a
492``Peer'' or a ``Node''.
493
494@node Peer Information
495@subsection Peer Information
496
497
498First, you should launch the peer information graphical user interface.
499You can do this from the command-line by typing
500
501@example
502$ gnunet-peerinfo-gtk
503@end example
504
505Once you have done this, you will see a list of known peers (by the
506first four characters of their public key), their friend status (all
507should be marked as not-friends initially), their connectivity (green
508is connected, red is disconnected), assigned bandwidth, country of
509origin (if determined) and address information. If hardly any peers
510are listed and/or if there are very few peers with a green light for
511connectivity, there is likely a problem with your network
512configuration.
513
514@c NOTE: Inserted from Installation Handbook in original ``order'':
515@c FIXME: Move this to User Handbook.
516@node The graphical configuration interface
517@section The graphical configuration interface
518
519If you also would like to use @command{gnunet-gtk} and
520@command{gnunet-setup} (highly recommended for beginners), do:
521
522@menu
523* Configuring your peer::
524* Configuring the Friend-to-Friend (F2F) mode::
525* Configuring the hostlist to bootstrap::
526* Configuration of the HOSTLIST proxy settings::
527* Configuring your peer to provide a hostlist ::
528* Configuring the datastore::
529* Configuring the MySQL database::
530* Reasons for using MySQL::
531* Reasons for not using MySQL::
532* Setup Instructions::
533* Testing::
534* Performance Tuning::
535* Setup for running Testcases::
536* Configuring the Postgres database::
537* Reasons to use Postgres::
538* Reasons not to use Postgres::
539* Manual setup instructions::
540* Testing the setup manually::
541* Configuring the datacache::
542* Configuring the file-sharing service::
543* Configuring logging::
544* Configuring the transport service and plugins::
545* Configuring the WLAN transport plugin::
546* Configuring HTTP(S) reverse proxy functionality using Apache or nginx::
547* Blacklisting peers::
548* Configuration of the HTTP and HTTPS transport plugins::
549* Configuring the GNU Name System::
550* Configuring the GNUnet VPN::
551* Bandwidth Configuration::
552* Configuring NAT::
553* Peer configuration for distributors (e.g. Operating Systems)::
554@end menu
555
556@node Configuring your peer
557@subsection Configuring your peer
558
559This chapter will describe the various configuration options in GNUnet.
560
561The easiest way to configure your peer is to use the
562@command{gnunet-setup} tool.
563@command{gnunet-setup} is part of the @command{gnunet-gtk}
564package. You might have to install it separately.
565
566Many of the specific sections from this chapter actually are linked from
567within @command{gnunet-setup} to help you while using the setup tool.
568
569While you can also configure your peer by editing the configuration
570file by hand, this is not recommended for anyone except for developers
571as it requires a more in-depth understanding of the configuration files
572and internal dependencies of GNUnet.
573
574@node Configuring the Friend-to-Friend (F2F) mode
575@subsection Configuring the Friend-to-Friend (F2F) mode
576
577GNUnet knows three basic modes of operation:
578@itemize @bullet
579@item In standard "peer-to-peer" mode,
580your peer will connect to any peer.
581@item In the pure "friend-to-friend"
582mode, your peer will ONLY connect to peers from a list of friends
583specified in the configuration.
584@item Finally, in mixed mode,
585GNUnet will only connect to arbitrary peers if it
586has at least a specified number of connections to friends.
587@end itemize
588
589When configuring any of the F2F ("friend-to-friend") modes,
590you first need to create a file with the peer identities
591of your friends. Ask your friends to run
592
593@example
594$ gnunet-peerinfo -sq
595@end example
596
597@noindent
598The resulting output of this command needs to be added to your
599@file{friends} file, which is simply a plain text file with one line
600per friend with the output from the above command.
601
602You then specify the location of your @file{friends} file in the
603@code{FRIENDS} option of the "topology" section.
604
605Once you have created the @file{friends} file, you can tell GNUnet to only
606connect to your friends by setting the @code{FRIENDS-ONLY} option
607(again in the "topology" section) to YES.
608
609If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a
610minimum number of friends to have (before connecting to arbitrary peers)
611under the "MINIMUM-FRIENDS" option.
612
613If you want to operate in normal P2P-only mode, simply set
614@code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO.
615This is the default.
616
617@node Configuring the hostlist to bootstrap
618@subsection Configuring the hostlist to bootstrap
619
620After installing the software you need to get connected to the GNUnet
621network. The configuration file included in your download is already
622configured to connect you to the GNUnet network.
623In this section the relevant configuration settings are explained.
624
625To get an initial connection to the GNUnet network and to get to know
626peers already connected to the network you can use the so called
627"bootstrap servers".
628These servers can give you a list of peers connected to the network.
629To use these bootstrap servers you have to configure the hostlist daemon
630to activate bootstrapping.
631
632To activate bootstrapping, edit the @code{[hostlist]}-section in your
633configuration file. You have to set the argument @command{-b} in the
634options line:
635
636@example
637[hostlist]
638OPTIONS = -b
639@end example
640
641Additionally you have to specify which server you want to use.
642The default bootstrapping server is
643"@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}".
644[^] To set the server you have to edit the line "SERVERS" in the hostlist
645section. To use the default server you should set the lines to
646
647@example
648SERVERS = http://v10.gnunet.org/hostlist [^]
649@end example
650
651@noindent
652To use bootstrapping your configuration file should include these lines:
653
654@example
655[hostlist]
656OPTIONS = -b
657SERVERS = http://v10.gnunet.org/hostlist [^]
658@end example
659
660@noindent
661Besides using bootstrap servers you can configure your GNUnet peer to
662receive hostlist advertisements.
663Peers offering hostlists to other peers can send advertisement messages
664to peers that connect to them. If you configure your peer to receive these
665messages, your peer can download these lists and connect to the peers
666included. These lists are persistent, which means that they are saved to
667your hard disk regularly and are loaded during startup.
668
669To activate hostlist learning you have to add the @command{-e}
670switch to the @code{OPTIONS} line in the hostlist section:
671
672@example
673[hostlist]
674OPTIONS = -b -e
675@end example
676
677@noindent
678Furthermore you can specify in which file the lists are saved.
679To save the lists in the file @file{hostlists.file} just add the line:
680
681@example
682HOSTLISTFILE = hostlists.file
683@end example
684
685@noindent
686Best practice is to activate both bootstrapping and hostlist learning.
687So your configuration file should include these lines:
688
689@example
690[hostlist]
691OPTIONS = -b -e
692HTTPPORT = 8080
693SERVERS = http://v10.gnunet.org/hostlist [^]
694HOSTLISTFILE = $SERVICEHOME/hostlists.file
695@end example
696
697@node Configuration of the HOSTLIST proxy settings
698@subsection Configuration of the HOSTLIST proxy settings
699
700The hostlist client can be configured to use a proxy to connect to the
701hostlist server.
702This functionality can be configured in the configuration file directly
703or using the @command{gnunet-setup} tool.
704
705The hostlist client supports the following proxy types at the moment:
706
707@itemize @bullet
708@item HTTP and HTTP 1.0 only proxy
709@item SOCKS 4/4a/5/5 with hostname
710@end itemize
711
712In addition authentication at the proxy with username and password can be
713configured.
714
715To configure proxy support for the hostlist client in the
716@command{gnunet-setup} tool, select the "hostlist" tab and select
717the appropriate proxy type.
718The hostname or IP address (including port if required) has to be entered
719in the "Proxy hostname" textbox. If required, enter username and password
720in the "Proxy username" and "Proxy password" boxes.
721Be aware that this information will be stored in the configuration in
722plain text (TODO: Add explanation and generalize the part in Chapter 3.6
723about the encrypted home).
724
725To provide these options directly in the configuration, you can
726enter the following settings in the @code{[hostlist]} section of
727the configuration:
728
729@example
730# Type of proxy server,
731# Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME
732# Default: HTTP
733# PROXY_TYPE = HTTP
734
735# Hostname or IP of proxy server
736# PROXY =
737# User name for proxy server
738# PROXY_USERNAME =
739# User password for proxy server
740# PROXY_PASSWORD =
741@end example
742
743@node Configuring your peer to provide a hostlist
744@subsection Configuring your peer to provide a hostlist
745
746If you operate a peer permanently connected to GNUnet you can configure
747your peer to act as a hostlist server, providing other peers the list of
748peers known to him.
749
750Your server can act as a bootstrap server and peers needing to obtain a
751list of peers can contact it to download this list.
752To download this hostlist the peer uses HTTP.
753For this reason you have to build your peer with libgnurl (or libcurl)
754and microhttpd support.
755
756To configure your peer to act as a bootstrap server you have to add the
757@command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section
758of your configuration file.
759Besides that you have to specify a port number for the http server.
760In conclusion you have to add the following lines:
761
762@example
763[hostlist]
764HTTPPORT = 12980
765OPTIONS = -p
766@end example
767
768@noindent
769If your peer acts as a bootstrap server other peers should know about
770that. You can advertise the hostlist your are providing to other peers.
771Peers connecting to your peer will get a message containing an
772advertisement for your hostlist and the URL where it can be downloaded.
773If this peer is in learning mode, it will test the hostlist and, in the
774case it can obtain the list successfully, it will save it for
775bootstrapping.
776
777To activate hostlist advertisement on your peer, you have to set the
778following lines in your configuration file:
779
780@example
781[hostlist]
782EXTERNAL_DNS_NAME = example.org
783HTTPPORT = 12981
784OPTIONS = -p -a
785@end example
786
787@noindent
788With this configuration your peer will a act as a bootstrap server and
789advertise this hostlist to other peers connecting to it.
790The URL used to download the list will be
791@code{@uref{http://example.org:12981/, http://example.org:12981/}}.
792
793Please notice:
794
795@itemize @bullet
796@item The hostlist is @b{not} human readable, so you should not try to
797download it using your webbrowser. Just point your GNUnet peer to the
798address!
799@item Advertising without providing a hostlist does not make sense and
800will not work.
801@end itemize
802
803@node Configuring the datastore
804@subsection Configuring the datastore
805
806The datastore is what GNUnet uses for long-term storage of file-sharing
807data. Note that long-term does not mean 'forever' since content does have
808an expiration date, and of course storage space is finite (and hence
809sometimes content may have to be discarded).
810
811Use the @code{QUOTA} option to specify how many bytes of storage space
812you are willing to dedicate to GNUnet.
813
814In addition to specifying the maximum space GNUnet is allowed to use for
815the datastore, you need to specify which database GNUnet should use to do
816so. Currently, you have the choice between sqLite, MySQL and Postgres.
817
818@node Configuring the MySQL database
819@subsection Configuring the MySQL database
820
821This section describes how to setup the MySQL database for GNUnet.
822
823Note that the mysql plugin does NOT work with mysql before 4.1 since we
824need prepared statements.
825We are generally testing the code against MySQL 5.1 at this point.
826
827@node Reasons for using MySQL
828@subsection Reasons for using MySQL
829
830@itemize @bullet
831
832@item On up-to-date hardware where
833mysql can be used comfortably, this module
834will have better performance than the other database choices (according
835to our tests).
836
837@item Its often possible to recover the mysql database from internal
838inconsistencies. Some of the other databases do not support repair.
839@end itemize
840
841@node Reasons for not using MySQL
842@subsection Reasons for not using MySQL
843
844@itemize @bullet
845@item Memory usage (likely not an issue if you have more than 1 GB)
846@item Complex manual setup
847@end itemize
848
849@node Setup Instructions
850@subsection Setup Instructions
851
852@itemize @bullet
853
854@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
855@code{DATABASE} to @code{mysql}.
856
857@item Access mysql as root:
858
859@example
860$ mysql -u root -p
861@end example
862
863@noindent
864and issue the following commands, replacing $USER with the username
865that will be running @command{gnunet-arm} (so typically "gnunet"):
866
867@example
868CREATE DATABASE gnunet;
869GRANT select,insert,update,delete,create,alter,drop,create \
870temporary tables ON gnunet.* TO $USER@@localhost;
871SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like');
872FLUSH PRIVILEGES;
873@end example
874
875@item
876In the $HOME directory of $USER, create a @file{.my.cnf} file with the
877following lines
878
879@example
880[client]
881user=$USER
882password=$the_password_you_like
883@end example
884
885@end itemize
886
887That's it. Note that @file{.my.cnf} file is a slight security risk unless
888its on a safe partition. The @file{$HOME/.my.cnf} can of course be
889a symbolic link.
890Luckily $USER has only privileges to mess up GNUnet's tables,
891which should be pretty harmless.
892
893@node Testing
894@subsection Testing
895
896You should briefly try if the database connection works. First, login
897as $USER. Then use:
898
899@example
900$ mysql -u $USER
901mysql> use gnunet;
902@end example
903
904@noindent
905If you get the message
906
907@example
908Database changed
909@end example
910
911@noindent
912it probably works.
913
914If you get
915
916@example
917ERROR 2002: Can't connect to local MySQL server
918through socket '/tmp/mysql.sock' (2)
919@end example
920
921@noindent
922it may be resolvable by
923
924@example
925ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock
926@end example
927
928@noindent
929so there may be some additional trouble depending on your mysql setup.
930
931@node Performance Tuning
932@subsection Performance Tuning
933
934For GNUnet, you probably want to set the option
935
936@example
937innodb_flush_log_at_trx_commit = 0
938@end example
939
940@noindent
941for a rather dramatic boost in MySQL performance. However, this reduces
942the "safety" of your database as with this options you may loose
943transactions during a power outage.
944While this is totally harmless for GNUnet, the option applies to all
945applications using MySQL. So you should set it if (and only if) GNUnet is
946the only application on your system using MySQL.
947
948@node Setup for running Testcases
949@subsection Setup for running Testcases
950
951If you want to run the testcases, you must create a second database
952"gnunetcheck" with the same username and password. This database will
953then be used for testing (@command{make check}).
954
955@node Configuring the Postgres database
956@subsection Configuring the Postgres database
957
958This text describes how to setup the Postgres database for GNUnet.
959
960This Postgres plugin was developed for Postgres 8.3 but might work for
961earlier versions as well.
962
963@node Reasons to use Postgres
964@subsection Reasons to use Postgres
965
966@itemize @bullet
967@item Easier to setup than MySQL
968@item Real database
969@end itemize
970
971@node Reasons not to use Postgres
972@subsection Reasons not to use Postgres
973
974@itemize @bullet
975@item Quite slow
976@item Still some manual setup required
977@end itemize
978
979@node Manual setup instructions
980@subsection Manual setup instructions
981
982@itemize @bullet
983@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
984@code{DATABASE} to @code{postgres}.
985@item Access Postgres to create a user:
986
987@table @asis
988@item with Postgres 8.x, use:
989
990@example
991# su - postgres
992$ createuser
993@end example
994
995@noindent
996and enter the name of the user running GNUnet for the role interactively.
997Then, when prompted, do not set it to superuser, allow the creation of
998databases, and do not allow the creation of new roles.
999
1000@item with Postgres 9.x, use:
1001
1002@example
1003# su - postgres
1004$ createuser -d $GNUNET_USER
1005@end example
1006
1007@noindent
1008where $GNUNET_USER is the name of the user running GNUnet.
1009
1010@end table
1011
1012
1013@item
1014As that user (so typically as user "gnunet"), create a database (or two):
1015
1016@example
1017$ createdb gnunet
1018# this way you can run "make check"
1019$ createdb gnunetcheck
1020@end example
1021
1022@end itemize
1023
1024Now you should be able to start @code{gnunet-arm}.
1025
1026@node Testing the setup manually
1027@subsection Testing the setup manually
1028
1029You may want to try if the database connection works. First, again login
1030as the user who will run @command{gnunet-arm}. Then use:
1031
1032@example
1033$ psql gnunet # or gnunetcheck
1034gnunet=> \dt
1035@end example
1036
1037@noindent
1038If, after you have started @command{gnunet-arm} at least once, you get
1039a @code{gn090} table here, it probably works.
1040
1041@node Configuring the datacache
1042@subsection Configuring the datacache
1043
1044
1045The datacache is what GNUnet uses for storing temporary data. This data is
1046expected to be wiped completely each time GNUnet is restarted (or the
1047system is rebooted).
1048
1049You need to specify how many bytes GNUnet is allowed to use for the
1050datacache using the @code{QUOTA} option in the section @code{[dhtcache]}.
1051Furthermore, you need to specify which database backend should be used to
1052store the data. Currently, you have the choice between
1053sqLite, MySQL and Postgres.
1054
1055@node Configuring the file-sharing service
1056@subsection Configuring the file-sharing service
1057
1058In order to use GNUnet for file-sharing, you first need to make sure
1059that the file-sharing service is loaded.
1060This is done by setting the @code{START_ON_DEMAND} option in
1061section @code{[fs]} to "YES". Alternatively, you can run
1062
1063@example
1064$ gnunet-arm -i fs
1065@end example
1066
1067@noindent
1068to start the file-sharing service by hand.
1069
1070Except for configuring the database and the datacache the only important
1071option for file-sharing is content migration.
1072
1073Content migration allows your peer to cache content from other peers as
1074well as send out content stored on your system without explicit requests.
1075This content replication has positive and negative impacts on both system
1076performance and privacy.
1077
1078FIXME: discuss the trade-offs. Here is some older text about it...
1079
1080Setting this option to YES allows gnunetd to migrate data to the local
1081machine. Setting this option to YES is highly recommended for efficiency.
1082Its also the default. If you set this value to YES, GNUnet will store
1083content on your machine that you cannot decrypt.
1084While this may protect you from liability if the judge is sane, it may
1085not (IANAL). If you put illegal content on your machine yourself, setting
1086this option to YES will probably increase your chances to get away with it
1087since you can plausibly deny that you inserted the content.
1088Note that in either case, your anonymity would have to be broken first
1089(which may be possible depending on the size of the GNUnet network and the
1090strength of the adversary).
1091
1092@node Configuring logging
1093@subsection Configuring logging
1094
1095Since version 0.9.0, logging in GNUnet is controlled via the
1096@code{-L} and @code{-l} options.
1097Using @code{-L}, a log level can be specified. With log level
1098@code{ERROR} only serious errors are logged.
1099The default log level is @code{WARNING} which causes anything of
1100concern to be logged.
1101Log level @code{INFO} can be used to log anything that might be
1102interesting information whereas
1103@code{DEBUG} can be used by developers to log debugging messages
1104(but you need to run @code{./configure} with
1105@code{--enable-logging=verbose} to get them compiled).
1106The @code{-l} option is used to specify the log file.
1107
1108Since most GNUnet services are managed by @code{gnunet-arm}, using the
1109@code{-l} or @code{-L} options directly is not possible.
1110Instead, they can be specified using the @code{OPTIONS} configuration
1111value in the respective section for the respective service.
1112In order to enable logging globally without editing the @code{OPTIONS}
1113values for each service, @command{gnunet-arm} supports a
1114@code{GLOBAL_POSTFIX} option.
1115The value specified here is given as an extra option to all services for
1116which the configuration does contain a service-specific @code{OPTIONS}
1117field.
1118
1119@code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which
1120is replaced by the name of the service that is being started.
1121Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences
1122starting with "$" anywhere in the string are expanded (according
1123to options in @code{PATHS}); this expansion otherwise is
1124only happening for filenames and then the "$" must be the
1125first character in the option. Both of these restrictions do
1126not apply to @code{GLOBAL_POSTFIX}.
1127Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX}
1128disables both of these features.
1129
1130In summary, in order to get all services to log at level
1131@code{INFO} to log-files called @code{SERVICENAME-logs}, the
1132following global prefix should be used:
1133
1134@example
1135GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO
1136@end example
1137
1138@node Configuring the transport service and plugins
1139@subsection Configuring the transport service and plugins
1140
1141The transport service in GNUnet is responsible to maintain basic
1142connectivity to other peers.
1143Besides initiating and keeping connections alive it is also responsible
1144for address validation.
1145
1146The GNUnet transport supports more than one transport protocol.
1147These protocols are configured together with the transport service.
1148
1149The configuration section for the transport service itself is quite
1150similar to all the other services
1151
1152@example
1153START_ON_DEMAND = YES
1154@@UNIXONLY@@ PORT = 2091
1155HOSTNAME = localhost
1156HOME = $SERVICEHOME
1157CONFIG = $DEFAULTCONFIG
1158BINARY = gnunet-service-transport
1159#PREFIX = valgrind
1160NEIGHBOUR_LIMIT = 50
1161ACCEPT_FROM = 127.0.0.1;
1162ACCEPT_FROM6 = ::1;
1163PLUGINS = tcp udp
1164UNIXPATH = /tmp/gnunet-service-transport.sock
1165@end example
1166
1167Different are the settings for the plugins to load @code{PLUGINS}.
1168The first setting specifies which transport plugins to load.
1169
1170@itemize @bullet
1171@item transport-unix
1172A plugin for local only communication with UNIX domain sockets. Used for
1173testing and available on unix systems only. Just set the port
1174
1175@example
1176[transport-unix]
1177PORT = 22086
1178TESTING_IGNORE_KEYS = ACCEPT_FROM;
1179@end example
1180
1181@item transport-tcp
1182A plugin for communication with TCP. Set port to 0 for client mode with
1183outbound only connections
1184
1185@example
1186[transport-tcp]
1187# Use 0 to ONLY advertise as a peer behind NAT (no port binding)
1188PORT = 2086
1189ADVERTISED_PORT = 2086
1190TESTING_IGNORE_KEYS = ACCEPT_FROM;
1191# Maximum number of open TCP connections allowed
1192MAX_CONNECTIONS = 128
1193@end example
1194
1195@item transport-udp
1196A plugin for communication with UDP. Supports peer discovery using
1197broadcasts.
1198
1199@example
1200[transport-udp]
1201PORT = 2086
1202BROADCAST = YES
1203BROADCAST_INTERVAL = 30 s
1204MAX_BPS = 1000000
1205TESTING_IGNORE_KEYS = ACCEPT_FROM;
1206@end example
1207
1208@item transport-http
1209HTTP and HTTPS support is split in two part: a client plugin initiating
1210outbound connections and a server part accepting connections from the
1211client. The client plugin just takes the maximum number of connections as
1212an argument.
1213
1214@example
1215[transport-http_client]
1216MAX_CONNECTIONS = 128
1217TESTING_IGNORE_KEYS = ACCEPT_FROM;
1218@end example
1219
1220@example
1221[transport-https_client]
1222MAX_CONNECTIONS = 128
1223TESTING_IGNORE_KEYS = ACCEPT_FROM;
1224@end example
1225
1226@noindent
1227The server has a port configured and the maximum number of connections.
1228The HTTPS part has two files with the certificate key and the certificate
1229file.
1230
1231The server plugin supports reverse proxies, so a external hostname can be
1232set using the @code{EXTERNAL_HOSTNAME} setting.
1233The webserver under this address should forward the request to the peer
1234and the configure port.
1235
1236@example
1237[transport-http_server]
1238EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet
1239PORT = 1080
1240MAX_CONNECTIONS = 128
1241TESTING_IGNORE_KEYS = ACCEPT_FROM;
1242@end example
1243
1244@example
1245[transport-https_server]
1246PORT = 4433
1247CRYPTO_INIT = NORMAL
1248KEY_FILE = https.key
1249CERT_FILE = https.cert
1250MAX_CONNECTIONS = 128
1251TESTING_IGNORE_KEYS = ACCEPT_FROM;
1252@end example
1253
1254@item transport-wlan
1255
1256The next section describes how to setup the WLAN plugin,
1257so here only the settings. Just specify the interface to use:
1258
1259@example
1260[transport-wlan]
1261# Name of the interface in monitor mode (typically monX)
1262INTERFACE = mon0
1263# Real hardware, no testing
1264TESTMODE = 0
1265TESTING_IGNORE_KEYS = ACCEPT_FROM;
1266@end example
1267@end itemize
1268
1269@node Configuring the WLAN transport plugin
1270@subsection Configuring the WLAN transport plugin
1271
1272The wlan transport plugin enables GNUnet to send and to receive data on a
1273wlan interface.
1274It has not to be connected to a wlan network as long as sender and
1275receiver are on the same channel. This enables you to get connection to
1276GNUnet where no internet access is possible, for example during
1277catastrophes or when censorship cuts you off from the internet.
1278
1279
1280@menu
1281* Requirements for the WLAN plugin::
1282* Configuration::
1283* Before starting GNUnet::
1284* Limitations and known bugs::
1285@end menu
1286
1287
1288@node Requirements for the WLAN plugin
1289@subsubsection Requirements for the WLAN plugin
1290
1291@itemize @bullet
1292
1293@item wlan network card with monitor support and packet injection
1294(see @uref{http://www.aircrack-ng.org/, aircrack-ng.org})
1295
1296@item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with
12972.6.35 and 2.6.38
1298
1299@item Wlantools to create the a monitor interface, tested with airmon-ng
1300of the aircrack-ng package
1301@end itemize
1302
1303@node Configuration
1304@subsubsection Configuration
1305
1306There are the following options for the wlan plugin (they should be like
1307this in your default config file, you only need to adjust them if the
1308values are incorrect for your system)
1309
1310@example
1311# section for the wlan transport plugin
1312[transport-wlan]
1313# interface to use, more information in the
1314# "Before starting GNUnet" section of the handbook.
1315INTERFACE = mon0
1316# testmode for developers:
1317# 0 use wlan interface,
1318#1 or 2 use loopback driver for tests 1 = server, 2 = client
1319TESTMODE = 0
1320@end example
1321
1322@node Before starting GNUnet
1323@subsubsection Before starting GNUnet
1324
1325Before starting GNUnet, you have to make sure that your wlan interface is
1326in monitor mode.
1327One way to put the wlan interface into monitor mode (if your interface
1328name is wlan0) is by executing:
1329
1330@example
1331sudo airmon-ng start wlan0
1332@end example
1333
1334@noindent
1335Here is an example what the result should look like:
1336
1337@example
1338Interface Chipset Driver
1339wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]
1340(monitor mode enabled on mon0)
1341@end example
1342
1343@noindent
1344The monitor interface is mon0 is the one that you have to put into the
1345configuration file.
1346
1347@node Limitations and known bugs
1348@subsubsection Limitations and known bugs
1349
1350Wlan speed is at the maximum of 1 Mbit/s because support for choosing the
1351wlan speed with packet injection was removed in newer kernels.
1352Please pester the kernel developers about fixing this.
1353
1354The interface channel depends on the wlan network that the card is
1355connected to. If no connection has been made since the start of the
1356computer, it is usually the first channel of the card.
1357Peers will only find each other and communicate if they are on the same
1358channel. Channels must be set manually, e.g. by using:
1359
1360@example
1361iwconfig wlan0 channel 1
1362@end example
1363
1364@node Configuring HTTP(S) reverse proxy functionality using Apache or nginx
1365@subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
1366
1367The HTTP plugin supports data transfer using reverse proxies. A reverse
1368proxy forwards the HTTP request he receives with a certain URL to another
1369webserver, here a GNUnet peer.
1370
1371So if you have a running Apache or nginx webserver you can configure it to
1372be a GNUnet reverse proxy. Especially if you have a well-known website
1373this improves censorship resistance since it looks as normal surfing
1374behaviour.
1375
1376To do so, you have to do two things:
1377
1378@itemize @bullet
1379@item Configure your webserver to forward the GNUnet HTTP traffic
1380@item Configure your GNUnet peer to announce the respective address
1381@end itemize
1382
1383As an example we want to use GNUnet peer running:
1384
1385@itemize @bullet
1386
1387@item HTTP server plugin on @code{gnunet.foo.org:1080}
1388
1389@item HTTPS server plugin on @code{gnunet.foo.org:4433}
1390
1391@item A apache or nginx webserver on
1392@uref{http://www.foo.org/, http://www.foo.org:80/}
1393
1394@item A apache or nginx webserver on https://www.foo.org:443/
1395@end itemize
1396
1397And we want the webserver to accept GNUnet traffic under
1398@code{http://www.foo.org/bar/}. The required steps are described here:
1399
1400@menu
1401* Reverse Proxy - Configure your Apache2 HTTP webserver::
1402* Reverse Proxy - Configure your Apache2 HTTPS webserver::
1403* Reverse Proxy - Configure your nginx HTTPS webserver::
1404* Reverse Proxy - Configure your nginx HTTP webserver::
1405* Reverse Proxy - Configure your GNUnet peer::
1406@end menu
1407
1408@node Reverse Proxy - Configure your Apache2 HTTP webserver
1409@subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver
1410
1411First of all you need mod_proxy installed.
1412
1413Edit your webserver configuration. Edit
1414@code{/etc/apache2/apache2.conf} or the site-specific configuration file.
1415
1416In the respective @code{server config},@code{virtual host} or
1417@code{directory} section add the following lines:
1418
1419@example
1420ProxyTimeout 300
1421ProxyRequests Off
1422<Location /bar/ >
1423ProxyPass http://gnunet.foo.org:1080/
1424ProxyPassReverse http://gnunet.foo.org:1080/
1425</Location>
1426@end example
1427
1428@node Reverse Proxy - Configure your Apache2 HTTPS webserver
1429@subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver
1430
1431We assume that you already have an HTTPS server running, if not please
1432check how to configure a HTTPS host. An uncomplicated to use example
1433is the example configuration file for Apache2/HTTPD provided in
1434@file{apache2/sites-available/default-ssl}.
1435
1436In the respective HTTPS @code{server config},@code{virtual host} or
1437@code{directory} section add the following lines:
1438
1439@example
1440SSLProxyEngine On
1441ProxyTimeout 300
1442ProxyRequests Off
1443<Location /bar/ >
1444ProxyPass https://gnunet.foo.org:4433/
1445ProxyPassReverse https://gnunet.foo.org:4433/
1446</Location>
1447@end example
1448
1449@noindent
1450More information about the apache mod_proxy configuration can be found
1451in the
1452@uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, Apache documentation}.
1453
1454@node Reverse Proxy - Configure your nginx HTTPS webserver
1455@subsubsection Reverse Proxy - Configure your nginx HTTPS webserver
1456
1457Since nginx does not support chunked encoding, you first of all have to
1458install the @code{chunkin}
1459@uref{http://wiki.nginx.org/HttpChunkinModule, module}.
1460
1461To enable chunkin add:
1462
1463@example
1464chunkin on;
1465error_page 411 = @@my_411_error;
1466location @@my_411_error @{
1467chunkin_resume;
1468@}
1469@end example
1470
1471@noindent
1472Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
1473the site-specific configuration file.
1474
1475In the @code{server} section add:
1476
1477@example
1478location /bar/ @{
1479proxy_pass http://gnunet.foo.org:1080/;
1480proxy_buffering off;
1481proxy_connect_timeout 5; # more than http_server
1482proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout
1483proxy_http_version 1.1; # 1.0 default
1484proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;
1485@}
1486@end example
1487
1488@node Reverse Proxy - Configure your nginx HTTP webserver
1489@subsubsection Reverse Proxy - Configure your nginx HTTP webserver
1490
1491Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
1492the site-specific configuration file.
1493
1494In the @code{server} section add:
1495
1496@example
1497ssl_session_timeout 6m;
1498location /bar/
1499@{
1500proxy_pass https://gnunet.foo.org:4433/;
1501proxy_buffering off;
1502proxy_connect_timeout 5; # more than http_server
1503proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout
1504proxy_http_version 1.1; # 1.0 default
1505proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;
1506@}
1507@end example
1508
1509@node Reverse Proxy - Configure your GNUnet peer
1510@subsubsection Reverse Proxy - Configure your GNUnet peer
1511
1512To have your GNUnet peer announce the address, you have to specify the
1513@code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]}
1514section:
1515
1516@example
1517[transport-http_server]
1518EXTERNAL_HOSTNAME = http://www.foo.org/bar/
1519@end example
1520
1521@noindent
1522and/or @code{[transport-https_server]} section:
1523
1524@example
1525[transport-https_server]
1526EXTERNAL_HOSTNAME = https://www.foo.org/bar/
1527@end example
1528
1529@noindent
1530Now restart your webserver and your peer...
1531
1532@node Blacklisting peers
1533@subsection Blacklisting peers
1534
1535Transport service supports to deny connecting to a specific peer of to a
1536specific peer with a specific transport plugin using the blacklisting
1537component of transport service. With@ blacklisting it is possible to deny
1538connections to specific peers of@ to use a specific plugin to a specific
1539peer. Peers can be blacklisted using@ the configuration or a blacklist
1540client can be asked.
1541
1542To blacklist peers using the configuration you have to add a section to
1543your configuration containing the peer id of the peer to blacklist and
1544the plugin@ if required.
1545
1546Examples:
1547
1548To blacklist connections to P565... on peer AG2P... using tcp add:
1549
1550@c FIXME: This is too long and produces errors in the pdf.
1551@example
1552[transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
1553P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp
1554@end example
1555
1556To blacklist connections to P565... on peer AG2P... using all plugins add:
1557
1558@example
1559[transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
1560P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =
1561@end example
1562
1563You can also add a blacklist client using the blacklist API. On a
1564blacklist check, blacklisting first checks internally if the peer is
1565blacklisted and if not, it asks the blacklisting clients. Clients are
1566asked if it is OK to connect to a peer ID, the plugin is omitted.
1567
1568On blacklist check for (peer, plugin)
1569
1570@itemize @bullet
1571@item Do we have a local blacklist entry for this peer and this plugin?
1572@item YES: disallow connection
1573@item Do we have a local blacklist entry for this peer and all plugins?
1574@item YES: disallow connection
1575@item Does one of the clients disallow?
1576@item YES: disallow connection
1577@end itemize
1578
1579@node Configuration of the HTTP and HTTPS transport plugins
1580@subsection Configuration of the HTTP and HTTPS transport plugins
1581
1582The client parts of the http and https transport plugins can be configured
1583to use a proxy to connect to the hostlist server. This functionality can
1584be configured in the configuration file directly or using the
1585gnunet-setup tool.
1586
1587Both the HTTP and HTTPS clients support the following proxy types at
1588the moment:
1589
1590@itemize @bullet
1591@item HTTP 1.1 proxy
1592@item SOCKS 4/4a/5/5 with hostname
1593@end itemize
1594
1595In addition authentication at the proxy with username and password can be
1596configured.
1597
1598To configure proxy support for the clients in the gnunet-setup tool,
1599select the "transport" tab and activate the respective plugin. Now you
1600can select the appropriate proxy type. The hostname or IP address
1601(including port if required) has to be entered in the "Proxy hostname"
1602textbox. If required, enter username and password in the "Proxy username"
1603and "Proxy password" boxes. Be aware that these information will be stored
1604in the configuration in plain text.
1605
1606To configure these options directly in the configuration, you can
1607configure the following settings in the @code{[transport-http_client]}
1608and @code{[transport-https_client]} section of the configuration:
1609
1610@example
1611# Type of proxy server,
1612# Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME
1613# Default: HTTP
1614# PROXY_TYPE = HTTP
1615
1616# Hostname or IP of proxy server
1617# PROXY =
1618# User name for proxy server
1619# PROXY_USERNAME =
1620# User password for proxy server
1621# PROXY_PASSWORD =
1622@end example
1623
1624@node Configuring the GNU Name System
1625@subsection Configuring the GNU Name System
1626
1627@menu
1628* Configuring system-wide DNS interception::
1629* Configuring the GNS nsswitch plugin::
1630@c * Configuring GNS on W32::
1631* GNS Proxy Setup::
1632* Setup of the GNS CA::
1633* Testing the GNS setup::
1634* Migrating existing DNS zones into GNS::
1635@end menu
1636
1637
1638@node Configuring system-wide DNS interception
1639@subsubsection Configuring system-wide DNS interception
1640
1641Before you install GNUnet, make sure you have a user and group 'gnunet'
1642as well as an empty group 'gnunetdns'.
1643
1644When using GNUnet with system-wide DNS interception, it is absolutely
1645necessary for all GNUnet service processes to be started by
1646@code{gnunet-service-arm} as user and group 'gnunet'. You also need to be
1647sure to run @code{make install} as root (or use the @code{sudo} option to
1648configure) to grant GNUnet sufficient privileges.
1649
1650With this setup, all that is required for enabling system-wide DNS
1651interception is for some GNUnet component (VPN or GNS) to request it.
1652The @code{gnunet-service-dns} will then start helper programs that will
1653make the necessary changes to your firewall (@code{iptables}) rules.
1654
1655Note that this will NOT work if your system sends out DNS traffic to a
1656link-local IPv6 address, as in this case GNUnet can intercept the traffic,
1657but not inject the responses from the link-local IPv6 address. Hence you
1658cannot use system-wide DNS interception in conjunction with link-local
1659IPv6-based DNS servers. If such a DNS server is used, it will bypass
1660GNUnet's DNS traffic interception.
1661
1662Using the GNU Name System (GNS) requires two different configuration
1663steps.
1664First of all, GNS needs to be integrated with the operating system. Most
1665of this section is about the operating system level integration.
1666
1667The remainder of this chapter will detail the various methods for
1668configuring the use of GNS with your operating system.
1669
1670At this point in time you have different options depending on your OS:
1671
1672@itemize @bullet
1673@item Use the gnunet-gns-proxy@*
1674This approach works for all operating systems and is likely the
1675easiest. However, it enables GNS only for browsers, not for other
1676applications that might be using DNS, such as SSH. Still, using the
1677proxy is required for using HTTP with GNS and is thus recommended for
1678all users. To do this, you simply have to run the
1679@code{gnunet-gns-proxy-setup-ca} script as the user who will run the
1680browser (this will create a GNS certificate authority (CA) on your
1681system and import its key into your browser), then start
1682@code{gnunet-gns-proxy} and inform your browser to use the Socks5
1683proxy which @code{gnunet-gns-proxy} makes available by default on port
16847777.
1685@item Use a nsswitch plugin (recommended on GNU systems)@*
1686This approach has the advantage of offering fully personalized
1687resolution even on multi-user systems. A potential disadvantage is
1688that some applications might be able to bypass GNS.
1689@item Use a W32 resolver plugin (recommended on W32)@*
1690This is currently the only option on W32 systems.
1691@item Use system-wide DNS packet interception@*
1692This approach is recommended for the GNUnet VPN. It can be used to
1693handle GNS at the same time; however, if you only use this method, you
1694will only get one root zone per machine (not so great for multi-user
1695systems).
1696@end itemize
1697
1698You can combine system-wide DNS packet interception with the nsswitch
1699plugin.
1700The setup of the system-wide DNS interception is described here. All of
1701the other GNS-specific configuration steps are described in the following
1702sections.
1703
1704@node Configuring the GNS nsswitch plugin
1705@subsubsection Configuring the GNS nsswitch plugin
1706
1707The Name Service Switch (NSS) is a facility in Unix-like operating systems
1708(in most cases provided by the GNU C Library)
1709that provides a variety of sources for common configuration databases and
1710name resolution mechanisms.
1711A superuser (system administrator) usually configures the
1712operating system's name services using the file
1713@file{/etc/nsswitch.conf}.
1714
1715GNS provides a NSS plugin to integrate GNS name resolution with the
1716operating system's name resolution process.
1717To use the GNS NSS plugin you have to either
1718
1719@itemize @bullet
1720@item install GNUnet as root or
1721@item compile GNUnet with the @code{--with-sudo=yes} switch.
1722@end itemize
1723
1724Name resolution is controlled by the @emph{hosts} section in the NSS
1725configuration. By default this section first performs a lookup in the
1726@file{/etc/hosts} file and then in DNS.
1727The nsswitch file should contain a line similar to:
1728
1729@example
1730hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4
1731@end example
1732
1733@noindent
1734Here the GNS NSS plugin can be added to perform a GNS lookup before
1735performing a DNS lookup.
1736The GNS NSS plugin has to be added to the "hosts" section in
1737@file{/etc/nsswitch.conf} file before DNS related plugins:
1738
1739@example
1740...
1741hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4
1742...
1743@end example
1744
1745@noindent
1746The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not
1747found in GNS it will not be queried in DNS.
1748
1749@c @node Configuring GNS on W32
1750@c @subsubsection Configuring GNS on W32
1751
1752@c This document is a guide to configuring GNU Name System on W32-compatible
1753@c platforms.
1754
1755@c After GNUnet is installed, run the w32nsp-install tool:
1756
1757@c @example
1758@c w32nsp-install.exe libw32nsp-0.dll
1759@c @end example
1760
1761@c @noindent
1762@c ('0' is the library version of W32 NSP; it might increase in the future,
1763@c change the invocation accordingly).
1764
1765@c This will install GNS namespace provider into the system and allow other
1766@c applications to resolve names that end in '@strong{gnu}'
1767@c and '@strong{zkey}'. Note that namespace provider requires
1768@c gnunet-gns-helper-service-w32 to be running, as well as gns service
1769@c itself (and its usual dependencies).
1770
1771@c Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353},
1772@c and this is where gnunet-gns-helper-service-w32 should be listening to
1773@c (and is configured to listen to by default).
1774
1775@c To uninstall the provider, run:
1776
1777@c @example
1778@c w32nsp-uninstall.exe
1779@c @end example
1780
1781@c @noindent
1782@c (uses provider GUID to uninstall it, does not need a dll name).
1783
1784@c Note that while MSDN claims that other applications will only be able to
1785@c use the new namespace provider after re-starting, in reality they might
1786@c stat to use it without that. Conversely, they might stop using the
1787@c provider after it's been uninstalled, even if they were not re-started.
1788@c W32 will not permit namespace provider library to be deleted or
1789@c overwritten while the provider is installed, and while there is at least
1790@c one process still using it (even after it was uninstalled).
1791
1792@node GNS Proxy Setup
1793@subsubsection GNS Proxy Setup
1794
1795When using the GNU Name System (GNS) to browse the WWW, there are several
1796issues that can be solved by adding the GNS Proxy to your setup:
1797
1798@itemize @bullet
1799
1800@item If the target website does not support GNS, it might assume that it
1801is operating under some name in the legacy DNS system (such as
1802example.com). It may then attempt to set cookies for that domain, and the
1803web server might expect a @code{Host: example.com} header in the request
1804from your browser.
1805However, your browser might be using @code{example.gnu} for the
1806@code{Host} header and might only accept (and send) cookies for
1807@code{example.gnu}. The GNS Proxy will perform the necessary translations
1808of the hostnames for cookies and HTTP headers (using the LEHO record for
1809the target domain as the desired substitute).
1810
1811@item If using HTTPS, the target site might include an SSL certificate
1812which is either only valid for the LEHO domain or might match a TLSA
1813record in GNS. However, your browser would expect a valid certificate for
1814@code{example.gnu}, not for some legacy domain name. The proxy will
1815validate the certificate (either against LEHO or TLSA) and then
1816on-the-fly produce a valid certificate for the exchange, signed by your
1817own CA. Assuming you installed the CA of your proxy in your browser's
1818certificate authority list, your browser will then trust the
1819HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy.
1820
1821@item Finally, the proxy will in the future indicate to the server that it
1822speaks GNS, which will enable server operators to deliver GNS-enabled web
1823sites to your browser (and continue to deliver legacy links to legacy
1824browsers)
1825@end itemize
1826
1827@node Setup of the GNS CA
1828@subsubsection Setup of the GNS CA
1829
1830First you need to create a CA certificate that the proxy can use.
1831To do so use the provided script gnunet-gns-proxy-ca:
1832
1833@example
1834$ gnunet-gns-proxy-setup-ca
1835@end example
1836
1837@noindent
1838This will create a personal certification authority for you and add this
1839authority to the firefox and chrome database. The proxy will use the this
1840CA certificate to generate @code{*.gnu} client certificates on the fly.
1841
1842Note that the proxy uses libcurl. Make sure your version of libcurl uses
1843GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled
1844against OpenSSL.
1845
1846You can check the configuration your libcurl was build with by
1847running:
1848
1849@example
1850curl --version
1851@end example
1852
1853the output will look like this (without the linebreaks):
1854
1855@example
1856gnurl --version
1857curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \
1858GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4
1859Release-Date: 2017-10-08
1860Protocols: http https
1861Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \
1862TLS-SRP UnixSockets HTTPS-proxy
1863@end example
1864
1865@node Testing the GNS setup
1866@subsubsection Testing the GNS setup
1867
1868Now for testing purposes we can create some records in our zone to test
1869the SSL functionality of the proxy:
1870
1871@example
1872$ gnunet-identity -C test
1873$ gnunet-namestore -a -e "1 d" -n "homepage" \
1874 -t A -V 131.159.74.67 -z test
1875$ gnunet-namestore -a -e "1 d" -n "homepage" \
1876 -t LEHO -V "gnunet.org" -z test
1877@end example
1878
1879@noindent
1880At this point we can start the proxy. Simply execute
1881
1882@example
1883$ gnunet-arm -i gns-proxy
1884@end example
1885
1886To run the proxy at all times in the future, you should
1887change your configuration as follows:
1888
1889@example
1890$ gnunet-config -s gns-proxy -o AUTOSTART -V YES
1891@end example
1892
1893@noindent
1894Configure your browser to use this SOCKSv5 proxy using
1895@code{localhost} on port 7777.
1896If you use @command{Firefox} (or one of its derivatives/forks such as
1897Icecat) you also have to go to @code{about:config} and set the key
1898@code{network.proxy.socks_remote_dns} to @code{true}.
1899
1900When you visit @code{https://homepage.test/}, you should get to the
1901@code{https://gnunet.org/} frontpage and the browser (with the correctly
1902configured proxy) should give you a valid SSL certificate for
1903@code{homepage.gnu} and no warnings. It should look like this:
1904
1905@c FIXME: Image does not exist, create it or save it from Drupal?
1906@c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser}
1907
1908@node Migrating existing DNS zones into GNS
1909@subsubsection Migrating existing DNS zones into GNS
1910
1911To migrate an existing zone into GNS use the Ascension tool.
1912
1913Ascension transfers entire zones into GNS by doing incremental zone transfers
1914and then adding the records to GNS.
1915
1916Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending
1917on whether or not there exists a SOA record for the zone. If that is the case it
1918will take the serial as a reference point and request the zone. The server will
1919either answer the IXFR request with a correct incremental zone or with the
1920entire zone, which depends on the server configuration.
1921
1922You can find the source code here: @code{https://git.gnunet.org/ascension.git/}
1923
1924The software can be installed into a Python virtual environment like this:
1925@example
1926$ python3 -m venv .venv
1927$ source .venv/bin/activate
1928$ python3 setup.py install
1929@end example
1930
1931Or installed globally like this:
1932@example
1933$ sudo python3 setup.py install
1934@end example
1935
1936Pip will then install all the necessary requirements that are needed to run
1937Ascension. For development purposes a virtual environment should suffice.
1938Keeping a virtual environment helps with keeping things tidy and prevents
1939breaking of Ascension through a future Python update.
1940
1941The advantage of using a virtual environment is, that all the dependencies can
1942be installed separately in different versions without touching your systems
1943Python installation and its dependencies.
1944
1945Another way to install Ascension on Debian is to install the python3-ascension
1946package. It can be found within the above mentioned Ascension git repository.
1947This also adds a system user called ascension and runs a GNUnet peer in the
1948background. Please note: This only works if a recent version of GNUnet is
1949installed on your system. The version number of Ascension is chosen according
1950to the required feature level of GNUnet: Ascension 0.11.5 is only
1951compatible with GNUnet 0.11.5 or later and so on.
1952As Debian's packages for GNUnet are outdated even in experimental,
1953you will need to install GNUnet manually
1954@xref{Installing GNUnet}.
1955
1956Please check @xref{Migrating an existing DNS zone into GNS}, for usage manual
1957of the tool.
1958
1959@node Configuring the GNUnet VPN
1960@subsection Configuring the GNUnet VPN
1961
1962@menu
1963* IPv4 address for interface::
1964* IPv6 address for interface::
1965* Configuring the GNUnet VPN DNS::
1966* Configuring the GNUnet VPN Exit Service::
1967* IP Address of external DNS resolver::
1968* IPv4 address for Exit interface::
1969* IPv6 address for Exit interface::
1970@end menu
1971
1972Before configuring the GNUnet VPN, please make sure that system-wide DNS
1973interception is configured properly as described in the section on the
1974GNUnet DNS setup. @pxref{Configuring the GNU Name System},
1975if you haven't done so already.
1976
1977The default options for the GNUnet VPN are usually sufficient to use
1978GNUnet as a Layer 2 for your Internet connection.
1979However, what you always have to specify is which IP protocol you want
1980to tunnel: IPv4, IPv6 or both.
1981Furthermore, if you tunnel both, you most likely should also tunnel
1982all of your DNS requests.
1983You theoretically can tunnel "only" your DNS traffic, but that usually
1984makes little sense.
1985
1986The other options as shown on the gnunet-setup tool are:
1987
1988@node IPv4 address for interface
1989@subsubsection IPv4 address for interface
1990
1991This is the IPv4 address the VPN interface will get. You should pick a
1992'private' IPv4 network that is not yet in use for you system. For example,
1993if you use @code{10.0.0.1/255.255.0.0} already, you might use
1994@code{10.1.0.1/255.255.0.0}.
1995If you use @code{10.0.0.1/255.0.0.0} already, then you might use
1996@code{192.168.0.1/255.255.0.0}.
1997If your system is not in a private IP-network, using any of the above will
1998work fine.
1999You should try to make the mask of the address big enough
2000(@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more
2001mappings of remote IP Addresses into this range.
2002However, even a @code{255.255.255.0} mask will suffice for most users.
2003
2004@node IPv6 address for interface
2005@subsubsection IPv6 address for interface
2006
2007The IPv6 address the VPN interface will get. Here you can specify any
2008non-link-local address (the address should not begin with @code{fe80:}).
2009A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are
2010currently not using would be a good choice.
2011
2012@node Configuring the GNUnet VPN DNS
2013@subsubsection Configuring the GNUnet VPN DNS
2014
2015To resolve names for remote nodes, activate the DNS exit option.
2016
2017@node Configuring the GNUnet VPN Exit Service
2018@subsubsection Configuring the GNUnet VPN Exit Service
2019
2020If you want to allow other users to share your Internet connection (yes,
2021this may be dangerous, just as running a Tor exit node) or want to
2022provide access to services on your host (this should be less dangerous,
2023as long as those services are secure), you have to enable the GNUnet exit
2024daemon.
2025
2026You then get to specify which exit functions you want to provide. By
2027enabling the exit daemon, you will always automatically provide exit
2028functions for manually configured local services (this component of the
2029system is under
2030development and not documented further at this time). As for those
2031services you explicitly specify the target IP address and port, there is
2032no significant security risk in doing so.
2033
2034Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet.
2035Being a DNS exit is usually pretty harmless. However, enabling IPv4 or
2036IPv6-exit without further precautions may enable adversaries to access
2037your local network, send spam, attack other systems from your Internet
2038connection and do other mischiefs that will appear to come from your
2039machine. This may or may not get you into legal trouble.
2040If you want to allow IPv4 or IPv6-exit functionality, you should strongly
2041consider adding additional firewall rules manually to protect your local
2042network and to restrict outgoing TCP traffic (e.g. by not allowing access
2043to port 25). While we plan to improve exit-filtering in the future,
2044you're currently on your own here.
2045Essentially, be prepared for any kind of IP-traffic to exit the respective
2046TUN interface (and GNUnet will enable IP-forwarding and NAT for the
2047interface automatically).
2048
2049Additional configuration options of the exit as shown by the gnunet-setup
2050tool are:
2051
2052@node IP Address of external DNS resolver
2053@subsubsection IP Address of external DNS resolver
2054
2055If DNS traffic is to exit your machine, it will be send to this DNS
2056resolver. You can specify an IPv4 or IPv6 address.
2057
2058@node IPv4 address for Exit interface
2059@subsubsection IPv4 address for Exit interface
2060
2061This is the IPv4 address the Interface will get. Make the mask of the
2062address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more
2063mappings of IP addresses into this range. As for the VPN interface, any
2064unused, private IPv4 address range will do.
2065
2066@node IPv6 address for Exit interface
2067@subsubsection IPv6 address for Exit interface
2068
2069The public IPv6 address the interface will get. If your kernel is not a
2070very recent kernel and you are willing to manually enable IPv6-NAT, the
2071IPv6 address you specify here must be a globally routed IPv6 address of
2072your host.
2073
2074Suppose your host has the address @code{2001:4ca0::1234/64}, then
2075using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits,
2076then change at least one bit in the range before the bitmask, in the
2077example above we changed bit 111 from 0 to 1).
2078
2079You may also have to configure your router to route traffic for the entire
2080subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this
2081should be automatic with IPv6, but obviously anything can be
2082disabled).
2083
2084@node Bandwidth Configuration
2085@subsection Bandwidth Configuration
2086
2087You can specify how many bandwidth GNUnet is allowed to use to receive
2088and send data. This is important for users with limited bandwidth or
2089traffic volume.
2090
2091@node Configuring NAT
2092@subsection Configuring NAT
2093
2094Most hosts today do not have a normal global IP address but instead are
2095behind a router performing Network Address Translation (NAT) which assigns
2096each host in the local network a private IP address.
2097As a result, these machines cannot trivially receive inbound connections
2098from the Internet. GNUnet supports NAT traversal to enable these machines
2099to receive incoming connections from other peers despite their
2100limitations.
2101
2102In an ideal world, you can press the "Attempt automatic configuration"
2103button in gnunet-setup to automatically configure your peer correctly.
2104Alternatively, your distribution might have already triggered this
2105automatic configuration during the installation process.
2106However, automatic configuration can fail to determine the optimal
2107settings, resulting in your peer either not receiving as many connections
2108as possible, or in the worst case it not connecting to the network at all.
2109
2110To manually configure the peer, you need to know a few things about your
2111network setup. First, determine if you are behind a NAT in the first
2112place.
2113This is always the case if your IP address starts with "10.*" or
2114"192.168.*". Next, if you have control over your NAT router, you may
2115choose to manually configure it to allow GNUnet traffic to your host.
2116If you have configured your NAT to forward traffic on ports 2086 (and
2117possibly 1080) to your host, you can check the "NAT ports have been opened
2118manually" option, which corresponds to the "PUNCHED_NAT" option in the
2119configuration file. If you did not punch your NAT box, it may still be
2120configured to support UPnP, which allows GNUnet to automatically
2121configure it. In that case, you need to install the "upnpc" command,
2122enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal
2123via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the
2124configuration file).
2125
2126Some NAT boxes can be traversed using the autonomous NAT traversal method.
2127This requires certain GNUnet components to be installed with "SUID"
2128privileges on your system (so if you're installing on a system you do
2129not have administrative rights to, this will not work).
2130If you installed as 'root', you can enable autonomous NAT traversal by
2131checking the "Enable NAT traversal using ICMP method".
2132The ICMP method requires a way to determine your NAT's external (global)
2133IP address. This can be done using either UPnP, DynDNS, or by manual
2134configuration. If you have a DynDNS name or know your external IP address,
2135you should enter that name under "External (public) IPv4 address" (which
2136corresponds to the "EXTERNAL_ADDRESS" option in the configuration file).
2137If you leave the option empty, GNUnet will try to determine your external
2138IP address automatically (which may fail, in which case autonomous
2139NAT traversal will then not work).
2140
2141Finally, if you yourself are not behind NAT but want to be able to
2142connect to NATed peers using autonomous NAT traversal, you need to check
2143the "Enable connecting to NATed peers using ICMP method" box.
2144
2145
2146@node Peer configuration for distributors (e.g. Operating Systems)
2147@subsection Peer configuration for distributors (e.g. Operating Systems)
2148
2149The "GNUNET_DATA_HOME" in "[PATHS]" in @file{/etc/gnunet.conf} should be
2150manually set to "/var/lib/gnunet/data/" as the default
2151"~/.local/share/gnunet/" is probably not that appropriate in this case.
2152Similarly, distributors may consider pointing "GNUNET_RUNTIME_DIR" to
2153"/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a
2154distributor decide to override system defaults, all of these changes
2155should be done in a custom @file{/etc/gnunet.conf} and not in the files
2156in the @file{config.d/} directory.
2157
2158Given the proposed access permissions, the "gnunet-setup" tool must be
2159run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it
2160modifies the system configuration). As always, gnunet-setup should be run
2161after the GNUnet peer was stopped using "gnunet-arm -e". Distributors
2162might want to include a wrapper for gnunet-setup that allows the
2163desktop-user to "sudo" (e.g. using gtksudo) to the "gnunet" user account
2164and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
2165sequence.
2166
2167@node Config Leftovers
2168@section Config Leftovers
2169
2170This section describes how to start a GNUnet peer. It assumes that you
2171have already compiled and installed GNUnet and its' dependencies.
2172Before you start a GNUnet peer, you may want to create a configuration
2173file using gnunet-setup (but you do not have to).
2174Sane defaults should exist in your
2175@file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice
2176you could simply start without any configuration. If you want to
2177configure your peer later, you need to stop it before invoking the
2178@code{gnunet-setup} tool to customize further and to test your
2179configuration (@code{gnunet-setup} has built-in test functions).
2180
2181The most important option you might have to still set by hand is in
2182[PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where
2183GNUnet should store its data.
2184It defaults to @code{$HOME/}, which again should work for most users.
2185Make sure that the directory specified as GNUNET_HOME is writable to
2186the user that you will use to run GNUnet (note that you can run frontends
2187using other users, GNUNET_HOME must only be accessible to the user used to
2188run the background processes).
2189
2190You will also need to make one central decision: should all of GNUnet be
2191run under your normal UID, or do you want distinguish between system-wide
2192(user-independent) GNUnet services and personal GNUnet services. The
2193multi-user setup is slightly more complicated, but also more secure and
2194generally recommended.
2195
2196@menu
2197* The Single-User Setup::
2198* The Multi-User Setup::
2199* Killing GNUnet services::
2200* Access Control for GNUnet::
2201@end menu
2202
2203@node The Single-User Setup
2204@subsection The Single-User Setup
2205
2206For the single-user setup, you do not need to do anything special and can
2207just start the GNUnet background processes using @code{gnunet-arm}.
2208By default, GNUnet looks in @file{~/.config/gnunet.conf} for a
2209configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@
2210@code{$XDG_CONFIG_HOME} is defined). If your configuration lives
2211elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet
2212commands.
2213
2214Assuming the configuration file is called @file{~/.config/gnunet.conf},
2215you start your peer using the @code{gnunet-arm} command (say as user
2216@code{gnunet}) using:
2217
2218@example
2219gnunet-arm -c ~/.config/gnunet.conf -s
2220@end example
2221
2222@noindent
2223The "-s" option here is for "start". The command should return almost
2224instantly. If you want to stop GNUnet, you can use:
2225
2226@example
2227gnunet-arm -c ~/.config/gnunet.conf -e
2228@end example
2229
2230@noindent
2231The "-e" option here is for "end".
2232
2233Note that this will only start the basic peer, no actual applications
2234will be available.
2235If you want to start the file-sharing service, use (after starting
2236GNUnet):
2237
2238@example
2239gnunet-arm -c ~/.config/gnunet.conf -i fs
2240@end example
2241
2242@noindent
2243The "-i fs" option here is for "initialize" the "fs" (file-sharing)
2244application. You can also selectively kill only file-sharing support using
2245
2246@example
2247gnunet-arm -c ~/.config/gnunet.conf -k fs
2248@end example
2249
2250@noindent
2251Assuming that you want certain services (like file-sharing) to be always
2252automatically started whenever you start GNUnet, you can activate them by
2253setting "IMMEDIATE_START=YES" in the respective section of the configuration
2254file (for example, "[fs]"). Then GNUnet with file-sharing support would
2255be started whenever you@ enter:
2256
2257@example
2258gnunet-arm -c ~/.config/gnunet.conf -s
2259@end example
2260
2261@noindent
2262Alternatively, you can combine the two options:
2263
2264@example
2265gnunet-arm -c ~/.config/gnunet.conf -s -i fs
2266@end example
2267
2268@noindent
2269Using @code{gnunet-arm} is also the preferred method for initializing
2270GNUnet from @code{init}.
2271
2272Finally, you should edit your @code{crontab} (using the @code{crontab}
2273command) and insert a line@
2274
2275@example
2276@@reboot gnunet-arm -c ~/.config/gnunet.conf -s
2277@end example
2278
2279to automatically start your peer whenever your system boots.
2280
2281@node The Multi-User Setup
2282@subsection The Multi-User Setup
2283
2284This requires you to create a user @code{gnunet} and an additional group
2285@code{gnunetdns}, prior to running @code{make install} during
2286installation.
2287Then, you create a configuration file @file{/etc/gnunet.conf} which should
2288contain the lines:@
2289
2290@example
2291[arm]
2292START_SYSTEM_SERVICES = YES
2293START_USER_SERVICES = NO
2294@end example
2295
2296@noindent
2297Then, perform the same steps to run GNUnet as in the per-user
2298configuration, except as user @code{gnunet} (including the
2299@code{crontab} installation).
2300You may also want to run @code{gnunet-setup} to configure your peer
2301(databases, etc.).
2302Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you
2303run @code{gnunet-setup} as user @code{gnunet}, you might need to change
2304permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can
2305write to the file (during setup).
2306
2307Afterwards, you need to perform another setup step for each normal user
2308account from which you want to access GNUnet. First, grant the normal user
2309(@code{$USER}) permission to the group gnunet:
2310
2311@example
2312# adduser $USER gnunet
2313@end example
2314
2315@noindent
2316Then, create a configuration file in @file{~/.config/gnunet.conf} for the
2317$USER with the lines:
2318
2319@example
2320[arm]
2321START_SYSTEM_SERVICES = NO
2322START_USER_SERVICES = YES
2323@end example
2324
2325@noindent
2326This will ensure that @code{gnunet-arm} when started by the normal user
2327will only run services that are per-user, and otherwise rely on the
2328system-wide services.
2329Note that the normal user may run gnunet-setup, but the
2330configuration would be ineffective as the system-wide services will use
2331@file{/etc/gnunet.conf} and ignore options set by individual users.
2332
2333Again, each user should then start the peer using
2334@file{gnunet-arm -s} --- and strongly consider adding logic to start
2335the peer automatically to their crontab.
2336
2337Afterwards, you should see two (or more, if you have more than one USER)
2338@code{gnunet-service-arm} processes running in your system.
2339
2340@node Killing GNUnet services
2341@subsection Killing GNUnet services
2342
2343It is not necessary to stop GNUnet services explicitly when shutting
2344down your computer.
2345
2346It should be noted that manually killing "most" of the
2347@code{gnunet-service} processes is generally not a successful method for
2348stopping a peer (since @code{gnunet-service-arm} will instantly restart
2349them). The best way to explicitly stop a peer is using
2350@code{gnunet-arm -e}; note that the per-user services may need to be
2351terminated before the system-wide services will terminate normally.
2352
2353@node Access Control for GNUnet
2354@subsection Access Control for GNUnet
2355
2356This chapter documents how we plan to make access control work within the
2357GNUnet system for a typical peer. It should be read as a best-practice
2358installation guide for advanced users and builders of binary
2359distributions. The recommendations in this guide apply to POSIX-systems
2360with full support for UNIX domain sockets only.
2361
2362Note that this is an advanced topic. The discussion presumes a very good
2363understanding of users, groups and file permissions. Normal users on
2364hosts with just a single user can just install GNUnet under their own
2365account (and possibly allow the installer to use SUDO to grant additional
2366permissions for special GNUnet tools that need additional rights).
2367The discussion below largely applies to installations where multiple users
2368share a system and to installations where the best possible security is
2369paramount.
2370
2371A typical GNUnet system consists of components that fall into four
2372categories:
2373
2374@table @asis
2375
2376@item User interfaces
2377User interfaces are not security sensitive and are supposed to be run and
2378used by normal system users.
2379The GTK GUIs and most command-line programs fall into this category.
2380Some command-line tools (like gnunet-transport) should be excluded as they
2381offer low-level access that normal users should not need.
2382@item System services and support tools
2383System services should always run and offer services that can then be
2384accessed by the normal users.
2385System services do not require special permissions, but as they are not
2386specific to a particular user, they probably should not run as a
2387particular user. Also, there should typically only be one GNUnet peer per
2388host. System services include the gnunet-service and gnunet-daemon
2389programs; support tools include command-line programs such as gnunet-arm.
2390@item Privileged helpers
2391Some GNUnet components require root rights to open raw sockets or perform
2392other special operations. These gnunet-helper binaries are typically
2393installed SUID and run from services or daemons.
2394@item Critical services
2395Some GNUnet services (such as the DNS service) can manipulate the service
2396in deep and possibly highly security sensitive ways. For example, the DNS
2397service can be used to intercept and alter any DNS query originating from
2398the local machine. Access to the APIs of these critical services and their
2399privileged helpers must be tightly controlled.
2400@end table
2401
2402@c FIXME: The titles of these chapters are too long in the index.
2403
2404@menu
2405* Recommendation - Disable access to services via TCP::
2406* Recommendation - Run most services as system user "gnunet"::
2407* Recommendation - Control access to services using group "gnunet"::
2408* Recommendation - Limit access to certain SUID binaries by group "gnunet"::
2409* Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"::
2410* Differences between "make install" and these recommendations::
2411@end menu
2412
2413@node Recommendation - Disable access to services via TCP
2414@subsubsection Recommendation - Disable access to services via TCP
2415
2416GNUnet services allow two types of access: via TCP socket or via UNIX
2417domain socket.
2418If the service is available via TCP, access control can only be
2419implemented by restricting connections to a particular range of IP
2420addresses.
2421This is acceptable for non-critical services that are supposed to be
2422available to all users on the local system or local network.
2423However, as TCP is generally less efficient and it is rarely the case
2424that a single GNUnet peer is supposed to serve an entire local network,
2425the default configuration should disable TCP access to all GNUnet
2426services on systems with support for UNIX domain sockets.
2427Since GNUnet 0.9.2, configuration files with TCP access disabled should be
2428generated by default. Users can re-enable TCP access to particular
2429services simply by specifying a non-zero port number in the section of
2430the respective service.
2431
2432
2433@node Recommendation - Run most services as system user "gnunet"
2434@subsubsection Recommendation - Run most services as system user "gnunet"
2435
2436GNUnet's main services should be run as a separate user "gnunet" in a
2437special group "gnunet".
2438The user "gnunet" should start the peer using "gnunet-arm -s" during
2439system startup. The home directory for this user should be
2440@file{/var/lib/gnunet} and the configuration file should be
2441@file{/etc/gnunet.conf}.
2442Only the @code{gnunet} user should have the right to access
2443@file{/var/lib/gnunet} (@emph{mode: 700}).
2444
2445@node Recommendation - Control access to services using group "gnunet"
2446@subsubsection Recommendation - Control access to services using group "gnunet"
2447
2448Users that should be allowed to use the GNUnet peer should be added to the
2449group "gnunet". Using GNUnet's access control mechanism for UNIX domain
2450sockets, those services that are considered useful to ordinary users
2451should be made available by setting "UNIX_MATCH_GID=YES" for those
2452services.
2453Again, as shipped, GNUnet provides reasonable defaults.
2454Permissions to access the transport and core subsystems might additionally
2455be granted without necessarily causing security concerns.
2456Some services, such as DNS, must NOT be made accessible to the "gnunet"
2457group (and should thus only be accessible to the "gnunet" user and
2458services running with this UID).
2459
2460@node Recommendation - Limit access to certain SUID binaries by group "gnunet"
2461@subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet"
2462
2463Most of GNUnet's SUID binaries should be safe even if executed by normal
2464users. However, it is possible to reduce the risk a little bit more by
2465making these binaries owned by the group "gnunet" and restricting their
2466execution to user of the group "gnunet" as well (4750).
2467
2468@node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
2469@subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
2470
2471A special group "gnunetdns" should be created for controlling access to
2472the "gnunet-helper-dns".
2473The binary should then be owned by root and be in group "gnunetdns" and
2474be installed SUID and only be group-executable (2750).
2475@b{Note that the group "gnunetdns" should have no users in it at all,
2476ever.}
2477The "gnunet-service-dns" program should be executed by user "gnunet" (via
2478gnunet-service-arm) with the binary owned by the user "root" and the group
2479"gnunetdns" and be SGID (2700). This way, @strong{only}
2480"gnunet-service-dns" can change its group to "gnunetdns" and execute the
2481helper, and the helper can then run as root (as per SUID).
2482Access to the API offered by "gnunet-service-dns" is in turn restricted
2483to the user "gnunet" (not the group!), which means that only
2484"benign" services can manipulate DNS queries using "gnunet-service-dns".
2485
2486@node Differences between "make install" and these recommendations
2487@subsubsection Differences between "make install" and these recommendations
2488
2489The current build system does not set all permissions automatically based
2490on the recommendations above. In particular, it does not use the group
2491"gnunet" at all (so setting gnunet-helpers other than the
2492gnunet-helper-dns to be owned by group "gnunet" must be done manually).
2493Furthermore, 'make install' will silently fail to set the DNS binaries to
2494be owned by group "gnunetdns" unless that group already exists (!).
2495An alternative name for the "gnunetdns" group can be specified using the
2496@code{--with-gnunetdns=GRPNAME} configure option.