1 @node GNUnet Installation Handbook
2 @chapter GNUnet Installation Handbook
4 This handbook describes how to install (build setup, compilation) and
5 setup (configuration, start) GNUnet 0.10.x. After following these
6 instructions you should be able to install and then start user-interfaces
7 to interact with the network.
9 This manual is far from complete, and we welcome informed contributions,
10 be 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 Microsoft Windows Platforms::
18 * Build instructions for Debian 7.5::
19 * Installing GNUnet from Git on Ubuntu 14.4::
20 * Build instructions for Debian 8::
21 * Outdated build instructions for previous revisions::
23 * The graphical configuration interface::
24 * How to start and stop a GNUnet peer::
31 This section lists the various known dependencies for
32 GNUnet @value{EDITION}.
33 Suggestions for missing dependencies or wrong version numbers are welcome.
36 * External dependencies::
37 * Fixing libgnurl build issues::
38 * Optional dependencies::
39 * Internal dependencies::
42 @node External dependencies
43 @subsection External dependencies
46 These packages must be installed before a typical GNUnet installation
55 @item gst-plugins-base
57 @item python (only 2.7 supported)@footnote{tests and gnunet-qr}
67 @item GNU libmicrohttpd @geq{} 0.9.30 @footnote{We recommend to build it
68 with a GnuTLS version that was configured with libunbound}
69 @item GNU libextractor @geq{} 1.0
70 @item GNU libtool @geq{} 2.2
71 @item GNU libunistring @geq{} 0.9.1.1
72 @item GNU libidn @geq{} 1.0.0
73 @item @uref{https://gnupg.org/software/libgcrypt/, GNU libgcrypt} @geq{}
74 @uref{https://gnupg.org/ftp/gcrypt/libgcrypt/, 1.6.0}
75 @item @uref{https://gnutls.org/, GnuTLS} @geq{} 3.2.7
76 @footnote{We recommend to compile with libunbound for DANE support;
77 GnuTLS also requires GNU nettle 2.7 (update: GnuTLS 3.2.7 appears NOT
78 to work against GNU nettle > 2.7, due to some API updatings done by
79 nettle. Thus it should be compiled against nettle 2.7
80 and, in case you get some error on the reference to `rpl_strerror' being
81 undefined, follow the instructions on
82 @uref{http://lists.gnupg.org/pipermail/gnutls-devel/2013-November/00
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 Fixing libgnurl build issues
101 @subsection Fixing libgnurl build issues
103 If you have to compile libgnurl from source since the version included in
104 your distribution is to old you perhaps get an error message while
105 running the @file{configure} script:
110 checking for 64-bit curl_off_t data type... unknown
111 checking for 32-bit curl_off_t data type... unknown
112 checking for 16-bit curl_off_t data type... unknown
113 configure: error: cannot find data type for curl_off_t.
119 Before running the configure script, set:
122 CFLAGS="-I. -I$BUILD_ROOT/include"
125 @node Optional dependencies
126 @subsection Optional dependencies
128 These applications must be installed for various experimental or otherwise
129 optional features such as @code{gnunet-conversation}, @code{gnunet-gtk}.
132 @item libpulse 2.0 or higher, optional (for gnunet-conversation)
133 @item libopus 1.0.1 or higher, optional (for gnunet-conversation)
134 @item libogg 1.3.0 or higher, optional (for gnunet-conversation)
135 @item certool (binary) optional @footnote{for convenient installation of
136 the GNS proxy (available as part of Debian's libnss3-tools)}
137 @item python-zbar 0.10 or higher, optional (for gnunet-qr)
138 @item Gtk+ 3.0 or higher, optional (for gnunet-gtk)
139 @item libgladeui must match Gtk+ version, optional (for gnunet-gtk)
140 @item libqrencode 3.0 or higher, optional (for gnunet-namestore-gtk)
143 @node Internal dependencies
144 @subsection Internal dependencies
146 This section tries to give an overview of what processes a typical GNUnet
147 peer running a particular application would consist of. All of the
148 processes listed here should be automatically started by
149 @code{gnunet-arm -s}.
150 The list is given as a rough first guide to users for failure diagnostics.
151 Ideally, end-users should never have to worry about these internal
153 In terms of internal dependencies, a minimum file-sharing system consists
154 of the following GNUnet processes (in order of dependency):
157 @item gnunet-service-arm
158 @item gnunet-service-resolver (required by all)
159 @item gnunet-service-statistics (required by all)
160 @item gnunet-service-peerinfo
161 @item gnunet-service-transport (requires peerinfo)
162 @item gnunet-service-core (requires transport)
163 @item gnunet-daemon-hostlist (requires core)
164 @item gnunet-daemon-topology (requires hostlist, peerinfo)
165 @item gnunet-service-datastore
166 @item gnunet-service-dht (requires core)
167 @item gnunet-service-identity
168 @item gnunet-service-fs (requires identity, mesh, dht, datastore, core)
172 A minimum VPN system consists of the following GNUnet processes (in
173 order of dependency):
176 @item gnunet-service-arm
177 @item gnunet-service-resolver (required by all)
178 @item gnunet-service-statistics (required by all)
179 @item gnunet-service-peerinfo
180 @item gnunet-service-transport (requires peerinfo)
181 @item gnunet-service-core (requires transport)
182 @item gnunet-daemon-hostlist (requires core)
183 @item gnunet-service-dht (requires core)
184 @item gnunet-service-mesh (requires dht, core)
185 @item gnunet-service-dns (requires dht)
186 @item gnunet-service-regex (requires dht)
187 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
191 A minimum GNS system consists of the following GNUnet processes (in
192 order of dependency):
195 @item gnunet-service-arm
196 @item gnunet-service-resolver (required by all)
197 @item gnunet-service-statistics (required by all)
198 @item gnunet-service-peerinfo
199 @item gnunet-service-transport (requires peerinfo)
200 @item gnunet-service-core (requires transport)
201 @item gnunet-daemon-hostlist (requires core)
202 @item gnunet-service-dht (requires core)
203 @item gnunet-service-mesh (requires dht, core)
204 @item gnunet-service-dns (requires dht)
205 @item gnunet-service-regex (requires dht)
206 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
207 @item gnunet-service-identity
208 @item gnunet-service-namestore (requires identity)
209 @item gnunet-service-gns (requires vpn, dns, dht, namestore, identity)
212 @node Pre-installation notes
213 @section Pre-installation notes
215 Please note that in the code instructions for the installation,
216 @emph{#} indicates commands run as privileged root user and
217 @emph{$} shows commands run as unprivileged ("normal") system user.
220 @node Generic installation instructions
221 @section Generic installation instructions
223 First, in addition to the GNUnet sources you might require downloading the
224 latest version of various dependencies, depending on how recent the
225 software versions in your distribution of GNU/Linux are.
226 Most distributions do not include sufficiently recent versions of these
228 Thus, a typically installation on a "modern" GNU/Linux distribution
229 requires you to install the following dependencies (ideally in this
233 @item libgpgerror and libgcrypt
234 @item libnettle and libunbound (possibly from distribution), GnuTLS
235 @item libgnurl (read the README)
236 @item GNU libmicrohttpd
237 @item GNU libextractor
240 Make sure to first install the various mandatory and optional
241 dependencies including development headers from your distribution.
243 Other dependencies that you should strongly consider to install is a
244 database (MySQL, sqlite or Postgres).
245 The following instructions will assume that you installed at least sqlite.
246 For most distributions you should be able to find pre-build packages for
247 the database. Again, make sure to install the client libraries and the
248 respective development headers (if they are packaged separately) as well.
250 You can find specific, detailed instructions for installing of the
251 dependencies (and possibly the rest of the GNUnet installation) in the
252 platform-specific descriptions, which can be found in the Index.
253 Please consult them now.
254 If your distribution is not listed, please study the instructions for
255 Debian stable carefully as you try to install the dependencies for your
257 Contributing additional instructions for further platforms is always
259 Please take in mind that operating system development tends to move at
260 a rather fast speed. Due to this you should be aware that some of
261 the instructionss could be outdated by the time you are reading this.
262 If you find a mistake, please tell us about it (or even better: send
263 a patch to the documentation to fix it!).
265 Before proceeding further, please double-check the dependency list.
266 Note that in addition to satisfying the dependencies, you might have to
267 make sure that development headers for the various libraries are also
269 There maybe files for other distributions, or you might be able to find
270 equivalent packages for your distribution.
272 While it is possible to build and install GNUnet without having root
273 access, we will assume that you have full control over your system in
275 First, you should create a system user @emph{gnunet} and an additional
276 group @emph{gnunetdns}. On Debian and Ubuntu GNU/Linux, type:
279 # adduser --system --home /var/lib/gnunet --group \
280 --disabled-password gnunet
281 # addgroup --system gnunetdns
285 On other Unixes, this should have the same effect:
288 # useradd --system --groups gnunet --home-dir /var/lib/gnunet
289 # addgroup --system gnunetdns
292 Now compile and install GNUnet using:
295 $ tar xvf gnunet-0.10.?.tar.gz
297 $ ./configure --with-sudo=sudo --with-nssdir=/lib
302 If you want to be able to enable DEBUG-level log messages, add
303 @code{--enable-logging=verbose} to the end of the
304 @code{./configure} command.
305 DEBUG-level log messages are in English-only and should only be useful for
306 developers (or for filing really detailed bug reports).
308 Finally, you probably want to compile @code{gnunet-gtk}, which
309 includes gnunet-setup (graphical tool for configuration)
310 and @code{gnunet-fs-gtk} (graphical tool for file-sharing):
313 $ tar xvf gnunet-gtk-0.10.?.tar.gz
314 $ cd gnunet-gtk-0.10.?
315 $ ./configure --with-gnunet=/usr/local/
319 $ sudo ldconfig # just to be safe
323 Next, edit the file @file{/etc/gnunet.conf} to contain the following:
332 You may need to update your ld.so cache to include files installed in
333 @file{/usr/local/lib}:
340 Then, switch from user root to user gnunet to start the peer:
343 # su -s /bin/sh - gnunet
344 $ gnunet-arm -c /etc/gnunet.conf -s
347 You may also want to add the last line in the gnunet users @file{crontab}
348 prefixed with @code{@@reboot} so that it is executed whenever the system
352 @@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s@
356 This will only start the system-wide GNUnet services.
357 Type exit to get back your root shell.
358 Now, you need to configure the per-user part. For each
359 $USER on the system, run:
362 # adduser $USER gnunet
366 to allow them to access the system-wide GNUnet services. Then, each
367 user should create a configuration file @file{~/.config/gnunet.conf}
374 DEFAULTSERVICES = gns
378 and start the per-user services using
381 $ gnunet-arm -c ~/.config/gnunet.conf -s
385 Again, adding a @code{crontab} entry to autostart the peer is advised:
388 @@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s
392 Note that some GNUnet services (such as SOCKS5 proxies) may need a
393 system-wide TCP port for each user.
394 For those services, systems with more than one user may require each user
395 to specify a different port number in their personal configuration file.
397 Finally, the user should perform the basic initial setup for the GNU Name
398 System. This is done by running two commands:
401 $ gnunet-gns-import.sh
402 $ gnunet-gns-proxy-setup-ca
406 The first generates the default zones, wheras the second setups the GNS
407 Certificate Authority with the user's browser. Now, to actiave GNS in the
408 normal DNS resolution process, you need to edit your
409 @file{/etc/nsswitch.conf} where you should find a line like this:
412 hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
416 The exact details may differ a bit, which is fine. Add the text
417 @emph{"gns [NOTFOUND=return]"} after @emph{"files"}:
420 hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
424 You might want to make sure that @file{/lib/libnss_gns.so.2} exists on
425 your system, it should have been created during the installation.
429 @node Build instructions for Ubuntu 12.04 using Git
430 @section Build instructions for Ubuntu 12.04 using Git
434 * Install the required build tools::
435 * Install libgcrypt 1.6 and libgpg-error::
436 * Install gnutls with DANE support::
438 * Install libmicrohttpd from Git::
439 * Install libextractor from Git::
440 * Install GNUnet dependencies::
442 * Install the GNUnet-gtk user interface from Git::
445 @node Install the required build tools
446 @subsection Install the required build tools
448 First, make sure Git is installed on your system:
451 $ sudo apt-get install git
454 Install the essential buildtools:
457 $ sudo apt-get install automake autopoint autoconf libtool
460 @node Install libgcrypt 1.6 and libgpg-error
461 @subsection Install libgcrypt 1.6 and libgpg-error
464 $ wget ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
465 $ tar xf libgpg-error-1.12.tar.bz2
466 $ cd libgpg-error-1.12
468 $ sudo make install ; cd ..
471 @node Install gnutls with DANE support
472 @subsection Install gnutls with DANE support
475 $ wget http://www.lysator.liu.se/~nisse/archive/nettle-2.7.1.tar.gz
476 $ tar xf nettle-2.7.1.tar.gz
479 $ sudo make install ; cd ..
483 $ wget https://www.nlnetlabs.nl/downloads/ldns/ldns-1.6.16.tar.gz
484 $ tar xf ldns-1.6.16.tar.gz
487 $ sudo make install ; cd ..
491 $ wget https://unbound.net/downloads/unbound-1.4.21.tar.gz
492 $ tar xf unbound-1.4.21.tar.gz
495 $ sudo make install ; cd ..
499 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.1/gnutls-3.1.17.tar.xz
500 $ tar xf gnutls-3.1.17.tar.xz
503 $ sudo make install ; cd ..
507 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
508 $ tar xf libgcrypt-1.6.0.tar.bz2
511 $ sudo make install ; cd ..
514 @node Install libgnurl
515 @subsection Install libgnurl
518 $ wget https://gnunet.org/sites/default/files/gnurl-7.34.0.tar.bz2
519 $ tar xf gnurl-7.34.0.tar.bz2
521 $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
522 --without-libmetalink --without-winidn --without-librtmp \
523 --without-nghttp2 --without-nss --without-cyassl \
524 --without-polarssl --without-ssl --without-winssl \
525 --without-darwinssl --disable-sspi --disable-ntlm-wb \
526 --disable-ldap --disable-rtsp --disable-dict --disable-telnet \
527 --disable-tftp --disable-pop3 --disable-imap --disable-smtp \
528 --disable-gopher --disable-file --disable-ftp
529 $ sudo make install ; cd ..
532 @node Install libmicrohttpd from Git
533 @subsection Install libmicrohttpd from Git
536 $ git clone https://gnunet.org/git/libmicrohttpd
540 $ sudo make install ; cd ..
543 @node Install libextractor from Git
544 @subsection Install libextractor from Git
546 Install libextractor dependencies:
549 $ sudo apt-get install zlib1g-dev libgsf-1-dev libmpeg2-4-dev \
550 libpoppler-dev libvorbis-dev libexiv2-dev libjpeg-dev \
551 libtiff-dev libgif-dev libvorbis-dev libflac-dev libsmf-dev \
558 $ git clone https://gnunet.org/git/libextractor
562 $ sudo make install ; cd ..
565 @node Install GNUnet dependencies
566 @subsection Install GNUnet dependencies
569 $ sudo apt-get install libidn11-dev libunistring-dev libglpk-dev \
570 libpulse-dev libbluetooth-dev libsqlite-dev
576 $ wget http://downloads.xiph.org/releases/opus/opus-1.1.tar.gz
577 $ tar xf opus-1.1.tar.gz
580 $ sudo make install ; cd ..
583 Choose one or more database backends:
587 $ sudo apt-get install libsqlite3-dev
591 $ sudo apt-get install libmysqlclient-dev
595 $ sudo apt-get install libpq-dev postgresql
601 @subsection Build GNUnet
606 * Configuring the installation path::
607 * Configuring the system::
608 * Installing components requiring sudo permission::
612 @node Configuring the installation path
613 @subsubsection Configuring the installation path
615 You can specify the location of the GNUnet installation by setting the
616 prefix when calling the configure script with @code{--prefix=DIRECTORY}
619 $ export PATH=$PATH:DIRECTORY/bin
622 @node Configuring the system
623 @subsubsection Configuring the system
625 Please make sure NOW that you have created a user and group 'gnunet'
626 and additionally a group 'gnunetdns':
629 $ sudo addgroup gnunet
630 $ sudo addgroup gnunetdns
631 $ sudo adduser gnunet
634 Each GNUnet user should be added to the 'gnunet' group (may
635 require fresh login to come into effect):
638 $ sudo useradd -G gnunet
641 @node Installing components requiring sudo permission
642 @subsubsection Installing components requiring sudo permission
644 Some components, like the nss plugin required for GNS, may require root
645 permissions. To allow these few components to be installed use:
648 $ ./configure --with-sudo
655 $ git clone https://gnunet.org/git/gnunet/
660 Use the required configure call including the optional installation prefix
661 PREFIX or the sudo permissions:
664 $ ./configure [ --with-sudo | --with-prefix=PREFIX ]
668 $ make; sudo make install
671 After installing it, you need to create an empty configuration file:
674 mkdir ~/.gnunet; touch ~/.gnunet/gnunet.conf
677 And finally you can start GNUnet with @code{$ gnunet-arm -s}.
679 @node Install the GNUnet-gtk user interface from Git
680 @subsection Install the GNUnet-gtk user interface from Git
686 $ sudo apt-get install libgtk-3-dev libunique-3.0-dev libgladeui-dev \
690 To build GNUnet (with an optional prefix)and execute:
693 $ git clone https://gnunet.org/git/gnunet-gtk/
696 $ ./configure [--prefix=PREFIX] --with-gnunet=DIRECTORY
697 $ make; sudo make install
700 @node Build Instructions for Microsoft Windows Platforms
701 @section Build Instructions for Microsoft Windows Platforms
704 * Introduction to building on MS Windows::
706 * Dependencies & Initial Setup::
707 * GNUnet Installation::
708 * Adjusting Windows for running and testing GNUnet::
709 * Building the GNUnet Installer::
710 * Using GNUnet with Netbeans on Windows::
713 @node Introduction to building on MS Windows
714 @subsection Introduction to building on MS Windows
717 This document is a guide to building GNUnet and its dependencies on
718 Windows platforms. GNUnet development is mostly done under Linux and
719 especially SVN checkouts may not build out of the box.
720 We regret any inconvenience, and if you have problems, please report them.
723 @subsection Requirements
725 The Howto is based upon a @strong{Windows Server 2008 32bit}
726 @strong{Installation}, @strong{sbuild} and thus a
727 @uref{http://www.mingw.org/wiki/MSYS, MSYS+MinGW}
728 (W32-GCC-Compiler-Suite + Unix-like Userland) installation. sbuild
729 is a convenient set of scripts which creates a working msys/mingw
730 installation and installs most dependencies required for GNUnet.
732 As of the point of the creation of this Howto, GNUnet @strong{requires} a
733 Windows @strong{Server} 2003 or newer for full feature support.
734 Windows Vista and later will also work, but
735 @strong{non-server version can not run a VPN-Exit-Node} as the NAT
736 features have been removed as of Windows Vista.
738 @node Dependencies & Initial Setup
739 @subsection Dependencies & Initial Setup
745 Install a fresh version of @strong{Python 2.x}, even if you are using a
746 x64-OS, install a 32-bit version for use with sbuild.
747 Python 3.0 currently is incompatible.
750 Install your favorite @uref{http://code.google.com/p/tortoisegit/, GIT} &
751 @uref{http://tortoisesvn.net/, SVN}-clients.
754 You will also need some archive-manager like
755 @uref{http://www.7-zip.org/, 7zip}.
758 Pull a copy of sbuild to a directory of your choice, which will be used
759 in the remainder of this guide. For now, we will use
760 @file{c:\gnunet\sbuild\}
763 in @file{sbuild\src\mingw\mingw32-buildall.sh}, comment out the packages
764 @strong{gnunet-svn} and @strong{gnunet-gtk-svn}, as we don't want sbuild
765 to compile/install those for us.
768 Follow LRN's sbuild installation instructions.-
771 Please note that sbuild may (or will most likely) fail during
772 installation, thus you really HAVE to @strong{check the logfiles} created
773 during the installation process.
774 Certain packages may fail to build initially due to missing dependencies,
776 @strong{substitute those with binary-versions initially}. Later on once
777 dependencies are satisfied you can re-build the newer package versions.
779 @strong{It is normal that you may have to repeat this step multiple times
780 and there is no uniform way to fix all compile-time issues, as the
781 build-process of many of the dependencies installed are rather unstable
782 on win32 and certain releases may not even compile at all.}
784 Most dependencies for GNUnet have been set up by sbuild, thus we now
785 should add the @file{bin/} directories in your new msys and mingw
786 installations to PATH. You will want to create a backup of your finished
787 msys-environment by now.
789 @node GNUnet Installation
790 @subsection GNUnet Installation
792 First, we need to launch our msys-shell, you can do this via
794 @file{C:\gnunet\sbuild\msys\msys.bat}
796 You might wish to take a look at this file and adjust some
797 login-parameters to your msys environment.
799 Also, sbuild added two pointpoints to your msys-environment, though those
800 might remain invisible:
805 /mingw, which will mount your mingw-directory from sbuild/mingw and the
809 /src which contains all the installation sources sbuild just compiled.
812 Check out the current gnunet-sources (git HEAD) from the
813 gnunet-repository, we will do this in your home directory:
815 @code{git clone https://gnunet.org/git/gnunet/ ~/gnunet}
817 Now, we will first need to bootstrap the checked out installation and then
818 configure it accordingly.
823 STRIP=true CPPFLAGS="-DUSE_IPV6=1 -DW32_VEH" CFLAGS="$CFLAGS -g -O2" \
824 ./configure --prefix=/ --docdir=/share/doc/gnunet \
825 --with-libiconv-prefix=/mingw --with-libintl-prefix=/mingw \
826 --with-libcurl=/mingw --with-extractor=/mingw --with-sqlite=/mingw \
827 --with-microhttpd=/mingw --with-plibc=/mingw --enable-benchmarks \
828 --enable-expensivetests --enable-experimental --with-qrencode=/mingw \
829 --enable-silent-rules --enable-experimental 2>&1 | tee -a ./configure.log
832 The parameters above will configure for a reasonable gnunet installation
833 to the your msys-root directory.
834 Depending on which features your would like to build or you may need to
835 specify additional dependencies. Sbuild installed most libs into
836 the /mingw subdirectory, so remember to prefix library locations with
839 Like on a unixoid system, you might want to use your home directory as
840 prefix for your own gnunet installation for development, without tainting
841 the buildenvironment. Just change the "prefix" parameter to point towards
844 Now it's time to compile gnunet as usual. Though this will take some time,
845 so you may fetch yourself a coffee or some Mate now...
851 @node Adjusting Windows for running and testing GNUnet
852 @subsection Adjusting Windows for running and testing GNUnet
854 Assuming the build succeeded and you
855 @strong{added the bin directory of your gnunet to PATH}, you can now use
856 your gnunet-installation as usual.
857 Remember that UAC or the windows firewall may popup initially, blocking
858 further execution of gnunet until you acknowledge them.
860 You will also have to take the usual steps to get p2p software running
861 properly (port forwarding, ...), and gnunet will require administrative
862 permissions as it may even install a device-driver (in case you are using
863 gnunet-vpn and/or gnunet-exit).
865 @node Building the GNUnet Installer
866 @subsection Building the GNUnet Installer
868 The GNUnet installer is made with
869 @uref{http://nsis.sourceforge.net/, NSIS} The installer script is located
870 in @file{contrib\win} in the GNUnet source tree.
872 @node Using GNUnet with Netbeans on Windows
873 @subsection Using GNUnet with Netbeans on Windows
877 @node Build instructions for Debian 7.5
878 @section Build instructions for Debian 7.5
881 These are the installation instructions for Debian 7.5. They were tested using
882 a minimal, fresh Debian 7.5 AMD64 installation without non-free software
883 (no contrib or non-free). By "minimal", we mean that during installation, we
884 did not select any desktop environment, servers or system utilities during the
885 "tasksel" step. Note that the packages and the dependencies that we will
886 install during this chapter take about 1.5 GB of disk space. Combined with
887 GNUnet and space for objects during compilation, you should not even attempt
888 this unless you have about 2.5 GB free after the minimal Debian installation.
889 Using these instructions to build a VM image is likely to require a minimum of
890 4-5 GB for the VM (as you will likely also want a desktop manager).
892 GNUnet's security model assumes that your @file{/home} directory is encrypted.
893 Thus, if possible, you should encrypt your home partition
894 (or per-user home directory).
896 Naturally, the exact details of the starting state for your installation
897 should not matter much. For example, if you selected any of those installation
898 groups you might simply already have some of the necessary packages installed.
899 We did this for testing, as this way we are less likely to forget to mention a
900 required package. Note that we will not install a desktop environment, but of
901 course you will need to install one to use GNUnet's graphical user interfaces.
902 Thus, it is suggested that you simply install the desktop environment of your
903 choice before beginning with the instructions.
911 * Installing packages::
912 * Installing dependencies from source::
913 * Installing GNUnet from source::
914 * But wait there is more!::
920 After any installation, you should begin by running
923 # apt-get update ; apt-get upgrade
926 to ensure that all of your packages are up-to-date. Note that the "#" is used
927 to indicate that you need to type in this command as "root"
928 (or prefix with "sudo"), whereas "$" is used to indicate typing in a command
932 @subsection Stable? Hah!
934 Yes, we said we start with a Debian 7.5 "stable" system. However, to reduce the
935 amount of compilation by hand, we will begin by allowing the installation of
936 packages from the testing and unstable distributions as well. We will stick to
937 "stable" packages where possible, but some packages will be taken from the
938 other distributions. Start by modifying @file{/etc/apt/sources.list} to contain
939 the following (possibly adjusted to point to your mirror of choice):
941 # These were there before:
942 deb http://ftp.de.debian.org/debian/ wheezy main
943 deb-src http://ftp.de.debian.org/debian/ wheezy main
944 deb http://security.debian.org/ wheezy/updates main
945 deb-src http://security.debian.org/ wheezy/updates main
946 deb http://ftp.de.debian.org/debian/ wheezy-updates main
947 deb-src http://ftp.de.debian.org/debian/ wheezy-updates main
949 # Add these lines (feel free to adjust the mirror):
950 deb http://ftp.de.debian.org/debian/ testing main
951 deb http://ftp.de.debian.org/debian/ unstable main
954 The next step is to create/edit your @file{/etc/apt/preferences} file to look
959 Pin: release a=stable,n=wheezy
963 Pin: release o=Debian,a=testing
967 Pin: release o=Debian,a=unstable
971 You can read more about Apt Preferences here and here. Note that other pinnings
972 are likely to also work for GNUnet, the key thing is that you need some
973 packages from unstable (as shown below). However, as unstable is unlikely to
974 be comprehensive (missing packages) or might be problematic (crashing packages),
975 you probably want others from stable and/or testing.
978 @subsection Update again
987 to ensure that all your new distribution indices are downloaded, and that your
988 pinning is correct: the upgrade step should cause no changes at all.
990 @node Installing packages
991 @subsection Installing packages
993 We begin by installing a few Debian packages from stable:@
996 # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \
997 libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev \
998 texlive libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev \
999 libbz2-dev libexiv2-dev libflac-dev libgif-dev libglib2.0-dev \
1000 libgtk-3-dev libmagic-dev libjpeg8-dev libmpeg2-4-dev libmp4v2-dev \
1001 librpm-dev libsmf-dev libtidy-dev libtiff5-dev libvorbis-dev \
1002 libogg-dev zlib1g-dev g++ gettext libgsf-1-dev libunbound-dev \
1003 libqrencode-dev libgladeui-dev nasm texlive-latex-extra \
1004 libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev
1007 After that, we install a few more packages from unstable:@
1010 # apt-get install -t unstable nettle-dev libgstreamer1.0-dev \
1011 gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
1012 libgstreamer-plugins-base1.0-dev
1015 @node Installing dependencies from source
1016 @subsection Installing dependencies from source
1018 Next, we need to install a few dependencies from source. You might want to do
1019 this as a "normal" user and only run the @code{make install} steps as root
1020 (hence the @code{sudo} in the commands below). Also, you do this from any
1021 directory. We begin by downloading all dependencies, then extracting the
1022 sources, and finally compiling and installing the libraries:@
1025 $ wget https://libav.org/releases/libav-9.10.tar.xz
1026 $ wget http://ftp.gnu.org/gnu/libextractor/libextractor-1.3.tar.gz
1027 $ wget ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
1028 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
1029 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.2/gnutls-3.2.7.tar.xz
1030 $ wget http://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.33.tar.gz
1031 $ wget https://gnunet.org/sites/default/files/gnurl-7.34.0.tar.bz2
1032 $ tar xvf libextractor-1.3.tar.gz
1033 $ tar xvf libgpg-error-1.12.tar.bz2
1034 $ tar xvf libgcrypt-1.6.0.tar.bz2
1035 $ tar xvf gnutls-3.2.7.tar.xz
1036 $ tar xvf libmicrohttpd-0.9.33.tar.gz
1037 $ tar xvf gnurl-7.34.0.tar.bz2
1038 $ cd libav-0.9 ; ./configure --enable-shared;
1039 $ make; sudo make install; cd ..
1040 $ cd libextractor-1.3 ; ./configure;
1041 $ make ; sudo make install; cd ..
1042 $ cd libgpg-error-1.12; ./configure;
1043 $ make ; sudo make install; cd ..
1044 $ cd libgcrypt-1.6.0; ./configure --with-gpg-error-prefix=/usr/local;
1045 $ make ; sudo make install ; cd ..
1046 $ cd gnutls-3.2.7 ; ./configure;
1047 $ make ; sudo make install ; cd ..
1048 $ cd libmicrohttpd-0.9.33; ./configure;
1049 $ make ; sudo make install ; cd ..
1051 $ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \
1052 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \
1053 --without-nss --without-cyassl --without-polarssl --without-ssl \
1054 --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \
1055 --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \
1056 --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \
1058 $ make ; sudo make install; cd ..
1061 @node Installing GNUnet from source
1062 @subsection Installing GNUnet from source
1065 For this, simply follow the generic installation instructions from
1068 @node But wait there is more!
1069 @subsection But wait there is more!
1071 So far, we installed all of the packages and dependencies required to ensure
1072 that all of GNUnet would be built. However, while for example the plugins to
1073 interact with the MySQL or Postgres databases have been created, we did not
1074 actually install or configure those databases. Thus, you will need to install
1075 and configure those databases or stick with the default Sqlite database.
1076 Sqlite is usually fine for most applications, but MySQL can offer better
1077 performance and Postgres better resillience.
1080 @node Installing GNUnet from Git on Ubuntu 14.4
1081 @section Installing GNUnet from Git on Ubuntu 14.4
1083 @strong{Install the required build tools:}
1084 @code{ $ sudo apt-get install git automake autopoint autoconf }
1086 @strong{Install the required dependencies}
1088 $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \
1089 libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \
1090 libmicrohttpd-dev libgnutls28-dev
1093 @strong{Choose one or more database backends}
1097 $ sudo apt-get install libsqlite3-dev
1101 $ sudo apt-get install libmysqlclient-dev
1105 $ sudo apt-get install libpq-dev postgresql
1108 @strong{Install the optional dependencies for gnunet-conversation:}
1111 $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev
1114 @strong{Install the libgrypt 1.6.1:}
1117 $ sudo apt-get install libgcrypt20-dev
1119 For Ubuntu older 14.04:
1121 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2
1122 $ tar xf libgcrypt-1.6.1.tar.bz2
1123 $ cd libgcrypt-1.6.1
1128 @strong{Install libgnurl}
1130 $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2
1131 $ tar xf gnurl-7.35.0.tar.bz2
1133 $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
1134 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \
1135 --without-nss --without-cyassl --without-polarssl --without-ssl \
1136 --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \
1137 --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \
1138 --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \
1144 @strong{Install GNUnet}
1146 $ git clone https://gnunet.org/git/gnunet/
1156 Install to a different directory:@
1160 Have sudo permission, but do not want to compile as root:@
1164 Want debug message enabled:@
1165 -- enable-logging=verbose
1170 $ ./configure [ --with-sudo | --prefix=PREFIX | --- enable-logging=verbose]@
1171 $ make; sudo make install@
1174 After installing it, you need to create an empty configuration file:@
1175 @code{touch ~/.config/gnunet.conf}
1177 And finally you can start GNUnet with@
1178 @code{$ gnunet-arm -s}
1180 @node Build instructions for Debian 8
1181 @section Build instructions for Debian 8
1183 These are the installation instructions for Debian 8. They were tested using a
1184 fresh Debian 8 AMD64 installation without non-free software (no contrib or
1185 non-free). During installation, I only selected "lxde" for the desktop
1186 environment. Note that the packages and the dependencies that we will install
1187 during this chapter take about 1.5 GB of disk space. Combined with GNUnet and
1188 space for objects during compilation, you should not even attempt this unless
1189 you have about 2.5 GB free after the Debian installation. Using these
1190 instructions to build a VM image is likely to require a minimum of 4-5 GB for
1191 the VM (as you will likely also want a desktop manager).
1193 GNUnet's security model assumes that your @code{/home} directory is encrypted.
1194 Thus, if possible, you should encrypt your entire disk, or at least just your
1195 home partition (or per-user home directory).
1197 Naturally, the exact details of the starting state for your installation should
1198 not matter much. For example, if you selected any of those installation groups
1199 you might simply already have some of the necessary packages installed. Thus,
1200 it is suggested that you simply install the desktop environment of your choice
1201 before beginning with the instructions.
1206 * Installing Debian Packages::
1207 * Installing Dependencies from Source2::
1208 * Installing GNUnet from Source2::
1209 * But wait (again) there is more!::
1213 @subsection Update Debian
1215 After any installation, you should begin by running@
1220 to ensure that all of your packages are up-to-date. Note that the "#" is used
1221 to indicate that you need to type in this command as "root" (or prefix with
1222 "sudo"), whereas "$" is used to indicate typing in a command as a normal
1225 @node Installing Debian Packages
1226 @subsection Installing Debian Packages
1228 We begin by installing a few Debian packages from stable:@
1230 # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \
1231 libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \
1232 libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \
1233 libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \
1234 libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext libgsf-1-dev \
1235 libunbound-dev libqrencode-dev libgladeui-dev nasm texlive-latex-extra \
1236 libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev \
1237 gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
1238 libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev libgcrypt20-dev \
1242 @node Installing Dependencies from Source2
1243 @subsection Installing Dependencies from Source2
1245 Yes, we said we start with a Debian 8 "stable" system, but because Debian
1246 linked GnuTLS without support for DANE, we need to compile a few things, in
1247 addition to GNUnet, still by hand. Yes, you can run GNUnet using the respective
1248 Debian packages, but then you will not get DANE support.
1250 Next, we need to install a few dependencies from source. You might want to do
1251 this as a "normal" user and only run the @code{make install} steps as root
1252 (hence the @code{sudo} in the commands below). Also, you do this from any
1253 directory. We begin by downloading all dependencies, then extracting the
1254 sources, and finally compiling and installing the libraries:@
1257 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz@
1258 $ wget https://gnunet.org/sites/default/files/gnurl-7.40.0.tar.bz2@
1259 $ tar xvf gnutls-3.3.12.tar.xz@
1260 $ tar xvf gnurl-7.40.0.tar.bz2@
1261 $ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd ..@
1263 $ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \
1264 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \
1265 --without-nss --without-cyassl --without-polarssl --without-ssl \
1266 --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \
1267 --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \
1268 --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \
1269 --disable-ftp --disable-smb
1270 $ make ; sudo make install; cd ..@
1273 @node Installing GNUnet from Source2
1274 @subsection Installing GNUnet from Source2
1276 For this, simply follow the generic installation instructions from@
1279 @node But wait (again) there is more!
1280 @subsection But wait (again) there is more!
1282 So far, we installed all of the packages and dependencies required to ensure
1283 that all of GNUnet would be built. However, while for example the plugins to
1284 interact with the MySQL or Postgres databases have been created, we did not
1285 actually install or configure those databases. Thus, you will need to install
1286 and configure those databases or stick with the default Sqlite database. Sqlite
1287 is usually fine for most applications, but MySQL can offer better performance
1288 and Postgres better resillience.
1290 @node Outdated build instructions for previous revisions
1291 @section Outdated build instructions for previous revisions
1293 This chapter contains a collection of outdated, older installation guides. They
1294 are mostly intended to serve as a starting point for writing up-to-date
1295 instructions and should not be expected to work for GNUnet 0.10.x.
1296 A set of older installation instructions can also be found in the
1297 @file{doc/outdated-and-old-installation-instructions.txt} in the source
1298 of GNUnet. This file covers old instructions which no longer receive
1299 security updates or any kind of support.
1303 * Installing GNUnet 0.10.1 on Ubuntu 14.04::
1304 * Building GLPK for MinGW::
1305 * GUI build instructions for Ubuntu 12.04 using Subversion::
1306 * Installation with gnunet-update::
1307 * Instructions for Microsoft Windows Platforms (Old)::
1311 @node Installing GNUnet 0.10.1 on Ubuntu 14.04
1312 @subsection Installing GNUnet 0.10.1 on Ubuntu 14.04
1314 Install the required dependencies@
1317 $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \
1318 libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \
1319 libmicrohttpd-dev libgnutls28-dev
1322 Choose one or more database backends@
1325 $ sudo apt-get install libsqlite3-dev@
1329 $ sudo apt-get install libmysqlclient-dev@
1333 $ sudo apt-get install libpq-dev postgresql@
1336 Install the optional dependencies for gnunet-conversation:@
1338 $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev@
1341 Install the libgrypt 1.6:@
1343 @code{$ sudo apt-get install libgcrypt20-dev}@
1344 For Ubuntu older 14.04:@
1345 @code{$ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2@
1346 $ tar xf libgcrypt-1.6.1.tar.bz2@
1347 $ cd libgcrypt-1.6.1@
1349 $ sudo make install@
1354 $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2@
1355 $ tar xf gnurl-7.35.0.tar.bz2@
1357 $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
1358 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \
1359 --without-nss --without-cyassl --without-polarssl --without-ssl \
1360 --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \
1361 --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \
1362 --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \
1364 $ sudo make install@
1370 $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz@
1371 $ tar xf gnunet-0.10.1.tar.gz@
1379 Install to a different directory:@
1383 Have sudo permission, but do not want to compile as root:@
1387 Want debug message enabled:@
1388 -- enable-logging=verbose
1392 $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose]@
1393 $ make; sudo make install@
1396 After installing it, you need to create an empty configuration file:@
1397 @code{touch ~/.config/gnunet.conf}
1399 And finally you can start GNUnet with@
1400 @code{$ gnunet-arm -s}
1402 @node Building GLPK for MinGW
1403 @subsection Building GLPK for MinGW
1405 GNUnet now requires the GNU Linear Programming Kit (GLPK). Since there's is no
1406 package you can install with @code{mingw-get} you have to compile it from
1412 Download the latest version from http://ftp.gnu.org/gnu/glpk/
1415 Unzip it using your favourite unzipper@
1419 change to the respective directory
1422 @code{./configure '--build=i686-pc-mingw32'}
1425 run @code{make install check }
1427 MinGW does not automatically detect the correct buildtype so you have to
1432 @node GUI build instructions for Ubuntu 12.04 using Subversion
1433 @subsection GUI build instructions for Ubuntu 12.04 using Subversion
1435 After installing GNUnet you can continue installing the GNUnet GUI tools:
1437 First, install the required dependencies:
1440 $ sudo apt-get install libgladeui-dev libqrencode-dev@
1443 Please ensure that the GNUnet shared libraries can be found by the linker. If
1444 you installed GNUnet libraries in a non standard path (say
1445 GNUNET_PREFIX=/usr/local/lib/), you can
1450 set the environmental variable permanently to@
1451 @code{LD_LIBRARY_PATH=$GNUNET_PREFIX}
1454 or add @code{$GNUNET_PREFIX} to @code{/etc/ld.so.conf}
1458 Now you can checkout and compile the GNUnet GUI tools@
1460 $ svn co https://gnunet.org/svn/gnunet-gtk@
1463 $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/..@
1467 @node Installation with gnunet-update
1468 @subsection Installation with gnunet-update
1470 gnunet-update project is an effort to introduce updates to GNUnet
1471 installations. An interesting to-be-implemented-feature of gnunet-update is
1472 that these updates are propagated through GNUnet's peer-to-peer network. More
1473 information about gnunet-update can be found at
1474 https://gnunet.org/svn/gnunet-update/README.
1476 While the project is still under development, we have implemented the following
1477 features which we believe may be helpful for users and we would like them to be
1483 Packaging GNUnet installation along with its run-time dependencies into update
1487 Installing update packages into compatible hosts
1490 Updating an existing installation (which had been installed by gnunet-update)
1494 The above said features of gnunet-update are currently available for testing on
1497 The following is a guide to help you get started with gnunet-update. It shows
1498 you how to install the testing binary packages of GNUnet 0.9.1 we have at
1499 https://gnunet.org/install/
1501 gnunet-update needs the following:
1505 python ( 2.6 or above)
1515 Checkout gnunet-update:@
1517 $ svn checkout -r24905 https://gnunet.org/svn/gnunet-update@
1520 For security reasons, all packages released for gnunet-update from us are
1521 signed with the key at https://gnunet.org/install/key.txt You would need to
1522 import this key into your gpg key ring. gnunet-update uses this key to verify
1523 the integrity of the packages it installs@
1525 $ gpg --recv-keys 7C613D78@
1528 Download the packages relevant to your architecture (currently I have access to
1529 GNU/Linux machines on x86_64 and i686, so only two for now, hopefully more
1530 later) from https://gnunet.org/install/.
1532 To install the downloaded package into the directory /foo:
1535 gnunet-update/bin/gnunet-update install downloaded/package /foo@
1538 The installer reports the directories into which shared libraries and
1539 dependencies have been installed. You may need to add the reported shared
1540 library installation paths to LD_LIBRARY_PATH before you start running any
1543 Please report bugs at https://gnunet.org/bugs/ under the project
1546 @node Instructions for Microsoft Windows Platforms (Old)
1547 @subsection Instructions for Microsoft Windows Platforms (Old)
1549 This document is a DEPRECATED installation guide for gnunet on windows. It will
1550 not work for recent gnunet versions, but maybe it will be of some use if
1553 The Windows build uses a UNIX emulator for Windows,
1554 @uref{http://www.mingw.org/, MinGW}, to build the executable modules. These
1555 modules run natively on Windows and do not require additional emulation
1556 software besides the usual dependencies.
1558 GNUnet development is mostly done under Linux and especially SVN checkouts may
1559 not build out of the box. We regret any inconvenience, and if you have
1560 problems, please report them.
1565 * Hardware and OS requirements::
1566 * Software installation::
1567 * Building libextractor and GNUnet::
1572 @node Hardware and OS requirements
1573 @subsubsection Hardware and OS requirements
1578 Pentium II or equivalent processor, 350 MHz or better
1584 600 MB free disk space
1587 Windows 2000 or Windows XP are recommended
1590 @node Software installation
1591 @subsubsection Software installation
1596 @strong{Compression software}@
1598 The software packages GNUnet depends on are usually compressed using UNIX
1599 tools like tar, gzip and bzip2.@ If you do not already have an utility that is
1600 able to extract such archives, get @uref{http://www.7-zip.org/, 7-Zip}.
1603 @strong{UNIX environment}@
1605 The MinGW project provides the compiler toolchain that is used to build
1606 GNUnet.@ Get the following packages from
1607 @uref{http://sourceforge.net/projects/mingw/files/, the MinGW project}:
1621 MSYS Developer Tool Kit (msysDTK)
1624 MSYS Developer Tool Kit - msys-autoconf (bin)
1627 MSYS Developer Tool Kit - msys-automake (bin)
1655 Install MSYS (to c:\mingw, for example.)@
1656 Do @strong{not} use spaces in the pathname (c:\program files\mingw).
1659 Install MinGW runtime, utilities and GCC to a subdirectory (to c:\mingw\mingw,
1663 Install the Development Kit to the MSYS directory (c:\mingw)
1666 Create a batch file bash.bat in your MSYS directory with the files:@
1673 This batch file opens a shell which is used to invoke the build processes..@
1674 MinGW's standard shell (msys.bat) is not suitable because it opens a separate
1675 console window@ On Vista, bash.bat needs to be run as administrator.
1678 Start bash.sh and rename (c:\mingw\mingw\)lib\libstdc++.la to avoid problems:@
1681 mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken
1686 Unpack the Windows API to the MinGW directory (c:\mingw\mingw\) and remove the
1687 declaration of DATADIR from (c:\mingw\mingw\)include\objidl.h (lines 55-58)
1690 Unpack autoconf, automake to the MSYS directory (c:\mingw)
1693 Install all other packages to the MinGW directory (c:\mingw\mingw\)
1698 @strong{GNU Libtool}@
1700 GNU Libtool is required to use shared libraries.@
1702 Get the prebuilt package from here and unpack it to the MinGW directory
1708 GNUnet uses the portable POSIX thread library for multi-threading..@
1714 Save @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86
1715 /libpthreadGC2.a, libpthreadGC2.a} (x86) or @uref{ftp://sources.redhat.c
1716 om/pub/pthreads-win32/dll-latest/lib/x64/libpthreadGC2.a, libpthreadGC2.
1717 a} (x64) as libpthread.a into the lib directory (c:\mingw\mingw\lib\libpt
1721 Save @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86
1722 /pthreadGC2.dll, pthreadGC2.dll} (x86) or @uref{ftp://sources.redhat.c
1723 om/pub/pthreads-win32/dll-latest/lib/x64/pthreadGC2.dll, libpthreadGC2.a}
1724 (x64) into the MinGW bin directory (c:\mingw\mingw\bin)
1727 Download all header files from @uref{ftp://sources.redhat.com/pub/pthread
1728 s-win32/dll-latest/include/, include/} to the @file{include} directory
1729 (c:\mingw\mingw\include)
1737 GNUnet uses the GNU Multiple Precision library for special cryptographic operations.@
1739 Get the GMP binary package from the
1740 @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and
1741 unpack it to the MinGW directory (c:\mingw\mingw)
1744 @strong{GNU Gettext}@
1746 GNU gettext is used to provide national language support.@
1748 Get the prebuilt package from hereand unpack it to the MinGW directory (c:\mingw\mingw)
1753 GNU Libiconv is used for character encoding conversion.@
1755 Get the prebuilt package from here and unpack it to the MinGW directory (c:\mingw\mingw)
1760 GNUnet uses the SQLite database to store data.@
1762 Get the prebuilt binary from here and unpack it to your MinGW directory.
1764 @item @strong{MySQL}@
1765 As an alternative to SQLite, GNUnet also supports MySQL.
1769 @item Get the binary installer from the
1770 @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project}
1771 (version 4.1), install it and follow the instructions in README.mysql.
1773 @item Create a temporary build directory (c:\mysql)
1775 @item Copy the directories include\ and lib\ from the MySQL directory to
1778 @item Get the patches from
1779 @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and
1780 @uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the
1781 latter is only required for MySQL
1787 @item Move lib\opt\libmysql.dll to lib\libmysql.dll
1789 @item Change to lib\ and create an import library:@
1792 dlltool --input-def ../include/libmySQL.def --dllname libmysql.dll
1793 --output-lib libmysqlclient.a -k
1796 @item Copy include\* to include\mysql\
1798 @item Pass "--with-mysql=/c/mysql" to ./configure and copy libmysql.dll
1799 to your PATH or GNUnet's @file{bin} directory
1806 gnunet-gtk and libextractor depend on GTK.@
1808 Get the the binary and developer packages of atk, glib, gtk, iconv,
1809 gettext-runtime, pango from
1810 @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack it to the
1811 MinGW directory (c:\mingw\mingw)@
1813 Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and libpng
1814 and unpack them to the MinGW directory (c:\mingw\mingw)@
1816 Here is an all-in-one package for
1817 @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies}.
1818 Do not overwrite any existing files!
1823 gnunet-gtk and and gnunet-setup were created using this interface builder
1829 Get the Glade and libglade (-bin and -devel) packages (without GTK!) from
1830 @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack it to
1831 the MinGW directory (c:\mingw\mingw)
1834 Get libxml from here and unpack it to the MinGW
1835 directory (c:\mingw\mingw).
1842 libextractor requires zLib to decompress some file formats. GNUnet uses it
1843 to (de)compress meta-data.@
1845 Get zLib from here (Signature) and unpack it to the
1846 MinGW directory (c:\mingw\mingw)
1851 libextractor also requires Bzip2 to decompress some file formats.@
1853 Get Bzip2 (binary and developer package) from
1854 @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and
1855 unpack it to the MinGW directory (c:\mingw\mingw)
1860 Libgcrypt provides the cryptographic functions used by GNUnet@
1862 Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here},
1863 compile and place it in the MinGW directory (c:\mingw\mingw). Currently
1864 you need at least version 1.4.2 to compile GNUnet.
1869 PlibC emulates Unix functions under Windows.@
1871 Get PlibC from here and unpack it to the MinGW
1872 directory (c:\mingw\mingw)
1875 @strong{OGG Vorbis}@
1877 OGG Vorbis is used to extract meta-data from .ogg files@
1880 @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg}
1882 @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis}
1884 @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build}
1885 and unpack them to the MinGW directory (c:\mingw\mingw)
1890 (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data@
1893 @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2}
1894 and unpack it to the MSYS directory (c:\mingw)
1897 @node Building libextractor and GNUnet
1898 @subsubsection Building libextractor and GNUnet
1900 Before you compile libextractor or GNUnet, be sure to set PKG_CONFIG_PATH:
1903 export PKG_CONFIG_PATH=/mingw/lib/pkgconfig
1907 See Installation for basic instructions on building libextractor
1908 and GNUnet. By default, all modules that are created in this way contain
1909 debug information and are quite large. To compile release versions (small
1910 and fast) set the variable CFLAGS:
1913 export CFLAGS='-O2 -march=pentium -fomit-frame-pointer'
1914 ./configure --prefix=$HOME --with-extractor=$HOME
1918 @subsubsection Installer
1920 The GNUnet installer is made with
1921 @uref{http://nsis.sourceforge.net/, NSIS}. The installer script is
1922 located in @file{contrib\win} in the GNUnet source tree.
1925 @subsubsection Source
1927 The sources of all dependencies are available here.
1929 @node Portable GNUnet
1930 @section Portable GNUnet
1932 Quick instructions on how to use the most recent GNUnet on most GNU/Linux
1935 Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian
1936 and CentOS 6, but it should work on almost any GNU/Linux distribution.
1937 More in-detail information can be found in the handbook.
1943 * Download & set up gnunet-update::
1948 @subsection Prerequisites
1950 Open a terminal and paste this line into it to install all required tools
1952 @code{sudo apt-get install python-gpgme subversion}
1954 @node Download & set up gnunet-update
1955 @subsection Download & set up gnunet-update
1957 The following command will download a working version of gnunet-update
1958 with the subversion tool and import the public key which is needed for
1962 svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update
1964 gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78
1967 @node Install GNUnet
1968 @subsection Install GNUnet
1970 Download and install GNUnet binaries which can be found here and set
1974 wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz
1975 ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~
1976 echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment
1977 echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \
1978 /etc/ld.so.conf.d/gnunet.conf > /dev/null
1982 You may need to re-login once after executing these last commands
1984 That's it, GNUnet is installed in your home directory now. GNUnet can be
1985 configured and afterwards started by executing @code{gnunet-arm -s}.
1987 @node The graphical configuration interface
1988 @section The graphical configuration interface
1990 If you also would like to use gnunet-gtk and gnunet-setup (highly
1991 recommended for beginners), do:
1994 wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz
1995 sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~
1999 Now you can run @code{gnunet-setup} for easy configuration of your
2003 * Configuring your peer::
2004 * Configuring the Friend-to-Friend (F2F) mode::
2005 * Configuring the hostlist to bootstrap::
2006 * Configuration of the HOSTLIST proxy settings::
2007 * Configuring your peer to provide a hostlist ::
2008 * Configuring the datastore::
2009 * Configuring the MySQL database::
2010 * Reasons for using MySQL::
2011 * Reasons for not using MySQL::
2012 * Setup Instructions::
2014 * Performance Tuning::
2015 * Setup for running Testcases::
2016 * Configuring the Postgres database::
2017 * Reasons to use Postgres::
2018 * Reasons not to use Postgres::
2019 * Manual setup instructions::
2020 * Testing the setup manually::
2021 * Configuring the datacache::
2022 * Configuring the file-sharing service::
2023 * Configuring logging::
2024 * Configuring the transport service and plugins::
2025 * Configuring the wlan transport plugin::
2026 * Configuring HTTP(S) reverse proxy functionality using Apache or nginx::
2027 * Blacklisting peers::
2028 * Configuration of the HTTP and HTTPS transport plugins::
2029 * Configuring the GNU Name System::
2030 * Configuring the GNUnet VPN::
2031 * Bandwidth Configuration::
2033 * Peer configuration for distributions::
2036 @node Configuring your peer
2037 @subsection Configuring your peer
2039 This chapter will describe the various configuration options in GNUnet.
2041 The easiest way to configure your peer is to use the gnunet-setup tool.
2042 gnunet-setup is part of the gnunet-gtk download. You might have to
2043 install it separately.
2045 Many of the specific sections from this chapter actually are linked from
2046 within gnunet-setup to help you while using the setup tool.
2048 While you can also configure your peer by editing the configuration
2049 file by hand, this is not recommended for anyone except for developers.
2052 @node Configuring the Friend-to-Friend (F2F) mode
2053 @subsection Configuring the Friend-to-Friend (F2F) mode
2055 GNUnet knows three basic modes of operation. In standard "peer-to-peer"
2056 mode, your peer will connect to any peer. In the pure "friend-to-friend"
2057 mode, your peer will ONLY connect to peers from a list of friends
2058 specified in the configuration.
2059 Finally, in mixed mode, GNUnet will only connect to arbitrary peers if it
2060 has at least a specified number of connections to friends.
2062 When configuring any of the F2F modes, you first need to create a file
2063 with the peer identities of your friends. Ask your friends to run
2066 $ gnunet-peerinfo -sq
2070 The output of this command needs to be added to your friends file, which
2071 is simply a plain text file with one line per friend with the output from
2074 You then specify the location of your friends file in the "FRIENDS"
2075 option of the "topology" section.
2077 Once you have created the friends file, you can tell GNUnet to only
2078 connect to your friends by setting the "FRIENDS-ONLY" option (again in
2079 the "topology" section) to YES.
2081 If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a
2082 minimum number of friends to have (before connecting to arbitrary peers)
2083 under the "MINIMUM-FRIENDS" option.
2085 If you want to operate in normal P2P-only mode, simply set
2086 "MINIMUM-FRIENDS" to zero and "FRIENDS_ONLY" to NO. This is the default.
2088 @node Configuring the hostlist to bootstrap
2089 @subsection Configuring the hostlist to bootstrap
2091 After installing the software you need to get connected to the GNUnet
2092 network. The configuration file included in your download is already
2093 configured to connect you to the GNUnet network.
2094 In this section the relevant configuration settings are explained.
2096 To get an initial connection to the GNUnet network and to get to know
2097 peers already connected to the network you can use the so called
2099 These servers can give you a list of peers connected to the network.
2100 To use these bootstrap servers you have to configure the hostlist daemon
2101 to activate bootstrapping.
2103 To activate bootstrapping edit your configuration file and edit the
2104 @code{[hostlist]}-section. You have to set the argument "-b" in the
2112 Additionally you have to specify which server you want to use.
2113 The default bootstrapping server is
2114 "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}".
2115 [^] To set the server you have to edit the line "SERVERS" in the hostlist
2116 section. To use the default server you should set the lines to
2119 SERVERS = http://v10.gnunet.org/hostlist [^]
2123 To use bootstrapping your configuration file should include these lines:
2128 SERVERS = http://v10.gnunet.org/hostlist [^]
2132 Besides using bootstrap servers you can configure your GNUnet peer to
2133 recieve hostlist advertisements.
2134 Peers offering hostlists to other peers can send advertisement messages
2135 to peers that connect to them. If you configure your peer to receive these
2136 messages, your peer can download these lists and connect to the peers
2137 included. These lists are persistent, which means that they are saved to
2138 your hard disk regularly and are loaded during startup.
2140 To activate hostlist learning you have to add the "-e" switch to the
2141 OPTIONS line in the hostlist section:
2149 Furthermore you can specify in which file the lists are saved. To save the
2150 lists in the file "hostlists.file" just add the line:
2153 HOSTLISTFILE = hostlists.file
2157 Best practice is to activate both bootstrapping and hostlist learning.
2158 So your configuration file should include these lines:
2164 SERVERS = http://v10.gnunet.org/hostlist [^]
2165 HOSTLISTFILE = $SERVICEHOME/hostlists.file
2168 @node Configuration of the HOSTLIST proxy settings
2169 @subsection Configuration of the HOSTLIST proxy settings
2171 The hostlist client can be configured to use a proxy to connect to the
2173 This functionality can be configured in the configuration file directly
2174 or using the gnunet-setup tool.
2176 The hostlist client supports the following proxy types at the moment:
2179 @item HTTP and HTTP 1.0 only proxy
2180 @item SOCKS 4/4a/5/5 with hostname
2183 In addition authentication at the proxy with username and password can be
2186 To configure proxy support for the hostlist client in the gnunet-setup
2187 tool, select the "hostlist" tab and select the appropriate proxy type.
2188 The hostname or IP address (including port if required) has to be entered
2189 in the "Proxy hostname" textbox. If required, enter username and password
2190 in the "Proxy username" and "Proxy password" boxes.
2191 Be aware that these information will be stored in the configuration in
2194 To configure these options directly in the configuration, you can
2195 configure the following settings in the
2196 @code{[hostlist]} section of the configuration:
2199 # Type of proxy server,@
2200 # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME@
2204 # Hostname or IP of proxy server@
2206 # User name for proxy server@
2208 # User password for proxy server@
2212 @node Configuring your peer to provide a hostlist
2213 @subsection Configuring your peer to provide a hostlist
2215 If you operate a peer permanently connected to GNUnet you can configure
2216 your peer to act as a hostlist server, providing other peers the list of
2219 Yor server can act as a bootstrap server and peers needing to obtain a
2220 list of peers can contact him to download this list.
2221 To download this hostlist the peer uses HTTP.
2222 For this reason you have to build your peer with libcurl and microhttpd
2223 support. How you build your peer with this options can be found here:
2224 @uref{https://gnunet.org/generic_installation}
2226 To configure your peer to act as a bootstrap server you have to add the
2227 "@code{-p}" option to OPTIONS in the @code{[hostlist]} section of your
2228 configuration file. Besides that you have to specify a port number for
2229 the http server. In conclusion you have to add the following lines:
2238 If your peer acts as a bootstrap server other peers should know about
2239 that. You can advertise the hostlist your are providing to other peers.
2240 Peers connecting to your peer will get a message containing an
2241 advertisement for your hostlist and the URL where it can be downloaded.
2242 If this peer is in learning mode, it will test the hostlist and, in the
2243 case it can obtain the list successfully, it will save it for
2246 To activate hostlist advertisement on your peer, you have to set the
2247 following lines in your configuration file:
2251 EXTERNAL_DNS_NAME = example.org
2257 With this configuration your peer will a act as a bootstrap server and
2258 advertise this hostlist to other peers connecting to him. The URL used to
2259 download the list will be
2260 @code{@uref{http://example.org:12981/, http://example.org:12981/}}.
2264 @item The hostlist is not human readable, so you should not try to
2265 download it using your webbrowser. Just point your GNUnet peer to the
2267 @item Advertising without providing a hostlist does not make sense and
2271 @node Configuring the datastore
2272 @subsection Configuring the datastore
2274 The datastore is what GNUnet uses to for long-term storage of file-sharing
2275 data. Note that long-term does not mean 'forever' since content does have
2276 an expiration date, and of course storage space is finite (and hence
2277 sometimes content may have to be discarded).
2279 Use the "QUOTA" option to specify how many bytes of storage space you are
2280 willing to dedicate to GNUnet.
2282 In addition to specifying the maximum space GNUnet is allowed to use for
2283 the datastore, you need to specify which database GNUnet should use to do
2284 so. Currently, you have the choice between sqLite, MySQL and Postgres.
2286 @node Configuring the MySQL database
2287 @subsection Configuring the MySQL database
2289 This section describes how to setup the MySQL database for GNUnet.
2291 Note that the mysql plugin does NOT work with mysql before 4.1 since we
2292 need prepared statements.
2293 We are generally testing the code against MySQL 5.1 at this point.
2295 @node Reasons for using MySQL
2296 @subsection Reasons for using MySQL
2301 On up-to-date hardware where mysql can be used comfortably, this module
2302 will have better performance than the other database choices (according
2305 @item Its often possible to recover the mysql database from internal
2306 inconsistencies. Some of the other databases do not support repair.
2309 @node Reasons for not using MySQL
2310 @subsection Reasons for not using MySQL
2313 @item Memory usage (likely not an issue if you have more than 1 GB)
2314 @item Complex manual setup
2317 @node Setup Instructions
2318 @subsection Setup Instructions
2321 @item In @code{gnunet.conf} set in section "DATASTORE" the value for
2322 "DATABASE" to "mysql".
2323 @item Access mysql as root:@
2330 and issue the following commands, replacing $USER with the username
2331 that will be running gnunet-arm (so typically "gnunet"):
2334 CREATE DATABASE gnunet;
2335 GRANT select,insert,update,delete,create,alter,drop,create temporary tables
2336 ON gnunet.* TO $USER@@localhost;
2337 SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like');
2342 In the $HOME directory of $USER, create a ".my.cnf" file with the
2348 password=$the_password_you_like
2353 Thats it. Note that @code{.my.cnf} file is a slight security risk unless
2354 its on a safe partition. The $HOME/.my.cnf can of course be a symbolic
2355 link. Luckily $USER has only priviledges to mess up GNUnet's tables,
2356 which should be pretty harmless.
2361 You should briefly try if the database connection works. First, login
2370 If you get the message "Database changed" it probably works.
2372 If you get "ERROR 2002: Can't connect to local MySQL server@
2373 through socket '/tmp/mysql.sock' (2)" it may be resolvable by@
2374 "ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock"@
2375 so there may be some additional trouble depending on your mysql setup.
2377 @node Performance Tuning
2378 @subsection Performance Tuning
2380 For GNUnet, you probably want to set the option
2383 innodb_flush_log_at_trx_commit = 0
2387 for a rather dramatic boost in MySQL performance. However, this reduces
2388 the "safety" of your database as with this options you may loose
2389 transactions during a power outage.
2390 While this is totally harmless for GNUnet, the option applies to all
2391 applications using MySQL. So you should set it if (and only if) GNUnet is
2392 the only application on your system using MySQL.
2394 @node Setup for running Testcases
2395 @subsection Setup for running Testcases
2397 If you want to run the testcases, you must create a second database
2398 "gnunetcheck" with the same username and password. This database will
2399 then be used for testing ("make check").
2401 @node Configuring the Postgres database
2402 @subsection Configuring the Postgres database
2404 This text describes how to setup the Postgres database for GNUnet.
2406 This Postgres plugin was developed for Postgres 8.3 but might work for
2407 earlier versions as well.
2409 @node Reasons to use Postgres
2410 @subsection Reasons to use Postgres
2413 @item Easier to setup than MySQL
2417 @node Reasons not to use Postgres
2418 @subsection Reasons not to use Postgres
2422 @item Still some manual setup required
2425 @node Manual setup instructions
2426 @subsection Manual setup instructions
2429 @item In @code{gnunet.conf} set in section "DATASTORE" the value for
2430 "DATABASE" to "postgres".
2431 @item Access Postgres to create a user:@
2434 @item with Postgres 8.x, use:
2442 and enter the name of the user running GNUnet for the role interactively.
2443 Then, when prompted, do not set it to superuser, allow the creation of
2444 databases, and do not allow the creation of new roles.@
2446 @item with Postgres 9.x, use:
2450 $ createuser -d $GNUNET_USER
2454 where $GNUNET_USER is the name of the user running GNUnet.@
2460 As that user (so typically as user "gnunet"), create a database (or two):@
2464 # this way you can run "make check"
2465 $ createdb gnunetcheck
2470 Now you should be able to start @code{gnunet-arm}.
2472 @node Testing the setup manually
2473 @subsection Testing the setup manually
2475 You may want to try if the database connection works. First, again login
2476 as the user who will run gnunet-arm. Then use,
2479 $ psql gnunet # or gnunetcheck
2484 If, after you have started gnunet-arm at least once, you get
2485 a @code{gn090} table here, it probably works.
2487 @node Configuring the datacache
2488 @subsection Configuring the datacache
2491 The datacache is what GNUnet uses for storing temporary data. This data is
2492 expected to be wiped completely each time GNUnet is restarted (or the
2493 system is rebooted).
2495 You need to specify how many bytes GNUnet is allowed to use for the
2496 datacache using the "QUOTA" option in the section "dhtcache".
2497 Furthermore, you need to specify which database backend should be used to
2498 store the data. Currently, you have the choice between
2499 sqLite, MySQL and Postgres.
2501 @node Configuring the file-sharing service
2502 @subsection Configuring the file-sharing service
2504 In order to use GNUnet for file-sharing, you first need to make sure
2505 that the file-sharing service is loaded.
2506 This is done by setting the AUTOSTART option in section "fs" to "YES".
2507 Alternatively, you can run
2514 to start the file-sharing service by hand.
2516 Except for configuring the database and the datacache the only important
2517 option for file-sharing is content migration.
2519 Content migration allows your peer to cache content from other peers as
2520 well as send out content stored on your system without explicit requests.
2521 This content replication has positive and negative impacts on both system
2522 performance and privacy.
2524 FIXME: discuss the trade-offs. Here is some older text about it...
2526 Setting this option to YES allows gnunetd to migrate data to the local
2527 machine. Setting this option to YES is highly recommended for efficiency.
2528 Its also the default. If you set this value to YES, GNUnet will store
2529 content on your machine that you cannot decrypt.
2530 While this may protect you from liability if the judge is sane, it may
2531 not (IANAL). If you put illegal content on your machine yourself, setting
2532 this option to YES will probably increase your chances to get away with it
2533 since you can plausibly deny that you inserted the content.
2534 Note that in either case, your anonymity would have to be broken first
2535 (which may be possible depending on the size of the GNUnet network and the
2536 strength of the adversary).
2538 @node Configuring logging
2539 @subsection Configuring logging
2541 Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options.
2542 Using "-L", a log level can be specified. With log level "ERROR" only
2543 serious errors are logged.
2544 The default log level is "WARNING" which causes anything of
2545 concern to be logged. Log level "INFO" can be used to log anything that
2546 might be interesting information whereas "DEBUG" can be used by
2547 developers to log debugging messages (but you need to run configure with
2548 @code{--enable-logging=verbose} to get them compiled).
2549 The "-l" option is used to specify the log file.
2551 Since most GNUnet services are managed by @code{gnunet-arm}, using the
2552 "-l" or "-L" options directly is not possible.
2553 Instead, they can be specified using the "OPTIONS" configuration value in
2554 the respective section for the respective service.
2555 In order to enable logging globally without editing the "OPTIONS" values
2556 for each service, @code{gnunet-arm} supports a "GLOBAL_POSTFIX" option.
2557 The value specified here is given as an extra option to all services for
2558 which the configuration does contain a service-specific "OPTIONS" field.
2560 "GLOBAL_POSTFIX" can contain the special sequence "@{@}" which is replaced
2561 by the name of the service that is being started. Furthermore,
2562 @code{GLOBAL_POSTFIX} is special in that sequences starting with "$"
2563 anywhere in the string are expanded (according to options in "PATHS");
2564 this expansion otherwise is only happening for filenames and then the "$"
2565 must be the first character in the option. Both of these restrictions do
2566 not apply to "GLOBAL_POSTFIX".
2567 Note that specifying @code{%} anywhere in the "GLOBAL_POSTFIX" disables
2568 both of these features.
2570 In summary, in order to get all services to log at level "INFO" to
2571 log-files called @code{SERVICENAME-logs}, the following global prefix
2575 GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO
2578 @node Configuring the transport service and plugins
2579 @subsection Configuring the transport service and plugins
2581 The transport service in GNUnet is responsible to maintain basic
2582 connectivity to other peers.
2583 Besides initiating and keeping connections alive it is also responsible
2584 for address validation.
2586 The GNUnet transport supports more than one transport protocol.
2587 These protocols are configured together with the transport service.
2589 The configuration section for the transport service itself is quite
2590 similar to all the other services
2594 @@UNIXONLY@@ PORT = 2091@
2595 HOSTNAME = localhost@
2596 HOME = $SERVICEHOME@
2597 CONFIG = $DEFAULTCONFIG@
2598 BINARY = gnunet-service-transport@
2600 NEIGHBOUR_LIMIT = 50@
2601 ACCEPT_FROM = 127.0.0.1;@
2602 ACCEPT_FROM6 = ::1;@
2604 UNIXPATH = /tmp/gnunet-service-transport.sock@
2607 Different are the settings for the plugins to load @code{PLUGINS}.
2608 The first setting specifies which transport plugins to load.
2611 @item transport-unix
2612 A plugin for local only communication with UNIX domain sockets. Used for
2613 testing and available on unix systems only. Just set the port
2618 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2622 A plugin for communication with TCP. Set port to 0 for client mode with
2623 outbound only connections
2627 # Use 0 to ONLY advertise as a peer behind NAT (no port binding)@
2629 ADVERTISED_PORT = 2086@
2630 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2631 # Maximum number of open TCP connections allowed@
2632 MAX_CONNECTIONS = 128@
2636 A plugin for communication with UDP. Supports peer discovery using
2643 BROADCAST_INTERVAL = 30 s@
2645 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2648 @item transport-http
2649 HTTP and HTTPS support is split in two part: a client plugin initiating
2650 outbound connections and a server part accepting connections from the
2651 client. The client plugin just takes the maximum number of connections as
2655 [transport-http_client]@
2656 MAX_CONNECTIONS = 128@
2657 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2661 [transport-https_client]@
2662 MAX_CONNECTIONS = 128@
2663 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2667 The server has a port configured and the maximum nunber of connections.
2668 The HTTPS part has two files with the certificate key and the certificate
2671 The server plugin supports reverse proxies, so a external hostname can be
2672 set using the @code{EXTERNAL_HOSTNAME} setting.
2673 The webserver under this address should forward the request to the peer
2674 and the configure port.
2677 [transport-http_server]@
2678 EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet@
2680 MAX_CONNECTIONS = 128@
2681 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2685 [transport-https_server]@
2687 CRYPTO_INIT = NORMAL@
2688 KEY_FILE = https.key@
2689 CERT_FILE = https.cert@
2690 MAX_CONNECTIONS = 128@
2691 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2694 @item transport-wlan
2696 There is a special article how to setup the WLAN plugin, so here only the
2697 settings. Just specify the interface to use:
2701 # Name of the interface in monitor mode (typically monX)@
2703 # Real hardware, no testing@
2705 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2709 @node Configuring the wlan transport plugin
2710 @subsection Configuring the wlan transport plugin
2713 The wlan transport plugin enables GNUnet to send and to receive data on a
2715 It has not to be connected to a wlan network as long as sender and
2716 receiver are on the same channel. This enables you to get connection to
2717 the GNUnet where no internet access is possible, for example while
2718 catastrophes or when censorship cuts you off the internet.
2722 * Requirements for the WLAN plugin::
2724 * Before starting GNUnet::
2725 * Limitations and known bugs::
2729 @node Requirements for the WLAN plugin
2730 @subsubsection Requirements for the WLAN plugin
2734 @item wlan network card with monitor support and packet injection
2735 (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org})
2737 @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with
2740 @item Wlantools to create the a monitor interface, tested with airmon-ng
2741 of the aircrack-ng package
2745 @subsubsection Configuration
2747 There are the following options for the wlan plugin (they should be like
2748 this in your default config file, you only need to adjust them if the
2749 values are incorrect for your system)
2752 # section for the wlan transport plugin@
2754 # interface to use, more information in the
2755 # "Before starting GNUnet" section of the handbook.
2757 # testmode for developers:@
2758 # 0 use wlan interface,@
2759 #1 or 2 use loopback driver for tests 1 = server, 2 = client@
2763 @node Before starting GNUnet
2764 @subsubsection Before starting GNUnet
2766 Before starting GNUnet, you have to make sure that your wlan interface is
2767 in monitor mode. One way to put the wlan interface into monitor mode (if
2768 your interface name is wlan0) is by executing:
2771 sudo airmon-ng start wlan0@
2775 Here is an example what the result should look like:
2778 Interface Chipset Driver@
2779 wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]@
2780 (monitor mode enabled on mon0)@
2784 The monitor interface is mon0 is the one that you have to put into the
2787 @node Limitations and known bugs
2788 @subsubsection Limitations and known bugs
2790 Wlan speed is at the maximum of 1 Mbit/s because support for choosing the
2791 wlan speed with packet injection was removed in newer kernels.
2792 Please pester the kernel developers about fixing this.
2794 The interface channel depends on the wlan network that the card is
2795 connected to. If no connection has been made since the start of the
2796 computer, it is usually the first channel of the card.
2797 Peers will only find each other and communicate if they are on the same
2798 channel. Channels must be set manually (i.e. using
2799 @code{iwconfig wlan0 channel 1}).
2802 @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx
2803 @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
2805 The HTTP plugin supports data transfer using reverse proxies. A reverse
2806 proxy forwards the HTTP request he receives with a certain URL to another
2807 webserver, here a GNUnet peer.
2809 So if you have a running Apache or nginx webserver you can configure it to
2810 be a GNUnet reverse proxy. Especially if you have a well-known webiste
2811 this improves censorship resistance since it looks as normal surfing
2814 To do so, you have to do two things:
2817 @item Configure your webserver to forward the GNUnet HTTP traffic
2818 @item Configure your GNUnet peer to announce the respective address
2821 As an example we want to use GNUnet peer running:
2825 @item HTTP server plugin on @code{gnunet.foo.org:1080}
2827 @item HTTPS server plugin on @code{gnunet.foo.org:4433}
2829 @item A apache or nginx webserver on
2830 @uref{http://www.foo.org/, http://www.foo.org:80/}
2832 @item A apache or nginx webserver on https://www.foo.org:443/
2835 And we want the webserver to accept GNUnet traffic under
2836 @code{http://www.foo.org/bar/}. The required steps are described here:
2838 @strong{Configure your Apache2 HTTP webserver}
2840 First of all you need mod_proxy installed.
2842 Edit your webserver configuration. Edit
2843 @code{/etc/apache2/apache2.conf} or the site-specific configuration file.
2845 In the respective @code{server config},@code{virtual host} or
2846 @code{directory} section add the following lines:
2852 ProxyPass http://gnunet.foo.org:1080/@
2853 ProxyPassReverse http://gnunet.foo.org:1080/@
2858 @strong{Configure your Apache2 HTTPS webserver}
2860 We assume that you already have an HTTPS server running, if not please
2861 check how to configure a HTTPS host. An easy to use example is the
2862 @file{apache2/sites-available/default-ssl} example configuration file.
2864 In the respective HTTPS @code{server config},@code{virtual host} or
2865 @code{directory} section add the following lines:
2872 ProxyPass https://gnunet.foo.org:4433/@
2873 ProxyPassReverse https://gnunet.foo.org:4433/@
2878 More information about the apache mod_proxy configuration can be found
2879 at @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}
2881 @strong{Configure your nginx HTTPS webserver}
2883 Since nginx does not support chunked encoding, you first of all have to
2884 install @code{chunkin}:@
2885 @uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}
2887 To enable chunkin add:
2891 error_page 411 = @@my_411_error;@
2892 location @@my_411_error @{@
2898 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
2899 the site-specific configuration file.
2901 In the @code{server} section add:@
2906 proxy_pass http://gnunet.foo.org:1080/;@
2907 proxy_buffering off;@
2908 proxy_connect_timeout 5; # more than http_server@
2909 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout@
2910 proxy_http_version 1.1; # 1.0 default@
2911 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@
2916 @strong{Configure your nginx HTTPS webserver}
2918 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
2919 the site-specific configuration file.
2921 In the @code{server} section add:
2924 ssl_session_timeout 6m;@
2927 proxy_pass https://gnunet.foo.org:4433/;@
2928 proxy_buffering off;@
2929 proxy_connect_timeout 5; # more than http_server@
2930 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout@
2931 proxy_http_version 1.1; # 1.0 default@
2932 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@
2937 @strong{Configure your GNUnet peer}
2939 To have your GNUnet peer announce the address, you have to specify the
2940 @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]}
2944 [transport-http_server]@
2945 EXTERNAL_HOSTNAME = http://www.foo.org/bar/@
2949 and/or @code{[transport-https_server]} section:
2952 [transport-https_server]@
2953 EXTERNAL_HOSTNAME = https://www.foo.org/bar/@
2957 Now restart your webserver and your peer...
2959 @node Blacklisting peers
2960 @subsection Blacklisting peers
2962 Transport service supports to deny connecting to a specific peer of to a
2963 specific peer with a specific transport plugin using te blacklisting
2964 component of transport service. With@ blacklisting it is possible to deny
2965 connections to specific peers of@ to use a specific plugin to a specific
2966 peer. Peers can be blacklisted using@ the configuration or a blacklist
2967 client can be asked.
2969 To blacklist peers using the configuration you have to add a section to
2970 your@ configuration containing the peer id of the peer to blacklist and
2971 the plugin@ if required.
2975 To blacklist connections to P565... on peer AG2P... using tcp add:@
2977 @c FIXME: This is too long and produces errors in the pdf.
2979 [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@
2980 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp@
2983 To blacklist connections to P565... on peer AG2P... using all plugins add:@
2986 [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@
2987 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =@
2990 You can also add a blacklist client usign the blacklist api. On a
2991 blacklist check, blacklisting first checks internally if the peer is
2992 blacklisted and if not, it asks the blacklisting clients. Clients are
2993 asked if it is OK to connect to a peer ID, the plugin is omitted.
2995 On blacklist check for (peer, plugin)
2997 @item Do we have a local blacklist entry for this peer and this plugin?@
2998 @item YES: disallow connection@
2999 @item Do we have a local blacklist entry for this peer and all plugins?@
3000 @item YES: disallow connection@
3001 @item Does one of the clients disallow?@
3002 @item YES: disallow connection
3005 @node Configuration of the HTTP and HTTPS transport plugins
3006 @subsection Configuration of the HTTP and HTTPS transport plugins
3008 The client part of the http and https transport plugins can be configured
3009 to use a proxy to connect to the hostlist server. This functionality can
3010 be configured in the configuration file directly or using the
3013 The both the HTTP and HTTPS clients support the following proxy types at
3017 @item HTTP 1.1 proxy
3018 @item SOCKS 4/4a/5/5 with hostname
3021 In addition authentication at the proxy with username and password can be
3024 To configure proxy support for the clients in the gnunet-setup tool,
3025 select the "transport" tab and activate the respective plugin. Now you
3026 can select the appropriate proxy type. The hostname or IP address
3027 (including port if required) has to be entered in the "Proxy hostname"
3028 textbox. If required, enter username and password in the "Proxy username"
3029 and "Proxy password" boxes. Be aware that these information will be stored
3030 in the configuration in plain text.
3032 To configure these options directly in the configuration, you can
3033 configure the following settings in the [transport-http_client] and
3034 [transport-https_client] section of the configuration:
3037 # Type of proxy server,@
3038 # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME@
3042 # Hostname or IP of proxy server@
3044 # User name for proxy server@
3046 # User password for proxy server@
3050 @node Configuring the GNU Name System
3051 @subsection Configuring the GNU Name System
3054 * Configuring system-wide DNS interception::
3055 * Configuring the GNS nsswitch plugin::
3056 * Configuring GNS on W32::
3058 * Setup of the GNS CA::
3059 * Testing the GNS setup::
3060 * Automatic Shortening in the GNU Name System::
3064 @node Configuring system-wide DNS interception
3065 @subsubsection Configuring system-wide DNS interception
3067 Before you install GNUnet, make sure you have a user and group 'gnunet'
3068 as well as an empty group 'gnunetdns'.
3070 When using GNUnet with system-wide DNS interception, it is absolutely
3071 necessary for all GNUnet service processes to be started by
3072 @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be
3073 sure to run @code{make install} as root (or use the @code{sudo} option to
3074 configure) to grant GNUnet sufficient privileges.
3076 With this setup, all that is required for enabling system-wide DNS
3077 interception is for some GNUnet component (VPN or GNS) to request it.
3078 The @code{gnunet-service-dns} will then start helper programs that will
3079 make the necessary changes to your firewall (@code{iptables}) rules.
3081 Note that this will NOT work if your system sends out DNS traffic to a
3082 link-local IPv6 address, as in this case GNUnet can intercept the traffic,
3083 but not inject the responses from the link-local IPv6 address. Hence you
3084 cannot use system-wide DNS interception in conjunction with link-local
3085 IPv6-based DNS servers. If such a DNS server is used, it will bypass
3086 GNUnet's DNS traffic interception.
3088 Using the GNU Name System (GNS) requires two different configuration
3090 First of all, GNS needs to be integrated with the operating system. Most
3091 of this section is about the operating system level integration.
3093 Additionally, each individual user who wants to use the system must also
3094 initialize his GNS zones. This can be done by running (after starting
3098 $ gnunet-gns-import.sh
3102 after the local GNUnet peer has been started. Note that the namestore (in
3103 particular the namestore database backend) should not be reconfigured
3104 afterwards (as records are not automatically migrated between backends).
3106 The remainder of this chapter will detail the various methods for
3107 configuring the use of GNS with your operating system.
3109 At this point in time you have different options depending on your OS:
3113 @item Use the gnunet-gns-proxy This approach works for all operating
3114 systems and is likely the easiest. However, it enables GNS only for
3115 browsers, not for other applications that might be using DNS, such as SSH.
3116 Still, using the proxy is required for using HTTP with GNS and is thus
3117 recommended for all users. To do this, you simply have to run the
3118 @code{gnunet-gns-proxy-setup-ca} script as the user who will run the
3119 browser (this will create a GNS certificate authority (CA) on your system
3120 and import its key into your browser), then start @code{gnunet-gns-proxy}
3121 and inform your browser to use the Socks5 proxy which
3122 @code{gnunet-gns-proxy} makes available by default on port 7777.
3123 @item Use a nsswitch plugin (recommended on GNU systems)
3124 This approach has the advantage of offering fully personalized resolution
3125 even on multi-user systems. A potential disadvantage is that some
3126 applications might be able to bypass GNS.
3127 @item Use a W32 resolver plugin (recommended on W32)
3128 This is currently the only option on W32 systems.
3129 @item Use system-wide DNS packet interception
3130 This approach is recommended for the GNUnet VPN. It can be used to handle
3131 GNS at the same time; however, if you only use this method, you will only
3132 get one root zone per machine (not so great for multi-user systems).
3135 You can combine system-wide DNS packet interception with the nsswitch
3137 The setup of the system-wide DNS interception is described here. All of
3138 the other GNS-specific configuration steps are described in the following
3141 @node Configuring the GNS nsswitch plugin
3142 @subsubsection Configuring the GNS nsswitch plugin
3144 The Name Service Switch (NSS) is a facility in Unix-like operating systems
3145 that provides a variety of sources for common configuration databases and
3146 name resolution mechanisms.
3147 A system administrator usually configures the operating system's name
3148 services using the file @file{/etc/nsswitch.conf}.
3150 GNS provides a NSS plugin to integrate GNS name resolution with the
3151 operating system's name resolution process.
3152 To use the GNS NSS plugin you have to either
3155 @item install GNUnet as root or
3156 @item compile GNUnet with the @code{--with-sudo=yes} switch.
3159 Name resolution is controlled by the @emph{hosts} section in the NSS
3160 configuration. By default this section first performs a lookup in the
3161 /etc/hosts file and then in DNS. The nsswitch file should contain a line
3165 hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4
3169 Here the GNS NSS plugin can be added to perform a GNS lookup before
3170 performing a DNS lookup.
3171 The GNS NSS plugin has to be added to the "hosts" section in
3172 @file{/etc/nsswitch.conf} file before DNS related plugins:
3176 hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4
3181 The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not
3182 found in GNS it will not be queried in DNS.
3184 @node Configuring GNS on W32
3185 @subsubsection Configuring GNS on W32
3187 This document is a guide to configuring GNU Name System on W32-compatible
3190 After GNUnet is installed, run the w32nsp-install tool:
3193 w32nsp-install.exe libw32nsp-0.dll
3197 ('0' is the library version of W32 NSP; it might increase in the future,
3198 change the invocation accordingly).
3200 This will install GNS namespace provider into the system and allow other
3201 applications to resolve names that end in '@strong{gnu}'
3202 and '@strong{zkey}'. Note that namespace provider requires
3203 gnunet-gns-helper-service-w32 to be running, as well as gns service
3204 itself (and its usual dependencies).
3206 Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353},
3207 and this is where gnunet-gns-helper-service-w32 should be listening to
3208 (and is configured to listen to by default).
3210 To uninstall the provider, run:
3213 w32nsp-uninstall.exe
3217 (uses provider GUID to uninstall it, does not need a dll name).
3219 Note that while MSDN claims that other applications will only be able to
3220 use the new namespace provider after re-starting, in reality they might
3221 stat to use it without that. Conversely, they might stop using the
3222 provider after it's been uninstalled, even if they were not re-started.
3223 W32 will not permit namespace provider library to be deleted or
3224 overwritten while the provider is installed, and while there is at least
3225 one process still using it (even after it was uninstalled).
3227 @node GNS Proxy Setup
3228 @subsubsection GNS Proxy Setup
3230 When using the GNU Name System (GNS) to browse the WWW, there are several
3231 issues that can be solved by adding the GNS Proxy to your setup:
3235 @item If the target website does not support GNS, it might assume that it
3236 is operating under some name in the legacy DNS system (such as
3237 example.com). It may then attempt to set cookies for that domain, and the
3238 web server might expect a @code{Host: example.com} header in the request
3240 However, your browser might be using @code{example.gnu} for the
3241 @code{Host} header and might only accept (and send) cookies for
3242 @code{example.gnu}. The GNS Proxy will perform the necessary translations
3243 of the hostnames for cookies and HTTP headers (using the LEHO record for
3244 the target domain as the desired substitute).
3246 @item If using HTTPS, the target site might include an SSL certificate
3247 which is either only valid for the LEHO domain or might match a TLSA
3248 record in GNS. However, your browser would expect a valid certificate for
3249 @code{example.gnu}, not for some legacy domain name. The proxy will
3250 validate the certificate (either against LEHO or TLSA) and then
3251 on-the-fly produce a valid certificate for the exchange, signed by your
3252 own CA. Assuming you installed the CA of your proxy in your browser's
3253 certificate authority list, your browser will then trust the
3254 HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy.
3256 @item Finally, the proxy will in the future indicate to the server that it
3257 speaks GNS, which will enable server operators to deliver GNS-enabled web
3258 sites to your browser (and continue to deliver legacy links to legacy
3262 @node Setup of the GNS CA
3263 @subsubsection Setup of the GNS CA
3265 First you need to create a CA certificate that the proxy can use.
3266 To do so use the provided script gnunet-gns-proxy-ca:
3269 $ gnunet-gns-proxy-setup-ca
3273 This will create a personal certification authority for you and add this
3274 authority to the firefox and chrome database. The proxy will use the this
3275 CA certificate to generate @code{*.gnu} client certificates on the fly.
3277 Note that the proxy uses libcurl. Make sure your version of libcurl uses
3278 GnuTLS and NOT OpenSSL. The proxy will not work with libcurl compiled
3281 @node Testing the GNS setup
3282 @subsubsection Testing the GNS setup
3284 Now for testing purposes we can create some records in our zone to test
3285 the SSL functionality of the proxy:
3288 $ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67
3289 $ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org"
3293 At this point we can start the proxy. Simply execute
3300 Configure your browser to use this SOCKSv5 proxy on port 7777 and visit
3302 If you use firefox you also have to go to about:config and set the key
3303 @code{network.proxy.socks_remote_dns} to @code{true}.
3305 When you visit @code{https://homepage.gnu/}, you should get to the
3306 @code{https://gnunet.org/} frontpage and the browser (with the correctly
3307 configured proxy) should give you a valid SSL certificate for
3308 @code{homepage.gnu} and no warnings. It should look like this:
3310 @c insert image here gnunethpgns.png
3312 @node Automatic Shortening in the GNU Name System
3313 @subsubsection Automatic Shortening in the GNU Name System
3315 This page describes a possible option for 'automatic name shortening',
3316 which you can choose to enable with the GNU Name System.
3318 When GNS encounters a name for the first time, it can use the 'NICK'
3319 record of the originating zone to automatically generate a name for the
3320 zone. If automatic shortening is enabled, those auto-generated names will
3321 be placed (as private records) into your personal 'shorten' zone (to
3322 prevent confusion with manually selected names).
3323 Then, in the future, if the same name is encountered again, GNS will
3324 display the shortened name instead (the first time, the long name will
3325 still be used as shortening typically happens asynchronously as looking up
3326 the 'NICK' record takes some time). Using this feature can be a convenient
3327 way to avoid very long @code{.gnu} names; however, note that names from
3328 the shorten-zone are assigned on a first-come-first-serve basis and should
3329 not be trusted. Furthermore, if you enable this feature, you will no
3330 longer see the full delegation chain for zones once shortening has been
3333 @node Configuring the GNUnet VPN
3334 @subsection Configuring the GNUnet VPN
3337 * IPv4 address for interface::
3338 * IPv6 address for interface::
3339 * Configuring the GNUnet VPN DNS::
3340 * Configuring the GNUnet VPN Exit Service::
3341 * IP Address of external DNS resolver::
3342 * IPv4 address for Exit interface::
3343 * IPv6 address for Exit interface::
3346 Before configuring the GNUnet VPN, please make sure that system-wide DNS
3347 interception is configured properly as described in the section on the
3350 The default-options for the GNUnet VPN are usually sufficient to use
3351 GNUnet as a Layer 2 for your Internet connection. However, what you always
3352 have to specify is which IP protocol you want to tunnel: IPv4, IPv6 or
3353 both. Furthermore, if you tunnel both, you most likely should also tunnel
3354 all of your DNS requests.
3355 You theoretically can tunnel "only" your DNS traffic, but that usually
3358 The other options as shown on the gnunet-setup tool are:
3360 @node IPv4 address for interface
3361 @subsubsection IPv4 address for interface
3363 This is the IPv4 address the VPN interface will get. You should pick an
3364 'private' IPv4 network that is not yet in use for you system. For example,
3365 if you use 10.0.0.1/255.255.0.0 already, you might use
3366 10.1.0.1/255.255.0.0.
3367 If you use 10.0.0.1/255.0.0.0 already, then you might use
3368 192.168.0.1/255.255.0.0.
3369 If your system is not in a private IP-network, using any of the above will
3371 You should try to make the mask of the address big enough (255.255.0.0
3372 or, even better, 255.0.0.0) to allow more mappings of remote IP Addresses
3374 However, even a 255.255.255.0-mask will suffice for most users.
3376 @node IPv6 address for interface
3377 @subsubsection IPv6 address for interface
3379 The IPv6 address the VPN interface will get. Here you can specify any
3380 non-link-local address (the address should not begin with "fe80:").
3381 A subnet Unique Local Unicast (fd00::/8-prefix) that you are currently
3382 not using would be a good choice.
3384 @node Configuring the GNUnet VPN DNS
3385 @subsubsection Configuring the GNUnet VPN DNS
3387 To resolve names for remote nodes, activate the DNS exit option.
3389 @node Configuring the GNUnet VPN Exit Service
3390 @subsubsection Configuring the GNUnet VPN Exit Service
3392 If you want to allow other users to share your Internet connection (yes,
3393 this may be dangerous, just as running a Tor exit node) or want to
3394 provide access to services on your host (this should be less dangerous,
3395 as long as those services are secure), you have to enable the GNUnet exit
3398 You then get to specify which exit functions you want to provide. By
3399 enabling the exit daemon, you will always automatically provide exit
3400 functions for manually configured local services (this component of the
3402 development and not documented further at this time). As for those
3403 services you explicitly specify the target IP address and port, there is
3404 no significant security risk in doing so.
3406 Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet.
3407 Being a DNS exit is usually pretty harmless. However, enabling IPv4 or
3408 IPv6-exit without further precautions may enable adversaries to access
3409 your local network, send spam, attack other systems from your Internet
3410 connection and to other mischief that will appear to come from your
3411 machine. This may or may not get you into legal trouble.
3412 If you want to allow IPv4 or IPv6-exit functionality, you should strongly
3413 consider adding additional firewall rules manually to protect your local
3414 network and to restrict outgoing TCP traffic (i.e. by not allowing access
3415 to port 25). While we plan to improve exit-filtering in the future,
3416 you're currently on your own here.
3417 Essentially, be prepared for any kind of IP-traffic to exit the respective
3418 TUN interface (and GNUnet will enable IP-forwarding and NAT for the
3419 interface automatically).
3421 Additional configuration options of the exit as shown by the gnunet-setup
3424 @node IP Address of external DNS resolver
3425 @subsubsection IP Address of external DNS resolver
3427 If DNS traffic is to exit your machine, it will be send to this DNS
3428 resolver. You can specify an IPv4 or IPv6 address.
3430 @node IPv4 address for Exit interface
3431 @subsubsection IPv4 address for Exit interface
3433 This is the IPv4 address the Interface will get. Make the mask of the
3434 address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more
3435 mappings of IP addresses into this range. As for the VPN interface, any
3436 unused, private IPv4 address range will do.
3438 @node IPv6 address for Exit interface
3439 @subsubsection IPv6 address for Exit interface
3441 The public IPv6 address the interface will get. If your kernel is not a
3442 very recent kernel and you are willing to manually enable IPv6-NAT, the
3443 IPv6 address you specify here must be a globally routed IPv6 address of
3446 Suppose your host has the address @code{2001:4ca0::1234/64}, then
3447 using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits,
3448 then change at least one bit in the range before the bitmask, in the
3449 example above we changed bit 111 from 0 to 1).
3451 You may also have to configure your router to route traffic for the entire
3452 subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this
3453 should be automatic with IPv6, but obviously anything can be
3456 @node Bandwidth Configuration
3457 @subsection Bandwidth Configuration
3459 You can specify how many bandwidth GNUnet is allowed to use to receive
3460 and send data. This is important for users with limited bandwidth or
3463 @node Configuring NAT
3464 @subsection Configuring NAT
3466 Most hosts today do not have a normal global IP address but instead are
3467 behind a router performing Network Address Translation (NAT) which assigns
3468 each host in the local network a private IP address.
3469 As a result, these machines cannot trivially receive inbound connections
3470 from the Internet. GNUnet supports NAT traversal to enable these machines
3471 to receive incoming connections from other peers despite their
3474 In an ideal world, you can press the "Attempt automatic configuration"
3475 button in gnunet-setup to automatically configure your peer correctly.
3476 Alternatively, your distribution might have already triggered this
3477 automatic configuration during the installation process.
3478 However, automatic configuration can fail to determine the optimal
3479 settings, resulting in your peer either not receiving as many connections
3480 as possible, or in the worst case it not connecting to the network at all.
3482 To manually configure the peer, you need to know a few things about your
3483 network setup. First, determine if you are behind a NAT in the first
3485 This is always the case if your IP address starts with "10.*" or
3486 "192.168.*". Next, if you have control over your NAT router, you may
3487 choose to manually configure it to allow GNUnet traffic to your host.
3488 If you have configured your NAT to forward traffic on ports 2086 (and
3489 possibly 1080) to your host, you can check the "NAT ports have been opened
3490 manually" option, which corresponds to the "PUNCHED_NAT" option in the
3491 configuration file. If you did not punch your NAT box, it may still be
3492 configured to support UPnP, which allows GNUnet to automatically
3493 configure it. In that case, you need to install the "upnpc" command,
3494 enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal
3495 via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the
3496 configuration file).
3498 Some NAT boxes can be traversed using the autonomous NAT traversal method.
3499 This requires certain GNUnet components to be installed with "SUID"
3500 prividledges on your system (so if you're installing on a system you do
3501 not have administrative rights to, this will not work).
3502 If you installed as 'root', you can enable autonomous NAT traversal by
3503 checking the "Enable NAT traversal using ICMP method".
3504 The ICMP method requires a way to determine your NAT's external (global)
3505 IP address. This can be done using either UPnP, DynDNS, or by manual
3506 configuration. If you have a DynDNS name or know your external IP address,
3507 you should enter that name under "External (public) IPv4 address" (which
3508 corresponds to the "EXTERNAL_ADDRESS" option in the configuration file).
3509 If you leave the option empty, GNUnet will try to determine your external
3510 IP address automatically (which may fail, in which case autonomous
3511 NAT traversal will then not work).
3513 Finally, if you yourself are not behind NAT but want to be able to
3514 connect to NATed peers using autonomous NAT traversal, you need to check
3515 the "Enable connecting to NATed peers using ICMP method" box.
3518 @node Peer configuration for distributions
3519 @subsection Peer configuration for distributions
3521 The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be
3522 manually set to "/var/lib/gnunet/data/" as the default
3523 "~/.local/share/gnunet/" is probably not that appropriate in this case.
3524 Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to
3525 "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a
3526 distribution decide to override system defaults, all of these changes
3527 should be done in a custom @file{/etc/gnunet.conf} and not in the files
3528 in the @file{config.d/} directory.
3530 Given the proposed access permissions, the "gnunet-setup" tool must be
3531 run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it
3532 modifies the system configuration). As always, gnunet-setup should be run
3533 after the GNUnet peer was stopped using "gnunet-arm -e". Distributions
3534 might want to include a wrapper for gnunet-setup that allows the
3535 desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account
3536 and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
3539 @node How to start and stop a GNUnet peer
3540 @section How to start and stop a GNUnet peer
3542 This section describes how to start a GNUnet peer. It assumes that you
3543 have already compiled and installed GNUnet and its' dependencies.
3544 Before you start a GNUnet peer, you may want to create a configuration
3545 file using gnunet-setup (but you do not have to).
3546 Sane defaults should exist in your
3547 @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice
3548 you could simply start without any configuration. If you want to
3549 configure your peer later, you need to stop it before invoking the
3550 @code{gnunet-setup} tool to customize further and to test your
3551 configuration (@code{gnunet-setup} has build-in test functions).
3553 The most important option you might have to still set by hand is in
3554 [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where
3555 GNUnet should store its data.
3556 It defaults to @code{$HOME/}, which again should work for most users.
3557 Make sure that the directory specified as GNUNET_HOME is writable to
3558 the user that you will use to run GNUnet (note that you can run frontends
3559 using other users, GNUNET_HOME must only be accessible to the user used to
3560 run the background processes).
3562 You will also need to make one central decision: should all of GNUnet be
3563 run under your normal UID, or do you want distinguish between system-wide
3564 (user-independent) GNUnet services and personal GNUnet services. The
3565 multi-user setup is slightly more complicated, but also more secure and
3566 generally recommended.
3569 * The Single-User Setup::
3570 * The Multi-User Setup::
3571 * Killing GNUnet services::
3572 * Access Control for GNUnet::
3575 @node The Single-User Setup
3576 @subsection The Single-User Setup
3578 For the single-user setup, you do not need to do anything special and can
3579 just start the GNUnet background processes using @code{gnunet-arm}.
3580 By default, GNUnet looks in @file{~/.config/gnunet.conf} for a
3581 configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@
3582 @code{$XDG_CONFIG_HOME} is defined). If your configuration lives
3583 elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet
3586 Assuming the configuration file is called @file{~/.config/gnunet.conf},
3587 you start your peer using the @code{gnunet-arm} command (say as user
3588 @code{gnunet}) using:
3591 gnunet-arm -c ~/.config/gnunet.conf -s
3595 The "-s" option here is for "start". The command should return almost
3596 instantly. If you want to stop GNUnet, you can use:
3599 gnunet-arm -c ~/.config/gnunet.conf -e
3603 The "-e" option here is for "end".
3605 Note that this will only start the basic peer, no actual applications
3607 If you want to start the file-sharing service, use (after starting
3611 gnunet-arm -c ~/.config/gnunet.conf -i fs
3615 The "-i fs" option here is for "initialize" the "fs" (file-sharing)
3616 application. You can also selectively kill only file-sharing support using
3619 gnunet-arm -c ~/.config/gnunet.conf -k fs
3623 Assuming that you want certain services (like file-sharing) to be always
3624 automatically started whenever you start GNUnet, you can activate them by
3625 setting "FORCESTART=YES" in the respective section of the configuration
3626 file (for example, "[fs]"). Then GNUnet with file-sharing support would
3627 be started whenever you@ enter:
3630 gnunet-arm -c ~/.config/gnunet.conf -s
3634 Alternatively, you can combine the two options:
3637 gnunet-arm -c ~/.config/gnunet.conf -s -i fs
3641 Using @code{gnunet-arm} is also the preferred method for initializing
3642 GNUnet from @code{init}.
3644 Finally, you should edit your @code{crontab} (using the @code{crontab}
3645 command) and insert a line@
3648 @@reboot gnunet-arm -c ~/.config/gnunet.conf -s@
3651 to automatically start your peer whenever your system boots.
3653 @node The Multi-User Setup
3654 @subsection The Multi-User Setup
3656 This requires you to create a user @code{gnunet} and an additional group
3657 @code{gnunetdns}, prior to running @code{make install} during
3659 Then, you create a configuration file @file{/etc/gnunet.conf} which should
3669 Then, perform the same steps to run GNUnet as in the per-user
3670 configuration, except as user @code{gnunet} (including the
3671 @code{crontab} installation).
3672 You may also want to run @code{gnunet-setup} to configure your peer
3674 Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you
3675 run @code{gnunet-setup} as user @code{gnunet}, you might need to change
3676 permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can
3677 write to the file (during setup).
3679 Afterwards, you need to perform another setup step for each normal user
3680 account from which you want to access GNUnet. First, grant the normal user
3681 (@code{$USER}) permission to the group gnunet:
3684 # adduser $USER gnunet
3688 Then, create a configuration file in @file{~/.config/gnunet.conf} for the
3689 $USER with the lines:
3698 This will ensure that @code{gnunet-arm} when started by the normal user
3699 will only run services that are per-user, and otherwise rely on the
3700 system-wide services.
3701 Note that the normal user may run gnunet-setup, but the
3702 configuration would be ineffective as the system-wide services will use
3703 @code{/etc/gnunet.conf} and ignore options set by individual users.
3705 Again, each user should then start the peer using
3706 @code{gnunet-arm -s} --- and strongly consider adding logic to start
3707 the peer automatically to their crontab.
3709 Afterwards, you should see two (or more, if you have more than one USER)
3710 @code{gnunet-service-arm} processes running in your system.
3712 @node Killing GNUnet services
3713 @subsection Killing GNUnet services
3715 It is not necessary to stop GNUnet services explicitly when shutting
3718 It should be noted that manually killing "most" of the
3719 @code{gnunet-service} processes is generally not a successful method for
3720 stopping a peer (since @code{gnunet-service-arm} will instantly restart
3721 them). The best way to explicitly stop a peer is using
3722 @code{gnunet-arm -e}; note that the per-user services may need to be
3723 terminated before the system-wide services will terminate normally.
3725 @node Access Control for GNUnet
3726 @subsection Access Control for GNUnet
3728 This chapter documents how we plan to make access control work within the
3729 GNUnet system for a typical peer. It should be read as a best-practice
3730 installation guide for advanced users and builders of binary
3731 distributions. The recommendations in this guide apply to POSIX-systems
3732 with full support for UNIX domain sockets only.
3734 Note that this is an advanced topic. The discussion presumes a very good
3735 understanding of users, groups and file permissions. Normal users on
3736 hosts with just a single user can just install GNUnet under their own
3737 account (and possibly allow the installer to use SUDO to grant additional
3738 permissions for special GNUnet tools that need additional rights).
3739 The discussion below largely applies to installations where multiple users
3740 share a system and to installations where the best possible security is
3743 A typical GNUnet system consists of components that fall into four
3748 @item User interfaces
3749 User interfaces are not security sensitive and are supposed to be run and
3750 used by normal system users.
3751 The GTK GUIs and most command-line programs fall into this category.
3752 Some command-line tools (like gnunet-transport) should be excluded as they
3753 offer low-level access that normal users should not need.
3754 @item System services and support tools
3755 System services should always run and offer services that can then be
3756 accessed by the normal users.
3757 System services do not require special permissions, but as they are not
3758 specific to a particular user, they probably should not run as a
3759 particular user. Also, there should typically only be one GNUnet peer per
3760 host. System services include the gnunet-service and gnunet-daemon
3761 programs; support tools include command-line programs such as gnunet-arm.
3762 @item Priviledged helpers
3763 Some GNUnet components require root rights to open raw sockets or perform
3764 other special operations. These gnunet-helper binaries are typically
3765 installed SUID and run from services or daemons.
3766 @item Critical services
3767 Some GNUnet services (such as the DNS service) can manipulate the service
3768 in deep and possibly highly security sensitive ways. For example, the DNS
3769 service can be used to intercept and alter any DNS query originating from
3770 the local machine. Access to the APIs of these critical services and their
3771 priviledged helpers must be tightly controlled.
3774 @c FIXME: The titles of these chapters are too long in the index.
3777 * Recommendation - Disable access to services via TCP::
3778 * Recommendation - Run most services as system user "gnunet"::
3779 * Recommendation - Control access to services using group "gnunet"::
3780 * Recommendation - Limit access to certain SUID binaries by group "gnunet"::
3781 * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"::
3782 * Differences between "make install" and these recommendations::
3785 @node Recommendation - Disable access to services via TCP
3786 @subsubsection Recommendation - Disable access to services via TCP
3788 GNUnet services allow two types of access: via TCP socket or via UNIX
3790 If the service is available via TCP, access control can only be
3791 implemented by restricting connections to a particular range of IP
3793 This is acceptable for non-critical services that are supposed to be
3794 available to all users on the local system or local network.
3795 However, as TCP is generally less efficient and it is rarely the case
3796 that a single GNUnet peer is supposed to serve an entire local network,
3797 the default configuration should disable TCP access to all GNUnet
3798 services on systems with support for UNIX domain sockets.
3799 As of GNUnet 0.9.2, configuration files with TCP access disabled should be
3800 generated by default. Users can re-enable TCP access to particular
3801 services simply by specifying a non-zero port number in the section of
3802 the respective service.
3805 @node Recommendation - Run most services as system user "gnunet"
3806 @subsubsection Recommendation - Run most services as system user "gnunet"
3808 GNUnet's main services should be run as a separate user "gnunet" in a
3809 special group "gnunet".
3810 The user "gnunet" should start the peer using "gnunet-arm -s" during
3811 system startup. The home directory for this user should be
3812 @file{/var/lib/gnunet} and the configuration file should be
3813 @file{/etc/gnunet.conf}.
3814 Only the @code{gnunet} user should have the right to access
3815 @file{/var/lib/gnunet} (@emph{mode: 700}).
3817 @node Recommendation - Control access to services using group "gnunet"
3818 @subsubsection Recommendation - Control access to services using group "gnunet"
3820 Users that should be allowed to use the GNUnet peer should be added to the
3821 group "gnunet". Using GNUnet's access control mechanism for UNIX domain
3822 sockets, those services that are considered useful to ordinary users
3823 should be made available by setting "UNIX_MATCH_GID=YES" for those
3825 Again, as shipped, GNUnet provides reasonable defaults.
3826 Permissions to access the transport and core subsystems might additionally
3827 be granted without necessarily causing security concerns.
3828 Some services, such as DNS, must NOT be made accessible to the "gnunet"
3829 group (and should thus only be accessible to the "gnunet" user and
3830 services running with this UID).
3832 @node Recommendation - Limit access to certain SUID binaries by group "gnunet"
3833 @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet"
3835 Most of GNUnet's SUID binaries should be safe even if executed by normal
3836 users. However, it is possible to reduce the risk a little bit more by
3837 making these binaries owned by the group "gnunet" and restricting their
3838 execution to user of the group "gnunet" as well (4750).
3840 @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
3841 @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
3843 A special group "gnunetdns" should be created for controlling access to
3844 the "gnunet-helper-dns".
3845 The binary should then be owned by root and be in group "gnunetdns" and
3846 be installed SUID and only be group-executable (2750).
3847 @b{Note that the group "gnunetdns" should have no users in it at all,
3849 The "gnunet-service-dns" program should be executed by user "gnunet" (via
3850 gnunet-service-arm) with the binary owned by the user "root" and the group
3851 "gnunetdns" and be SGID (2700). This way, @strong{only}
3852 "gnunet-service-dns" can change its group to "gnunetdns" and execute the
3853 helper, and the helper can then run as root (as per SUID).
3854 Access to the API offered by "gnunet-service-dns" is in turn restricted
3855 to the user "gnunet" (not the group!), which means that only
3856 "benign" services can manipulate DNS queries using "gnunet-service-dns".
3858 @node Differences between "make install" and these recommendations
3859 @subsubsection Differences between "make install" and these recommendations
3861 The current build system does not set all permissions automatically based
3862 on the recommendations above. In particular, it does not use the group
3863 "gnunet" at all (so setting gnunet-helpers other than the
3864 gnunet-helper-dns to be owned by group "gnunet" must be done manually).
3865 Furthermore, 'make install' will silently fail to set the DNS binaries to
3866 be owned by group "gnunetdns" unless that group already exists (!).
3867 An alternative name for the "gnunetdns" group can be specified using the
3868 "--with-gnunetdns=GRPNAME" configure option.