1 @node Installing GNUnet
2 @chapter Installing GNUnet
4 This guide is intended for those who want to install Gnunet from
5 source. For instructions on how to install GNUnet as a binary package
6 please refer to the official documentation of your operating system or
9 For understanding this guide properly it is important to know that
10 there are two different ways of running GNUnet:
13 @item the @emph{single-user setup}
14 @item the @emph{multi-user setup}
17 The latter variant has a better security model and requires extra preparation
18 before running @code{make install} and a different configuration. Beginners who want to
19 quickly try out GNUnet can use the @emph{single-user setup}.
22 * Installing dependencies::
23 * Getting the Source Code::
24 * Create user and groups for the system services::
25 * Preparing and Compiling the Source Code::
27 * Minimal configuration::
28 * Checking the Installation::
29 * The graphical configuration interface::
33 @c -----------------------------------------------------------------------
34 @node Installing dependencies
35 @section Installing dependencies
36 GNUnet needs few libraries and applications for being able to run and
37 another few optional ones for using certain features. Preferably they
38 should be installed with a package manager. Just in case we include a
39 link to the project websites.
41 The mandatory libraries and applications are
43 @item autoconf 2.59 or above
44 @item automake 1.11.1 or above
46 @item glibc (read below, other libcs should work)
47 @item gnutls 3.2.12 or above, recommended to be linked against libunbound
48 @item iptables (on Linux systems)
49 @item libtool 2.2 or above
50 @item libltdl (part of libtool)
51 @item libgcrypt 1.6 or above
53 @item libidn2 or libidn
54 @item libmicrohttpd 0.9.63 or above
57 @item libgnurl or libcurl (libcurl has to be linked to GnuTLS) 7.35.0 or above
58 @item Texinfo 5.2 or above (for building the documentation)
59 @item Texlive 2012 or above (for building the documentation, and for gnunet-bcd)
60 @item makeinfo 4.8 or above
64 Glibc is required for certain NSS features:
67 One mechanism of integrating GNS with legacy applications via NSS is
68 not available if this is disabled. But applications that don't use the
69 glibc for NS resolution won't work anyway with this, so little is lost
71 GNS via direct use or via the HTTP or DNS proxies is unaffected.
74 Other libcs should work, the resulting builds just don't include the
75 glibc NSS specific code. One example is the build against NetBSD's libc
76 as detailed in @uref{https://bugs.gnunet.org/view.php?id=5605}.
78 In addition GNUnet needs one of of these three databases
80 @item sqlite + libsqlite 3.8 or above (the default, requires no further configuration)
81 @item postgres + libpq
82 @item mysql + libmysqlclient
85 These are the dependencies only required for certain features
87 @item guile 1.6.4 for gnunet-download-manager
88 @item miniupnpc (for traversing NAT boxes more reliably)
90 @item libglpk 4.45 or above for experimental code
91 @item libopus (for running the GNUnet conversation telephony application)
92 @item libpulse (for running the GNUnet conversation telephony application)
93 @item libogg (for running the GNUnet conversation telephony application)
94 @item bluez (for bluetooth support)
96 (for attribute-based encryption and the identity provider subsystem)
98 (for attribute-based encryption and the identity provider subsystem)
99 @item texi2mdoc (for automatic mdoc generation)
100 @item perl5 for some utilities
103 These are the test suite requirements:
106 @item gnunet (installation first)
108 @item a shell (possibly Bash, maybe just POSIX sh)
111 These are runtime requirements:
113 @item nss (the certutil binary, for gnunet-gns-proxy-setup-ca)
114 @item openssl (openssl binary, for gnunet-gns-proxy-setup-ca)
115 @item python2.7 for gnunet-qr (at the moment only python2.7 supported)
116 @item python-zbar 0.10 or above for gnunet-qr
119 @c -----------------------------------------------------------------------
120 @node Getting the Source Code
121 @section Getting the Source Code
122 You can either download the source code using git (you obviously need
123 git installed) or as an archive.
127 git clone https://git.gnunet.org/gnunet.git
130 The archive can be found at
131 @uref{https://ftpmirror.gnu.org/gnu/gnunet/}. Extract it using a graphical
132 archive tool or @code{tar}:
134 tar xzvf gnunet-@value{VERSION}.tar.gz
137 In the next chapter we will assume that the source code is available
138 in the home directory at @code{~/gnunet}.
140 @c -----------------------------------------------------------------------
141 @node Create user and groups for the system services
142 @section Create user and groups for the system services
145 For the single-user setup this section can be skipped.
148 The multi-user setup means that there are @emph{system services}, which are
149 run once per machine as a dedicated system user (called @code{gnunet}) and
150 @emph{user services} which can be started by every user who wants to use
151 GNUnet applications. The user services communicate with the system services
152 over unix domain sockets. To gain permissions to read and write those sockets
153 the users running GNUnet applications will need to be in the @code{gnunet}
154 group. In addition the group @code{gnunetdns} may be needed (see below).
156 Create user @code{gnunet} who is member of the group @code{gnunet}
157 (automatically created) and specify a home directory where the GNUnet
158 services will store persistant data such as information about peers.
160 $ sudo useradd --system --home-dir /var/lib/gnunet --create-home gnunet
163 Now add your own user to the @code{gnunet} group.
166 $ sudo usermod -aG gnunet alice
169 Create a group @code{gnunetdns}. This allows using @code{setgid} in a way
170 that only the DNS service can run the @code{gnunet-helper-dns} binary. This
171 is only needed if @emph{system-wide DNS interception} will be used. For more
172 information see @xref{Configuring system-wide DNS interception}.
175 $ sudo groupadd gnunetdns
178 @c -----------------------------------------------------------------------
179 @node Preparing and Compiling the Source Code
180 @section Preparing and Compiling the Source Code
181 For preparing the source code for compilation a bootstrap script and
182 @code{configure} has to be run from the source code directory. When
183 running @code{configure} the following options can be specified to
184 customize the compilation and installation process:
187 @item @code{--disable-documentation} - don't build the documentation
188 @item @code{--enable-looging=[LOGLEVEL]} - choose a loglevel (@code{debug}, @code{info}, @code{warning} or @code{error})
189 @item @code{--prefix=[PATH]} - the directory where the GNUnet libraries and binaries will be installed
190 @item @code{--with-extractor=[PATH]} - the path to libextractor
191 @item @code{--with-libidn=[PATH]} - the path to libidn
192 @item @code{--with-libidn2=[PATH]} - the path to libidn2 (takes priority over libidn if both are found)
193 @item @code{--with-microhttpd=[PATH]} - the path to libmicrohttpd
194 @item @code{--with-sqlite=[PATH]} - the path to libsqlite
195 @item @code{--with-zlib=[PATH]} - the path to zlib
196 @item @code{--with-sudo=[PATH]} - path to the sudo binary (no need to run @code{make install} as root if specified)
199 Note that the list above is not always up to date and you
200 should check the output of @code{./configure --help}, read
201 the @file{configure.ac} or send an email asking for assistance
202 if you are in doubt of any configure options or require fixes
203 for your operating system.
205 The following example configures the installation prefix
206 @code{/usr/lib} and disables building the documentation
210 $ configure --prefix=/usr/lib --disable-documentation
213 After running the bootstrap script and @code{configure} successfully
214 the source code can be compiled with make. Here @code{-j5} specifies
215 that 5 threads should be used.
220 @c -----------------------------------------------------------------------
222 @section Installation
223 The compiled binaries can be installed using @code{make install}. It
224 needs to be run as root (or with sudo) because some binaries need the
225 @code{suid} bit set. Without that some features (e.g. the VPN service,
226 system-wide DNS interception, NAT traversal using ICMP) will not work.
232 @node Extra installation step: NSS plugin
233 @subsection Extra installation step: NSS plugin
236 The installation of the NSS plugin is only necessary if GNS
237 resolution shall be used with legacy applications (that only
241 One important library is the GNS plugin for NSS (the name services
242 switch) which allows using GNS (the GNU name system) in the normal DNS
243 resolution process. Unfortunately NSS expects it in a specific
244 location (probably @code{/lib}) which may differ from the installation
245 prefix (see @code{--prefix} option in the previous section). This is
246 why the pugin has to be installed manually.
248 Find the directory where nss plugins are installed on your system, e.g.
251 $ ls -l /lib/libnss_*
252 /lib/libnss_mymachines.so.2
253 /lib/libnss_resolve.so.2
254 /lib/libnss_myhostname.so.2
255 /lib/libnss_systemd.so.2
258 Copy the GNS NSS plugin to that directory:
261 cp ~/gnunet/src/gns/nss/.libs/libnss_gns.so.2 /lib
264 Now, to activate the plugin, you need to edit your
265 @code{/etc/nsswitch.conf} where you should find a line like this:
268 hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
271 The exact details may differ a bit, which is fine. Add the text
272 @code{"gns [NOTFOUND=return]"} after @code{"files"}.
275 hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
278 @node Extra installation step: installing the GNS Certificate Authority
279 @subsection Extra installation step: installing the GNS Certificate Authority
282 Installing the GNS certificate authority is only necessary if GNS shall
283 be used in a browser.
286 The GNS Certificate authority can provide TLS certificates for GNS names while
287 downloading webpages from legacy webservers. This allows browsers to use HTTPS
288 in combinations with GNS name resolution.
290 To install it execute the GNS CA-setup script. So far Firefox and Chromium are
294 $ gnunet-gns-proxy-setup-ca
297 A local proxy server, that takes care of the name resolution and provides
298 certificates on-the-fly needs to be started:
301 $ /usr/lib/gnunet/libexec/gnunet-gns-proxy
304 Now GNS should work in browsers that are configured to use a SOCKS proxy on
305 @code{localhost:7777}.
308 @node Minimal configuration
309 @section Minimal configuration
310 GNUnet needs a configuration file to start. For the @emph{single-user setup}
311 an empty file is sufficient:
314 $ touch ~/.config/gnunet.conf
317 For the @emph{multi-user setup} we need an extra config file for the system
318 services. The default location is @code{/etc/gnunet.conf}. The minimal
319 content of that file which activates the system services roll is:
323 START_SYSTEM_SERVICES = YES
324 START_USER_SERVICES = NO
327 The config file for the user services (@code{~/.config/gnunet.conf}) needs
328 the opposite configuration to activate the user services roll:
332 START_SYSTEM_SERVICES = NO
333 START_USER_SERVICES = YES
337 @node Checking the Installation
338 @section Checking the Installation
341 This section describes a quick, casual way to check if your GNUnet
342 installation works. However, if it does not, we do not cover
343 steps for recovery --- for this, please study the instructions
344 provided in the developer handbook as well as the system-specific
345 instruction in the source code repository.
346 Please note that the system specific instructions are not provided
347 as part of this handbook!.
357 @cindex Starting GNUnet
360 @cindex GTK user interface
362 @node Starting GNUnet
363 @subsection Starting GNUnet
364 The GNUnet services are started and stopped by the ARM service (Automatic
365 Restart Manager). For the @emph{single-user setup} a simple
371 starts a default set of services. Later GNUnet applications can request more
372 services to start without additional user interaction. GNUnet can be stopped
373 again using the @code{-e} option:
379 The list of running services can be displayed using the @code{-I} option.
380 It should look similar to this example:
385 topology (gnunet-daemon-topology)
386 nat (gnunet-service-nat)
387 vpn (gnunet-service-vpn)
388 gns (gnunet-service-gns)
389 cadet (gnunet-service-cadet)
390 namecache (gnunet-service-namecache)
391 hostlist (gnunet-daemon-hostlist)
392 revocation (gnunet-service-revocation)
393 ats (gnunet-service-ats)
394 peerinfo (gnunet-service-peerinfo)
395 zonemaster (gnunet-service-zonemaster)
396 zonemaster-monitor (gnunet-service-zonemaster-monitor)
397 dht (gnunet-service-dht)
398 namestore (gnunet-service-namestore)
399 set (gnunet-service-set)
400 statistics (gnunet-service-statistics)
401 nse (gnunet-service-nse)
402 fs (gnunet-service-fs)
403 peerstore (gnunet-service-peerstore)
404 core (gnunet-service-core)
405 rest (gnunet-rest-server)
406 transport (gnunet-service-transport)
407 datastore (gnunet-service-datastore)
410 For the @emph{multi-user setup} first the system services need to be started
411 as the system user, i.e. the user @code{gnunet} needs to execute
412 @code{gnunet-arm -s}. This should be done by the system's init system.
416 @subsection gnunet-gtk
419 The @command{gnunet-gtk} package contains several graphical
420 user interfaces for the respective GNUnet applications.
421 Currently these interfaces cover:
425 @item Peer Information
426 @item GNU Name System
432 Previously, many of these interfaces were combined into one application
433 called @command{gnunet-gtk}, with different tabs for each interface. This
434 combined application has been removed in version 0.11.0, but each of the
435 interfaces is still available as a standalone application
436 (@command{gnunet-statistics-gtk} for statistics, @command{gnunet-fs-gtk}
437 for filesharing, etc).
440 @subsection Statistics
443 We assume that you have started gnunet via @code{gnunet-arm} or via your
444 system-provided method for starting services.
445 First, you should launch GNUnet's graphical statistics interface.
446 You can do this from the command-line by typing
449 gnunet-statistics-gtk
452 If your peer is running correctly, you should see a bunch
453 of lines, all of which should be ``significantly'' above zero (at
454 least if your peer has been running for more than a few seconds). The
455 lines indicate how many other peers your peer is connected to (via
456 different mechanisms) and how large the entire overlay network is
457 currently estimated to be. The X-axis represents time (in seconds
458 since the start of @command{gnunet-statistics-gtk}).
460 You can click on "Traffic" to see information about the amount of
461 bandwidth your peer has consumed, and on "Storage" to check the amount
462 of storage available and used by your peer. Note that "Traffic" is
463 plotted cumulatively, so you should see a strict upwards trend in the
466 The term ``peer'' is a common word used in
467 federated and distributed networks to describe a participating device
468 which is connected to the network. Thus, your Personal Computer or
469 whatever it is you are looking at the Gtk+ interface describes a
470 ``Peer'' or a ``Node''.
472 @node Peer Information
473 @subsection Peer Information
476 First, you should launch the peer information graphical user interface.
477 You can do this from the command-line by typing
480 $ gnunet-peerinfo-gtk
483 Once you have done this, you will see a list of known peers (by the
484 first four characters of their public key), their friend status (all
485 should be marked as not-friends initially), their connectivity (green
486 is connected, red is disconnected), assigned bandwidth, country of
487 origin (if determined) and address information. If hardly any peers
488 are listed and/or if there are very few peers with a green light for
489 connectivity, there is likely a problem with your network
492 @c NOTE: Inserted from Installation Handbook in original ``order'':
493 @c FIXME: Move this to User Handbook.
494 @node The graphical configuration interface
495 @section The graphical configuration interface
497 If you also would like to use @command{gnunet-gtk} and
498 @command{gnunet-setup} (highly recommended for beginners), do:
501 * Configuring your peer::
502 * Configuring the Friend-to-Friend (F2F) mode::
503 * Configuring the hostlist to bootstrap::
504 * Configuration of the HOSTLIST proxy settings::
505 * Configuring your peer to provide a hostlist ::
506 * Configuring the datastore::
507 * Configuring the MySQL database::
508 * Reasons for using MySQL::
509 * Reasons for not using MySQL::
510 * Setup Instructions::
512 * Performance Tuning::
513 * Setup for running Testcases::
514 * Configuring the Postgres database::
515 * Reasons to use Postgres::
516 * Reasons not to use Postgres::
517 * Manual setup instructions::
518 * Testing the setup manually::
519 * Configuring the datacache::
520 * Configuring the file-sharing service::
521 * Configuring logging::
522 * Configuring the transport service and plugins::
523 * Configuring the WLAN transport plugin::
524 * Configuring HTTP(S) reverse proxy functionality using Apache or nginx::
525 * Blacklisting peers::
526 * Configuration of the HTTP and HTTPS transport plugins::
527 * Configuring the GNU Name System::
528 * Configuring the GNUnet VPN::
529 * Bandwidth Configuration::
531 * Peer configuration for distributors (e.g. Operating Systems)::
534 @node Configuring your peer
535 @subsection Configuring your peer
537 This chapter will describe the various configuration options in GNUnet.
539 The easiest way to configure your peer is to use the
540 @command{gnunet-setup} tool.
541 @command{gnunet-setup} is part of the @command{gnunet-gtk}
542 package. You might have to install it separately.
544 Many of the specific sections from this chapter actually are linked from
545 within @command{gnunet-setup} to help you while using the setup tool.
547 While you can also configure your peer by editing the configuration
548 file by hand, this is not recommended for anyone except for developers
549 as it requires a more in-depth understanding of the configuration files
550 and internal dependencies of GNUnet.
552 @node Configuring the Friend-to-Friend (F2F) mode
553 @subsection Configuring the Friend-to-Friend (F2F) mode
555 GNUnet knows three basic modes of operation:
557 @item In standard "peer-to-peer" mode,
558 your peer will connect to any peer.
559 @item In the pure "friend-to-friend"
560 mode, your peer will ONLY connect to peers from a list of friends
561 specified in the configuration.
562 @item Finally, in mixed mode,
563 GNUnet will only connect to arbitrary peers if it
564 has at least a specified number of connections to friends.
567 When configuring any of the F2F ("friend-to-friend") modes,
568 you first need to create a file with the peer identities
569 of your friends. Ask your friends to run
572 $ gnunet-peerinfo -sq
576 The resulting output of this command needs to be added to your
577 @file{friends} file, which is simply a plain text file with one line
578 per friend with the output from the above command.
580 You then specify the location of your @file{friends} file in the
581 @code{FRIENDS} option of the "topology" section.
583 Once you have created the @file{friends} file, you can tell GNUnet to only
584 connect to your friends by setting the @code{FRIENDS-ONLY} option
585 (again in the "topology" section) to YES.
587 If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a
588 minimum number of friends to have (before connecting to arbitrary peers)
589 under the "MINIMUM-FRIENDS" option.
591 If you want to operate in normal P2P-only mode, simply set
592 @code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO.
595 @node Configuring the hostlist to bootstrap
596 @subsection Configuring the hostlist to bootstrap
598 After installing the software you need to get connected to the GNUnet
599 network. The configuration file included in your download is already
600 configured to connect you to the GNUnet network.
601 In this section the relevant configuration settings are explained.
603 To get an initial connection to the GNUnet network and to get to know
604 peers already connected to the network you can use the so called
606 These servers can give you a list of peers connected to the network.
607 To use these bootstrap servers you have to configure the hostlist daemon
608 to activate bootstrapping.
610 To activate bootstrapping, edit the @code{[hostlist]}-section in your
611 configuration file. You have to set the argument @command{-b} in the
619 Additionally you have to specify which server you want to use.
620 The default bootstrapping server is
621 "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}".
622 [^] To set the server you have to edit the line "SERVERS" in the hostlist
623 section. To use the default server you should set the lines to
626 SERVERS = http://v10.gnunet.org/hostlist [^]
630 To use bootstrapping your configuration file should include these lines:
635 SERVERS = http://v10.gnunet.org/hostlist [^]
639 Besides using bootstrap servers you can configure your GNUnet peer to
640 receive hostlist advertisements.
641 Peers offering hostlists to other peers can send advertisement messages
642 to peers that connect to them. If you configure your peer to receive these
643 messages, your peer can download these lists and connect to the peers
644 included. These lists are persistent, which means that they are saved to
645 your hard disk regularly and are loaded during startup.
647 To activate hostlist learning you have to add the @command{-e}
648 switch to the @code{OPTIONS} line in the hostlist section:
656 Furthermore you can specify in which file the lists are saved.
657 To save the lists in the file @file{hostlists.file} just add the line:
660 HOSTLISTFILE = hostlists.file
664 Best practice is to activate both bootstrapping and hostlist learning.
665 So your configuration file should include these lines:
671 SERVERS = http://v10.gnunet.org/hostlist [^]
672 HOSTLISTFILE = $SERVICEHOME/hostlists.file
675 @node Configuration of the HOSTLIST proxy settings
676 @subsection Configuration of the HOSTLIST proxy settings
678 The hostlist client can be configured to use a proxy to connect to the
680 This functionality can be configured in the configuration file directly
681 or using the @command{gnunet-setup} tool.
683 The hostlist client supports the following proxy types at the moment:
686 @item HTTP and HTTP 1.0 only proxy
687 @item SOCKS 4/4a/5/5 with hostname
690 In addition authentication at the proxy with username and password can be
693 To configure proxy support for the hostlist client in the
694 @command{gnunet-setup} tool, select the "hostlist" tab and select
695 the appropriate proxy type.
696 The hostname or IP address (including port if required) has to be entered
697 in the "Proxy hostname" textbox. If required, enter username and password
698 in the "Proxy username" and "Proxy password" boxes.
699 Be aware that this information will be stored in the configuration in
700 plain text (TODO: Add explanation and generalize the part in Chapter 3.6
701 about the encrypted home).
703 To provide these options directly in the configuration, you can
704 enter the following settings in the @code{[hostlist]} section of
708 # Type of proxy server,
709 # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME
713 # Hostname or IP of proxy server
715 # User name for proxy server
717 # User password for proxy server
721 @node Configuring your peer to provide a hostlist
722 @subsection Configuring your peer to provide a hostlist
724 If you operate a peer permanently connected to GNUnet you can configure
725 your peer to act as a hostlist server, providing other peers the list of
728 Your server can act as a bootstrap server and peers needing to obtain a
729 list of peers can contact it to download this list.
730 To download this hostlist the peer uses HTTP.
731 For this reason you have to build your peer with libgnurl (or libcurl)
732 and microhttpd support.
734 To configure your peer to act as a bootstrap server you have to add the
735 @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section
736 of your configuration file.
737 Besides that you have to specify a port number for the http server.
738 In conclusion you have to add the following lines:
747 If your peer acts as a bootstrap server other peers should know about
748 that. You can advertise the hostlist your are providing to other peers.
749 Peers connecting to your peer will get a message containing an
750 advertisement for your hostlist and the URL where it can be downloaded.
751 If this peer is in learning mode, it will test the hostlist and, in the
752 case it can obtain the list successfully, it will save it for
755 To activate hostlist advertisement on your peer, you have to set the
756 following lines in your configuration file:
760 EXTERNAL_DNS_NAME = example.org
766 With this configuration your peer will a act as a bootstrap server and
767 advertise this hostlist to other peers connecting to it.
768 The URL used to download the list will be
769 @code{@uref{http://example.org:12981/, http://example.org:12981/}}.
774 @item The hostlist is @b{not} human readable, so you should not try to
775 download it using your webbrowser. Just point your GNUnet peer to the
777 @item Advertising without providing a hostlist does not make sense and
781 @node Configuring the datastore
782 @subsection Configuring the datastore
784 The datastore is what GNUnet uses for long-term storage of file-sharing
785 data. Note that long-term does not mean 'forever' since content does have
786 an expiration date, and of course storage space is finite (and hence
787 sometimes content may have to be discarded).
789 Use the @code{QUOTA} option to specify how many bytes of storage space
790 you are willing to dedicate to GNUnet.
792 In addition to specifying the maximum space GNUnet is allowed to use for
793 the datastore, you need to specify which database GNUnet should use to do
794 so. Currently, you have the choice between sqLite, MySQL and Postgres.
796 @node Configuring the MySQL database
797 @subsection Configuring the MySQL database
799 This section describes how to setup the MySQL database for GNUnet.
801 Note that the mysql plugin does NOT work with mysql before 4.1 since we
802 need prepared statements.
803 We are generally testing the code against MySQL 5.1 at this point.
805 @node Reasons for using MySQL
806 @subsection Reasons for using MySQL
810 @item On up-to-date hardware wher
811 mysql can be used comfortably, this module
812 will have better performance than the other database choices (according
815 @item Its often possible to recover the mysql database from internal
816 inconsistencies. Some of the other databases do not support repair.
819 @node Reasons for not using MySQL
820 @subsection Reasons for not using MySQL
823 @item Memory usage (likely not an issue if you have more than 1 GB)
824 @item Complex manual setup
827 @node Setup Instructions
828 @subsection Setup Instructions
832 @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
833 @code{DATABASE} to @code{mysql}.
835 @item Access mysql as root:
842 and issue the following commands, replacing $USER with the username
843 that will be running @command{gnunet-arm} (so typically "gnunet"):
846 CREATE DATABASE gnunet;
847 GRANT select,insert,update,delete,create,alter,drop,create \
848 temporary tables ON gnunet.* TO $USER@@localhost;
849 SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like');
854 In the $HOME directory of $USER, create a @file{.my.cnf} file with the
860 password=$the_password_you_like
865 That's it. Note that @file{.my.cnf} file is a slight security risk unless
866 its on a safe partition. The @file{$HOME/.my.cnf} can of course be
868 Luckily $USER has only privileges to mess up GNUnet's tables,
869 which should be pretty harmless.
874 You should briefly try if the database connection works. First, login
883 If you get the message
895 ERROR 2002: Can't connect to local MySQL server
896 through socket '/tmp/mysql.sock' (2)
900 it may be resolvable by
903 ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock
907 so there may be some additional trouble depending on your mysql setup.
909 @node Performance Tuning
910 @subsection Performance Tuning
912 For GNUnet, you probably want to set the option
915 innodb_flush_log_at_trx_commit = 0
919 for a rather dramatic boost in MySQL performance. However, this reduces
920 the "safety" of your database as with this options you may loose
921 transactions during a power outage.
922 While this is totally harmless for GNUnet, the option applies to all
923 applications using MySQL. So you should set it if (and only if) GNUnet is
924 the only application on your system using MySQL.
926 @node Setup for running Testcases
927 @subsection Setup for running Testcases
929 If you want to run the testcases, you must create a second database
930 "gnunetcheck" with the same username and password. This database will
931 then be used for testing (@command{make check}).
933 @node Configuring the Postgres database
934 @subsection Configuring the Postgres database
936 This text describes how to setup the Postgres database for GNUnet.
938 This Postgres plugin was developed for Postgres 8.3 but might work for
939 earlier versions as well.
941 @node Reasons to use Postgres
942 @subsection Reasons to use Postgres
945 @item Easier to setup than MySQL
949 @node Reasons not to use Postgres
950 @subsection Reasons not to use Postgres
954 @item Still some manual setup required
957 @node Manual setup instructions
958 @subsection Manual setup instructions
961 @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
962 @code{DATABASE} to @code{postgres}.
963 @item Access Postgres to create a user:
966 @item with Postgres 8.x, use:
974 and enter the name of the user running GNUnet for the role interactively.
975 Then, when prompted, do not set it to superuser, allow the creation of
976 databases, and do not allow the creation of new roles.
978 @item with Postgres 9.x, use:
982 $ createuser -d $GNUNET_USER
986 where $GNUNET_USER is the name of the user running GNUnet.
992 As that user (so typically as user "gnunet"), create a database (or two):
996 # this way you can run "make check"
997 $ createdb gnunetcheck
1002 Now you should be able to start @code{gnunet-arm}.
1004 @node Testing the setup manually
1005 @subsection Testing the setup manually
1007 You may want to try if the database connection works. First, again login
1008 as the user who will run @command{gnunet-arm}. Then use:
1011 $ psql gnunet # or gnunetcheck
1016 If, after you have started @command{gnunet-arm} at least once, you get
1017 a @code{gn090} table here, it probably works.
1019 @node Configuring the datacache
1020 @subsection Configuring the datacache
1023 The datacache is what GNUnet uses for storing temporary data. This data is
1024 expected to be wiped completely each time GNUnet is restarted (or the
1025 system is rebooted).
1027 You need to specify how many bytes GNUnet is allowed to use for the
1028 datacache using the @code{QUOTA} option in the section @code{[dhtcache]}.
1029 Furthermore, you need to specify which database backend should be used to
1030 store the data. Currently, you have the choice between
1031 sqLite, MySQL and Postgres.
1033 @node Configuring the file-sharing service
1034 @subsection Configuring the file-sharing service
1036 In order to use GNUnet for file-sharing, you first need to make sure
1037 that the file-sharing service is loaded.
1038 This is done by setting the @code{START_ON_DEMAND} option in
1039 section @code{[fs]} to "YES". Alternatively, you can run
1046 to start the file-sharing service by hand.
1048 Except for configuring the database and the datacache the only important
1049 option for file-sharing is content migration.
1051 Content migration allows your peer to cache content from other peers as
1052 well as send out content stored on your system without explicit requests.
1053 This content replication has positive and negative impacts on both system
1054 performance and privacy.
1056 FIXME: discuss the trade-offs. Here is some older text about it...
1058 Setting this option to YES allows gnunetd to migrate data to the local
1059 machine. Setting this option to YES is highly recommended for efficiency.
1060 Its also the default. If you set this value to YES, GNUnet will store
1061 content on your machine that you cannot decrypt.
1062 While this may protect you from liability if the judge is sane, it may
1063 not (IANAL). If you put illegal content on your machine yourself, setting
1064 this option to YES will probably increase your chances to get away with it
1065 since you can plausibly deny that you inserted the content.
1066 Note that in either case, your anonymity would have to be broken first
1067 (which may be possible depending on the size of the GNUnet network and the
1068 strength of the adversary).
1070 @node Configuring logging
1071 @subsection Configuring logging
1073 Since version 0.9.0, logging in GNUnet is controlled via the
1074 @code{-L} and @code{-l} options.
1075 Using @code{-L}, a log level can be specified. With log level
1076 @code{ERROR} only serious errors are logged.
1077 The default log level is @code{WARNING} which causes anything of
1078 concern to be logged.
1079 Log level @code{INFO} can be used to log anything that might be
1080 interesting information whereas
1081 @code{DEBUG} can be used by developers to log debugging messages
1082 (but you need to run @code{./configure} with
1083 @code{--enable-logging=verbose} to get them compiled).
1084 The @code{-l} option is used to specify the log file.
1086 Since most GNUnet services are managed by @code{gnunet-arm}, using the
1087 @code{-l} or @code{-L} options directly is not possible.
1088 Instead, they can be specified using the @code{OPTIONS} configuration
1089 value in the respective section for the respective service.
1090 In order to enable logging globally without editing the @code{OPTIONS}
1091 values for each service, @command{gnunet-arm} supports a
1092 @code{GLOBAL_POSTFIX} option.
1093 The value specified here is given as an extra option to all services for
1094 which the configuration does contain a service-specific @code{OPTIONS}
1097 @code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which
1098 is replaced by the name of the service that is being started.
1099 Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences
1100 starting with "$" anywhere in the string are expanded (according
1101 to options in @code{PATHS}); this expansion otherwise is
1102 only happening for filenames and then the "$" must be the
1103 first character in the option. Both of these restrictions do
1104 not apply to @code{GLOBAL_POSTFIX}.
1105 Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX}
1106 disables both of these features.
1108 In summary, in order to get all services to log at level
1109 @code{INFO} to log-files called @code{SERVICENAME-logs}, the
1110 following global prefix should be used:
1113 GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO
1116 @node Configuring the transport service and plugins
1117 @subsection Configuring the transport service and plugins
1119 The transport service in GNUnet is responsible to maintain basic
1120 connectivity to other peers.
1121 Besides initiating and keeping connections alive it is also responsible
1122 for address validation.
1124 The GNUnet transport supports more than one transport protocol.
1125 These protocols are configured together with the transport service.
1127 The configuration section for the transport service itself is quite
1128 similar to all the other services
1131 START_ON_DEMAND = YES
1132 @@UNIXONLY@@ PORT = 2091
1133 HOSTNAME = localhost
1135 CONFIG = $DEFAULTCONFIG
1136 BINARY = gnunet-service-transport
1138 NEIGHBOUR_LIMIT = 50
1139 ACCEPT_FROM = 127.0.0.1;
1142 UNIXPATH = /tmp/gnunet-service-transport.sock
1145 Different are the settings for the plugins to load @code{PLUGINS}.
1146 The first setting specifies which transport plugins to load.
1149 @item transport-unix
1150 A plugin for local only communication with UNIX domain sockets. Used for
1151 testing and available on unix systems only. Just set the port
1156 TESTING_IGNORE_KEYS = ACCEPT_FROM;
1160 A plugin for communication with TCP. Set port to 0 for client mode with
1161 outbound only connections
1165 # Use 0 to ONLY advertise as a peer behind NAT (no port binding)
1167 ADVERTISED_PORT = 2086
1168 TESTING_IGNORE_KEYS = ACCEPT_FROM;
1169 # Maximum number of open TCP connections allowed
1170 MAX_CONNECTIONS = 128
1174 A plugin for communication with UDP. Supports peer discovery using
1181 BROADCAST_INTERVAL = 30 s
1183 TESTING_IGNORE_KEYS = ACCEPT_FROM;
1186 @item transport-http
1187 HTTP and HTTPS support is split in two part: a client plugin initiating
1188 outbound connections and a server part accepting connections from the
1189 client. The client plugin just takes the maximum number of connections as
1193 [transport-http_client]
1194 MAX_CONNECTIONS = 128
1195 TESTING_IGNORE_KEYS = ACCEPT_FROM;
1199 [transport-https_client]
1200 MAX_CONNECTIONS = 128
1201 TESTING_IGNORE_KEYS = ACCEPT_FROM;
1205 The server has a port configured and the maximum number of connections.
1206 The HTTPS part has two files with the certificate key and the certificate
1209 The server plugin supports reverse proxies, so a external hostname can be
1210 set using the @code{EXTERNAL_HOSTNAME} setting.
1211 The webserver under this address should forward the request to the peer
1212 and the configure port.
1215 [transport-http_server]
1216 EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet
1218 MAX_CONNECTIONS = 128
1219 TESTING_IGNORE_KEYS = ACCEPT_FROM;
1223 [transport-https_server]
1225 CRYPTO_INIT = NORMAL
1226 KEY_FILE = https.key
1227 CERT_FILE = https.cert
1228 MAX_CONNECTIONS = 128
1229 TESTING_IGNORE_KEYS = ACCEPT_FROM;
1232 @item transport-wlan
1234 The next section describes how to setup the WLAN plugin,
1235 so here only the settings. Just specify the interface to use:
1239 # Name of the interface in monitor mode (typically monX)
1241 # Real hardware, no testing
1243 TESTING_IGNORE_KEYS = ACCEPT_FROM;
1247 @node Configuring the WLAN transport plugin
1248 @subsection Configuring the WLAN transport plugin
1250 The wlan transport plugin enables GNUnet to send and to receive data on a
1252 It has not to be connected to a wlan network as long as sender and
1253 receiver are on the same channel. This enables you to get connection to
1254 GNUnet where no internet access is possible, for example during
1255 catastrophes or when censorship cuts you off from the internet.
1259 * Requirements for the WLAN plugin::
1261 * Before starting GNUnet::
1262 * Limitations and known bugs::
1266 @node Requirements for the WLAN plugin
1267 @subsubsection Requirements for the WLAN plugin
1271 @item wlan network card with monitor support and packet injection
1272 (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org})
1274 @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with
1277 @item Wlantools to create the a monitor interface, tested with airmon-ng
1278 of the aircrack-ng package
1282 @subsubsection Configuration
1284 There are the following options for the wlan plugin (they should be like
1285 this in your default config file, you only need to adjust them if the
1286 values are incorrect for your system)
1289 # section for the wlan transport plugin
1291 # interface to use, more information in the
1292 # "Before starting GNUnet" section of the handbook.
1294 # testmode for developers:
1295 # 0 use wlan interface,
1296 #1 or 2 use loopback driver for tests 1 = server, 2 = client
1300 @node Before starting GNUnet
1301 @subsubsection Before starting GNUnet
1303 Before starting GNUnet, you have to make sure that your wlan interface is
1305 One way to put the wlan interface into monitor mode (if your interface
1306 name is wlan0) is by executing:
1309 sudo airmon-ng start wlan0
1313 Here is an example what the result should look like:
1316 Interface Chipset Driver
1317 wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]
1318 (monitor mode enabled on mon0)
1322 The monitor interface is mon0 is the one that you have to put into the
1325 @node Limitations and known bugs
1326 @subsubsection Limitations and known bugs
1328 Wlan speed is at the maximum of 1 Mbit/s because support for choosing the
1329 wlan speed with packet injection was removed in newer kernels.
1330 Please pester the kernel developers about fixing this.
1332 The interface channel depends on the wlan network that the card is
1333 connected to. If no connection has been made since the start of the
1334 computer, it is usually the first channel of the card.
1335 Peers will only find each other and communicate if they are on the same
1336 channel. Channels must be set manually, i.e. using:
1339 iwconfig wlan0 channel 1
1342 @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx
1343 @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
1345 The HTTP plugin supports data transfer using reverse proxies. A reverse
1346 proxy forwards the HTTP request he receives with a certain URL to another
1347 webserver, here a GNUnet peer.
1349 So if you have a running Apache or nginx webserver you can configure it to
1350 be a GNUnet reverse proxy. Especially if you have a well-known webiste
1351 this improves censorship resistance since it looks as normal surfing
1354 To do so, you have to do two things:
1357 @item Configure your webserver to forward the GNUnet HTTP traffic
1358 @item Configure your GNUnet peer to announce the respective address
1361 As an example we want to use GNUnet peer running:
1365 @item HTTP server plugin on @code{gnunet.foo.org:1080}
1367 @item HTTPS server plugin on @code{gnunet.foo.org:4433}
1369 @item A apache or nginx webserver on
1370 @uref{http://www.foo.org/, http://www.foo.org:80/}
1372 @item A apache or nginx webserver on https://www.foo.org:443/
1375 And we want the webserver to accept GNUnet traffic under
1376 @code{http://www.foo.org/bar/}. The required steps are described here:
1379 * Reverse Proxy - Configure your Apache2 HTTP webserver::
1380 * Reverse Proxy - Configure your Apache2 HTTPS webserver::
1381 * Reverse Proxy - Configure your nginx HTTPS webserver::
1382 * Reverse Proxy - Configure your nginx HTTP webserver::
1383 * Reverse Proxy - Configure your GNUnet peer::
1386 @node Reverse Proxy - Configure your Apache2 HTTP webserver
1387 @subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver
1389 First of all you need mod_proxy installed.
1391 Edit your webserver configuration. Edit
1392 @code{/etc/apache2/apache2.conf} or the site-specific configuration file.
1394 In the respective @code{server config},@code{virtual host} or
1395 @code{directory} section add the following lines:
1401 ProxyPass http://gnunet.foo.org:1080/
1402 ProxyPassReverse http://gnunet.foo.org:1080/
1406 @node Reverse Proxy - Configure your Apache2 HTTPS webserver
1407 @subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver
1409 We assume that you already have an HTTPS server running, if not please
1410 check how to configure a HTTPS host. An uncomplicated to use example
1411 is the example configuration file for Apache2/HTTPD provided in
1412 @file{apache2/sites-available/default-ssl}.
1414 In the respective HTTPS @code{server config},@code{virtual host} or
1415 @code{directory} section add the following lines:
1422 ProxyPass https://gnunet.foo.org:4433/
1423 ProxyPassReverse https://gnunet.foo.org:4433/
1428 More information about the apache mod_proxy configuration can be found
1430 @uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, Apache documentation}.
1432 @node Reverse Proxy - Configure your nginx HTTPS webserver
1433 @subsubsection Reverse Proxy - Configure your nginx HTTPS webserver
1435 Since nginx does not support chunked encoding, you first of all have to
1436 install the @code{chunkin}
1437 @uref{http://wiki.nginx.org/HttpChunkinModule, module}.
1439 To enable chunkin add:
1443 error_page 411 = @@my_411_error;
1444 location @@my_411_error @{
1450 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
1451 the site-specific configuration file.
1453 In the @code{server} section add:
1457 proxy_pass http://gnunet.foo.org:1080/;
1458 proxy_buffering off;
1459 proxy_connect_timeout 5; # more than http_server
1460 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout
1461 proxy_http_version 1.1; # 1.0 default
1462 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;
1466 @node Reverse Proxy - Configure your nginx HTTP webserver
1467 @subsubsection Reverse Proxy - Configure your nginx HTTP webserver
1469 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
1470 the site-specific configuration file.
1472 In the @code{server} section add:
1475 ssl_session_timeout 6m;
1478 proxy_pass https://gnunet.foo.org:4433/;
1479 proxy_buffering off;
1480 proxy_connect_timeout 5; # more than http_server
1481 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout
1482 proxy_http_version 1.1; # 1.0 default
1483 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;
1487 @node Reverse Proxy - Configure your GNUnet peer
1488 @subsubsection Reverse Proxy - Configure your GNUnet peer
1490 To have your GNUnet peer announce the address, you have to specify the
1491 @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]}
1495 [transport-http_server]
1496 EXTERNAL_HOSTNAME = http://www.foo.org/bar/
1500 and/or @code{[transport-https_server]} section:
1503 [transport-https_server]
1504 EXTERNAL_HOSTNAME = https://www.foo.org/bar/
1508 Now restart your webserver and your peer...
1510 @node Blacklisting peers
1511 @subsection Blacklisting peers
1513 Transport service supports to deny connecting to a specific peer of to a
1514 specific peer with a specific transport plugin using te blacklisting
1515 component of transport service. With@ blacklisting it is possible to deny
1516 connections to specific peers of@ to use a specific plugin to a specific
1517 peer. Peers can be blacklisted using@ the configuration or a blacklist
1518 client can be asked.
1520 To blacklist peers using the configuration you have to add a section to
1521 your configuration containing the peer id of the peer to blacklist and
1522 the plugin@ if required.
1526 To blacklist connections to P565... on peer AG2P... using tcp add:
1528 @c FIXME: This is too long and produces errors in the pdf.
1530 [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
1531 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp
1534 To blacklist connections to P565... on peer AG2P... using all plugins add:
1537 [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
1538 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =
1541 You can also add a blacklist client usign the blacklist API. On a
1542 blacklist check, blacklisting first checks internally if the peer is
1543 blacklisted and if not, it asks the blacklisting clients. Clients are
1544 asked if it is OK to connect to a peer ID, the plugin is omitted.
1546 On blacklist check for (peer, plugin)
1549 @item Do we have a local blacklist entry for this peer and this plugin?
1550 @item YES: disallow connection
1551 @item Do we have a local blacklist entry for this peer and all plugins?
1552 @item YES: disallow connection
1553 @item Does one of the clients disallow?
1554 @item YES: disallow connection
1557 @node Configuration of the HTTP and HTTPS transport plugins
1558 @subsection Configuration of the HTTP and HTTPS transport plugins
1560 The client parts of the http and https transport plugins can be configured
1561 to use a proxy to connect to the hostlist server. This functionality can
1562 be configured in the configuration file directly or using the
1565 Both the HTTP and HTTPS clients support the following proxy types at
1569 @item HTTP 1.1 proxy
1570 @item SOCKS 4/4a/5/5 with hostname
1573 In addition authentication at the proxy with username and password can be
1576 To configure proxy support for the clients in the gnunet-setup tool,
1577 select the "transport" tab and activate the respective plugin. Now you
1578 can select the appropriate proxy type. The hostname or IP address
1579 (including port if required) has to be entered in the "Proxy hostname"
1580 textbox. If required, enter username and password in the "Proxy username"
1581 and "Proxy password" boxes. Be aware that these information will be stored
1582 in the configuration in plain text.
1584 To configure these options directly in the configuration, you can
1585 configure the following settings in the @code{[transport-http_client]}
1586 and @code{[transport-https_client]} section of the configuration:
1589 # Type of proxy server,
1590 # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME
1594 # Hostname or IP of proxy server
1596 # User name for proxy server
1598 # User password for proxy server
1602 @node Configuring the GNU Name System
1603 @subsection Configuring the GNU Name System
1606 * Configuring system-wide DNS interception::
1607 * Configuring the GNS nsswitch plugin::
1608 * Configuring GNS on W32::
1610 * Setup of the GNS CA::
1611 * Testing the GNS setup::
1612 * Migrating existing DNS zones into GNS::
1616 @node Configuring system-wide DNS interception
1617 @subsubsection Configuring system-wide DNS interception
1619 Before you install GNUnet, make sure you have a user and group 'gnunet'
1620 as well as an empty group 'gnunetdns'.
1622 When using GNUnet with system-wide DNS interception, it is absolutely
1623 necessary for all GNUnet service processes to be started by
1624 @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be
1625 sure to run @code{make install} as root (or use the @code{sudo} option to
1626 configure) to grant GNUnet sufficient privileges.
1628 With this setup, all that is required for enabling system-wide DNS
1629 interception is for some GNUnet component (VPN or GNS) to request it.
1630 The @code{gnunet-service-dns} will then start helper programs that will
1631 make the necessary changes to your firewall (@code{iptables}) rules.
1633 Note that this will NOT work if your system sends out DNS traffic to a
1634 link-local IPv6 address, as in this case GNUnet can intercept the traffic,
1635 but not inject the responses from the link-local IPv6 address. Hence you
1636 cannot use system-wide DNS interception in conjunction with link-local
1637 IPv6-based DNS servers. If such a DNS server is used, it will bypass
1638 GNUnet's DNS traffic interception.
1640 Using the GNU Name System (GNS) requires two different configuration
1642 First of all, GNS needs to be integrated with the operating system. Most
1643 of this section is about the operating system level integration.
1645 The remainder of this chapter will detail the various methods for
1646 configuring the use of GNS with your operating system.
1648 At this point in time you have different options depending on your OS:
1651 @item Use the gnunet-gns-proxy@*
1652 This approach works for all operating systems and is likely the
1653 easiest. However, it enables GNS only for browsers, not for other
1654 applications that might be using DNS, such as SSH. Still, using the
1655 proxy is required for using HTTP with GNS and is thus recommended for
1656 all users. To do this, you simply have to run the
1657 @code{gnunet-gns-proxy-setup-ca} script as the user who will run the
1658 browser (this will create a GNS certificate authority (CA) on your
1659 system and import its key into your browser), then start
1660 @code{gnunet-gns-proxy} and inform your browser to use the Socks5
1661 proxy which @code{gnunet-gns-proxy} makes available by default on port
1663 @item Use a nsswitch plugin (recommended on GNU systems)@*
1664 This approach has the advantage of offering fully personalized
1665 resolution even on multi-user systems. A potential disadvantage is
1666 that some applications might be able to bypass GNS.
1667 @item Use a W32 resolver plugin (recommended on W32)@*
1668 This is currently the only option on W32 systems.
1669 @item Use system-wide DNS packet interception@*
1670 This approach is recommended for the GNUnet VPN. It can be used to
1671 handle GNS at the same time; however, if you only use this method, you
1672 will only get one root zone per machine (not so great for multi-user
1676 You can combine system-wide DNS packet interception with the nsswitch
1678 The setup of the system-wide DNS interception is described here. All of
1679 the other GNS-specific configuration steps are described in the following
1682 @node Configuring the GNS nsswitch plugin
1683 @subsubsection Configuring the GNS nsswitch plugin
1685 The Name Service Switch (NSS) is a facility in Unix-like operating systems
1686 (in most cases provided by the GNU C Library)
1687 that provides a variety of sources for common configuration databases and
1688 name resolution mechanisms.
1689 A superuser (system administrator) usually configures the
1690 operating system's name services using the file
1691 @file{/etc/nsswitch.conf}.
1693 GNS provides a NSS plugin to integrate GNS name resolution with the
1694 operating system's name resolution process.
1695 To use the GNS NSS plugin you have to either
1698 @item install GNUnet as root or
1699 @item compile GNUnet with the @code{--with-sudo=yes} switch.
1702 Name resolution is controlled by the @emph{hosts} section in the NSS
1703 configuration. By default this section first performs a lookup in the
1704 @file{/etc/hosts} file and then in DNS.
1705 The nsswitch file should contain a line similar to:
1708 hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4
1712 Here the GNS NSS plugin can be added to perform a GNS lookup before
1713 performing a DNS lookup.
1714 The GNS NSS plugin has to be added to the "hosts" section in
1715 @file{/etc/nsswitch.conf} file before DNS related plugins:
1719 hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4
1724 The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not
1725 found in GNS it will not be queried in DNS.
1727 @node Configuring GNS on W32
1728 @subsubsection Configuring GNS on W32
1730 This document is a guide to configuring GNU Name System on W32-compatible
1733 After GNUnet is installed, run the w32nsp-install tool:
1736 w32nsp-install.exe libw32nsp-0.dll
1740 ('0' is the library version of W32 NSP; it might increase in the future,
1741 change the invocation accordingly).
1743 This will install GNS namespace provider into the system and allow other
1744 applications to resolve names that end in '@strong{gnu}'
1745 and '@strong{zkey}'. Note that namespace provider requires
1746 gnunet-gns-helper-service-w32 to be running, as well as gns service
1747 itself (and its usual dependencies).
1749 Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353},
1750 and this is where gnunet-gns-helper-service-w32 should be listening to
1751 (and is configured to listen to by default).
1753 To uninstall the provider, run:
1756 w32nsp-uninstall.exe
1760 (uses provider GUID to uninstall it, does not need a dll name).
1762 Note that while MSDN claims that other applications will only be able to
1763 use the new namespace provider after re-starting, in reality they might
1764 stat to use it without that. Conversely, they might stop using the
1765 provider after it's been uninstalled, even if they were not re-started.
1766 W32 will not permit namespace provider library to be deleted or
1767 overwritten while the provider is installed, and while there is at least
1768 one process still using it (even after it was uninstalled).
1770 @node GNS Proxy Setup
1771 @subsubsection GNS Proxy Setup
1773 When using the GNU Name System (GNS) to browse the WWW, there are several
1774 issues that can be solved by adding the GNS Proxy to your setup:
1778 @item If the target website does not support GNS, it might assume that it
1779 is operating under some name in the legacy DNS system (such as
1780 example.com). It may then attempt to set cookies for that domain, and the
1781 web server might expect a @code{Host: example.com} header in the request
1783 However, your browser might be using @code{example.gnu} for the
1784 @code{Host} header and might only accept (and send) cookies for
1785 @code{example.gnu}. The GNS Proxy will perform the necessary translations
1786 of the hostnames for cookies and HTTP headers (using the LEHO record for
1787 the target domain as the desired substitute).
1789 @item If using HTTPS, the target site might include an SSL certificate
1790 which is either only valid for the LEHO domain or might match a TLSA
1791 record in GNS. However, your browser would expect a valid certificate for
1792 @code{example.gnu}, not for some legacy domain name. The proxy will
1793 validate the certificate (either against LEHO or TLSA) and then
1794 on-the-fly produce a valid certificate for the exchange, signed by your
1795 own CA. Assuming you installed the CA of your proxy in your browser's
1796 certificate authority list, your browser will then trust the
1797 HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy.
1799 @item Finally, the proxy will in the future indicate to the server that it
1800 speaks GNS, which will enable server operators to deliver GNS-enabled web
1801 sites to your browser (and continue to deliver legacy links to legacy
1805 @node Setup of the GNS CA
1806 @subsubsection Setup of the GNS CA
1808 First you need to create a CA certificate that the proxy can use.
1809 To do so use the provided script gnunet-gns-proxy-ca:
1812 $ gnunet-gns-proxy-setup-ca
1816 This will create a personal certification authority for you and add this
1817 authority to the firefox and chrome database. The proxy will use the this
1818 CA certificate to generate @code{*.gnu} client certificates on the fly.
1820 Note that the proxy uses libcurl. Make sure your version of libcurl uses
1821 GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled
1824 You can check the configuration your libcurl was build with by
1831 the output will look like this (without the linebreaks):
1835 curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \
1836 GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4
1837 Release-Date: 2017-10-08
1838 Protocols: http https
1839 Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \
1840 TLS-SRP UnixSockets HTTPS-proxy
1843 @node Testing the GNS setup
1844 @subsubsection Testing the GNS setup
1846 Now for testing purposes we can create some records in our zone to test
1847 the SSL functionality of the proxy:
1850 $ gnunet-identity -C test
1851 $ gnunet-namestore -a -e "1 d" -n "homepage" \
1852 -t A -V 131.159.74.67 -z test
1853 $ gnunet-namestore -a -e "1 d" -n "homepage" \
1854 -t LEHO -V "gnunet.org" -z test
1858 At this point we can start the proxy. Simply execute
1861 $ gnunet-arm -i gns-proxy
1864 To run the proxy at all times in the future, you should
1865 change your configuration as follows:
1868 $ gnunet-config -s gns-proxy -o AUTOSTART -V YES
1872 Configure your browser to use this SOCKSv5 proxy using
1873 @code{localhost} on port 7777.
1874 If you use @command{Firefox} (or one of its derivatives/forks such as
1875 Icecat) you also have to go to @code{about:config} and set the key
1876 @code{network.proxy.socks_remote_dns} to @code{true}.
1878 When you visit @code{https://homepage.test/}, you should get to the
1879 @code{https://gnunet.org/} frontpage and the browser (with the correctly
1880 configured proxy) should give you a valid SSL certificate for
1881 @code{homepage.gnu} and no warnings. It should look like this:
1883 @c FIXME: Image does not exist, create it or save it from Drupal?
1884 @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser}
1886 @node Migrating existing DNS zones into GNS
1887 @subsubsection Migrating existing DNS zones into GNS
1889 To migrate an existing zone into GNS use the Ascension tool.
1891 Ascension transfers entire zones into GNS by doing incremental zone transfers
1892 and then adding the records to GNS.
1894 Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending
1895 on whether or not there exists a SOA record for the zone. If that is the case it
1896 will take the serial as a reference point and request the zone. The server will
1897 either answer the IXFR request with a correct incremental zone or with the
1898 entire zone, which depends on the server configuration.
1900 You can find the source code here: @code{https://git.gnunet.org/ascension.git/}
1902 The software can be installed into a Python virtual environment like this:
1904 $ python3 -m venv .venv
1905 $ source .venv/bin/activate
1906 $ python3 setup.py install
1909 Or installed globally like this:
1911 $ sudo python3 setup.py install
1914 Pip will then install all the necessary requirements that are needed to run
1915 Ascension. For development purposes a virtual environment should suffice.
1916 Keeping a virtual environment helps with keeping things tidy and prevents
1917 breaking of Ascension through a future Python update.
1919 The advantage of using a virtual environment is, that all the dependencies can
1920 be installed separately in different versions without touching your systems
1921 Python installation and its dependencies.
1923 Another way to install Ascension on Debian is to install the python3-ascension
1924 package. It can be found within the above mentioned Ascension git repository.
1925 This also adds a system user ascension and runs a GNUnet peer in the
1926 background. Attention: This only works if a recent version of GNUnet is
1927 installed on your system. The version number of Ascension is chosen according
1928 to the required feature level of GNUnet. I.e. Ascension 0.11.5 is only
1929 compatible with GNUnet 0.11.5 and upwards. As Debian's packages for GNUnet are
1930 outdated even in experimental, you will need to install GNUnet manually.
1931 @xref{Installing GNUnet}
1933 Please check @xref{Migrating an existing DNS zone into GNS}, for usage manual
1936 @node Configuring the GNUnet VPN
1937 @subsection Configuring the GNUnet VPN
1940 * IPv4 address for interface::
1941 * IPv6 address for interface::
1942 * Configuring the GNUnet VPN DNS::
1943 * Configuring the GNUnet VPN Exit Service::
1944 * IP Address of external DNS resolver::
1945 * IPv4 address for Exit interface::
1946 * IPv6 address for Exit interface::
1949 Before configuring the GNUnet VPN, please make sure that system-wide DNS
1950 interception is configured properly as described in the section on the
1951 GNUnet DNS setup. @pxref{Configuring the GNU Name System},
1952 if you haven't done so already.
1954 The default options for the GNUnet VPN are usually sufficient to use
1955 GNUnet as a Layer 2 for your Internet connection.
1956 However, what you always have to specify is which IP protocol you want
1957 to tunnel: IPv4, IPv6 or both.
1958 Furthermore, if you tunnel both, you most likely should also tunnel
1959 all of your DNS requests.
1960 You theoretically can tunnel "only" your DNS traffic, but that usually
1963 The other options as shown on the gnunet-setup tool are:
1965 @node IPv4 address for interface
1966 @subsubsection IPv4 address for interface
1968 This is the IPv4 address the VPN interface will get. You should pick a
1969 'private' IPv4 network that is not yet in use for you system. For example,
1970 if you use @code{10.0.0.1/255.255.0.0} already, you might use
1971 @code{10.1.0.1/255.255.0.0}.
1972 If you use @code{10.0.0.1/255.0.0.0} already, then you might use
1973 @code{192.168.0.1/255.255.0.0}.
1974 If your system is not in a private IP-network, using any of the above will
1976 You should try to make the mask of the address big enough
1977 (@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more
1978 mappings of remote IP Addresses into this range.
1979 However, even a @code{255.255.255.0} mask will suffice for most users.
1981 @node IPv6 address for interface
1982 @subsubsection IPv6 address for interface
1984 The IPv6 address the VPN interface will get. Here you can specify any
1985 non-link-local address (the address should not begin with @code{fe80:}).
1986 A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are
1987 currently not using would be a good choice.
1989 @node Configuring the GNUnet VPN DNS
1990 @subsubsection Configuring the GNUnet VPN DNS
1992 To resolve names for remote nodes, activate the DNS exit option.
1994 @node Configuring the GNUnet VPN Exit Service
1995 @subsubsection Configuring the GNUnet VPN Exit Service
1997 If you want to allow other users to share your Internet connection (yes,
1998 this may be dangerous, just as running a Tor exit node) or want to
1999 provide access to services on your host (this should be less dangerous,
2000 as long as those services are secure), you have to enable the GNUnet exit
2003 You then get to specify which exit functions you want to provide. By
2004 enabling the exit daemon, you will always automatically provide exit
2005 functions for manually configured local services (this component of the
2007 development and not documented further at this time). As for those
2008 services you explicitly specify the target IP address and port, there is
2009 no significant security risk in doing so.
2011 Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet.
2012 Being a DNS exit is usually pretty harmless. However, enabling IPv4 or
2013 IPv6-exit without further precautions may enable adversaries to access
2014 your local network, send spam, attack other systems from your Internet
2015 connection and to other mischief that will appear to come from your
2016 machine. This may or may not get you into legal trouble.
2017 If you want to allow IPv4 or IPv6-exit functionality, you should strongly
2018 consider adding additional firewall rules manually to protect your local
2019 network and to restrict outgoing TCP traffic (i.e. by not allowing access
2020 to port 25). While we plan to improve exit-filtering in the future,
2021 you're currently on your own here.
2022 Essentially, be prepared for any kind of IP-traffic to exit the respective
2023 TUN interface (and GNUnet will enable IP-forwarding and NAT for the
2024 interface automatically).
2026 Additional configuration options of the exit as shown by the gnunet-setup
2029 @node IP Address of external DNS resolver
2030 @subsubsection IP Address of external DNS resolver
2032 If DNS traffic is to exit your machine, it will be send to this DNS
2033 resolver. You can specify an IPv4 or IPv6 address.
2035 @node IPv4 address for Exit interface
2036 @subsubsection IPv4 address for Exit interface
2038 This is the IPv4 address the Interface will get. Make the mask of the
2039 address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more
2040 mappings of IP addresses into this range. As for the VPN interface, any
2041 unused, private IPv4 address range will do.
2043 @node IPv6 address for Exit interface
2044 @subsubsection IPv6 address for Exit interface
2046 The public IPv6 address the interface will get. If your kernel is not a
2047 very recent kernel and you are willing to manually enable IPv6-NAT, the
2048 IPv6 address you specify here must be a globally routed IPv6 address of
2051 Suppose your host has the address @code{2001:4ca0::1234/64}, then
2052 using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits,
2053 then change at least one bit in the range before the bitmask, in the
2054 example above we changed bit 111 from 0 to 1).
2056 You may also have to configure your router to route traffic for the entire
2057 subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this
2058 should be automatic with IPv6, but obviously anything can be
2061 @node Bandwidth Configuration
2062 @subsection Bandwidth Configuration
2064 You can specify how many bandwidth GNUnet is allowed to use to receive
2065 and send data. This is important for users with limited bandwidth or
2068 @node Configuring NAT
2069 @subsection Configuring NAT
2071 Most hosts today do not have a normal global IP address but instead are
2072 behind a router performing Network Address Translation (NAT) which assigns
2073 each host in the local network a private IP address.
2074 As a result, these machines cannot trivially receive inbound connections
2075 from the Internet. GNUnet supports NAT traversal to enable these machines
2076 to receive incoming connections from other peers despite their
2079 In an ideal world, you can press the "Attempt automatic configuration"
2080 button in gnunet-setup to automatically configure your peer correctly.
2081 Alternatively, your distribution might have already triggered this
2082 automatic configuration during the installation process.
2083 However, automatic configuration can fail to determine the optimal
2084 settings, resulting in your peer either not receiving as many connections
2085 as possible, or in the worst case it not connecting to the network at all.
2087 To manually configure the peer, you need to know a few things about your
2088 network setup. First, determine if you are behind a NAT in the first
2090 This is always the case if your IP address starts with "10.*" or
2091 "192.168.*". Next, if you have control over your NAT router, you may
2092 choose to manually configure it to allow GNUnet traffic to your host.
2093 If you have configured your NAT to forward traffic on ports 2086 (and
2094 possibly 1080) to your host, you can check the "NAT ports have been opened
2095 manually" option, which corresponds to the "PUNCHED_NAT" option in the
2096 configuration file. If you did not punch your NAT box, it may still be
2097 configured to support UPnP, which allows GNUnet to automatically
2098 configure it. In that case, you need to install the "upnpc" command,
2099 enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal
2100 via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the
2101 configuration file).
2103 Some NAT boxes can be traversed using the autonomous NAT traversal method.
2104 This requires certain GNUnet components to be installed with "SUID"
2105 privileges on your system (so if you're installing on a system you do
2106 not have administrative rights to, this will not work).
2107 If you installed as 'root', you can enable autonomous NAT traversal by
2108 checking the "Enable NAT traversal using ICMP method".
2109 The ICMP method requires a way to determine your NAT's external (global)
2110 IP address. This can be done using either UPnP, DynDNS, or by manual
2111 configuration. If you have a DynDNS name or know your external IP address,
2112 you should enter that name under "External (public) IPv4 address" (which
2113 corresponds to the "EXTERNAL_ADDRESS" option in the configuration file).
2114 If you leave the option empty, GNUnet will try to determine your external
2115 IP address automatically (which may fail, in which case autonomous
2116 NAT traversal will then not work).
2118 Finally, if you yourself are not behind NAT but want to be able to
2119 connect to NATed peers using autonomous NAT traversal, you need to check
2120 the "Enable connecting to NATed peers using ICMP method" box.
2123 @node Peer configuration for distributors (e.g. Operating Systems)
2124 @subsection Peer configuration for distributors (e.g. Operating Systems)
2126 The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be
2127 manually set to "/var/lib/gnunet/data/" as the default
2128 "~/.local/share/gnunet/" is probably not that appropriate in this case.
2129 Similarly, distributors may consider pointing "GNUNET_RUNTIME_DIR" to
2130 "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a
2131 distributor decide to override system defaults, all of these changes
2132 should be done in a custom @file{/etc/gnunet.conf} and not in the files
2133 in the @file{config.d/} directory.
2135 Given the proposed access permissions, the "gnunet-setup" tool must be
2136 run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it
2137 modifies the system configuration). As always, gnunet-setup should be run
2138 after the GNUnet peer was stopped using "gnunet-arm -e". Distributors
2139 might want to include a wrapper for gnunet-setup that allows the
2140 desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account
2141 and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
2144 @node Config Leftovers
2145 @section Config Leftovers
2147 This section describes how to start a GNUnet peer. It assumes that you
2148 have already compiled and installed GNUnet and its' dependencies.
2149 Before you start a GNUnet peer, you may want to create a configuration
2150 file using gnunet-setup (but you do not have to).
2151 Sane defaults should exist in your
2152 @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice
2153 you could simply start without any configuration. If you want to
2154 configure your peer later, you need to stop it before invoking the
2155 @code{gnunet-setup} tool to customize further and to test your
2156 configuration (@code{gnunet-setup} has build-in test functions).
2158 The most important option you might have to still set by hand is in
2159 [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where
2160 GNUnet should store its data.
2161 It defaults to @code{$HOME/}, which again should work for most users.
2162 Make sure that the directory specified as GNUNET_HOME is writable to
2163 the user that you will use to run GNUnet (note that you can run frontends
2164 using other users, GNUNET_HOME must only be accessible to the user used to
2165 run the background processes).
2167 You will also need to make one central decision: should all of GNUnet be
2168 run under your normal UID, or do you want distinguish between system-wide
2169 (user-independent) GNUnet services and personal GNUnet services. The
2170 multi-user setup is slightly more complicated, but also more secure and
2171 generally recommended.
2174 * The Single-User Setup::
2175 * The Multi-User Setup::
2176 * Killing GNUnet services::
2177 * Access Control for GNUnet::
2180 @node The Single-User Setup
2181 @subsection The Single-User Setup
2183 For the single-user setup, you do not need to do anything special and can
2184 just start the GNUnet background processes using @code{gnunet-arm}.
2185 By default, GNUnet looks in @file{~/.config/gnunet.conf} for a
2186 configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@
2187 @code{$XDG_CONFIG_HOME} is defined). If your configuration lives
2188 elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet
2191 Assuming the configuration file is called @file{~/.config/gnunet.conf},
2192 you start your peer using the @code{gnunet-arm} command (say as user
2193 @code{gnunet}) using:
2196 gnunet-arm -c ~/.config/gnunet.conf -s
2200 The "-s" option here is for "start". The command should return almost
2201 instantly. If you want to stop GNUnet, you can use:
2204 gnunet-arm -c ~/.config/gnunet.conf -e
2208 The "-e" option here is for "end".
2210 Note that this will only start the basic peer, no actual applications
2212 If you want to start the file-sharing service, use (after starting
2216 gnunet-arm -c ~/.config/gnunet.conf -i fs
2220 The "-i fs" option here is for "initialize" the "fs" (file-sharing)
2221 application. You can also selectively kill only file-sharing support using
2224 gnunet-arm -c ~/.config/gnunet.conf -k fs
2228 Assuming that you want certain services (like file-sharing) to be always
2229 automatically started whenever you start GNUnet, you can activate them by
2230 setting "IMMEDIATE_START=YES" in the respective section of the configuration
2231 file (for example, "[fs]"). Then GNUnet with file-sharing support would
2232 be started whenever you@ enter:
2235 gnunet-arm -c ~/.config/gnunet.conf -s
2239 Alternatively, you can combine the two options:
2242 gnunet-arm -c ~/.config/gnunet.conf -s -i fs
2246 Using @code{gnunet-arm} is also the preferred method for initializing
2247 GNUnet from @code{init}.
2249 Finally, you should edit your @code{crontab} (using the @code{crontab}
2250 command) and insert a line@
2253 @@reboot gnunet-arm -c ~/.config/gnunet.conf -s
2256 to automatically start your peer whenever your system boots.
2258 @node The Multi-User Setup
2259 @subsection The Multi-User Setup
2261 This requires you to create a user @code{gnunet} and an additional group
2262 @code{gnunetdns}, prior to running @code{make install} during
2264 Then, you create a configuration file @file{/etc/gnunet.conf} which should
2269 START_SYSTEM_SERVICES = YES
2270 START_USER_SERVICES = NO
2274 Then, perform the same steps to run GNUnet as in the per-user
2275 configuration, except as user @code{gnunet} (including the
2276 @code{crontab} installation).
2277 You may also want to run @code{gnunet-setup} to configure your peer
2279 Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you
2280 run @code{gnunet-setup} as user @code{gnunet}, you might need to change
2281 permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can
2282 write to the file (during setup).
2284 Afterwards, you need to perform another setup step for each normal user
2285 account from which you want to access GNUnet. First, grant the normal user
2286 (@code{$USER}) permission to the group gnunet:
2289 # adduser $USER gnunet
2293 Then, create a configuration file in @file{~/.config/gnunet.conf} for the
2294 $USER with the lines:
2298 START_SYSTEM_SERVICES = NO
2299 START_USER_SERVICES = YES
2303 This will ensure that @code{gnunet-arm} when started by the normal user
2304 will only run services that are per-user, and otherwise rely on the
2305 system-wide services.
2306 Note that the normal user may run gnunet-setup, but the
2307 configuration would be ineffective as the system-wide services will use
2308 @file{/etc/gnunet.conf} and ignore options set by individual users.
2310 Again, each user should then start the peer using
2311 @file{gnunet-arm -s} --- and strongly consider adding logic to start
2312 the peer automatically to their crontab.
2314 Afterwards, you should see two (or more, if you have more than one USER)
2315 @code{gnunet-service-arm} processes running in your system.
2317 @node Killing GNUnet services
2318 @subsection Killing GNUnet services
2320 It is not necessary to stop GNUnet services explicitly when shutting
2323 It should be noted that manually killing "most" of the
2324 @code{gnunet-service} processes is generally not a successful method for
2325 stopping a peer (since @code{gnunet-service-arm} will instantly restart
2326 them). The best way to explicitly stop a peer is using
2327 @code{gnunet-arm -e}; note that the per-user services may need to be
2328 terminated before the system-wide services will terminate normally.
2330 @node Access Control for GNUnet
2331 @subsection Access Control for GNUnet
2333 This chapter documents how we plan to make access control work within the
2334 GNUnet system for a typical peer. It should be read as a best-practice
2335 installation guide for advanced users and builders of binary
2336 distributions. The recommendations in this guide apply to POSIX-systems
2337 with full support for UNIX domain sockets only.
2339 Note that this is an advanced topic. The discussion presumes a very good
2340 understanding of users, groups and file permissions. Normal users on
2341 hosts with just a single user can just install GNUnet under their own
2342 account (and possibly allow the installer to use SUDO to grant additional
2343 permissions for special GNUnet tools that need additional rights).
2344 The discussion below largely applies to installations where multiple users
2345 share a system and to installations where the best possible security is
2348 A typical GNUnet system consists of components that fall into four
2353 @item User interfaces
2354 User interfaces are not security sensitive and are supposed to be run and
2355 used by normal system users.
2356 The GTK GUIs and most command-line programs fall into this category.
2357 Some command-line tools (like gnunet-transport) should be excluded as they
2358 offer low-level access that normal users should not need.
2359 @item System services and support tools
2360 System services should always run and offer services that can then be
2361 accessed by the normal users.
2362 System services do not require special permissions, but as they are not
2363 specific to a particular user, they probably should not run as a
2364 particular user. Also, there should typically only be one GNUnet peer per
2365 host. System services include the gnunet-service and gnunet-daemon
2366 programs; support tools include command-line programs such as gnunet-arm.
2367 @item Privileged helpers
2368 Some GNUnet components require root rights to open raw sockets or perform
2369 other special operations. These gnunet-helper binaries are typically
2370 installed SUID and run from services or daemons.
2371 @item Critical services
2372 Some GNUnet services (such as the DNS service) can manipulate the service
2373 in deep and possibly highly security sensitive ways. For example, the DNS
2374 service can be used to intercept and alter any DNS query originating from
2375 the local machine. Access to the APIs of these critical services and their
2376 privileged helpers must be tightly controlled.
2379 @c FIXME: The titles of these chapters are too long in the index.
2382 * Recommendation - Disable access to services via TCP::
2383 * Recommendation - Run most services as system user "gnunet"::
2384 * Recommendation - Control access to services using group "gnunet"::
2385 * Recommendation - Limit access to certain SUID binaries by group "gnunet"::
2386 * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"::
2387 * Differences between "make install" and these recommendations::
2390 @node Recommendation - Disable access to services via TCP
2391 @subsubsection Recommendation - Disable access to services via TCP
2393 GNUnet services allow two types of access: via TCP socket or via UNIX
2395 If the service is available via TCP, access control can only be
2396 implemented by restricting connections to a particular range of IP
2398 This is acceptable for non-critical services that are supposed to be
2399 available to all users on the local system or local network.
2400 However, as TCP is generally less efficient and it is rarely the case
2401 that a single GNUnet peer is supposed to serve an entire local network,
2402 the default configuration should disable TCP access to all GNUnet
2403 services on systems with support for UNIX domain sockets.
2404 Since GNUnet 0.9.2, configuration files with TCP access disabled should be
2405 generated by default. Users can re-enable TCP access to particular
2406 services simply by specifying a non-zero port number in the section of
2407 the respective service.
2410 @node Recommendation - Run most services as system user "gnunet"
2411 @subsubsection Recommendation - Run most services as system user "gnunet"
2413 GNUnet's main services should be run as a separate user "gnunet" in a
2414 special group "gnunet".
2415 The user "gnunet" should start the peer using "gnunet-arm -s" during
2416 system startup. The home directory for this user should be
2417 @file{/var/lib/gnunet} and the configuration file should be
2418 @file{/etc/gnunet.conf}.
2419 Only the @code{gnunet} user should have the right to access
2420 @file{/var/lib/gnunet} (@emph{mode: 700}).
2422 @node Recommendation - Control access to services using group "gnunet"
2423 @subsubsection Recommendation - Control access to services using group "gnunet"
2425 Users that should be allowed to use the GNUnet peer should be added to the
2426 group "gnunet". Using GNUnet's access control mechanism for UNIX domain
2427 sockets, those services that are considered useful to ordinary users
2428 should be made available by setting "UNIX_MATCH_GID=YES" for those
2430 Again, as shipped, GNUnet provides reasonable defaults.
2431 Permissions to access the transport and core subsystems might additionally
2432 be granted without necessarily causing security concerns.
2433 Some services, such as DNS, must NOT be made accessible to the "gnunet"
2434 group (and should thus only be accessible to the "gnunet" user and
2435 services running with this UID).
2437 @node Recommendation - Limit access to certain SUID binaries by group "gnunet"
2438 @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet"
2440 Most of GNUnet's SUID binaries should be safe even if executed by normal
2441 users. However, it is possible to reduce the risk a little bit more by
2442 making these binaries owned by the group "gnunet" and restricting their
2443 execution to user of the group "gnunet" as well (4750).
2445 @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
2446 @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
2448 A special group "gnunetdns" should be created for controlling access to
2449 the "gnunet-helper-dns".
2450 The binary should then be owned by root and be in group "gnunetdns" and
2451 be installed SUID and only be group-executable (2750).
2452 @b{Note that the group "gnunetdns" should have no users in it at all,
2454 The "gnunet-service-dns" program should be executed by user "gnunet" (via
2455 gnunet-service-arm) with the binary owned by the user "root" and the group
2456 "gnunetdns" and be SGID (2700). This way, @strong{only}
2457 "gnunet-service-dns" can change its group to "gnunetdns" and execute the
2458 helper, and the helper can then run as root (as per SUID).
2459 Access to the API offered by "gnunet-service-dns" is in turn restricted
2460 to the user "gnunet" (not the group!), which means that only
2461 "benign" services can manipulate DNS queries using "gnunet-service-dns".
2463 @node Differences between "make install" and these recommendations
2464 @subsubsection Differences between "make install" and these recommendations
2466 The current build system does not set all permissions automatically based
2467 on the recommendations above. In particular, it does not use the group
2468 "gnunet" at all (so setting gnunet-helpers other than the
2469 gnunet-helper-dns to be owned by group "gnunet" must be done manually).
2470 Furthermore, 'make install' will silently fail to set the DNS binaries to
2471 be owned by group "gnunetdns" unless that group already exists (!).
2472 An alternative name for the "gnunetdns" group can be specified using the
2473 @code{--with-gnunetdns=GRPNAME} configure option.