documentation: user + developer changes

Signed-off-by: Nils Gillmann <ng0@n0.is>

3 files changed, 2310 insertions, 11 deletions

diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi
index 6a895ed117..16039c8d3e 100644
--- a/doc/documentation/chapters/developer.texi
+++ b/doc/documentation/chapters/developer.texi
@@ -11,7 +11,7 @@ For developers, GNUnet is:
 @itemize @bullet
 @item developed by a community that believes in the GNU philosophy
 @item Free Software (Free as in Freedom), licensed under the
-GNU General Public License@footnote{@uref{https://www.gnu.org/licenses/licenses.html#GPL, https://www.gnu.org/licenses/licenses.html#GPL}}
+GNU Affero General Public License@footnote{@uref{https://www.gnu.org/licenses/licenses.html#AGPL, https://www.gnu.org/licenses/licenses.html#AGPL}}
 @item A set of standards, including coding conventions and
 architectural rules
 @item A set of layered protocols, both specifying the communication
@@ -40,6 +40,7 @@ new chapters, sections or insightful comments.
 
 @menu
 * Developer Introduction::
+* Internal Dependencies::
 * Code overview::
 * System Architecture::
 * Subsystem stability::
@@ -47,6 +48,7 @@ new chapters, sections or insightful comments.
 * Build-system::
 * Developing extensions for GNUnet using the gnunet-ext template::
 * Writing testcases::
+* Building GNUnet and its dependencies::
 * TESTING library::
 * Performance regression analysis with Gauger::
 * TESTBED Subsystem::
@@ -251,6 +253,77 @@ those that have a public website) which build on top of the GNUnet
 framework.
 
 @c ***********************************************************************
+@node Internal dependencies
+@section 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
+
+@c ***********************************************************************
 @node Code overview
 @section Code overview
 
@@ -1089,6 +1162,314 @@ typically necessary to run @code{make install} before running any
 testcases. Thus the canonical command @code{make check install} has to be
 changed to @code{make install check} for GNUnet.
 
+@c ***********************************************************************
+@cindex Building GNUnet
+@node Building GNUnet and its dependencies
+@section Building GNUnet and its dependencies
+
+In the following section we will outline how to build GNUnet and
+some of its dependencies. We will assume a fair amount of knowledge
+for building applications under UNIX-like systems. Furthermore we
+assume that the build environment is sane and that you are aware of
+any implications actions in this process could have.
+Instructions here can be seen as notes for developers (an extension to
+the 'HACKING' section in README) as well as package mantainers.
+@b{Users should rely on the available binary packages.}
+We will use Debian as an example Operating System environment. Substitute
+accordingly with your own Ooperating System environment.
+
+For the full list of depenendencies, consult the appropriate, up-to-date
+section in the @file{README} file.
+
+First, we need to build or install (depending on your OS) the following
+packages. If you build them from source, build them in this exact order:
+
+@exmaple
+libgpgerror, libgcrypt, libnettle, libunbound, GnuTLS (with libunbound
+support)
+@end example
+
+After we have build and installed those packages, we continue with
+packages closer to GNUnet in this step: libgnurl (our libcurl fork),
+GNU libmicrohttpd, and GNU libextractor. Again, if your package manager
+provides one of these packages, use the packages provided from it
+unless you have good reasons (package version too old, conflicts, etc).
+We advise against compiling widely used packages such as GnuTLS
+yourself if your OS provides a variant already unless you take care
+of maintenance of the packages then.
+
+In the optimistic case, this command will give you all the dependencies:
+
+@example
+sudo apt-get install libgnurl libmicrohttpd libextractor
+@end example
+
+From experience we know that at the very least libgnurl is not
+available in some environments. You could substitute libgnurl
+with libcurl, but we recommend to install libgnurl, as it gives
+you a predefined libcurl with the small set GNUnet requires. In
+the past namespaces of libcurl and libgnurl were shared, which
+caused problems when you wanted to integrate both of them in one
+Operating System. This has been resolved, and they can be installed
+side by side now.
+
+@cindex libgnurl
+@cindex compiling libgnurl
+GNUnet and some of its function depend on a limited subset of cURL/libcurl.
+Rather than trying to enforce a certain configuration on the world, we
+opted to maintain a microfork of it that ensures we can link against the
+right set of features. We called this specialized set of libcurl
+``libgnurl''. It is fully ABI compatible with libcurl and currently used
+by GNUnet and some of its dependencies.
+
+We download libgnurl and its digital signature from the GNU fileserver,
+assuming @env{TMPDIR} exists@footnote{It might be @file{/tmp}, @env{TMPDIR}, @env{TMP} or any other location. For consistency we assume @env{TMPDIR} points to @file{/tmp} for the remainder of this section.}
+
+@example
+cd \$TMPDIR
+wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z
+wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z.sig
+@end example
+
+Next, verify the digital signature of the file:
+
+@example
+gpg --verify gnurl-7.60.0.tar.Z.sig
+@end example
+
+If gpg fails, you might try with @command{gpg2} on your OS. If the error
+states that ``the key can not be found'' or it is unknown, you have to
+retrieve the key (A88C8ADD129828D7EAC02E52E22F9BBFEE348588) from a
+keyserver first:
+
+@example
+gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588
+@end example
+
+and rerun the verification command.
+
+libgnurl will require the following packages to be present at runtime:
+gnutls (with DANE support / libunbound), libidn, zlib and at compile time:
+libtool, groff, perl, pkg-config, and python 2.7.
+
+Once you have verified that all the required packages are present on your
+system, we can proceed to compile libgnurl:
+
+@example
+tar -xvf gnurl-7.60.0.tar.Z
+cd gnurl-7.60.0
+sh configure --disable-ntlm-wb
+make
+make -C tests test
+sudo make install
+@end example
+
+After you've compiled and installed libgnurl, we can proceed to building
+GNUnet.
+
+
+
+
+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
+sudo adduser --system --home /var/lib/gnunet --group \
+--disabled-password gnunet
+sudo addgroup --system gnunetdns
+@end example
+
+@noindent
+On other Unixes and GNU systems, this should have the same effect:
+
+@example
+sudo useradd --system --groups gnunet --home-dir /var/lib/gnunet
+sudo 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).
+
+@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 @command{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
+(replace alice with your username):
+
+@example
+sudo adduser alice 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.
+
+
+@c **********************************************************************
 @cindex TESTING library
 @node TESTING library
 @section TESTING library
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi
index e5ebf53715..48fcc04c33 100644
--- a/doc/documentation/chapters/user.texi
+++ b/doc/documentation/chapters/user.texi
@@ -27,6 +27,8 @@ Comments and extensions of this documentation are always welcome.
 * File-sharing::
 * The GNU Name System::
 * Using the Virtual Public Network::
+* The graphical configuration interface::
+* How to start and stop a GNUnet peer::
 @end menu
 
 @node Checking the Installation
@@ -2006,3 +2008,1927 @@ service offered by that peer, you can create an IP tunnel to
 that peer by specifying the peer's identity, service name and
 protocol (--tcp or --udp) and you will again receive an IP address
 that will terminate at the respective peer's service.
+
+
+
+@c NOTE: Inserted from Installation Handbook in original ``order'':
+@c FIXME: Move this to User Handbook.
+@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:
+
+@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).