From a4f268904b7e0a29136376a4d5e95d0cf8faedc3 Mon Sep 17 00:00:00 2001 From: Nils Gillmann Date: Wed, 6 Jun 2018 12:18:30 +0000 Subject: documentation: Remove installation Signed-off-by: Nils Gillmann --- doc/documentation/Makefile.am | 1 - doc/documentation/chapters/installation.texi | 4149 -------------------------- doc/documentation/gnunet.texi | 20 +- 3 files changed, 2 insertions(+), 4168 deletions(-) delete mode 100644 doc/documentation/chapters/installation.texi diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am index 0781b2fbb..12f40f147 100644 --- a/doc/documentation/Makefile.am +++ b/doc/documentation/Makefile.am @@ -113,7 +113,6 @@ info_TEXINFOS = \ gnunet_TEXINFOS = \ chapters/developer.texi \ chapters/preface.texi \ - chapters/installation.texi \ chapters/philosophy.texi \ chapters/user.texi \ chapters/vocabulary.texi \ diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi deleted file mode 100644 index 665f980be..000000000 --- a/doc/documentation/chapters/installation.texi +++ /dev/null @@ -1,4149 +0,0 @@ -@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 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:: -* Build instructions for macOS:: -@c * Build instructions for OpenBSD 6.2:: -* 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-conversation-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}) -@item libpbc @geq{} 0.5.14, optional for Attribute-Based Encryption and Identity Provider functionality -@item libgabe (https://github.com/schanzen/libgabe), optional for Attribute-Based Encryption and Identity Provider functionality -@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) certificate authority. This is done by running: - -@example -$ 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 -@end example - -@noindent -If you want a GnuTLS with DANE functionality (recommended for GNUnet), -you have to compile it against libunbound. Assuming that libunbound -is installed on your system: - -@example -$ ./configure --enable-libdane -@end example - -@noindent -Note that the build system of GnuTLS should pick up libunbound without -the explicit mention of @code{--enable-libdane}. -If you don't want libdane support you should pass @code{--disable-libdane} -instead. - -@example -$ ./configure -$ make ; sudo make install ; cd .. -@end example - -@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 installation of libgnurl version 7.57.0 from source. - -@example -$ wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.57.0.tar.xz -$ wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.57.0.tar.xz.sig -$ gpg --verify gnurl-7.57.0.tar.xz.sig -@end example - -@noindent -If that command fails because you do not have the required public key, -then run this command to import it: - -@example -$ gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588 -@end example - -@noindent -and rerun the gpg --verify command. - -@example -$ tar xvf gnurl-7.57.0.tar.xz -$ cd gnurl-7.57.0 -$ ./configure --disable-ntlm-wb -$ make ; sudo make install; cd .. -@end example - -You have now build and installed libgnurl from source. - -@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 Build instructions for macOS -@section Build instructions for macOS -@c FIXME: I -> we - -These are the installation guidelines for macOS. -They were tested on macOS High Sierra. - -@menu -* Installing dependencies:: -* Compile from Source:: -@end menu - -@node Installing dependencies -@subsection Installing dependencies - -First, install XCode in the newest version. -See https://developer.apple.com/xcode/. - -Install Homebrew (https://brew.sh) and then install the dependencies listed above. -If a dependency does not exists in brew, you need to compile it from source. - -@example -# brew install -@end example - -@node Compile from Source -@subsection Compile from Source - -Before you start building GNUnet, you need to setup your environment. -This means that you have to make sure the proper tools are used in the build process. -For example, after installing texinfo you need to make sure the new texinfo is actually used: - -@example -# echo 'export PATH="/usr/local/opt/texinfo/bin:$PATH"' >> ~/.bash_profile -@end example - -Note: brew tells you the appropriate command when executing - -@example -# brew info texinfo -@end example - -This may also be necessary for the gettext package. - -Before you start compiling, you need to make sure gcc is used and not the clang compile of your macOS system. -On my system, gcc was actually ``gcc-7'' and gcc pointed to the clang compiler. - -@example -# export CC=gcc-7 -@end example - -After this the standard compile instructions apply. - -@c @node Build instructions for OpenBSD 6.2 -@c @section Build instructions for OpenBSD 6.2 - -@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-fs-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 - -ProxyPass http://gnunet.foo.org:1080/ -ProxyPassReverse http://gnunet.foo.org:1080/ - -@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 uncomplicated to use example -is the example configuration file for Apache2/HTTPD provided in -@file{apache2/sites-available/default-ssl}. - -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 - -ProxyPass https://gnunet.foo.org:4433/ -ProxyPassReverse https://gnunet.foo.org:4433/ - -@end example - -@noindent -More information about the apache mod_proxy configuration can be found -in the Apache documentation@footnote{@uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass}} - -@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 the @code{chunkin} module@footnote{@uref{http://wiki.nginx.org/HttpChunkinModule, 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:: -@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. - -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-identity -C test -$ gnunet-namestore -a -e "1 d" -n "homepage" \ - -t A -V 131.159.74.67 -z test -$ gnunet-namestore -a -e "1 d" -n "homepage" \ - -t LEHO -V "gnunet.org" -z test -@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.test/}, 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 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. diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi index 22ee8206a..13c3aa9c8 100644 --- a/doc/documentation/gnunet.texi +++ b/doc/documentation/gnunet.texi @@ -113,22 +113,6 @@ Philosophy * Backup of Identities and Egos:: * Revocation:: -GNUnet Installation Handbook - -* 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:: - Using GNUnet * Checking the Installation:: @@ -140,8 +124,6 @@ Using GNUnet * The GNU Name System:: * Using the Virtual Public Network:: -@c Configuration Handbook - GNUnet Contributors Handbook * Contributing to GNUnet:: @@ -152,6 +134,7 @@ GNUnet Contributors Handbook GNUnet Developer Handbook * Developer Introduction:: +* Internal Dependencies:: * Code overview:: * System Architecture:: * Subsystem stability:: @@ -159,6 +142,7 @@ GNUnet Developer Handbook * Build-system:: * Developing extensions for GNUnet using the gnunet-ext template:: * Writing testcases:: +* Building GNUNet and its dependencies:: * TESTING library:: * Performance regression analysis with Gauger:: * TESTBED Subsystem:: -- cgit v1.2.3