+++ /dev/null
-@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 <dependency>
-@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
-<Location /bar/ >
-ProxyPass http://gnunet.foo.org:1080/
-ProxyPassReverse http://gnunet.foo.org:1080/
-</Location>
-@end example
-
-@node Reverse Proxy - Configure your Apache2 HTTPS webserver
-@subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver
-
-We assume that you already have an HTTPS server running, if not please
-check how to configure a HTTPS host. An 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
-<Location /bar/ >
-ProxyPass https://gnunet.foo.org:4433/
-ProxyPassReverse https://gnunet.foo.org:4433/
-</Location>
-@end example
-
-@noindent
-More information about the apache mod_proxy configuration can be found
-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.
projects / oweals / gnunet.git / commitdiff