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 ("DANE support")}
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/006588.html, this}
83 post (and the link inside it)).}
84 @item @uref{https://gnunet.org/gnurl, gnURL} libgnurl @geq{} 7.34.0
85 @footnote{must be compiled after @code{GnuTLS}}
86 @item libglpk @geq{} 4.45
87 @item @uref{http://www.openssl.org/, OpenSSL} @geq{} 1.0
88 @item TeX Live @geq{} 2012, optional (for gnunet-bcd)
89 @item Texinfo @geq{} 5.2 (for documentation)
90 @item libsqlite @geq{} 3.8.0 @footnote{(note that the code will
91 compile and often work with lower version numbers, but you may get subtle
92 bugs with respect to quota management in certain rare cases);
93 alternatively, MySQL or Postgres can also be installed, but those
94 databases will require more complex configurations (not
95 recommended for first-time users)}
99 @node Fixing libgnurl build issues
100 @subsection Fixing libgnurl build issues
102 If you have to compile libgnurl from source since the version included in
103 your distribution is to old you perhaps get an error message while
104 running the @file{configure} script:
109 checking for 64-bit curl_off_t data type... unknown
110 checking for 32-bit curl_off_t data type... unknown
111 checking for 16-bit curl_off_t data type... unknown
112 configure: error: cannot find data type for curl_off_t.
118 Before running the configure script, set:
121 CFLAGS="-I. -I$BUILD_ROOT/include"
124 @node Optional dependencies
125 @subsection Optional dependencies
127 These applications must be installed for various experimental or otherwise
128 optional features such as @code{gnunet-conversation}, @code{gnunet-gtk}.
131 @item libpulse 2.0 or higher, optional (for gnunet-conversation)
132 @item libopus 1.0.1 or higher, optional (for gnunet-conversation)
133 @item libogg 1.3.0 or higher, optional (for gnunet-conversation)
134 @item certool (binary) optional @footnote{for convenient installation of
135 the GNS proxy (available as part of Debian's libnss3-tools)}
136 @item python-zbar 0.10 or higher, optional (for gnunet-qr)
137 @item Gtk+ 3.0 or higher, optional (for gnunet-gtk)
138 @item libgladeui must match Gtk+ version, optional (for gnunet-gtk)
139 @item libqrencode 3.0 or higher, optional (for gnunet-namestore-gtk)
142 @node Internal dependencies
143 @subsection Internal dependencies
145 This section tries to give an overview of what processes a typical GNUnet peer
146 running a particular application would consist of. All of the processes listed
147 here should be automatically started by @code{gnunet-arm -s}. The list is given
148 as a rough first guide to users for failure diagnostics. Ideally, end-users
149 should never have to worry about these internal dependencies.
151 In terms of internal dependencies, a minimum file-sharing system consists of
152 the following GNUnet processes (in order of dependency):
155 @item gnunet-service-arm
156 @item gnunet-service-resolver (required by all)
157 @item gnunet-service-statistics (required by all)
158 @item gnunet-service-peerinfo
159 @item gnunet-service-transport (requires peerinfo)
160 @item gnunet-service-core (requires transport)
161 @item gnunet-daemon-hostlist (requires core)
162 @item gnunet-daemon-topology (requires hostlist, peerinfo)
163 @item gnunet-service-datastore
164 @item gnunet-service-dht (requires core)
165 @item gnunet-service-identity
166 @item gnunet-service-fs (requires identity, mesh, dht, datastore, core)
170 A minimum VPN system consists of the following GNUnet processes (in order of
174 @item gnunet-service-arm
175 @item gnunet-service-resolver (required by all)
176 @item gnunet-service-statistics (required by all)
177 @item gnunet-service-peerinfo
178 @item gnunet-service-transport (requires peerinfo)
179 @item gnunet-service-core (requires transport)
180 @item gnunet-daemon-hostlist (requires core)
181 @item gnunet-service-dht (requires core)
182 @item gnunet-service-mesh (requires dht, core)
183 @item gnunet-service-dns (requires dht)
184 @item gnunet-service-regex (requires dht)
185 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
189 A minimum GNS system consists of the following GNUnet processes (in order of
192 @item gnunet-service-arm
193 @item gnunet-service-resolver (required by all)
194 @item gnunet-service-statistics (required by all)
195 @item gnunet-service-peerinfo
196 @item gnunet-service-transport (requires peerinfo)
197 @item gnunet-service-core (requires transport)
198 @item gnunet-daemon-hostlist (requires core)
199 @item gnunet-service-dht (requires core)
200 @item gnunet-service-mesh (requires dht, core)
201 @item gnunet-service-dns (requires dht)
202 @item gnunet-service-regex (requires dht)
203 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
204 @item gnunet-service-identity
205 @item gnunet-service-namestore (requires identity)
206 @item gnunet-service-gns (requires vpn, dns, dht, namestore, identity)
209 @node Pre-installation notes
210 @section Pre-installation notes
212 Please note that in the code instructions for the installation,
213 @emph{#} indicates commands run as privileged root user and
214 @emph{$} shows commands run as unprivileged ("normal") system user.
217 @node Generic installation instructions
218 @section Generic installation instructions
220 First, in addition to the GNUnet sources you must download the latest version
221 of various dependencies. Most distributions do not include sufficiently recent
222 versions of these dependencies. Thus, a typically installation on a "modern"
223 GNU/Linux distribution requires you to install the following
224 dependencies (ideally in this order):
227 @item libgpgerror and libgcrypt
228 @item libnettle and libunbound (possibly from distribution), GnuTLS
229 @item libgnurl (read the README)
230 @item GNU libmicrohttpd
231 @item GNU libextractor
234 Make sure to first install the various mandatory and optional
235 dependencies including development headers from your distribution.
237 Other dependencies that you should strongly consider to install is a
238 database (MySQL, sqlite or Postgres). The following instructions will assume
239 that you installed at least sqlite. For most distributions you should be able
240 to find pre-build packages for the database. Again, make sure to install the
241 client libraries and the respective development headers (if they are
242 packaged separately) as well.
244 You can find specific, detailed instructions for installing of the dependencies
245 (and possibly the rest of the GNUnet installation) in the platform-specific
246 descriptions, which are linked from the bottom of this page. Please consult
247 them now. If your distribution is not listed, please study the instructions for
248 Debian stable carefully as you try to install the dependencies for your own
249 distribution. Contributing additional instructions for further platforms is
252 Before proceeding further, please double-check the dependency list.
253 Note that in addition to satisfying the dependencies, you might have to
254 make sure that development headers for the various libraries are also
256 There maybe files for other distributions, or you might be able to find
257 equivalent packages for your distribution.
259 While it is possible to build and install GNUnet without having root access,
260 we will assume that you have full control over your system in these
261 instructions. First, you should create a system user @emph{gnunet} and
262 an additional group @emph{gnunetdns}. On Debian and Ubuntu GNU/Linux, type:
265 # adduser --system --home /var/lib/gnunet --group \
266 --disabled-password gnunet
267 # addgroup --system gnunetdns
270 On other Unixes, this should have the same effect:
273 # useradd --system --groups gnunet --home-dir /var/lib/gnunet
274 # addgroup --system gnunetdns
277 Now compile and install GNUnet using:
280 $ tar xvf gnunet-0.10.?.tar.gz
282 $ ./configure --with-sudo=sudo --with-nssdir=/lib
287 If you want to be able to enable DEBUG-level log messages, add
288 @code{--enable-logging=verbose} to the end of the @code{./configure} command.
289 DEBUG-level log messages are in English-only and should only be useful for
290 developers (or for filing really detailed bug reports).
292 Finally, you probably want to compile @code{gnunet-gtk}, which
293 includes gnunet-setup (graphical tool for configuration)
294 and @code{gnunet-fs-gtk} (graphical tool for file-sharing):
297 $ tar xvf gnunet-gtk-0.10.?.tar.gz
298 $ cd gnunet-gtk-0.10.?
299 $ ./configure --with-gnunet=/usr/local/
303 $ sudo ldconfig # just to be safe
306 Next, edit the file @file{/etc/gnunet.conf} to contain the following:
314 You may need to update your ld.so cache to include files installed in
315 @file{/usr/local/lib}: @code{ # ldconfig }.
317 Then, switch from user root to user gnunet to start the peer:
320 # su -s /bin/sh - gnunet
321 $ gnunet-arm -c /etc/gnunet.conf -s
324 You may also want to add the last line in the gnunet users @file{crontab}
325 prefixed with @code{@@reboot} so that it is executed whenever the system is
329 @@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s@
332 This will only start the system-wide GNUnet services. Type exit to get back
333 your root shell. Now, you need to configure the per-user part. For each
334 $USER on the system, run: @code{ # adduser $USER gnunet }.
336 to allow them to access the system-wide GNUnet services. Then, each
337 user should create a configuration file @file{~/.config/gnunet.conf}
344 DEFAULTSERVICES = gns
347 and start the per-user services using
350 $ gnunet-arm -c ~/.config/gnunet.conf -s@
353 Again, adding a @code{crontab} entry to autostart the peer is advised:@
355 @@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s@
358 Note that some GNUnet services (such as SOCKS5 proxies) may need a system-wide
359 TCP port for each user. For those services, systems with more than one user may
360 require each user to specify a different port number in their personal
363 Finally, the user should perform the basic initial setup for the GNU Name
364 System. This is done by running two commands:@
367 $ gnunet-gns-import.sh@
368 $ gnunet-gns-proxy-setup-ca@
371 The first generates the default zones, wheras the second setups the GNS
372 Certificate Authority with the user's browser. Now, to actiave GNS in the
373 normal DNS resolution process, you need to edit your @file{/etc/nsswitch.conf}
374 where you should find a line like this:
376 hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
380 The exact details may differ a bit, which is fine. Add the text
381 @emph{"gns [NOTFOUND=return]"} after @emph{"files"}:
384 hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
388 You might want to make sure that @file{/lib/libnss_gns.so.2} exists on your
389 system, it should have been created during the installation.
393 @node Build instructions for Ubuntu 12.04 using Git
394 @section Build instructions for Ubuntu 12.04 using Git
398 * Install the required build tools::
399 * Install libgcrypt 1.6 and libgpg-error::
400 * Install gnutls with DANE support::
402 * Install libmicrohttpd from Git::
403 * Install libextractor from Git::
404 * Install GNUnet dependencies::
406 * Install the GNUnet-gtk user interface from Git::
409 @node Install the required build tools
410 @subsection Install the required build tools
412 First, make sure Git is installed on your system:
415 $ sudo apt-get install git
418 Install the essential buildtools:
421 $ sudo apt-get install automake autopoint autoconf libtool
424 @node Install libgcrypt 1.6 and libgpg-error
425 @subsection Install libgcrypt 1.6 and libgpg-error
428 $ wget ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
429 $ tar xf libgpg-error-1.12.tar.bz2
430 $ cd libgpg-error-1.12
432 $ sudo make install ; cd ..
435 @node Install gnutls with DANE support
436 @subsection Install gnutls with DANE support
439 $ wget http://www.lysator.liu.se/~nisse/archive/nettle-2.7.1.tar.gz
440 $ tar xf nettle-2.7.1.tar.gz
443 $ sudo make install ; cd ..
447 $ wget https://www.nlnetlabs.nl/downloads/ldns/ldns-1.6.16.tar.gz
448 $ tar xf ldns-1.6.16.tar.gz
451 $ sudo make install ; cd ..
455 $ wget https://unbound.net/downloads/unbound-1.4.21.tar.gz
456 $ tar xf unbound-1.4.21.tar.gz
459 $ sudo make install ; cd ..
463 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.1/gnutls-3.1.17.tar.xz
464 $ tar xf gnutls-3.1.17.tar.xz
467 $ sudo make install ; cd ..
471 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
472 $ tar xf libgcrypt-1.6.0.tar.bz2
475 $ sudo make install ; cd ..
478 @node Install libgnurl
479 @subsection Install libgnurl
482 $ wget https://gnunet.org/sites/default/files/gnurl-7.34.0.tar.bz2
483 $ tar xf gnurl-7.34.0.tar.bz2
485 $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
486 --without-libmetalink --without-winidn --without-librtmp \
487 --without-nghttp2 --without-nss --without-cyassl \
488 --without-polarssl --without-ssl --without-winssl \
489 --without-darwinssl --disable-sspi --disable-ntlm-wb \
490 --disable-ldap --disable-rtsp --disable-dict --disable-telnet \
491 --disable-tftp --disable-pop3 --disable-imap --disable-smtp \
492 --disable-gopher --disable-file --disable-ftp
493 $ sudo make install ; cd ..
496 @node Install libmicrohttpd from Git
497 @subsection Install libmicrohttpd from Git
500 $ git clone https://gnunet.org/git/libmicrohttpd
504 $ sudo make install ; cd ..
507 @node Install libextractor from Git
508 @subsection Install libextractor from Git
510 Install libextractor dependencies:
513 $ sudo apt-get install zlib1g-dev libgsf-1-dev libmpeg2-4-dev \
514 libpoppler-dev libvorbis-dev libexiv2-dev libjpeg-dev \
515 libtiff-dev libgif-dev libvorbis-dev libflac-dev libsmf-dev \
522 $ git clone https://gnunet.org/git/libextractor
526 $ sudo make install ; cd ..
529 @node Install GNUnet dependencies
530 @subsection Install GNUnet dependencies
533 $ sudo apt-get install libidn11-dev libunistring-dev libglpk-dev \
534 libpulse-dev libbluetooth-dev libsqlite-dev
540 $ wget http://downloads.xiph.org/releases/opus/opus-1.1.tar.gz
541 $ tar xf opus-1.1.tar.gz
544 $ sudo make install ; cd ..
547 Choose one or more database backends:
551 $ sudo apt-get install libsqlite3-dev
555 $ sudo apt-get install libmysqlclient-dev
559 $ sudo apt-get install libpq-dev postgresql
565 @subsection Build GNUnet
570 * Configuring the installation path::
571 * Configuring the system::
572 * Installing components requiring sudo permission::
576 @node Configuring the installation path
577 @subsubsection Configuring the installation path
579 You can specify the location of the GNUnet installation by setting the prefix
580 when calling the configure script with @code{--prefix=DIRECTORY}
583 $ export PATH=$PATH:DIRECTORY/bin
586 @node Configuring the system
587 @subsubsection Configuring the system
589 Please make sure NOW that you have created a user and group 'gnunet'
590 and additionally a group 'gnunetdns':
593 $ sudo addgroup gnunet
594 $ sudo addgroup gnunetdns
595 $ sudo adduser gnunet
598 Each GNUnet user should be added to the 'gnunet' group (may
599 require fresh login to come into effect):
602 $ sudo useradd -G gnunet
605 @node Installing components requiring sudo permission
606 @subsubsection Installing components requiring sudo permission
608 Some components, like the nss plugin required for GNS, may require root
609 permissions. To allow these few components to be installed use:
612 $ ./configure --with-sudo
619 $ git clone https://gnunet.org/git/gnunet/
624 Use the required configure call including the optional installation prefix
625 PREFIX or the sudo permissions:
628 $ ./configure [ --with-sudo | --with-prefix=PREFIX ]
632 $ make; sudo make install
635 After installing it, you need to create an empty configuration file:
638 mkdir ~/.gnunet; touch ~/.gnunet/gnunet.conf
641 And finally you can start GNUnet with @code{$ gnunet-arm -s}.
643 @node Install the GNUnet-gtk user interface from Git
644 @subsection Install the GNUnet-gtk user interface from Git
650 $ sudo apt-get install libgtk-3-dev libunique-3.0-dev libgladeui-dev \
654 To build GNUnet (with an optional prefix)and execute:
657 $ git clone https://gnunet.org/git/gnunet-gtk/
660 $ ./configure [--prefix=PREFIX] --with-gnunet=DIRECTORY
661 $ make; sudo make install
664 @node Build Instructions for Microsoft Windows Platforms
665 @section Build Instructions for Microsoft Windows Platforms
668 * Introduction to building on MS Windows::
670 * Dependencies & Initial Setup::
671 * GNUnet Installation::
672 * Adjusting Windows for running and testing GNUnet::
673 * Building the GNUnet Installer::
674 * Using GNUnet with Netbeans on Windows::
677 @node Introduction to building on MS Windows
678 @subsection Introduction to building on MS Windows
681 This document is a guide to building GNUnet and its dependencies on Windows
682 platforms. GNUnet development is mostly done under Linux and especially SVN
683 checkouts may not build out of the box. We regret any inconvenience, and
684 if you have problems, please report them.
687 @subsection Requirements
689 The Howto is based upon a @strong{Windows Server 2008 32bit@strong{
690 Installation, @strong{sbuild} and thus a @uref{http://www.mingw.org/wiki/MSYS,
691 MSYS+MinGW} (W32-GCC-Compiler-Suite + Unix-like Userland) installation. sbuild
692 is a convenient set of scripts which creates a working msys/mingw installation
693 and installs most dependencies required for GNUnet. }}
695 As of the point of the creation of this Howto, GNUnet @strong{requires} a
696 Windows @strong{Server} 2003 or newer for full feature support. Windows Vista
697 and later will also work, but
698 @strong{non-server version can not run a VPN-Exit-Node} as the NAT features
699 have been removed as of Windows Vista.
701 @node Dependencies & Initial Setup
702 @subsection Dependencies & Initial Setup
708 Install a fresh version of @strong{Python 2.x}, even if you are using a x64-OS,
709 install a 32-bit version for use with sbuild. Python 3.0 currently is
713 Install your favorite @uref{http://code.google.com/p/tortoisegit/, GIT} &
714 @uref{http://tortoisesvn.net/, SVN}-clients.
717 You will also need some archive-manager like @uref{http://www.7-zip.org/, 7zip}.
720 Pull a copy of sbuild to a directory of your choice, which will be used in the
721 remainder of this guide. For now, we will use @file{c:\gnunet\sbuild\}
724 in @file{sbuild\src\mingw\mingw32-buildall.sh}, comment out the packages
725 @strong{gnunet-svn} and @strong{gnunet-gtk-svn}, as we don't want sbuild to
726 compile/install those for us.
729 Follow LRN's sbuild installation instructions.-
732 Please note that sbuild may (or will most likely) fail during installation,
733 thus you really HAVE to @strong{check the logfiles} created during the
734 installation process. Certain packages may fail to build initially due to
735 missing dependencies, thus you may have to
736 @strong{substitute those with binary-versions initially}. Later on once
737 dependencies are satisfied you can re-build the newer package versions.
739 @strong{It is normal that you may have to repeat this step multiple times and
740 there is no uniform way to fix all compile-time issues, as the build-process
741 of many of the dependencies installed are rather unstable on win32 and certain
742 releases may not even compile at all.}
744 Most dependencies for GNUnet have been set up by sbuild, thus we now should add
745 the @file{bin/} directories in your new msys and mingw installations to PATH.
746 You will want to create a backup of your finished msys-environment by now.
748 @node GNUnet Installation
749 @subsection GNUnet Installation
751 First, we need to launch our msys-shell, you can do this via
753 @file{C:\gnunet\sbuild\msys\msys.bat}
755 You might wish to take a look at this file and adjust some login-parameters to
756 your msys environment.
758 Also, sbuild added two pointpoints to your msys-environment, though those
759 might remain invisible:
764 /mingw, which will mount your mingw-directory from sbuild/mingw and the other one is
767 /src which contains all the installation sources sbuild just compiled.
770 Check out the current gnunet-sources (svn-head) from the gnunet-repository,
771 we will do this in your home directory:
773 @code{svn checkout https://gnunet.org/svn/gnunet/ ~/gnunet}
775 Now, we will first need to bootstrap the checked out installation and then
776 configure it accordingly.
781 STRIP=true CPPFLAGS="-DUSE_IPV6=1 -DW32_VEH" CFLAGS="$CFLAGS -g -O2" \
782 ./configure --prefix=/ --docdir=/share/doc/gnunet \
783 --with-libiconv-prefix=/mingw --with-libintl-prefix=/mingw \
784 --with-libcurl=/mingw --with-extractor=/mingw --with-sqlite=/mingw \
785 --with-microhttpd=/mingw --with-plibc=/mingw --enable-benchmarks \
786 --enable-expensivetests --enable-experimental --with-qrencode=/mingw \
787 --enable-silent-rules --enable-experimental 2>&1 | tee -a ./configure.log
790 The parameters above will configure for a reasonable gnunet installation to the
791 your msys-root directory. Depending on which features your would like to build
792 or you may need to specify additional dependencies. Sbuild installed most libs
793 into the /mingw subdirectory, so remember to prefix library locations with
796 Like on a unixoid system, you might want to use your home directory as prefix
797 for your own gnunet installation for development, without tainting the
798 buildenvironment. Just change the "prefix" parameter to point towards
801 Now it's time to compile gnunet as usual. Though this will take some time, so
802 you may fetch yourself a coffee or some Mate now...
808 @node Adjusting Windows for running and testing GNUnet
809 @subsection Adjusting Windows for running and testing GNUnet
811 Assuming the build succeeded and you
812 @strong{added the bin directory of your gnunet to PATH}, you can now use your
813 gnunet-installation as usual. Remember that UAC or the windows firewall may
814 popup initially, blocking further execution of gnunet until you acknowledge
817 You will also have to take the usual steps to get p2p software running properly
818 (port forwarding, ...), and gnunet will require administrative permissions as
819 it may even install a device-driver (in case you are using gnunet-vpn and/or
822 @node Building the GNUnet Installer
823 @subsection Building the GNUnet Installer
825 The GNUnet installer is made with @uref{http://nsis.sourceforge.net/, NSIS}
826 The installer script is located in @file{contrib\win} in the
829 @node Using GNUnet with Netbeans on Windows
830 @subsection Using GNUnet with Netbeans on Windows
834 @node Build instructions for Debian 7.5
835 @section Build instructions for Debian 7.5
838 These are the installation instructions for Debian 7.5. They were tested using
839 a minimal, fresh Debian 7.5 AMD64 installation without non-free software
840 (no contrib or non-free). By "minimal", we mean that during installation, we
841 did not select any desktop environment, servers or system utilities during the
842 "tasksel" step. Note that the packages and the dependencies that we will
843 install during this chapter take about 1.5 GB of disk space. Combined with
844 GNUnet and space for objects during compilation, you should not even attempt
845 this unless you have about 2.5 GB free after the minimal Debian installation.
846 Using these instructions to build a VM image is likely to require a minimum of
847 4-5 GB for the VM (as you will likely also want a desktop manager).
849 GNUnet's security model assumes that your @file{/home} directory is encrypted.
850 Thus, if possible, you should encrypt your home partition
851 (or per-user home directory).
853 Naturally, the exact details of the starting state for your installation
854 should not matter much. For example, if you selected any of those installation
855 groups you might simply already have some of the necessary packages installed.
856 We did this for testing, as this way we are less likely to forget to mention a
857 required package. Note that we will not install a desktop environment, but of
858 course you will need to install one to use GNUnet's graphical user interfaces.
859 Thus, it is suggested that you simply install the desktop environment of your
860 choice before beginning with the instructions.
868 * Installing packages::
869 * Installing dependencies from source::
870 * Installing GNUnet from source::
871 * But wait there is more!::
877 After any installation, you should begin by running
880 # apt-get update ; apt-get upgrade
883 to ensure that all of your packages are up-to-date. Note that the "#" is used
884 to indicate that you need to type in this command as "root"
885 (or prefix with "sudo"), whereas "$" is used to indicate typing in a command
889 @subsection Stable? Hah!
891 Yes, we said we start with a Debian 7.5 "stable" system. However, to reduce the
892 amount of compilation by hand, we will begin by allowing the installation of
893 packages from the testing and unstable distributions as well. We will stick to
894 "stable" packages where possible, but some packages will be taken from the
895 other distributions. Start by modifying @file{/etc/apt/sources.list} to contain
896 the following (possibly adjusted to point to your mirror of choice):
898 # These were there before:
899 deb http://ftp.de.debian.org/debian/ wheezy main
900 deb-src http://ftp.de.debian.org/debian/ wheezy main
901 deb http://security.debian.org/ wheezy/updates main
902 deb-src http://security.debian.org/ wheezy/updates main
903 deb http://ftp.de.debian.org/debian/ wheezy-updates main
904 deb-src http://ftp.de.debian.org/debian/ wheezy-updates main
906 # Add these lines (feel free to adjust the mirror):
907 deb http://ftp.de.debian.org/debian/ testing main
908 deb http://ftp.de.debian.org/debian/ unstable main
911 The next step is to create/edit your @file{/etc/apt/preferences} file to look
916 Pin: release a=stable,n=wheezy
920 Pin: release o=Debian,a=testing
924 Pin: release o=Debian,a=unstable
928 You can read more about Apt Preferences here and here. Note that other pinnings
929 are likely to also work for GNUnet, the key thing is that you need some
930 packages from unstable (as shown below). However, as unstable is unlikely to
931 be comprehensive (missing packages) or might be problematic (crashing packages),
932 you probably want others from stable and/or testing.
935 @subsection Update again
944 to ensure that all your new distribution indices are downloaded, and that your
945 pinning is correct: the upgrade step should cause no changes at all.
947 @node Installing packages
948 @subsection Installing packages
950 We begin by installing a few Debian packages from stable:@
953 # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \
954 libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev \
955 texlive libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev \
956 libbz2-dev libexiv2-dev libflac-dev libgif-dev libglib2.0-dev \
957 libgtk-3-dev libmagic-dev libjpeg8-dev libmpeg2-4-dev libmp4v2-dev \
958 librpm-dev libsmf-dev libtidy-dev libtiff5-dev libvorbis-dev \
959 libogg-dev zlib1g-dev g++ gettext libgsf-1-dev libunbound-dev \
960 libqrencode-dev libgladeui-dev nasm texlive-latex-extra \
961 libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev
964 After that, we install a few more packages from unstable:@
967 # apt-get install -t unstable nettle-dev libgstreamer1.0-dev \
968 gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
969 libgstreamer-plugins-base1.0-dev
972 @node Installing dependencies from source
973 @subsection Installing dependencies from source
975 Next, we need to install a few dependencies from source. You might want to do
976 this as a "normal" user and only run the @code{make install} steps as root
977 (hence the @code{sudo} in the commands below). Also, you do this from any
978 directory. We begin by downloading all dependencies, then extracting the
979 sources, and finally compiling and installing the libraries:@
982 $ wget https://libav.org/releases/libav-9.10.tar.xz
983 $ wget http://ftp.gnu.org/gnu/libextractor/libextractor-1.3.tar.gz
984 $ wget ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
985 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
986 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.2/gnutls-3.2.7.tar.xz
987 $ wget http://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.33.tar.gz
988 $ wget https://gnunet.org/sites/default/files/gnurl-7.34.0.tar.bz2
989 $ tar xvf libextractor-1.3.tar.gz
990 $ tar xvf libgpg-error-1.12.tar.bz2
991 $ tar xvf libgcrypt-1.6.0.tar.bz2
992 $ tar xvf gnutls-3.2.7.tar.xz
993 $ tar xvf libmicrohttpd-0.9.33.tar.gz
994 $ tar xvf gnurl-7.34.0.tar.bz2
995 $ cd libav-0.9 ; ./configure --enable-shared;
996 $ make; sudo make install; cd ..
997 $ cd libextractor-1.3 ; ./configure;
998 $ make ; sudo make install; cd ..
999 $ cd libgpg-error-1.12; ./configure;
1000 $ make ; sudo make install; cd ..
1001 $ cd libgcrypt-1.6.0; ./configure --with-gpg-error-prefix=/usr/local;
1002 $ make ; sudo make install ; cd ..
1003 $ cd gnutls-3.2.7 ; ./configure;
1004 $ make ; sudo make install ; cd ..
1005 $ cd libmicrohttpd-0.9.33; ./configure;
1006 $ make ; sudo make install ; cd ..
1008 $ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \
1009 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \
1010 --without-nss --without-cyassl --without-polarssl --without-ssl \
1011 --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \
1012 --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \
1013 --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \
1015 $ make ; sudo make install; cd ..
1018 @node Installing GNUnet from source
1019 @subsection Installing GNUnet from source
1022 For this, simply follow the generic installation instructions from
1025 @node But wait there is more!
1026 @subsection But wait there is more!
1028 So far, we installed all of the packages and dependencies required to ensure
1029 that all of GNUnet would be built. However, while for example the plugins to
1030 interact with the MySQL or Postgres databases have been created, we did not
1031 actually install or configure those databases. Thus, you will need to install
1032 and configure those databases or stick with the default Sqlite database.
1033 Sqlite is usually fine for most applications, but MySQL can offer better
1034 performance and Postgres better resillience.
1037 @node Installing GNUnet from Git on Ubuntu 14.4
1038 @section Installing GNUnet from Git on Ubuntu 14.4
1040 @strong{Install the required build tools:}
1041 @code{ $ sudo apt-get install git automake autopoint autoconf }
1043 @strong{Install the required dependencies}
1045 $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \
1046 libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \
1047 libmicrohttpd-dev libgnutls28-dev
1050 @strong{Choose one or more database backends}
1054 $ sudo apt-get install libsqlite3-dev
1058 $ sudo apt-get install libmysqlclient-dev
1062 $ sudo apt-get install libpq-dev postgresql
1065 @strong{Install the optional dependencies for gnunet-conversation:}
1068 $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev
1071 @strong{Install the libgrypt 1.6.1:}
1074 $ sudo apt-get install libgcrypt20-dev
1076 For Ubuntu older 14.04:
1078 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2
1079 $ tar xf libgcrypt-1.6.1.tar.bz2
1080 $ cd libgcrypt-1.6.1
1085 @strong{Install libgnurl}
1087 $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2
1088 $ tar xf gnurl-7.35.0.tar.bz2
1090 $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
1091 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \
1092 --without-nss --without-cyassl --without-polarssl --without-ssl \
1093 --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \
1094 --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \
1095 --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \
1101 @strong{Install GNUnet}
1103 $ git clone https://gnunet.org/git/gnunet/
1113 Install to a different directory:@
1117 Have sudo permission, but do not want to compile as root:@
1121 Want debug message enabled:@
1122 -- enable-logging=verbose
1127 $ ./configure [ --with-sudo | --prefix=PREFIX | --- enable-logging=verbose]@
1128 $ make; sudo make install@
1131 After installing it, you need to create an empty configuration file:@
1132 @code{touch ~/.config/gnunet.conf}
1134 And finally you can start GNUnet with@
1135 @code{$ gnunet-arm -s}
1137 @node Build instructions for Debian 8
1138 @section Build instructions for Debian 8
1140 These are the installation instructions for Debian 8. They were tested using a
1141 fresh Debian 8 AMD64 installation without non-free software (no contrib or
1142 non-free). During installation, I only selected "lxde" for the desktop
1143 environment. Note that the packages and the dependencies that we will install
1144 during this chapter take about 1.5 GB of disk space. Combined with GNUnet and
1145 space for objects during compilation, you should not even attempt this unless
1146 you have about 2.5 GB free after the Debian installation. Using these
1147 instructions to build a VM image is likely to require a minimum of 4-5 GB for
1148 the VM (as you will likely also want a desktop manager).
1150 GNUnet's security model assumes that your @code{/home} directory is encrypted.
1151 Thus, if possible, you should encrypt your entire disk, or at least just your
1152 home partition (or per-user home directory).
1154 Naturally, the exact details of the starting state for your installation should
1155 not matter much. For example, if you selected any of those installation groups
1156 you might simply already have some of the necessary packages installed. Thus,
1157 it is suggested that you simply install the desktop environment of your choice
1158 before beginning with the instructions.
1163 * Installing Debian Packages::
1164 * Installing Dependencies from Source2::
1165 * Installing GNUnet from Source2::
1166 * But wait (again) there is more!::
1170 @subsection Update Debian
1172 After any installation, you should begin by running@
1177 to ensure that all of your packages are up-to-date. Note that the "#" is used
1178 to indicate that you need to type in this command as "root" (or prefix with
1179 "sudo"), whereas "$" is used to indicate typing in a command as a normal
1182 @node Installing Debian Packages
1183 @subsection Installing Debian Packages
1185 We begin by installing a few Debian packages from stable:@
1187 # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \
1188 libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \
1189 libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \
1190 libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \
1191 libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext libgsf-1-dev \
1192 libunbound-dev libqrencode-dev libgladeui-dev nasm texlive-latex-extra \
1193 libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev \
1194 gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
1195 libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev libgcrypt20-dev \
1199 @node Installing Dependencies from Source2
1200 @subsection Installing Dependencies from Source2
1202 Yes, we said we start with a Debian 8 "stable" system, but because Debian
1203 linked GnuTLS without support for DANE, we need to compile a few things, in
1204 addition to GNUnet, still by hand. Yes, you can run GNUnet using the respective
1205 Debian packages, but then you will not get DANE support.
1207 Next, we need to install a few dependencies from source. You might want to do
1208 this as a "normal" user and only run the @code{make install} steps as root
1209 (hence the @code{sudo} in the commands below). Also, you do this from any
1210 directory. We begin by downloading all dependencies, then extracting the
1211 sources, and finally compiling and installing the libraries:@
1214 $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz@
1215 $ wget https://gnunet.org/sites/default/files/gnurl-7.40.0.tar.bz2@
1216 $ tar xvf gnutls-3.3.12.tar.xz@
1217 $ tar xvf gnurl-7.40.0.tar.bz2@
1218 $ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd ..@
1220 $ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \
1221 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \
1222 --without-nss --without-cyassl --without-polarssl --without-ssl \
1223 --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \
1224 --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \
1225 --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \
1226 --disable-ftp --disable-smb
1227 $ make ; sudo make install; cd ..@
1230 @node Installing GNUnet from Source2
1231 @subsection Installing GNUnet from Source2
1233 For this, simply follow the generic installation instructions from@
1236 @node But wait (again) there is more!
1237 @subsection But wait (again) there is more!
1239 So far, we installed all of the packages and dependencies required to ensure
1240 that all of GNUnet would be built. However, while for example the plugins to
1241 interact with the MySQL or Postgres databases have been created, we did not
1242 actually install or configure those databases. Thus, you will need to install
1243 and configure those databases or stick with the default Sqlite database. Sqlite
1244 is usually fine for most applications, but MySQL can offer better performance
1245 and Postgres better resillience.
1247 @node Outdated build instructions for previous revisions
1248 @section Outdated build instructions for previous revisions
1250 This chapter contains a collection of outdated, older installation guides. They
1251 are mostly intended to serve as a starting point for writing up-to-date
1252 instructions and should not be expected to work for GNUnet 0.10.x.
1253 A set of older installation instructions can also be found in the
1254 @file{doc/outdated-and-old-installation-instructions.txt} in the source
1255 of GNUnet. This file covers old instructions which no longer receive
1256 security updates or any kind of support.
1260 * Installing GNUnet 0.10.1 on Ubuntu 14.04::
1261 * Building GLPK for MinGW::
1262 * GUI build instructions for Ubuntu 12.04 using Subversion::
1263 * Installation with gnunet-update::
1264 * Instructions for Microsoft Windows Platforms (Old)::
1268 @node Installing GNUnet 0.10.1 on Ubuntu 14.04
1269 @subsection Installing GNUnet 0.10.1 on Ubuntu 14.04
1271 Install the required dependencies@
1274 $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \
1275 libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \
1276 libmicrohttpd-dev libgnutls28-dev
1279 Choose one or more database backends@
1282 $ sudo apt-get install libsqlite3-dev@
1286 $ sudo apt-get install libmysqlclient-dev@
1290 $ sudo apt-get install libpq-dev postgresql@
1293 Install the optional dependencies for gnunet-conversation:@
1295 $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev@
1298 Install the libgrypt 1.6:@
1300 @code{$ sudo apt-get install libgcrypt20-dev}@
1301 For Ubuntu older 14.04:@
1302 @code{$ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2@
1303 $ tar xf libgcrypt-1.6.1.tar.bz2@
1304 $ cd libgcrypt-1.6.1@
1306 $ sudo make install@
1311 $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2@
1312 $ tar xf gnurl-7.35.0.tar.bz2@
1314 $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
1315 --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \
1316 --without-nss --without-cyassl --without-polarssl --without-ssl \
1317 --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \
1318 --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \
1319 --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \
1321 $ sudo make install@
1327 $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz@
1328 $ tar xf gnunet-0.10.1.tar.gz@
1336 Install to a different directory:@
1340 Have sudo permission, but do not want to compile as root:@
1344 Want debug message enabled:@
1345 -- enable-logging=verbose
1349 $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose]@
1350 $ make; sudo make install@
1353 After installing it, you need to create an empty configuration file:@
1354 @code{touch ~/.config/gnunet.conf}
1356 And finally you can start GNUnet with@
1357 @code{$ gnunet-arm -s}
1359 @node Building GLPK for MinGW
1360 @subsection Building GLPK for MinGW
1362 GNUnet now requires the GNU Linear Programming Kit (GLPK). Since there's is no
1363 package you can install with @code{mingw-get} you have to compile it from
1369 Download the latest version from http://ftp.gnu.org/gnu/glpk/
1372 Unzip it using your favourite unzipper@
1376 change to the respective directory
1379 @code{./configure '--build=i686-pc-mingw32'}
1382 run @code{make install check }
1384 MinGW does not automatically detect the correct buildtype so you have to
1389 @node GUI build instructions for Ubuntu 12.04 using Subversion
1390 @subsection GUI build instructions for Ubuntu 12.04 using Subversion
1392 After installing GNUnet you can continue installing the GNUnet GUI tools:
1394 First, install the required dependencies:
1397 $ sudo apt-get install libgladeui-dev libqrencode-dev@
1400 Please ensure that the GNUnet shared libraries can be found by the linker. If
1401 you installed GNUnet libraries in a non standard path (say
1402 GNUNET_PREFIX=/usr/local/lib/), you can
1407 set the environmental variable permanently to@
1408 @code{LD_LIBRARY_PATH=$GNUNET_PREFIX}
1411 or add @code{$GNUNET_PREFIX} to @code{/etc/ld.so.conf}
1415 Now you can checkout and compile the GNUnet GUI tools@
1417 $ svn co https://gnunet.org/svn/gnunet-gtk@
1420 $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/..@
1424 @node Installation with gnunet-update
1425 @subsection Installation with gnunet-update
1427 gnunet-update project is an effort to introduce updates to GNUnet
1428 installations. An interesting to-be-implemented-feature of gnunet-update is
1429 that these updates are propagated through GNUnet's peer-to-peer network. More
1430 information about gnunet-update can be found at
1431 https://gnunet.org/svn/gnunet-update/README.
1433 While the project is still under development, we have implemented the following
1434 features which we believe may be helpful for users and we would like them to be
1440 Packaging GNUnet installation along with its run-time dependencies into update
1444 Installing update packages into compatible hosts
1447 Updating an existing installation (which had been installed by gnunet-update)
1451 The above said features of gnunet-update are currently available for testing on
1454 The following is a guide to help you get started with gnunet-update. It shows
1455 you how to install the testing binary packages of GNUnet 0.9.1 we have at
1456 https://gnunet.org/install/
1458 gnunet-update needs the following:
1462 python ( 2.6 or above)
1472 Checkout gnunet-update:@
1474 $ svn checkout -r24905 https://gnunet.org/svn/gnunet-update@
1477 For security reasons, all packages released for gnunet-update from us are
1478 signed with the key at https://gnunet.org/install/key.txt You would need to
1479 import this key into your gpg key ring. gnunet-update uses this key to verify
1480 the integrity of the packages it installs@
1482 $ gpg --recv-keys 7C613D78@
1485 Download the packages relevant to your architecture (currently I have access to
1486 GNU/Linux machines on x86_64 and i686, so only two for now, hopefully more
1487 later) from https://gnunet.org/install/.
1489 To install the downloaded package into the directory /foo:
1492 gnunet-update/bin/gnunet-update install downloaded/package /foo@
1495 The installer reports the directories into which shared libraries and
1496 dependencies have been installed. You may need to add the reported shared
1497 library installation paths to LD_LIBRARY_PATH before you start running any
1500 Please report bugs at https://gnunet.org/bugs/ under the project
1503 @node Instructions for Microsoft Windows Platforms (Old)
1504 @subsection Instructions for Microsoft Windows Platforms (Old)
1506 This document is a DEPRECATED installation guide for gnunet on windows. It will
1507 not work for recent gnunet versions, but maybe it will be of some use if
1510 The Windows build uses a UNIX emulator for Windows,
1511 @uref{http://www.mingw.org/, MinGW}, to build the executable modules. These
1512 modules run natively on Windows and do not require additional emulation
1513 software besides the usual dependencies.
1515 GNUnet development is mostly done under Linux and especially SVN checkouts may
1516 not build out of the box. We regret any inconvenience, and if you have
1517 problems, please report them.
1522 * Hardware and OS requirements::
1523 * Software installation::
1524 * Building libextractor and GNUnet::
1529 @node Hardware and OS requirements
1530 @subsubsection Hardware and OS requirements
1535 Pentium II or equivalent processor, 350 MHz or better
1541 600 MB free disk space
1544 Windows 2000 or Windows XP are recommended
1547 @node Software installation
1548 @subsubsection Software installation
1553 @strong{Compression software}@
1555 The software packages GNUnet depends on are usually compressed using UNIX
1556 tools like tar, gzip and bzip2.@ If you do not already have an utility that is
1557 able to extract such archives, get @uref{http://www.7-zip.org/, 7-Zip}.
1560 @strong{UNIX environment}@
1562 The MinGW project provides the compiler toolchain that is used to build
1563 GNUnet.@ Get the following packages from
1564 @uref{http://sourceforge.net/projects/mingw/files/, the MinGW project}:
1578 MSYS Developer Tool Kit (msysDTK)
1581 MSYS Developer Tool Kit - msys-autoconf (bin)
1584 MSYS Developer Tool Kit - msys-automake (bin)
1612 Install MSYS (to c:\mingw, for example.)@
1613 Do @strong{not} use spaces in the pathname (c:\program files\mingw).
1616 Install MinGW runtime, utilities and GCC to a subdirectory (to c:\mingw\mingw,
1620 Install the Development Kit to the MSYS directory (c:\mingw)
1623 Create a batch file bash.bat in your MSYS directory with the files:@
1630 This batch file opens a shell which is used to invoke the build processes..@
1631 MinGW's standard shell (msys.bat) is not suitable because it opens a separate
1632 console window@ On Vista, bash.bat needs to be run as administrator.
1635 Start bash.sh and rename (c:\mingw\mingw\)lib\libstdc++.la to avoid problems:@
1638 mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken
1643 Unpack the Windows API to the MinGW directory (c:\mingw\mingw\) and remove the
1644 declaration of DATADIR from (c:\mingw\mingw\)include\objidl.h (lines 55-58)
1647 Unpack autoconf, automake to the MSYS directory (c:\mingw)
1650 Install all other packages to the MinGW directory (c:\mingw\mingw\)
1655 @strong{GNU Libtool}@
1657 GNU Libtool is required to use shared libraries.@
1659 Get the prebuilt package from here and unpack it to the MinGW directory
1665 GNUnet uses the portable POSIX thread library for multi-threading..@
1671 Save @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86
1672 /libpthreadGC2.a, libpthreadGC2.a} (x86) or @uref{ftp://sources.redhat.c
1673 om/pub/pthreads-win32/dll-latest/lib/x64/libpthreadGC2.a, libpthreadGC2.
1674 a} (x64) as libpthread.a into the lib directory (c:\mingw\mingw\lib\libpt
1678 Save @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86
1679 /pthreadGC2.dll, pthreadGC2.dll} (x86) or @uref{ftp://sources.redhat.c
1680 om/pub/pthreads-win32/dll-latest/lib/x64/pthreadGC2.dll, libpthreadGC2.a}
1681 (x64) into the MinGW bin directory (c:\mingw\mingw\bin)
1684 Download all header files from @uref{ftp://sources.redhat.com/pub/pthread
1685 s-win32/dll-latest/include/, include/} to the @file{include} directory
1686 (c:\mingw\mingw\include)
1694 GNUnet uses the GNU Multiple Precision library for special cryptographic operations.@
1696 Get the GMP binary package from the
1697 @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and
1698 unpack it to the MinGW directory (c:\mingw\mingw)
1701 @strong{GNU Gettext}@
1703 GNU gettext is used to provide national language support.@
1705 Get the prebuilt package from hereand unpack it to the MinGW directory (c:\mingw\mingw)
1710 GNU Libiconv is used for character encoding conversion.@
1712 Get the prebuilt package from here and unpack it to the MinGW directory (c:\mingw\mingw)
1717 GNUnet uses the SQLite database to store data.@
1719 Get the prebuilt binary from here and unpack it to your MinGW directory.
1721 @item @strong{MySQL}@
1722 As an alternative to SQLite, GNUnet also supports MySQL.
1726 @item Get the binary installer from the
1727 @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project}
1728 (version 4.1), install it and follow the instructions in README.mysql.
1730 @item Create a temporary build directory (c:\mysql)
1732 @item Copy the directories include\ and lib\ from the MySQL directory to
1735 @item Get the patches from
1736 @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and
1737 @uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the
1738 latter is only required for MySQL
1744 @item Move lib\opt\libmysql.dll to lib\libmysql.dll
1746 @item Change to lib\ and create an import library:@
1749 dlltool --input-def ../include/libmySQL.def --dllname libmysql.dll
1750 --output-lib libmysqlclient.a -k
1753 @item Copy include\* to include\mysql\
1755 @item Pass "--with-mysql=/c/mysql" to ./configure and copy libmysql.dll
1756 to your PATH or GNUnet's @file{bin} directory
1763 gnunet-gtk and libextractor depend on GTK.@
1765 Get the the binary and developer packages of atk, glib, gtk, iconv,
1766 gettext-runtime, pango from
1767 @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack it to the
1768 MinGW directory (c:\mingw\mingw)@
1770 Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and libpng
1771 and unpack them to the MinGW directory (c:\mingw\mingw)@
1773 Here is an all-in-one package for
1774 @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies}.
1775 Do not overwrite any existing files!
1780 gnunet-gtk and and gnunet-setup were created using this interface builder
1786 Get the Glade and libglade (-bin and -devel) packages (without GTK!) from
1787 @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack it to
1788 the MinGW directory (c:\mingw\mingw)
1791 Get libxml from here and unpack it to the MinGW
1792 directory (c:\mingw\mingw).
1799 libextractor requires zLib to decompress some file formats. GNUnet uses it
1800 to (de)compress meta-data.@
1802 Get zLib from here (Signature) and unpack it to the
1803 MinGW directory (c:\mingw\mingw)
1808 libextractor also requires Bzip2 to decompress some file formats.@
1810 Get Bzip2 (binary and developer package) from
1811 @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and
1812 unpack it to the MinGW directory (c:\mingw\mingw)
1817 Libgcrypt provides the cryptographic functions used by GNUnet@
1819 Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here},
1820 compile and place it in the MinGW directory (c:\mingw\mingw). Currently
1821 you need at least version 1.4.2 to compile GNUnet.
1826 PlibC emulates Unix functions under Windows.@
1828 Get PlibC from here and unpack it to the MinGW
1829 directory (c:\mingw\mingw)
1832 @strong{OGG Vorbis}@
1834 OGG Vorbis is used to extract meta-data from .ogg files@
1837 @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg}
1839 @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis}
1841 @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build}
1842 and unpack them to the MinGW directory (c:\mingw\mingw)
1847 (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data@
1850 @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2}
1851 and unpack it to the MSYS directory (c:\mingw)
1854 @node Building libextractor and GNUnet
1855 @subsubsection Building libextractor and GNUnet
1857 Before you compile libextractor or GNUnet, be sure to set PKG_CONFIG_PATH:
1860 export PKG_CONFIG_PATH=/mingw/lib/pkgconfig
1864 See Installation for basic instructions on building libextractor
1865 and GNUnet. By default, all modules that are created in this way contain
1866 debug information and are quite large. To compile release versions (small
1867 and fast) set the variable CFLAGS:
1870 export CFLAGS='-O2 -march=pentium -fomit-frame-pointer'
1871 ./configure --prefix=$HOME --with-extractor=$HOME
1875 @subsubsection Installer
1877 The GNUnet installer is made with
1878 @uref{http://nsis.sourceforge.net/, NSIS}. The installer script is
1879 located in @file{contrib\win} in the GNUnet source tree.
1882 @subsubsection Source
1884 The sources of all dependencies are available here.
1886 @node Portable GNUnet
1887 @section Portable GNUnet
1889 Quick instructions on how to use the most recent GNUnet on most GNU/Linux
1892 Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian
1893 and CentOS 6, but it should work on almost any GNU/Linux distribution.
1894 More in-detail information can be found in the handbook.
1900 * Download & set up gnunet-update::
1905 @subsection Prerequisites
1907 Open a terminal and paste this line into it to install all required tools
1909 @code{sudo apt-get install python-gpgme subversion}
1911 @node Download & set up gnunet-update
1912 @subsection Download & set up gnunet-update
1914 The following command will download a working version of gnunet-update
1915 with the subversion tool and import the public key which is needed for
1919 svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update
1921 gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78
1924 @node Install GNUnet
1925 @subsection Install GNUnet
1927 Download and install GNUnet binaries which can be found here and set
1931 wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz
1932 ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~
1933 echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment
1934 echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \
1935 /etc/ld.so.conf.d/gnunet.conf > /dev/null
1939 You may need to re-login once after executing these last commands
1941 That's it, GNUnet is installed in your home directory now. GNUnet can be
1942 configured and afterwards started by executing @code{gnunet-arm -s}.
1944 @node The graphical configuration interface
1945 @section The graphical configuration interface
1947 If you also would like to use gnunet-gtk and gnunet-setup (highly
1948 recommended for beginners), do:
1951 wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz
1952 sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~
1956 Now you can run @code{gnunet-setup} for easy configuration of your
1960 * Configuring your peer::
1961 * Configuring the Friend-to-Friend (F2F) mode::
1962 * Configuring the hostlist to bootstrap::
1963 * Configuration of the HOSTLIST proxy settings::
1964 * Configuring your peer to provide a hostlist ::
1965 * Configuring the datastore::
1966 * Configuring the MySQL database::
1967 * Reasons for using MySQL::
1968 * Reasons for not using MySQL::
1969 * Setup Instructions::
1971 * Performance Tuning::
1972 * Setup for running Testcases::
1973 * Configuring the Postgres database::
1974 * Reasons to use Postgres::
1975 * Reasons not to use Postgres::
1976 * Manual setup instructions::
1977 * Testing the setup manually::
1978 * Configuring the datacache::
1979 * Configuring the file-sharing service::
1980 * Configuring logging::
1981 * Configuring the transport service and plugins::
1982 * Configuring the wlan transport plugin::
1983 * Configuring HTTP(S) reverse proxy functionality using Apache or nginx::
1984 * Blacklisting peers::
1985 * Configuration of the HTTP and HTTPS transport plugins::
1986 * Configuring the GNU Name System::
1987 * Configuring the GNUnet VPN::
1988 * Bandwidth Configuration::
1990 * Peer configuration for distributions::
1993 @node Configuring your peer
1994 @subsection Configuring your peer
1996 This chapter will describe the various configuration options in GNUnet.
1998 The easiest way to configure your peer is to use the gnunet-setup tool.
1999 gnunet-setup is part of the gnunet-gtk download. You might have to
2000 install it separately.
2002 Many of the specific sections from this chapter actually are linked from
2003 within gnunet-setup to help you while using the setup tool.
2005 While you can also configure your peer by editing the configuration
2006 file by hand, this is not recommended for anyone except for developers.
2009 @node Configuring the Friend-to-Friend (F2F) mode
2010 @subsection Configuring the Friend-to-Friend (F2F) mode
2012 GNUnet knows three basic modes of operation. In standard "peer-to-peer"
2013 mode, your peer will connect to any peer. In the pure "friend-to-friend"
2014 mode, your peer will ONLY connect to peers from a list of friends
2015 specified in the configuration.
2016 Finally, in mixed mode, GNUnet will only connect to arbitrary peers if it
2017 has at least a specified number of connections to friends.
2019 When configuring any of the F2F modes, you first need to create a file
2020 with the peer identities of your friends. Ask your friends to run
2023 $ gnunet-peerinfo -sq
2027 The output of this command needs to be added to your friends file, which
2028 is simply a plain text file with one line per friend with the output from
2031 You then specify the location of your friends file in the "FRIENDS"
2032 option of the "topology" section.
2034 Once you have created the friends file, you can tell GNUnet to only
2035 connect to your friends by setting the "FRIENDS-ONLY" option (again in
2036 the "topology" section) to YES.
2038 If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a
2039 minimum number of friends to have (before connecting to arbitrary peers)
2040 under the "MINIMUM-FRIENDS" option.
2042 If you want to operate in normal P2P-only mode, simply set
2043 "MINIMUM-FRIENDS" to zero and "FRIENDS_ONLY" to NO. This is the default.
2045 @node Configuring the hostlist to bootstrap
2046 @subsection Configuring the hostlist to bootstrap
2048 After installing the software you need to get connected to the GNUnet
2049 network. The configuration file included in your download is already
2050 configured to connect you to the GNUnet network.
2051 In this section the relevant configuration settings are explained.
2053 To get an initial connection to the GNUnet network and to get to know
2054 peers already connected to the network you can use the so called
2056 These servers can give you a list of peers connected to the network.
2057 To use these bootstrap servers you have to configure the hostlist daemon
2058 to activate bootstrapping.
2060 To activate bootstrapping edit your configuration file and edit the
2061 @code{[hostlist]}-section. You have to set the argument "-b" in the
2069 Additionally you have to specify which server you want to use.
2070 The default bootstrapping server is
2071 "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}".
2072 [^] To set the server you have to edit the line "SERVERS" in the hostlist
2073 section. To use the default server you should set the lines to
2076 SERVERS = http://v10.gnunet.org/hostlist [^]
2080 To use bootstrapping your configuration file should include these lines:
2085 SERVERS = http://v10.gnunet.org/hostlist [^]
2089 Besides using bootstrap servers you can configure your GNUnet peer to
2090 recieve hostlist advertisements.
2091 Peers offering hostlists to other peers can send advertisement messages
2092 to peers that connect to them. If you configure your peer to receive these
2093 messages, your peer can download these lists and connect to the peers
2094 included. These lists are persistent, which means that they are saved to
2095 your hard disk regularly and are loaded during startup.
2097 To activate hostlist learning you have to add the "-e" switch to the
2098 OPTIONS line in the hostlist section:
2106 Furthermore you can specify in which file the lists are saved. To save the
2107 lists in the file "hostlists.file" just add the line:
2110 HOSTLISTFILE = hostlists.file
2114 Best practice is to activate both bootstrapping and hostlist learning.
2115 So your configuration file should include these lines:
2121 SERVERS = http://v10.gnunet.org/hostlist [^]
2122 HOSTLISTFILE = $SERVICEHOME/hostlists.file
2125 @node Configuration of the HOSTLIST proxy settings
2126 @subsection Configuration of the HOSTLIST proxy settings
2128 The hostlist client can be configured to use a proxy to connect to the
2130 This functionality can be configured in the configuration file directly
2131 or using the gnunet-setup tool.
2133 The hostlist client supports the following proxy types at the moment:
2136 @item HTTP and HTTP 1.0 only proxy
2137 @item SOCKS 4/4a/5/5 with hostname
2140 In addition authentication at the proxy with username and password can be
2143 To configure proxy support for the hostlist client in the gnunet-setup
2144 tool, select the "hostlist" tab and select the appropriate proxy type.
2145 The hostname or IP address (including port if required) has to be entered
2146 in the "Proxy hostname" textbox. If required, enter username and password
2147 in the "Proxy username" and "Proxy password" boxes.
2148 Be aware that these information will be stored in the configuration in
2151 To configure these options directly in the configuration, you can
2152 configure the following settings in the
2153 @code{[hostlist]} section of the configuration:
2156 # Type of proxy server,@
2157 # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME@
2161 # Hostname or IP of proxy server@
2163 # User name for proxy server@
2165 # User password for proxy server@
2169 @node Configuring your peer to provide a hostlist
2170 @subsection Configuring your peer to provide a hostlist
2172 If you operate a peer permanently connected to GNUnet you can configure
2173 your peer to act as a hostlist server, providing other peers the list of
2176 Yor server can act as a bootstrap server and peers needing to obtain a
2177 list of peers can contact him to download this list.
2178 To download this hostlist the peer uses HTTP.
2179 For this reason you have to build your peer with libcurl and microhttpd
2180 support. How you build your peer with this options can be found here:
2181 @uref{https://gnunet.org/generic_installation}
2183 To configure your peer to act as a bootstrap server you have to add the
2184 "@code{-p}" option to OPTIONS in the @code{[hostlist]} section of your
2185 configuration file. Besides that you have to specify a port number for
2186 the http server. In conclusion you have to add the following lines:
2195 If your peer acts as a bootstrap server other peers should know about
2196 that. You can advertise the hostlist your are providing to other peers.
2197 Peers connecting to your peer will get a message containing an
2198 advertisement for your hostlist and the URL where it can be downloaded.
2199 If this peer is in learning mode, it will test the hostlist and, in the
2200 case it can obtain the list successfully, it will save it for
2203 To activate hostlist advertisement on your peer, you have to set the
2204 following lines in your configuration file:
2208 EXTERNAL_DNS_NAME = example.org
2214 With this configuration your peer will a act as a bootstrap server and
2215 advertise this hostlist to other peers connecting to him. The URL used to
2216 download the list will be
2217 @code{@uref{http://example.org:12981/, http://example.org:12981/}}.
2221 @item The hostlist is not human readable, so you should not try to
2222 download it using your webbrowser. Just point your GNUnet peer to the
2224 @item Advertising without providing a hostlist does not make sense and
2228 @node Configuring the datastore
2229 @subsection Configuring the datastore
2231 The datastore is what GNUnet uses to for long-term storage of file-sharing
2232 data. Note that long-term does not mean 'forever' since content does have
2233 an expiration date, and of course storage space is finite (and hence
2234 sometimes content may have to be discarded).
2236 Use the "QUOTA" option to specify how many bytes of storage space you are
2237 willing to dedicate to GNUnet.
2239 In addition to specifying the maximum space GNUnet is allowed to use for
2240 the datastore, you need to specify which database GNUnet should use to do
2241 so. Currently, you have the choice between sqLite, MySQL and Postgres.
2243 @node Configuring the MySQL database
2244 @subsection Configuring the MySQL database
2246 This section describes how to setup the MySQL database for GNUnet.
2248 Note that the mysql plugin does NOT work with mysql before 4.1 since we
2249 need prepared statements.
2250 We are generally testing the code against MySQL 5.1 at this point.
2252 @node Reasons for using MySQL
2253 @subsection Reasons for using MySQL
2258 On up-to-date hardware where mysql can be used comfortably, this module
2259 will have better performance than the other database choices (according
2262 @item Its often possible to recover the mysql database from internal
2263 inconsistencies. Some of the other databases do not support repair.
2266 @node Reasons for not using MySQL
2267 @subsection Reasons for not using MySQL
2270 @item Memory usage (likely not an issue if you have more than 1 GB)
2271 @item Complex manual setup
2274 @node Setup Instructions
2275 @subsection Setup Instructions
2278 @item In @code{gnunet.conf} set in section "DATASTORE" the value for
2279 "DATABASE" to "mysql".
2280 @item Access mysql as root:@
2287 and issue the following commands, replacing $USER with the username
2288 that will be running gnunet-arm (so typically "gnunet"):
2291 CREATE DATABASE gnunet;
2292 GRANT select,insert,update,delete,create,alter,drop,create temporary tables
2293 ON gnunet.* TO $USER@@localhost;
2294 SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like');
2299 In the $HOME directory of $USER, create a ".my.cnf" file with the
2305 password=$the_password_you_like
2310 Thats it. Note that @code{.my.cnf} file is a slight security risk unless
2311 its on a safe partition. The $HOME/.my.cnf can of course be a symbolic
2312 link. Luckily $USER has only priviledges to mess up GNUnet's tables,
2313 which should be pretty harmless.
2318 You should briefly try if the database connection works. First, login
2327 If you get the message "Database changed" it probably works.
2329 If you get "ERROR 2002: Can't connect to local MySQL server@
2330 through socket '/tmp/mysql.sock' (2)" it may be resolvable by@
2331 "ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock"@
2332 so there may be some additional trouble depending on your mysql setup.
2334 @node Performance Tuning
2335 @subsection Performance Tuning
2337 For GNUnet, you probably want to set the option
2340 innodb_flush_log_at_trx_commit = 0
2344 for a rather dramatic boost in MySQL performance. However, this reduces
2345 the "safety" of your database as with this options you may loose
2346 transactions during a power outage.
2347 While this is totally harmless for GNUnet, the option applies to all
2348 applications using MySQL. So you should set it if (and only if) GNUnet is
2349 the only application on your system using MySQL.
2351 @node Setup for running Testcases
2352 @subsection Setup for running Testcases
2354 If you want to run the testcases, you must create a second database
2355 "gnunetcheck" with the same username and password. This database will
2356 then be used for testing ("make check").
2358 @node Configuring the Postgres database
2359 @subsection Configuring the Postgres database
2361 This text describes how to setup the Postgres database for GNUnet.
2363 This Postgres plugin was developed for Postgres 8.3 but might work for
2364 earlier versions as well.
2366 @node Reasons to use Postgres
2367 @subsection Reasons to use Postgres
2370 @item Easier to setup than MySQL
2374 @node Reasons not to use Postgres
2375 @subsection Reasons not to use Postgres
2379 @item Still some manual setup required
2382 @node Manual setup instructions
2383 @subsection Manual setup instructions
2386 @item In @code{gnunet.conf} set in section "DATASTORE" the value for
2387 "DATABASE" to "postgres".
2388 @item Access Postgres to create a user:@
2391 @item with Postgres 8.x, use:
2399 and enter the name of the user running GNUnet for the role interactively.
2400 Then, when prompted, do not set it to superuser, allow the creation of
2401 databases, and do not allow the creation of new roles.@
2403 @item with Postgres 9.x, use:
2407 $ createuser -d $GNUNET_USER
2411 where $GNUNET_USER is the name of the user running GNUnet.@
2417 As that user (so typically as user "gnunet"), create a database (or two):@
2421 # this way you can run "make check"
2422 $ createdb gnunetcheck
2427 Now you should be able to start @code{gnunet-arm}.
2429 @node Testing the setup manually
2430 @subsection Testing the setup manually
2432 You may want to try if the database connection works. First, again login
2433 as the user who will run gnunet-arm. Then use,
2436 $ psql gnunet # or gnunetcheck
2441 If, after you have started gnunet-arm at least once, you get
2442 a @code{gn090} table here, it probably works.
2444 @node Configuring the datacache
2445 @subsection Configuring the datacache
2448 The datacache is what GNUnet uses for storing temporary data. This data is
2449 expected to be wiped completely each time GNUnet is restarted (or the
2450 system is rebooted).
2452 You need to specify how many bytes GNUnet is allowed to use for the
2453 datacache using the "QUOTA" option in the section "dhtcache".
2454 Furthermore, you need to specify which database backend should be used to
2455 store the data. Currently, you have the choice between
2456 sqLite, MySQL and Postgres.
2458 @node Configuring the file-sharing service
2459 @subsection Configuring the file-sharing service
2461 In order to use GNUnet for file-sharing, you first need to make sure
2462 that the file-sharing service is loaded.
2463 This is done by setting the AUTOSTART option in section "fs" to "YES".
2464 Alternatively, you can run
2471 to start the file-sharing service by hand.
2473 Except for configuring the database and the datacache the only important
2474 option for file-sharing is content migration.
2476 Content migration allows your peer to cache content from other peers as
2477 well as send out content stored on your system without explicit requests.
2478 This content replication has positive and negative impacts on both system
2479 performance and privacy.
2481 FIXME: discuss the trade-offs. Here is some older text about it...
2483 Setting this option to YES allows gnunetd to migrate data to the local
2484 machine. Setting this option to YES is highly recommended for efficiency.
2485 Its also the default. If you set this value to YES, GNUnet will store
2486 content on your machine that you cannot decrypt.
2487 While this may protect you from liability if the judge is sane, it may
2488 not (IANAL). If you put illegal content on your machine yourself, setting
2489 this option to YES will probably increase your chances to get away with it
2490 since you can plausibly deny that you inserted the content.
2491 Note that in either case, your anonymity would have to be broken first
2492 (which may be possible depending on the size of the GNUnet network and the
2493 strength of the adversary).
2495 @node Configuring logging
2496 @subsection Configuring logging
2498 Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options.
2499 Using "-L", a log level can be specified. With log level "ERROR" only
2500 serious errors are logged.
2501 The default log level is "WARNING" which causes anything of
2502 concern to be logged. Log level "INFO" can be used to log anything that
2503 might be interesting information whereas "DEBUG" can be used by
2504 developers to log debugging messages (but you need to run configure with
2505 @code{--enable-logging=verbose} to get them compiled).
2506 The "-l" option is used to specify the log file.
2508 Since most GNUnet services are managed by @code{gnunet-arm}, using the
2509 "-l" or "-L" options directly is not possible.
2510 Instead, they can be specified using the "OPTIONS" configuration value in
2511 the respective section for the respective service.
2512 In order to enable logging globally without editing the "OPTIONS" values
2513 for each service, @code{gnunet-arm} supports a "GLOBAL_POSTFIX" option.
2514 The value specified here is given as an extra option to all services for
2515 which the configuration does contain a service-specific "OPTIONS" field.
2517 "GLOBAL_POSTFIX" can contain the special sequence "@{@}" which is replaced
2518 by the name of the service that is being started. Furthermore,
2519 @code{GLOBAL_POSTFIX} is special in that sequences starting with "$"
2520 anywhere in the string are expanded (according to options in "PATHS");
2521 this expansion otherwise is only happening for filenames and then the "$"
2522 must be the first character in the option. Both of these restrictions do
2523 not apply to "GLOBAL_POSTFIX".
2524 Note that specifying @code{%} anywhere in the "GLOBAL_POSTFIX" disables
2525 both of these features.
2527 In summary, in order to get all services to log at level "INFO" to
2528 log-files called @code{SERVICENAME-logs}, the following global prefix
2532 GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO
2535 @node Configuring the transport service and plugins
2536 @subsection Configuring the transport service and plugins
2538 The transport service in GNUnet is responsible to maintain basic
2539 connectivity to other peers.
2540 Besides initiating and keeping connections alive it is also responsible
2541 for address validation.
2543 The GNUnet transport supports more than one transport protocol.
2544 These protocols are configured together with the transport service.
2546 The configuration section for the transport service itself is quite
2547 similar to all the other services
2551 @@UNIXONLY@@ PORT = 2091@
2552 HOSTNAME = localhost@
2553 HOME = $SERVICEHOME@
2554 CONFIG = $DEFAULTCONFIG@
2555 BINARY = gnunet-service-transport@
2557 NEIGHBOUR_LIMIT = 50@
2558 ACCEPT_FROM = 127.0.0.1;@
2559 ACCEPT_FROM6 = ::1;@
2561 UNIXPATH = /tmp/gnunet-service-transport.sock@
2564 Different are the settings for the plugins to load @code{PLUGINS}.
2565 The first setting specifies which transport plugins to load.
2568 @item transport-unix
2569 A plugin for local only communication with UNIX domain sockets. Used for
2570 testing and available on unix systems only. Just set the port
2575 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2579 A plugin for communication with TCP. Set port to 0 for client mode with
2580 outbound only connections
2584 # Use 0 to ONLY advertise as a peer behind NAT (no port binding)@
2586 ADVERTISED_PORT = 2086@
2587 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2588 # Maximum number of open TCP connections allowed@
2589 MAX_CONNECTIONS = 128@
2593 A plugin for communication with UDP. Supports peer discovery using
2600 BROADCAST_INTERVAL = 30 s@
2602 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2605 @item transport-http
2606 HTTP and HTTPS support is split in two part: a client plugin initiating
2607 outbound connections and a server part accepting connections from the
2608 client. The client plugin just takes the maximum number of connections as
2612 [transport-http_client]@
2613 MAX_CONNECTIONS = 128@
2614 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2618 [transport-https_client]@
2619 MAX_CONNECTIONS = 128@
2620 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2624 The server has a port configured and the maximum nunber of connections.
2625 The HTTPS part has two files with the certificate key and the certificate
2628 The server plugin supports reverse proxies, so a external hostname can be
2629 set using the @code{EXTERNAL_HOSTNAME} setting.
2630 The webserver under this address should forward the request to the peer
2631 and the configure port.
2634 [transport-http_server]@
2635 EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet@
2637 MAX_CONNECTIONS = 128@
2638 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2642 [transport-https_server]@
2644 CRYPTO_INIT = NORMAL@
2645 KEY_FILE = https.key@
2646 CERT_FILE = https.cert@
2647 MAX_CONNECTIONS = 128@
2648 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2651 @item transport-wlan
2653 There is a special article how to setup the WLAN plugin, so here only the
2654 settings. Just specify the interface to use:
2658 # Name of the interface in monitor mode (typically monX)@
2660 # Real hardware, no testing@
2662 TESTING_IGNORE_KEYS = ACCEPT_FROM;@
2666 @node Configuring the wlan transport plugin
2667 @subsection Configuring the wlan transport plugin
2670 The wlan transport plugin enables GNUnet to send and to receive data on a
2672 It has not to be connected to a wlan network as long as sender and
2673 receiver are on the same channel. This enables you to get connection to
2674 the GNUnet where no internet access is possible, for example while
2675 catastrophes or when censorship cuts you off the internet.
2679 * Requirements for the WLAN plugin::
2681 * Before starting GNUnet::
2682 * Limitations and known bugs::
2686 @node Requirements for the WLAN plugin
2687 @subsubsection Requirements for the WLAN plugin
2691 @item wlan network card with monitor support and packet injection
2692 (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org})
2694 @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with
2697 @item Wlantools to create the a monitor interface, tested with airmon-ng
2698 of the aircrack-ng package
2702 @subsubsection Configuration
2704 There are the following options for the wlan plugin (they should be like
2705 this in your default config file, you only need to adjust them if the
2706 values are incorrect for your system)
2709 # section for the wlan transport plugin@
2711 # interface to use, more information in the
2712 # "Before starting GNUnet" section of the handbook.
2714 # testmode for developers:@
2715 # 0 use wlan interface,@
2716 #1 or 2 use loopback driver for tests 1 = server, 2 = client@
2720 @node Before starting GNUnet
2721 @subsubsection Before starting GNUnet
2723 Before starting GNUnet, you have to make sure that your wlan interface is
2724 in monitor mode. One way to put the wlan interface into monitor mode (if
2725 your interface name is wlan0) is by executing:
2728 sudo airmon-ng start wlan0@
2732 Here is an example what the result should look like:
2735 Interface Chipset Driver@
2736 wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]@
2737 (monitor mode enabled on mon0)@
2741 The monitor interface is mon0 is the one that you have to put into the
2744 @node Limitations and known bugs
2745 @subsubsection Limitations and known bugs
2747 Wlan speed is at the maximum of 1 Mbit/s because support for choosing the
2748 wlan speed with packet injection was removed in newer kernels.
2749 Please pester the kernel developers about fixing this.
2751 The interface channel depends on the wlan network that the card is
2752 connected to. If no connection has been made since the start of the
2753 computer, it is usually the first channel of the card.
2754 Peers will only find each other and communicate if they are on the same
2755 channel. Channels must be set manually (i.e. using
2756 @code{iwconfig wlan0 channel 1}).
2759 @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx
2760 @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
2762 The HTTP plugin supports data transfer using reverse proxies. A reverse
2763 proxy forwards the HTTP request he receives with a certain URL to another
2764 webserver, here a GNUnet peer.
2766 So if you have a running Apache or nginx webserver you can configure it to
2767 be a GNUnet reverse proxy. Especially if you have a well-known webiste
2768 this improves censorship resistance since it looks as normal surfing
2771 To do so, you have to do two things:
2774 @item Configure your webserver to forward the GNUnet HTTP traffic
2775 @item Configure your GNUnet peer to announce the respective address
2778 As an example we want to use GNUnet peer running:
2782 @item HTTP server plugin on @code{gnunet.foo.org:1080}
2784 @item HTTPS server plugin on @code{gnunet.foo.org:4433}
2786 @item A apache or nginx webserver on
2787 @uref{http://www.foo.org/, http://www.foo.org:80/}
2789 @item A apache or nginx webserver on https://www.foo.org:443/
2792 And we want the webserver to accept GNUnet traffic under
2793 @code{http://www.foo.org/bar/}. The required steps are described here:
2795 @strong{Configure your Apache2 HTTP webserver}
2797 First of all you need mod_proxy installed.
2799 Edit your webserver configuration. Edit
2800 @code{/etc/apache2/apache2.conf} or the site-specific configuration file.
2802 In the respective @code{server config},@code{virtual host} or
2803 @code{directory} section add the following lines:
2809 ProxyPass http://gnunet.foo.org:1080/@
2810 ProxyPassReverse http://gnunet.foo.org:1080/@
2815 @strong{Configure your Apache2 HTTPS webserver}
2817 We assume that you already have an HTTPS server running, if not please
2818 check how to configure a HTTPS host. An easy to use example is the
2819 @file{apache2/sites-available/default-ssl} example configuration file.
2821 In the respective HTTPS @code{server config},@code{virtual host} or
2822 @code{directory} section add the following lines:
2829 ProxyPass https://gnunet.foo.org:4433/@
2830 ProxyPassReverse https://gnunet.foo.org:4433/@
2835 More information about the apache mod_proxy configuration can be found
2836 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}
2838 @strong{Configure your nginx HTTPS webserver}
2840 Since nginx does not support chunked encoding, you first of all have to
2841 install @code{chunkin}:@
2842 @uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}
2844 To enable chunkin add:
2848 error_page 411 = @@my_411_error;@
2849 location @@my_411_error @{@
2855 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
2856 the site-specific configuration file.
2858 In the @code{server} section add:@
2863 proxy_pass http://gnunet.foo.org:1080/;@
2864 proxy_buffering off;@
2865 proxy_connect_timeout 5; # more than http_server@
2866 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout@
2867 proxy_http_version 1.1; # 1.0 default@
2868 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@
2873 @strong{Configure your nginx HTTPS webserver}
2875 Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
2876 the site-specific configuration file.
2878 In the @code{server} section add:
2881 ssl_session_timeout 6m;@
2884 proxy_pass https://gnunet.foo.org:4433/;@
2885 proxy_buffering off;@
2886 proxy_connect_timeout 5; # more than http_server@
2887 proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout@
2888 proxy_http_version 1.1; # 1.0 default@
2889 proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@
2894 @strong{Configure your GNUnet peer}
2896 To have your GNUnet peer announce the address, you have to specify the
2897 @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]}
2901 [transport-http_server]@
2902 EXTERNAL_HOSTNAME = http://www.foo.org/bar/@
2906 and/or @code{[transport-https_server]} section:
2909 [transport-https_server]@
2910 EXTERNAL_HOSTNAME = https://www.foo.org/bar/@
2914 Now restart your webserver and your peer...
2916 @node Blacklisting peers
2917 @subsection Blacklisting peers
2919 Transport service supports to deny connecting to a specific peer of to a
2920 specific peer with a specific transport plugin using te blacklisting
2921 component of transport service. With@ blacklisting it is possible to deny
2922 connections to specific peers of@ to use a specific plugin to a specific
2923 peer. Peers can be blacklisted using@ the configuration or a blacklist
2924 client can be asked.
2926 To blacklist peers using the configuration you have to add a section to
2927 your@ configuration containing the peer id of the peer to blacklist and
2928 the plugin@ if required.
2932 To blacklist connections to P565... on peer AG2P... using tcp add:@
2934 @c FIXME: This is too long and produces errors in the pdf.
2936 [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@
2937 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp@
2940 To blacklist connections to P565... on peer AG2P... using all plugins add:@
2943 [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@
2944 P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =@
2947 You can also add a blacklist client usign the blacklist api. On a
2948 blacklist check, blacklisting first checks internally if the peer is
2949 blacklisted and if not, it asks the blacklisting clients. Clients are
2950 asked if it is OK to connect to a peer ID, the plugin is omitted.
2952 On blacklist check for (peer, plugin)
2954 @item Do we have a local blacklist entry for this peer and this plugin?@
2955 @item YES: disallow connection@
2956 @item Do we have a local blacklist entry for this peer and all plugins?@
2957 @item YES: disallow connection@
2958 @item Does one of the clients disallow?@
2959 @item YES: disallow connection
2962 @node Configuration of the HTTP and HTTPS transport plugins
2963 @subsection Configuration of the HTTP and HTTPS transport plugins
2965 The client part of the http and https transport plugins can be configured
2966 to use a proxy to connect to the hostlist server. This functionality can
2967 be configured in the configuration file directly or using the
2970 The both the HTTP and HTTPS clients support the following proxy types at
2974 @item HTTP 1.1 proxy
2975 @item SOCKS 4/4a/5/5 with hostname
2978 In addition authentication at the proxy with username and password can be
2981 To configure proxy support for the clients in the gnunet-setup tool,
2982 select the "transport" tab and activate the respective plugin. Now you
2983 can select the appropriate proxy type. The hostname or IP address
2984 (including port if required) has to be entered in the "Proxy hostname"
2985 textbox. If required, enter username and password in the "Proxy username"
2986 and "Proxy password" boxes. Be aware that these information will be stored
2987 in the configuration in plain text.
2989 To configure these options directly in the configuration, you can
2990 configure the following settings in the [transport-http_client] and
2991 [transport-https_client] section of the configuration:
2994 # Type of proxy server,@
2995 # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME@
2999 # Hostname or IP of proxy server@
3001 # User name for proxy server@
3003 # User password for proxy server@
3007 @node Configuring the GNU Name System
3008 @subsection Configuring the GNU Name System
3011 * Configuring system-wide DNS interception::
3012 * Configuring the GNS nsswitch plugin::
3013 * Configuring GNS on W32::
3015 * Setup of the GNS CA::
3016 * Testing the GNS setup::
3017 * Automatic Shortening in the GNU Name System::
3021 @node Configuring system-wide DNS interception
3022 @subsubsection Configuring system-wide DNS interception
3024 Before you install GNUnet, make sure you have a user and group 'gnunet'
3025 as well as an empty group 'gnunetdns'.
3027 When using GNUnet with system-wide DNS interception, it is absolutely
3028 necessary for all GNUnet service processes to be started by
3029 @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be
3030 sure to run @code{make install} as root (or use the @code{sudo} option to
3031 configure) to grant GNUnet sufficient privileges.
3033 With this setup, all that is required for enabling system-wide DNS
3034 interception is for some GNUnet component (VPN or GNS) to request it.
3035 The @code{gnunet-service-dns} will then start helper programs that will
3036 make the necessary changes to your firewall (@code{iptables}) rules.
3038 Note that this will NOT work if your system sends out DNS traffic to a
3039 link-local IPv6 address, as in this case GNUnet can intercept the traffic,
3040 but not inject the responses from the link-local IPv6 address. Hence you
3041 cannot use system-wide DNS interception in conjunction with link-local
3042 IPv6-based DNS servers. If such a DNS server is used, it will bypass
3043 GNUnet's DNS traffic interception.
3045 Using the GNU Name System (GNS) requires two different configuration
3047 First of all, GNS needs to be integrated with the operating system. Most
3048 of this section is about the operating system level integration.
3050 Additionally, each individual user who wants to use the system must also
3051 initialize his GNS zones. This can be done by running (after starting
3055 $ gnunet-gns-import.sh
3059 after the local GNUnet peer has been started. Note that the namestore (in
3060 particular the namestore database backend) should not be reconfigured
3061 afterwards (as records are not automatically migrated between backends).
3063 The remainder of this chapter will detail the various methods for
3064 configuring the use of GNS with your operating system.
3066 At this point in time you have different options depending on your OS:
3070 @item Use the gnunet-gns-proxy This approach works for all operating
3071 systems and is likely the easiest. However, it enables GNS only for
3072 browsers, not for other applications that might be using DNS, such as SSH.
3073 Still, using the proxy is required for using HTTP with GNS and is thus
3074 recommended for all users. To do this, you simply have to run the
3075 @code{gnunet-gns-proxy-setup-ca} script as the user who will run the
3076 browser (this will create a GNS certificate authority (CA) on your system
3077 and import its key into your browser), then start @code{gnunet-gns-proxy}
3078 and inform your browser to use the Socks5 proxy which
3079 @code{gnunet-gns-proxy} makes available by default on port 7777.
3080 @item Use a nsswitch plugin (recommended on GNU systems)
3081 This approach has the advantage of offering fully personalized resolution
3082 even on multi-user systems. A potential disadvantage is that some
3083 applications might be able to bypass GNS.
3084 @item Use a W32 resolver plugin (recommended on W32)
3085 This is currently the only option on W32 systems.
3086 @item Use system-wide DNS packet interception
3087 This approach is recommended for the GNUnet VPN. It can be used to handle
3088 GNS at the same time; however, if you only use this method, you will only
3089 get one root zone per machine (not so great for multi-user systems).
3092 You can combine system-wide DNS packet interception with the nsswitch
3094 The setup of the system-wide DNS interception is described here. All of
3095 the other GNS-specific configuration steps are described in the following
3098 @node Configuring the GNS nsswitch plugin
3099 @subsubsection Configuring the GNS nsswitch plugin
3101 The Name Service Switch (NSS) is a facility in Unix-like operating systems
3102 that provides a variety of sources for common configuration databases and
3103 name resolution mechanisms.
3104 A system administrator usually configures the operating system's name
3105 services using the file @file{/etc/nsswitch.conf}.
3107 GNS provides a NSS plugin to integrate GNS name resolution with the
3108 operating system's name resolution process.
3109 To use the GNS NSS plugin you have to either
3112 @item install GNUnet as root or
3113 @item compile GNUnet with the @code{--with-sudo=yes} switch.
3116 Name resolution is controlled by the @emph{hosts} section in the NSS
3117 configuration. By default this section first performs a lookup in the
3118 /etc/hosts file and then in DNS. The nsswitch file should contain a line
3122 hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4
3126 Here the GNS NSS plugin can be added to perform a GNS lookup before
3127 performing a DNS lookup.
3128 The GNS NSS plugin has to be added to the "hosts" section in
3129 @file{/etc/nsswitch.conf} file before DNS related plugins:
3133 hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4
3138 The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not
3139 found in GNS it will not be queried in DNS.
3141 @node Configuring GNS on W32
3142 @subsubsection Configuring GNS on W32
3144 This document is a guide to configuring GNU Name System on W32-compatible
3147 After GNUnet is installed, run the w32nsp-install tool:
3150 w32nsp-install.exe libw32nsp-0.dll
3154 ('0' is the library version of W32 NSP; it might increase in the future,
3155 change the invocation accordingly).
3157 This will install GNS namespace provider into the system and allow other
3158 applications to resolve names that end in '@strong{gnu}'
3159 and '@strong{zkey}'. Note that namespace provider requires
3160 gnunet-gns-helper-service-w32 to be running, as well as gns service
3161 itself (and its usual dependencies).
3163 Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353},
3164 and this is where gnunet-gns-helper-service-w32 should be listening to
3165 (and is configured to listen to by default).
3167 To uninstall the provider, run:
3170 w32nsp-uninstall.exe
3174 (uses provider GUID to uninstall it, does not need a dll name).
3176 Note that while MSDN claims that other applications will only be able to
3177 use the new namespace provider after re-starting, in reality they might
3178 stat to use it without that. Conversely, they might stop using the
3179 provider after it's been uninstalled, even if they were not re-started.
3180 W32 will not permit namespace provider library to be deleted or
3181 overwritten while the provider is installed, and while there is at least
3182 one process still using it (even after it was uninstalled).
3184 @node GNS Proxy Setup
3185 @subsubsection GNS Proxy Setup
3187 When using the GNU Name System (GNS) to browse the WWW, there are several
3188 issues that can be solved by adding the GNS Proxy to your setup:
3192 @item If the target website does not support GNS, it might assume that it
3193 is operating under some name in the legacy DNS system (such as
3194 example.com). It may then attempt to set cookies for that domain, and the
3195 web server might expect a @code{Host: example.com} header in the request
3197 However, your browser might be using @code{example.gnu} for the
3198 @code{Host} header and might only accept (and send) cookies for
3199 @code{example.gnu}. The GNS Proxy will perform the necessary translations
3200 of the hostnames for cookies and HTTP headers (using the LEHO record for
3201 the target domain as the desired substitute).
3203 @item If using HTTPS, the target site might include an SSL certificate
3204 which is either only valid for the LEHO domain or might match a TLSA
3205 record in GNS. However, your browser would expect a valid certificate for
3206 @code{example.gnu}, not for some legacy domain name. The proxy will
3207 validate the certificate (either against LEHO or TLSA) and then
3208 on-the-fly produce a valid certificate for the exchange, signed by your
3209 own CA. Assuming you installed the CA of your proxy in your browser's
3210 certificate authority list, your browser will then trust the
3211 HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy.
3213 @item Finally, the proxy will in the future indicate to the server that it
3214 speaks GNS, which will enable server operators to deliver GNS-enabled web
3215 sites to your browser (and continue to deliver legacy links to legacy
3219 @node Setup of the GNS CA
3220 @subsubsection Setup of the GNS CA
3222 First you need to create a CA certificate that the proxy can use.
3223 To do so use the provided script gnunet-gns-proxy-ca:
3226 $ gnunet-gns-proxy-setup-ca
3230 This will create a personal certification authority for you and add this
3231 authority to the firefox and chrome database. The proxy will use the this
3232 CA certificate to generate @code{*.gnu} client certificates on the fly.
3234 Note that the proxy uses libcurl. Make sure your version of libcurl uses
3235 GnuTLS and NOT OpenSSL. The proxy will not work with libcurl compiled
3238 @node Testing the GNS setup
3239 @subsubsection Testing the GNS setup
3241 Now for testing purposes we can create some records in our zone to test
3242 the SSL functionality of the proxy:
3245 $ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67
3246 $ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org"
3250 At this point we can start the proxy. Simply execute
3257 Configure your browser to use this SOCKSv5 proxy on port 7777 and visit
3259 If you use firefox you also have to go to about:config and set the key
3260 @code{network.proxy.socks_remote_dns} to @code{true}.
3262 When you visit @code{https://homepage.gnu/}, you should get to the
3263 @code{https://gnunet.org/} frontpage and the browser (with the correctly
3264 configured proxy) should give you a valid SSL certificate for
3265 @code{homepage.gnu} and no warnings. It should look like this:
3267 @c insert image here gnunethpgns.png
3269 @node Automatic Shortening in the GNU Name System
3270 @subsubsection Automatic Shortening in the GNU Name System
3272 This page describes a possible option for 'automatic name shortening',
3273 which you can choose to enable with the GNU Name System.
3275 When GNS encounters a name for the first time, it can use the 'NICK'
3276 record of the originating zone to automatically generate a name for the
3277 zone. If automatic shortening is enabled, those auto-generated names will
3278 be placed (as private records) into your personal 'shorten' zone (to
3279 prevent confusion with manually selected names).
3280 Then, in the future, if the same name is encountered again, GNS will
3281 display the shortened name instead (the first time, the long name will
3282 still be used as shortening typically happens asynchronously as looking up
3283 the 'NICK' record takes some time). Using this feature can be a convenient
3284 way to avoid very long @code{.gnu} names; however, note that names from
3285 the shorten-zone are assigned on a first-come-first-serve basis and should
3286 not be trusted. Furthermore, if you enable this feature, you will no
3287 longer see the full delegation chain for zones once shortening has been
3290 @node Configuring the GNUnet VPN
3291 @subsection Configuring the GNUnet VPN
3294 * IPv4 address for interface::
3295 * IPv6 address for interface::
3296 * Configuring the GNUnet VPN DNS::
3297 * Configuring the GNUnet VPN Exit Service::
3298 * IP Address of external DNS resolver::
3299 * IPv4 address for Exit interface::
3300 * IPv6 address for Exit interface::
3303 Before configuring the GNUnet VPN, please make sure that system-wide DNS
3304 interception is configured properly as described in the section on the
3307 The default-options for the GNUnet VPN are usually sufficient to use
3308 GNUnet as a Layer 2 for your Internet connection. However, what you always
3309 have to specify is which IP protocol you want to tunnel: IPv4, IPv6 or
3310 both. Furthermore, if you tunnel both, you most likely should also tunnel
3311 all of your DNS requests.
3312 You theoretically can tunnel "only" your DNS traffic, but that usually
3315 The other options as shown on the gnunet-setup tool are:
3317 @node IPv4 address for interface
3318 @subsubsection IPv4 address for interface
3320 This is the IPv4 address the VPN interface will get. You should pick an
3321 'private' IPv4 network that is not yet in use for you system. For example,
3322 if you use 10.0.0.1/255.255.0.0 already, you might use
3323 10.1.0.1/255.255.0.0.
3324 If you use 10.0.0.1/255.0.0.0 already, then you might use
3325 192.168.0.1/255.255.0.0.
3326 If your system is not in a private IP-network, using any of the above will
3328 You should try to make the mask of the address big enough (255.255.0.0
3329 or, even better, 255.0.0.0) to allow more mappings of remote IP Addresses
3331 However, even a 255.255.255.0-mask will suffice for most users.
3333 @node IPv6 address for interface
3334 @subsubsection IPv6 address for interface
3336 The IPv6 address the VPN interface will get. Here you can specify any
3337 non-link-local address (the address should not begin with "fe80:").
3338 A subnet Unique Local Unicast (fd00::/8-prefix) that you are currently
3339 not using would be a good choice.
3341 @node Configuring the GNUnet VPN DNS
3342 @subsubsection Configuring the GNUnet VPN DNS
3344 To resolve names for remote nodes, activate the DNS exit option.
3346 @node Configuring the GNUnet VPN Exit Service
3347 @subsubsection Configuring the GNUnet VPN Exit Service
3349 If you want to allow other users to share your Internet connection (yes,
3350 this may be dangerous, just as running a Tor exit node) or want to
3351 provide access to services on your host (this should be less dangerous,
3352 as long as those services are secure), you have to enable the GNUnet exit
3355 You then get to specify which exit functions you want to provide. By
3356 enabling the exit daemon, you will always automatically provide exit
3357 functions for manually configured local services (this component of the
3359 development and not documented further at this time). As for those
3360 services you explicitly specify the target IP address and port, there is
3361 no significant security risk in doing so.
3363 Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet.
3364 Being a DNS exit is usually pretty harmless. However, enabling IPv4 or
3365 IPv6-exit without further precautions may enable adversaries to access
3366 your local network, send spam, attack other systems from your Internet
3367 connection and to other mischief that will appear to come from your
3368 machine. This may or may not get you into legal trouble.
3369 If you want to allow IPv4 or IPv6-exit functionality, you should strongly
3370 consider adding additional firewall rules manually to protect your local
3371 network and to restrict outgoing TCP traffic (i.e. by not allowing access
3372 to port 25). While we plan to improve exit-filtering in the future,
3373 you're currently on your own here.
3374 Essentially, be prepared for any kind of IP-traffic to exit the respective
3375 TUN interface (and GNUnet will enable IP-forwarding and NAT for the
3376 interface automatically).
3378 Additional configuration options of the exit as shown by the gnunet-setup
3381 @node IP Address of external DNS resolver
3382 @subsubsection IP Address of external DNS resolver
3384 If DNS traffic is to exit your machine, it will be send to this DNS
3385 resolver. You can specify an IPv4 or IPv6 address.
3387 @node IPv4 address for Exit interface
3388 @subsubsection IPv4 address for Exit interface
3390 This is the IPv4 address the Interface will get. Make the mask of the
3391 address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more
3392 mappings of IP addresses into this range. As for the VPN interface, any
3393 unused, private IPv4 address range will do.
3395 @node IPv6 address for Exit interface
3396 @subsubsection IPv6 address for Exit interface
3398 The public IPv6 address the interface will get. If your kernel is not a
3399 very recent kernel and you are willing to manually enable IPv6-NAT, the
3400 IPv6 address you specify here must be a globally routed IPv6 address of
3403 Suppose your host has the address @code{2001:4ca0::1234/64}, then
3404 using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits,
3405 then change at least one bit in the range before the bitmask, in the
3406 example above we changed bit 111 from 0 to 1).
3408 You may also have to configure your router to route traffic for the entire
3409 subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this
3410 should be automatic with IPv6, but obviously anything can be
3413 @node Bandwidth Configuration
3414 @subsection Bandwidth Configuration
3416 You can specify how many bandwidth GNUnet is allowed to use to receive
3417 and send data. This is important for users with limited bandwidth or
3420 @node Configuring NAT
3421 @subsection Configuring NAT
3423 Most hosts today do not have a normal global IP address but instead are
3424 behind a router performing Network Address Translation (NAT) which assigns
3425 each host in the local network a private IP address.
3426 As a result, these machines cannot trivially receive inbound connections
3427 from the Internet. GNUnet supports NAT traversal to enable these machines
3428 to receive incoming connections from other peers despite their
3431 In an ideal world, you can press the "Attempt automatic configuration"
3432 button in gnunet-setup to automatically configure your peer correctly.
3433 Alternatively, your distribution might have already triggered this
3434 automatic configuration during the installation process.
3435 However, automatic configuration can fail to determine the optimal
3436 settings, resulting in your peer either not receiving as many connections
3437 as possible, or in the worst case it not connecting to the network at all.
3439 To manually configure the peer, you need to know a few things about your
3440 network setup. First, determine if you are behind a NAT in the first
3442 This is always the case if your IP address starts with "10.*" or
3443 "192.168.*". Next, if you have control over your NAT router, you may
3444 choose to manually configure it to allow GNUnet traffic to your host.
3445 If you have configured your NAT to forward traffic on ports 2086 (and
3446 possibly 1080) to your host, you can check the "NAT ports have been opened
3447 manually" option, which corresponds to the "PUNCHED_NAT" option in the
3448 configuration file. If you did not punch your NAT box, it may still be
3449 configured to support UPnP, which allows GNUnet to automatically
3450 configure it. In that case, you need to install the "upnpc" command,
3451 enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal
3452 via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the
3453 configuration file).
3455 Some NAT boxes can be traversed using the autonomous NAT traversal method.
3456 This requires certain GNUnet components to be installed with "SUID"
3457 prividledges on your system (so if you're installing on a system you do
3458 not have administrative rights to, this will not work).
3459 If you installed as 'root', you can enable autonomous NAT traversal by
3460 checking the "Enable NAT traversal using ICMP method".
3461 The ICMP method requires a way to determine your NAT's external (global)
3462 IP address. This can be done using either UPnP, DynDNS, or by manual
3463 configuration. If you have a DynDNS name or know your external IP address,
3464 you should enter that name under "External (public) IPv4 address" (which
3465 corresponds to the "EXTERNAL_ADDRESS" option in the configuration file).
3466 If you leave the option empty, GNUnet will try to determine your external
3467 IP address automatically (which may fail, in which case autonomous
3468 NAT traversal will then not work).
3470 Finally, if you yourself are not behind NAT but want to be able to
3471 connect to NATed peers using autonomous NAT traversal, you need to check
3472 the "Enable connecting to NATed peers using ICMP method" box.
3475 @node Peer configuration for distributions
3476 @subsection Peer configuration for distributions
3478 The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be
3479 manually set to "/var/lib/gnunet/data/" as the default
3480 "~/.local/share/gnunet/" is probably not that appropriate in this case.
3481 Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to
3482 "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a
3483 distribution decide to override system defaults, all of these changes
3484 should be done in a custom @file{/etc/gnunet.conf} and not in the files
3485 in the @file{config.d/} directory.
3487 Given the proposed access permissions, the "gnunet-setup" tool must be
3488 run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it
3489 modifies the system configuration). As always, gnunet-setup should be run
3490 after the GNUnet peer was stopped using "gnunet-arm -e". Distributions
3491 might want to include a wrapper for gnunet-setup that allows the
3492 desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account
3493 and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
3496 @node How to start and stop a GNUnet peer
3497 @section How to start and stop a GNUnet peer
3499 This section describes how to start a GNUnet peer. It assumes that you
3500 have already compiled and installed GNUnet and its' dependencies.
3501 Before you start a GNUnet peer, you may want to create a configuration
3502 file using gnunet-setup (but you do not have to).
3503 Sane defaults should exist in your
3504 @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice
3505 you could simply start without any configuration. If you want to
3506 configure your peer later, you need to stop it before invoking the
3507 @code{gnunet-setup} tool to customize further and to test your
3508 configuration (@code{gnunet-setup} has build-in test functions).
3510 The most important option you might have to still set by hand is in
3511 [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where
3512 GNUnet should store its data.
3513 It defaults to @code{$HOME/}, which again should work for most users.
3514 Make sure that the directory specified as GNUNET_HOME is writable to
3515 the user that you will use to run GNUnet (note that you can run frontends
3516 using other users, GNUNET_HOME must only be accessible to the user used to
3517 run the background processes).
3519 You will also need to make one central decision: should all of GNUnet be
3520 run under your normal UID, or do you want distinguish between system-wide
3521 (user-independent) GNUnet services and personal GNUnet services. The
3522 multi-user setup is slightly more complicated, but also more secure and
3523 generally recommended.
3526 * The Single-User Setup::
3527 * The Multi-User Setup::
3528 * Killing GNUnet services::
3529 * Access Control for GNUnet::
3532 @node The Single-User Setup
3533 @subsection The Single-User Setup
3535 For the single-user setup, you do not need to do anything special and can
3536 just start the GNUnet background processes using @code{gnunet-arm}.
3537 By default, GNUnet looks in @file{~/.config/gnunet.conf} for a
3538 configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@
3539 @code{$XDG_CONFIG_HOME} is defined). If your configuration lives
3540 elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet
3543 Assuming the configuration file is called @file{~/.config/gnunet.conf},
3544 you start your peer using the @code{gnunet-arm} command (say as user
3545 @code{gnunet}) using:
3548 gnunet-arm -c ~/.config/gnunet.conf -s
3552 The "-s" option here is for "start". The command should return almost
3553 instantly. If you want to stop GNUnet, you can use:
3556 gnunet-arm -c ~/.config/gnunet.conf -e
3560 The "-e" option here is for "end".
3562 Note that this will only start the basic peer, no actual applications
3564 If you want to start the file-sharing service, use (after starting
3568 gnunet-arm -c ~/.config/gnunet.conf -i fs
3572 The "-i fs" option here is for "initialize" the "fs" (file-sharing)
3573 application. You can also selectively kill only file-sharing support using
3576 gnunet-arm -c ~/.config/gnunet.conf -k fs
3580 Assuming that you want certain services (like file-sharing) to be always
3581 automatically started whenever you start GNUnet, you can activate them by
3582 setting "FORCESTART=YES" in the respective section of the configuration
3583 file (for example, "[fs]"). Then GNUnet with file-sharing support would
3584 be started whenever you@ enter:
3587 gnunet-arm -c ~/.config/gnunet.conf -s
3591 Alternatively, you can combine the two options:
3594 gnunet-arm -c ~/.config/gnunet.conf -s -i fs
3598 Using @code{gnunet-arm} is also the preferred method for initializing
3599 GNUnet from @code{init}.
3601 Finally, you should edit your @code{crontab} (using the @code{crontab}
3602 command) and insert a line@
3605 @@reboot gnunet-arm -c ~/.config/gnunet.conf -s@
3608 to automatically start your peer whenever your system boots.
3610 @node The Multi-User Setup
3611 @subsection The Multi-User Setup
3613 This requires you to create a user @code{gnunet} and an additional group
3614 @code{gnunetdns}, prior to running @code{make install} during
3616 Then, you create a configuration file @file{/etc/gnunet.conf} which should
3626 Then, perform the same steps to run GNUnet as in the per-user
3627 configuration, except as user @code{gnunet} (including the
3628 @code{crontab} installation).
3629 You may also want to run @code{gnunet-setup} to configure your peer
3631 Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you
3632 run @code{gnunet-setup} as user @code{gnunet}, you might need to change
3633 permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can
3634 write to the file (during setup).
3636 Afterwards, you need to perform another setup step for each normal user
3637 account from which you want to access GNUnet. First, grant the normal user
3638 (@code{$USER}) permission to the group gnunet:
3641 # adduser $USER gnunet
3645 Then, create a configuration file in @file{~/.config/gnunet.conf} for the
3646 $USER with the lines:
3655 This will ensure that @code{gnunet-arm} when started by the normal user
3656 will only run services that are per-user, and otherwise rely on the
3657 system-wide services.
3658 Note that the normal user may run gnunet-setup, but the
3659 configuration would be ineffective as the system-wide services will use
3660 @code{/etc/gnunet.conf} and ignore options set by individual users.
3662 Again, each user should then start the peer using
3663 @code{gnunet-arm -s} --- and strongly consider adding logic to start
3664 the peer automatically to their crontab.
3666 Afterwards, you should see two (or more, if you have more than one USER)
3667 @code{gnunet-service-arm} processes running in your system.
3669 @node Killing GNUnet services
3670 @subsection Killing GNUnet services
3672 It is not necessary to stop GNUnet services explicitly when shutting
3675 It should be noted that manually killing "most" of the
3676 @code{gnunet-service} processes is generally not a successful method for
3677 stopping a peer (since @code{gnunet-service-arm} will instantly restart
3678 them). The best way to explicitly stop a peer is using
3679 @code{gnunet-arm -e}; note that the per-user services may need to be
3680 terminated before the system-wide services will terminate normally.
3682 @node Access Control for GNUnet
3683 @subsection Access Control for GNUnet
3685 This chapter documents how we plan to make access control work within the
3686 GNUnet system for a typical peer. It should be read as a best-practice
3687 installation guide for advanced users and builders of binary
3688 distributions. The recommendations in this guide apply to POSIX-systems
3689 with full support for UNIX domain sockets only.
3691 Note that this is an advanced topic. The discussion presumes a very good
3692 understanding of users, groups and file permissions. Normal users on
3693 hosts with just a single user can just install GNUnet under their own
3694 account (and possibly allow the installer to use SUDO to grant additional
3695 permissions for special GNUnet tools that need additional rights).
3696 The discussion below largely applies to installations where multiple users
3697 share a system and to installations where the best possible security is
3700 A typical GNUnet system consists of components that fall into four
3705 @item User interfaces
3706 User interfaces are not security sensitive and are supposed to be run and
3707 used by normal system users.
3708 The GTK GUIs and most command-line programs fall into this category.
3709 Some command-line tools (like gnunet-transport) should be excluded as they
3710 offer low-level access that normal users should not need.
3711 @item System services and support tools
3712 System services should always run and offer services that can then be
3713 accessed by the normal users.
3714 System services do not require special permissions, but as they are not
3715 specific to a particular user, they probably should not run as a
3716 particular user. Also, there should typically only be one GNUnet peer per
3717 host. System services include the gnunet-service and gnunet-daemon
3718 programs; support tools include command-line programs such as gnunet-arm.
3719 @item Priviledged helpers
3720 Some GNUnet components require root rights to open raw sockets or perform
3721 other special operations. These gnunet-helper binaries are typically
3722 installed SUID and run from services or daemons.
3723 @item Critical services
3724 Some GNUnet services (such as the DNS service) can manipulate the service
3725 in deep and possibly highly security sensitive ways. For example, the DNS
3726 service can be used to intercept and alter any DNS query originating from
3727 the local machine. Access to the APIs of these critical services and their
3728 priviledged helpers must be tightly controlled.
3731 @c FIXME: The titles of these chapters are too long in the index.
3734 * Recommendation - Disable access to services via TCP::
3735 * Recommendation - Run most services as system user "gnunet"::
3736 * Recommendation - Control access to services using group "gnunet"::
3737 * Recommendation - Limit access to certain SUID binaries by group "gnunet"::
3738 * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"::
3739 * Differences between "make install" and these recommendations::
3742 @node Recommendation - Disable access to services via TCP
3743 @subsubsection Recommendation - Disable access to services via TCP
3745 GNUnet services allow two types of access: via TCP socket or via UNIX
3747 If the service is available via TCP, access control can only be
3748 implemented by restricting connections to a particular range of IP
3750 This is acceptable for non-critical services that are supposed to be
3751 available to all users on the local system or local network.
3752 However, as TCP is generally less efficient and it is rarely the case
3753 that a single GNUnet peer is supposed to serve an entire local network,
3754 the default configuration should disable TCP access to all GNUnet
3755 services on systems with support for UNIX domain sockets.
3756 As of GNUnet 0.9.2, configuration files with TCP access disabled should be
3757 generated by default. Users can re-enable TCP access to particular
3758 services simply by specifying a non-zero port number in the section of
3759 the respective service.
3762 @node Recommendation - Run most services as system user "gnunet"
3763 @subsubsection Recommendation - Run most services as system user "gnunet"
3765 GNUnet's main services should be run as a separate user "gnunet" in a
3766 special group "gnunet".
3767 The user "gnunet" should start the peer using "gnunet-arm -s" during
3768 system startup. The home directory for this user should be
3769 @file{/var/lib/gnunet} and the configuration file should be
3770 @file{/etc/gnunet.conf}.
3771 Only the @code{gnunet} user should have the right to access
3772 @file{/var/lib/gnunet} (@emph{mode: 700}).
3774 @node Recommendation - Control access to services using group "gnunet"
3775 @subsubsection Recommendation - Control access to services using group "gnunet"
3777 Users that should be allowed to use the GNUnet peer should be added to the
3778 group "gnunet". Using GNUnet's access control mechanism for UNIX domain
3779 sockets, those services that are considered useful to ordinary users
3780 should be made available by setting "UNIX_MATCH_GID=YES" for those
3782 Again, as shipped, GNUnet provides reasonable defaults.
3783 Permissions to access the transport and core subsystems might additionally
3784 be granted without necessarily causing security concerns.
3785 Some services, such as DNS, must NOT be made accessible to the "gnunet"
3786 group (and should thus only be accessible to the "gnunet" user and
3787 services running with this UID).
3789 @node Recommendation - Limit access to certain SUID binaries by group "gnunet"
3790 @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet"
3792 Most of GNUnet's SUID binaries should be safe even if executed by normal
3793 users. However, it is possible to reduce the risk a little bit more by
3794 making these binaries owned by the group "gnunet" and restricting their
3795 execution to user of the group "gnunet" as well (4750).
3797 @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
3798 @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns"
3800 A special group "gnunetdns" should be created for controlling access to
3801 the "gnunet-helper-dns".
3802 The binary should then be owned by root and be in group "gnunetdns" and
3803 be installed SUID and only be group-executable (2750).
3804 @b{Note that the group "gnunetdns" should have no users in it at all,
3806 The "gnunet-service-dns" program should be executed by user "gnunet" (via
3807 gnunet-service-arm) with the binary owned by the user "root" and the group
3808 "gnunetdns" and be SGID (2700). This way, @strong{only}
3809 "gnunet-service-dns" can change its group to "gnunetdns" and execute the
3810 helper, and the helper can then run as root (as per SUID).
3811 Access to the API offered by "gnunet-service-dns" is in turn restricted
3812 to the user "gnunet" (not the group!), which means that only
3813 "benign" services can manipulate DNS queries using "gnunet-service-dns".
3815 @node Differences between "make install" and these recommendations
3816 @subsubsection Differences between "make install" and these recommendations
3818 The current build system does not set all permissions automatically based
3819 on the recommendations above. In particular, it does not use the group
3820 "gnunet" at all (so setting gnunet-helpers other than the
3821 gnunet-helper-dns to be owned by group "gnunet" must be done manually).
3822 Furthermore, 'make install' will silently fail to set the DNS binaries to
3823 be owned by group "gnunetdns" unless that group already exists (!).
3824 An alternative name for the "gnunetdns" group can be specified using the
3825 "--with-gnunetdns=GRPNAME" configure option.