1 @node GNUnet Installation Handbook
2 @chapter GNUnet Installation Handbook
4 This handbook describes how to install (build, setup, compile) and
5 setup (configure, start) GNUnet @value{VERSION}. After following these
6 instructions you should be able to install and then start user-interfaces
7 to interact with the network.
9 Note: This manual is far from complete, and we welcome contributions, be
10 it in the form of new chapters or insightful comments.
14 * Pre-installation notes::
15 * Generic installation instructions::
16 * Build instructions for Ubuntu 12.04 using Git::
17 * Build instructions for software builds from source::
18 * Build Instructions for Microsoft Windows Platforms::
19 * Build instructions for Debian 7.5::
20 * Installing GNUnet from Git on Ubuntu 14.4::
21 * Build instructions for Debian 8::
22 @c * Build instructions for OpenBSD 6.2::
23 * Outdated build instructions for previous revisions::
24 @c * Portable GNUnet::
25 * The graphical configuration interface::
26 * How to start and stop a GNUnet peer::
33 This section lists the various known dependencies for
34 GNUnet @value{EDITION}.
35 Suggestions for missing dependencies or wrong version numbers are welcome.
38 * External dependencies::
39 * Optional dependencies::
40 * Internal dependencies::
43 @node External dependencies
44 @subsection External dependencies
47 These packages must be installed before a typical GNUnet installation
56 @item gst-plugins-base
58 @item python (only 2.7 supported)@footnote{tests and gnunet-qr}
67 @item texinfo @geq{} 5.2
68 @item GNU libmicrohttpd @geq{} 0.9.30 @footnote{We recommend to build it
69 with a GnuTLS version that was configured with libunbound}
70 @item GNU libextractor @geq{} 1.0
71 @item GNU libtool @geq{} 2.2
72 @item GNU libunistring @geq{} 0.9.1.1
73 @item GNU libidn @geq{} 1.0.0
74 @item @uref{https://gnupg.org/software/libgcrypt/, GNU libgcrypt} @geq{}
75 @uref{https://gnupg.org/ftp/gcrypt/libgcrypt/, 1.6.0}
76 @item @uref{https://gnutls.org/, GnuTLS} @geq{} 3.2.7
77 @footnote{We recommend to compile with libunbound for DANE support;
78 GnuTLS also requires GNU nettle 2.7 (update: GnuTLS 3.2.7 appears NOT
79 to work against GNU nettle > 2.7, due to some API updatings done by
80 nettle. Thus it should be compiled against nettle 2.7
81 and, in case you get some error on the reference to `rpl_strerror' being
82 undefined, follow the instructions on
83 @uref{http://lists.gnupg.org/pipermail/gnutls-devel/2013-November/006588.html, this}
84 post (and the link inside it)).}
85 @item @uref{https://gnunet.org/gnurl, gnURL} libgnurl @geq{} 7.34.0
86 @footnote{must be compiled after @code{GnuTLS}}
87 @item libglpk @geq{} 4.45
88 @item @uref{http://www.openssl.org/, OpenSSL} @geq{} 1.0
89 @item TeX Live @geq{} 2012, optional (for gnunet-bcd)
90 @item Texinfo @geq{} 5.2 (for documentation)
91 @item libsqlite @geq{} 3.8.0 @footnote{(note that the code will
92 compile and often work with lower version numbers, but you may get subtle
93 bugs with respect to quota management in certain rare cases);
94 alternatively, MySQL or Postgres can also be installed, but those
95 databases will require more complex configurations (not
96 recommended for first-time users)}
100 @node Optional dependencies
101 @subsection Optional dependencies
103 These applications must be installed for various experimental or otherwise
104 optional features such as @command{gnunet-conversation},
105 and @command{gnunet-gtk} (most of these features are only build if you
106 configure GNUnet with @command{--enable-experimental}):
109 @item libpulse @geq{} 2.0,
110 optional (for @command{gnunet-conversation})
111 @item libopus @geq{} 1.0.1,
112 optional (for @command{gnunet-conversation})
113 @item libogg @geq{} 1.3.0,
114 optional (for @command{gnunet-conversation})
115 @item libnss contained @command{certool} binary,
116 optional for convenient installation of
118 @item python-zbar @geq{} 0.10,
119 optional (for @command{gnunet-qr})
120 @item Gtk+ @geq{} 3.0,
121 optional (for @command{gnunet-gtk})
122 @item libgladeui (must match Gtk+ version),
123 optional (for @command{gnunet-gtk})
124 @item libqrencode @geq{} 3.0,
125 optional (for @command{gnunet-namestore-gtk})
126 @item libpbc @geq{} 0.5.14, optional for Attribute-Based Encryption and Identity Provider functionality
127 @item libgabe (https://github.com/schanzen/libgabe), optional for Attribute-Based Encryption and Identity Provider functionality
130 @node Internal dependencies
131 @subsection Internal dependencies
133 This section tries to give an overview of what processes a typical GNUnet
134 peer running a particular application would consist of. All of the
135 processes listed here should be automatically started by
136 @command{gnunet-arm -s}.
137 The list is given as a rough first guide to users for failure diagnostics.
138 Ideally, end-users should never have to worry about these internal
141 In terms of internal dependencies, a minimum file-sharing system consists
142 of the following GNUnet processes (in order of dependency):
145 @item gnunet-service-arm
146 @item gnunet-service-resolver (required by all)
147 @item gnunet-service-statistics (required by all)
148 @item gnunet-service-peerinfo
149 @item gnunet-service-transport (requires peerinfo)
150 @item gnunet-service-core (requires transport)
151 @item gnunet-daemon-hostlist (requires core)
152 @item gnunet-daemon-topology (requires hostlist, peerinfo)
153 @item gnunet-service-datastore
154 @item gnunet-service-dht (requires core)
155 @item gnunet-service-identity
156 @item gnunet-service-fs (requires identity, mesh, dht, datastore, core)
160 A minimum VPN system consists of the following GNUnet processes (in
161 order of dependency):
164 @item gnunet-service-arm
165 @item gnunet-service-resolver (required by all)
166 @item gnunet-service-statistics (required by all)
167 @item gnunet-service-peerinfo
168 @item gnunet-service-transport (requires peerinfo)
169 @item gnunet-service-core (requires transport)
170 @item gnunet-daemon-hostlist (requires core)
171 @item gnunet-service-dht (requires core)
172 @item gnunet-service-mesh (requires dht, core)
173 @item gnunet-service-dns (requires dht)
174 @item gnunet-service-regex (requires dht)
175 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
179 A minimum GNS system consists of the following GNUnet processes (in
180 order of dependency):
183 @item gnunet-service-arm
184 @item gnunet-service-resolver (required by all)
185 @item gnunet-service-statistics (required by all)
186 @item gnunet-service-peerinfo
187 @item gnunet-service-transport (requires peerinfo)
188 @item gnunet-service-core (requires transport)
189 @item gnunet-daemon-hostlist (requires core)
190 @item gnunet-service-dht (requires core)
191 @item gnunet-service-mesh (requires dht, core)
192 @item gnunet-service-dns (requires dht)
193 @item gnunet-service-regex (requires dht)
194 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
195 @item gnunet-service-identity
196 @item gnunet-service-namestore (requires identity)
197 @item gnunet-service-gns (requires vpn, dns, dht, namestore, identity)
200 @node Pre-installation notes
201 @section Pre-installation notes
203 Please note that in the code instructions for the installation,
204 @emph{#} indicates commands run as privileged root user and
205 @emph{$} shows commands run as unprivileged ("normal") system user.
208 @node Generic installation instructions
209 @section Generic installation instructions
211 First, in addition to the GNUnet sources you might require downloading the
212 latest version of various dependencies, depending on how recent the
213 software versions in your distribution of GNU/Linux are.
214 Most distributions do not include sufficiently recent versions of these
216 Thus, a typically installation on a "modern" GNU/Linux distribution
217 requires you to install the following dependencies (ideally in this
221 @item libgpgerror and libgcrypt
222 @item libnettle and libunbound (possibly from distribution), GnuTLS
223 @item libgnurl (read the README)
224 @item GNU libmicrohttpd
225 @item GNU libextractor
228 Make sure to first install the various mandatory and optional
229 dependencies including development headers from your distribution.
231 Other dependencies that you should strongly consider to install is a
232 database (MySQL, sqlite or Postgres).
233 The following instructions will assume that you installed at least sqlite.
234 For most distributions you should be able to find pre-build packages for
235 the database. Again, make sure to install the client libraries @b{and} the
236 respective development headers (if they are packaged separately) as well.
238 You can find specific, detailed instructions for installing of the
239 dependencies (and possibly the rest of the GNUnet installation) in the
240 platform-specific descriptions, which can be found in the Index.
241 Please consult them now.
242 If your distribution is not listed, please study
243 @ref{Build instructions for Debian 8}, the build instructions for
244 Debian stable, carefully as you try to install the dependencies for your
246 Contributing additional instructions for further platforms is always
248 Please take in mind that operating system development tends to move at
249 a rather fast speed. Due to this you should be aware that some of
250 the instructions could be outdated by the time you are reading this.
251 If you find a mistake, please tell us about it (or even better: send
252 a patch to the documentation to fix it!).
254 Before proceeding further, please double-check the dependency list.
255 Note that in addition to satisfying the dependencies, you might have to
256 make sure that development headers for the various libraries are also
258 There maybe files for other distributions, or you might be able to find
259 equivalent packages for your distribution.
261 While it is possible to build and install GNUnet without having root
262 access, we will assume that you have full control over your system in
264 First, you should create a system user @emph{gnunet} and an additional
265 group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu,
269 # adduser --system --home /var/lib/gnunet --group \
270 --disabled-password gnunet
271 # addgroup --system gnunetdns
275 On other Unixes and GNU systems, this should have the same effect:
278 # useradd --system --groups gnunet --home-dir /var/lib/gnunet
279 # addgroup --system gnunetdns
282 Now compile and install GNUnet using:
285 $ tar xvf gnunet-@value{VERSION}.tar.gz
286 $ cd gnunet-@value{VERSION}
287 $ ./configure --with-sudo=sudo --with-nssdir=/lib
292 If you want to be able to enable DEBUG-level log messages, add
293 @code{--enable-logging=verbose} to the end of the
294 @command{./configure} command.
295 @code{DEBUG}-level log messages are in English only and
296 should only be useful for developers (or for filing
297 really detailed bug reports).
299 Finally, you probably want to compile @command{gnunet-gtk}, which
300 includes @command{gnunet-setup} (a graphical tool for
301 GNUnet configuration) and @command{gnunet-fs-gtk} (a graphical tool for
302 GNUnet file-sharing):
305 $ tar xvf gnunet-gtk-@value{VERSION}.tar.gz
306 $ cd gnunet-gtk-@value{VERSION}
307 $ ./configure --with-gnunet=/usr/local/
311 # just to be safe run this:
316 Next, edit the file @file{/etc/gnunet.conf} to contain the following:
325 You may need to update your @code{ld.so} cache to include
326 files installed in @file{/usr/local/lib}:
333 Then, switch from user @code{root} to user @code{gnunet} to start
337 # su -s /bin/sh - gnunet
338 $ gnunet-arm -c /etc/gnunet.conf -s
341 You may also want to add the last line in the gnunet user's @file{crontab}
342 prefixed with @code{@@reboot} so that it is executed whenever the system
346 @@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s
350 This will only start the system-wide GNUnet services.
351 Type exit to get back your root shell.
352 Now, you need to configure the per-user part. For each
353 $USER that should get access to GNUnet on the system, run:
356 # adduser $USER gnunet
360 to allow them to access the system-wide GNUnet services. Then, each
361 user should create a configuration file @file{~/.config/gnunet.conf}
368 DEFAULTSERVICES = gns
372 and start the per-user services using
375 $ gnunet-arm -c ~/.config/gnunet.conf -s
379 Again, adding a @code{crontab} entry to autostart the peer is advised:
382 @@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s
386 Note that some GNUnet services (such as SOCKS5 proxies) may need a
387 system-wide TCP port for each user.
388 For those services, systems with more than one user may require each user
389 to specify a different port number in their personal configuration file.
391 Finally, the user should perform the basic initial setup for the GNU Name
392 System (GNS). This is done by running two commands:
395 $ gnunet-gns-import.sh
396 $ gnunet-gns-proxy-setup-ca
400 The first generates the default zones, wheras the second setups the GNS
401 Certificate Authority with the user's browser. Now, to activate GNS in the
402 normal DNS resolution process, you need to edit your
403 @file{/etc/nsswitch.conf} where you should find a line like this:
406 hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
410 The exact details may differ a bit, which is fine. Add the text
411 @emph{"gns [NOTFOUND=return]"} after @emph{"files"}.
412 Keep in mind that we included a backslash ("\") here just for
413 markup reasons. You should write the text below on @b{one line}
414 and @b{without} the "\":
417 hosts: files gns [NOTFOUND=return] mdns4_minimal \
418 [NOTFOUND=return] dns mdns4
421 @c FIXME: Document new behavior.
422 You might want to make sure that @file{/lib/libnss_gns.so.2} exists on
423 your system, it should have been created during the installation.
425 @node Build instructions for Ubuntu 12.04 using Git
426 @section Build instructions for Ubuntu 12.04 using Git
429 * Install the required build tools::
430 * Install libgcrypt 1.6 and libgpg-error::
431 * Install gnutls with DANE support::
433 * Install libmicrohttpd from Git::
434 * Install libextractor from Git::
435 * Install GNUnet dependencies::
437 * Install the GNUnet-gtk user interface from Git::
440 @node Install the required build tools
441 @subsection Install the required build tools
443 First, make sure Git is installed on your system:
446 $ sudo apt-get install git
449 Install the essential buildtools:
452 $ sudo apt-get install automake autopoint autoconf libtool
455 @node Install libgcrypt 1.6 and libgpg-error
456 @subsection Install libgcrypt 1.6 and libgpg-error
458 @ref{generic source installation - libgpg-error}
460 @node Install gnutls with DANE support
461 @subsection Install gnutls with DANE support
464 @item @ref{generic source installation - nettle}
465 @item @ref{generic source installation - ldns}
466 @item @ref{generic source installation - libunbound/unbound}
467 @item @ref{generic source installation - gnutls}
468 @item @ref{generic source installation - libgcrypt}
471 @node Install libgnurl
472 @subsection Install libgnurl
474 Follow the @ref{generic source installation - libgnurl}.
476 @node Install libmicrohttpd from Git
477 @subsection Install libmicrohttpd from Git
480 $ git clone https://gnunet.org/git/libmicrohttpd
484 $ sudo make install ; cd ..
487 @node Install libextractor from Git
488 @subsection Install libextractor from Git
490 Install libextractor dependencies:
493 $ sudo apt-get install zlib1g-dev libgsf-1-dev libmpeg2-4-dev \
494 libpoppler-dev libvorbis-dev libexiv2-dev libjpeg-dev \
495 libtiff-dev libgif-dev libvorbis-dev libflac-dev libsmf-dev \
502 $ git clone https://gnunet.org/git/libextractor
506 $ sudo make install ; cd ..
509 @node Install GNUnet dependencies
510 @subsection Install GNUnet dependencies
513 $ sudo apt-get install libidn11-dev libunistring-dev libglpk-dev \
514 libpulse-dev libbluetooth-dev libsqlite-dev
520 $ wget http://downloads.xiph.org/releases/opus/opus-1.1.tar.gz
521 $ tar xf opus-1.1.tar.gz
524 $ sudo make install ; cd ..
527 Choose one or more database backends:
531 $ sudo apt-get install libsqlite3-dev
535 $ sudo apt-get install libmysqlclient-dev
539 $ sudo apt-get install libpq-dev postgresql
545 @subsection Build GNUnet
550 * Configuring the installation path::
551 * Configuring the system::
552 * Installing components requiring sudo permission::
556 @node Configuring the installation path
557 @subsubsection Configuring the installation path
559 You can specify the location of the GNUnet installation by setting the
560 prefix when calling the configure script with @code{--prefix=DIRECTORY}
563 $ export PATH=$PATH:DIRECTORY/bin
566 @node Configuring the system
567 @subsubsection Configuring the system
569 Please make sure NOW that you have created a user and group 'gnunet'
570 and additionally a group 'gnunetdns':
573 $ sudo addgroup gnunet
574 $ sudo addgroup gnunetdns
575 $ sudo adduser gnunet
578 Each GNUnet user should be added to the 'gnunet' group (may
579 require fresh login to come into effect):
582 $ sudo useradd -G gnunet
585 @node Installing components requiring sudo permission
586 @subsubsection Installing components requiring sudo permission
588 Some components, like the nss plugin required for GNS, may require root
589 permissions. To allow these few components to be installed use:
592 $ ./configure --with-sudo
599 $ git clone https://gnunet.org/git/gnunet/
604 Use the required configure call including the optional installation prefix
605 @code{PREFIX} or the sudo permissions:
608 $ ./configure [ --with-sudo | --with-prefix=PREFIX ]
612 $ make; sudo make install
615 After installing it, you need to create an empty configuration file:
618 mkdir ~/.gnunet; touch ~/.gnunet/gnunet.conf
621 And finally you can start GNUnet with:
627 @node Install the GNUnet-gtk user interface from Git
628 @subsection Install the GNUnet-gtk user interface from Git
634 $ sudo apt-get install libgtk-3-dev libunique-3.0-dev libgladeui-dev \
638 Build GNUnet (with an optional prefix) and execute:
641 $ git clone https://gnunet.org/git/gnunet-gtk/
644 $ ./configure [--prefix=PREFIX] --with-gnunet=DIRECTORY
645 $ make; sudo make install
648 @node Build instructions for software builds from source
649 @section Build instructions for software builds from source
651 This section describes software builds in case your operating
652 system lacks binary substitutes / binary builds for some dependencies
654 It is assumed that you have installed common build dependencies
655 and that these instructions are treated as generic without any
657 It is furthermore assumed that you use the release tarballs of
658 the software, installation from the respective version control
659 sources might differ in ways that are only minimal different
660 (for example a dependency on autotools etc).
663 * generic source installation - nettle::
664 * generic source installation - ldns::
665 * generic source installation - libunbound/unbound::
666 * generic source installation - libav::
667 * generic source installation - libextractor::
668 * generic source installation - libgpg-error::
669 * generic source installation - libgcrypt::
670 * generic source installation - gnutls::
671 * generic source installation - libmicrohttpd::
672 * generic source installation - libgnurl::
675 @node generic source installation - nettle
676 @subsection generic source installation - nettle
679 $ wget http://www.lysator.liu.se/~nisse/archive/nettle-2.7.1.tar.gz
680 $ tar xf nettle-2.7.1.tar.gz
683 $ sudo make install ; cd ..
686 @node generic source installation - ldns
687 @subsection generic source installation - ldns
690 $ wget https://www.nlnetlabs.nl/downloads/ldns/ldns-1.6.16.tar.gz
691 $ tar xf ldns-1.6.16.tar.gz
694 $ sudo make install ; cd ..
697 @node generic source installation - libunbound/unbound
698 @subsection generic source installation - libunbound/unbound
701 $ wget https://unbound.net/downloads/unbound-1.4.21.tar.gz
702 $ tar xf unbound-1.4.21.tar.gz
705 $ sudo make install ; cd ..
708 @node generic source installation - libav
709 @subsection generic source installation - libav
712 $ wget https://libav.org/releases/libav-9.10.tar.xz
713 $ cd libav-0.9 ; ./configure --enable-shared;
714 $ make; sudo make install; cd ..
717 @node generic source installation - libextractor
718 @subsection generic source installation - libextractor
721 $ wget https://ftp.gnu.org/gnu/libextractor/libextractor-1.3.tar.gz
722 $ tar xvf libextractor-1.3.tar.gz
723 $ cd libextractor-1.3 ; ./configure;
724 $ make ; sudo make install; cd ..
727 @node generic source installation - libgpg-error
728 @subsection generic source installation - libgpg-error
731 $ wget https://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
732 $ tar xvf libgpg-error-1.12.tar.bz2
733 $ cd libgpg-error-1.12; ./configure;
734 $ make ; sudo make install; cd ..
737 @node generic source installation - libgcrypt
738 @subsection generic source installation - libgcrypt
740 $ wget https://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
741 $ tar xvf libgcrypt-1.6.0.tar.bz2
742 $ cd libgcrypt-1.6.0; ./configure --with-gpg-error-prefix=/usr/local;
743 $ make ; sudo make install ; cd ..
746 @node generic source installation - gnutls
747 @subsection generic source installation - gnutls
750 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.2/gnutls-3.2.7.tar.xz
751 $ tar xvf gnutls-3.2.7.tar.xz
756 If you want a GnuTLS with DANE functionality (recommended for GNUnet),
757 you have to compile it against libunbound. Assuming that libunbound
758 is installed on your system:
761 $ ./configure --enable-libdane
765 Note that the build system of GnuTLS should pick up libunbound without
766 the explicit mention of @code{--enable-libdane}.
767 If you don't want libdane support you should pass @code{--disable-libdane}
772 $ make ; sudo make install ; cd ..
775 @node generic source installation - libmicrohttpd
776 @subsection generic source installation - libmicrohttpd
779 $ wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.33.tar.gz
780 $ tar xvf libmicrohttpd-0.9.33.tar.gz
781 $ cd libmicrohttpd-0.9.33; ./configure;
782 $ make ; sudo make install ; cd ..
785 @node generic source installation - libgnurl
786 @subsection generic source installation - libgnurl
788 Example installation of libgnurl version 7.57.0 from source.
791 $ wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.57.0.tar.xz
792 $ wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.57.0.tar.xz.sig
793 $ gpg --verify gnurl-7.57.0.tar.xz.sig
797 If that command fails because you do not have the required public key,
798 then run this command to import it:
801 $ gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588
805 and rerun the gpg --verify command.
808 $ tar xvf gnurl-7.57.0.tar.xz
810 $ ./configure --disable-ntlm-wb
811 $ make ; sudo make install; cd ..
814 You have now build and installed libgnurl from source.
817 * Fixing libgnurl build issues::
820 @node Fixing libgnurl build issues
821 @subsubsection Fixing libgnurl build issues
823 @c FIXME: Obviously this subsection should be evaluated and
824 @c if still necessary moved into gnURL itself (README) or
825 @c into a separate section which deals with gnURL.
826 If you have to compile libgnurl from source (for example if the version
827 included in your distribution is too old or it's not included at all)
828 you perhaps might get an error message while running the
829 @command{configure} script:
834 checking for 64-bit curl_off_t data type... unknown
835 checking for 32-bit curl_off_t data type... unknown
836 checking for 16-bit curl_off_t data type... unknown
837 configure: error: cannot find data type for curl_off_t.
843 Before running the @command{configure} script, set:
846 CFLAGS="-I. -I$BUILD_ROOT/include"
849 @node Build Instructions for Microsoft Windows Platforms
850 @section Build Instructions for Microsoft Windows Platforms
853 * Introduction to building on MS Windows::
855 * Dependencies & Initial Setup::
856 * GNUnet Installation::
857 * Adjusting Windows for running and testing GNUnet::
858 * Building the GNUnet Installer::
859 * Using GNUnet with Netbeans on Windows::
862 @node Introduction to building on MS Windows
863 @subsection Introduction to building on MS Windows
866 This document is a guide to building GNUnet and its dependencies on
867 Windows platforms. GNUnet development is mostly done under GNU/Linux and
868 especially git checkouts may not build out of the box.
869 We regret any inconvenience, and if you have problems, please report
873 @subsection Requirements
875 The Howto is based upon a @strong{Windows Server 2008 32bit}
876 @strong{Installation}, @strong{sbuild} and thus a
877 @uref{http://www.mingw.org/wiki/MSYS, MSYS+MinGW}
878 (W32-GCC-Compiler-Suite + Unix-like Userland) installation. sbuild
879 is a convenient set of scripts which creates a working msys/mingw
880 installation and installs most dependencies required for GNUnet.
882 As of the point of the creation of these instructions,
883 GNUnet @strong{requires} a Windows @strong{Server} 2003 or
884 newer for full feature support.
885 Windows Vista and later will also work, but
886 @strong{non-server version can not run a VPN-Exit-Node} as the NAT
887 features have been removed as of Windows Vista.
889 @c TODO: We should document Windows 10!
890 @c It seems like the situation hasn't changed with W10
892 @node Dependencies & Initial Setup
893 @subsection Dependencies & Initial Setup
899 Install a fresh version of @strong{Python 2.x}, even if you are using a
900 x64-OS, install a 32-bit version for use with sbuild.
901 Python 3.0 is currently incompatible.
904 Install your favorite @uref{http://code.google.com/p/tortoisegit/, git} &
905 @uref{http://tortoisesvn.net/, subversion}-clients.
908 You will also need some archive-manager like
909 @uref{http://www.7-zip.org/, 7zip}.
912 Pull a copy of sbuild to a directory of your choice, which will be used
913 in the remainder of this guide. For now, we will use
914 @file{c:\gnunet\sbuild\}
917 in @file{sbuild\src\mingw\mingw32-buildall.sh}, comment out the packages
918 @strong{gnunet-svn} and @strong{gnunet-gtk-svn}, as we don't want sbuild
919 to compile/install those for us.
922 Follow LRN's sbuild installation instructions.-
925 Please note that sbuild may (or will most likely) fail during
926 installation, thus you really HAVE to @strong{check the logfiles} created
927 during the installation process.
928 Certain packages may fail to build initially due to missing dependencies,
930 @strong{substitute those with binary-versions initially}. Later on once
931 dependencies are satisfied you can re-build the newer package versions.
933 @strong{It is normal that you may have to repeat this step multiple times
934 and there is no uniform way to fix all compile-time issues, as the
935 build-process of many of the dependencies installed are rather unstable
936 on win32 and certain releases may not even compile at all.}
938 Most dependencies for GNUnet have been set up by sbuild, thus we now
939 should add the @file{bin/} directories in your new msys and mingw
940 installations to PATH. You will want to create a backup of your finished
941 msys-environment by now.
943 @node GNUnet Installation
944 @subsection GNUnet Installation
946 First, we need to launch our msys-shell, you can do this via
948 @file{C:\gnunet\sbuild\msys\msys.bat}
950 You might wish to take a look at this file and adjust some
951 login-parameters to your msys environment.
953 Also, sbuild added two pointpoints to your msys-environment, though those
954 might remain invisible:
959 /mingw, which will mount your mingw-directory from sbuild/mingw and the
963 /src which contains all the installation sources sbuild just compiled.
966 Check out the current GNUnet sources (git HEAD) from the
967 GNUnet repository "gnunet.git", we will do this in your home directory:
969 @code{git clone https://gnunet.org/git/gnunet/ ~/gnunet}
971 Now, we will first need to bootstrap the checked out installation and then
972 configure it accordingly.
977 STRIP=true CPPFLAGS="-DUSE_IPV6=1 -DW32_VEH" CFLAGS="$CFLAGS -g -O2" \
978 ./configure --prefix=/ --docdir=/share/doc/gnunet \
979 --with-libiconv-prefix=/mingw --with-libintl-prefix=/mingw \
980 --with-libcurl=/mingw --with-extractor=/mingw --with-sqlite=/mingw \
981 --with-microhttpd=/mingw --with-plibc=/mingw --enable-benchmarks \
982 --enable-expensivetests --enable-experimental --with-qrencode=/mingw \
983 --enable-silent-rules --enable-experimental 2>&1 | tee -a ./configure.log
986 The parameters above will configure for a reasonable GNUnet installation
987 to the your msys-root directory.
988 Depending on which features your would like to build or you may need to
989 specify additional dependencies. Sbuild installed most libs into
990 the /mingw subdirectory, so remember to prefix library locations with
993 Like on a unixoid system, you might want to use your home directory as
994 prefix for your own GNUnet installation for development, without tainting
995 the buildenvironment. Just change the "prefix" parameter to point towards
998 Now it's time to compile GNUnet as usual. Though this will take some time,
999 so you may fetch yourself a coffee or some Mate now...
1005 @node Adjusting Windows for running and testing GNUnet
1006 @subsection Adjusting Windows for running and testing GNUnet
1008 Assuming the build succeeded and you
1009 @strong{added the bin directory of your GNUnet to PATH}, you can now use
1010 your gnunet-installation as usual.
1011 Remember that UAC or the windows firewall may popup initially, blocking
1012 further execution of gnunet until you acknowledge them.
1014 You will also have to take the usual steps to get peer-to-peer (p2p)
1015 software running properly (port forwarding, ...),
1016 and GNUnet will require administrative permissions as it may even
1017 install a device-driver (in case you are using gnunet-vpn and/or
1020 @node Building the GNUnet Installer
1021 @subsection Building the GNUnet Installer
1023 The GNUnet installer is made with
1024 @uref{http://nsis.sourceforge.net/, NSIS}.
1025 The installer script is located in @file{contrib\win} in the
1028 @node Using GNUnet with Netbeans on Windows
1029 @subsection Using GNUnet with Netbeans on Windows
1033 @node Build instructions for Debian 7.5
1034 @section Build instructions for Debian 7.5
1037 These are the installation instructions for Debian 7.5. They were tested
1038 using a minimal, fresh Debian 7.5 AMD64 installation without non-free
1039 software (no contrib or non-free).
1040 By "minimal", we mean that during installation, we did not select any
1041 desktop environment, servers or system utilities during the "tasksel"
1042 step. Note that the packages and the dependencies that we will install
1043 during this chapter take about 1.5 GB of disk space.
1044 Combined with GNUnet and space for objects during compilation, you should
1045 not even attempt this unless you have about 2.5 GB free after the minimal
1046 Debian installation.
1047 Using these instructions to build a VM image is likely to require a
1048 minimum of 4-5 GB for the VM (as you will likely also want a desktop
1051 GNUnet's security model assumes that your @file{/home} directory is
1052 encrypted. Thus, if possible, you should encrypt your home partition
1053 (or per-user home directory).
1055 Naturally, the exact details of the starting state for your installation
1056 should not matter much. For example, if you selected any of those
1057 installation groups you might simply already have some of the necessary
1059 We did this for testing, as this way we are less likely to forget to
1060 mention a required package.
1061 Note that we will not install a desktop environment, but of course you
1062 will need to install one to use GNUnet's graphical user interfaces.
1063 Thus, it is suggested that you simply install the desktop environment of
1064 your choice before beginning with the instructions.
1072 * Installing packages::
1073 * Installing dependencies from source::
1074 * Installing GNUnet from source::
1075 * But wait there is more!::
1081 After any installation, you should begin by running
1084 # apt-get update ; apt-get upgrade
1087 to ensure that all of your packages are up-to-date. Note that the "#" is
1088 used to indicate that you need to type in this command as "root"
1089 (or prefix with "sudo"), whereas "$" is used to indicate typing in a
1090 command as a normal user.
1093 @subsection Stable? Hah!
1095 Yes, we said we start with a Debian 7.5 "stable" system. However, to
1096 reduce the amount of compilation by hand, we will begin by allowing the
1097 installation of packages from the testing and unstable distributions as
1099 We will stick to "stable" packages where possible, but some packages will
1100 be taken from the other distributions.
1101 Start by modifying @file{/etc/apt/sources.list} to contain the
1102 following (possibly adjusted to point to your mirror of choice):
1105 # These were there before:
1106 deb http://ftp.de.debian.org/debian/ wheezy main
1107 deb-src http://ftp.de.debian.org/debian/ wheezy main
1108 deb http://security.debian.org/ wheezy/updates main
1109 deb-src http://security.debian.org/ wheezy/updates main
1110 deb http://ftp.de.debian.org/debian/ wheezy-updates main
1111 deb-src http://ftp.de.debian.org/debian/ wheezy-updates main
1113 # Add these lines (feel free to adjust the mirror):
1114 deb http://ftp.de.debian.org/debian/ testing main
1115 deb http://ftp.de.debian.org/debian/ unstable main
1118 The next step is to create/edit your @file{/etc/apt/preferences}
1119 file to look like this:
1123 Pin: release a=stable,n=wheezy
1127 Pin: release o=Debian,a=testing
1131 Pin: release o=Debian,a=unstable
1135 You can read more about Apt Preferences here and here.
1136 Note that other pinnings are likely to also work for GNUnet, the key
1137 thing is that you need some packages from unstable (as shown below).
1138 However, as unstable is unlikely to be comprehensive (missing packages)
1139 or might be problematic (crashing packages), you probably want others
1140 from stable and/or testing.
1143 @subsection Update again
1152 to ensure that all your new distribution indices are downloaded, and
1153 that your pinning is correct: the upgrade step should cause no changes
1156 @node Installing packages
1157 @subsection Installing packages
1159 We begin by installing a few Debian packages from stable:@
1162 # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \
1163 libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev \
1164 texlive libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev \
1165 libbz2-dev libexiv2-dev libflac-dev libgif-dev libglib2.0-dev \
1166 libgtk-3-dev libmagic-dev libjpeg8-dev libmpeg2-4-dev libmp4v2-dev \
1167 librpm-dev libsmf-dev libtidy-dev libtiff5-dev libvorbis-dev \
1168 libogg-dev zlib1g-dev g++ gettext libgsf-1-dev libunbound-dev \
1169 libqrencode-dev libgladeui-dev nasm texlive-latex-extra \
1170 libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev
1173 After that, we install a few more packages from unstable:@
1176 # apt-get install -t unstable nettle-dev libgstreamer1.0-dev \
1177 gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
1178 libgstreamer-plugins-base1.0-dev
1181 @node Installing dependencies from source
1182 @subsection Installing dependencies from source
1184 Next, we need to install a few dependencies from source.
1185 You might want to do this as a "normal" user and only run the
1186 @code{make install} steps as root (hence the @code{sudo} in the
1187 commands below). Also, you do this from any
1188 directory. We begin by downloading all dependencies, then extracting the
1189 sources, and finally compiling and installing the libraries.
1191 For these steps, follow the instructions given in the
1192 installation from source instruction in this order:
1195 @item @ref{generic source installation - libav}
1196 @item @ref{generic source installation - libextractor}
1197 @item @ref{generic source installation - libgpg-error}
1198 @item @ref{generic source installation - libgcrypt}
1199 @item @ref{generic source installation - gnutls}
1200 @item @ref{generic source installation - libmicrohttpd}
1201 @item @ref{generic source installation - libgnurl}
1204 @node Installing GNUnet from source
1205 @subsection Installing GNUnet from source
1208 For this, simply follow the generic installation instructions from
1211 @node But wait there is more!
1212 @subsection But wait there is more!
1214 So far, we installed all of the packages and dependencies required to
1215 ensure that all of GNUnet would be built.
1216 However, while for example the plugins to interact with the MySQL or
1217 Postgres databases have been created, we did not actually install or
1218 configure those databases. Thus, you will need to install
1219 and configure those databases or stick with the default Sqlite database.
1220 Sqlite is usually fine for most applications, but MySQL can offer better
1221 performance and Postgres better resillience.
1224 @node Installing GNUnet from Git on Ubuntu 14.4
1225 @section Installing GNUnet from Git on Ubuntu 14.4
1227 @strong{Install the required build tools:}
1230 $ sudo apt-get install git automake autopoint autoconf
1233 @strong{Install the required dependencies}
1236 $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \
1237 libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \
1238 libmicrohttpd-dev libgnutls28-dev
1241 @strong{Choose one or more database backends}
1248 $ sudo apt-get install libsqlite3-dev
1254 $ sudo apt-get install libmysqlclient-dev
1260 $ sudo apt-get install libpq-dev postgresql
1265 @strong{Install the optional dependencies for gnunet-conversation:}
1268 $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev
1271 @strong{Install the libgrypt 1.6.1:}
1275 @item For Ubuntu 14.04:
1278 $ sudo apt-get install libgcrypt20-dev
1281 @item For Ubuntu older 14.04:
1284 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2
1285 $ tar xf libgcrypt-1.6.1.tar.bz2
1286 $ cd libgcrypt-1.6.1
1294 @strong{Install libgnurl}
1297 $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2
1298 $ tar xf gnurl-7.35.0.tar.bz2
1300 $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
1301 --without-libmetalink --without-winidn --without-librtmp \
1302 --without-nghttp2 --without-nss --without-cyassl --without-polarssl \
1303 --without-ssl --without-winssl --without-darwinssl --disable-sspi \
1304 --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \
1305 --disable-telnet --disable-tftp --disable-pop3 --disable-imap \
1306 --disable-smtp --disable-gopher --disable-file --disable-ftp
1311 @strong{Install GNUnet}
1314 $ git clone https://gnunet.org/git/gnunet/
1323 @item Install to a different directory:
1330 Have sudo permission, but do not want to compile as root:
1337 Want debug message enabled:
1340 --enable-logging=verbose
1347 $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose]
1348 $ make; sudo make install
1351 After installing it, you need to create an empty configuration file:
1354 touch ~/.config/gnunet.conf
1357 And finally you can start GNUnet with
1363 @node Build instructions for Debian 8
1364 @section Build instructions for Debian 8
1367 These are the installation instructions for Debian 8. They were tested
1368 sing a fresh Debian 8 AMD64 installation without non-free software (no
1369 contrib or non-free). During installation, I only selected "lxde" for the
1370 desktop environment.
1371 Note that the packages and the dependencies that we will install during
1372 this chapter take about 1.5 GB of disk space. Combined with GNUnet and
1373 space for objects during compilation, you should not even attempt this
1374 unless you have about 2.5 GB free after the Debian installation.
1375 Using these instructions to build a VM image is likely to require a
1376 minimum of 4-5 GB for the VM (as you will likely also want a desktop
1379 GNUnet's security model assumes that your @code{/home} directory is
1381 Thus, if possible, you should encrypt your entire disk, or at least just
1382 your home partition (or per-user home directory).
1384 Naturally, the exact details of the starting state for your installation
1385 should not matter much.
1386 For example, if you selected any of those installation groups you might
1387 simply already have some of the necessary packages installed. Thus, it is
1388 suggested that you simply install the desktop environment of your choice
1389 before beginning with the instructions.
1394 * Installing Debian Packages::
1395 * Installing Dependencies from Source2::
1396 * Installing GNUnet from Source2::
1397 * But wait (again) there is more!::
1401 @subsection Update Debian
1403 After any installation, you should begin by running
1410 to ensure that all of your packages are up-to-date. Note that the "#" is
1411 used to indicate that you need to type in this command as "root" (or
1412 prefix with "sudo"), whereas "$" is used to indicate typing in a command
1415 @node Installing Debian Packages
1416 @subsection Installing Debian Packages
1418 We begin by installing a few Debian packages from stable:
1421 # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \
1422 libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \
1423 libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \
1424 libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \
1425 libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext \
1426 libgsf-1-dev libunbound-dev libqrencode-dev libgladeui-dev nasm \
1427 texlive-latex-extra libunique-3.0-dev gawk miniupnpc libfuse-dev \
1428 libbluetooth-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
1429 libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev \
1430 libgcrypt20-dev libmicrohttpd-dev
1433 @node Installing Dependencies from Source2
1434 @subsection Installing Dependencies from Source2
1436 Yes, we said we start with a Debian 8 "stable" system, but because Debian
1437 linked GnuTLS without support for DANE, we need to compile a few things,
1438 in addition to GNUnet, still by hand. Yes, you can run GNUnet using the
1439 respective Debian packages, but then you will not get DANE support.
1441 Next, we need to install a few dependencies from source. You might want
1442 to do this as a "normal" user and only run the @code{make install} steps
1443 as root (hence the @code{sudo} in the commands below). Also, you do this
1444 from any directory. We begin by downloading all dependencies, then
1445 extracting the sources, and finally compiling and installing the
1449 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz
1450 $ tar xvf gnutls-3.3.12.tar.xz
1451 $ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd ..
1454 For the installation and compilation of libgnurl/gnURL refer to
1455 the generic installation section,
1456 @xref{generic source installation - libgnurl}.
1458 @node Installing GNUnet from Source2
1459 @subsection Installing GNUnet from Source2
1461 For this, simply follow the generic installation instructions from@
1464 @node But wait (again) there is more!
1465 @subsection But wait (again) there is more!
1467 So far, we installed all of the packages and dependencies required to
1468 ensure that all of GNUnet would be built. However, while for example the
1469 plugins to interact with the MySQL or Postgres databases have been
1470 created, we did not actually install or configure those databases.
1471 Thus, you will need to install and configure those databases or stick
1472 with the default Sqlite database. Sqlite is usually fine for most
1473 applications, but MySQL can offer better performance and Postgres better
1476 @c @node Build instructions for OpenBSD 6.2
1477 @c @section Build instructions for OpenBSD 6.2
1479 @node Outdated build instructions for previous revisions
1480 @section Outdated build instructions for previous revisions
1482 This chapter contains a collection of outdated, older installation guides.
1483 They are mostly intended to serve as a starting point for writing
1484 up-to-date instructions and should not be expected to work for
1486 A set of older installation instructions can also be found in the
1487 file @file{doc/outdated-and-old-installation-instructions.txt} in the
1488 source tree of GNUnet.
1490 This file covers old instructions which no longer receive security
1491 updates or any kind of support.
1494 * Installing GNUnet 0.10.1 on Ubuntu 14.04::
1495 * Building GLPK for MinGW::
1496 * GUI build instructions for Ubuntu 12.04 using Subversion::
1497 @c * Installation with gnunet-update::
1498 * Instructions for Microsoft Windows Platforms (Old)::
1502 @node Installing GNUnet 0.10.1 on Ubuntu 14.04
1503 @subsection Installing GNUnet 0.10.1 on Ubuntu 14.04
1505 Install the required dependencies:
1508 $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \
1509 libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \
1510 libmicrohttpd-dev libgnutls28-dev
1513 Choose one or more database backends:
1520 $ sudo apt-get install libsqlite3-dev@
1526 $ sudo apt-get install libmysqlclient-dev@
1532 $ sudo apt-get install libpq-dev postgresql@
1537 Install the optional dependencies for gnunet-conversation:
1540 $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev
1543 Install libgcrypt 1.6:
1547 @item For Ubuntu 14.04:
1550 $ sudo apt-get install libgcrypt20-dev
1553 @item For Ubuntu older than 14.04:
1556 wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2
1557 $ tar xf libgcrypt-1.6.1.tar.bz2
1558 $ cd libgcrypt-1.6.1
1567 @pxref{generic source installation - libgnurl}.
1572 $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz
1573 $ tar xf gnunet-0.10.1.tar.gz
1582 Install to a different directory:
1589 Have sudo permission, but do not want to compile as root:
1596 Want debug message enabled:
1599 --enable-logging=verbose
1605 $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose]
1606 $ make; sudo make install
1609 After installing it, you need to create an empty configuration file:
1612 touch ~/.config/gnunet.conf
1615 And finally you can start GNUnet with
1621 @node Building GLPK for MinGW
1622 @subsection Building GLPK for MinGW
1624 GNUnet now requires the GNU Linear Programming Kit (GLPK).
1625 Since there's is no package you can install with @code{mingw-get} you
1626 have to compile it from source:
1630 @item Download the latest version from
1631 @uref{http://ftp.gnu.org/gnu/glpk/}
1633 @item Unzip the downloaded source tarball using your favourite
1634 unzipper application In the MSYS shell
1636 @item change to the respective directory
1638 @item Configure glpk for "i686-pc-mingw32":
1641 ./configure '--build=i686-pc-mingw32'
1652 MinGW does not automatically detect the correct buildtype so you have to
1653 specify it manually.
1656 @node GUI build instructions for Ubuntu 12.04 using Subversion
1657 @subsection GUI build instructions for Ubuntu 12.04 using Subversion
1659 After installing GNUnet you can continue installing the GNUnet GUI tools:
1661 First, install the required dependencies:
1664 $ sudo apt-get install libgladeui-dev libqrencode-dev
1667 Please ensure that the GNUnet shared libraries can be found by the linker.
1668 If you installed GNUnet libraries in a non standard path
1669 (say GNUNET_PREFIX=/usr/local/lib/), you can
1673 @item set the environmental variable permanently to:
1676 LD_LIBRARY_PATH=$GNUNET_PREFIX
1679 @item or add @code{$GNUNET_PREFIX} to @file{/etc/ld.so.conf}
1683 Now you can checkout and compile the GNUnet GUI tools:
1686 $ git clone https://gnunet.org/git/gnunet-gtk
1689 $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/..
1693 @c @node Installation with gnunet-update
1694 @c @subsection Installation with gnunet-update
1696 @c gnunet-update project is an effort to introduce updates to GNUnet
1697 @c installations. An interesting to-be-implemented-feature of gnunet-update
1698 @c is that these updates are propagated through GNUnet's peer-to-peer
1699 @c network. More information about gnunet-update can be found at
1700 @c @c FIXME: Use correct cgit URL
1701 @c @uref{https://gnunet.org/git/gnunet-update.git/tree/plain/README}.
1703 @c While the project is still under development, we have implemented the
1704 @c following features which we believe may be helpful for users and we
1705 @c would like them to be tested:
1710 @c Packaging GNUnet installation along with its run-time dependencies into
1714 @c Installing update packages into compatible hosts
1717 @c Updating an existing installation (which had been installed by
1718 @c gnunet-update) to a newer one
1722 @c The above said features of gnunet-update are currently available for
1723 @c testing on GNU/Linux systems.
1725 @c The following is a guide to help you get started with gnunet-update.
1726 @c It shows you how to install the testing binary packages of GNUnet
1727 @c 0.9.1 we have at @uref{https://gnunet.org/install/}.
1729 @c gnunet-update needs the following dependencies:
1733 @c python @geq{} 2.6
1743 @c Checkout gnunet-update:
1747 @c $ svn checkout -r24905 https://gnunet.org/svn/gnunet-update@
1750 @c For security reasons, all packages released for gnunet-update from us are
1751 @c signed with the key at @uref{https://gnunet.org/install/key.txt}.
1752 @c You would need to import this key into your gpg key ring.
1753 @c gnunet-update uses this key to verify the integrity of the packages it
1757 @c $ gpg --recv-keys 7C613D78@
1760 @c Download the packages relevant to your architecture (currently I have
1761 @c access to GNU/Linux machines on x86_64 and i686, so only two for now,
1762 @c hopefully more later) from https://gnunet.org/install/.
1764 @c To install the downloaded package into the directory /foo:
1767 @c gnunet-update/bin/gnunet-update install downloaded/package /foo
1770 @c The installer reports the directories into which shared libraries and
1771 @c dependencies have been installed. You may need to add the reported shared
1772 @c library installation paths to LD_LIBRARY_PATH before you start running any
1773 @c installed binaries.
1775 @c Please report bugs at https://gnunet.org/bugs/ under the project
1778 @node Instructions for Microsoft Windows Platforms (Old)
1779 @subsection Instructions for Microsoft Windows Platforms (Old)
1781 This document is a @b{DEPRECATED} installation guide for GNUnet on
1783 It will not work for recent GNUnet versions, but maybe it will be of
1784 some use if problems arise.
1786 The Windows build uses a UNIX emulator for Windows,
1787 @uref{http://www.mingw.org/, MinGW}, to build the executable modules.
1788 These modules run natively on Windows and do not require additional
1789 emulation software besides the usual dependencies.
1791 GNUnet development is mostly done under GNU/Linux and especially git
1792 checkouts may not build out of the box.
1793 We regret any inconvenience, and if you have problems, please report them.
1796 * Hardware and OS requirements::
1797 * Software installation::
1798 * Building libextractor and GNUnet::
1803 @node Hardware and OS requirements
1804 @subsubsection Hardware and OS requirements
1808 @item Pentium II or equivalent processor, @geq{} 350 MHz
1812 @item 600 MB free disk space
1814 @item Windows 2000 or Windows XP are recommended
1818 @node Software installation
1819 @subsubsection Software installation
1824 @strong{Compression software}@
1826 The software packages GNUnet depends on are usually compressed using UNIX
1827 tools like @command{tar}, @command{gzip}, @command{xzip} and
1829 If you do not already have an utility that is able to extract such
1830 archives, get @uref{http://www.7-zip.org/, 7-Zip}.
1833 @strong{UNIX environment}@
1835 The MinGW project provides the compiler toolchain that is used to build
1837 Get the following packages from the
1838 @uref{http://sourceforge.net/projects/mingw/files/, MinGW} project:
1845 @item MSYS Developer Tool Kit (msysDTK)
1846 @item MSYS Developer Tool Kit - msys-autoconf (bin)
1847 @item MSYS Developer Tool Kit - msys-automake (bin)
1849 @item MinGW Utilities
1854 @item GDB (snapshot)
1860 @item Install MSYS (to c:\mingw, for example.)@
1861 Do @strong{not} use spaces in the pathname.
1862 For example, avoid a location such as @file{c:\program files\mingw}.
1864 @item Install MinGW runtime, utilities and GCC to a subdirectory
1865 (to @file{c:\mingw\mingw}, for example)
1867 @item Install the Development Kit to the MSYS directory
1870 @item Create a batch file bash.bat in your MSYS directory with
1877 This batch file opens a shell which is used to invoke the build
1879 MinGW's standard shell (@command{msys.bat}) is not suitable
1880 because it opens a separate console window.
1881 On Vista, @command{bash.bat} needs to be run as Administrator.
1884 Start @command{bash.sh} and rename
1885 @file{c:\mingw\mingw\lib\libstdc++.la} to avoid problems:
1888 mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken
1892 Unpack the Windows API to the MinGW directory (@file{c:\mingw\mingw\}) and
1893 remove the declaration of DATADIR from
1894 (@file{c:\mingw\mingw\include\objidl.h} (lines 55-58)
1897 Unpack autoconf, automake to the MSYS directory (@file{c:\mingw})
1900 Install all other packages to the MinGW directory (@file{c:\mingw\mingw\})
1904 @item @strong{GNU Libtool}@
1905 GNU Libtool is required to use shared libraries.
1906 Get the prebuilt package from here and unpack it to the
1907 MinGW directory (@file{c:\mingw})
1909 @item @strong{Pthreads}@
1910 GNUnet uses the portable POSIX thread library for multi-threading:
1915 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/libpthreadGC2.a, libpthreadGC2.a}
1917 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/libpthreadGC2.a, libpthreadGC2.a}
1918 (x64) as libpthread.a into the @file{lib}
1919 directory (@file{c:\mingw\mingw\lib\libpthread.a}).
1922 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/pthreadGC2.dll, pthreadGC2.dll}
1924 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/pthreadGC2.dll, libpthreadGC2.a}
1925 (x64) into the MinGW @file{bin} directory (@file{c:\mingw\mingw\bin}).
1927 @item Download all header files from
1928 @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/include/, include/}
1929 to the @file{include} directory (@file{c:\mingw\mingw\include}).
1933 @item @strong{GNU MP}@
1934 GNUnet uses the GNU Multiple Precision library for special cryptographic
1935 operations. Get the GMP binary package from the
1936 @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and
1937 unpack it to the MinGW directory (@file{c:\mingw\mingw})
1939 @item @strong{GNU Gettext}@
1940 GNU gettext is used to provide national language support.
1941 Get the prebuilt package from hereand unpack it to the MinGW
1942 directory (@file{c:\mingw\mingw})
1944 @item @strong{GNU iconv}@
1945 GNU Libiconv is used for character encoding conversion.
1946 Get the prebuilt package from here and unpack it to the MinGW
1947 directory (@file{c:\mingw\mingw}).
1949 @item @strong{SQLite}@
1950 GNUnet uses the SQLite database to store data.
1951 Get the prebuilt binary from here and unpack it to your MinGW directory.
1953 @item @strong{MySQL}@
1954 As an alternative to SQLite, GNUnet also supports MySQL.
1958 @item Get the binary installer from the
1959 @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project}
1960 (version 4.1), install it and follow the instructions in
1961 @file{README.mysql}.
1963 @item Create a temporary build directory (@file{c:\mysql})
1965 @item Copy the directories @file{include\} and @file{lib\} from the
1966 MySQL directory to the new directory
1968 @item Get the patches from
1969 @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and
1970 @uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the
1971 latter is only required for MySQL
1977 @item Move @file{lib\opt\libmysql.dll} to @file{lib\libmysql.dll}
1979 @item Change to @file{lib\} and create an import library:
1982 dlltool --input-def ../include/libmySQL.def \
1983 --dllname libmysql.dll \
1984 --output-lib libmysqlclient.a -k
1987 @item Copy include\* to include\mysql\
1989 @item Pass @code{--with-mysql=/c/mysql} to
1990 @command{./configure} and copy @file{libmysql.dll}
1991 to your PATH or GNUnet's @file{bin} directory
1995 @item @strong{GTK+}@
1996 @command{gnunet-gtk} and @command{libextractor} depend on GTK.
1997 Get the the binary and developer packages of @command{atk},
1998 @command{glib}, @command{gtk}, @command{iconv},
1999 @command{gettext-runtime}, @command{pango} from
2000 @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack them
2001 to the MinGW directory (@file{c:\mingw\mingw}).
2002 @c FIXME: The URL below for pkg-config seems wrong.
2003 Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and
2004 @command{libpng} and unpack them to the MinGW directory
2005 (@file{c:\mingw\mingw}).
2006 Here is an all-in-one package for the
2007 @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies}
2008 . Do not overwrite any existing files!
2010 @item @strong{Glade}@
2011 @command{gnunet-gtk} and @command{gnunet-setup} were created using
2012 this interface builder
2016 @item Get the Glade and libglade (-bin and -devel) packages
2018 @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack them to
2019 the MinGW directory (@file{c:\mingw\mingw}).
2021 @item Get @command{libxml} from here and unpack it to the MinGW
2022 directory (@file{c:\mingw\mingw}).
2026 @item @strong{zLib}@
2027 @command{libextractor} requires @command{zLib} to decompress some file
2028 formats. GNUnet uses it to (de)compress meta-data.
2029 Get zLib from here (Signature) and unpack it to the MinGW directory
2030 (@file{c:\mingw\mingw}).
2032 @item @strong{Bzip2}@
2033 @command{libextractor} also requires @command{Bzip2} to
2034 decompress some file formats.
2035 Get the Bzip2 (binary and developer package) from
2036 @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and
2037 unpack it to the MinGW directory (@file{c:\mingw\mingw}).
2039 @item @strong{Libgcrypt}@
2040 @command{Libgcrypt} provides the cryptographic functions used by GNUnet.
2041 Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here},
2042 compile and place it in the MinGW directory
2043 (@file{c:\mingw\mingw}). Currently libgcrypt @geq{} 1.4.2 is required to
2046 @item @strong{PlibC}@
2047 PlibC emulates Unix functions under Windows. Get PlibC from here and
2048 unpack it to the MinGW directory (c:\mingw\mingw)
2050 @item @strong{OGG Vorbis}@
2051 @command{OGG Vorbis} is used to extract meta-data from @file{.ogg} files.
2053 @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg}
2055 @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis}
2057 @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build}
2058 and unpack them to the MinGW directory (c:\mingw\mingw).
2060 @item @strong{Exiv2}@
2061 (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data.
2063 @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2}
2064 and unpack it to the MSYS directory (c:\mingw).
2067 @node Building libextractor and GNUnet
2068 @subsubsection Building libextractor and GNUnet
2070 Before you compile @command{libextractor} or @command{GNUnet},
2071 be sure to set @code{PKG_CONFIG_PATH}:
2074 export PKG_CONFIG_PATH=/mingw/lib/pkgconfig
2078 @xref{GNUnet Installation Handbook}, for basic instructions on building
2079 @command{libextractor} and @command{GNUnet}.
2080 By default, all modules that are created in this way contain
2081 debug information and are quite large. To compile release versions
2082 (small and fast) set the variable @code{CFLAGS}:
2085 export CFLAGS='-O2 -march=pentium -fomit-frame-pointer'
2086 ./configure --prefix=$HOME --with-extractor=$HOME
2090 @subsubsection Installer
2092 The GNUnet installer is made with
2093 @uref{http://nsis.sourceforge.net/, NSIS}. The installer script is
2094 located in @file{contrib\win} in the GNUnet source tree.
2097 @subsubsection Source
2100 The sources of all dependencies are available here.
2102 @c @node Portable GNUnet
2103 @c @section Portable GNUnet
2105 @c Quick instructions on how to use the most recent GNUnet on most GNU/Linux
2108 @c Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian
2109 @c and CentOS 6, but it should work on almost any GNU/Linux distribution.
2110 @c More in-detail information can be found in the handbook.
2112 @c Note 2017-10: Currently this section assumes the old SVN repo of GNUnet
2113 @c which no longer exists.
2116 @c * Prerequisites::
2117 @c * Download & set up gnunet-update::
2118 @c * Install GNUnet::
2121 @c @node Prerequisites
2122 @c @subsection Prerequisites
2124 @c Open a terminal and paste this line into it to install all required tools
2128 @c sudo apt-get install python-gpgme subversion
2131 @c @node Download & set up gnunet-update
2132 @c @subsection Download & set up gnunet-update
2134 @c The following command will download a working version of gnunet-update
2135 @c with the subversion tool and import the public key which is needed for
2139 @c svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update
2140 @c cd ~/gnunet-update
2141 @c gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78
2144 @c @node Install GNUnet
2145 @c @subsection Install GNUnet
2147 @c Download and install GNUnet binaries which can be found here and set
2151 @c wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz
2152 @c ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~
2153 @c echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment
2154 @c echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \
2155 @c /etc/ld.so.conf.d/gnunet.conf > /dev/null
2159 @c You may need to re-login once after executing these last commands
2161 @c That's it, GNUnet is installed in your home directory now. GNUnet can be
2162 @c configured and afterwards started by executing:
2168 @node The graphical configuration interface
2169 @section The graphical configuration interface
2171 If you also would like to use @command{gnunet-gtk} and
2172 @command{gnunet-setup} (highly recommended for beginners), do:
2176 https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz
2177 sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~
2181 Now you can run @command{gnunet-setup} for easy configuration of your
2185 * Configuring your peer::
2186 * Configuring the Friend-to-Friend (F2F) mode::
2187 * Configuring the hostlist to bootstrap::
2188 * Configuration of the HOSTLIST proxy settings::
2189 * Configuring your peer to provide a hostlist ::
2190 * Configuring the datastore::
2191 * Configuring the MySQL database::
2192 * Reasons for using MySQL::
2193 * Reasons for not using MySQL::
2194 * Setup Instructions::
2196 * Performance Tuning::
2197 * Setup for running Testcases::
2198 * Configuring the Postgres database::
2199 * Reasons to use Postgres::
2200 * Reasons not to use Postgres::
2201 * Manual setup instructions::
2202 * Testing the setup manually::
2203 * Configuring the datacache::
2204 * Configuring the file-sharing service::
2205 * Configuring logging::
2206 * Configuring the transport service and plugins::
2207 * Configuring the wlan transport plugin::
2208 * Configuring HTTP(S) reverse proxy functionality using Apache or nginx::
2209 * Blacklisting peers::
2210 * Configuration of the HTTP and HTTPS transport plugins::
2211 * Configuring the GNU Name System::
2212 * Configuring the GNUnet VPN::
2213 * Bandwidth Configuration::
2215 * Peer configuration for distributions::
2218 @node Configuring your peer
2219 @subsection Configuring your peer
2221 This chapter will describe the various configuration options in GNUnet.
2223 The easiest way to configure your peer is to use the
2224 @command{gnunet-setup} tool.
2225 @command{gnunet-setup} is part of the @command{gnunet-gtk}
2226 application. You might have to install it separately.
2228 Many of the specific sections from this chapter actually are linked from
2229 within @command{gnunet-setup} to help you while using the setup tool.
2231 While you can also configure your peer by editing the configuration
2232 file by hand, this is not recommended for anyone except for developers
2233 as it requires a more in-depth understanding of the configuration files
2234 and internal dependencies of GNUnet.
2236 @node Configuring the Friend-to-Friend (F2F) mode
2237 @subsection Configuring the Friend-to-Friend (F2F) mode
2239 GNUnet knows three basic modes of operation:
2241 @item In standard "peer-to-peer" mode,
2242 your peer will connect to any peer.
2243 @item In the pure "friend-to-friend"
2244 mode, your peer will ONLY connect to peers from a list of friends
2245 specified in the configuration.
2246 @item Finally, in mixed mode,
2247 GNUnet will only connect to arbitrary peers if it
2248 has at least a specified number of connections to friends.
2251 When configuring any of the F2F ("friend-to-friend") modes,
2252 you first need to create a file with the peer identities
2253 of your friends. Ask your friends to run
2256 $ gnunet-peerinfo -sq
2260 The resulting output of this command needs to be added to your
2261 @file{friends} file, which is simply a plain text file with one line
2262 per friend with the output from the above command.
2264 You then specify the location of your @file{friends} file in the
2265 @code{FRIENDS} option of the "topology" section.
2267 Once you have created the @file{friends} file, you can tell GNUnet to only
2268 connect to your friends by setting the @code{FRIENDS-ONLY} option
2269 (again in the "topology" section) to YES.
2271 If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a
2272 minimum number of friends to have (before connecting to arbitrary peers)
2273 under the "MINIMUM-FRIENDS" option.
2275 If you want to operate in normal P2P-only mode, simply set
2276 @code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO.
2277 This is the default.
2279 @node Configuring the hostlist to bootstrap
2280 @subsection Configuring the hostlist to bootstrap
2282 After installing the software you need to get connected to the GNUnet
2283 network. The configuration file included in your download is already
2284 configured to connect you to the GNUnet network.
2285 In this section the relevant configuration settings are explained.
2287 To get an initial connection to the GNUnet network and to get to know
2288 peers already connected to the network you can use the so called
2289 "bootstrap servers".
2290 These servers can give you a list of peers connected to the network.
2291 To use these bootstrap servers you have to configure the hostlist daemon
2292 to activate bootstrapping.
2294 To activate bootstrapping, edit the @code{[hostlist]}-section in your
2295 configuration file. You have to set the argument @command{-b} in the
2303 Additionally you have to specify which server you want to use.
2304 The default bootstrapping server is
2305 "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}".
2306 [^] To set the server you have to edit the line "SERVERS" in the hostlist
2307 section. To use the default server you should set the lines to
2310 SERVERS = http://v10.gnunet.org/hostlist [^]
2314 To use bootstrapping your configuration file should include these lines:
2319 SERVERS = http://v10.gnunet.org/hostlist [^]
2323 Besides using bootstrap servers you can configure your GNUnet peer to
2324 recieve hostlist advertisements.
2325 Peers offering hostlists to other peers can send advertisement messages
2326 to peers that connect to them. If you configure your peer to receive these
2327 messages, your peer can download these lists and connect to the peers
2328 included. These lists are persistent, which means that they are saved to
2329 your hard disk regularly and are loaded during startup.
2331 To activate hostlist learning you have to add the @command{-e}
2332 switch to the @code{OPTIONS} line in the hostlist section:
2340 Furthermore you can specify in which file the lists are saved.
2341 To save the lists in the file @file{hostlists.file} just add the line:
2344 HOSTLISTFILE = hostlists.file
2348 Best practice is to activate both bootstrapping and hostlist learning.
2349 So your configuration file should include these lines:
2355 SERVERS = http://v10.gnunet.org/hostlist [^]
2356 HOSTLISTFILE = $SERVICEHOME/hostlists.file
2359 @node Configuration of the HOSTLIST proxy settings
2360 @subsection Configuration of the HOSTLIST proxy settings
2362 The hostlist client can be configured to use a proxy to connect to the
2364 This functionality can be configured in the configuration file directly
2365 or using the @command{gnunet-setup} tool.
2367 The hostlist client supports the following proxy types at the moment:
2370 @item HTTP and HTTP 1.0 only proxy
2371 @item SOCKS 4/4a/5/5 with hostname
2374 In addition authentication at the proxy with username and password can be
2377 To configure proxy support for the hostlist client in the
2378 @command{gnunet-setup} tool, select the "hostlist" tab and select
2379 the appropriate proxy type.
2380 The hostname or IP address (including port if required) has to be entered
2381 in the "Proxy hostname" textbox. If required, enter username and password
2382 in the "Proxy username" and "Proxy password" boxes.
2383 Be aware that this information will be stored in the configuration in
2384 plain text (TODO: Add explanation and generalize the part in Chapter 3.6
2385 about the encrypted home).
2387 To provide these options directly in the configuration, you can
2388 enter the following settings in the @code{[hostlist]} section of
2392 # Type of proxy server,
2393 # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME
2397 # Hostname or IP of proxy server
2399 # User name for proxy server
2401 # User password for proxy server
2405 @node Configuring your peer to provide a hostlist
2406 @subsection Configuring your peer to provide a hostlist
2408 If you operate a peer permanently connected to GNUnet you can configure
2409 your peer to act as a hostlist server, providing other peers the list of
2412 Your server can act as a bootstrap server and peers needing to obtain a
2413 list of peers can contact it to download this list.
2414 To download this hostlist the peer uses HTTP.
2415 For this reason you have to build your peer with libgnurl (or libcurl)
2416 and microhttpd support.
2417 How you build your peer with these options can be found here:
2418 @xref{Generic installation instructions}.
2420 To configure your peer to act as a bootstrap server you have to add the
2421 @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section
2422 of your configuration file.
2423 Besides that you have to specify a port number for the http server.
2424 In conclusion you have to add the following lines:
2433 If your peer acts as a bootstrap server other peers should know about
2434 that. You can advertise the hostlist your are providing to other peers.
2435 Peers connecting to your peer will get a message containing an
2436 advertisement for your hostlist and the URL where it can be downloaded.
2437 If this peer is in learning mode, it will test the hostlist and, in the
2438 case it can obtain the list successfully, it will save it for
2441 To activate hostlist advertisement on your peer, you have to set the
2442 following lines in your configuration file:
2446 EXTERNAL_DNS_NAME = example.org
2452 With this configuration your peer will a act as a bootstrap server and
2453 advertise this hostlist to other peers connecting to it.
2454 The URL used to download the list will be
2455 @code{@uref{http://example.org:12981/, http://example.org:12981/}}.
2460 @item The hostlist is @b{not} human readable, so you should not try to
2461 download it using your webbrowser. Just point your GNUnet peer to the
2463 @item Advertising without providing a hostlist does not make sense and
2467 @node Configuring the datastore
2468 @subsection Configuring the datastore
2470 The datastore is what GNUnet uses for long-term storage of file-sharing
2471 data. Note that long-term does not mean 'forever' since content does have
2472 an expiration date, and of course storage space is finite (and hence
2473 sometimes content may have to be discarded).
2475 Use the @code{QUOTA} option to specify how many bytes of storage space
2476 you are willing to dedicate to GNUnet.
2478 In addition to specifying the maximum space GNUnet is allowed to use for
2479 the datastore, you need to specify which database GNUnet should use to do
2480 so. Currently, you have the choice between sqLite, MySQL and Postgres.
2482 @node Configuring the MySQL database
2483 @subsection Configuring the MySQL database
2485 This section describes how to setup the MySQL database for GNUnet.
2487 Note that the mysql plugin does NOT work with mysql before 4.1 since we
2488 need prepared statements.
2489 We are generally testing the code against MySQL 5.1 at this point.
2491 @node Reasons for using MySQL
2492 @subsection Reasons for using MySQL
2496 @item On up-to-date hardware wher
2497 mysql can be used comfortably, this module
2498 will have better performance than the other database choices (according
2501 @item Its often possible to recover the mysql database from internal
2502 inconsistencies. Some of the other databases do not support repair.
2505 @node Reasons for not using MySQL
2506 @subsection Reasons for not using MySQL
2509 @item Memory usage (likely not an issue if you have more than 1 GB)
2510 @item Complex manual setup
2513 @node Setup Instructions
2514 @subsection Setup Instructions
2518 @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
2519 @code{DATABASE} to @code{mysql}.
2521 @item Access mysql as root:
2528 and issue the following commands, replacing $USER with the username
2529 that will be running @command{gnunet-arm} (so typically "gnunet"):
2532 CREATE DATABASE gnunet;
2533 GRANT select,insert,update,delete,create,alter,drop,create \
2534 temporary tables ON gnunet.* TO $USER@@localhost;
2535 SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like');
2540 In the $HOME directory of $USER, create a @file{.my.cnf} file with the
2546 password=$the_password_you_like
2551 Thats it. Note that @file{.my.cnf} file is a slight security risk unless
2552 its on a safe partition. The @file{$HOME/.my.cnf} can of course be
2554 Luckily $USER has only priviledges to mess up GNUnet's tables,
2555 which should be pretty harmless.
2560 You should briefly try if the database connection works. First, login
2569 If you get the message
2581 ERROR 2002: Can't connect to local MySQL server
2582 through socket '/tmp/mysql.sock' (2)
2586 it may be resolvable by
2589 ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock
2593 so there may be some additional trouble depending on your mysql setup.
2595 @node Performance Tuning
2596 @subsection Performance Tuning
2598 For GNUnet, you probably want to set the option
2601 innodb_flush_log_at_trx_commit = 0
2605 for a rather dramatic boost in MySQL performance. However, this reduces
2606 the "safety" of your database as with this options you may loose
2607 transactions during a power outage.
2608 While this is totally harmless for GNUnet, the option applies to all
2609 applications using MySQL. So you should set it if (and only if) GNUnet is
2610 the only application on your system using MySQL.
2612 @node Setup for running Testcases
2613 @subsection Setup for running Testcases
2615 If you want to run the testcases, you must create a second database
2616 "gnunetcheck" with the same username and password. This database will
2617 then be used for testing (@command{make check}).
2619 @node Configuring the Postgres database
2620 @subsection Configuring the Postgres database
2622 This text describes how to setup the Postgres database for GNUnet.
2624 This Postgres plugin was developed for Postgres 8.3 but might work for
2625 earlier versions as well.
2627 @node Reasons to use Postgres
2628 @subsection Reasons to use Postgres
2631 @item Easier to setup than MySQL
2635 @node Reasons not to use Postgres
2636 @subsection Reasons not to use Postgres
2640 @item Still some manual setup required
2643 @node Manual setup instructions
2644 @subsection Manual setup instructions
2647 @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
2648 @code{DATABASE} to @code{postgres}.
2649 @item Access Postgres to create a user:
2652 @item with Postgres 8.x, use:
2660 and enter the name of the user running GNUnet for the role interactively.
2661 Then, when prompted, do not set it to superuser, allow the creation of
2662 databases, and do not allow the creation of new roles.
2664 @item with Postgres 9.x, use:
2668 $ createuser -d $GNUNET_USER
2672 where $GNUNET_USER is the name of the user running GNUnet.
2678 As that user (so typically as user "gnunet"), create a database (or two):
2682 # this way you can run "make check"
2683 $ createdb gnunetcheck
2688 Now you should be able to start @code{gnunet-arm}.
2690 @node Testing the setup manually
2691 @subsection Testing the setup manually
2693 You may want to try if the database connection works. First, again login
2694 as the user who will run @command{gnunet-arm}. Then use:
2697 $ psql gnunet # or gnunetcheck
2702 If, after you have started @command{gnunet-arm} at least once, you get
2703 a @code{gn090} table here, it probably works.
2705 @node Configuring the datacache
2706 @subsection Configuring the datacache
2709 The datacache is what GNUnet uses for storing temporary data. This data is
2710 expected to be wiped completely each time GNUnet is restarted (or the
2711 system is rebooted).
2713 You need to specify how many bytes GNUnet is allowed to use for the
2714 datacache using the @code{QUOTA} option in the section @code{[dhtcache]}.
2715 Furthermore, you need to specify which database backend should be used to
2716 store the data. Currently, you have the choice between
2717 sqLite, MySQL and Postgres.
2719 @node Configuring the file-sharing service
2720 @subsection Configuring the file-sharing service
2722 In order to use GNUnet for file-sharing, you first need to make sure
2723 that the file-sharing service is loaded.
2724 This is done by setting the @code{AUTOSTART} option in
2725 section @code{[fs]} to "YES". Alternatively, you can run
2732 to start the file-sharing service by hand.
2734 Except for configuring the database and the datacache the only important
2735 option for file-sharing is content migration.
2737 Content migration allows your peer to cache content from other peers as
2738 well as send out content stored on your system without explicit requests.
2739 This content replication has positive and negative impacts on both system
2740 performance and privacy.
2742 FIXME: discuss the trade-offs. Here is some older text about it...
2744 Setting this option to YES allows gnunetd to migrate data to the local
2745 machine. Setting this option to YES is highly recommended for efficiency.
2746 Its also the default. If you set this value to YES, GNUnet will store
2747 content on your machine that you cannot decrypt.
2748 While this may protect you from liability if the judge is sane, it may
2749 not (IANAL). If you put illegal content on your machine yourself, setting
2750 this option to YES will probably increase your chances to get away with it
2751 since you can plausibly deny that you inserted the content.
2752 Note that in either case, your anonymity would have to be broken first
2753 (which may be possible depending on the size of the GNUnet network and the
2754 strength of the adversary).
2756 @node Configuring logging
2757 @subsection Configuring logging
2759 Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options.
2760 Using @code{-L}, a log level can be specified. With log level
2761 @code{ERROR} only serious errors are logged.
2762 The default log level is @code{WARNING} which causes anything of
2763 concern to be logged.
2764 Log level @code{INFO} can be used to log anything that might be
2765 interesting information whereas
2766 @code{DEBUG} can be used by developers to log debugging messages
2767 (but you need to run @code{./configure} with
2768 @code{--enable-logging=verbose} to get them compiled).
2769 The @code{-l} option is used to specify the log file.
2771 Since most GNUnet services are managed by @code{gnunet-arm}, using the
2772 @code{-l} or @code{-L} options directly is not possible.
2773 Instead, they can be specified using the @code{OPTIONS} configuration
2774 value in the respective section for the respective service.
2775 In order to enable logging globally without editing the @code{OPTIONS}
2776 values for each service, @command{gnunet-arm} supports a
2777 @code{GLOBAL_POSTFIX} option.
2778 The value specified here is given as an extra option to all services for
2779 which the configuration does contain a service-specific @code{OPTIONS}
2782 @code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which
2783 is replaced by the name of the service that is being started.
2784 Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences
2785 starting with "$" anywhere in the string are expanded (according
2786 to options in @code{PATHS}); this expansion otherwise is
2787 only happening for filenames and then the "$" must be the
2788 first character in the option. Both of these restrictions do
2789 not apply to @code{GLOBAL_POSTFIX}.
2790 Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX}
2791 disables both of these features.
2793 In summary, in order to get all services to log at level
2794 @code{INFO} to log-files called @code{SERVICENAME-logs}, the
2795 following global prefix should be used:
2798 GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO
2801 @node Configuring the transport service and plugins
2802 @subsection Configuring the transport service and plugins
2804 The transport service in GNUnet is responsible to maintain basic
2805 connectivity to other peers.
2806 Besides initiating and keeping connections alive it is also responsible
2807 for address validation.
2809 The GNUnet transport supports more than one transport protocol.
2810 These protocols are configured together with the transport service.
2812 The configuration section for the transport service itself is quite
2813 similar to all the other services
2817 @@UNIXONLY@@ PORT = 2091
2818 HOSTNAME = localhost
2820 CONFIG = $DEFAULTCONFIG
2821 BINARY = gnunet-service-transport
2823 NEIGHBOUR_LIMIT = 50
2824 ACCEPT_FROM = 127.0.0.1;
2827 UNIXPATH = /tmp/gnunet-service-transport.sock
2830 Different are the settings for the plugins to load @code{PLUGINS}.
2831 The first setting specifies which transport plugins to load.
2834 @item transport-unix
2835 A plugin for local only communication with UNIX domain sockets. Used for
2836 testing and available on unix systems only. Just set the port
2841 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2845 A plugin for communication with TCP. Set port to 0 for client mode with
2846 outbound only connections
2850 # Use 0 to ONLY advertise as a peer behind NAT (no port binding)
2852 ADVERTISED_PORT = 2086
2853 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2854 # Maximum number of open TCP connections allowed
2855 MAX_CONNECTIONS = 128
2859 A plugin for communication with UDP. Supports peer discovery using
2866 BROADCAST_INTERVAL = 30 s
2868 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2871 @item transport-http
2872 HTTP and HTTPS support is split in two part: a client plugin initiating
2873 outbound connections and a server part accepting connections from the
2874 client. The client plugin just takes the maximum number of connections as
2878 [transport-http_client]
2879 MAX_CONNECTIONS = 128
2880 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2884 [transport-https_client]
2885 MAX_CONNECTIONS = 128
2886 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2890 The server has a port configured and the maximum nunber of connections.
2891 The HTTPS part has two files with the certificate key and the certificate
2894 The server plugin supports reverse proxies, so a external hostname can be
2895 set using the @code{EXTERNAL_HOSTNAME} setting.
2896 The webserver under this address should forward the request to the peer
2897 and the configure port.
2900 [transport-http_server]
2901 EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet
2903 MAX_CONNECTIONS = 128
2904 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2908 [transport-https_server]
2910 CRYPTO_INIT = NORMAL
2911 KEY_FILE = https.key
2912 CERT_FILE = https.cert
2913 MAX_CONNECTIONS = 128
2914 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2917 @item transport-wlan
2919 The next section describes how to setup the WLAN plugin,
2920 so here only the settings. Just specify the interface to use:
2924 # Name of the interface in monitor mode (typically monX)
2926 # Real hardware, no testing
2928 TESTING_IGNORE_KEYS = ACCEPT_FROM;
2932 @node Configuring the wlan transport plugin
2933 @subsection Configuring the wlan transport plugin
2935 The wlan transport plugin enables GNUnet to send and to receive data on a
2937 It has not to be connected to a wlan network as long as sender and
2938 receiver are on the same channel. This enables you to get connection to
2939 GNUnet where no internet access is possible, for example during
2940 catastrophes or when censorship cuts you off from the internet.
2944 * Requirements for the WLAN plugin::
2946 * Before starting GNUnet::
2947 * Limitations and known bugs::
2951 @node Requirements for the WLAN plugin
2952 @subsubsection Requirements for the WLAN plugin
2956 @item wlan network card with monitor support and packet injection
2957 (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org})
2959 @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with
2962 @item Wlantools to create the a monitor interface, tested with airmon-ng
2963 of the aircrack-ng package
2967 @subsubsection Configuration
2969 There are the following options for the wlan plugin (they should be like
2970 this in your default config file, you only need to adjust them if the
2971 values are incorrect for your system)
2974 # section for the wlan transport plugin
2976 # interface to use, more information in the
2977 # "Before starting GNUnet" section of the handbook.
2979 # testmode for developers:
2980 # 0 use wlan interface,
2981 #1 or 2 use loopback driver for tests 1 = server, 2 = client
2985 @node Before starting GNUnet
2986 @subsubsection Before starting GNUnet
2988 Before starting GNUnet, you have to make sure that your wlan interface is
2990 One way to put the wlan interface into monitor mode (if your interface
2991 name is wlan0) is by executing:
2994 sudo airmon-ng start wlan0
2998 Here is an example what the result should look like:
3001 Interface Chipset Driver
3002 wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]
3003 (monitor mode enabled on mon0)
3007 The monitor interface is mon0 is the one that you have to put into the
3010 @node Limitations and known bugs
3011 @subsubsection Limitations and known bugs
3013 Wlan speed is at the maximum of 1 Mbit/s because support for choosing the
3014 wlan speed with packet injection was removed in newer kernels.
3015 Please pester the kernel developers about fixing this.
3017 The interface channel depends on the wlan network that the card is
3018 connected to. If no connection has been made since the start of the
3019 computer, it is usually the first channel of the card.
3020 Peers will only find each other and communicate if they are on the same
3021 channel. Channels must be set manually, i.e. using:
3024 iwconfig wlan0 channel 1
3027 @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx
3028 @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
3030 The HTTP plugin supports data transfer using reverse proxies. A reverse
3031 proxy forwards the HTTP request he receives with a certain URL to another
3032 webserver, here a GNUnet peer.
3034 So if you have a running Apache or nginx webserver you can configure it to
3035 be a GNUnet reverse proxy. Especially if you have a well-known webiste
3036 this improves censorship resistance since it looks as normal surfing
3039 To do so, you have to do two things:
3042 @item Configure your webserver to forward the GNUnet HTTP traffic
3043 @item Configure your GNUnet peer to announce the respective address
3046 As an example we want to use GNUnet peer running:
3050 @item HTTP server plugin on @code{gnunet.foo.org:1080}
3052 @item HTTPS server plugin on @code{gnunet.foo.org:4433}
3054 @item A apache or nginx webserver on
3055 @uref{http://www.foo.org/, http://www.foo.org:80/}
3057 @item A apache or nginx webserver on https://www.foo.org:443/
3060 And we want the webserver to accept GNUnet traffic under
3061 @code{http://www.foo.org/bar/}. The required steps are described here:
3064 * Reverse Proxy - Configure your Apache2 HTTP webserver::
3065 * Reverse Proxy - Configure your Apache2 HTTPS webserver::
3066 * Reverse Proxy - Configure your nginx HTTPS webserver::
3067 * Reverse Proxy - Configure your nginx HTTP webserver::
3068 * Reverse Proxy - Configure your GNUnet peer::
3071 @node Reverse Proxy - Configure your Apache2 HTTP webserver
3072 @subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver
3074 First of all you need mod_proxy installed.
3076 Edit your webserver configuration. Edit
3077 @code{/etc/apache2/apache2.conf} or the site-specific configuration file.
3079 In the respective @code{server config},@code{virtual host} or
3080 @code{directory} section add the following lines:
3086 ProxyPass http://gnunet.foo.org:1080/
3087 ProxyPassReverse http://gnunet.foo.org:1080/
3091 @node Reverse Proxy - Configure your Apache2 HTTPS webserver
3092 @subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver
3094 We assume that you already have an HTTPS server running, if not please
3095 check how to configure a HTTPS host. An uncomplicated to use example
3096 is the example configuration file for Apache2/HTTPD provided in
3097 @file{apache2/sites-available/default-ssl}.
3099 In the respective HTTPS @code{server config},@code{virtual host} or
3100 @code{directory} section add the following lines:
3107 ProxyPass https://gnunet.foo.org:4433/
3108 ProxyPassReverse https://gnunet.foo.org:4433/
3113 More information about the apache mod_proxy configuration can be found
3114 in the Apache documentation@footnote{@uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass}}
3116 @node Reverse Proxy - Configure your nginx HTTPS webserver
3117 @subsubsection Reverse Proxy - Configure your nginx HTTPS webserver
3119 Since nginx does not support chunked encoding, you first of all have to
3120 install the @code{chunkin} module@footnote{@uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}}
3122 To enable chunkin add:
3126 error_page 411 = @@my_411_error;
3127 location @@my_411_error @{
3133 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
3134 the site-specific configuration file.
3136 In the @code{server} section add:
3140 proxy_pass http://gnunet.foo.org:1080/;
3141 proxy_buffering off;
3142 proxy_connect_timeout 5; # more than http_server
3143 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout
3144 proxy_http_version 1.1; # 1.0 default
3145 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;
3149 @node Reverse Proxy - Configure your nginx HTTP webserver
3150 @subsubsection Reverse Proxy - Configure your nginx HTTP webserver
3152 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
3153 the site-specific configuration file.
3155 In the @code{server} section add:
3158 ssl_session_timeout 6m;
3161 proxy_pass https://gnunet.foo.org:4433/;
3162 proxy_buffering off;
3163 proxy_connect_timeout 5; # more than http_server
3164 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout
3165 proxy_http_version 1.1; # 1.0 default
3166 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;
3170 @node Reverse Proxy - Configure your GNUnet peer
3171 @subsubsection Reverse Proxy - Configure your GNUnet peer
3173 To have your GNUnet peer announce the address, you have to specify the
3174 @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]}
3178 [transport-http_server]
3179 EXTERNAL_HOSTNAME = http://www.foo.org/bar/
3183 and/or @code{[transport-https_server]} section:
3186 [transport-https_server]
3187 EXTERNAL_HOSTNAME = https://www.foo.org/bar/
3191 Now restart your webserver and your peer...
3193 @node Blacklisting peers
3194 @subsection Blacklisting peers
3196 Transport service supports to deny connecting to a specific peer of to a
3197 specific peer with a specific transport plugin using te blacklisting
3198 component of transport service. With@ blacklisting it is possible to deny
3199 connections to specific peers of@ to use a specific plugin to a specific
3200 peer. Peers can be blacklisted using@ the configuration or a blacklist
3201 client can be asked.
3203 To blacklist peers using the configuration you have to add a section to
3204 your configuration containing the peer id of the peer to blacklist and
3205 the plugin@ if required.
3209 To blacklist connections to P565... on peer AG2P... using tcp add:
3211 @c FIXME: This is too long and produces errors in the pdf.
3213 [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
3214 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp
3217 To blacklist connections to P565... on peer AG2P... using all plugins add:
3220 [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
3221 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =
3224 You can also add a blacklist client usign the blacklist API. On a
3225 blacklist check, blacklisting first checks internally if the peer is
3226 blacklisted and if not, it asks the blacklisting clients. Clients are
3227 asked if it is OK to connect to a peer ID, the plugin is omitted.
3229 On blacklist check for (peer, plugin)
3231 @item Do we have a local blacklist entry for this peer and this plugin?@
3232 @item YES: disallow connection@
3233 @item Do we have a local blacklist entry for this peer and all plugins?@
3234 @item YES: disallow connection@
3235 @item Does one of the clients disallow?@
3236 @item YES: disallow connection
3239 @node Configuration of the HTTP and HTTPS transport plugins
3240 @subsection Configuration of the HTTP and HTTPS transport plugins
3242 The client parts of the http and https transport plugins can be configured
3243 to use a proxy to connect to the hostlist server. This functionality can
3244 be configured in the configuration file directly or using the
3247 Both the HTTP and HTTPS clients support the following proxy types at
3251 @item HTTP 1.1 proxy
3252 @item SOCKS 4/4a/5/5 with hostname
3255 In addition authentication at the proxy with username and password can be
3258 To configure proxy support for the clients in the gnunet-setup tool,
3259 select the "transport" tab and activate the respective plugin. Now you
3260 can select the appropriate proxy type. The hostname or IP address
3261 (including port if required) has to be entered in the "Proxy hostname"
3262 textbox. If required, enter username and password in the "Proxy username"
3263 and "Proxy password" boxes. Be aware that these information will be stored
3264 in the configuration in plain text.
3266 To configure these options directly in the configuration, you can
3267 configure the following settings in the @code{[transport-http_client]}
3268 and @code{[transport-https_client]} section of the configuration:
3271 # Type of proxy server,
3272 # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME
3276 # Hostname or IP of proxy server
3278 # User name for proxy server
3280 # User password for proxy server
3284 @node Configuring the GNU Name System
3285 @subsection Configuring the GNU Name System
3288 * Configuring system-wide DNS interception::
3289 * Configuring the GNS nsswitch plugin::
3290 * Configuring GNS on W32::
3292 * Setup of the GNS CA::
3293 * Testing the GNS setup::
3294 * Automatic Shortening in the GNU Name System::
3298 @node Configuring system-wide DNS interception
3299 @subsubsection Configuring system-wide DNS interception
3301 Before you install GNUnet, make sure you have a user and group 'gnunet'
3302 as well as an empty group 'gnunetdns'.
3304 When using GNUnet with system-wide DNS interception, it is absolutely
3305 necessary for all GNUnet service processes to be started by
3306 @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be
3307 sure to run @code{make install} as root (or use the @code{sudo} option to
3308 configure) to grant GNUnet sufficient privileges.
3310 With this setup, all that is required for enabling system-wide DNS
3311 interception is for some GNUnet component (VPN or GNS) to request it.
3312 The @code{gnunet-service-dns} will then start helper programs that will
3313 make the necessary changes to your firewall (@code{iptables}) rules.
3315 Note that this will NOT work if your system sends out DNS traffic to a
3316 link-local IPv6 address, as in this case GNUnet can intercept the traffic,
3317 but not inject the responses from the link-local IPv6 address. Hence you
3318 cannot use system-wide DNS interception in conjunction with link-local
3319 IPv6-based DNS servers. If such a DNS server is used, it will bypass
3320 GNUnet's DNS traffic interception.
3322 Using the GNU Name System (GNS) requires two different configuration
3324 First of all, GNS needs to be integrated with the operating system. Most
3325 of this section is about the operating system level integration.
3327 Additionally, each individual user who wants to use the system must also
3328 initialize their GNS zones. This can be done by running (after starting
3332 $ gnunet-gns-import.sh
3336 after the local GNUnet peer has been started. Note that the namestore (in
3337 particular the namestore database backend) should not be reconfigured
3338 afterwards (as records are not automatically migrated between backends).
3340 The remainder of this chapter will detail the various methods for
3341 configuring the use of GNS with your operating system.
3343 At this point in time you have different options depending on your OS:
3347 @item Use the gnunet-gns-proxy This approach works for all operating
3348 systems and is likely the easiest. However, it enables GNS only for
3349 browsers, not for other applications that might be using DNS, such as SSH.
3350 Still, using the proxy is required for using HTTP with GNS and is thus
3351 recommended for all users. To do this, you simply have to run the
3352 @code{gnunet-gns-proxy-setup-ca} script as the user who will run the
3353 browser (this will create a GNS certificate authority (CA) on your system
3354 and import its key into your browser), then start @code{gnunet-gns-proxy}
3355 and inform your browser to use the Socks5 proxy which
3356 @code{gnunet-gns-proxy} makes available by default on port 7777.
3357 @item Use a nsswitch plugin (recommended on GNU systems)
3358 This approach has the advantage of offering fully personalized resolution
3359 even on multi-user systems. A potential disadvantage is that some
3360 applications might be able to bypass GNS.
3361 @item Use a W32 resolver plugin (recommended on W32)
3362 This is currently the only option on W32 systems.
3363 @item Use system-wide DNS packet interception
3364 This approach is recommended for the GNUnet VPN. It can be used to handle
3365 GNS at the same time; however, if you only use this method, you will only
3366 get one root zone per machine (not so great for multi-user systems).
3369 You can combine system-wide DNS packet interception with the nsswitch
3371 The setup of the system-wide DNS interception is described here. All of
3372 the other GNS-specific configuration steps are described in the following
3375 @node Configuring the GNS nsswitch plugin
3376 @subsubsection Configuring the GNS nsswitch plugin
3378 The Name Service Switch (NSS) is a facility in Unix-like operating systems
3379 @footnote{More accurate: NSS is a functionality of the GNU C Library}
3380 that provides a variety of sources for common configuration databases and
3381 name resolution mechanisms.
3382 A superuser (system administrator) usually configures the
3383 operating system's name services using the file
3384 @file{/etc/nsswitch.conf}.
3386 GNS provides a NSS plugin to integrate GNS name resolution with the
3387 operating system's name resolution process.
3388 To use the GNS NSS plugin you have to either
3391 @item install GNUnet as root or
3392 @item compile GNUnet with the @code{--with-sudo=yes} switch.
3395 Name resolution is controlled by the @emph{hosts} section in the NSS
3396 configuration. By default this section first performs a lookup in the
3397 @file{/etc/hosts} file and then in DNS.
3398 The nsswitch file should contain a line similar to:
3401 hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4
3405 Here the GNS NSS plugin can be added to perform a GNS lookup before
3406 performing a DNS lookup.
3407 The GNS NSS plugin has to be added to the "hosts" section in
3408 @file{/etc/nsswitch.conf} file before DNS related plugins:
3412 hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4
3417 The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not
3418 found in GNS it will not be queried in DNS.
3420 @node Configuring GNS on W32
3421 @subsubsection Configuring GNS on W32
3423 This document is a guide to configuring GNU Name System on W32-compatible
3426 After GNUnet is installed, run the w32nsp-install tool:
3429 w32nsp-install.exe libw32nsp-0.dll
3433 ('0' is the library version of W32 NSP; it might increase in the future,
3434 change the invocation accordingly).
3436 This will install GNS namespace provider into the system and allow other
3437 applications to resolve names that end in '@strong{gnu}'
3438 and '@strong{zkey}'. Note that namespace provider requires
3439 gnunet-gns-helper-service-w32 to be running, as well as gns service
3440 itself (and its usual dependencies).
3442 Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353},
3443 and this is where gnunet-gns-helper-service-w32 should be listening to
3444 (and is configured to listen to by default).
3446 To uninstall the provider, run:
3449 w32nsp-uninstall.exe
3453 (uses provider GUID to uninstall it, does not need a dll name).
3455 Note that while MSDN claims that other applications will only be able to
3456 use the new namespace provider after re-starting, in reality they might
3457 stat to use it without that. Conversely, they might stop using the
3458 provider after it's been uninstalled, even if they were not re-started.
3459 W32 will not permit namespace provider library to be deleted or
3460 overwritten while the provider is installed, and while there is at least
3461 one process still using it (even after it was uninstalled).
3463 @node GNS Proxy Setup
3464 @subsubsection GNS Proxy Setup
3466 When using the GNU Name System (GNS) to browse the WWW, there are several
3467 issues that can be solved by adding the GNS Proxy to your setup:
3471 @item If the target website does not support GNS, it might assume that it
3472 is operating under some name in the legacy DNS system (such as
3473 example.com). It may then attempt to set cookies for that domain, and the
3474 web server might expect a @code{Host: example.com} header in the request
3476 However, your browser might be using @code{example.gnu} for the
3477 @code{Host} header and might only accept (and send) cookies for
3478 @code{example.gnu}. The GNS Proxy will perform the necessary translations
3479 of the hostnames for cookies and HTTP headers (using the LEHO record for
3480 the target domain as the desired substitute).
3482 @item If using HTTPS, the target site might include an SSL certificate
3483 which is either only valid for the LEHO domain or might match a TLSA
3484 record in GNS. However, your browser would expect a valid certificate for
3485 @code{example.gnu}, not for some legacy domain name. The proxy will
3486 validate the certificate (either against LEHO or TLSA) and then
3487 on-the-fly produce a valid certificate for the exchange, signed by your
3488 own CA. Assuming you installed the CA of your proxy in your browser's
3489 certificate authority list, your browser will then trust the
3490 HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy.
3492 @item Finally, the proxy will in the future indicate to the server that it
3493 speaks GNS, which will enable server operators to deliver GNS-enabled web
3494 sites to your browser (and continue to deliver legacy links to legacy
3498 @node Setup of the GNS CA
3499 @subsubsection Setup of the GNS CA
3501 First you need to create a CA certificate that the proxy can use.
3502 To do so use the provided script gnunet-gns-proxy-ca:
3505 $ gnunet-gns-proxy-setup-ca
3509 This will create a personal certification authority for you and add this
3510 authority to the firefox and chrome database. The proxy will use the this
3511 CA certificate to generate @code{*.gnu} client certificates on the fly.
3513 Note that the proxy uses libcurl. Make sure your version of libcurl uses
3514 GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled
3517 You can check the configuration your libcurl was build with by
3524 the output will look like this (without the linebreaks):
3528 curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \
3529 GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4
3530 Release-Date: 2017-10-08
3531 Protocols: http https
3532 Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \
3533 TLS-SRP UnixSockets HTTPS-proxy
3536 @node Testing the GNS setup
3537 @subsubsection Testing the GNS setup
3539 Now for testing purposes we can create some records in our zone to test
3540 the SSL functionality of the proxy:
3543 $ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67
3544 $ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org"
3548 At this point we can start the proxy. Simply execute
3555 Configure your browser to use this SOCKSv5 proxy on port 7777 and visit
3557 If you use @command{Firefox} (or one of its deriviates/forks such as
3558 Icecat) you also have to go to @code{about:config} and set the key
3559 @code{network.proxy.socks_remote_dns} to @code{true}.
3561 When you visit @code{https://homepage.gnu/}, you should get to the
3562 @code{https://gnunet.org/} frontpage and the browser (with the correctly
3563 configured proxy) should give you a valid SSL certificate for
3564 @code{homepage.gnu} and no warnings. It should look like this:
3566 @c FIXME: Image does not exist, create it or save it from Drupal?
3567 @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser}
3569 @node Automatic Shortening in the GNU Name System
3570 @subsubsection Automatic Shortening in the GNU Name System
3572 This page describes a possible option for 'automatic name shortening',
3573 which you can choose to enable with the GNU Name System.
3575 When GNS encounters a name for the first time, it can use the 'NICK'
3576 record of the originating zone to automatically generate a name for the
3577 zone. If automatic shortening is enabled, those auto-generated names will
3578 be placed (as private records) into your personal 'shorten' zone (to
3579 prevent confusion with manually selected names).
3580 Then, in the future, if the same name is encountered again, GNS will
3581 display the shortened name instead (the first time, the long name will
3582 still be used as shortening typically happens asynchronously as looking up
3583 the 'NICK' record takes some time). Using this feature can be a convenient
3584 way to avoid very long @code{.gnu} names; however, note that names from
3585 the shorten-zone are assigned on a first-come-first-serve basis and should
3586 not be trusted. Furthermore, if you enable this feature, you will no
3587 longer see the full delegation chain for zones once shortening has been
3590 @node Configuring the GNUnet VPN
3591 @subsection Configuring the GNUnet VPN
3594 * IPv4 address for interface::
3595 * IPv6 address for interface::
3596 * Configuring the GNUnet VPN DNS::
3597 * Configuring the GNUnet VPN Exit Service::
3598 * IP Address of external DNS resolver::
3599 * IPv4 address for Exit interface::
3600 * IPv6 address for Exit interface::
3603 Before configuring the GNUnet VPN, please make sure that system-wide DNS
3604 interception is configured properly as described in the section on the
3605 GNUnet DNS setup. @pxref{Configuring the GNU Name System},
3606 if you haven't done so already.
3608 The default options for the GNUnet VPN are usually sufficient to use
3609 GNUnet as a Layer 2 for your Internet connection.
3610 However, what you always have to specify is which IP protocol you want
3611 to tunnel: IPv4, IPv6 or both.
3612 Furthermore, if you tunnel both, you most likely should also tunnel
3613 all of your DNS requests.
3614 You theoretically can tunnel "only" your DNS traffic, but that usually
3617 The other options as shown on the gnunet-setup tool are:
3619 @node IPv4 address for interface
3620 @subsubsection IPv4 address for interface
3622 This is the IPv4 address the VPN interface will get. You should pick an
3623 'private' IPv4 network that is not yet in use for you system. For example,
3624 if you use @code{10.0.0.1/255.255.0.0} already, you might use
3625 @code{10.1.0.1/255.255.0.0}.
3626 If you use @code{10.0.0.1/255.0.0.0} already, then you might use
3627 @code{192.168.0.1/255.255.0.0}.
3628 If your system is not in a private IP-network, using any of the above will
3630 You should try to make the mask of the address big enough
3631 (@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more
3632 mappings of remote IP Addresses into this range.
3633 However, even a @code{255.255.255.0} mask will suffice for most users.
3635 @node IPv6 address for interface
3636 @subsubsection IPv6 address for interface
3638 The IPv6 address the VPN interface will get. Here you can specify any
3639 non-link-local address (the address should not begin with @code{fe80:}).
3640 A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are
3641 currently not using would be a good choice.
3643 @node Configuring the GNUnet VPN DNS
3644 @subsubsection Configuring the GNUnet VPN DNS
3646 To resolve names for remote nodes, activate the DNS exit option.
3648 @node Configuring the GNUnet VPN Exit Service
3649 @subsubsection Configuring the GNUnet VPN Exit Service
3651 If you want to allow other users to share your Internet connection (yes,
3652 this may be dangerous, just as running a Tor exit node) or want to
3653 provide access to services on your host (this should be less dangerous,
3654 as long as those services are secure), you have to enable the GNUnet exit
3657 You then get to specify which exit functions you want to provide. By
3658 enabling the exit daemon, you will always automatically provide exit
3659 functions for manually configured local services (this component of the
3661 development and not documented further at this time). As for those
3662 services you explicitly specify the target IP address and port, there is
3663 no significant security risk in doing so.
3665 Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet.
3666 Being a DNS exit is usually pretty harmless. However, enabling IPv4 or
3667 IPv6-exit without further precautions may enable adversaries to access
3668 your local network, send spam, attack other systems from your Internet
3669 connection and to other mischief that will appear to come from your
3670 machine. This may or may not get you into legal trouble.
3671 If you want to allow IPv4 or IPv6-exit functionality, you should strongly
3672 consider adding additional firewall rules manually to protect your local
3673 network and to restrict outgoing TCP traffic (i.e. by not allowing access
3674 to port 25). While we plan to improve exit-filtering in the future,
3675 you're currently on your own here.
3676 Essentially, be prepared for any kind of IP-traffic to exit the respective
3677 TUN interface (and GNUnet will enable IP-forwarding and NAT for the
3678 interface automatically).
3680 Additional configuration options of the exit as shown by the gnunet-setup
3683 @node IP Address of external DNS resolver
3684 @subsubsection IP Address of external DNS resolver
3686 If DNS traffic is to exit your machine, it will be send to this DNS
3687 resolver. You can specify an IPv4 or IPv6 address.
3689 @node IPv4 address for Exit interface
3690 @subsubsection IPv4 address for Exit interface
3692 This is the IPv4 address the Interface will get. Make the mask of the
3693 address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more
3694 mappings of IP addresses into this range. As for the VPN interface, any
3695 unused, private IPv4 address range will do.
3697 @node IPv6 address for Exit interface
3698 @subsubsection IPv6 address for Exit interface
3700 The public IPv6 address the interface will get. If your kernel is not a
3701 very recent kernel and you are willing to manually enable IPv6-NAT, the
3702 IPv6 address you specify here must be a globally routed IPv6 address of
3705 Suppose your host has the address @code{2001:4ca0::1234/64}, then
3706 using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits,
3707 then change at least one bit in the range before the bitmask, in the
3708 example above we changed bit 111 from 0 to 1).
3710 You may also have to configure your router to route traffic for the entire
3711 subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this
3712 should be automatic with IPv6, but obviously anything can be
3715 @node Bandwidth Configuration
3716 @subsection Bandwidth Configuration
3718 You can specify how many bandwidth GNUnet is allowed to use to receive
3719 and send data. This is important for users with limited bandwidth or
3722 @node Configuring NAT
3723 @subsection Configuring NAT
3725 Most hosts today do not have a normal global IP address but instead are
3726 behind a router performing Network Address Translation (NAT) which assigns
3727 each host in the local network a private IP address.
3728 As a result, these machines cannot trivially receive inbound connections
3729 from the Internet. GNUnet supports NAT traversal to enable these machines
3730 to receive incoming connections from other peers despite their
3733 In an ideal world, you can press the "Attempt automatic configuration"
3734 button in gnunet-setup to automatically configure your peer correctly.
3735 Alternatively, your distribution might have already triggered this
3736 automatic configuration during the installation process.
3737 However, automatic configuration can fail to determine the optimal
3738 settings, resulting in your peer either not receiving as many connections
3739 as possible, or in the worst case it not connecting to the network at all.
3741 To manually configure the peer, you need to know a few things about your
3742 network setup. First, determine if you are behind a NAT in the first
3744 This is always the case if your IP address starts with "10.*" or
3745 "192.168.*". Next, if you have control over your NAT router, you may
3746 choose to manually configure it to allow GNUnet traffic to your host.
3747 If you have configured your NAT to forward traffic on ports 2086 (and
3748 possibly 1080) to your host, you can check the "NAT ports have been opened
3749 manually" option, which corresponds to the "PUNCHED_NAT" option in the
3750 configuration file. If you did not punch your NAT box, it may still be
3751 configured to support UPnP, which allows GNUnet to automatically
3752 configure it. In that case, you need to install the "upnpc" command,
3753 enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal
3754 via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the
3755 configuration file).
3757 Some NAT boxes can be traversed using the autonomous NAT traversal method.
3758 This requires certain GNUnet components to be installed with "SUID"
3759 prividledges on your system (so if you're installing on a system you do
3760 not have administrative rights to, this will not work).
3761 If you installed as 'root', you can enable autonomous NAT traversal by
3762 checking the "Enable NAT traversal using ICMP method".
3763 The ICMP method requires a way to determine your NAT's external (global)
3764 IP address. This can be done using either UPnP, DynDNS, or by manual
3765 configuration. If you have a DynDNS name or know your external IP address,
3766 you should enter that name under "External (public) IPv4 address" (which
3767 corresponds to the "EXTERNAL_ADDRESS" option in the configuration file).
3768 If you leave the option empty, GNUnet will try to determine your external
3769 IP address automatically (which may fail, in which case autonomous
3770 NAT traversal will then not work).
3772 Finally, if you yourself are not behind NAT but want to be able to
3773 connect to NATed peers using autonomous NAT traversal, you need to check
3774 the "Enable connecting to NATed peers using ICMP method" box.
3777 @node Peer configuration for distributions
3778 @subsection Peer configuration for distributions
3780 The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be
3781 manually set to "/var/lib/gnunet/data/" as the default
3782 "~/.local/share/gnunet/" is probably not that appropriate in this case.
3783 Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to
3784 "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a
3785 distribution decide to override system defaults, all of these changes
3786 should be done in a custom @file{/etc/gnunet.conf} and not in the files
3787 in the @file{config.d/} directory.
3789 Given the proposed access permissions, the "gnunet-setup" tool must be
3790 run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it
3791 modifies the system configuration). As always, gnunet-setup should be run
3792 after the GNUnet peer was stopped using "gnunet-arm -e". Distributions
3793 might want to include a wrapper for gnunet-setup that allows the
3794 desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account
3795 and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
3798 @node How to start and stop a GNUnet peer
3799 @section How to start and stop a GNUnet peer
3801 This section describes how to start a GNUnet peer. It assumes that you
3802 have already compiled and installed GNUnet and its' dependencies.
3803 Before you start a GNUnet peer, you may want to create a configuration
3804 file using gnunet-setup (but you do not have to).
3805 Sane defaults should exist in your
3806 @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice
3807 you could simply start without any configuration. If you want to
3808 configure your peer later, you need to stop it before invoking the
3809 @code{gnunet-setup} tool to customize further and to test your
3810 configuration (@code{gnunet-setup} has build-in test functions).
3812 The most important option you might have to still set by hand is in
3813 [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where
3814 GNUnet should store its data.
3815 It defaults to @code{$HOME/}, which again should work for most users.
3816 Make sure that the directory specified as GNUNET_HOME is writable to
3817 the user that you will use to run GNUnet (note that you can run frontends
3818 using other users, GNUNET_HOME must only be accessible to the user used to
3819 run the background processes).
3821 You will also need to make one central decision: should all of GNUnet be
3822 run under your normal UID, or do you want distinguish between system-wide
3823 (user-independent) GNUnet services and personal GNUnet services. The
3824 multi-user setup is slightly more complicated, but also more secure and
3825 generally recommended.
3828 * The Single-User Setup::
3829 * The Multi-User Setup::
3830 * Killing GNUnet services::
3831 * Access Control for GNUnet::
3834 @node The Single-User Setup
3835 @subsection The Single-User Setup
3837 For the single-user setup, you do not need to do anything special and can
3838 just start the GNUnet background processes using @code{gnunet-arm}.
3839 By default, GNUnet looks in @file{~/.config/gnunet.conf} for a
3840 configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@
3841 @code{$XDG_CONFIG_HOME} is defined). If your configuration lives
3842 elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet
3845 Assuming the configuration file is called @file{~/.config/gnunet.conf},
3846 you start your peer using the @code{gnunet-arm} command (say as user
3847 @code{gnunet}) using:
3850 gnunet-arm -c ~/.config/gnunet.conf -s
3854 The "-s" option here is for "start". The command should return almost
3855 instantly. If you want to stop GNUnet, you can use:
3858 gnunet-arm -c ~/.config/gnunet.conf -e
3862 The "-e" option here is for "end".
3864 Note that this will only start the basic peer, no actual applications
3866 If you want to start the file-sharing service, use (after starting
3870 gnunet-arm -c ~/.config/gnunet.conf -i fs
3874 The "-i fs" option here is for "initialize" the "fs" (file-sharing)
3875 application. You can also selectively kill only file-sharing support using
3878 gnunet-arm -c ~/.config/gnunet.conf -k fs
3882 Assuming that you want certain services (like file-sharing) to be always
3883 automatically started whenever you start GNUnet, you can activate them by
3884 setting "FORCESTART=YES" in the respective section of the configuration
3885 file (for example, "[fs]"). Then GNUnet with file-sharing support would
3886 be started whenever you@ enter:
3889 gnunet-arm -c ~/.config/gnunet.conf -s
3893 Alternatively, you can combine the two options:
3896 gnunet-arm -c ~/.config/gnunet.conf -s -i fs
3900 Using @code{gnunet-arm} is also the preferred method for initializing
3901 GNUnet from @code{init}.
3903 Finally, you should edit your @code{crontab} (using the @code{crontab}
3904 command) and insert a line@
3907 @@reboot gnunet-arm -c ~/.config/gnunet.conf -s
3910 to automatically start your peer whenever your system boots.
3912 @node The Multi-User Setup
3913 @subsection The Multi-User Setup
3915 This requires you to create a user @code{gnunet} and an additional group
3916 @code{gnunetdns}, prior to running @code{make install} during
3918 Then, you create a configuration file @file{/etc/gnunet.conf} which should
3928 Then, perform the same steps to run GNUnet as in the per-user
3929 configuration, except as user @code{gnunet} (including the
3930 @code{crontab} installation).
3931 You may also want to run @code{gnunet-setup} to configure your peer
3933 Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you
3934 run @code{gnunet-setup} as user @code{gnunet}, you might need to change
3935 permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can
3936 write to the file (during setup).
3938 Afterwards, you need to perform another setup step for each normal user
3939 account from which you want to access GNUnet. First, grant the normal user
3940 (@code{$USER}) permission to the group gnunet:
3943 # adduser $USER gnunet
3947 Then, create a configuration file in @file{~/.config/gnunet.conf} for the
3948 $USER with the lines:
3957 This will ensure that @code{gnunet-arm} when started by the normal user
3958 will only run services that are per-user, and otherwise rely on the
3959 system-wide services.
3960 Note that the normal user may run gnunet-setup, but the
3961 configuration would be ineffective as the system-wide services will use
3962 @file{/etc/gnunet.conf} and ignore options set by individual users.
3964 Again, each user should then start the peer using
3965 @file{gnunet-arm -s} --- and strongly consider adding logic to start
3966 the peer automatically to their crontab.
3968 Afterwards, you should see two (or more, if you have more than one USER)
3969 @code{gnunet-service-arm} processes running in your system.
3971 @node Killing GNUnet services
3972 @subsection Killing GNUnet services
3974 It is not necessary to stop GNUnet services explicitly when shutting
3977 It should be noted that manually killing "most" of the
3978 @code{gnunet-service} processes is generally not a successful method for
3979 stopping a peer (since @code{gnunet-service-arm} will instantly restart
3980 them). The best way to explicitly stop a peer is using
3981 @code{gnunet-arm -e}; note that the per-user services may need to be
3982 terminated before the system-wide services will terminate normally.
3984 @node Access Control for GNUnet
3985 @subsection Access Control for GNUnet
3987 This chapter documents how we plan to make access control work within the
3988 GNUnet system for a typical peer. It should be read as a best-practice
3989 installation guide for advanced users and builders of binary
3990 distributions. The recommendations in this guide apply to POSIX-systems
3991 with full support for UNIX domain sockets only.
3993 Note that this is an advanced topic. The discussion presumes a very good
3994 understanding of users, groups and file permissions. Normal users on
3995 hosts with just a single user can just install GNUnet under their own
3996 account (and possibly allow the installer to use SUDO to grant additional
3997 permissions for special GNUnet tools that need additional rights).
3998 The discussion below largely applies to installations where multiple users
3999 share a system and to installations where the best possible security is
4002 A typical GNUnet system consists of components that fall into four
4007 @item User interfaces
4008 User interfaces are not security sensitive and are supposed to be run and
4009 used by normal system users.
4010 The GTK GUIs and most command-line programs fall into this category.
4011 Some command-line tools (like gnunet-transport) should be excluded as they
4012 offer low-level access that normal users should not need.
4013 @item System services and support tools
4014 System services should always run and offer services that can then be
4015 accessed by the normal users.
4016 System services do not require special permissions, but as they are not
4017 specific to a particular user, they probably should not run as a
4018 particular user. Also, there should typically only be one GNUnet peer per
4019 host. System services include the gnunet-service and gnunet-daemon
4020 programs; support tools include command-line programs such as gnunet-arm.
4021 @item Priviledged helpers
4022 Some GNUnet components require root rights to open raw sockets or perform
4023 other special operations. These gnunet-helper binaries are typically
4024 installed SUID and run from services or daemons.
4025 @item Critical services
4026 Some GNUnet services (such as the DNS service) can manipulate the service
4027 in deep and possibly highly security sensitive ways. For example, the DNS
4028 service can be used to intercept and alter any DNS query originating from
4029 the local machine. Access to the APIs of these critical services and their
4030 priviledged helpers must be tightly controlled.
4033 @c FIXME: The titles of these chapters are too long in the index.
4036 * Recommendation - Disable access to services via TCP::
4037 * Recommendation - Run most services as system user "gnunet"::
4038 * Recommendation - Control access to services using group "gnunet"::
4039 * Recommendation - Limit access to certain SUID binaries by group "gnunet"::
4040 * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"::
4041 * Differences between "make install" and these recommendations::
4044 @node Recommendation - Disable access to services via TCP
4045 @subsubsection Recommendation - Disable access to services via TCP
4047 GNUnet services allow two types of access: via TCP socket or via UNIX
4049 If the service is available via TCP, access control can only be
4050 implemented by restricting connections to a particular range of IP
4052 This is acceptable for non-critical services that are supposed to be
4053 available to all users on the local system or local network.
4054 However, as TCP is generally less efficient and it is rarely the case
4055 that a single GNUnet peer is supposed to serve an entire local network,
4056 the default configuration should disable TCP access to all GNUnet
4057 services on systems with support for UNIX domain sockets.
4058 As of GNUnet 0.9.2, configuration files with TCP access disabled should be
4059 generated by default. Users can re-enable TCP access to particular
4060 services simply by specifying a non-zero port number in the section of
4061 the respective service.
4064 @node Recommendation - Run most services as system user "gnunet"
4065 @subsubsection Recommendation - Run most services as system user "gnunet"
4067 GNUnet's main services should be run as a separate user "gnunet" in a
4068 special group "gnunet".
4069 The user "gnunet" should start the peer using "gnunet-arm -s" during
4070 system startup. The home directory for this user should be
4071 @file{/var/lib/gnunet} and the configuration file should be
4072 @file{/etc/gnunet.conf}.
4073 Only the @code{gnunet} user should have the right to access
4074 @file{/var/lib/gnunet} (@emph{mode: 700}).
4076 @node Recommendation - Control access to services using group "gnunet"
4077 @subsubsection Recommendation - Control access to services using group "gnunet"
4079 Users that should be allowed to use the GNUnet peer should be added to the
4080 group "gnunet". Using GNUnet's access control mechanism for UNIX domain
4081 sockets, those services that are considered useful to ordinary users
4082 should be made available by setting "UNIX_MATCH_GID=YES" for those
4084 Again, as shipped, GNUnet provides reasonable defaults.
4085 Permissions to access the transport and core subsystems might additionally
4086 be granted without necessarily causing security concerns.
4087 Some services, such as DNS, must NOT be made accessible to the "gnunet"
4088 group (and should thus only be accessible to the "gnunet" user and
4089 services running with this UID).
4091 @node Recommendation - Limit access to certain SUID binaries by group "gnunet"
4092 @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet"
4094 Most of GNUnet's SUID binaries should be safe even if executed by normal
4095 users. However, it is possible to reduce the risk a little bit more by
4096 making these binaries owned by the group "gnunet" and restricting their
4097 execution to user of the group "gnunet" as well (4750).
4099 @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
4100 @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
4102 A special group "gnunetdns" should be created for controlling access to
4103 the "gnunet-helper-dns".
4104 The binary should then be owned by root and be in group "gnunetdns" and
4105 be installed SUID and only be group-executable (2750).
4106 @b{Note that the group "gnunetdns" should have no users in it at all,
4108 The "gnunet-service-dns" program should be executed by user "gnunet" (via
4109 gnunet-service-arm) with the binary owned by the user "root" and the group
4110 "gnunetdns" and be SGID (2700). This way, @strong{only}
4111 "gnunet-service-dns" can change its group to "gnunetdns" and execute the
4112 helper, and the helper can then run as root (as per SUID).
4113 Access to the API offered by "gnunet-service-dns" is in turn restricted
4114 to the user "gnunet" (not the group!), which means that only
4115 "benign" services can manipulate DNS queries using "gnunet-service-dns".
4117 @node Differences between "make install" and these recommendations
4118 @subsubsection Differences between "make install" and these recommendations
4120 The current build system does not set all permissions automatically based
4121 on the recommendations above. In particular, it does not use the group
4122 "gnunet" at all (so setting gnunet-helpers other than the
4123 gnunet-helper-dns to be owned by group "gnunet" must be done manually).
4124 Furthermore, 'make install' will silently fail to set the DNS binaries to
4125 be owned by group "gnunetdns" unless that group already exists (!).
4126 An alternative name for the "gnunetdns" group can be specified using the
4127 @code{--with-gnunetdns=GRPNAME} configure option.