diff options
Diffstat (limited to 'doc/documentation/chapters/installation.texi')
| -rw-r--r-- | doc/documentation/chapters/installation.texi | 4086 |
1 files changed, 4086 insertions, 0 deletions
diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi new file mode 100644 index 0000000000..7be1e9833c --- /dev/null +++ b/doc/documentation/chapters/installation.texi @@ -0,0 +1,4086 @@ +@node GNUnet Installation Handbook +@chapter GNUnet Installation Handbook + +This handbook describes how to install (build, setup, compile) and +setup (configure, start) GNUnet @value{VERSION}. After following these +instructions you should be able to install and then start user-interfaces +to interact with the network. + +Note: This manual is far from complete, and we welcome informed +contributions, be it in the form of new chapters or insightful comments. + +@menu +* Dependencies:: +* Pre-installation notes:: +* Generic installation instructions:: +* Build instructions for Ubuntu 12.04 using Git:: +* Build instructions for software builds from source:: +* Build Instructions for Microsoft Windows Platforms:: +* Build instructions for Debian 7.5:: +* Installing GNUnet from Git on Ubuntu 14.4:: +* Build instructions for Debian 8:: +* Outdated build instructions for previous revisions:: +@c * Portable GNUnet:: +* The graphical configuration interface:: +* How to start and stop a GNUnet peer:: +@end menu + +@node Dependencies +@section Dependencies +@c %**end of header + +This section lists the various known dependencies for +GNUnet @value{EDITION}. +Suggestions for missing dependencies or wrong version numbers are welcome. + +@menu +* External dependencies:: +* Optional dependencies:: +* Internal dependencies:: +@end menu + +@node External dependencies +@subsection External dependencies +@c %**end of header + +These packages must be installed before a typical GNUnet installation +can be performed: + +@itemize @bullet +@item autoconf +@item automake +@item pkg-config +@item libltdl +@item gstreamer +@item gst-plugins-base +@item perl +@item python (only 2.7 supported)@footnote{tests and gnunet-qr} +@item jansson +@item nss +@item glib +@item gmp +@item bluez +@item miniupnpc +@item gettext +@item which +@item texinfo @geq{} 5.2 +@item GNU libmicrohttpd @geq{} 0.9.30 @footnote{We recommend to build it +with a GnuTLS version that was configured with libunbound} +@item GNU libextractor @geq{} 1.0 +@item GNU libtool @geq{} 2.2 +@item GNU libunistring @geq{} 0.9.1.1 +@item GNU libidn @geq{} 1.0.0 +@item @uref{https://gnupg.org/software/libgcrypt/, GNU libgcrypt} @geq{} +@uref{https://gnupg.org/ftp/gcrypt/libgcrypt/, 1.6.0} +@item @uref{https://gnutls.org/, GnuTLS} @geq{} 3.2.7 +@footnote{We recommend to compile with libunbound for DANE support; +GnuTLS also requires GNU nettle 2.7 (update: GnuTLS 3.2.7 appears NOT +to work against GNU nettle > 2.7, due to some API updatings done by +nettle. Thus it should be compiled against nettle 2.7 +and, in case you get some error on the reference to `rpl_strerror' being +undefined, follow the instructions on +@uref{http://lists.gnupg.org/pipermail/gnutls-devel/2013-November/006588.html, this} +post (and the link inside it)).} +@item @uref{https://gnunet.org/gnurl, gnURL} libgnurl @geq{} 7.34.0 +@footnote{must be compiled after @code{GnuTLS}} +@item libglpk @geq{} 4.45 +@item @uref{http://www.openssl.org/, OpenSSL} @geq{} 1.0 +@item TeX Live @geq{} 2012, optional (for gnunet-bcd) +@item Texinfo @geq{} 5.2 (for documentation) +@item libsqlite @geq{} 3.8.0 @footnote{(note that the code will +compile and often work with lower version numbers, but you may get subtle +bugs with respect to quota management in certain rare cases); +alternatively, MySQL or Postgres can also be installed, but those +databases will require more complex configurations (not +recommended for first-time users)} +@item zlib +@end itemize + +@node Optional dependencies +@subsection Optional dependencies + +These applications must be installed for various experimental or otherwise +optional features such as @command{gnunet-conversation}, +and @command{gnunet-gtk} (most of these features are only build if you +configure GNUnet with @command{--enable-experimental}): + +@itemize @bullet +@item libpulse @geq{} 2.0, +optional (for @command{gnunet-conversation}) +@item libopus @geq{} 1.0.1, +optional (for @command{gnunet-conversation}) +@item libogg @geq{} 1.3.0, +optional (for @command{gnunet-conversation}) +@item libnss contained @command{certool} binary, +optional for convenient installation of +the GNS proxy. +@item python-zbar @geq{} 0.10, +optional (for @command{gnunet-qr}) +@item Gtk+ @geq{} 3.0, +optional (for @command{gnunet-gtk}) +@item libgladeui (must match Gtk+ version), +optional (for @command{gnunet-gtk}) +@item libqrencode @geq{} 3.0, +optional (for @command{gnunet-namestore-gtk}) +@end itemize + +@node Internal dependencies +@subsection Internal dependencies + +This section tries to give an overview of what processes a typical GNUnet +peer running a particular application would consist of. All of the +processes listed here should be automatically started by +@command{gnunet-arm -s}. +The list is given as a rough first guide to users for failure diagnostics. +Ideally, end-users should never have to worry about these internal +dependencies. + +In terms of internal dependencies, a minimum file-sharing system consists +of the following GNUnet processes (in order of dependency): + +@itemize @bullet +@item gnunet-service-arm +@item gnunet-service-resolver (required by all) +@item gnunet-service-statistics (required by all) +@item gnunet-service-peerinfo +@item gnunet-service-transport (requires peerinfo) +@item gnunet-service-core (requires transport) +@item gnunet-daemon-hostlist (requires core) +@item gnunet-daemon-topology (requires hostlist, peerinfo) +@item gnunet-service-datastore +@item gnunet-service-dht (requires core) +@item gnunet-service-identity +@item gnunet-service-fs (requires identity, mesh, dht, datastore, core) +@end itemize + +@noindent +A minimum VPN system consists of the following GNUnet processes (in +order of dependency): + +@itemize @bullet +@item gnunet-service-arm +@item gnunet-service-resolver (required by all) +@item gnunet-service-statistics (required by all) +@item gnunet-service-peerinfo +@item gnunet-service-transport (requires peerinfo) +@item gnunet-service-core (requires transport) +@item gnunet-daemon-hostlist (requires core) +@item gnunet-service-dht (requires core) +@item gnunet-service-mesh (requires dht, core) +@item gnunet-service-dns (requires dht) +@item gnunet-service-regex (requires dht) +@item gnunet-service-vpn (requires regex, dns, mesh, dht) +@end itemize + +@noindent +A minimum GNS system consists of the following GNUnet processes (in +order of dependency): + +@itemize @bullet +@item gnunet-service-arm +@item gnunet-service-resolver (required by all) +@item gnunet-service-statistics (required by all) +@item gnunet-service-peerinfo +@item gnunet-service-transport (requires peerinfo) +@item gnunet-service-core (requires transport) +@item gnunet-daemon-hostlist (requires core) +@item gnunet-service-dht (requires core) +@item gnunet-service-mesh (requires dht, core) +@item gnunet-service-dns (requires dht) +@item gnunet-service-regex (requires dht) +@item gnunet-service-vpn (requires regex, dns, mesh, dht) +@item gnunet-service-identity +@item gnunet-service-namestore (requires identity) +@item gnunet-service-gns (requires vpn, dns, dht, namestore, identity) +@end itemize + +@node Pre-installation notes +@section Pre-installation notes + +Please note that in the code instructions for the installation, +@emph{#} indicates commands run as privileged root user and +@emph{$} shows commands run as unprivileged ("normal") system user. + + +@node Generic installation instructions +@section Generic installation instructions + +First, in addition to the GNUnet sources you might require downloading the +latest version of various dependencies, depending on how recent the +software versions in your distribution of GNU/Linux are. +Most distributions do not include sufficiently recent versions of these +dependencies. +Thus, a typically installation on a "modern" GNU/Linux distribution +requires you to install the following dependencies (ideally in this +order): + +@itemize @bullet +@item libgpgerror and libgcrypt +@item libnettle and libunbound (possibly from distribution), GnuTLS +@item libgnurl (read the README) +@item GNU libmicrohttpd +@item GNU libextractor +@end itemize + +Make sure to first install the various mandatory and optional +dependencies including development headers from your distribution. + +Other dependencies that you should strongly consider to install is a +database (MySQL, sqlite or Postgres). +The following instructions will assume that you installed at least sqlite. +For most distributions you should be able to find pre-build packages for +the database. Again, make sure to install the client libraries @b{and} the +respective development headers (if they are packaged separately) as well. + +You can find specific, detailed instructions for installing of the +dependencies (and possibly the rest of the GNUnet installation) in the +platform-specific descriptions, which can be found in the Index. +Please consult them now. +If your distribution is not listed, please study +@ref{Build instructions for Debian 8}, the build instructions for +Debian stable, carefully as you try to install the dependencies for your +own distribution. +Contributing additional instructions for further platforms is always +appreciated. +Please take in mind that operating system development tends to move at +a rather fast speed. Due to this you should be aware that some of +the instructions could be outdated by the time you are reading this. +If you find a mistake, please tell us about it (or even better: send +a patch to the documentation to fix it!). + +Before proceeding further, please double-check the dependency list. +Note that in addition to satisfying the dependencies, you might have to +make sure that development headers for the various libraries are also +installed. +There maybe files for other distributions, or you might be able to find +equivalent packages for your distribution. + +While it is possible to build and install GNUnet without having root +access, we will assume that you have full control over your system in +these instructions. +First, you should create a system user @emph{gnunet} and an additional +group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu, +type: + +@example +# adduser --system --home /var/lib/gnunet --group \ +--disabled-password gnunet +# addgroup --system gnunetdns +@end example + +@noindent +On other Unixes and GNU systems, this should have the same effect: + +@example +# useradd --system --groups gnunet --home-dir /var/lib/gnunet +# addgroup --system gnunetdns +@end example + +Now compile and install GNUnet using: + +@example +$ tar xvf gnunet-@value{VERSION}.tar.gz +$ cd gnunet-@value{VERSION} +$ ./configure --with-sudo=sudo --with-nssdir=/lib +$ make +$ sudo make install +@end example + +If you want to be able to enable DEBUG-level log messages, add +@code{--enable-logging=verbose} to the end of the +@command{./configure} command. +@code{DEBUG}-level log messages are in English only and +should only be useful for developers (or for filing +really detailed bug reports). + +Finally, you probably want to compile @command{gnunet-gtk}, which +includes @command{gnunet-setup} (a graphical tool for +GNUnet configuration) and @command{gnunet-fs-gtk} (a graphical tool for +GNUnet file-sharing): + +@example +$ tar xvf gnunet-gtk-@value{VERSION}.tar.gz +$ cd gnunet-gtk-@value{VERSION} +$ ./configure --with-gnunet=/usr/local/ +$ make +$ sudo make install +$ cd .. +# just to be safe run this: +$ sudo ldconfig +@end example + +@noindent +Next, edit the file @file{/etc/gnunet.conf} to contain the following: + +@example +[arm] +SYSTEM_ONLY = YES +USER_ONLY = NO +@end example + +@noindent +You may need to update your @code{ld.so} cache to include +files installed in @file{/usr/local/lib}: + +@example +# ldconfig +@end example + +@noindent +Then, switch from user @code{root} to user @code{gnunet} to start +the peer: + +@example +# su -s /bin/sh - gnunet +$ gnunet-arm -c /etc/gnunet.conf -s +@end example + +You may also want to add the last line in the gnunet user's @file{crontab} +prefixed with @code{@@reboot} so that it is executed whenever the system +is booted: + +@example +@@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s +@end example + +@noindent +This will only start the system-wide GNUnet services. +Type exit to get back your root shell. +Now, you need to configure the per-user part. For each +$USER that should get access to GNUnet on the system, run: + +@example +# adduser $USER gnunet +@end example + +@noindent +to allow them to access the system-wide GNUnet services. Then, each +user should create a configuration file @file{~/.config/gnunet.conf} +with the lines: + +@example +[arm] +SYSTEM_ONLY = NO +USER_ONLY = YES +DEFAULTSERVICES = gns +@end example + +@noindent +and start the per-user services using + +@example +$ gnunet-arm -c ~/.config/gnunet.conf -s +@end example + +@noindent +Again, adding a @code{crontab} entry to autostart the peer is advised: + +@example +@@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s +@end example + +@noindent +Note that some GNUnet services (such as SOCKS5 proxies) may need a +system-wide TCP port for each user. +For those services, systems with more than one user may require each user +to specify a different port number in their personal configuration file. + +Finally, the user should perform the basic initial setup for the GNU Name +System (GNS). This is done by running two commands: + +@example +$ gnunet-gns-import.sh +$ gnunet-gns-proxy-setup-ca +@end example + +@noindent +The first generates the default zones, wheras the second setups the GNS +Certificate Authority with the user's browser. Now, to activate GNS in the +normal DNS resolution process, you need to edit your +@file{/etc/nsswitch.conf} where you should find a line like this: + +@example +hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 +@end example + +@noindent +The exact details may differ a bit, which is fine. Add the text +@emph{"gns [NOTFOUND=return]"} after @emph{"files"}. +Keep in mind that we included a backslash ("\") here just for +markup reasons. You should write the text below on @b{one line} +and @b{without} the "\": + +@example +hosts: files gns [NOTFOUND=return] mdns4_minimal \ +[NOTFOUND=return] dns mdns4 +@end example + +@c FIXME: Document new behavior. +You might want to make sure that @file{/lib/libnss_gns.so.2} exists on +your system, it should have been created during the installation. + +@node Build instructions for Ubuntu 12.04 using Git +@section Build instructions for Ubuntu 12.04 using Git + +@menu +* Install the required build tools:: +* Install libgcrypt 1.6 and libgpg-error:: +* Install gnutls with DANE support:: +* Install libgnurl:: +* Install libmicrohttpd from Git:: +* Install libextractor from Git:: +* Install GNUnet dependencies:: +* Build GNUnet:: +* Install the GNUnet-gtk user interface from Git:: +@end menu + +@node Install the required build tools +@subsection Install the required build tools + +First, make sure Git is installed on your system: + +@example +$ sudo apt-get install git +@end example + +Install the essential buildtools: + +@example +$ sudo apt-get install automake autopoint autoconf libtool +@end example + +@node Install libgcrypt 1.6 and libgpg-error +@subsection Install libgcrypt 1.6 and libgpg-error + +@ref{generic source installation - libgpg-error} + +@node Install gnutls with DANE support +@subsection Install gnutls with DANE support + +@itemize @bullet +@item @ref{generic source installation - nettle} +@item @ref{generic source installation - ldns} +@item @ref{generic source installation - libunbound/unbound} +@item @ref{generic source installation - gnutls} +@item @ref{generic source installation - libgcrypt} +@end itemize + +@node Install libgnurl +@subsection Install libgnurl + +Follow the @ref{generic source installation - libgnurl}. + +@node Install libmicrohttpd from Git +@subsection Install libmicrohttpd from Git + +@example +$ git clone https://gnunet.org/git/libmicrohttpd +$ cd libmicrohttpd/ +$ ./bootstrap +$ ./configure +$ sudo make install ; cd .. +@end example + +@node Install libextractor from Git +@subsection Install libextractor from Git + +Install libextractor dependencies: + +@example +$ sudo apt-get install zlib1g-dev libgsf-1-dev libmpeg2-4-dev \ + libpoppler-dev libvorbis-dev libexiv2-dev libjpeg-dev \ + libtiff-dev libgif-dev libvorbis-dev libflac-dev libsmf-dev \ + g++ +@end example + +Build libextractor: + +@example +$ git clone https://gnunet.org/git/libextractor +$ cd libextractor +$ ./bootstrap +$ ./configure +$ sudo make install ; cd .. +@end example + +@node Install GNUnet dependencies +@subsection Install GNUnet dependencies + +@example +$ sudo apt-get install libidn11-dev libunistring-dev libglpk-dev \ + libpulse-dev libbluetooth-dev libsqlite-dev +@end example + +Install libopus: + +@example +$ wget http://downloads.xiph.org/releases/opus/opus-1.1.tar.gz +$ tar xf opus-1.1.tar.gz +$ cd opus-1.1/ +$ ./configure +$ sudo make install ; cd .. +@end example + +Choose one or more database backends: + +SQLite3: +@example +$ sudo apt-get install libsqlite3-dev +@end example +MySQL: +@example +$ sudo apt-get install libmysqlclient-dev +@end example +PostgreSQL: +@example +$ sudo apt-get install libpq-dev postgresql +@end example + + + +@node Build GNUnet +@subsection Build GNUnet + + + +@menu +* Configuring the installation path:: +* Configuring the system:: +* Installing components requiring sudo permission:: +* Build:: +@end menu + +@node Configuring the installation path +@subsubsection Configuring the installation path + +You can specify the location of the GNUnet installation by setting the +prefix when calling the configure script with @code{--prefix=DIRECTORY} + +@example +$ export PATH=$PATH:DIRECTORY/bin +@end example + +@node Configuring the system +@subsubsection Configuring the system + +Please make sure NOW that you have created a user and group 'gnunet' +and additionally a group 'gnunetdns': + +@example +$ sudo addgroup gnunet +$ sudo addgroup gnunetdns +$ sudo adduser gnunet +@end example + +Each GNUnet user should be added to the 'gnunet' group (may +require fresh login to come into effect): + +@example +$ sudo useradd -G gnunet +@end example + +@node Installing components requiring sudo permission +@subsubsection Installing components requiring sudo permission + +Some components, like the nss plugin required for GNS, may require root +permissions. To allow these few components to be installed use: + +@example +$ ./configure --with-sudo +@end example + +@node Build +@subsubsection Build + +@example +$ git clone https://gnunet.org/git/gnunet/ +$ cd gnunet/ +$ ./bootstrap +@end example + +Use the required configure call including the optional installation prefix +@code{PREFIX} or the sudo permissions: + +@example +$ ./configure [ --with-sudo | --with-prefix=PREFIX ] +@end example + +@example +$ make; sudo make install +@end example + +After installing it, you need to create an empty configuration file: + +@example +mkdir ~/.gnunet; touch ~/.gnunet/gnunet.conf +@end example + +And finally you can start GNUnet with: + +@example +$ gnunet-arm -s +@end example + +@node Install the GNUnet-gtk user interface from Git +@subsection Install the GNUnet-gtk user interface from Git + + +Install depencies: + +@example +$ sudo apt-get install libgtk-3-dev libunique-3.0-dev libgladeui-dev \ + libqrencode-dev +@end example + +Build GNUnet (with an optional prefix) and execute: + +@example +$ git clone https://gnunet.org/git/gnunet-gtk/ +$ cd gnunet-gtk/ +$ ./bootstrap +$ ./configure [--prefix=PREFIX] --with-gnunet=DIRECTORY +$ make; sudo make install +@end example + +@node Build instructions for software builds from source +@section Build instructions for software builds from source + +This section describes software builds in case your operating +system lacks binary substitutes / binary builds for some dependencies +of GNUnet. +It is assumed that you have installed common build dependencies +and that these instructions are treated as generic without any +debugging help. +It is furthermore assumed that you use the release tarballs of +the software, installation from the respective version control +sources might differ in ways that are only minimal different +(for example a dependency on autotools etc). + +@menu +* generic source installation - nettle:: +* generic source installation - ldns:: +* generic source installation - libunbound/unbound:: +* generic source installation - libav:: +* generic source installation - libextractor:: +* generic source installation - libgpg-error:: +* generic source installation - libgcrypt:: +* generic source installation - gnutls:: +* generic source installation - libmicrohttpd:: +* generic source installation - libgnurl:: +@end menu + +@node generic source installation - nettle +@subsection generic source installation - nettle +@example +$ wget http://www.lysator.liu.se/~nisse/archive/nettle-2.7.1.tar.gz +$ tar xf nettle-2.7.1.tar.gz +$ cd nettle-2.7.1 +$ ./configure +$ sudo make install ; cd .. +@end example + +@node generic source installation - ldns +@subsection generic source installation - ldns +@example +$ wget https://www.nlnetlabs.nl/downloads/ldns/ldns-1.6.16.tar.gz +$ tar xf ldns-1.6.16.tar.gz +$ cd ldns-1.6.16 +$ ./configure +$ sudo make install ; cd .. +@end example + +@node generic source installation - libunbound/unbound +@subsection generic source installation - libunbound/unbound +@example +$ wget https://unbound.net/downloads/unbound-1.4.21.tar.gz +$ tar xf unbound-1.4.21.tar.gz +$ cd unbound-1.4.21 +$ ./configure +$ sudo make install ; cd .. +@end example + +@node generic source installation - libav +@subsection generic source installation - libav +@example +$ wget https://libav.org/releases/libav-9.10.tar.xz +$ cd libav-0.9 ; ./configure --enable-shared; +$ make; sudo make install; cd .. +@end example + +@node generic source installation - libextractor +@subsection generic source installation - libextractor +@example +$ wget https://ftp.gnu.org/gnu/libextractor/libextractor-1.3.tar.gz +$ tar xvf libextractor-1.3.tar.gz +$ cd libextractor-1.3 ; ./configure; +$ make ; sudo make install; cd .. +@end example + +@node generic source installation - libgpg-error +@subsection generic source installation - libgpg-error +@example +$ wget https://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2 +$ tar xvf libgpg-error-1.12.tar.bz2 +$ cd libgpg-error-1.12; ./configure; +$ make ; sudo make install; cd .. +@end example + +@node generic source installation - libgcrypt +@subsection generic source installation - libgcrypt +@example +$ wget https://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2 +$ tar xvf libgcrypt-1.6.0.tar.bz2 +$ cd libgcrypt-1.6.0; ./configure --with-gpg-error-prefix=/usr/local; +$ make ; sudo make install ; cd .. +@end example + +@node generic source installation - gnutls +@subsection generic source installation - gnutls +@example +$ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.2/gnutls-3.2.7.tar.xz +$ tar xvf gnutls-3.2.7.tar.xz +$ cd gnutls-3.2.7 ; ./configure; +$ make ; sudo make install ; cd .. +@end example + +@noindent +If you want a GnuTLS with DANE functionality, you have to compile +it against libunbound. + +@node generic source installation - libmicrohttpd +@subsection generic source installation - libmicrohttpd +@example +$ wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.33.tar.gz +$ tar xvf libmicrohttpd-0.9.33.tar.gz +$ cd libmicrohttpd-0.9.33; ./configure; +$ make ; sudo make install ; cd .. +@end example + +@node generic source installation - libgnurl +@subsection generic source installation - libgnurl + +@example +$ wget https://gnunet.org/sites/default/files/gnurl-7.34.0.tar.bz2 +$ tar xvf gnurl-7.34.0.tar.bz2 +$ cd gnurl-7.34.0 +$ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \ + --without-libmetalink --without-winidn --without-librtmp \ + --without-nghttp2 --without-nss --without-cyassl --without-polarssl \ + --without-ssl --without-winssl --without-darwinssl --disable-sspi \ + --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \ + --disable-telnet --disable-tftp --disable-pop3 --disable-imap \ + --disable-smtp --disable-gopher --disable-file --disable-ftp +$ make ; sudo make install; cd .. +@end example + +@menu +* Fixing libgnurl build issues:: +@end menu + +@node Fixing libgnurl build issues +@subsubsection Fixing libgnurl build issues + +@c FIXME: Obviously this subsection should be evaluated and +@c if still necessary moved into gnURL itself (README) or +@c into a separate section which deals with gnURL. +If you have to compile libgnurl from source (for example if the version +included in your distribution is too old or it's not included at all) +you perhaps might get an error message while running the +@command{configure} script: + +@example +$ configure +... +checking for 64-bit curl_off_t data type... unknown +checking for 32-bit curl_off_t data type... unknown +checking for 16-bit curl_off_t data type... unknown +configure: error: cannot find data type for curl_off_t. +@end example + +@noindent +Solution: + +Before running the @command{configure} script, set: + +@example +CFLAGS="-I. -I$BUILD_ROOT/include" +@end example + +@node Build Instructions for Microsoft Windows Platforms +@section Build Instructions for Microsoft Windows Platforms + +@menu +* Introduction to building on MS Windows:: +* Requirements:: +* Dependencies & Initial Setup:: +* GNUnet Installation:: +* Adjusting Windows for running and testing GNUnet:: +* Building the GNUnet Installer:: +* Using GNUnet with Netbeans on Windows:: +@end menu + +@node Introduction to building on MS Windows +@subsection Introduction to building on MS Windows + + +This document is a guide to building GNUnet and its dependencies on +Windows platforms. GNUnet development is mostly done under GNU/Linux and +especially git checkouts may not build out of the box. +We regret any inconvenience, and if you have problems, please report +them. + +@node Requirements +@subsection Requirements + +The Howto is based upon a @strong{Windows Server 2008 32bit} +@strong{Installation}, @strong{sbuild} and thus a +@uref{http://www.mingw.org/wiki/MSYS, MSYS+MinGW} +(W32-GCC-Compiler-Suite + Unix-like Userland) installation. sbuild +is a convenient set of scripts which creates a working msys/mingw +installation and installs most dependencies required for GNUnet. + +As of the point of the creation of these instructions, +GNUnet @strong{requires} a Windows @strong{Server} 2003 or +newer for full feature support. +Windows Vista and later will also work, but +@strong{non-server version can not run a VPN-Exit-Node} as the NAT +features have been removed as of Windows Vista. + +@c TODO: We should document Windows 10! +@c It seems like the situation hasn't changed with W10 + +@node Dependencies & Initial Setup +@subsection Dependencies & Initial Setup + + +@itemize @bullet + +@item +Install a fresh version of @strong{Python 2.x}, even if you are using a +x64-OS, install a 32-bit version for use with sbuild. +Python 3.0 is currently incompatible. + +@item +Install your favorite @uref{http://code.google.com/p/tortoisegit/, git} & +@uref{http://tortoisesvn.net/, subversion}-clients. + +@item +You will also need some archive-manager like +@uref{http://www.7-zip.org/, 7zip}. + +@item +Pull a copy of sbuild to a directory of your choice, which will be used +in the remainder of this guide. For now, we will use +@file{c:\gnunet\sbuild\} + +@item +in @file{sbuild\src\mingw\mingw32-buildall.sh}, comment out the packages +@strong{gnunet-svn} and @strong{gnunet-gtk-svn}, as we don't want sbuild +to compile/install those for us. + +@item +Follow LRN's sbuild installation instructions.- +@end itemize + +Please note that sbuild may (or will most likely) fail during +installation, thus you really HAVE to @strong{check the logfiles} created +during the installation process. +Certain packages may fail to build initially due to missing dependencies, +thus you may have to +@strong{substitute those with binary-versions initially}. Later on once +dependencies are satisfied you can re-build the newer package versions. + +@strong{It is normal that you may have to repeat this step multiple times +and there is no uniform way to fix all compile-time issues, as the +build-process of many of the dependencies installed are rather unstable +on win32 and certain releases may not even compile at all.} + +Most dependencies for GNUnet have been set up by sbuild, thus we now +should add the @file{bin/} directories in your new msys and mingw +installations to PATH. You will want to create a backup of your finished +msys-environment by now. + +@node GNUnet Installation +@subsection GNUnet Installation + +First, we need to launch our msys-shell, you can do this via + +@file{C:\gnunet\sbuild\msys\msys.bat} + +You might wish to take a look at this file and adjust some +login-parameters to your msys environment. + +Also, sbuild added two pointpoints to your msys-environment, though those +might remain invisible: + +@itemize @bullet + +@item +/mingw, which will mount your mingw-directory from sbuild/mingw and the +other one is + +@item +/src which contains all the installation sources sbuild just compiled. +@end itemize + +Check out the current GNUnet sources (git HEAD) from the +GNUnet repository "gnunet.git", we will do this in your home directory: + +@code{git clone https://gnunet.org/git/gnunet/ ~/gnunet} + +Now, we will first need to bootstrap the checked out installation and then +configure it accordingly. + +@example +cd ~/gnunet +./bootstrap +STRIP=true CPPFLAGS="-DUSE_IPV6=1 -DW32_VEH" CFLAGS="$CFLAGS -g -O2" \ +./configure --prefix=/ --docdir=/share/doc/gnunet \ +--with-libiconv-prefix=/mingw --with-libintl-prefix=/mingw \ +--with-libcurl=/mingw --with-extractor=/mingw --with-sqlite=/mingw \ +--with-microhttpd=/mingw --with-plibc=/mingw --enable-benchmarks \ +--enable-expensivetests --enable-experimental --with-qrencode=/mingw \ +--enable-silent-rules --enable-experimental 2>&1 | tee -a ./configure.log +@end example + +The parameters above will configure for a reasonable GNUnet installation +to the your msys-root directory. +Depending on which features your would like to build or you may need to +specify additional dependencies. Sbuild installed most libs into +the /mingw subdirectory, so remember to prefix library locations with +this path. + +Like on a unixoid system, you might want to use your home directory as +prefix for your own GNUnet installation for development, without tainting +the buildenvironment. Just change the "prefix" parameter to point towards +~/ in this case. + +Now it's time to compile GNUnet as usual. Though this will take some time, +so you may fetch yourself a coffee or some Mate now... + +@example +make ; make install +@end example + +@node Adjusting Windows for running and testing GNUnet +@subsection Adjusting Windows for running and testing GNUnet + +Assuming the build succeeded and you +@strong{added the bin directory of your GNUnet to PATH}, you can now use +your gnunet-installation as usual. +Remember that UAC or the windows firewall may popup initially, blocking +further execution of gnunet until you acknowledge them. + +You will also have to take the usual steps to get peer-to-peer (p2p) +software running properly (port forwarding, ...), +and GNUnet will require administrative permissions as it may even +install a device-driver (in case you are using gnunet-vpn and/or +gnunet-exit). + +@node Building the GNUnet Installer +@subsection Building the GNUnet Installer + +The GNUnet installer is made with +@uref{http://nsis.sourceforge.net/, NSIS}. +The installer script is located in @file{contrib\win} in the +GNUnet source tree. + +@node Using GNUnet with Netbeans on Windows +@subsection Using GNUnet with Netbeans on Windows + +TODO + +@node Build instructions for Debian 7.5 +@section Build instructions for Debian 7.5 + + +These are the installation instructions for Debian 7.5. They were tested +using a minimal, fresh Debian 7.5 AMD64 installation without non-free +software (no contrib or non-free). +By "minimal", we mean that during installation, we did not select any +desktop environment, servers or system utilities during the "tasksel" +step. Note that the packages and the dependencies that we will install +during this chapter take about 1.5 GB of disk space. +Combined with GNUnet and space for objects during compilation, you should +not even attempt this unless you have about 2.5 GB free after the minimal +Debian installation. +Using these instructions to build a VM image is likely to require a +minimum of 4-5 GB for the VM (as you will likely also want a desktop +manager). + +GNUnet's security model assumes that your @file{/home} directory is +encrypted. Thus, if possible, you should encrypt your home partition +(or per-user home directory). + +Naturally, the exact details of the starting state for your installation +should not matter much. For example, if you selected any of those +installation groups you might simply already have some of the necessary +packages installed. +We did this for testing, as this way we are less likely to forget to +mention a required package. +Note that we will not install a desktop environment, but of course you +will need to install one to use GNUnet's graphical user interfaces. +Thus, it is suggested that you simply install the desktop environment of +your choice before beginning with the instructions. + + + +@menu +* Update:: +* Stable? Hah!:: +* Update again:: +* Installing packages:: +* Installing dependencies from source:: +* Installing GNUnet from source:: +* But wait there is more!:: +@end menu + +@node Update +@subsection Update + +After any installation, you should begin by running + +@example +# apt-get update ; apt-get upgrade +@end example + +to ensure that all of your packages are up-to-date. Note that the "#" is +used to indicate that you need to type in this command as "root" +(or prefix with "sudo"), whereas "$" is used to indicate typing in a +command as a normal user. + +@node Stable? Hah! +@subsection Stable? Hah! + +Yes, we said we start with a Debian 7.5 "stable" system. However, to +reduce the amount of compilation by hand, we will begin by allowing the +installation of packages from the testing and unstable distributions as +well. +We will stick to "stable" packages where possible, but some packages will +be taken from the other distributions. +Start by modifying @file{/etc/apt/sources.list} to contain the +following (possibly adjusted to point to your mirror of choice): + +@example +# These were there before: +deb http://ftp.de.debian.org/debian/ wheezy main +deb-src http://ftp.de.debian.org/debian/ wheezy main +deb http://security.debian.org/ wheezy/updates main +deb-src http://security.debian.org/ wheezy/updates main +deb http://ftp.de.debian.org/debian/ wheezy-updates main +deb-src http://ftp.de.debian.org/debian/ wheezy-updates main + +# Add these lines (feel free to adjust the mirror): +deb http://ftp.de.debian.org/debian/ testing main +deb http://ftp.de.debian.org/debian/ unstable main +@end example + +The next step is to create/edit your @file{/etc/apt/preferences} +file to look like this: + +@example +Package: * +Pin: release a=stable,n=wheezy +Pin-Priority: 700 + +Package: * +Pin: release o=Debian,a=testing +Pin-Priority: 650 + +Package: * +Pin: release o=Debian,a=unstable +Pin-Priority: 600 +@end example + +You can read more about Apt Preferences here and here. +Note that other pinnings are likely to also work for GNUnet, the key +thing is that you need some packages from unstable (as shown below). +However, as unstable is unlikely to be comprehensive (missing packages) +or might be problematic (crashing packages), you probably want others +from stable and/or testing. + +@node Update again +@subsection Update again + +Now, run again@ + +@example +# apt-get update@ +# apt-get upgrade@ +@end example + +to ensure that all your new distribution indices are downloaded, and +that your pinning is correct: the upgrade step should cause no changes +at all. + +@node Installing packages +@subsection Installing packages + +We begin by installing a few Debian packages from stable:@ + +@example +# apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \ + libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev \ + texlive libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev \ + libbz2-dev libexiv2-dev libflac-dev libgif-dev libglib2.0-dev \ + libgtk-3-dev libmagic-dev libjpeg8-dev libmpeg2-4-dev libmp4v2-dev \ + librpm-dev libsmf-dev libtidy-dev libtiff5-dev libvorbis-dev \ + libogg-dev zlib1g-dev g++ gettext libgsf-1-dev libunbound-dev \ + libqrencode-dev libgladeui-dev nasm texlive-latex-extra \ + libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev +@end example + +After that, we install a few more packages from unstable:@ + +@example +# apt-get install -t unstable nettle-dev libgstreamer1.0-dev \ + gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ + libgstreamer-plugins-base1.0-dev +@end example + +@node Installing dependencies from source +@subsection Installing dependencies from source + +Next, we need to install a few dependencies from source. +You might want to do this as a "normal" user and only run the +@code{make install} steps as root (hence the @code{sudo} in the +commands below). Also, you do this from any +directory. We begin by downloading all dependencies, then extracting the +sources, and finally compiling and installing the libraries. + +For these steps, follow the instructions given in the +installation from source instruction in this order: + +@itemize @bullet +@item @ref{generic source installation - libav} +@item @ref{generic source installation - libextractor} +@item @ref{generic source installation - libgpg-error} +@item @ref{generic source installation - libgcrypt} +@item @ref{generic source installation - gnutls} +@item @ref{generic source installation - libmicrohttpd} +@item @ref{generic source installation - libgnurl} +@end itemize + +@node Installing GNUnet from source +@subsection Installing GNUnet from source + + +For this, simply follow the generic installation instructions from +here. + +@node But wait there is more! +@subsection But wait there is more! + +So far, we installed all of the packages and dependencies required to +ensure that all of GNUnet would be built. +However, while for example the plugins to interact with the MySQL or +Postgres databases have been created, we did not actually install or +configure those databases. Thus, you will need to install +and configure those databases or stick with the default Sqlite database. +Sqlite is usually fine for most applications, but MySQL can offer better +performance and Postgres better resillience. + + +@node Installing GNUnet from Git on Ubuntu 14.4 +@section Installing GNUnet from Git on Ubuntu 14.4 + +@strong{Install the required build tools:} + +@example +$ sudo apt-get install git automake autopoint autoconf +@end example + +@strong{Install the required dependencies} + +@example +$ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ + libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ + libmicrohttpd-dev libgnutls28-dev +@end example + +@strong{Choose one or more database backends} + +@itemize @bullet + +@item SQLite3: + +@example +$ sudo apt-get install libsqlite3-dev +@end example + +@item MySQL: + +@example +$ sudo apt-get install libmysqlclient-dev +@end example + +@item PostgreSQL: + +@example +$ sudo apt-get install libpq-dev postgresql +@end example + +@end itemize + +@strong{Install the optional dependencies for gnunet-conversation:} + +@example +$ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev +@end example + +@strong{Install the libgrypt 1.6.1:} + +@itemize @bullet + +@item For Ubuntu 14.04: + +@example +$ sudo apt-get install libgcrypt20-dev +@end example + +@item For Ubuntu older 14.04: + +@example +$ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 +$ tar xf libgcrypt-1.6.1.tar.bz2 +$ cd libgcrypt-1.6.1 +$ ./configure +$ sudo make install +$ cd .. +@end example + +@end itemize + +@strong{Install libgnurl} + +@example +$ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2 +$ tar xf gnurl-7.35.0.tar.bz2 +$ cd gnurl-7.35.0 +$ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \ + --without-libmetalink --without-winidn --without-librtmp \ + --without-nghttp2 --without-nss --without-cyassl --without-polarssl \ + --without-ssl --without-winssl --without-darwinssl --disable-sspi \ + --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \ + --disable-telnet --disable-tftp --disable-pop3 --disable-imap \ + --disable-smtp --disable-gopher --disable-file --disable-ftp +$ sudo make install +$ cd .. +@end example + +@strong{Install GNUnet} + +@example +$ git clone https://gnunet.org/git/gnunet/ +$ cd gnunet/ +$ ./bootstrap +@end example + +If you want to: + +@itemize @bullet + +@item Install to a different directory: + +@example +--prefix=PREFIX +@end example + +@item +Have sudo permission, but do not want to compile as root: + +@example +--with-sudo +@end example + +@item +Want debug message enabled: + +@example +--enable-logging=verbose +@end example + +@end itemize + + +@example +$ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose] +$ make; sudo make install +@end example + +After installing it, you need to create an empty configuration file: + +@example +touch ~/.config/gnunet.conf +@end example + +And finally you can start GNUnet with + +@example +$ gnunet-arm -s +@end example + +@node Build instructions for Debian 8 +@section Build instructions for Debian 8 +@c FIXME: I -> we + +These are the installation instructions for Debian 8. They were tested +sing a fresh Debian 8 AMD64 installation without non-free software (no +contrib or non-free). During installation, I only selected "lxde" for the +desktop environment. +Note that the packages and the dependencies that we will install during +this chapter take about 1.5 GB of disk space. Combined with GNUnet and +space for objects during compilation, you should not even attempt this +unless you have about 2.5 GB free after the Debian installation. +Using these instructions to build a VM image is likely to require a +minimum of 4-5 GB for the VM (as you will likely also want a desktop +manager). + +GNUnet's security model assumes that your @code{/home} directory is +encrypted. +Thus, if possible, you should encrypt your entire disk, or at least just +your home partition (or per-user home directory). + +Naturally, the exact details of the starting state for your installation +should not matter much. +For example, if you selected any of those installation groups you might +simply already have some of the necessary packages installed. Thus, it is +suggested that you simply install the desktop environment of your choice +before beginning with the instructions. + + +@menu +* Update Debian:: +* Installing Debian Packages:: +* Installing Dependencies from Source2:: +* Installing GNUnet from Source2:: +* But wait (again) there is more!:: +@end menu + +@node Update Debian +@subsection Update Debian + +After any installation, you should begin by running + +@example +# apt-get update +# apt-get upgrade +@end example + +to ensure that all of your packages are up-to-date. Note that the "#" is +used to indicate that you need to type in this command as "root" (or +prefix with "sudo"), whereas "$" is used to indicate typing in a command +as a normal user. + +@node Installing Debian Packages +@subsection Installing Debian Packages + +We begin by installing a few Debian packages from stable: + +@example +# apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \ +libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \ +libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \ +libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \ +libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext \ +libgsf-1-dev libunbound-dev libqrencode-dev libgladeui-dev nasm \ +texlive-latex-extra libunique-3.0-dev gawk miniupnpc libfuse-dev \ +libbluetooth-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ +libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev \ +libgcrypt20-dev libmicrohttpd-dev +@end example + +@node Installing Dependencies from Source2 +@subsection Installing Dependencies from Source2 + +Yes, we said we start with a Debian 8 "stable" system, but because Debian +linked GnuTLS without support for DANE, we need to compile a few things, +in addition to GNUnet, still by hand. Yes, you can run GNUnet using the +respective Debian packages, but then you will not get DANE support. + +Next, we need to install a few dependencies from source. You might want +to do this as a "normal" user and only run the @code{make install} steps +as root (hence the @code{sudo} in the commands below). Also, you do this +from any directory. We begin by downloading all dependencies, then +extracting the sources, and finally compiling and installing the +libraries: + +@example +$ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz +$ tar xvf gnutls-3.3.12.tar.xz +$ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd .. +@end example + +For the installation and compilation of libgnurl/gnURL refer to +the generic installation section, +@xref{generic source installation - libgnurl}. + +@node Installing GNUnet from Source2 +@subsection Installing GNUnet from Source2 + +For this, simply follow the generic installation instructions from@ +here. + +@node But wait (again) there is more! +@subsection But wait (again) there is more! + +So far, we installed all of the packages and dependencies required to +ensure that all of GNUnet would be built. However, while for example the +plugins to interact with the MySQL or Postgres databases have been +created, we did not actually install or configure those databases. +Thus, you will need to install and configure those databases or stick +with the default Sqlite database. Sqlite is usually fine for most +applications, but MySQL can offer better performance and Postgres better +resillience. + +@node Outdated build instructions for previous revisions +@section Outdated build instructions for previous revisions + +This chapter contains a collection of outdated, older installation guides. +They are mostly intended to serve as a starting point for writing +up-to-date instructions and should not be expected to work for +GNUnet 0.10.x. +A set of older installation instructions can also be found in the +file @file{doc/outdated-and-old-installation-instructions.txt} in the +source tree of GNUnet. + +This file covers old instructions which no longer receive security +updates or any kind of support. + +@menu +* Installing GNUnet 0.10.1 on Ubuntu 14.04:: +* Building GLPK for MinGW:: +* GUI build instructions for Ubuntu 12.04 using Subversion:: +@c * Installation with gnunet-update:: +* Instructions for Microsoft Windows Platforms (Old):: +@end menu + + +@node Installing GNUnet 0.10.1 on Ubuntu 14.04 +@subsection Installing GNUnet 0.10.1 on Ubuntu 14.04 + +Install the required dependencies: + +@example +$ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ + libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ + libmicrohttpd-dev libgnutls28-dev +@end example + +Choose one or more database backends: + +@itemize @bullet + +@item SQLite3 + +@example + $ sudo apt-get install libsqlite3-dev@ +@end example + +@item MySQL + +@example +$ sudo apt-get install libmysqlclient-dev@ +@end example + +@item PostgreSQL + +@example + $ sudo apt-get install libpq-dev postgresql@ +@end example + +@end itemize + +Install the optional dependencies for gnunet-conversation: + +@example + $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev +@end example + +Install libgcrypt 1.6: + +@itemize @bullet + +@item For Ubuntu 14.04: + +@example +$ sudo apt-get install libgcrypt20-dev +@end example + +@item For Ubuntu older than 14.04: + +@example +wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 +$ tar xf libgcrypt-1.6.1.tar.bz2 +$ cd libgcrypt-1.6.1 +$ ./configure +$ sudo make install +$ cd .. +@end example +@end itemize + +Install libgnurl: + +@pxref{generic source installation - libgnurl}. + +Install GNUnet: + +@example +$ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz +$ tar xf gnunet-0.10.1.tar.gz +$ cd gnunet-0.10.1 +@end example + +If you want to: + +@itemize @bullet + +@item +Install to a different directory: + +@example +--prefix=PREFIX +@end example + +@item +Have sudo permission, but do not want to compile as root: + +@example +--with-sudo +@end example + +@item +Want debug message enabled: + +@example +--enable-logging=verbose +@end example + +@end itemize + +@example +$ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose] +$ make; sudo make install +@end example + +After installing it, you need to create an empty configuration file: + +@example +touch ~/.config/gnunet.conf +@end example + +And finally you can start GNUnet with + +@example +$ gnunet-arm -s +@end example + +@node Building GLPK for MinGW +@subsection Building GLPK for MinGW + +GNUnet now requires the GNU Linear Programming Kit (GLPK). +Since there's is no package you can install with @code{mingw-get} you +have to compile it from source: + +@itemize @bullet + +@item Download the latest version from +@uref{http://ftp.gnu.org/gnu/glpk/} + +@item Unzip the downloaded source tarball using your favourite +unzipper application In the MSYS shell + +@item change to the respective directory + +@item Configure glpk for "i686-pc-mingw32": + +@example +./configure '--build=i686-pc-mingw32' +@end example + +@item run + +@example +make install check +@end example + +@end itemize + +MinGW does not automatically detect the correct buildtype so you have to +specify it manually. + + +@node GUI build instructions for Ubuntu 12.04 using Subversion +@subsection GUI build instructions for Ubuntu 12.04 using Subversion + +After installing GNUnet you can continue installing the GNUnet GUI tools: + +First, install the required dependencies: + +@example +$ sudo apt-get install libgladeui-dev libqrencode-dev +@end example + +Please ensure that the GNUnet shared libraries can be found by the linker. +If you installed GNUnet libraries in a non standard path +(say GNUNET_PREFIX=/usr/local/lib/), you can + +@itemize @bullet + +@item set the environmental variable permanently to: + +@example +LD_LIBRARY_PATH=$GNUNET_PREFIX +@end example + +@item or add @code{$GNUNET_PREFIX} to @file{/etc/ld.so.conf} + +@end itemize + +Now you can checkout and compile the GNUnet GUI tools: + +@example +$ git clone https://gnunet.org/git/gnunet-gtk +$ cd gnunet-gtk +$ ./bootstrap +$ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/.. +$ make install +@end example + +@c @node Installation with gnunet-update +@c @subsection Installation with gnunet-update + +@c gnunet-update project is an effort to introduce updates to GNUnet +@c installations. An interesting to-be-implemented-feature of gnunet-update +@c is that these updates are propagated through GNUnet's peer-to-peer +@c network. More information about gnunet-update can be found at +@c @c FIXME: Use correct cgit URL +@c @uref{https://gnunet.org/git/gnunet-update.git/tree/plain/README}. + +@c While the project is still under development, we have implemented the +@c following features which we believe may be helpful for users and we +@c would like them to be tested: + +@c @itemize @bullet + +@c @item +@c Packaging GNUnet installation along with its run-time dependencies into +@c update packages + +@c @item +@c Installing update packages into compatible hosts + +@c @item +@c Updating an existing installation (which had been installed by +@c gnunet-update) to a newer one + +@c @end itemize + +@c The above said features of gnunet-update are currently available for +@c testing on GNU/Linux systems. + +@c The following is a guide to help you get started with gnunet-update. +@c It shows you how to install the testing binary packages of GNUnet +@c 0.9.1 we have at @uref{https://gnunet.org/install/}. + +@c gnunet-update needs the following dependencies: + +@c @itemize @bullet +@c @item +@c python @geq{} 2.6 + +@c @item +@c gnupg + +@c @item +@c python-gpgme +@c @end itemize + + +@c Checkout gnunet-update: + +@c @c FIXME: git! +@c @example +@c $ svn checkout -r24905 https://gnunet.org/svn/gnunet-update@ +@c @end example + +@c For security reasons, all packages released for gnunet-update from us are +@c signed with the key at @uref{https://gnunet.org/install/key.txt}. +@c You would need to import this key into your gpg key ring. +@c gnunet-update uses this key to verify the integrity of the packages it +@c installs: + +@c @example +@c $ gpg --recv-keys 7C613D78@ +@c @end example + +@c Download the packages relevant to your architecture (currently I have +@c access to GNU/Linux machines on x86_64 and i686, so only two for now, +@c hopefully more later) from https://gnunet.org/install/. + +@c To install the downloaded package into the directory /foo: + +@c @example +@c gnunet-update/bin/gnunet-update install downloaded/package /foo +@c @end example + +@c The installer reports the directories into which shared libraries and +@c dependencies have been installed. You may need to add the reported shared +@c library installation paths to LD_LIBRARY_PATH before you start running any +@c installed binaries. + +@c Please report bugs at https://gnunet.org/bugs/ under the project +@c 'gnunet-update'. + +@node Instructions for Microsoft Windows Platforms (Old) +@subsection Instructions for Microsoft Windows Platforms (Old) + +This document is a @b{DEPRECATED} installation guide for GNUnet on +Windows. +It will not work for recent GNUnet versions, but maybe it will be of +some use if problems arise. + +The Windows build uses a UNIX emulator for Windows, +@uref{http://www.mingw.org/, MinGW}, to build the executable modules. +These modules run natively on Windows and do not require additional +emulation software besides the usual dependencies. + +GNUnet development is mostly done under GNU/Linux and especially git +checkouts may not build out of the box. +We regret any inconvenience, and if you have problems, please report them. + +@menu +* Hardware and OS requirements:: +* Software installation:: +* Building libextractor and GNUnet:: +* Installer:: +* Source:: +@end menu + +@node Hardware and OS requirements +@subsubsection Hardware and OS requirements + +@itemize @bullet + +@item Pentium II or equivalent processor, @geq{} 350 MHz + +@item 128 MB RAM + +@item 600 MB free disk space + +@item Windows 2000 or Windows XP are recommended + +@end itemize + +@node Software installation +@subsubsection Software installation + +@itemize @bullet + +@item +@strong{Compression software}@ + +The software packages GNUnet depends on are usually compressed using UNIX +tools like @command{tar}, @command{gzip}, @command{xzip} and +@command{bzip2}. +If you do not already have an utility that is able to extract such +archives, get @uref{http://www.7-zip.org/, 7-Zip}. + +@item +@strong{UNIX environment}@ + +The MinGW project provides the compiler toolchain that is used to build +GNUnet. +Get the following packages from the +@uref{http://sourceforge.net/projects/mingw/files/, MinGW} project: + +@itemize @bullet + +@item GCC core +@item GCC g++ +@item MSYS +@item MSYS Developer Tool Kit (msysDTK) +@item MSYS Developer Tool Kit - msys-autoconf (bin) +@item MSYS Developer Tool Kit - msys-automake (bin) +@item MinGW Runtime +@item MinGW Utilities +@item Windows API +@item Binutils +@item make +@item pdcurses +@item GDB (snapshot) +@end itemize + +@itemize @bullet + + +@item Install MSYS (to c:\mingw, for example.)@ +Do @strong{not} use spaces in the pathname. +For example, avoid a location such as @file{c:\program files\mingw}. + +@item Install MinGW runtime, utilities and GCC to a subdirectory +(to @file{c:\mingw\mingw}, for example) + +@item Install the Development Kit to the MSYS directory +(@file{c:\mingw}) + +@item Create a batch file bash.bat in your MSYS directory with +the files: + +@example +bin\sh.exe --login +@end example + +This batch file opens a shell which is used to invoke the build +processes. +MinGW's standard shell (@command{msys.bat}) is not suitable +because it opens a separate console window. +On Vista, @command{bash.bat} needs to be run as Administrator. + +@item +Start @command{bash.sh} and rename +@file{c:\mingw\mingw\lib\libstdc++.la} to avoid problems: + +@example +mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken +@end example + +@item +Unpack the Windows API to the MinGW directory (@file{c:\mingw\mingw\}) and +remove the declaration of DATADIR from +(@file{c:\mingw\mingw\include\objidl.h} (lines 55-58) + +@item +Unpack autoconf, automake to the MSYS directory (@file{c:\mingw}) + +@item +Install all other packages to the MinGW directory (@file{c:\mingw\mingw\}) +@end itemize + + +@item @strong{GNU Libtool}@ +GNU Libtool is required to use shared libraries. +Get the prebuilt package from here and unpack it to the +MinGW directory (@file{c:\mingw}) + +@item @strong{Pthreads}@ +GNUnet uses the portable POSIX thread library for multi-threading: + +@itemize @bullet + +@item Save +@uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/libpthreadGC2.a, libpthreadGC2.a} +(x86) or +@uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/libpthreadGC2.a, libpthreadGC2.a} +(x64) as libpthread.a into the @file{lib} +directory (@file{c:\mingw\mingw\lib\libpthread.a}). + +@item Save +@uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/pthreadGC2.dll, pthreadGC2.dll} +(x86) or +@uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/pthreadGC2.dll, libpthreadGC2.a} +(x64) into the MinGW @file{bin} directory (@file{c:\mingw\mingw\bin}). + +@item Download all header files from +@uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/include/, include/} +to the @file{include} directory (@file{c:\mingw\mingw\include}). +@end itemize + + +@item @strong{GNU MP}@ +GNUnet uses the GNU Multiple Precision library for special cryptographic +operations. Get the GMP binary package from the +@uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and +unpack it to the MinGW directory (@file{c:\mingw\mingw}) + +@item @strong{GNU Gettext}@ +GNU gettext is used to provide national language support. +Get the prebuilt package from hereand unpack it to the MinGW +directory (@file{c:\mingw\mingw}) + +@item @strong{GNU iconv}@ +GNU Libiconv is used for character encoding conversion. +Get the prebuilt package from here and unpack it to the MinGW +directory (@file{c:\mingw\mingw}). + +@item @strong{SQLite}@ +GNUnet uses the SQLite database to store data. +Get the prebuilt binary from here and unpack it to your MinGW directory. + +@item @strong{MySQL}@ +As an alternative to SQLite, GNUnet also supports MySQL. + +@itemize @bullet + +@item Get the binary installer from the +@uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project} +(version 4.1), install it and follow the instructions in +@file{README.mysql}. + +@item Create a temporary build directory (@file{c:\mysql}) + +@item Copy the directories @file{include\} and @file{lib\} from the +MySQL directory to the new directory + +@item Get the patches from +@uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and +@uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the +latter is only required for MySQL + +@example +patch -p 0 +@end example + +@item Move @file{lib\opt\libmysql.dll} to @file{lib\libmysql.dll} + +@item Change to @file{lib\} and create an import library: + +@example +dlltool --input-def ../include/libmySQL.def \ +--dllname libmysql.dll \ +--output-lib libmysqlclient.a -k +@end example + +@item Copy include\* to include\mysql\ + +@item Pass @code{--with-mysql=/c/mysql} to +@command{./configure} and copy @file{libmysql.dll} +to your PATH or GNUnet's @file{bin} directory +@end itemize + + +@item @strong{GTK+}@ +@command{gnunet-gtk} and @command{libextractor} depend on GTK. +Get the the binary and developer packages of @command{atk}, +@command{glib}, @command{gtk}, @command{iconv}, +@command{gettext-runtime}, @command{pango} from +@uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack them +to the MinGW directory (@file{c:\mingw\mingw}). +@c FIXME: The URL below for pkg-config seems wrong. +Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and +@command{libpng} and unpack them to the MinGW directory +(@file{c:\mingw\mingw}). +Here is an all-in-one package for the +@uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies} +. Do not overwrite any existing files! + +@item @strong{Glade}@ +@command{gnunet-gtk} and @command{gnunet-setup} were created using +this interface builder + +@itemize @bullet + +@item Get the Glade and libglade (-bin and -devel) packages +(without GTK!) from +@uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack them to +the MinGW directory (@file{c:\mingw\mingw}). + +@item Get @command{libxml} from here and unpack it to the MinGW +directory (@file{c:\mingw\mingw}). +@end itemize + +@c FIXME: URLs +@item @strong{zLib}@ +@command{libextractor} requires @command{zLib} to decompress some file +formats. GNUnet uses it to (de)compress meta-data. +Get zLib from here (Signature) and unpack it to the MinGW directory +(@file{c:\mingw\mingw}). + +@item @strong{Bzip2}@ +@command{libextractor} also requires @command{Bzip2} to +decompress some file formats. +Get the Bzip2 (binary and developer package) from +@uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and +unpack it to the MinGW directory (@file{c:\mingw\mingw}). + +@item @strong{Libgcrypt}@ +@command{Libgcrypt} provides the cryptographic functions used by GNUnet. +Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here}, +compile and place it in the MinGW directory +(@file{c:\mingw\mingw}). Currently libgcrypt @geq{} 1.4.2 is required to +compile GNUnet. + +@item @strong{PlibC}@ +PlibC emulates Unix functions under Windows. Get PlibC from here and +unpack it to the MinGW directory (c:\mingw\mingw) + +@item @strong{OGG Vorbis}@ +@command{OGG Vorbis} is used to extract meta-data from @file{.ogg} files. +Get the packages +@uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg} +and +@uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis} +from the +@uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build} +and unpack them to the MinGW directory (c:\mingw\mingw). + +@item @strong{Exiv2}@ +(lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data. +Download +@uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2} +and unpack it to the MSYS directory (c:\mingw). +@end itemize + +@node Building libextractor and GNUnet +@subsubsection Building libextractor and GNUnet + +Before you compile @command{libextractor} or @command{GNUnet}, +be sure to set @code{PKG_CONFIG_PATH}: + +@example +export PKG_CONFIG_PATH=/mingw/lib/pkgconfig +@end example + +@noindent +@xref{GNUnet Installation Handbook}, for basic instructions on building +@command{libextractor} and @command{GNUnet}. +By default, all modules that are created in this way contain +debug information and are quite large. To compile release versions +(small and fast) set the variable @code{CFLAGS}: + +@example +export CFLAGS='-O2 -march=pentium -fomit-frame-pointer' +./configure --prefix=$HOME --with-extractor=$HOME +@end example + +@node Installer +@subsubsection Installer + +The GNUnet installer is made with +@uref{http://nsis.sourceforge.net/, NSIS}. The installer script is +located in @file{contrib\win} in the GNUnet source tree. + +@node Source +@subsubsection Source + +@c FIXME: URL +The sources of all dependencies are available here. + +@c @node Portable GNUnet +@c @section Portable GNUnet + +@c Quick instructions on how to use the most recent GNUnet on most GNU/Linux +@c distributions + +@c Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian +@c and CentOS 6, but it should work on almost any GNU/Linux distribution. +@c More in-detail information can be found in the handbook. + +@c Note 2017-10: Currently this section assumes the old SVN repo of GNUnet +@c which no longer exists. + +@c @menu +@c * Prerequisites:: +@c * Download & set up gnunet-update:: +@c * Install GNUnet:: +@c @end menu + +@c @node Prerequisites +@c @subsection Prerequisites + +@c Open a terminal and paste this line into it to install all required tools +@c needed: + +@c @example +@c sudo apt-get install python-gpgme subversion +@c @end example + +@c @node Download & set up gnunet-update +@c @subsection Download & set up gnunet-update + +@c The following command will download a working version of gnunet-update +@c with the subversion tool and import the public key which is needed for +@c authentication: + +@c @example +@c svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update +@c cd ~/gnunet-update +@c gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78 +@c @end example + +@c @node Install GNUnet +@c @subsection Install GNUnet + +@c Download and install GNUnet binaries which can be found here and set +@c library paths: + +@c @example +@c wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz +@c ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~ +@c echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment +@c echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \ +@c /etc/ld.so.conf.d/gnunet.conf > /dev/null +@c sudo ldconfig +@c @end example + +@c You may need to re-login once after executing these last commands + +@c That's it, GNUnet is installed in your home directory now. GNUnet can be +@c configured and afterwards started by executing: + +@c @example +@c gnunet-arm -s +@c @end example + +@node The graphical configuration interface +@section The graphical configuration interface + +If you also would like to use @command{gnunet-gtk} and +@command{gnunet-setup} (highly recommended for beginners), do: + +@example +wget -P /tmp \ +https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz +sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~ +sudo ldconfig +@end example + +Now you can run @command{gnunet-setup} for easy configuration of your +GNUnet peer. + +@menu +* Configuring your peer:: +* Configuring the Friend-to-Friend (F2F) mode:: +* Configuring the hostlist to bootstrap:: +* Configuration of the HOSTLIST proxy settings:: +* Configuring your peer to provide a hostlist :: +* Configuring the datastore:: +* Configuring the MySQL database:: +* Reasons for using MySQL:: +* Reasons for not using MySQL:: +* Setup Instructions:: +* Testing:: +* Performance Tuning:: +* Setup for running Testcases:: +* Configuring the Postgres database:: +* Reasons to use Postgres:: +* Reasons not to use Postgres:: +* Manual setup instructions:: +* Testing the setup manually:: +* Configuring the datacache:: +* Configuring the file-sharing service:: +* Configuring logging:: +* Configuring the transport service and plugins:: +* Configuring the wlan transport plugin:: +* Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: +* Blacklisting peers:: +* Configuration of the HTTP and HTTPS transport plugins:: +* Configuring the GNU Name System:: +* Configuring the GNUnet VPN:: +* Bandwidth Configuration:: +* Configuring NAT:: +* Peer configuration for distributions:: +@end menu + +@node Configuring your peer +@subsection Configuring your peer + +This chapter will describe the various configuration options in GNUnet. + +The easiest way to configure your peer is to use the +@command{gnunet-setup} tool. +@command{gnunet-setup} is part of the @command{gnunet-gtk} +application. You might have to install it separately. + +Many of the specific sections from this chapter actually are linked from +within @command{gnunet-setup} to help you while using the setup tool. + +While you can also configure your peer by editing the configuration +file by hand, this is not recommended for anyone except for developers +as it requires a more in-depth understanding of the configuration files +and internal dependencies of GNUnet. + +@node Configuring the Friend-to-Friend (F2F) mode +@subsection Configuring the Friend-to-Friend (F2F) mode + +GNUnet knows three basic modes of operation: +@itemize @bullet +@item In standard "peer-to-peer" mode, +your peer will connect to any peer. +@item In the pure "friend-to-friend" +mode, your peer will ONLY connect to peers from a list of friends +specified in the configuration. +@item Finally, in mixed mode, +GNUnet will only connect to arbitrary peers if it +has at least a specified number of connections to friends. +@end itemize + +When configuring any of the F2F ("friend-to-friend") modes, +you first need to create a file with the peer identities +of your friends. Ask your friends to run + +@example +$ gnunet-peerinfo -sq +@end example + +@noindent +The resulting output of this command needs to be added to your +@file{friends} file, which is simply a plain text file with one line +per friend with the output from the above command. + +You then specify the location of your @file{friends} file in the +@code{FRIENDS} option of the "topology" section. + +Once you have created the @file{friends} file, you can tell GNUnet to only +connect to your friends by setting the @code{FRIENDS-ONLY} option +(again in the "topology" section) to YES. + +If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a +minimum number of friends to have (before connecting to arbitrary peers) +under the "MINIMUM-FRIENDS" option. + +If you want to operate in normal P2P-only mode, simply set +@code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO. +This is the default. + +@node Configuring the hostlist to bootstrap +@subsection Configuring the hostlist to bootstrap + +After installing the software you need to get connected to the GNUnet +network. The configuration file included in your download is already +configured to connect you to the GNUnet network. +In this section the relevant configuration settings are explained. + +To get an initial connection to the GNUnet network and to get to know +peers already connected to the network you can use the so called +"bootstrap servers". +These servers can give you a list of peers connected to the network. +To use these bootstrap servers you have to configure the hostlist daemon +to activate bootstrapping. + +To activate bootstrapping, edit the @code{[hostlist]}-section in your +configuration file. You have to set the argument @command{-b} in the +options line: + +@example +[hostlist] +OPTIONS = -b +@end example + +Additionally you have to specify which server you want to use. +The default bootstrapping server is +"@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}". +[^] To set the server you have to edit the line "SERVERS" in the hostlist +section. To use the default server you should set the lines to + +@example +SERVERS = http://v10.gnunet.org/hostlist [^] +@end example + +@noindent +To use bootstrapping your configuration file should include these lines: + +@example +[hostlist] +OPTIONS = -b +SERVERS = http://v10.gnunet.org/hostlist [^] +@end example + +@noindent +Besides using bootstrap servers you can configure your GNUnet peer to +recieve hostlist advertisements. +Peers offering hostlists to other peers can send advertisement messages +to peers that connect to them. If you configure your peer to receive these +messages, your peer can download these lists and connect to the peers +included. These lists are persistent, which means that they are saved to +your hard disk regularly and are loaded during startup. + +To activate hostlist learning you have to add the @command{-e} +switch to the @code{OPTIONS} line in the hostlist section: + +@example +[hostlist] +OPTIONS = -b -e +@end example + +@noindent +Furthermore you can specify in which file the lists are saved. +To save the lists in the file @file{hostlists.file} just add the line: + +@example +HOSTLISTFILE = hostlists.file +@end example + +@noindent +Best practice is to activate both bootstrapping and hostlist learning. +So your configuration file should include these lines: + +@example +[hostlist] +OPTIONS = -b -e +HTTPPORT = 8080 +SERVERS = http://v10.gnunet.org/hostlist [^] +HOSTLISTFILE = $SERVICEHOME/hostlists.file +@end example + +@node Configuration of the HOSTLIST proxy settings +@subsection Configuration of the HOSTLIST proxy settings + +The hostlist client can be configured to use a proxy to connect to the +hostlist server. +This functionality can be configured in the configuration file directly +or using the @command{gnunet-setup} tool. + +The hostlist client supports the following proxy types at the moment: + +@itemize @bullet +@item HTTP and HTTP 1.0 only proxy +@item SOCKS 4/4a/5/5 with hostname +@end itemize + +In addition authentication at the proxy with username and password can be +configured. + +To configure proxy support for the hostlist client in the +@command{gnunet-setup} tool, select the "hostlist" tab and select +the appropriate proxy type. +The hostname or IP address (including port if required) has to be entered +in the "Proxy hostname" textbox. If required, enter username and password +in the "Proxy username" and "Proxy password" boxes. +Be aware that this information will be stored in the configuration in +plain text (TODO: Add explanation and generalize the part in Chapter 3.6 +about the encrypted home). + +To provide these options directly in the configuration, you can +enter the following settings in the @code{[hostlist]} section of +the configuration: + +@example +# Type of proxy server, +# Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME +# Default: HTTP +# PROXY_TYPE = HTTP + +# Hostname or IP of proxy server +# PROXY = +# User name for proxy server +# PROXY_USERNAME = +# User password for proxy server +# PROXY_PASSWORD = +@end example + +@node Configuring your peer to provide a hostlist +@subsection Configuring your peer to provide a hostlist + +If you operate a peer permanently connected to GNUnet you can configure +your peer to act as a hostlist server, providing other peers the list of +peers known to him. + +Your server can act as a bootstrap server and peers needing to obtain a +list of peers can contact it to download this list. +To download this hostlist the peer uses HTTP. +For this reason you have to build your peer with libgnurl (or libcurl) +and microhttpd support. +How you build your peer with these options can be found here: +@xref{Generic installation instructions}. + +To configure your peer to act as a bootstrap server you have to add the +@command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section +of your configuration file. +Besides that you have to specify a port number for the http server. +In conclusion you have to add the following lines: + +@example +[hostlist] +HTTPPORT = 12980 +OPTIONS = -p +@end example + +@noindent +If your peer acts as a bootstrap server other peers should know about +that. You can advertise the hostlist your are providing to other peers. +Peers connecting to your peer will get a message containing an +advertisement for your hostlist and the URL where it can be downloaded. +If this peer is in learning mode, it will test the hostlist and, in the +case it can obtain the list successfully, it will save it for +bootstrapping. + +To activate hostlist advertisement on your peer, you have to set the +following lines in your configuration file: + +@example +[hostlist] +EXTERNAL_DNS_NAME = example.org +HTTPPORT = 12981 +OPTIONS = -p -a +@end example + +@noindent +With this configuration your peer will a act as a bootstrap server and +advertise this hostlist to other peers connecting to it. +The URL used to download the list will be +@code{@uref{http://example.org:12981/, http://example.org:12981/}}. + +Please notice: + +@itemize @bullet +@item The hostlist is @b{not} human readable, so you should not try to +download it using your webbrowser. Just point your GNUnet peer to the +address! +@item Advertising without providing a hostlist does not make sense and +will not work. +@end itemize + +@node Configuring the datastore +@subsection Configuring the datastore + +The datastore is what GNUnet uses for long-term storage of file-sharing +data. Note that long-term does not mean 'forever' since content does have +an expiration date, and of course storage space is finite (and hence +sometimes content may have to be discarded). + +Use the @code{QUOTA} option to specify how many bytes of storage space +you are willing to dedicate to GNUnet. + +In addition to specifying the maximum space GNUnet is allowed to use for +the datastore, you need to specify which database GNUnet should use to do +so. Currently, you have the choice between sqLite, MySQL and Postgres. + +@node Configuring the MySQL database +@subsection Configuring the MySQL database + +This section describes how to setup the MySQL database for GNUnet. + +Note that the mysql plugin does NOT work with mysql before 4.1 since we +need prepared statements. +We are generally testing the code against MySQL 5.1 at this point. + +@node Reasons for using MySQL +@subsection Reasons for using MySQL + +@itemize @bullet + +@item On up-to-date hardware wher +mysql can be used comfortably, this module +will have better performance than the other database choices (according +to our tests). + +@item Its often possible to recover the mysql database from internal +inconsistencies. Some of the other databases do not support repair. +@end itemize + +@node Reasons for not using MySQL +@subsection Reasons for not using MySQL + +@itemize @bullet +@item Memory usage (likely not an issue if you have more than 1 GB) +@item Complex manual setup +@end itemize + +@node Setup Instructions +@subsection Setup Instructions + +@itemize @bullet + +@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for +@code{DATABASE} to @code{mysql}. + +@item Access mysql as root: + +@example +$ mysql -u root -p +@end example + +@noindent +and issue the following commands, replacing $USER with the username +that will be running @command{gnunet-arm} (so typically "gnunet"): + +@example +CREATE DATABASE gnunet; +GRANT select,insert,update,delete,create,alter,drop,create \ +temporary tables ON gnunet.* TO $USER@@localhost; +SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); +FLUSH PRIVILEGES; +@end example + +@item +In the $HOME directory of $USER, create a @file{.my.cnf} file with the +following lines + +@example +[client] +user=$USER +password=$the_password_you_like +@end example + +@end itemize + +Thats it. Note that @file{.my.cnf} file is a slight security risk unless +its on a safe partition. The @file{$HOME/.my.cnf} can of course be +a symbolic link. +Luckily $USER has only priviledges to mess up GNUnet's tables, +which should be pretty harmless. + +@node Testing +@subsection Testing + +You should briefly try if the database connection works. First, login +as $USER. Then use: + +@example +$ mysql -u $USER +mysql> use gnunet; +@end example + +@noindent +If you get the message + +@example +Database changed +@end example + +@noindent +it probably works. + +If you get + +@example +ERROR 2002: Can't connect to local MySQL server +through socket '/tmp/mysql.sock' (2) +@end example + +@noindent +it may be resolvable by + +@example +ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock +@end example + +@noindent +so there may be some additional trouble depending on your mysql setup. + +@node Performance Tuning +@subsection Performance Tuning + +For GNUnet, you probably want to set the option + +@example +innodb_flush_log_at_trx_commit = 0 +@end example + +@noindent +for a rather dramatic boost in MySQL performance. However, this reduces +the "safety" of your database as with this options you may loose +transactions during a power outage. +While this is totally harmless for GNUnet, the option applies to all +applications using MySQL. So you should set it if (and only if) GNUnet is +the only application on your system using MySQL. + +@node Setup for running Testcases +@subsection Setup for running Testcases + +If you want to run the testcases, you must create a second database +"gnunetcheck" with the same username and password. This database will +then be used for testing (@command{make check}). + +@node Configuring the Postgres database +@subsection Configuring the Postgres database + +This text describes how to setup the Postgres database for GNUnet. + +This Postgres plugin was developed for Postgres 8.3 but might work for +earlier versions as well. + +@node Reasons to use Postgres +@subsection Reasons to use Postgres + +@itemize @bullet +@item Easier to setup than MySQL +@item Real database +@end itemize + +@node Reasons not to use Postgres +@subsection Reasons not to use Postgres + +@itemize @bullet +@item Quite slow +@item Still some manual setup required +@end itemize + +@node Manual setup instructions +@subsection Manual setup instructions + +@itemize @bullet +@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for +@code{DATABASE} to @code{postgres}. +@item Access Postgres to create a user: + +@table @asis +@item with Postgres 8.x, use: + +@example +# su - postgres +$ createuser +@end example + +@noindent +and enter the name of the user running GNUnet for the role interactively. +Then, when prompted, do not set it to superuser, allow the creation of +databases, and do not allow the creation of new roles. + +@item with Postgres 9.x, use: + +@example +# su - postgres +$ createuser -d $GNUNET_USER +@end example + +@noindent +where $GNUNET_USER is the name of the user running GNUnet. + +@end table + + +@item +As that user (so typically as user "gnunet"), create a database (or two): + +@example +$ createdb gnunet +# this way you can run "make check" +$ createdb gnunetcheck +@end example + +@end itemize + +Now you should be able to start @code{gnunet-arm}. + +@node Testing the setup manually +@subsection Testing the setup manually + +You may want to try if the database connection works. First, again login +as the user who will run @command{gnunet-arm}. Then use: + +@example +$ psql gnunet # or gnunetcheck +gnunet=> \dt +@end example + +@noindent +If, after you have started @command{gnunet-arm} at least once, you get +a @code{gn090} table here, it probably works. + +@node Configuring the datacache +@subsection Configuring the datacache +@c %**end of header + +The datacache is what GNUnet uses for storing temporary data. This data is +expected to be wiped completely each time GNUnet is restarted (or the +system is rebooted). + +You need to specify how many bytes GNUnet is allowed to use for the +datacache using the @code{QUOTA} option in the section @code{[dhtcache]}. +Furthermore, you need to specify which database backend should be used to +store the data. Currently, you have the choice between +sqLite, MySQL and Postgres. + +@node Configuring the file-sharing service +@subsection Configuring the file-sharing service + +In order to use GNUnet for file-sharing, you first need to make sure +that the file-sharing service is loaded. +This is done by setting the @code{AUTOSTART} option in +section @code{[fs]} to "YES". Alternatively, you can run + +@example +$ gnunet-arm -i fs +@end example + +@noindent +to start the file-sharing service by hand. + +Except for configuring the database and the datacache the only important +option for file-sharing is content migration. + +Content migration allows your peer to cache content from other peers as +well as send out content stored on your system without explicit requests. +This content replication has positive and negative impacts on both system +performance and privacy. + +FIXME: discuss the trade-offs. Here is some older text about it... + +Setting this option to YES allows gnunetd to migrate data to the local +machine. Setting this option to YES is highly recommended for efficiency. +Its also the default. If you set this value to YES, GNUnet will store +content on your machine that you cannot decrypt. +While this may protect you from liability if the judge is sane, it may +not (IANAL). If you put illegal content on your machine yourself, setting +this option to YES will probably increase your chances to get away with it +since you can plausibly deny that you inserted the content. +Note that in either case, your anonymity would have to be broken first +(which may be possible depending on the size of the GNUnet network and the +strength of the adversary). + +@node Configuring logging +@subsection Configuring logging + +Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. +Using @code{-L}, a log level can be specified. With log level +@code{ERROR} only serious errors are logged. +The default log level is @code{WARNING} which causes anything of +concern to be logged. +Log level @code{INFO} can be used to log anything that might be +interesting information whereas +@code{DEBUG} can be used by developers to log debugging messages +(but you need to run @code{./configure} with +@code{--enable-logging=verbose} to get them compiled). +The @code{-l} option is used to specify the log file. + +Since most GNUnet services are managed by @code{gnunet-arm}, using the +@code{-l} or @code{-L} options directly is not possible. +Instead, they can be specified using the @code{OPTIONS} configuration +value in the respective section for the respective service. +In order to enable logging globally without editing the @code{OPTIONS} +values for each service, @command{gnunet-arm} supports a +@code{GLOBAL_POSTFIX} option. +The value specified here is given as an extra option to all services for +which the configuration does contain a service-specific @code{OPTIONS} +field. + +@code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which +is replaced by the name of the service that is being started. +Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences +starting with "$" anywhere in the string are expanded (according +to options in @code{PATHS}); this expansion otherwise is +only happening for filenames and then the "$" must be the +first character in the option. Both of these restrictions do +not apply to @code{GLOBAL_POSTFIX}. +Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX} +disables both of these features. + +In summary, in order to get all services to log at level +@code{INFO} to log-files called @code{SERVICENAME-logs}, the +following global prefix should be used: + +@example +GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO +@end example + +@node Configuring the transport service and plugins +@subsection Configuring the transport service and plugins + +The transport service in GNUnet is responsible to maintain basic +connectivity to other peers. +Besides initiating and keeping connections alive it is also responsible +for address validation. + +The GNUnet transport supports more than one transport protocol. +These protocols are configured together with the transport service. + +The configuration section for the transport service itself is quite +similar to all the other services + +@example +AUTOSTART = YES +@@UNIXONLY@@ PORT = 2091 +HOSTNAME = localhost +HOME = $SERVICEHOME +CONFIG = $DEFAULTCONFIG +BINARY = gnunet-service-transport +#PREFIX = valgrind +NEIGHBOUR_LIMIT = 50 +ACCEPT_FROM = 127.0.0.1; +ACCEPT_FROM6 = ::1; +PLUGINS = tcp udp +UNIXPATH = /tmp/gnunet-service-transport.sock +@end example + +Different are the settings for the plugins to load @code{PLUGINS}. +The first setting specifies which transport plugins to load. + +@itemize @bullet +@item transport-unix +A plugin for local only communication with UNIX domain sockets. Used for +testing and available on unix systems only. Just set the port + +@example +[transport-unix] +PORT = 22086 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@item transport-tcp +A plugin for communication with TCP. Set port to 0 for client mode with +outbound only connections + +@example +[transport-tcp] +# Use 0 to ONLY advertise as a peer behind NAT (no port binding) +PORT = 2086 +ADVERTISED_PORT = 2086 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +# Maximum number of open TCP connections allowed +MAX_CONNECTIONS = 128 +@end example + +@item transport-udp +A plugin for communication with UDP. Supports peer discovery using +broadcasts. + +@example +[transport-udp] +PORT = 2086 +BROADCAST = YES +BROADCAST_INTERVAL = 30 s +MAX_BPS = 1000000 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@item transport-http +HTTP and HTTPS support is split in two part: a client plugin initiating +outbound connections and a server part accepting connections from the +client. The client plugin just takes the maximum number of connections as +an argument. + +@example +[transport-http_client] +MAX_CONNECTIONS = 128 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@example +[transport-https_client] +MAX_CONNECTIONS = 128 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@noindent +The server has a port configured and the maximum nunber of connections. +The HTTPS part has two files with the certificate key and the certificate +file. + +The server plugin supports reverse proxies, so a external hostname can be +set using the @code{EXTERNAL_HOSTNAME} setting. +The webserver under this address should forward the request to the peer +and the configure port. + +@example +[transport-http_server] +EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet +PORT = 1080 +MAX_CONNECTIONS = 128 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@example +[transport-https_server] +PORT = 4433 +CRYPTO_INIT = NORMAL +KEY_FILE = https.key +CERT_FILE = https.cert +MAX_CONNECTIONS = 128 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@item transport-wlan + +The next section describes how to setup the WLAN plugin, +so here only the settings. Just specify the interface to use: + +@example +[transport-wlan] +# Name of the interface in monitor mode (typically monX) +INTERFACE = mon0 +# Real hardware, no testing +TESTMODE = 0 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example +@end itemize + +@node Configuring the wlan transport plugin +@subsection Configuring the wlan transport plugin + +The wlan transport plugin enables GNUnet to send and to receive data on a +wlan interface. +It has not to be connected to a wlan network as long as sender and +receiver are on the same channel. This enables you to get connection to +GNUnet where no internet access is possible, for example during +catastrophes or when censorship cuts you off from the internet. + + +@menu +* Requirements for the WLAN plugin:: +* Configuration:: +* Before starting GNUnet:: +* Limitations and known bugs:: +@end menu + + +@node Requirements for the WLAN plugin +@subsubsection Requirements for the WLAN plugin + +@itemize @bullet + +@item wlan network card with monitor support and packet injection +(see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) + +@item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with +2.6.35 and 2.6.38 + +@item Wlantools to create the a monitor interface, tested with airmon-ng +of the aircrack-ng package +@end itemize + +@node Configuration +@subsubsection Configuration + +There are the following options for the wlan plugin (they should be like +this in your default config file, you only need to adjust them if the +values are incorrect for your system) + +@example +# section for the wlan transport plugin +[transport-wlan] +# interface to use, more information in the +# "Before starting GNUnet" section of the handbook. +INTERFACE = mon0 +# testmode for developers: +# 0 use wlan interface, +#1 or 2 use loopback driver for tests 1 = server, 2 = client +TESTMODE = 0 +@end example + +@node Before starting GNUnet +@subsubsection Before starting GNUnet + +Before starting GNUnet, you have to make sure that your wlan interface is +in monitor mode. +One way to put the wlan interface into monitor mode (if your interface +name is wlan0) is by executing: + +@example +sudo airmon-ng start wlan0 +@end example + +@noindent +Here is an example what the result should look like: + +@example +Interface Chipset Driver +wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0] +(monitor mode enabled on mon0) +@end example + +@noindent +The monitor interface is mon0 is the one that you have to put into the +configuration file. + +@node Limitations and known bugs +@subsubsection Limitations and known bugs + +Wlan speed is at the maximum of 1 Mbit/s because support for choosing the +wlan speed with packet injection was removed in newer kernels. +Please pester the kernel developers about fixing this. + +The interface channel depends on the wlan network that the card is +connected to. If no connection has been made since the start of the +computer, it is usually the first channel of the card. +Peers will only find each other and communicate if they are on the same +channel. Channels must be set manually, i.e. using: + +@example +iwconfig wlan0 channel 1 +@end example + +@node Configuring HTTP(S) reverse proxy functionality using Apache or nginx +@subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx + +The HTTP plugin supports data transfer using reverse proxies. A reverse +proxy forwards the HTTP request he receives with a certain URL to another +webserver, here a GNUnet peer. + +So if you have a running Apache or nginx webserver you can configure it to +be a GNUnet reverse proxy. Especially if you have a well-known webiste +this improves censorship resistance since it looks as normal surfing +behaviour. + +To do so, you have to do two things: + +@itemize @bullet +@item Configure your webserver to forward the GNUnet HTTP traffic +@item Configure your GNUnet peer to announce the respective address +@end itemize + +As an example we want to use GNUnet peer running: + +@itemize @bullet + +@item HTTP server plugin on @code{gnunet.foo.org:1080} + +@item HTTPS server plugin on @code{gnunet.foo.org:4433} + +@item A apache or nginx webserver on +@uref{http://www.foo.org/, http://www.foo.org:80/} + +@item A apache or nginx webserver on https://www.foo.org:443/ +@end itemize + +And we want the webserver to accept GNUnet traffic under +@code{http://www.foo.org/bar/}. The required steps are described here: + +@menu +* Reverse Proxy - Configure your Apache2 HTTP webserver:: +* Reverse Proxy - Configure your Apache2 HTTPS webserver:: +* Reverse Proxy - Configure your nginx HTTPS webserver:: +* Reverse Proxy - Configure your nginx HTTP webserver:: +* Reverse Proxy - Configure your GNUnet peer:: +@end menu + +@node Reverse Proxy - Configure your Apache2 HTTP webserver +@subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver + +First of all you need mod_proxy installed. + +Edit your webserver configuration. Edit +@code{/etc/apache2/apache2.conf} or the site-specific configuration file. + +In the respective @code{server config},@code{virtual host} or +@code{directory} section add the following lines: + +@example +ProxyTimeout 300 +ProxyRequests Off +<Location /bar/ > +ProxyPass http://gnunet.foo.org:1080/ +ProxyPassReverse http://gnunet.foo.org:1080/ +</Location> +@end example + +@node Reverse Proxy - Configure your Apache2 HTTPS webserver +@subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver + +We assume that you already have an HTTPS server running, if not please +check how to configure a HTTPS host. An easy to use example is the +@file{apache2/sites-available/default-ssl} example configuration file. + +In the respective HTTPS @code{server config},@code{virtual host} or +@code{directory} section add the following lines: + +@example +SSLProxyEngine On +ProxyTimeout 300 +ProxyRequests Off +<Location /bar/ > +ProxyPass https://gnunet.foo.org:4433/ +ProxyPassReverse https://gnunet.foo.org:4433/ +</Location> +@end example + +@noindent +More information about the apache mod_proxy configuration can be found +here: @uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass} +. + +@node Reverse Proxy - Configure your nginx HTTPS webserver +@subsubsection Reverse Proxy - Configure your nginx HTTPS webserver + +Since nginx does not support chunked encoding, you first of all have to +install @code{chunkin}: @uref{http://wiki.nginx.org/HttpChunkinModule}. + +To enable chunkin add: + +@example +chunkin on; +error_page 411 = @@my_411_error; +location @@my_411_error @{ +chunkin_resume; +@} +@end example + +@noindent +Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or +the site-specific configuration file. + +In the @code{server} section add: + +@example +location /bar/ +@{ +proxy_pass http://gnunet.foo.org:1080/; +proxy_buffering off; +proxy_connect_timeout 5; # more than http_server +proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout +proxy_http_version 1.1; # 1.0 default +proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; +@} +@end example + +@node Reverse Proxy - Configure your nginx HTTP webserver +@subsubsection Reverse Proxy - Configure your nginx HTTP webserver + +Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or +the site-specific configuration file. + +In the @code{server} section add: + +@example +ssl_session_timeout 6m; +location /bar/ +@{ +proxy_pass https://gnunet.foo.org:4433/; +proxy_buffering off; +proxy_connect_timeout 5; # more than http_server +proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout +proxy_http_version 1.1; # 1.0 default +proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; +@} +@end example + +@node Reverse Proxy - Configure your GNUnet peer +@subsubsection Reverse Proxy - Configure your GNUnet peer + +To have your GNUnet peer announce the address, you have to specify the +@code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} +section: + +@example +[transport-http_server] +EXTERNAL_HOSTNAME = http://www.foo.org/bar/ +@end example + +@noindent +and/or @code{[transport-https_server]} section: + +@example +[transport-https_server] +EXTERNAL_HOSTNAME = https://www.foo.org/bar/ +@end example + +@noindent +Now restart your webserver and your peer... + +@node Blacklisting peers +@subsection Blacklisting peers + +Transport service supports to deny connecting to a specific peer of to a +specific peer with a specific transport plugin using te blacklisting +component of transport service. With@ blacklisting it is possible to deny +connections to specific peers of@ to use a specific plugin to a specific +peer. Peers can be blacklisted using@ the configuration or a blacklist +client can be asked. + +To blacklist peers using the configuration you have to add a section to +your configuration containing the peer id of the peer to blacklist and +the plugin@ if required. + +Examples: + +To blacklist connections to P565... on peer AG2P... using tcp add: + +@c FIXME: This is too long and produces errors in the pdf. +@example +[transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] +P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp +@end example + +To blacklist connections to P565... on peer AG2P... using all plugins add: + +@example +[transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] +P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = +@end example + +You can also add a blacklist client usign the blacklist API. On a +blacklist check, blacklisting first checks internally if the peer is +blacklisted and if not, it asks the blacklisting clients. Clients are +asked if it is OK to connect to a peer ID, the plugin is omitted. + +On blacklist check for (peer, plugin) +@itemize @bullet +@item Do we have a local blacklist entry for this peer and this plugin?@ +@item YES: disallow connection@ +@item Do we have a local blacklist entry for this peer and all plugins?@ +@item YES: disallow connection@ +@item Does one of the clients disallow?@ +@item YES: disallow connection +@end itemize + +@node Configuration of the HTTP and HTTPS transport plugins +@subsection Configuration of the HTTP and HTTPS transport plugins + +The client parts of the http and https transport plugins can be configured +to use a proxy to connect to the hostlist server. This functionality can +be configured in the configuration file directly or using the +gnunet-setup tool. + +Both the HTTP and HTTPS clients support the following proxy types at +the moment: + +@itemize @bullet +@item HTTP 1.1 proxy +@item SOCKS 4/4a/5/5 with hostname +@end itemize + +In addition authentication at the proxy with username and password can be +configured. + +To configure proxy support for the clients in the gnunet-setup tool, +select the "transport" tab and activate the respective plugin. Now you +can select the appropriate proxy type. The hostname or IP address +(including port if required) has to be entered in the "Proxy hostname" +textbox. If required, enter username and password in the "Proxy username" +and "Proxy password" boxes. Be aware that these information will be stored +in the configuration in plain text. + +To configure these options directly in the configuration, you can +configure the following settings in the @code{[transport-http_client]} +and @code{[transport-https_client]} section of the configuration: + +@example +# Type of proxy server, +# Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME +# Default: HTTP +# PROXY_TYPE = HTTP + +# Hostname or IP of proxy server +# PROXY = +# User name for proxy server +# PROXY_USERNAME = +# User password for proxy server +# PROXY_PASSWORD = +@end example + +@node Configuring the GNU Name System +@subsection Configuring the GNU Name System + +@menu +* Configuring system-wide DNS interception:: +* Configuring the GNS nsswitch plugin:: +* Configuring GNS on W32:: +* GNS Proxy Setup:: +* Setup of the GNS CA:: +* Testing the GNS setup:: +* Automatic Shortening in the GNU Name System:: +@end menu + + +@node Configuring system-wide DNS interception +@subsubsection Configuring system-wide DNS interception + +Before you install GNUnet, make sure you have a user and group 'gnunet' +as well as an empty group 'gnunetdns'. + +When using GNUnet with system-wide DNS interception, it is absolutely +necessary for all GNUnet service processes to be started by +@code{gnunet-service-arm} as user and group 'gnunet'. You also need to be +sure to run @code{make install} as root (or use the @code{sudo} option to +configure) to grant GNUnet sufficient privileges. + +With this setup, all that is required for enabling system-wide DNS +interception is for some GNUnet component (VPN or GNS) to request it. +The @code{gnunet-service-dns} will then start helper programs that will +make the necessary changes to your firewall (@code{iptables}) rules. + +Note that this will NOT work if your system sends out DNS traffic to a +link-local IPv6 address, as in this case GNUnet can intercept the traffic, +but not inject the responses from the link-local IPv6 address. Hence you +cannot use system-wide DNS interception in conjunction with link-local +IPv6-based DNS servers. If such a DNS server is used, it will bypass +GNUnet's DNS traffic interception. + +Using the GNU Name System (GNS) requires two different configuration +steps. +First of all, GNS needs to be integrated with the operating system. Most +of this section is about the operating system level integration. + +Additionally, each individual user who wants to use the system must also +initialize their GNS zones. This can be done by running (after starting +GNUnet) + +@example +$ gnunet-gns-import.sh +@end example + +@noindent +after the local GNUnet peer has been started. Note that the namestore (in +particular the namestore database backend) should not be reconfigured +afterwards (as records are not automatically migrated between backends). + +The remainder of this chapter will detail the various methods for +configuring the use of GNS with your operating system. + +At this point in time you have different options depending on your OS: + +@table @asis + +@item Use the gnunet-gns-proxy This approach works for all operating +systems and is likely the easiest. However, it enables GNS only for +browsers, not for other applications that might be using DNS, such as SSH. +Still, using the proxy is required for using HTTP with GNS and is thus +recommended for all users. To do this, you simply have to run the +@code{gnunet-gns-proxy-setup-ca} script as the user who will run the +browser (this will create a GNS certificate authority (CA) on your system +and import its key into your browser), then start @code{gnunet-gns-proxy} +and inform your browser to use the Socks5 proxy which +@code{gnunet-gns-proxy} makes available by default on port 7777. +@item Use a nsswitch plugin (recommended on GNU systems) +This approach has the advantage of offering fully personalized resolution +even on multi-user systems. A potential disadvantage is that some +applications might be able to bypass GNS. +@item Use a W32 resolver plugin (recommended on W32) +This is currently the only option on W32 systems. +@item Use system-wide DNS packet interception +This approach is recommended for the GNUnet VPN. It can be used to handle +GNS at the same time; however, if you only use this method, you will only +get one root zone per machine (not so great for multi-user systems). +@end table + +You can combine system-wide DNS packet interception with the nsswitch +plugin. +The setup of the system-wide DNS interception is described here. All of +the other GNS-specific configuration steps are described in the following +sections. + +@node Configuring the GNS nsswitch plugin +@subsubsection Configuring the GNS nsswitch plugin + +The Name Service Switch (NSS) is a facility in Unix-like operating systems +@footnote{More accurate: NSS is a functionality of the GNU C Library} +that provides a variety of sources for common configuration databases and +name resolution mechanisms. +A superuser (system administrator) usually configures the +operating system's name services using the file +@file{/etc/nsswitch.conf}. + +GNS provides a NSS plugin to integrate GNS name resolution with the +operating system's name resolution process. +To use the GNS NSS plugin you have to either + +@itemize @bullet +@item install GNUnet as root or +@item compile GNUnet with the @code{--with-sudo=yes} switch. +@end itemize + +Name resolution is controlled by the @emph{hosts} section in the NSS +configuration. By default this section first performs a lookup in the +@file{/etc/hosts} file and then in DNS. +The nsswitch file should contain a line similar to: + +@example +hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 +@end example + +@noindent +Here the GNS NSS plugin can be added to perform a GNS lookup before +performing a DNS lookup. +The GNS NSS plugin has to be added to the "hosts" section in +@file{/etc/nsswitch.conf} file before DNS related plugins: + +@example +... +hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4 +... +@end example + +@noindent +The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not +found in GNS it will not be queried in DNS. + +@node Configuring GNS on W32 +@subsubsection Configuring GNS on W32 + +This document is a guide to configuring GNU Name System on W32-compatible +platforms. + +After GNUnet is installed, run the w32nsp-install tool: + +@example +w32nsp-install.exe libw32nsp-0.dll +@end example + +@noindent +('0' is the library version of W32 NSP; it might increase in the future, +change the invocation accordingly). + +This will install GNS namespace provider into the system and allow other +applications to resolve names that end in '@strong{gnu}' +and '@strong{zkey}'. Note that namespace provider requires +gnunet-gns-helper-service-w32 to be running, as well as gns service +itself (and its usual dependencies). + +Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, +and this is where gnunet-gns-helper-service-w32 should be listening to +(and is configured to listen to by default). + +To uninstall the provider, run: + +@example +w32nsp-uninstall.exe +@end example + +@noindent +(uses provider GUID to uninstall it, does not need a dll name). + +Note that while MSDN claims that other applications will only be able to +use the new namespace provider after re-starting, in reality they might +stat to use it without that. Conversely, they might stop using the +provider after it's been uninstalled, even if they were not re-started. +W32 will not permit namespace provider library to be deleted or +overwritten while the provider is installed, and while there is at least +one process still using it (even after it was uninstalled). + +@node GNS Proxy Setup +@subsubsection GNS Proxy Setup + +When using the GNU Name System (GNS) to browse the WWW, there are several +issues that can be solved by adding the GNS Proxy to your setup: + +@itemize @bullet + +@item If the target website does not support GNS, it might assume that it +is operating under some name in the legacy DNS system (such as +example.com). It may then attempt to set cookies for that domain, and the +web server might expect a @code{Host: example.com} header in the request +from your browser. +However, your browser might be using @code{example.gnu} for the +@code{Host} header and might only accept (and send) cookies for +@code{example.gnu}. The GNS Proxy will perform the necessary translations +of the hostnames for cookies and HTTP headers (using the LEHO record for +the target domain as the desired substitute). + +@item If using HTTPS, the target site might include an SSL certificate +which is either only valid for the LEHO domain or might match a TLSA +record in GNS. However, your browser would expect a valid certificate for +@code{example.gnu}, not for some legacy domain name. The proxy will +validate the certificate (either against LEHO or TLSA) and then +on-the-fly produce a valid certificate for the exchange, signed by your +own CA. Assuming you installed the CA of your proxy in your browser's +certificate authority list, your browser will then trust the +HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy. + +@item Finally, the proxy will in the future indicate to the server that it +speaks GNS, which will enable server operators to deliver GNS-enabled web +sites to your browser (and continue to deliver legacy links to legacy +browsers) +@end itemize + +@node Setup of the GNS CA +@subsubsection Setup of the GNS CA + +First you need to create a CA certificate that the proxy can use. +To do so use the provided script gnunet-gns-proxy-ca: + +@example +$ gnunet-gns-proxy-setup-ca +@end example + +@noindent +This will create a personal certification authority for you and add this +authority to the firefox and chrome database. The proxy will use the this +CA certificate to generate @code{*.gnu} client certificates on the fly. + +Note that the proxy uses libcurl. Make sure your version of libcurl uses +GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled +against OpenSSL. + +You can check the configuration your libcurl was build with by +running: + +@example +curl --version +@end example + +the output will look like this (without the linebreaks): + +@example +gnurl --version +curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \ +GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4 +Release-Date: 2017-10-08 +Protocols: http https +Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \ +TLS-SRP UnixSockets HTTPS-proxy +@end example + +@node Testing the GNS setup +@subsubsection Testing the GNS setup + +Now for testing purposes we can create some records in our zone to test +the SSL functionality of the proxy: + +@example +$ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67 +$ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org" +@end example + +@noindent +At this point we can start the proxy. Simply execute + +@example +$ gnunet-gns-proxy +@end example + +@noindent +Configure your browser to use this SOCKSv5 proxy on port 7777 and visit +this link. +If you use @command{Firefox} (or one of its deriviates/forks such as +Icecat) you also have to go to @code{about:config} and set the key +@code{network.proxy.socks_remote_dns} to @code{true}. + +When you visit @code{https://homepage.gnu/}, you should get to the +@code{https://gnunet.org/} frontpage and the browser (with the correctly +configured proxy) should give you a valid SSL certificate for +@code{homepage.gnu} and no warnings. It should look like this: + +@c FIXME: Image does not exist, create it or save it from Drupal? +@c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} + +@node Automatic Shortening in the GNU Name System +@subsubsection Automatic Shortening in the GNU Name System + +This page describes a possible option for 'automatic name shortening', +which you can choose to enable with the GNU Name System. + +When GNS encounters a name for the first time, it can use the 'NICK' +record of the originating zone to automatically generate a name for the +zone. If automatic shortening is enabled, those auto-generated names will +be placed (as private records) into your personal 'shorten' zone (to +prevent confusion with manually selected names). +Then, in the future, if the same name is encountered again, GNS will +display the shortened name instead (the first time, the long name will +still be used as shortening typically happens asynchronously as looking up +the 'NICK' record takes some time). Using this feature can be a convenient +way to avoid very long @code{.gnu} names; however, note that names from +the shorten-zone are assigned on a first-come-first-serve basis and should +not be trusted. Furthermore, if you enable this feature, you will no +longer see the full delegation chain for zones once shortening has been +applied. + +@node Configuring the GNUnet VPN +@subsection Configuring the GNUnet VPN + +@menu +* IPv4 address for interface:: +* IPv6 address for interface:: +* Configuring the GNUnet VPN DNS:: +* Configuring the GNUnet VPN Exit Service:: +* IP Address of external DNS resolver:: +* IPv4 address for Exit interface:: +* IPv6 address for Exit interface:: +@end menu + +Before configuring the GNUnet VPN, please make sure that system-wide DNS +interception is configured properly as described in the section on the +GNUnet DNS setup. @pxref{Configuring the GNU Name System}, +if you haven't done so already. + +The default options for the GNUnet VPN are usually sufficient to use +GNUnet as a Layer 2 for your Internet connection. +However, what you always have to specify is which IP protocol you want +to tunnel: IPv4, IPv6 or both. +Furthermore, if you tunnel both, you most likely should also tunnel +all of your DNS requests. +You theoretically can tunnel "only" your DNS traffic, but that usually +makes little sense. + +The other options as shown on the gnunet-setup tool are: + +@node IPv4 address for interface +@subsubsection IPv4 address for interface + +This is the IPv4 address the VPN interface will get. You should pick an +'private' IPv4 network that is not yet in use for you system. For example, +if you use @code{10.0.0.1/255.255.0.0} already, you might use +@code{10.1.0.1/255.255.0.0}. +If you use @code{10.0.0.1/255.0.0.0} already, then you might use +@code{192.168.0.1/255.255.0.0}. +If your system is not in a private IP-network, using any of the above will +work fine. +You should try to make the mask of the address big enough +(@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more +mappings of remote IP Addresses into this range. +However, even a @code{255.255.255.0} mask will suffice for most users. + +@node IPv6 address for interface +@subsubsection IPv6 address for interface + +The IPv6 address the VPN interface will get. Here you can specify any +non-link-local address (the address should not begin with @code{fe80:}). +A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are +currently not using would be a good choice. + +@node Configuring the GNUnet VPN DNS +@subsubsection Configuring the GNUnet VPN DNS + +To resolve names for remote nodes, activate the DNS exit option. + +@node Configuring the GNUnet VPN Exit Service +@subsubsection Configuring the GNUnet VPN Exit Service + +If you want to allow other users to share your Internet connection (yes, +this may be dangerous, just as running a Tor exit node) or want to +provide access to services on your host (this should be less dangerous, +as long as those services are secure), you have to enable the GNUnet exit +daemon. + +You then get to specify which exit functions you want to provide. By +enabling the exit daemon, you will always automatically provide exit +functions for manually configured local services (this component of the +system is under +development and not documented further at this time). As for those +services you explicitly specify the target IP address and port, there is +no significant security risk in doing so. + +Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. +Being a DNS exit is usually pretty harmless. However, enabling IPv4 or +IPv6-exit without further precautions may enable adversaries to access +your local network, send spam, attack other systems from your Internet +connection and to other mischief that will appear to come from your +machine. This may or may not get you into legal trouble. +If you want to allow IPv4 or IPv6-exit functionality, you should strongly +consider adding additional firewall rules manually to protect your local +network and to restrict outgoing TCP traffic (i.e. by not allowing access +to port 25). While we plan to improve exit-filtering in the future, +you're currently on your own here. +Essentially, be prepared for any kind of IP-traffic to exit the respective +TUN interface (and GNUnet will enable IP-forwarding and NAT for the +interface automatically). + +Additional configuration options of the exit as shown by the gnunet-setup +tool are: + +@node IP Address of external DNS resolver +@subsubsection IP Address of external DNS resolver + +If DNS traffic is to exit your machine, it will be send to this DNS +resolver. You can specify an IPv4 or IPv6 address. + +@node IPv4 address for Exit interface +@subsubsection IPv4 address for Exit interface + +This is the IPv4 address the Interface will get. Make the mask of the +address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more +mappings of IP addresses into this range. As for the VPN interface, any +unused, private IPv4 address range will do. + +@node IPv6 address for Exit interface +@subsubsection IPv6 address for Exit interface + +The public IPv6 address the interface will get. If your kernel is not a +very recent kernel and you are willing to manually enable IPv6-NAT, the +IPv6 address you specify here must be a globally routed IPv6 address of +your host. + +Suppose your host has the address @code{2001:4ca0::1234/64}, then +using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, +then change at least one bit in the range before the bitmask, in the +example above we changed bit 111 from 0 to 1). + +You may also have to configure your router to route traffic for the entire +subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this +should be automatic with IPv6, but obviously anything can be +disabled). + +@node Bandwidth Configuration +@subsection Bandwidth Configuration + +You can specify how many bandwidth GNUnet is allowed to use to receive +and send data. This is important for users with limited bandwidth or +traffic volume. + +@node Configuring NAT +@subsection Configuring NAT + +Most hosts today do not have a normal global IP address but instead are +behind a router performing Network Address Translation (NAT) which assigns +each host in the local network a private IP address. +As a result, these machines cannot trivially receive inbound connections +from the Internet. GNUnet supports NAT traversal to enable these machines +to receive incoming connections from other peers despite their +limitations. + +In an ideal world, you can press the "Attempt automatic configuration" +button in gnunet-setup to automatically configure your peer correctly. +Alternatively, your distribution might have already triggered this +automatic configuration during the installation process. +However, automatic configuration can fail to determine the optimal +settings, resulting in your peer either not receiving as many connections +as possible, or in the worst case it not connecting to the network at all. + +To manually configure the peer, you need to know a few things about your +network setup. First, determine if you are behind a NAT in the first +place. +This is always the case if your IP address starts with "10.*" or +"192.168.*". Next, if you have control over your NAT router, you may +choose to manually configure it to allow GNUnet traffic to your host. +If you have configured your NAT to forward traffic on ports 2086 (and +possibly 1080) to your host, you can check the "NAT ports have been opened +manually" option, which corresponds to the "PUNCHED_NAT" option in the +configuration file. If you did not punch your NAT box, it may still be +configured to support UPnP, which allows GNUnet to automatically +configure it. In that case, you need to install the "upnpc" command, +enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal +via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the +configuration file). + +Some NAT boxes can be traversed using the autonomous NAT traversal method. +This requires certain GNUnet components to be installed with "SUID" +prividledges on your system (so if you're installing on a system you do +not have administrative rights to, this will not work). +If you installed as 'root', you can enable autonomous NAT traversal by +checking the "Enable NAT traversal using ICMP method". +The ICMP method requires a way to determine your NAT's external (global) +IP address. This can be done using either UPnP, DynDNS, or by manual +configuration. If you have a DynDNS name or know your external IP address, +you should enter that name under "External (public) IPv4 address" (which +corresponds to the "EXTERNAL_ADDRESS" option in the configuration file). +If you leave the option empty, GNUnet will try to determine your external +IP address automatically (which may fail, in which case autonomous +NAT traversal will then not work). + +Finally, if you yourself are not behind NAT but want to be able to +connect to NATed peers using autonomous NAT traversal, you need to check +the "Enable connecting to NATed peers using ICMP method" box. + + +@node Peer configuration for distributions +@subsection Peer configuration for distributions + +The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be +manually set to "/var/lib/gnunet/data/" as the default +"~/.local/share/gnunet/" is probably not that appropriate in this case. +Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to +"/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a +distribution decide to override system defaults, all of these changes +should be done in a custom @file{/etc/gnunet.conf} and not in the files +in the @file{config.d/} directory. + +Given the proposed access permissions, the "gnunet-setup" tool must be +run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it +modifies the system configuration). As always, gnunet-setup should be run +after the GNUnet peer was stopped using "gnunet-arm -e". Distributions +might want to include a wrapper for gnunet-setup that allows the +desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account +and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in +sequence. + +@node How to start and stop a GNUnet peer +@section How to start and stop a GNUnet peer + +This section describes how to start a GNUnet peer. It assumes that you +have already compiled and installed GNUnet and its' dependencies. +Before you start a GNUnet peer, you may want to create a configuration +file using gnunet-setup (but you do not have to). +Sane defaults should exist in your +@file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice +you could simply start without any configuration. If you want to +configure your peer later, you need to stop it before invoking the +@code{gnunet-setup} tool to customize further and to test your +configuration (@code{gnunet-setup} has build-in test functions). + +The most important option you might have to still set by hand is in +[PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where +GNUnet should store its data. +It defaults to @code{$HOME/}, which again should work for most users. +Make sure that the directory specified as GNUNET_HOME is writable to +the user that you will use to run GNUnet (note that you can run frontends +using other users, GNUNET_HOME must only be accessible to the user used to +run the background processes). + +You will also need to make one central decision: should all of GNUnet be +run under your normal UID, or do you want distinguish between system-wide +(user-independent) GNUnet services and personal GNUnet services. The +multi-user setup is slightly more complicated, but also more secure and +generally recommended. + +@menu +* The Single-User Setup:: +* The Multi-User Setup:: +* Killing GNUnet services:: +* Access Control for GNUnet:: +@end menu + +@node The Single-User Setup +@subsection The Single-User Setup + +For the single-user setup, you do not need to do anything special and can +just start the GNUnet background processes using @code{gnunet-arm}. +By default, GNUnet looks in @file{~/.config/gnunet.conf} for a +configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@ +@code{$XDG_CONFIG_HOME} is defined). If your configuration lives +elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet +commands. + +Assuming the configuration file is called @file{~/.config/gnunet.conf}, +you start your peer using the @code{gnunet-arm} command (say as user +@code{gnunet}) using: + +@example +gnunet-arm -c ~/.config/gnunet.conf -s +@end example + +@noindent +The "-s" option here is for "start". The command should return almost +instantly. If you want to stop GNUnet, you can use: + +@example +gnunet-arm -c ~/.config/gnunet.conf -e +@end example + +@noindent +The "-e" option here is for "end". + +Note that this will only start the basic peer, no actual applications +will be available. +If you want to start the file-sharing service, use (after starting +GNUnet): + +@example +gnunet-arm -c ~/.config/gnunet.conf -i fs +@end example + +@noindent +The "-i fs" option here is for "initialize" the "fs" (file-sharing) +application. You can also selectively kill only file-sharing support using + +@example +gnunet-arm -c ~/.config/gnunet.conf -k fs +@end example + +@noindent +Assuming that you want certain services (like file-sharing) to be always +automatically started whenever you start GNUnet, you can activate them by +setting "FORCESTART=YES" in the respective section of the configuration +file (for example, "[fs]"). Then GNUnet with file-sharing support would +be started whenever you@ enter: + +@example +gnunet-arm -c ~/.config/gnunet.conf -s +@end example + +@noindent +Alternatively, you can combine the two options: + +@example +gnunet-arm -c ~/.config/gnunet.conf -s -i fs +@end example + +@noindent +Using @code{gnunet-arm} is also the preferred method for initializing +GNUnet from @code{init}. + +Finally, you should edit your @code{crontab} (using the @code{crontab} +command) and insert a line@ + +@example +@@reboot gnunet-arm -c ~/.config/gnunet.conf -s +@end example + +to automatically start your peer whenever your system boots. + +@node The Multi-User Setup +@subsection The Multi-User Setup + +This requires you to create a user @code{gnunet} and an additional group +@code{gnunetdns}, prior to running @code{make install} during +installation. +Then, you create a configuration file @file{/etc/gnunet.conf} which should +contain the lines:@ + +@example +[arm] +SYSTEM_ONLY = YES +USER_ONLY = NO +@end example + +@noindent +Then, perform the same steps to run GNUnet as in the per-user +configuration, except as user @code{gnunet} (including the +@code{crontab} installation). +You may also want to run @code{gnunet-setup} to configure your peer +(databases, etc.). +Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you +run @code{gnunet-setup} as user @code{gnunet}, you might need to change +permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can +write to the file (during setup). + +Afterwards, you need to perform another setup step for each normal user +account from which you want to access GNUnet. First, grant the normal user +(@code{$USER}) permission to the group gnunet: + +@example +# adduser $USER gnunet +@end example + +@noindent +Then, create a configuration file in @file{~/.config/gnunet.conf} for the +$USER with the lines: + +@example +[arm] +SYSTEM_ONLY = NO +USER_ONLY = YES +@end example + +@noindent +This will ensure that @code{gnunet-arm} when started by the normal user +will only run services that are per-user, and otherwise rely on the +system-wide services. +Note that the normal user may run gnunet-setup, but the +configuration would be ineffective as the system-wide services will use +@file{/etc/gnunet.conf} and ignore options set by individual users. + +Again, each user should then start the peer using +@file{gnunet-arm -s} --- and strongly consider adding logic to start +the peer automatically to their crontab. + +Afterwards, you should see two (or more, if you have more than one USER) +@code{gnunet-service-arm} processes running in your system. + +@node Killing GNUnet services +@subsection Killing GNUnet services + +It is not necessary to stop GNUnet services explicitly when shutting +down your computer. + +It should be noted that manually killing "most" of the +@code{gnunet-service} processes is generally not a successful method for +stopping a peer (since @code{gnunet-service-arm} will instantly restart +them). The best way to explicitly stop a peer is using +@code{gnunet-arm -e}; note that the per-user services may need to be +terminated before the system-wide services will terminate normally. + +@node Access Control for GNUnet +@subsection Access Control for GNUnet + +This chapter documents how we plan to make access control work within the +GNUnet system for a typical peer. It should be read as a best-practice +installation guide for advanced users and builders of binary +distributions. The recommendations in this guide apply to POSIX-systems +with full support for UNIX domain sockets only. + +Note that this is an advanced topic. The discussion presumes a very good +understanding of users, groups and file permissions. Normal users on +hosts with just a single user can just install GNUnet under their own +account (and possibly allow the installer to use SUDO to grant additional +permissions for special GNUnet tools that need additional rights). +The discussion below largely applies to installations where multiple users +share a system and to installations where the best possible security is +paramount. + +A typical GNUnet system consists of components that fall into four +categories: + +@table @asis + +@item User interfaces +User interfaces are not security sensitive and are supposed to be run and +used by normal system users. +The GTK GUIs and most command-line programs fall into this category. +Some command-line tools (like gnunet-transport) should be excluded as they +offer low-level access that normal users should not need. +@item System services and support tools +System services should always run and offer services that can then be +accessed by the normal users. +System services do not require special permissions, but as they are not +specific to a particular user, they probably should not run as a +particular user. Also, there should typically only be one GNUnet peer per +host. System services include the gnunet-service and gnunet-daemon +programs; support tools include command-line programs such as gnunet-arm. +@item Priviledged helpers +Some GNUnet components require root rights to open raw sockets or perform +other special operations. These gnunet-helper binaries are typically +installed SUID and run from services or daemons. +@item Critical services +Some GNUnet services (such as the DNS service) can manipulate the service +in deep and possibly highly security sensitive ways. For example, the DNS +service can be used to intercept and alter any DNS query originating from +the local machine. Access to the APIs of these critical services and their +priviledged helpers must be tightly controlled. +@end table + +@c FIXME: The titles of these chapters are too long in the index. + +@menu +* Recommendation - Disable access to services via TCP:: +* Recommendation - Run most services as system user "gnunet":: +* Recommendation - Control access to services using group "gnunet":: +* Recommendation - Limit access to certain SUID binaries by group "gnunet":: +* Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns":: +* Differences between "make install" and these recommendations:: +@end menu + +@node Recommendation - Disable access to services via TCP +@subsubsection Recommendation - Disable access to services via TCP + +GNUnet services allow two types of access: via TCP socket or via UNIX +domain socket. +If the service is available via TCP, access control can only be +implemented by restricting connections to a particular range of IP +addresses. +This is acceptable for non-critical services that are supposed to be +available to all users on the local system or local network. +However, as TCP is generally less efficient and it is rarely the case +that a single GNUnet peer is supposed to serve an entire local network, +the default configuration should disable TCP access to all GNUnet +services on systems with support for UNIX domain sockets. +As of GNUnet 0.9.2, configuration files with TCP access disabled should be +generated by default. Users can re-enable TCP access to particular +services simply by specifying a non-zero port number in the section of +the respective service. + + +@node Recommendation - Run most services as system user "gnunet" +@subsubsection Recommendation - Run most services as system user "gnunet" + +GNUnet's main services should be run as a separate user "gnunet" in a +special group "gnunet". +The user "gnunet" should start the peer using "gnunet-arm -s" during +system startup. The home directory for this user should be +@file{/var/lib/gnunet} and the configuration file should be +@file{/etc/gnunet.conf}. +Only the @code{gnunet} user should have the right to access +@file{/var/lib/gnunet} (@emph{mode: 700}). + +@node Recommendation - Control access to services using group "gnunet" +@subsubsection Recommendation - Control access to services using group "gnunet" + +Users that should be allowed to use the GNUnet peer should be added to the +group "gnunet". Using GNUnet's access control mechanism for UNIX domain +sockets, those services that are considered useful to ordinary users +should be made available by setting "UNIX_MATCH_GID=YES" for those +services. +Again, as shipped, GNUnet provides reasonable defaults. +Permissions to access the transport and core subsystems might additionally +be granted without necessarily causing security concerns. +Some services, such as DNS, must NOT be made accessible to the "gnunet" +group (and should thus only be accessible to the "gnunet" user and +services running with this UID). + +@node Recommendation - Limit access to certain SUID binaries by group "gnunet" +@subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" + +Most of GNUnet's SUID binaries should be safe even if executed by normal +users. However, it is possible to reduce the risk a little bit more by +making these binaries owned by the group "gnunet" and restricting their +execution to user of the group "gnunet" as well (4750). + +@node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" +@subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" + +A special group "gnunetdns" should be created for controlling access to +the "gnunet-helper-dns". +The binary should then be owned by root and be in group "gnunetdns" and +be installed SUID and only be group-executable (2750). +@b{Note that the group "gnunetdns" should have no users in it at all, +ever.} +The "gnunet-service-dns" program should be executed by user "gnunet" (via +gnunet-service-arm) with the binary owned by the user "root" and the group +"gnunetdns" and be SGID (2700). This way, @strong{only} +"gnunet-service-dns" can change its group to "gnunetdns" and execute the +helper, and the helper can then run as root (as per SUID). +Access to the API offered by "gnunet-service-dns" is in turn restricted +to the user "gnunet" (not the group!), which means that only +"benign" services can manipulate DNS queries using "gnunet-service-dns". + +@node Differences between "make install" and these recommendations +@subsubsection Differences between "make install" and these recommendations + +The current build system does not set all permissions automatically based +on the recommendations above. In particular, it does not use the group +"gnunet" at all (so setting gnunet-helpers other than the +gnunet-helper-dns to be owned by group "gnunet" must be done manually). +Furthermore, 'make install' will silently fail to set the DNS binaries to +be owned by group "gnunetdns" unless that group already exists (!). +An alternative name for the "gnunetdns" group can be specified using the +@code{--with-gnunetdns=GRPNAME} configure option. + |